Get started

Install

Install, verify, upgrade, and uninstall Kraft with uv, Homebrew, the install script, or from source.

Install Kraft with uv, Homebrew, the install script, or from source. Then run kraft to serve the board at http://127.0.0.1:8765.

Requirements

To install and run Kraft you need:

macOS or Linux. Windows is not supported, and WSL is untested.
uv, or Homebrew. uv uses a Python 3.12 or newer already on your machine, or fetches one. To choose the interpreter yourself: uv tool install --python 3.13 kraft-sdlc.
git.
Claude Code (claude), installed and logged in. Every agent task in the shipped chains runs on it. Kraft supports other agent CLIs as harnesses, but using one means editing the chains.

Installation methods

Pick one. uv is the shortest path.

uv tool install kraft-sdlc
kraft

The package is kraft-sdlc on PyPI because other tools already use the name kraft (Unikraft's CLI, for one). The command it installs is still kraft.

brew tap itsOmidKarami/kraft
brew install kraft
kraft

The script fetches the newest release and installs uv first if you do not have it:

curl -fsSL https://raw.githubusercontent.com/itsOmidKarami/kraft/main/install.sh | sh

install.sh is short and worth reading before you pipe it to a shell.

Use this to run an unreleased commit or to work on Kraft itself. Besides uv and git, you need just and Node 22 to build the board:

git clone https://github.com/itsOmidKarami/kraft.git
cd kraft
just setup     # Python and frontend dependencies
just install   # builds the board and installs the `kraft` command
kraft

To develop Kraft rather than run it, see Contributing.

Connect your agent

Kraft talks to agents through its MCP server, the command kraft admin mcp. Register it with the agent you want to drive Kraft from. Pick your agent:

Install the plugin:

claude plugin marketplace add itsOmidKarami/kraft
claude plugin install kraft@kraft

Then, with the Kraft server running, open a session in your repo, run /kraft:onboard, and follow what it asks. It connects the repo and checks its setup and test commands. The plugin registers the MCP server itself: do not also run kraft admin init.

Without the plugin, register the server and the /kraft:* skills from a terminal, then connect the repo:

kraft admin init
cd ~/code/my-project
kraft repo connect

Install the plugin:

codex plugin marketplace add itsOmidKarami/kraft
codex plugin add kraft@kraft

It registers the MCP server and adds the Kraft skills. Without the plugin, register the server alone with codex mcp add kraft -- kraft admin mcp.

Then connect the repo:

cd ~/code/my-project
kraft repo connect

Add the server to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "kraft": { "command": "kraft", "args": ["admin", "mcp"] }
  }
}

Approve it with agent mcp enable kraft, then connect the repo with kraft repo connect.

opencode mcp add --global kraft -- kraft admin mcp
cd ~/code/my-project
kraft repo connect

amp mcp add kraft -- kraft admin mcp
cd ~/code/my-project
kraft repo connect

gemini mcp add --scope user kraft kraft admin mcp
cd ~/code/my-project
kraft repo connect

The shipped chains run every worker on Claude Code, and Kraft refuses to launch a Claude worker unless Claude Code knows the kraft MCP server: the worker asks the permission gate through it. So even when you drive Kraft from another agent, install the Claude Code plugin or run kraft admin init as well.

The Kraft plugin, with its skills, is for Claude Code and Codex. A plugin for Cursor, OpenCode, Amp or Gemini CLI isn't shipped yet, so those agents get the MCP server alone.

The kraft command must be on your PATH for every agent. Agent integration covers each agent in detail, including what a worker needs when a chain runs on it.

Verify

kraft runs the server in the foreground, so open a second terminal for this:

kraft --version      # prints the installed version
kraft admin health   # exits 1 if the server is down or degraded
kraft admin doctor   # runs every check; exits 1 if any fails

You know it worked when kraft admin doctor exits 0 and http://127.0.0.1:8765 shows the board.

Run it after you connect a repo: most of its rows are about connected repos. Two of them fail on a repo that is not ready yet:

forge <repo> fails when the repo has no GitHub or GitLab origin remote, because no forge is recorded for it. quick-task does not need one; the default chain does.
setup <repo> fails when the repo has no setup_command.

mcp server fails when nothing registers Kraft's MCP server: install the plugin, or run kraft admin init.

Next: Your first work item.

Enable vector search

Search works out of the box in full-text mode. To add vector (semantic) search to a uv or script install, reinstall with the vector extra. It downloads a model of about 130 MB on the first search.

uv tool install --force "kraft-sdlc[vector]"

Upgrading

kraft admin update             # install the newest release
kraft admin update --restart   # also restart a running server, the same way it was running

On a Homebrew install, kraft admin update runs brew upgrade kraft instead of uv tool install.

An upgrade never changes $KRAFT_HOME/templates/, with one exception: an install still on the pre-V1 template format is migrated, after a prompt (see Migrating a pre-V1 template configuration). To take new shipped chains and library tasks, see Upgrading your templates.

From before the kraft-sdlc rename. An older install can still hold a kraft uv tool next to kraft-sdlc. kraft admin update then stops and names the two commands that clear it:

uv tool uninstall kraft
uv tool install --force --reinstall kraft-sdlc

The reinstall is needed because the uninstall removes the kraft command both packages share.

From a 0.x install. Read the 1.0.0 changelog first. Finish or abandon in-flight items, and note that harness profile names and the template layout changed.

Pin or roll back a version

kraft admin update only installs the newest release on a channel; it cannot target a version. Install a specific version with the package manager instead.

uv or script install. Name the version:

uv tool install --force "kraft-sdlc==X.Y.Z"

Add the extra if you use vector search: "kraft-sdlc[vector]==X.Y.Z". To stay on that version, do not run kraft admin update; it moves you to the newest release again.

Homebrew. The tap has one formula, which each release rewrites to the newest version, so Homebrew cannot install an older one. brew pin kraft stops brew upgrade, and with it kraft admin update, from moving the version you have. To go back to an older release, brew uninstall kraft and install that version with uv.

What a rollback does to $KRAFT_HOME. Starting a newer Kraft migrates run/orchestrator.db forward in place, and there is no downgrade migration. An older Kraft refuses to start on a database a newer one migrated (database schema vN is newer than code vM). So back up run/orchestrator.db before you upgrade, and restore that backup when you roll back. run/index.db needs nothing: an older Kraft rebuilds a search index it cannot read. A rollback does not rewrite templates/; run kraft admin templates lint after a rollback to check the older version still accepts them.

Uninstall

uv tool uninstall kraft-sdlc   # uv or script install
brew uninstall kraft           # Homebrew install

Neither removes $KRAFT_HOME. Delete that directory yourself to discard all Kraft state.

Where state lives

Kraft keeps state in $KRAFT_HOME (default ~/.kraft):

Path	Holds
`~/.kraft/run/`	`orchestrator.db`, `index.db`, `logs/`, `results/`, `worktrees/`, `attachments/`
`~/.kraft/templates/`	The YAML the Settings screens edit: `library.yaml`, `chains/`, `harnesses.yaml`, `policy.yaml`, `repos.yaml`, `intake.yaml`; `access.yaml` and `notify.yaml` appear once you save those Settings screens

templates/ is seeded from the packaged defaults on first run and never overwritten after, so an upgrade cannot clobber an edited policy. It is a plain directory of files, so you can diff it, revert it, or git init it.

To reach the board from another device, see Remote access.

A second, fully separate instance needs its own KRAFT_HOME and its own port. See Run two instances. For backups, logs and disk use, see Operate a Kraft server.

Edit this pageorReport an issue

Why Kraft

What Kraft does that an interactive session, a loop, or a skill does not, and when it is the wrong tool.

Your first work item

Start Kraft, connect a repo, run a work item end to end, and approve its gates.