Core Concepts
Design Paradigm: Agentic Engineering
King AI is built on the Agentic Engineering paradigm: with a large language model as the primary reasoning engine, source code stops being the system and becomes an ephemeral instrument the model generates and discards inside a reasoning loop. Delivery shifts from intent → software → result to intent → agent → result — a human states goals and constraints, agents plan, execute, validate, and deliver an outcome, and the human audits that outcome. This framing follows Cao, The End of Software Engineering (arXiv:2606.05608).
In that model an agent system is the tuple A = (M, T, M, Π), and King AI maps onto it directly:
| Concept | In King AI |
|---|---|
| M — reasoning engine | Local Claude Code / Codex CLI as the big model, with a small model for inbox triage |
| T — executable tools | The king-ai runtime CLI (reply, task, card, doc, recall…), the host SDK, and remote-diagnostics commands |
| M — memory | Per-agent durable memory (memory/MEMORY.md) plus cross-session episodic recall |
| Π — planning | Inbox triage, task routing, auto-delegation, and a coordinator agent decomposing intent into assigned work |
The human role is reframed as intent architect, coordinator, and outcome auditor rather than code author: you state what you want, shape how the team coordinates, and approve results at the decision gates the Collaboration Layer enforces.
Runtime Boundary
King AI has two sides:
- The remote runtime server owns pairing, browser-facing state, wake events, message queues, cards, tasks, decisions, and status snapshots.
- The local computer daemon owns local execution. It calls installed Claude Code or Codex CLIs, writes local runtime state, and runs agent work inside allowed local workspaces.
This keeps model credentials and engine sessions local while still giving the GUI a shared collaboration ledger.
Agent Runner
Each remote agent maps to a local runner. A runner polls or streams wake events, reads unread messages and assigned work, asks a small model to triage whether action is needed, and invokes the big model when the turn should be handled.
The runner also owns runtime accounting such as token refresh and stable wake-event de-duplication, so model autonomy applies to collaboration decisions while the system keeps message delivery idempotent. Ordinary agent room chatter is not treated as another peer's runtime inbox item unless it is directed, mentioned, or marked as a steer/decision/blocker signal, which keeps simple roll-calls and closure summaries from spawning redundant reasoning turns. Broad team roll-calls may still be delegated for one concise response, but they do not require a reviewer and the coordinator wake is not pinned to another agent's task contract. When a routed task is just a direct acknowledgement, confirmation, or roll-call reply, the runner prompt tells the agent to use the already fetched context, post one brief reply, and close the assigned task instead of spending another turn rediscovering the same state. Local engine failures such as authentication, quota, or rate-limit problems are sent back to the GUI as runtime notices instead of staying only in daemon logs.
Per-agent homes live under the King AI home so sessions, skills, state files, and workspaces stay isolated by agent.
Episodic Memory
Beyond each agent's private memory/MEMORY.md, the runtime keeps a cross-session episodic memory. Every human and agent message is mirrored into an FTS5 full-text index inside the SQLite-backed runtime, separate from the live conversation buffer. Because the index is additive it survives conversation clears, so the team accumulates searchable experience over time.
Agents query it with king-ai recall <query> [--limit n] [--conversation <id>], which runs a ranked full-text search and returns matching snippets with their conversation and author. Use it to retrieve prior decisions, earlier answers, or context from past sessions instead of re-deriving them. This realizes the M (memory) component of the agent model as durable, searchable experience rather than only the current context window.
Skill Self-Evolution
Agents can turn a procedure that worked into a reusable skill for future sessions with king-ai skill save <name> --file notes/skill.md (plus skill list, show, and remove). Learned skills are stored outside the ephemeral agent home, so they survive restarts and resets, and the daemon reinstalls them into .claude/skills and .codex/skills on every start — a closed learning loop where the team's procedural knowledge compounds over time. Saves are validated (slugged name, size and count caps) and kept per-agent. This realizes the paradigm's notion of self-improving skills as durable, reusable modules rather than throwaway context.
Operators can also provide shared skills with KING_AI_SHARED_SKILLS. These are curated external skill folders installed into every agent home before the engine starts. Shared skills solve a different problem from learned skills: they give the team a controlled baseline, such as an internal playbook or the AI Builder Club codebase-harness and loop-engineer skills, while learned skills capture procedures discovered by a specific agent during real work. Startup snapshots record which shared skill files were active for a run.
Collaboration Layer
King AI models work as a small team. Role templates are a small, domain-neutral vocabulary for how an agent participates in a workflow — its coordination behavior plus the capabilities and permissions that come with it. The built-in templates are planner, builder, reviewer, tester, ops, researcher, doc-writer, and summarizer. Workflows use them to route work by capability, request reviews, create handoffs, and ask for human decisions.
A template is not an agent. A concrete roster maps agents onto templates and does not have to staff every template. The default GUI software-development workflow has one Dev agent using the builder template: Dev handles requests directly, records substantive work in the task ledger, verifies the result, and closes the task without a built-in planner or reviewer handoff. The generic planner, reviewer, handoff, and decision capabilities remain available to the shared workflow engine and CLI scenarios. Domain agents work the same way: the IELTS coach is also a single-agent workflow that reuses the generic builder template, while its subject expertise lives in its free-text role rather than a new template. This keeps the template set generic and reusable across domains — what an agent knows belongs to its role and its workflow template, not to the coordination vocabulary.
In the IELTS Study workflow, an unambiguous single-conversation turn uses the selected local engine's native JSON Schema output. The engine returns one object with learner-visible text in replyMarkdown and annotations in wordCards; the runner validates those configured fields, posts the reply through the existing runtime ledger, closes a pinned task, and avoids posting again if the model already recorded a reply action. Before storage, the runner serializes wordCards back into the existing hidden WordCards: block, so historical messages and the GUI parser keep the same wire format. A turn spanning multiple conversations keeps the previous text-output path because the runner cannot safely guess a reply target.
The sentences data splits each visible English sentence into clauses: simple sentences still get one clause, while compound, complex, and compound-complex sentences include every finite main, coordinate, subordinate, or relative clause. Each clause gets its own short, word-for-word continuous core, and phrases mark only useful short chunks from the same clause. Every English word is clickable: cards should supply structured Chinese meanings, the Chinese part of speech (partOfSpeech), IPA phonetics, syllable splits, and a short Chinese root/affix breakdown (roots) for every distinct visible English word token. JSON Schema guarantees the reply's structural shape; semantic matching remains best-effort. The GUI applies whatever sentence/clause highlights and word cards it can match, falls back to generated cards for omitted words, and strips the hidden JSON before the learner sees the reply.
The model still owns strategy and content. The system owns identity, ownership, idempotency, task state transitions, and durable audit records.
GUI Cards
The GUI presents work as cards: tasks, files, handoffs, reviews, decisions, initiatives, plans, and run history. Agents can create and update cards through runtime commands, and humans can use the same GUI to steer or approve work.
Local State
New installs use ~/.king-ai as the local home. Pairing tokens, per-agent homes, sessions, triage state, heartbeat files, and host event logs are stored there unless KING_AI_CONFIG_DIR overrides the path.