Skip to content

Agents

An agent works a run’s steps the way a person does: it picks up a step that is ready for it, does the work the step describes, and reports what it found. The server decides what is ready, who may do it, and what a report must contain. The agent never decides that for itself.

  1. step nextReady workThe server says which agent steps are ready
  2. step claimClaimA lease on one step, kept alive by heartbeats
  3. step getRead and doInstructions, inputs, skill files
  4. step reportReportStatus, verdict, outputs, evidence

Repeat until the brief says wait or exit.

The loop is the same however the agent connects. The agent loop explains it step by step.

The CLI MCP
For Agents with a shell: Claude Code, Codex, Cursor’s agent, CI jobs, scripts Clients that speak MCP, including ones with no shell, such as Claude and ChatGPT
How runbook … --json commands runbook mcp serve over stdio, or /mcp on your server
Credentials Kept by the CLI, out of the agent’s context, refreshed for it stdio: the CLI’s; remote: OAuth sign-in or a bearer token
Long commands runbook step exec runs a command under the step’s lease The agent heartbeats itself

Both expose the same operations (CLI, MCP tools). Prefer the CLI when the agent has a shell: it keeps tokens out of the model’s context. The therunbook skill tells an agent exactly this, and how to work the loop.

The server tells people and agents apart by the kind of credential, not by anything the caller says. Give an agent one of these, never a person’s token:

  • an execution pair (runbook run token <exe>), minted by a launcher with a service token: it reaches one run only, lasts an hour and refreshes, and is revoked when the run ends;
  • an agent-kind token (runbook token create --agent): an agent sponsored by you, with scopes you choose;
  • over remote MCP, an OAuth grant: the client signs in as you, and the server records it as an agent you sponsor, with the scopes you ticked.

The therunbook skill is a plain Agent Skills folder, so any agent that reads skills can use it:

Agent Install
Claude Code, Codex, Cursor runbook skill install --therunbook (every one set up on this machine)
Claude Code, as a plugin /plugin install therunbook --marketplace angler-ai/the-runbook-app
Other agents (Gemini CLI, GitHub Copilot, Windsurf, …) npx skills add angler-ai/the-runbook-app
Claude and ChatGPT apps upload therunbook-skill.zip (how)

An agent doesn’t need to poll. Subscribe a webhook to agent.work_available: it fires when agent steps become ready (a run started, an approval was decided, a wait ended, a lease lapsed), with the ready steps and the runbook’s spec.agents.params. A small launcher then mints an execution pair and starts the agent, as in the GitHub Actions recipe.

Then give your agent something to do: the prompt library has ready-to-paste prompts.