Get started

Install

Install Kraft with uv, Homebrew, the install script, or from source, start the server, register it with Claude Code, and check that it works.

Install Kraft, start its server, and register it with Claude Code. At the end the board loads at http://127.0.0.1:8765 and kraft admin doctor has nothing to say against your install.

Before you start

You need:

macOS or Linux. Windows is not supported, and WSL is untested: see the FAQ.
uv, or Homebrew: uv --version prints a version.
git with a commit identity: git config user.name and git config user.email each print a value. Kraft commits the agents' work under that identity. If either prints nothing, run git config --global user.name "Your Name" and the same for user.email. A repo that sets its own identity is the case in no user.name configured.
Claude Code (claude), installed and logged in: claude --version prints a version. The shipped chains run every agent task on it; another agent CLI is a harness and needs a chain edit.

Installation methods

Pick one. Each tab says who it suits. Kraft is Apache-2.0 licensed: see Licenses.

For anyone with uv. It is the shortest path, and installs from PyPI. uv uses a Python 3.12 or newer already on your machine, or fetches one. To choose the interpreter yourself, add --python 3.13.

uv tool install kraft-sdlc

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.

For a Mac where you manage tools with Homebrew: kraft admin update then runs brew upgrade kraft.

brew tap itsOmidKarami/kraft
brew install kraft

For a machine with neither uv nor Homebrew. 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. It says where it put kraft, and when that directory is not on your PATH yet (usually after it installed uv), it says to run uv tool update-shell and open a new terminal.

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. just setup installs the Python and frontend dependencies, and just install builds the board and installs the kraft command:

git clone https://github.com/itsOmidKarami/kraft.git
cd kraft
just setup
just install

To develop Kraft rather than run it, see Contributing.

Start the server

kraft

It prints its address and keeps running in this terminal:

kraft: http://127.0.0.1:8765

When a newer release exists, a line kraft: <installed> installed, <new> available - kraft admin update comes first; it is only a notice. Leave the server running and open the address in a browser. With no repo connected, the board shows Nothing on the board yet. Open a second terminal for everything that follows.

If the command is not found, see kraft: command not found. If it prints kraft: refusing to start - something is already answering on ..., see Kraft won't start: port already in use.

Connect your agent

Kraft talks to agents through its MCP server, the command kraft admin mcp. Register it with Claude Code first, then with any other agent you want to drive Kraft from.

Claude Code

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 register it even when you drive Kraft from another agent.

Install the plugin:

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

The plugin registers the MCP server itself: do not also run kraft admin init.

Without the plugin, register the server and the /kraft:* commands from a terminal instead:

kraft admin init

It prints one kraft: wrote <path> line for each file it writes, starting with the plugin's manifest:

kraft: wrote /home/you/.claude/skills/kraft/.claude-plugin/plugin.json
kraft: wrote /home/you/.claude/skills/kraft/skills/board/SKILL.md

If it exits with kraft admin init: could not register the MCP server automatically, it prints the claude mcp add command to run yourself. This happens whenever claude mcp add exits non-zero, for example when claude is not on your PATH.

Connecting a repo is step 2 of Your first work item.

Other agents (optional)

To drive Kraft from Codex, Cursor, OpenCode, Amp, Antigravity or Gemini CLI, register the MCP server with it. Use Kraft from your agent has the steps for each agent. Give a worker its login covers what a worker needs when a chain runs on it. The kraft command must be on your PATH for every agent.

Check it worked

In the second terminal:

kraft --version
kraft admin health
kraft admin doctor

Each prints a few lines, cut here to the ones that matter. The paths in the doctor rows are your own, and more rows come between them:

$ kraft --version
kraft 2.0.0
$ kraft admin health
status         ok
version        2.0.0
$ kraft admin doctor
ok    server         http://127.0.0.1:8765
ok    agent: claude  /usr/local/bin/claude
ok    kraft on PATH  /home/you/.local/bin/kraft

all <N> checks passed

doctor prints one line per check, led by ok, warn, FAIL or skip (a check that needs the server, when none is up), and a count at the end. You know it worked when:

http://127.0.0.1:8765 shows the board.
kraft admin health shows a status of ok and exits 0. It exits 1 when the server is down or degraded.
kraft admin doctor ends in all <N> checks passed, followed by , <W> warned when a row warns. While any row reads FAIL it exits 1 and ends in <F> of <N> checks failed.

A FAIL row names its cause, and Doctor failures has every row and its fix. Once you connect a repo, doctor adds rows about it. Four FAIL rows are common right after an install:

mcp server: nothing registers Kraft's MCP server with Claude Code. Install the plugin, or run kraft admin init.
kraft on PATH: the kraft command is not on your PATH. After a uv install, run uv tool update-shell, then start kraft again from a new terminal.
forge <repo>: a connected repo has no GitHub or GitLab origin, or gh or glab is not on your PATH.
setup <repo>: a connected repo has no setup_command. See Doctor failures for both.

Uninstall and where state lives

Uninstalling removes the kraft command and nothing else, so stop what runs first, while the command exists. Stop a running server:

kraft admin stop

If you installed a service, remove it too:

kraft admin uninstall-service

uninstall-service deletes the launchd agent or the systemd unit, and a systemd drop-in you made stays. Run Kraft as a service says what to save before you remove it. Then remove Kraft with the command for how you installed it:

Installed with	Run
uv or the script	`uv tool uninstall kraft-sdlc`
Homebrew	`brew uninstall kraft`

Two things are left:

Claude Code's registration. Remove the plugin with claude plugin uninstall kraft. If you ran kraft admin init instead, remove its registration with claude mcp remove --scope user kraft, and delete the skill files it wrote under ~/.claude/skills/kraft/. Another agent you registered keeps its registration: Use Kraft from your agent covers each one.
$KRAFT_HOME (default ~/.kraft), where Kraft keeps its state. Delete that directory yourself to discard it.

uv itself, and a Python it fetched for Kraft, stay too: they are uv's, and uv python uninstall removes a Python.

config/ holds the YAML you edit, a plain directory you can diff, revert or git init: see Configuration. run/ holds the databases, logs, worktrees and attachment copies: see Secrets and state. A second, fully separate instance needs its own KRAFT_HOME and its own port: see Run two instances.

Next steps

Your first work item: connect a repo, run a work item to a merged pull request, and approve its gates.
Upgrade Kraft: upgrade, restart safely, or roll back an installed Kraft.
Vector search: search works as full-text search out of the box; the optional vector extra adds semantic search.
Run the server: back up, read logs, and keep the server running as a service.
Remote access: reach the board from another device.

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.