architecture
This page sketches the crate graph and the data flow through a turn. For exhaustive detail, the code is the source of truth.
crate graph
kage-core (leaf)
kage-acp-wire (leaf, serde-only wire types)
kage-jsonrpc (depends on core)
kage-provider kage-session kage-tools (depend on core)
kage-mcp (core + jsonrpc + tools)
kage-acp (core + jsonrpc + provider + acp-wire)
kage-client (core + acp-wire)
kage-plugin (core + provider + tools)
kage-kura (core + plugin + tools)
kage-loop (core + provider + tools)
kage-remote (core + tungstenite)
kage-tui (core + plugin)
kage-cli (binary) (depends on everything it uses)
kage-desktop (binary) (client + core; never links the engine)Layering is strict: depend only downward. The kage-cli binary is the only crate that wires the whole graph together; kage-desktop talks to it over ACP instead.
what each crate owns
| Crate | Responsibility |
|---|---|
kage-core | Message types, content blocks, errors, the cancel tree, the engine protocol (events, commands, the agent tree and the MCP catalog types), the resource block format, agent definitions, the keymap, option and highlight registries |
kage-jsonrpc | Shared bidirectional JSON-RPC peer over stdio, with an optional cancel notice per connection |
kage-provider | LLM provider clients, registry, the bundled model catalog and the cache a running kage or kage models refresh writes |
kage-tools | Tool trait, built-in tools, tool registry |
kage-session | Append-only JSONL writer, replay, fork, search, the media blob store |
kage-loop | The agent loop, compaction, hooks |
kage-mcp | MCP client (tools, resources, prompts, the OAuth protocol, prompt expansion) and MCP server (kage's built-in tools over stdio) |
kage-acp | ACP agent (editors drive kage) and ACP client (kage drives another agent as a provider) |
kage-acp-wire | The ACP wire schema: serde-only, wasm-clean types (protocol version 1) shared by the agent, the serve host and the browser client |
kage-client | The sans-IO client side of ACP: frames in mirrored into a renderable state, commands out as frames, over any transport |
kage-plugin | Lua runtime, sandbox, host API surface, embedded stdlib and defaults, init.lua loading, package discovery and manifests |
kage-kura | The plugin registry client: the cached index, verified installs into the plugins directory, kura.lock |
kage-remote | The ACP WebSocket transport: request-head parsing and token authorization, the bearer token file, and the frame-to-line pipe that turns one accepted TCP stream into the reader and writer pair the agent serving loop consumes |
kage-tui | The interactive TUI, modal input, block renderer |
kage-cli | The binary, CLI flags, the session engine, frontend wiring |
kage-desktop | The desktop client, which runs the kage rpc shipped beside it, and its wasm build, the browser client kage serve hands out |
the engine
Every frontend drives the same engine. kage rpc for editors and -p print mode reach it directly through two channels:
- Events out. Each event is an envelope addressed to the session that produced it, with a per-session sequence number:
{"session":"01J...","seq":42,"type":"text_delta",...}. Durable events describe state a client keeps (a message was appended, a run ended, the model changed). Live events are deltas and progress a client may drop (streamed text, tool output tails).kage -p --jsonprints these envelopes one per line. - Commands in. Prompt, cancel, answer a permission request, switch model or thinking level, compact, run a shell command, restart an MCP server, and the session operations (new, resume, fork, clone, delete, export).
A dispatcher thread owns the sessions and never blocks on a run. Each run executes the agent loop on its own thread and hands the session back when it ends. Permission questions travel over the same channels: the engine publishes permission_requested and waits for the client's answer. The ACP projection turns the stream into ACP traffic, which is what the TUI and the editors speak (see the ACP projection).
agents
An agent is an engine session with a parent link. The agent tool never touches sessions itself. It sends a spawn request to the dispatcher and waits on its reply channel and its cancel flag.
parent runner thread dispatcher agent runner thread
loop -> agent tool
spawn request ----------> check the parent, definition, depth
open the agent session
publish agent_spawned
start its run, or queue it ---> kage-loop run()
wait on the reply ... (own seq, file,
cancel flag)
run finished <-----------------
send the result, start the
next queued agent
<----------- tool result
loop appends the result and continuesThe dispatcher still never blocks, and the wait graph stays a DAG: a parent's tool thread waits on a reply that the dispatcher sends when the agent's run ends, never the reverse. The link lives on the engine's session, with the parent, the depth and the reply channel. The first run that finishes takes the channel, so later runs a user starts in the agent never answer the parent twice. The running limit counts agent runs in flight, except agents that wait on their own agents, and queued agents start in spawn order.
An agent session is built from its parent's live state: the definition's model and thinking level over the parent's, the parent's tools filtered by the definition, a clone of the parent's permission gate (its rules, mode and session approvals are shared), and no plugin runtime or MCP manager of its own. Its runs forward no plugin events and use the plain run hooks. The agent tool is registered per run, never stored in the session's tools, so plugin reloads and MCP refreshes cannot drop or duplicate it. It is registered while the session's depth is below agent_max_depth.
Swarms. The swarm tool fans one call out to one child per item and fans the results back in. It expands the prompt template per item, pre-assigns each child's session id, and hands every child a clone of one reply channel, so the tool receives exactly one result per child and renders one aggregate. Spawns go through the ordinary queue, so agent_max_running throttles them, and each child's session marker records the batch id, index and item it came from. A call blocks on the tool thread until every child settles or the swarm_timeout_ms deadline cancels the stragglers; cancelling the parent cancels the whole fleet through the cancel tree. The loop refuses a swarm call that shares its message with any other call, so a batch of children never races an unrelated tool. The same call can also re-prompt earlier children: a resume map of child session id to prompt is verified against the session markers first, then attached. A hosted child gets its reply channel re-armed and the prompt queued; a child no longer hosted is reopened from its session file with its history, model and definition intact. Every agent that records is dropped once its result is delivered and it goes quiet, so idle agents hold no context in memory. Swarm mode (/swarm) injects a workflow block into the session's pending history on the way up and an exit note on the way down, once per switch. Plan mode (/plan) works the same way and also lives in the permission gate: while it is on, the gate refuses write tools, asks before command tools, and asks about every exit_plan call, whose approval turns the mode off mid-run.
Reports and the inbox. An agent's link records where the result of its next finished run goes: the waiting call (agent, swarm or a resume) or, for a background agent, the parent's inbox. Every session has an inbox next to its steering queue. The run hooks hand out the user's steering first, then the whole inbox joined into one message, at each turn boundary and once more before a run would end. A result that lands in an idle main session's inbox starts a run to read it when the session's setup wakes (the TUI and kage clients), or waits for the next prompt when it holds (plain ACP editors). A background agent's cancel flag is its own rather than a child of the parent's run flag, so interrupting the main run leaves it running. The <agent> report and <message> mail formats live in kage_core::agent_report, read by the engine, the TUI, print mode and the ACP bridge alike.
The mailbox. Every agent-enabled session also gets a send_message tool, whatever its depth, because sending does not nest. An agent whose definition lists tools gets it only when the list names it, like agent and swarm. It delivers fire-and-forget: the engine resolves parent or a session id to a running session under the sender's own main session, refusing an agent whose result was already delivered, and puts the text, wrapped as a <message> naming the sender, into the target's inbox. An idle target wakes as for a report. An agent that ends a run with unread mail runs again before its result is taken, so the message reaches its result.
Limits. An agent run carries its turn limit, timeout and the budget counter of its main session's tree. The run hooks warn at the turn limit and stop at the next turn with tool calls. A watcher thread cancels a run past its timeout. Each agent turn adds its tokens to the shared counter, and the run that crosses the budget asks the dispatcher to stop every agent under the main session. The next user prompt resets the counter. The limit that ended a run rides into its report as limit.
Worktrees. An agent whose definition sets isolation: worktree gets a jj workspace or git worktree under the state directory at spawn, held on its link. The run thread checkpoints it when the run ends and appends where the work is to the report. Dropping the agent drops the checkout, which forgets the workspace or removes the worktree.
Forked children. A swarm call with fork: true gives each new child the parent's conversation instead of zero context. The parent's session file is forked into the child's own file (up to the latest entry that is not an unanswered tool call) and the child's context history and token budget are replayed from that copy, so its transcript is self-contained and later resumes see the same conversation. A user-entry notice after the copied history tells the child the conversation is inherited reference material. Model, system prompt and tools still come from the definition, and the kage:agent marker is appended after the copied history, so marker lookups scan the file rather than its first entries.
The cancel tree. CancelFlag is a node with an optional parent. An agent's flag is a child of its parent's, and is_cancelled walks up the chain. Cancelling a session stops every agent below it through the checks every loop, tool and gate already makes, while cancelling an agent never reaches its parent. The dispatcher resets a session's own flag when its run ends, so an idle parent that was cancelled cannot cancel a run later started in one of its agents. Cancellation is immediate on Unix, where shutting the provider socket down wakes the blocked read; on Windows, which cannot wake a read blocked in another thread, the reader polls for kill events in 200 ms slices and observes a cancel up to 200 ms late.
The agent tree. Agents need one new event and no new commands. agent_spawned is published as the agent's first envelope, on the agent's own session:
{"session":"<agent>","seq":1,"type":"agent_spawned","parent":"<parent>","tool_call_id":"<call>","agent":"explore","description":"map exports"}After it, the agent publishes the usual events on its own session. Steering, messaging and stopping an agent are the ordinary prompt and cancel commands addressed to its session. Commands that replace or copy a session (new, resume, fork, clone) are refused for an agent. AgentTree in kage_core::protocol folds envelopes into one node per agent with its parent, state, usage, tool count, latest tool and open approvals. The TUI builds its cards, pinned list, drill-in views, breadcrumb and agents overlay from it, and routes each agent's loop events into that agent's own buffer. The ACP adapter uses it to find an agent's parent session, and for editors without subagent support, the client session at the root of the agent's branch.
mcp in the engine
Each session owns an McpManager with every configured server, live or not, and a cached catalog of their tools, resources, resource templates and prompts. Agents have no manager of their own.
The catalog event. mcp_servers is a live event with the whole catalog: each server's name, status (connected, failed with its error, or needs_auth), tool count, resources, templates and prompts. The dispatcher publishes it when a session opens, after a restart, and when a reload changed the catalog. The latest snapshot wins, and it is never recorded. The TUI builds @server: completion, the prompt commands and the /mcp picker from it, and the ACP adapter builds the editor's command list.
The restart command. restart_mcp {server} restarts one server. In-flight tool calls hold the old connection, so a busy session keeps the name until its next run starts, and an idle session restarts at once. The engine path sends it from /mcp restart, from the picker and after a login; the TUI, which speaks ACP, refuses it (see the TUI's ACP link). kage.mcp.restart from Lua joins the same list at run start.
MCP work off the dispatcher. The dispatcher never waits on an MCP server. A session's manager starts with its servers not spawned yet (McpManager::unstarted), so opening the session is instant; the dispatcher then brings every not-yet-started server up on a worker thread and keeps the session busy until the manager comes back, exactly like an idle restart. At run start it lends the manager to the run thread, which applies the pending restarts and the list reloads that servers announced, then hands the manager back with the resulting tool changes before the loop starts.
Expansion on the run thread. After those reloads, the run expands the prompt with kage_mcp::expand before it enters history: an MCP prompt command at the start is replaced by the prompt's messages, and each @server:uri mention is read and appended as a resource block. The expanded message is what the model receives and what the recorder writes, and clients shorten resource blocks for display. When expansion fails, the run publishes an error notice and fails with history untouched. Steered text is never expanded, which is why the TUI queues such prompts and ACP queues every prompt.
Cancel notices. A kage-jsonrpc connection can build one notification for a request it abandons, whether through a user cancel or a deadline. MCP connections send notifications/cancelled (never for initialize), and the ACP agent sends $/cancel_request when it withdraws a permission request. A closed connection sends nothing.
OAuth. kage-mcp implements the protocol (discovery, PKCE, registration, the loopback listener, token exchange and refresh) and never touches disk. The HTTP transport asks a TokenSource for a bearer token. kage-cli implements it over mcp-auth.json and owns refresh and storage.
the ACP projection
kage rpc maps each ACP session to an engine session and turns the event stream into ACP traffic with one bus subscriber:
- Loop events become
session/updatechunks and tool call updates.session/loadreplays recorded history through the same mapping. usage_updatedbecomesusage_update,title_changedbecomessession_info_update, astate_changedthat moves the model, thinking level or permission mode becomesconfig_option_update, andmcp_serversbecomesavailable_commands_update.permission_requestedbecomessession/request_permission, asked on its own thread. The asks still open when the run ends are withdrawn before the prompt answers.- For a client with the subagents capability,
agent_spawnedregisters the agent as a child session, announced withsubagent_update, whose events then take the same path under the child's id. A client session's prompt answers only after every child has sent its final state. Other clients get agent progress and asks on the root session'sagentcall.
Updates for a session are held until the response to the session/new, session/load or session/resume that names it is written, so a client never sees them first.
Config option changes and prompts become ordinary engine commands, so the editor, the TUI and print mode share one implementation.
the TUI's ACP link
The TUI is an ACP client. A reader thread, a writer thread and a pump thread run the connection, and the pump turns the agent's frames into the events the App draws. By default the agent is the user's shared host. --standalone, [host] share = false, a configuration override from the environment, a host of another version, a host that cannot be started and platforms without the socket use a private host served inside the process over an in-memory pipe.
Two knobs are experimental and exist for tests: KAGE_LINK=acp runs the TUI against a kage rpc child of the same binary instead, and KAGE_RPC_BIN names another program to run as that child. Neither is a supported way to run kage.
The TUI loads the user's plugins itself. At initialize it announces plugin_host, and the sessions it opens carry _meta.kage.plugins = "client", so the agent asks the TUI for the plugin tools, hooks and events with _kage/plugin/* requests. A worker thread answers them in order, so the pump keeps serving the App while a Lua tool runs, and Esc cancels the running tool. A resumed or loaded session carries the same _meta.kage a new one does, so its settings and the TUI's plugin hosting survive the switch. A hosted plugin MCP server that sets disabled_tools or oauth is started by the agent without them, and the TUI warns when it sends one.
The ACP link has no counterpart yet for some commands the engine path served. The TUI refuses each with the notice "... is not available over the ACP link yet":
| Command | What it was |
|---|---|
| shell escapes | running a shell command from the prompt |
| fork, rewind, undo | forking or rewinding the live session |
| clone | cloning the session |
| image open, image save, media open, media save | opening or saving attachments |
reload plugins, refresh providers, restart MCP (/mcp restart) | reloading what the engine held |
| fork a session file, delete a session | acting on recorded sessions |
An attachment kept in the session's blob store cannot ride the link and is dropped with a warning.
the serve component
kage serve puts the host behind a TCP listener. One endpoint, one token. On Unix it holds the shared host's single-instance lock for its whole life, so it cannot run alongside a kage host or another serve; on Windows the TCP port is the only guard:
kage-remoteparses the upgrade request head (16 KiB cap, 10 s deadline), checks the token in constant time in a fixed order (theAuthorization: Bearerheader, then akage.oracp.Sec-WebSocket-Protocolentry echoed in the 101, then thetokenquery parameter), and upgrades the socket: two plain threads turn text frames into JSON-RPC lines and flushed writes into text frames, with byte-capped backpressure, pings and an idle timeout.- The serve command owns the routing table. A valid-token
GET /acpupgrade is served like akage rpcconnection on the sharedHost; everything else gets a plain HTTP reply:401without a valid token,405for non-upgrade traffic on/acp,404elsewhere,431for an oversize head, and503once 16 connections are already served. Every connection runs on its own thread off the main accept loop. - The same routing table serves the web client bundle when a web directory is available (
--web-dir, default$XDG_DATA_HOME/kage/web, which--fetch-webfills):GET /answers the page andGET /<file>a file under the directory. Every asset response carries a strictContent-Security-Policy(same-origin sources only, WebAssembly compilation allowed, inline script closed off) plusnosniffandno-referrer; the page isno-store, the unhashed module and glue are cached for five minutes at most, and the page and the module carry cross-origin isolation headers so a future atomics build can useSharedArrayBuffer. A path is served only when it decodes inside the web directory, so traversals are refused. The assets hold no secret, so the token still guards/acponly. - Attach, shared approvals and idle close are host behavior, not transport behavior: a second connection attaches to the live session with a replay inside one bus lock, every attached client is asked each approval with the first answer winning, a second client's prompt during a run fails busy, and a session no connection holds is closed once idle.
- The accept loop also sheds what no client holds every 250 ms, like the shared host's tick: project runtimes past their grace and asks past the ask-hold cap.
- SIGINT and SIGTERM cancel every run and give the sessions a moment to close their files before the process exits; a second signal exits at once. The connect URL printed at startup is the only place the token is ever rendered.
the shared host
On Unix, kage host run serves the same Host on a local socket, so every kage rpc of one user shares one engine. See shared host for what users see.
- One per user. The host takes an exclusive
flockonhost.lockin the runtime directory before anything else, then bindshost.sock(0600) and only afterwards starts its engine, so clients queue while it warms up.host.jsonrecords it once it accepts. A host that cannot take the lock connects to the socket: when that answers, another host serves and this one exits 0; when it does not, an old host is shutting down and the new one waits for the lock for up to 10 seconds. - Accept loop. A
poll(2)loop with a 250 ms tick accepts connections, checks the stop flag and measures idleness: no connection open andHost::busyfalse (no turn running or paused and no ask open) for the idle timeout. On idle it unlinks the socket first, then accepts what queued in the meantime, and binds again if anything did, so a client never connects to a host that is leaving. - Web endpoint. With
[host] web = truethe host binds the same TCP listenerkage serveruns, on its own thread, with the same token, routing table and web directory defaults, and shares the local socket's connection budget, so a web client counts toward the connection cap and holds the host against idleness like a local one. The listener stops accepting before the exit path unlinks the socket. Off by default; on Windows the host does not run at all. - Per-client output. Each connection writes through a bounded queue drained by its own thread. A client that stops reading is disconnected once 16 MiB are queued for it, so it can never stall the engine's bus for the others.
- Native serving. On Linux every connection is served over the native Unix peer (
rpc/native.rs), which external sessions need. The peer writes into a pipe kage owns and one pump thread copies each line to the connection, so a slow client stalls only that thread and the peer's writes time out after 30 seconds. A message the host sends that is over 8 MiB closes the connection. - External sessions. A
session/newnaming an agent configured in the user's[acp.agents]starts it as a child process (rpc/external.rs). The host owns the process in one of 8 slots (external/lifecycle.rs), reserved with its cleanup thread before the process spawns, so closing or dropping a session never waits for cleanup. Updates from the agent fan out to every attached connection through a bounded queue per attachment. The session file records a display history on a worker of its slot (external/recorder.rs) and its header names the agent and the upstream session id, never a command. A reopen starts a fresh process and restores the upstream session withsession/resumeorsession/load, whichever the agent advertises. The session's engine features (tools, models, forks) do not apply: the agent owns them. - Relay.
kage rpcconnects, or startskage host run --detached(setsid, cwd/, stderr tohost.log) and retries with backoff. It waits forhost.json, refuses a host of another version, then sends_kage/environmentand copies bytes both ways. Any failure before relaying falls back to the in-process engine. - Session environment. A connection on the local socket may send its environment.
AgentContext::envcarries it, never persisted, to everyToolContext, the stdio MCP spawns and restarts of the session'sMcpManager, its plugin runtime'skage.execandkage.env, worktree VCS commands, every agent the session spawns, and eachStreamRequest, whoseworkdirandenvstart the agent behind anacp:model. A connection that sends none, and everykage serveconnection, runs with the host's own environment.
data flow per turn
user keypress
v
kage-tui input dispatch
v (a request)
kage-cli TUI pump -> ACP session/prompt to the agent
v
agent runner thread: kage-loop run()
v -> kage-provider stream request
v <- provider streams events
v
each loop event:
-> Lua plugin events ("turn_start", "message_update", ...)
-> session recorder appends JSONL
-> event bus: ACP session/update chunks, or print output
v
kage-tui applies the update and repaints the visible regionThe loop is fully synchronous. There is no async runtime in core.
sessions on disk
A session file is a single JSONL stream. The first line is a header. Every entry carries its own id and ts so forks can branch from any point:
{"type":"header","version":1,"session":"...","id":"...","ts":"...","cwd":"...","model":"...","system_prompt":"..."}
{"type":"message","id":"...","ts":"...","message":{"role":"user","content":[...]}}
{"type":"message","id":"...","ts":"...","message":{"role":"assistant","content":[...]}}
{"type":"compaction","id":"...","ts":"...","kept":4,"summarized":12,"summary":"..."}Tool calls and results are not separate entries: they ride inside message content blocks. The remaining entry kinds are thinking_level_change, model_change, label, title, and the plugin-defined custom.
An agent's header's parent_session names the session whose call started it, and a custom entry of kind kage:agent names the same session, with the agent call id, the agent name and the task description. The entry comes right after the header, followed by a title entry, or after the history an agent given its parent's context copied. A fork copies its source's lines, those entries included, but its header names the source, so only an entry naming the header's parent makes a file an agent, and a fork of an agent is a user session. Session listings read that entry to hide agent files from kage list and the pickers, and /tree shows them under their parent.
Files are append-only: the writer never rewrites prior lines, and an advisory lock rejects a second concurrent writer. To branch from an existing session, fork instead.
Media bytes do not sit in the file. An image of 16 KiB or more is written once to the blob store beside the sessions, blobs/sha256/<first two hex digits>/<sha256>, and the content block names it instead of carrying base64:
{"type":"image","source":{"kind":"blob","sha256":"...","size":618432},"mime":"image/png"}Every session in the directory shares the store, so a fork or a repeated image costs nothing. Reading a session puts the bytes back, and a blob that has gone missing reads as unavailable media rather than failing the session. Older files with inline base64 load unchanged.
the Lua layer
Lua is kage's configuration and extension layer. From the top down:
~/.config/kage/init.lua, lua/** trusted user config, all capabilities
plugins/*.lua (sorted by name) sandboxed, capabilities on request
kage.* stdlib (embedded Lua) kage.on, kage.keymap, kage.ui.set_slot, aliases
_defaults.lua (embedded Lua) default keymaps and slot specs
kage.api.* (Rust primitives) autocmds, options, keymaps, highlights, slots
kage-core registries Keymap, OptionStore, Highlights (plain data)
Rust renderers and components kage-tuikage-plugin builds one PluginRuntime per process. A single owner thread holds the Lua state. Everything else (tools, event dispatch, commands, key handlers, option changes from the TUI) sends it jobs and waits for the reply, so calls never interleave. Between jobs the same thread runs kage.schedule, kage.defer and kage.timer callbacks from a deadline heap. A long Lua tool or provider occupies the thread until it finishes.
The TUI loads, in order: _defaults.lua, the plugins sorted by file name, [keybindings] from config.toml, then init.lua, and fires color_scheme once. Each layer overrides the ones before it. A host (kage rpc and kage serve) loads the same layers once per project, keyed by the canonical workdir, and every session in that project shares that runtime. A project with no plugin content, nothing under the plugins directory and no user init.lua or lua/ modules, loads none for its sessions. Each piece of Lua work carries the session it runs for (kage_plugin::Invocation), so kage.exec and kage.env use that session's environment and its queued session writes reach its own file. A project runtime no session has held for a minute is dropped on the shared host's next tick, or elsewhere when a session opens. Print mode loads _defaults.lua and the plugins, never init.lua. Each file evaluates in its own environment with private copies of the shared kage tables, so no plugin can change another's view or reach the trusted user environment.
The keymap table, the option store and the highlight table are plain data in kage-core, shared behind mutexes with generation counters. Lua writes them on the owner thread. The TUI reads them under a short lock and recompiles what it needs when a generation moves, so looking up a key or painting a color never runs Lua. A key mapped to a Lua function is sent to the owner thread as a job.
Autocmd metadata and subscriber counts live on the Rust side, so an event nobody subscribes to never reaches the owner thread. Slot components, widgets and block renderers keep their last output. Slot components recompute on the owner thread only when a listed event fires, their interval passes, or the width changes, and the renderer reads the retained lines, so the screen never waits on Lua.
why no async
The agent loop is human-paced (one prompt at a time, one stream at a time). Providers expose blocking iterators over server-sent events. Tools run sequentially in the simplest case, in parallel by explicit opt-in for the read-only ones, and a batch made only of agent calls runs its agents at once on plain threads. None of this benefits from tokio, and adding it forces every layer to colour-async. The synchronous design keeps each crate small and the call stack readable.