Guides

Use Kraft from your agent

Register Kraft with Claude Code, Codex, Cursor, OpenCode, Amp or Gemini CLI, drive it from that agent, and run workers on it.

Drive Kraft from a coding-agent session: file work, read the board, and approve or reject gates without switching to the browser. Every agent reaches Kraft through its MCP server, the command kraft admin mcp. With the Kraft plugin, Claude Code and Codex also get Kraft's skills.

Before you start, you need Kraft installed with kraft on your PATH, and the server running (kraft). See Install.

Register Kraft with your agent

Pick your agent.

Add the Kraft marketplace and install the plugin:

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

Then, in each repo you want Kraft to work on, open a session, run /kraft:onboard, and follow what it asks.

The plugin registers Kraft's MCP server with Claude Code and adds the /kraft:* skills. You do not need kraft admin init as well. To check that it worked, run /kraft:board: it lists the board for the repo you are in.

claude plugin update kraft picks up new skills. claude plugin uninstall kraft removes them.

To use plain files instead of a managed plugin, see Set up without the plugin.

Codex installs the same plugin from the same marketplace:

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

The plugin registers Kraft's MCP server (codex mcp list shows kraft) and adds the Kraft skills. Start a new Codex session to load them. /skills lists them as kraft:board, kraft:handoff and so on. Type $ to pick one, or describe the task and let Codex choose. codex plugin remove kraft@kraft uninstalls it.

Without the plugin, register the server alone:

codex mcp add kraft -- kraft admin mcp

This writes the server to ~/.codex/config.toml:

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

To register it for one repo only, put the same table in that repo's .codex/config.toml instead. codex mcp list shows it.

Cursor's CLI (agent) has no command that adds a server. Add it to ~/.cursor/mcp.json for every project, or to .cursor/mcp.json in one repo:

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

The CLI loads a new server only once you approve it. Until then, agent mcp list shows kraft: not loaded (needs approval). Approve it with:

agent mcp enable kraft

The Cursor editor reads the same file.

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

--global writes your user config. Without it, the server goes into opencode.json in the current directory, for that project only. opencode mcp list shows kraft connected once OpenCode can start it.

amp mcp add kraft -- kraft admin mcp

This writes amp.mcpServers in ~/.config/amp/settings.json. With --workspace it writes the repo's .amp/settings.json instead, and Amp runs a workspace server only after you approve it: amp mcp approve kraft. amp mcp list shows it.

gemini mcp add --scope user kraft kraft admin mcp

--scope user writes ~/.gemini/settings.json. Without it, Gemini CLI writes the project's .gemini/settings.json, and connects a project's servers only in a folder you have trusted. gemini mcp list shows it.

Kraft's skills reach Claude Code and Codex, through the plugin. A plugin for Cursor, OpenCode, Amp or Gemini CLI isn't shipped yet. In those agents, ask for what you want in plain words ("what is waiting on me in Kraft?") and the agent calls the MCP tools.

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          # for every repo you open
kraft admin init --repo   # for this repo only

The first registers Kraft with Claude Code for your user (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 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.

To check a Claude Code setup, the plugin included, run kraft admin doctor. Its mcp server row passes once Kraft is registered, and names the permission tool Claude workers will use. For another agent, use the list command in its tab.

Run workers on your agent

Registering Kraft with an agent lets you drive Kraft from it. Which agent CLI runs a work item's tasks is a separate choice, made per task in your templates: every shipped task runs on Claude Code, and Switch a task to another harness moves tasks to another. Kraft calls that CLI a harness.

A worker runs headless, with nobody to answer a login prompt, and its environment is an allowlist: a variable reaches it only when the repo's env_passthrough in repos.yaml names it. What each harness needs:

Registration. Required. An unsandboxed Claude worker asks Kraft's permission gate through the kraft MCP server, and Kraft refuses to launch one when nothing registers it. The plugin, kraft admin init, or a committed .mcp.json each count.
Login. Your normal claude login works. ANTHROPIC_API_KEY and CLAUDE_CODE_OAUTH_TOKEN reach the worker without env_passthrough.

Registration. None. When a task's policy needs Kraft's permission hook, Kraft passes it on that launch's command line and trusts it for that launch only.
Login. Sign in with codex login; the login under your home directory reaches the worker. With an API key, name CODEX_API_KEY in env_passthrough, not OPENAI_API_KEY, which codex exec does not send.

Registration. None. When a task's policy needs Kraft's permission hook, Kraft installs it in the worktree.
Login. agent login keeps the login in the OS keychain, which a worker reaches unless it is sandboxed. With an API key, name CURSOR_API_KEY in env_passthrough. See Set up Amp or Cursor credentials.

Registration. None. When a task's policy sets tool rules, Kraft writes them into that launch's own OpenCode config.
Version. OpenCode 2.0.0 or newer. Kraft refuses to launch an older one, including npm's 1.x opencode-ai.
Login. Log in to your provider with opencode auth. A provider key read from the environment needs its variable in env_passthrough.

Registration. None. When a task's policy sets tool rules, Kraft writes them into a settings file of that launch's own.
Login. amp login works on the machine where you ran it. Otherwise name AMP_API_KEY in env_passthrough. See Set up Amp or Cursor credentials.

Registration. None. Gemini CLI takes no tool policy: Kraft refuses a task on it whose policy sets deny_tools or allowed_tools. It runs in its yolo approval mode unless the task sets another.
Login. Your normal gemini login works. With an API key, name GEMINI_API_KEY in env_passthrough.

What each harness can and cannot do is in the harness table. To add an agent CLI Kraft does not ship, see Add or override a harness.

The skills

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

Skill	Use it to
`/kraft:onboard`	Connect the repo you are in and check its setup and test commands.
`/kraft:board`	See what is running, blocked, or waiting on a person, or search specs and plans.
`/kraft:prepare`	Write a spec (and a plan, if you ask), then decide whether the work runs in this session or in Kraft.
`/kraft:handoff`	File work with Kraft, with any agreed spec and plan attached.
`/kraft:status`	Report where a work item has got to, or watch it until it ends.
`/kraft:gates`	Approve or reject the gate a work item is waiting on, leave review threads and submit a review, or pause and resume it.
`/kraft:review`	Read what a gate is about and recommend approve or reject, with reasons, drafted as review threads where they are about specific lines. It acts only once you answer.
`/kraft:steer`	Redirect a work item that is heading the wrong way.
`/kraft:triage`	Find out why a work item stopped, and retry it, raise a cap, or hand it to you.
`/kraft:check`	Report where a repo's Kraft config has drifted from this Kraft version.
`/kraft:doctor`	Diagnose an unhealthy Kraft server and fix what it can.

What an agent cannot do

An agent cannot file work and start it in one step. Everything an agent creates lands paused, and the board shows it as Not started with a single Start button. Nothing spends tokens until a person starts it, either by clicking that button or by asking your agent to resume the item (/kraft:gates).

A worker cannot act on itself. An agent session that Kraft started cannot approve, reject, pause, resume, retry, or abandon its own work item. Kraft refuses the request. A gate is where a human decides; an agent approving its own would make the gate pointless.

MCP tools

An agent without the skills calls the MCP tools kraft admin mcp serves: list_work_items and get_work_item to read the board, create_work_item to file work, approve_gate and reject_gate to decide a gate, and so on. MCP tools lists every tool, its parameters, and the kraft command that does the same, so a hook or an agent without MCP gets the same surface from the command line.

Without the Kraft server

Kraft Lite runs a chain inside a single agent session with no server and no MCP server.

Edit this pageorReport an issue

Overview

Task-focused how-tos for driving, extending, and reaching Kraft.

Kraft Lite

The Kraft Lite plugin, which runs a chain inside one agent session with no service, and its slash commands.