pilotfish – Orchestration policy for Claude Code

What it is

pilotfish is a policy package that adds a multi‑model orchestration layer to Claude Code, the AI‑powered coding assistant from Anthropic. It defines a set of lightweight “role agents” (e.g., scout, mech‑executor, security‑reviewer) and a dispatch policy that automatically routes parts of a coding session to the most cost‑effective model while keeping a central “main session” (the Opus family) responsible for high‑level planning and final judgment.

Why it exists

Typical Claude Code sessions spend many tokens on repetitive, low‑risk work (search, formatting, test scaffolding). pilotfish splits those bounded tasks to cheaper models (Haiku, Sonnet) and only uses the more expensive Opus models for planning, security review, and verification, reducing token cost without sacrificing oversight.

How it works

• Roles – pre‑defined agent files (~/.claude/agents/*.md) each bound to a specific model and effort level (low/medium/high).
• Policy – a CLAUDE.md block that decides, based on the interaction shape (co_discover, explore_then_plan, execute) and the task’s difficulty, which role to invoke.
• Dispatch flow – the main session (Opus) orchestrates, may call a scout for repository reconnaissance, a mech‑executor for mechanical code generation, an executor for judgment‑heavy implementation, and a verifier (fresh Opus context) to falsify outcomes. Security‑related work passes through a read‑only reviewer and a medium‑effort executor.
• Effort levels – the policy respects Claude Code’s CLAUDE_CODE_EFFORT_LEVEL override; otherwise it selects effort per role (e.g., scout = low, plan‑verifier = medium, security‑reviewer = high).

Installation options

1. Plugin (macOS / Linux) – native marketplace install via install/PLUGIN-INSTALL.md. Adds the policy as a hook‑based plugin; requires Claude Code 2.1.219+ and Ubuntu 20.04+/Debian 10+/Alpine 3.19+ for Linux.
2. Legacy global install – clone a tagged release (e.g., v1.5.0) and run Claude Code with a run‑book that writes the policy files into ~/.claude/. The installer is idempotent and shows a merge plan before any changes.

Operating the system

• Use the provided CLI wrapper (/pilotfish) or the Plugin UI to enable the policy for a session.
• Adjust model aliases, effort thresholds, or enable/disable delegation via docs/usage.md.
• All changes are reversible; the installer can uninstall the eight role files and the policy block.

Documentation & evidence

• Detailed design (docs/design.md), research on model economics (docs/research.md), and field‑report logs are included.
• Benchmarks (dispatch‑brake, spontaneous‑dispatch, baton‑activation, prompt‑compression, verifier‑boundary) provide empirical limits on how often delegation occurs and its token impact.

Who should use it

• Developers who rely on Claude Code for large coding sessions and want to lower token cost while preserving safety checks.
• Teams that need structured security review and verification steps baked into the AI workflow.
• Power users comfortable editing Claude Code configuration files and managing plugin installations on macOS or Linux.

Maturity

• MIT‑licensed, with a versioned release history and changelog.
• Claims about behavioral compatibility are backed by paid model runs; ongoing sponsorship funds further verification.
• Windows is not supported; Linux support is “contract‑qualified” (tested but not officially verified).

---

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