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.
- step nextReady workThe server says which agent steps are ready
- step claimClaimA lease on one step, kept alive by heartbeats
- step getRead and doInstructions, inputs, skill files
- 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.
Two ways to connect
Section titled “Two ways to connect”| 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.
Credentials: the agent is never a person
Section titled “Credentials: the agent is never a person”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.
Set up your agent
Section titled “Set up your agent”The skill, for any agent
Section titled “The skill, for any agent”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) |
Telling agents there’s work
Section titled “Telling agents there’s work”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.