Claude Code
Claude Code has a shell, so it works best through the runbook CLI, guided
by the therunbook skill. The MCP server is there for sessions without the
CLI.
With the CLI and the skill (recommended)
Section titled “With the CLI and the skill (recommended)”-
Install the CLI and sign it in to your server:
Terminal window curl -fsSL https://github.com/angler-ai/the-runbook-app/releases/latest/download/install.sh | shrunbook login https://runbooks.example.comInstalling the CLI has the other ways, such as building from source.
runbook loginopens the browser to approve the CLI and stores a personal access token for that host (in the macOS Keychain or Windows Credential Manager, otherwise a0600file). -
Install the skill. It teaches Claude the agent loop, when to ask a person, and how to treat runbook data:
Terminal window runbook skill install --therunbookThat writes
~/.claude/skills/therunbook/, and the same skill for Codex and Cursor if they are set up on this machine (--agent claudelimits it to Claude Code). Add--scope projectto install it into this repository’s.claude/skills/instead, so everyone who works here gets it. Run it again after upgrading the CLI to update the skill. -
Give the agent its own credential. Claude acting on your login is recorded as you. For agent work, mint an agent-kind token and hand it to the session:
Terminal window runbook token create --agent --name claude-code --expires-in 30d \--scope runbooks:read --scope executions:read --scope executions:act --jsonPut the printed secret in
RUNBOOK_TOKENfor the Claude Code session (for example in a.envyour shell loads). The token can do no more than you can, and never decides human approvals. For a single run, an execution pair is narrower still. -
Try it. In Claude Code:
Work the next agent step of run exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7.The skill makes Claude check
runbook whoami --json, then run the loop with--json. More prompts are in the prompt library.
Over MCP
Section titled “Over MCP”The CLI serves MCP over stdio with its own stored credentials:
claude mcp add runbook -- runbook mcp serveThis uses the CLI’s current context (runbook context use …). Like the
step commands, it never acts with your own runbook login: give it the
agent token from step 3 in RUNBOOK_TOKEN (or a stored execution pair from
runbook run token).
Your server answers MCP at /mcp (Streamable HTTP). Add it and sign in from
Claude Code:
claude mcp add --transport http runbook https://runbooks.example.com/mcpThen run /mcp in Claude Code and choose Authenticate. Claude Code
registers itself with your server, you sign in with an email code and tick
the scopes it may use on the consent page (runbooks:publish is off unless
you tick it). The grant is recorded as an agent you sponsor, so its work is
never mistaken for yours.
See and disconnect connected clients with runbook apps list and
runbook apps revoke <client>.
Without sign-in configured on the server, or for an agent-kind token you minted, send the token as a header:
claude mcp add --transport http runbook https://runbooks.example.com/mcp \ --header "Authorization: Bearer $RUNBOOK_TOKEN"The plugin
Section titled “The plugin”The skill and the stdio MCP server also come as a Claude Code plugin, from this repository’s marketplace. In Claude Code:
/plugin install therunbook --marketplace angler-ai/the-runbook-appClaude Code before 2.1.275 needs two steps:
/plugin marketplace add angler-ai/the-runbook-app, then
/plugin install therunbook@the-runbook.
It contains the same therunbook skill as runbook skill install and an
.mcp.json that runs runbook mcp serve, so it needs the CLI installed and
an agent token in RUNBOOK_TOKEN. /plugin marketplace update the-runbook picks up new versions.
The plugin lives in plugins/claude-code/.
Running Claude Code unattended
Section titled “Running Claude Code unattended”To have runs start Claude Code on their own, subscribe a launcher to
agent.work_available and run Claude Code headless there with an execution
pair. Your own agent shows the
launcher; the command it runs is:
claude -p "Work every ready agent step of run $EXE, then stop." \ --allowedTools "Bash(runbook:*)"