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.

繁體中文說明

Contents

• Why
• How it works
• Install
• What gets installed
• 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.

The orchestrator/executor split is officially endorsed: Anthropic's Fable 5 prompting guide recommends frequent subagent delegation and notes that independent fresh-context verifier subagents outperform self-critique. The economics are measured, not hypothetical:

Two subscription-specific bonuses stack on top:

提示 / Tip: Claude subscriptions use a two-bucket weekly limit — 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 frontier-priced tokens. pilotfish overrides it back to Haiku.

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 (the best alias, fallbackModel, and subagent model/effort frontmatter shipped across 2026 releases). 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/.

What gets installed

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

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:

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