Nanako0129/pilotfish

pilotfish – Orchestrating Claude Code agents

What it is

• A policy package that lets Claude Code (Anthropic’s coding‑assistant) split a programming session into several lightweight “role agents”.
• Each role runs on a different Claude model (Opus, Sonnet, Haiku) chosen for cost and capability, so the main session can focus on high‑level planning and judgment while cheaper models handle repetitive or low‑risk work.

Why it matters

• In long coding sessions most tokens are spent on searching, refactoring, testing, and documentation rather than on the core design decisions.
• pilotfish automatically routes those bounded tasks to cheaper models, reducing token cost and keeping the main model free for frontier reasoning and final approval.

How it works

1. Installation – either a Plugin (macOS/Linux) that hooks into Claude Code’s native plugin lifecycle, or a legacy global install that writes files under ~/.claude/ (or a custom CLAUDE_CONFIG_DIR).
2. Policy files –
   • settings.json defines the main‑model alias (Opus family) and a fallback chain.
   • agents/*.md describe each role (e.g., scout, mech-executor, security‑reviewer).
   • CLAUDE.md contains the dispatch logic that decides when to keep work in the main session and when to delegate to a role.
3. Dispatch flow – When you interact with Claude, pilotfish examines the interaction shape (e.g., co_discover, explore_then_plan, execute). Depending on the shape it may:
   • Call a low‑effort scout (Haiku) for repository reconnaissance.
   • Use a plan‑verifier (Opus) to challenge a proposed plan.
   • Hand off mechanical repetition to a mech‑executor (Sonnet) or higher‑risk code to an executor (Sonnet) after approval.
   • Run a verifier (fresh Opus context) after implementation to falsify the outcome.
   • Route security‑sensitive work through a security‑reviewer and security‑executor (both Opus, read‑only then high‑effort).
4. The policy is expressed in a markdown block (pilotfish:begin/end) inside CLAUDE.md; Claude reads it each session, so the behavior is applied automatically.

Installation steps (summary)

• Plugin beta – follow install/PLUGIN-INSTALL.md; works on macOS (Claude Code 2.1.239) and Linux (Ubuntu 20.04+, Debian 10+, Alpine 3.19+). Requires Claude Code 2.1.219+. The plugin must be the only install (cannot coexist with the legacy global install).
• Legacy global – clone the repo at a tagged release, run claude and ask it to follow the runbook in install/AGENT-INSTALL.md. The installer shows a merge plan, backs up existing files, and is idempotent.

Operating the system

• Enable/disable or update the plugin via the same install guide.
• Tune model choices, effort levels, or delegation rules in docs/usage.md.
• To activate pilotfish for a session, run the provided /pilotfish command or the CLI wrapper described in install/ACTIVATION-INSTALL.md.
• Uninstall safely by asking Claude to execute the uninstall runbook, which removes the eight agent files and the policy block.

Evidence & research

• The repo includes design notes, economic analysis, and field‑report documents (docs/design.md, docs/research.md).
• Benchmarks such as spontaneous‑dispatch and dispatch‑brake provide behavioral observations of how often delegation occurs.

Who might use it

• Developers who spend many hours in Claude Code and want to lower token costs.
• Teams that need a reproducible, policy‑driven way to separate low‑risk automation from high‑risk judgment.
• Researchers interested in multi‑model orchestration and risk‑aware AI assistance.

License & support

• MIT licensed.
• The author invites sponsorship via Patreon to fund paid‑model verification runs.

---

All details are taken directly from the repository’s README; no additional features are inferred.