Architecture

Kraft is one Python process on your machine. It serves a React SPA and an HTTP API, walks each work item's chain, and spawns a coding agent or a command for each task. Everything it knows is in one SQLite database. This page shows how those parts fit, and where in src/kraft/ to change each one.

For what a work item does, step by step and status by status, read How a work item runs first. For the words, see Vocabulary.

The parts

• One process. kraft (or kraft admin start) runs uvicorn with the FastAPI app from src/kraft/api/. The same process serves the built SPA, answers the API under /api, pushes events over a WebSocket, and runs every work item's walk as an asyncio task. There is no queue, broker or second server.
• Clients. The SPA, the kraft CLI and the MCP server all call the same HTTP API. The MCP server is kraft admin mcp: a separate stdio process that your coding agent starts, with one tool per CLI verb. Both go through src/kraft/client/, so a verb and its tool cannot drift apart.
• The executor. src/kraft/executor/ walks a work item's frozen chain node by node. It runs builtin and forge tasks inside the process and launches agent and subprocess tasks as child processes. It is started by an API request (resume, retry, approve, reject, skip) or by a poller.
• Worker sessions. Each agent task is a headless agent CLI (Claude Code, Codex, Gemini, Cursor, OpenCode or Amp) started in the item's git worktree, with an environment built from an allowlist. With a sandbox configured, it runs in a container (Docker or Podman) instead, and reaches the network only through Kraft's egress proxy. A worker talks back to Kraft for permission decisions, plan progress and review replies.
• Pollers. Background tasks in the same process re-enter items that are waiting or rate_limited, stop parked items whose time cap ran out, fire cron triggers, pick up ready beads when auto-intake is on, fire delayed auto-escalations, and archive old ended items.
• Stores. run/orchestrator.db holds work items, sessions, gates, review threads and an append-only events table. All writes go through one writer queue (src/kraft/db.py). The WebSocket, notifications and the search index each follow the events tail. run/index.db is the full-text and vector search index over your repos' documents.
• Outside tools. Kraft calls git for worktrees and rebases, gh or glab for merge requests and CI, and bd for beads, each as a subprocess with your own login.

From filing to merge

1. kraft item create posts to POST /api/work-items (api/routes/work_items.py). executor/entry.py runs intake: it resolves the chain (templates/), freezes it and the effective policy onto a new row (store/work_items.py), and copies attachments to run/attachments/. The item lands paused.
2. kraft item resume (api/routes/lifecycle.py) claims the item with a conditional update from paused to active, checks the slot limit in the same statement, and spawns executor.run as a task.
3. executor/walk.py loads the chain, cuts the worktree (builtins.py), and walks. For each exec node, executor/dispatch.py runs its steps. An agent task goes through adapters/agent.py, which builds the command line from the harness profile (harness.py, harnesses/*.yaml), then adapters/subprocess.py, which launches it, watches its log, and reads its result file and usage.
4. At a gate node, executor/gates.py sets needs_human and writes gate_requested. The walk task ends. The event reaches the board over the WebSocket and, if you configured one, an outbound notification (notify.py).
5. kraft item approve (api/routes/gates.py) checks for open must-fix threads, sets the item active again, and spawns a new walk at the node after the gate.
6. Forge nodes (adapters/forge/) open the draft merge request and read CI. A pending pipeline is an external wait (waits.py): the item goes waiting, the walk task ends, and the wait scheduler re-enters the walk when the next check is due.
7. After final_review, forge nodes mark the merge request ready, wait for any required approval, merge, and watch the post-merge pipeline. The walk marks the item completed and closes its beads (executor/entry.py).

A restart does not lose finished work. On startup, worker/reattach.py finds the sessions that were running, adopts the ones still alive, and resumes each item's walk from the node and step it had reached.

Trust boundaries

Four lines matter. The Security page states what each one does and does not stop by default; this is only where each one lives in the code.

A workspace member is a worktree of its connected repository (_setup_submodules in builtins.py), so host git in it reads that repository's config, not a gitdir under the root's worktree. It also reads the member's own config.worktree when that repository sets extensions.worktreeConfig. A sandboxed container sees each member as it sees the root: its refs go through a ref store of its own (prepare_stores in worker/refstore.py), and its .git and the commondir, gitdir and config.worktree of its admin directory are mounted read-only (_gitdir_mounts in worker/backends/docker.py), from paths derived from the connected repository and never read from the member's .git. For a sandboxed item, refuse_planted_repos in executor/stops.py checks each member against the checkout Kraft made (foreign_members in worker/sandbox.py) before host git runs there, and a task's launch mounts exactly the checkout that check returned. Every other sandboxed launch (a gate review, an escalation turn, a review reply, the setup command) takes its checkout from sandbox_checkout, which runs the same check and leaves out any member that fails it, so the launch does not start. Each directory from the worktree down to a member is mounted onto itself, so no container can rename it and put another .git in the member's place.

Module map

Every path below is under src/kraft/.

Serving

Running a chain

Templates

Agents and workers

Forge and trackers

State and configuration

Outside src/kraft/: the SPA is in frontend/src/ (views/ per screen), the packaged default templates are in templates/, the agent plugins are in plugins/, the VS Code extension is in vscode/, and contributor scripts are in dev/.

Where to change things

Before a pull request, see Contributing.

State on disk

State lives in $KRAFT_HOME (default ~/.kraft). run/ holds the databases, session logs and result files, worktrees, attachment copies, the process id file, and the sandbox's sockets and CA. templates/ holds the YAML the Settings screens edit. templates/ is seeded from the packaged defaults on first run and never overwritten after, so an upgrade cannot clobber an edited policy. See Configuration for what's in those files.