/\_/\ . catherd
(=^.^=)/ herds coding agents
(")(")
Autopilot builds from your own Claude Code or native Codex session. Your profile routes the architect, verifier and workers to their backends; Codex, opencode or headless Claude Code processes write the code, and the architect picks the model and effort for each dispatch from each role's ladder.
- Your harness, as you set it up. Every role runs in its vendor's own CLI with your config,
hooks, skills and
AGENTS.md. Isolation is an opt-in toggle per profile and harness, for when you'd rather save the tokens your customizations cost. - A daemon drives the run.
run_startlaunches a detached daemon that plans, dispatches, reviews, verifies and lands each milestone from the run's event log in catherd's database. Every role runs headless in its vendor's CLI (Claude Code, Codex, opencode); the session needs none of it once the run has started, and a dropped session or MCP server never loses a run. - Questions reach your phone. A parked question and the final report are sent to your ntfy topic
(
notify.url), and answered from the session (answer) or the terminal (catherd answer). - A protocol the daemon enforces. Every lane implements its plan tasks as written, and every role, whatever vendor runs it, gets its role's text and ends with the reply contract, and a milestone lands only after a reviewer and a verifier passed it. The architect decides what no rule can (an ambiguous finding, a stuck fix round, an unmet check) from the run's facts. An owner question parks one task, not the run.
- Guard rails for autopilot. Quota failover to an indexed stand-in at least as intelligent, a preflight check before any worker starts, per-repo knowledge carried between runs, and a run budget.
Requirements
- Bun ≥ 1.4
- An orchestration host: Claude Code, or native Codex CLI/Desktop with plugin support and the existing native queue endpoint (installed CLI 0.159.2 verified for packaging; queue support is feature-detected)
- At least one worker backend, logged in:
- Optional: gitleaks (
brew install gitleaks): catherd's milestone check scans the commits of a milestone with it for a leaked secret; without it the scan is skipped and the record says so
catherd doctor checks each backend's version and login and prints the fix for anything missing. The default
profile runs its workers on Codex; without Codex, doctor's fix also names how to move those roles to a backend
you have (/catherd-setup, or catherd profile set roles.<role>.rungs <rung> --host <codex|claude-code>). Codex-only setup does not require or configure Claude; enabled selected roles and reachable failover decide optional dependencies. Doctor sends nothing by default; --test-push is an explicit smoke send from a validated host session (--thread <uuid> names the Codex thread from a shell).
Install
catherd runs from Claude Code or, since 1.4, from native Codex; one global catherd and one plugin version serve both. To check a packaged build before you rely on it, follow the local packaged acceptance procedure; a matching version alone does not prove that the feature core ran.
Channels: catherd-cli@latest is the stable release. catherd-cli@next and the plugin-next marketplace carry
every merge to main before it is stable (CONTRIBUTING.md, "Next channel"). catherd-cli@1 is the 1.x line, which receives
bug fixes only (CONTRIBUTING.md, "Maintenance line (1.x)").
Claude Code
bun add -g catherd-cli
catherd init --host claude-code
The npm package is catherd-cli; the command it installs is catherd. bunx catherd-cli init --host claude-code
works too (a terminal with no host evidence cannot pick the architect/verifier defaults, so name the host): init
installs the global command at its own version (--no-global skips it) and says installing catherd… before
it does, though the first bunx resolve itself prints nothing for up to half a minute: bunx fetches the
package before catherd's first line, so bun add -g catherd-cli first is the quicker start. init fetches the
Slopalytics index, writes the default
profile and links its Claude agents, lists your backends' models, and ends with a readiness report (--no-input
asks nothing and keeps what exists; --profile <name> sets up and activates that profile instead of default;
piped, it reads one answer per line once stdin closes: the profile and whether to replace it, each on its own line
even when a question is skipped). Then add the plugin to
Claude Code:
claude plugin marketplace add 47vigen/catherd
claude plugin install catherd@catherd
Start a new Claude Code session so the plugin, its MCP server and the agent files load, then check with
catherd doctor --host claude-code. From inside that session, explicit catherd doctor --test-push sends a labeled smoke notice; inspect actual processing separately from transport acceptance.
Native Codex
bun add -g catherd-cli
catherd init --host codex
codex plugin marketplace add 47vigen/catherd
codex plugin add catherd@catherd
codex mcp list --json
Restart the Codex host to load the installed shared skills and server. Native CLI accepts owner/repo[@ref] and a local marketplace path. The supported marketplace uses .claude-plugin/marketplace.json with its plugin subdirectory; the native manifest is plugin/.codex-plugin/plugin.json, with skills: "./skills/" and mcpServers: "./.mcp-codex.json". Installed native resolution supplies command: "sh", args: ["./bin/catherd-mcp"], cwd: <installed plugin root> and CATHERD_ORCHESTRATION_HOST=codex. No Claude root macro or synthetic session ID belongs in that declaration. The shared launcher/core remains versioned together with both manifests.
Pass the actual project repo to repository-aware MCP profile/setup/catalog calls, because the server cwd is the plugin root. run_start(repo, ...) already requires it. Terminal init and doctor accept --host codex|claude-code|auto; selecting a terminal host chooses setup checks without inventing a conversation owner.
Use
In either supported host, use the installed shared skills through that host's skill invocation and tool discovery:
/catherd <task>runs a task on autopilot;/catherdalone resumes the latest run. While it runs, keep talking: a report arrives through the host's transport and on your phone, and "how is it going?" gets astatus./catherd-setuptunes your profile in conversation: which models and efforts each role may use, isolation, budget and failover.
A session sees six tools:
| Tool | What it does |
|---|---|
run_start(repo, title, a_lines, plan?, base?) |
Starts a run and returns its id and the notify url its questions go to |
status(run?) |
Phase, milestones, live roles, parked questions, quota holds and whether the daemon is alive |
answer(run, unit, answer) |
Answers a parked unit (the run, a milestone or a lane); it runs again with the answer |
cancel(run) |
Stops the run and every live role |
result(run, name?) |
The run's report (the merge request body), or one role's record |
profile(action, …) |
Reads, validates or changes a profile, or sets notify_url |
Set where questions go once: notify.url is an ntfy topic url (catherd-setup, or the profile
tool's notify_url). The daemon sends to it from your machine, so a question and the final report reach the phone
with no session open. If notify.url is unset, run_start makes a random, unlisted topic on the public ntfy.sh and
sends questions there; set notify.url to your own ntfy server for privacy. Omitted Codex architect/verifier choices are exactly codex:gpt-6.1-sol#high /
codex:gpt-6.1-sol#low; omitted Claude choices retain their existing defaults, and a claude: rung runs as its
headless claude-code: twin. To opt into host defaults, review and save the narrow reset:
catherd profile reset-host-defaults <profile> --host codex --preview --json > /tmp/catherd-host-defaults-review.json
# Review the diff, effective defaults, errors and warnings.
catherd profile reset-host-defaults <profile> --host codex --expect /tmp/catherd-host-defaults-review.json --json
It removes only architect/verifier rungs and defaultRung; every other setting stays intact. Run profile CLI commands from the project directory and choose the actual profile name. Use --host claude-code for Claude defaults.
A run's reports reach the session that started it (Claude Code's peer inbox, Codex's queued next input) and the phone.
status revives a daemon that died, so asking "how is it going?" is always safe. Roles get catherd's tools too:
headless Codex and Claude Code roles get a catherd_role MCP server, and other roles run
catherd run-file read|write <run> <path>, catherd team and catherd call from their shell, bound to their own
run and role (anything else is E_ROLE_SCOPE). run_start, answer, cancel, result and profile are the owner's: a role's process gets
E_ROLE_SCOPE for them, so a role can never take the run over.
In a terminal:
| Command | What it does |
|---|---|
catherd, catherd panel [--port <n>] [--no-open] |
The panel in your browser on 127.0.0.1: Setup, Runs and Questions; a fresh token each start; catherd --help for the commands |
catherd init [--host codex|claude-code|auto] [--no-input] [--no-global] [--profile <p>] |
First-run setup; installs the global catherd at its own version unless --no-global |
catherd doctor [--host codex|claude-code|auto] [--test-push [--thread <uuid>]] [--docker] [--json] |
Readiness and capability report; no send unless explicit smoke; --docker probes a compose network and the Docker disk; exits 3 when not ready |
catherd profile list|show|use [--repo]|new [--from <p>]|copy|rm|diff|validate |
Profiles; use --repo binds one to the repo you are in |
catherd profile use --repo --clear |
Unbinds the repo you are in; it runs on the active profile again |
catherd profile set <path> <value> [--profile <p>] |
One field, e.g. roles.verifier.access read-only, roles.worker.network false, budget.usd 20 |
catherd status [run], catherd watch [--once] [--interval <s>] |
Where runs stand, grouped by host and session; read-only ownership |
catherd runs list [--repo <path>]|show <id> [--debug [--name <n>]]|cancel <id> <name> |
Past runs, by session; --debug adds exit.json and the stderr and event tails, --name one role's |
catherd runs metrics [<id>] |
Where each run's time went (idle, concurrency, blocked, checks, rounds) and each reviewer rung's findings and misses |
catherd runs clean [<id>] |
Removes the roles' scratch folders (each role's $TMPDIR) of runs with no live role |
catherd catalog refresh|list [--backend <b>] [--role <r>] [--text <t>] [--older] |
The models catherd can place, with their indexed pairs; --older adds the ones a newer version replaces |
catherd catalog sync [--force] |
Fetches the Slopalytics index now (below); it is refreshed at most hourly otherwise |
catherd knowledge show [--role <role>]|add "<line>"|rm "<text>"|path [--repo <path>] |
The repo's knowledge.md, keyed by its git origin (its toplevel when it has none), which new runs read; add appends a fact of yours, marked "by hand"; a [role, …] tag after the source scopes a line to those roles' briefs; rm removes the one line the text matches |
catherd knowledge env set NAME=value|NAME --from VAR, env rm NAME, env list |
The repo's gate environment, which the verifier and preflight run with; a secret by reference only |
catherd runs supersede <id> --by <id>, catherd runs pin <id> |
Closes a run with a pointer to the one that took over; re-pins a run to the repo's profile now |
catherd pause --machine|--workspace <id> "<reason>", catherd resume --machine|--workspace <id> |
Pauses every run on the machine (or in a workspace) on one blocker; dispatch is refused until resume |
catherd lock [--slots N] -- <cmd> |
Runs a heavy command behind the machine-wide semaphore, in its own session (no /dev/tty) |
catherd run-file read|write <run> <path> |
A run's plan, lanes and notes (write reads stdin); in a role, its own run only |
catherd answer <run> <unit> <text> |
Answers a parked unit from the terminal, as the answer tool does; the daemon picks it up |
catherd mcp |
The MCP server on stdio; the plugin starts it, you never need to |
catherd capture-fixtures [--backend <b>] [--out <dir>] |
Contributors: records sanitized test fixtures from real runs (see CONTRIBUTING.md) |
catherd scorecard prepare <task>, record <dir> --label <l>, compare <label>, stage <label> --baseline <l> |
Contributors: measures a catherd version on four fixed tasks against the 1.5.0 baseline (docs/dev/scorecard.md) |
A profile command without a profile name (show, set, diff, validate), like the MCP profile tools, acts
on the profile the repo you are in runs on: the one bound to it, else the active one. Pass repo explicitly to MCP tools; profile CLI commands accept --host for effective defaults. Run them as
bunx catherd-cli <command> when catherd is not ins
