Skip to content

Codex

Codex runs shell commands, so it works best through the runbook CLI, guided by the therunbook skill.

  1. Install the CLI and sign in:

    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.

  2. Install the skill where Codex reads skills:

    Terminal window
    runbook skill install --agent codex --therunbook

    Without --agent, it installs for every agent set up on this machine (Claude Code, Codex, Cursor). Run it again after upgrading the CLI.

    That writes ~/.agents/skills/therunbook/; --scope project writes .agents/skills/therunbook/ in this repository instead.

  3. Give Codex its own credential, an agent-kind token, so its work is recorded as an agent’s and it can’t decide human approvals:

    Terminal window
    runbook token create --agent --name codex --expires-in 30d \
    --scope runbooks:read --scope executions:read --scope executions:act --json

    Export the secret as RUNBOOK_TOKEN in the environment Codex runs in.

  4. Try it:

    Terminal window
    codex "Work the next agent step of run exe_01JD2X6PZ5R8E2W4Y6A0C3D5F7."
~/.codex/config.toml
[mcp_servers.runbook]
command = "runbook"
args = ["mcp", "serve"]

The server uses the CLI’s current context. It never acts with your own runbook login: it needs the agent token from step 3 in RUNBOOK_TOKEN in Codex’s environment.

codex exec runs one task headless, which is what a launcher needs:

Terminal window
codex exec "Work every ready agent step of run $EXE, then stop."

See Your own agent for the launcher that starts it when work is available.