Use Kraft from your agent

Register Kraft with your coding agent and connect a repo, then file work, read the board, and approve or reject gates from the agent's session without switching to the browser. At the end the agent answers "what is waiting on me in Kraft?" from the board.

Every agent reaches Kraft through its MCP server, the command kraft admin mcp. With the Kraft plugin, Claude Code, Codex, Cursor and Antigravity also get Kraft's skills, which Claude Code runs as /kraft:* commands.

Registering lets you drive Kraft from the agent. The agent CLI that runs a work item's tasks is a separate choice: Switch a task to another harness moves tasks to another, and Give a worker its login gives that CLI the login a headless worker needs.

Before you start

• Kraft installed, with kraft on your PATH, and the server running (kraft). See Install.
• A git checkout of the repo you want Kraft to work on.
• One of the agents below, signed in.

Register Kraft with your agent

Pick your agent. Each tab ends with the command that lists the registration.

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

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

codex mcp add kraft -- kraft admin mcp

[mcp_servers.kraft]
command = "kraft"
args = ["admin", "mcp"]

agent plugin marketplace add https://github.com/itsOmidKarami/kraft

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

agent mcp enable kraft

opencode mcp add --global kraft -- kraft admin mcp

amp mcp add kraft -- kraft admin mcp

amp skill add itsOmidKarami/kraft/plugins/kraft/skills --global

clone=$(mktemp -d)
git clone --depth 1 https://github.com/itsOmidKarami/kraft.git "$clone"
agy plugin import "$clone/plugins/kraft"
rm -rf "$clone"

agy mcp add kraft kraft admin mcp

gemini mcp add --scope user kraft kraft admin mcp

Kraft's skills reach Claude Code, Codex, Cursor and Antigravity through the plugin, and Amp through amp skill add. OpenCode and Gemini CLI get the MCP server alone: ask for what you want in plain words ("what is waiting on me in Kraft?") and the agent calls the MCP tools. The kraft command gives a hook or an agent without MCP the same surface.

Connect the repo

Kraft works on repos it has connected. In the repo's directory, run:

cd ~/code/my-project
kraft repo connect

It prints the repo's path, the branch Kraft reads, and the two commands it proposed, each with the file it came from:

connected: /home/you/code/my-project
  read from origin/main, where work items start
test command: just test (from justfile recipe `test`)
setup command: uv sync (from uv.lock)

After those, an also found or not installed here line appears where Kraft has more to say. When it found no test command, a final saved disabled: line says how to enable the repo.

Where the skills are installed, /kraft:onboard in a session of that agent does the same and then checks the two commands. Run it before the first work item starts: the commands Kraft proposed are saved unconfirmed, and an item that runs against wrong ones stops.

Check it worked

1. The list command in your agent's tab shows kraft (Cursor's plugin shows in /mcp, as its tab says).
2. In a new session of that agent, ask: "what is waiting on me in Kraft?" The agent answers from the board: your items, or that nothing is waiting. Where the skills are installed, /kraft:board lists the work items of every connected repo, not only the one you are in.
3. For Claude Code, kraft admin doctor has an mcp server row. It passes once Kraft is registered, and names the permission tool Claude workers use. The row checks Claude Code's registration only, not Codex, Cursor, OpenCode, Amp, Antigravity or Gemini CLI. For those, use the list command in the agent's tab.

If the agent cannot reach Kraft, check that the server is running (kraft admin health) and that kraft is on the PATH of the shell the agent starts. Troubleshooting lists the rest.

Set up without the plugin

Use this when you want plain files instead of a managed plugin. For Claude Code without the plugin, this step is required: without a registered kraft MCP server, Kraft refuses to launch a Claude worker.

For Claude Code, run one of:

kraft admin init
kraft admin init --repo

• The first registers Kraft with Claude Code for your user, so it covers every repo you open (claude mcp add --scope user kraft -- kraft admin mcp) and writes the skills to ~/.claude/skills/kraft/. It needs the claude command; without it, it prints that command for you to run.
• The second covers this repo only. It writes a .mcp.json and .claude/skills/kraft/ into the current repo, where other tools can read them too. Commit the .mcp.json: each work item runs in a fresh checkout of the repo, and an uncommitted file is not in it.

Either way you get the same /kraft:* commands. To remove them, delete the skills directory.

kraft admin init registers Kraft with Claude Code only. For another agent, use its tab in Register Kraft with your agent. An agent not listed there needs an MCP server that runs the command kraft admin mcp over stdio.

Refresh the skills

The user-scope form fails on a second run. claude mcp add refuses a name that is already registered, so kraft admin init prints "could not register" and writes no skills. The same happens when you run the command it printed first. To refresh the skills after upgrading Kraft, or to write them after running the printed command, remove the registration and run it again:

claude mcp remove --scope user kraft
kraft admin init

kraft admin init --repo registers nothing with claude, so you can re-run it as often as you like. The plugin route has no such step: claude plugin update kraft refreshes its skills.

The skills

Claude Code runs these as slash commands. In Codex they have the same names without the slash (kraft:board), picked with $.

Example: hand work to Kraft

Say you and your agent have settled what to build, and you want Kraft to build it. Ask for /kraft:handoff, with the work in your own words:

1. The skill connects the repo if Kraft has not seen it. If it newly connected it, it tells you and runs /kraft:onboard before the item can start.
2. It files the work with create_work_item, putting your intent in the description, which is the brief the spec node writes its design from. A spec and a plan you already wrote are attached, and the item skips the node and gate each one satisfies.
3. It reads the board back (kraft view list --status=paused) to check the item is there under the title you gave.
4. It reports the work as filed, not running: the item is paused under Not started, and nothing spends tokens until you start it. Click its row, then Start in the side panel or on the item's own page, or ask your agent to resume it (/kraft:gates).

What an agent is refused

The MCP tools have no autostart option, and the server refuses kraft item create --autostart from a session Kraft started or a request tagged as the MCP client. It cannot tell a coding agent that runs the command in your own shell from you, so that call starts the item.

A worker is refused every item verb on its own work item (approve, reject, pause, resume, skip, abandon, retry, complete, cancel and escalate), and any change to its attachments, overrides or policy, because a gate is where a person decides.

These are checks on the client and on the API, and none is a boundary against a worker that is not sandboxed. Who may call what lists every refusal, and Agents and gates says what each one does and does not stop.

Next steps

• Reviewing a change: the comment, approve and request-changes outcomes your agent can send for you.
• Switch a task to another harness: run a chain's tasks on Codex or another CLI.
• Kraft for VS Code: clear gates from the editor instead of the agent.
• Kraft Lite: run a chain inside one agent session, with no server and no MCP server.