Repo of the day: pilotfish, multi-model orchestration for Claude Code

🔍 What pilotfish is

pilotfish is a multi-model orchestration layer for Claude Code: not an external tool, not a router intercepting calls, but a global configuration living under ~/.claude/ that redesigns who does what. The name comes from the pilot fish, which swims alongside the ocean's largest predators doing the routine work: here the main session runs on the opus family and delegates the volume to Sonnet and Haiku through subagents with explicit roles.

The project's origin story is almost comical, and the author tells it himself in the README: one morning his weekly quota had evaporated, and the first thing he did with the fresh Fable 5 allowance was ask it to investigate where the previous week's had gone. The answer — most tokens go into searching, mechanical edits and test runs, not judgment — became this configuration: three files, zero runtime code, idempotent install across every project.

repo       Nanako0129/pilotfish
what       multi-model orchestration for Claude Code: the frontier plans,
           Sonnet/Haiku execute, fresh-context Opus verifiers check
how        3 config files under ~/.claude/ · 8 subagent roles · zero runtime
gem        the Anthropic benchmark behind it: 96% of the performance
           at 46% of the cost with orchestrator + Sonnet workers
license    MIT · ~580 stars · born July 8, 2026, frequent releases

⚙️ Eight roles, three configuration layers

The architecture fits in three layers. The machine layer is ~/.claude/settings.json: it defines who orchestrates (the opus alias) and the fallbackModel chain to degrade gracefully when the primary model is unavailable. The roles layer is the ~/.claude/agents/ directory: eight Markdown agents, each pinned via frontmatter to the right tier and the minimal tool surface. The policy layer is the user-level CLAUDE.md: the delegation rules, written in terms of roles and never model names.

The eight roles cover the full lifecycle: scout and Explore (Haiku) for read-only reconnaissance, plan-verifier (Opus, read-only) which challenges the plan and answers READY or a structured REVISE, mech-executor (Sonnet, low effort) for fully specified mechanical work, executor (Sonnet, medium effort) for implementation requiring judgment, verifier (fresh-context Opus) which verifies the outcome and never fixes, plus the two security roles (security-reviewer and security-executor, both Opus) with a correctness-over-cost mandate.

💸 The numbers behind the pattern

What makes pilotfish more than an opinion is that the pattern is benchmarked by Anthropic itself. In the tests published in the multi-agent documentation, a Fable 5 orchestrator with Sonnet 5 workers reaches 96% of the all-Fable configuration's performance for 46% of the cost (on BrowseComp: 86.8% vs 90.8% accuracy, $18.53 vs $40.56 per problem). The inverse pattern — a Sonnet executor consulting Fable as an advisor — stops at roughly 92% for 63% of the cost: the orchestrator/worker split pilotfish adopts wins on both axes.

At hobby scale the direction is the same: a 12-worker audit experiment documented by Developers Digest drops from $14.50 (everything on Fable 5) to $6.10 with Sonnet workers and $3.70 with Haiku workers. And for subscribers there's a specific bonus: Claude's weekly limits use two buckets, a shared all-models one plus an additional Sonnet-only one — routing execution to Sonnet subagents costs less per token and draws on that extra dedicated headroom.

🧪 Installation: a runbook the agent reads

The installation is itself an exercise in well-done vibe coding: you clone the pinned release, start Claude Code from the checkout and paste a prompt that makes it read the local runbook install/AGENT-INSTALL.md. The agent inspects your existing configuration, shows a merge plan — nothing is blindly overwritten — and applies it only after approval. Running it again upgrades in place.

One choice I appreciate: the README explicitly discourages the convenient path of a prompt pointing at GitHub's raw URL, because it follows main with no pinning and because WebFetch's prompt-injection protection may legitimately intercept a remote document instructing an AI to install software. The suggested answer is not to disable the protection, but to use the local checkout: a security posture that's rare in this tool category.

git clone --branch v1.3.8 --depth 1 https://github.com/Nanako0129/pilotfish.git
cd pilotfish
claude

# then, inside the Claude Code session:
# "Read the local file install/AGENT-INSTALL.md in the current checkout
#  and follow it to install pilotfish into my global Claude Code configuration.
#  Show me the full plan of changes and get my approval before writing anything."

⚠️ The honest caveat: automatic delegation is not guaranteed

This is where the project shines in transparency. A successful install does not guarantee that Claude Code will delegate spontaneously: higher-priority instructions injected by the client can brake agent dispatch, and a user-level CLAUDE.md cannot override them. The README documents the experiments — on Pro, two cue-free attempts dispatched nothing; on Max, the expected topology emerged on one positive attempt out of four — and tracks everything in public issues, with per-cell data in benchmarks/spontaneous-dispatch.

The pragmatic solution is an explicit opt-in: when you want the orchestration lifecycle, you add one line to the request invoking pilotfish and its dispatch brake. There's also a warning that alone is worth the read: since Claude Code 2.1.198 the built-in Explore subagent inherits the main session's model — if the session runs on Fable or Opus, every background search burns top-tier tokens. pilotfish overrides it back to Haiku.

• Spontaneous delegation depends on the client: higher-priority injections can suppress it; you need the explicit opt-in in the request when you want the full lifecycle.
• The built-in Explore inherits the main session's model (since Claude Code 2.1.198): without the override, background searches run on the most expensive tier.
• Model aliases depend on provider and settings: opus may resolve to different deployments; use the full model ID when exact pinning matters.
• Young, fast-moving project: born July 8, 2026, frequent releases; in shared environments prefer the pinned release, not main.
• Global config, not per-project: it writes under ~/.claude/ and coexists with your existing configuration via merge, but review the proposed change plan before approving.

🏢 Why it matters, for developers and SMBs

For anyone developing with Claude Code daily, pilotfish is the structured answer to a problem previously handled by hand with the /model command and personal discipline. The separation between read-only and write-capable roles, verifiers that never fix, the brake keeping small work in the main session: these patterns improve the workflow regardless of the savings, because fresh-context verification beats self-critique — Anthropic's official prompting guide says so, not just the repo's author.

For an SMB adopting coding agents the question is budget and predictability: plans have weekly limits, top-tier tokens are the scarce resource, and a team burning them on searches and mechanical edits finds them exhausted for the architectural decisions where they actually matter. A delegation policy encoded in configuration — identical for everyone, versionable, reviewable — is a concrete piece of governance: it turns "use models sensibly" from a recommendation into an operational default.

✅ Where to start

The path I suggest has three steps. First: read the README and the documents in docs/ — even without installing anything, they're among the most honest analyses around on costs, quotas and the real behavior of subagent dispatch. Second: install from the pinned release with the runbook, review the proposed merge plan and restart the session. Third: try the full lifecycle on a real task with the explicit opt-in, and watch in the logs who does what — which roles get dispatched, what comes back from the verifier.

The broader signal is that multi-model orchestration is becoming a documented, benchmarked practice, not a power-user trick: Anthropic publishes the numbers, tools package the pattern, and the difference between adopting it or not shows up directly in the bill and in the quota left on Friday afternoon. pilotfish is a great place to study it, because the entire policy is readable in three text files.