pilotfish 🐟

Pilot fish swim alongside the ocean's largest predators — small, fast, and doing the routine work so the big one doesn't have to.

pilotfish is a multi-model orchestration layer for Claude Code: the frontier model (Claude Fable 5 / Opus) plans, decides, and reviews in your main session, while cheaper models (Opus / Sonnet / Haiku) execute the volume work through global subagents. Quality is protected by fresh-context verification, not by using the biggest model everywhere. Everything installs globally — one setup, every project — and the whole stack degrades gracefully when the frontier model becomes unavailable.

Where this came from: my weekly quota reset one morning, and the first thing I did with a fresh Fable 5 allowance was ask it to figure out why the previous week's had evaporated. This repo is the setup that research produced, and it's what I now run daily on every project — three config files, no runtime code. The research notes (with sources) are in docs/.

繁體中文說明

Contents

• Why
• How it works
• Install
• Trust & security
• What gets installed
• Updating
• The fallback story
• Tuning & FAQ
• Research & design
• Uninstall
• License

Why

Frontier-model sessions are expensive in exactly the place it hurts subscribers: Claude Fable 5 consumes subscription limits ~2× faster than Opus (official UI wording), and agentic sessions with heavy tool use burn far steeper than that in practice. Meanwhile, most tokens in a coding session are not judgment — they're searching, mechanical edits, test runs, and doc updates that a cheaper model does just as well.

Every piece of this now carries Anthropic backing. The Fable 5 prompting guide recommends frequent subagent delegation and notes that independent fresh-context verifier subagents outperform self-critique. And as of 2026-07-08, the cheap-executor split is officially benchmarked: Anthropic's own tests put a Fable 5 orchestrator with Sonnet 5 workers at 96% of all-Fable performance for 46% of the cost (BrowseComp: 86.8% vs 90.8% accuracy, $18.53 vs $40.56 per problem), with the inverse advisor pattern (Sonnet executor consulting Fable) at ~92% for ~63% on SWE-bench Pro — the orchestrator split pilotfish uses won on both axes (multi-agent docs). A community experiment points the same direction at hobby scale — a delegation-heavy 12-worker audit (Developers Digest), best-case-shaped, in API dollars:

Two subscription-specific bonuses stack on top:

Tip: Claude subscriptions use a two-bucket weekly limit (official article) — a shared "all models" bucket plus an additional Sonnet-only bucket. Routing execution to Sonnet subagents costs less per token and draws on that extra dedicated headroom. (Sonnet usage still counts against the all-models bucket too — it's additional allowance, not a fully separate pool.)

⚠️ Warning: Since Claude Code v2.1.198 the built-in Explore subagent inherits your main-session model. If your main session runs Fable 5 or Opus, every background search burns Opus-tier tokens (the Claude API caps Explore's inherited model at Opus; third-party platforms have no cap). pilotfish overrides it back to Haiku. (Trade-off, stated openly: a custom Explore loads your user memory like any subagent, which the built-in skips — the policy block self-disables for subagent roles to keep that overhead small.)

Note: The two bullets above are subscription-plan mechanics. On the pay-per-token API the per-token savings still apply (there is no weekly bucket). On Bedrock / Vertex / Foundry, aliases resolve to each platform's built-in defaults and Fable 5 may not be enabled — pin versions with the ANTHROPIC_DEFAULT_*_MODEL env vars before relying on best there.

How it works

Three layers, three files' worth of configuration, all under ~/.claude/:

flowchart TD
    U[You] --> O
    subgraph MAIN["main session — 'best' alias (Fable 5 when available, else latest Opus)"]
        O["Orchestrator<br>plan / decide / spec / review"]
    end
    O -->|recon| S["scout / Explore<br>haiku · effort low"]
    O -->|mechanical spec| M["mech-executor<br>sonnet · effort low"]
    O -->|judgment work| E["executor<br>opus · effort medium"]
    O -->|security-sensitive| SEC["security-executor<br>opus · effort high"]
    M --> V["verifier<br>opus · fresh context"]
    E --> V
    SEC --> V
    V -->|CONFIRMED / REFUTED| O

The six roles:

The policy layer adds the operating rules: spec delegations completely in one shot (including the why), start with the cheapest plausible role and escalate after two failures, always set an explicit model on ad-hoc fan-outs, and gate non-trivial work behind a verifier pass before calling it done.

Install

Paste this single prompt into any Claude Code session:

Read https://raw.githubusercontent.com/Nanako0129/pilotfish/main/install/AGENT-INSTALL.md
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.

Claude reads the install runbook, inspects your existing configuration, shows you a merge plan (nothing is overwritten blindly), and applies it after you approve. Installation is idempotent — running it again upgrades in place.

Note: Requires a reasonably current Claude Code — on older builds the best alias may be rejected, and effort/tools frontmatter is silently ignored (agents still run, just untuned). On native Windows without WSL, the runbook's shell snippets assume a POSIX shell; the installing agent is instructed to fall back to its own file tools. Restart your session afterwards: the agents directory is scanned at session start, and the model setting applies on restart.

Prefer to do it by hand? The same steps are written for humans in install/AGENT-INSTALL.md, and every file it installs lives under templates/.

Trust & security

pilotfish installs by having Claude fetch a runbook and template files from this repo and merge them into your global ~/.claude/ config — including a policy block that then loads into every future session. Treat it like any curl | sh: trust flows from this repo and your GitHub connection, not from the paste. Before running it:

• Read the actual bytes that get installed, not just the runbook: the six files in templates/agents/ and templates/claude-md.orchestration.md. Nothing else is written to disk.
• Pin to a release tag or commit so what you reviewed is what installs — main can change between the moment you read it and the moment Claude fetches it. Replace main with a release tag (e.g. v1.1.0, see releases) or, for the strictest guarantee, a full commit SHA:

Read https://raw.githubusercontent.com/Nanako0129/pilotfish/<TAG_OR_SHA>/install/AGENT-INSTALL.md
and follow it to install pilotfish. Fetch every template from that same <TAG_OR_SHA>, never from main.
Show me the full plan of changes and get my approval before writing anything.

• The approval gate is necessary but not sufficient by itself: Claude writes nothing until you approve, but the plan it shows you is its own summary of a document it just fetched. Pinning plus reading the templates is what makes the gate trustworthy. If you don't trust remote fetching at all, clone the repo and point the install prompt at your local checkout.

What gets installed

Nothing is written into any project. That's deliberate — see the design doc.

Updating

The installer is idempotent, so re-running the install prompt is the update — unchanged files are skipped, the policy block is replaced in place, your settings are only touched if keys are missing. For a proper update flow that shows you the changelog first, paste:

Read https://raw.githubusercontent.com/Nanako0129/pilotfish/main/install/AGENT-INSTALL.md
and follow its "Updating an existing install" section: detect my installed pilotfish version,
show me the changelog since then, and upgrade after my approval.

The fallback story

The whole stack keeps working when the frontier model disappears, because no policy text ever names a model:

The delegation policy in CLAUDE.md speaks only of roles (executor, scout, …). Model bindings live in exactly one place — one line of frontmatter per agent file — so re-pointing a tier is a one-line edit that takes effect everywhere.

Tuning & FAQ

Research & design

This repo is the packaged result of a sourced research pass (official docs, Anthropic announcements, community measurements) plus a design rationale:

Prior art & credits. The "smart brain, cheap hands" split is not pilotfish's invention: Anthropic's own engineering writeup (Decoupling the brain from the hands) frames it, Claude Code ships opusplan built in — if all you want is cheaper sessions, /model opusplan needs no repo at all — and Rylaa/fable5-orchestrator packages the same frugality thesis as a plugin with ledger-enforcing guard hooks. pilotfish's contribution is the packaging: six deliberately-few roles instead of a 100-agent catalog, a role-based policy that survives model churn, an installer that shows its plan before touching anything, and claims that were adversarially fact-checked. If a heavier, hook-enforced flavor fits you better, use theirs.

Uninstall

Tell Claude Code:

Uninstall pilotfish: remove the six pilotfish agent files from ~/.claude/agents/,
delete the <!-- pilotfish:begin --> ... <!-- pilotfish:end --> block from ~/.claude/CLAUDE.md,
and offer to restore my previous "model" / remove "fallbackModel" in ~/.claude/settings.json.

License

MIT