Skip to content

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.

  1. 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 | sh
    runbook login https://runbooks.example.com

    Installing the CLI has the other ways, such as building from source.

    runbook login opens the browser to approve the CLI and stores a personal access token for that host (in the macOS Keychain or Windows Credential Manager, otherwise a 0600 file).

  2. 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 --therunbook

    That writes ~/.claude/skills/therunbook/, and the same skill for Codex and Cursor if they are set up on this machine (--agent claude limits it to Claude Code). Add --scope project to 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.

  3. 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 --json

    Put the printed secret in RUNBOOK_TOKEN for the Claude Code session (for example in a .env your 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.

  4. 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.

The CLI serves MCP over stdio with its own stored credentials:

Terminal window
claude mcp add runbook -- runbook mcp serve

This 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).

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-app

Claude 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/.

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:

Terminal window
claude -p "Work every ready agent step of run $EXE, then stop." \
--allowedTools "Bash(runbook:*)"