catherd

 /\_/\  .  catherd
(=^.^=)/   herds coding agents
 (")(")

Autopilot builds from your own Claude Code session. Claude plans and verifies, Codex, opencode or
headless Claude Code workers write the code, and Jev picks the model and effort for each piece
of work, climbing a ladder only when a cheaper rung falls short.

• 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.
• Claude roles stay native. claude: rungs run as ordinary Claude Code subagents; Codex,
  opencode and headless claude-code: rungs run through catherd's MCP server.
• Survives restarts. Workers are detached processes writing straight to disk, so a dropped
  MCP server never loses a run.
• Guard rails for autopilot. Quota failover to a rung on another quota, a preflight check before any
  worker starts, per-repo knowledge carried between runs, and a run budget.

Requirements

• Bun ≥ 1.4
• Claude Code (desktop app or CLI)
• At least one worker backend, logged in:
  • Codex CLI 0.157.0 or newer
  • opencode v2, 2.0.16 or newer: curl -fsSL https://opencode.ai/v2/install | bash
    (the npm package opencode-ai is v1 and is not supported)
  • Claude Code's claude CLI 2.1.282 or newer, for headless claude-code: rungs
• Optional: a TypeSafe API key for Jev, in TYPESAFE_API_KEY or saved by catherd init

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 in Claude Code, or catherd profile set roles.<role>.rungs <rung>).

Install

bunx catherd-cli init

The npm package is catherd-cli; the command it installs is catherd. init asks for the optional Jev key,
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 Jev key, the profile, 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
bunx catherd-cli doctor.

Use

In Claude Code:

• /catherd <task> runs a task on autopilot; /catherd alone resumes the latest run.
• /catherd-setup tunes your profile in conversation: which models and efforts each role may
  use, cost or speed, isolation, budget and failover.

In a terminal:

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. Run them as
bunx catherd-cli <command> when catherd is not installed globally. Every read command takes --json; a bare catherd runs is catherd runs list. Exit codes: 0 ok, 1 error, 2 usage, 3 not ready, 130 interrupted; an error prints
error E_CODE: message and a fix: line. --verbose (or CATHERD_LOG=debug) logs more to
~/.local/share/catherd/logs/, kept for 7 days with secrets redacted. The dashboard takes --plain (ASCII, no colour)
and --reduced-motion; doctor and init take --plain for ASCII glyphs too. NO_COLOR drops colour, never glyphs.

Run data lives in ~/.local/share/catherd/, config in ~/.config/catherd/ (both follow
XDG_*).

Environment variables

For development only: CATHERD_STORY=1 opens the dashboard's storybook, and CATHERD_LIVE=1 enables the live
tests (CONTRIBUTING.md has the rest).

The dashboard

catherd opens three tabs: 1 Status (every check with its fix; y copies the fix, r checks again),
2 Profiles (one tree per profile: roles with their access, default rung, models and efforts, then routing,
harness, budget, failover, timeouts and notify) and 3 Runs (the Claude Code sessions that drove your runs, newest
first; a session opens on its runs, their milestones and every role with its rung, status, time and last event, live
ones first; a role opens on its brief, reply and record; the open screen redraws as run files change; esc goes back,
p pauses). catherd watch opens it on Runs.

• ctrl+p lists every command with its key and CLI twin; ? lists the keys that work where you are.
• ctrl+x is the leader: ctrl+x 1–3 tabs, ctrl+x n new profile, ctrl+x l profiles, ctrl+x u and
  ctrl+x r undo and redo, ctrl+x q quit.
• Lists: arrows or j/k, pgup/pgdn, home/g, end/G, / to filter; space ticks, enter
  changes or opens, →/← expand and collapse.
• Edits are staged: nothing is written until ctrl+s shows the diff and you choose Save or Save & make active.
  enter never saves.
• Inside a repo bound to a profile, the dashboard opens on that profile, and making a profile active binds the
  repo to it (as catherd profile use <name> --repo).
• esc backs out one level and never quits. q quits, asking first if something is unsaved; ctrl+c quits
  when nothing is, and pressed twice within 1.5 s discards and exits 130.
• Deleting a profile or cancelling a live role takes ctrl+d twice.
• --plain draws ASCII without colour, NO_COLOR drops the colour, --reduced-motion stops the spinner.
• Rebind a key in ~/.config/catherd/config.json: "keybinds": { "profile.save": "ctrl+w", "app.help": "none" }
  (the palette shows each command by title; the ids are listed in
  src/entry/tui/commands.ts).

Upgrading from 0.x

1.0 is a clean break: run bunx catherd-cli init once. It moves your 0.x config.json, projects.json and
profiles into a 0.x-backup-<time>/ folder next to them (it never reads or deletes them), writes the 1.0
default profile, replaces the 0.x Claude agent links with 1.0 ones and keeps your saved Jev key; 0.x run
folders stay where they are, unread. Then update the plugin
(claude plugin marketplace update catherd && claude plugin update catherd@catherd) and start a new Claude
Code session. The details are in MIGRATION.md.

Docs

Contributing

See CONTRIBUTING.md. CI runs the checks on Linux and macOS, on Bun 1.4.0 and the latest Bun;
what CI cannot run is in docs/dev/live-verification.md. Report security issues
privately, as SECURITY.md describes. Everyone taking part follows the
Code of Conduct.

License

MIT