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.

Want OpenAI GPT-5.6 inside Claude Code without changing native Claude state? remora packages pilotfish's role-based orchestration pattern into a session-scoped launcher for an existing Anthropic-compatible gateway. Use pilotfish to study or customize the global policy; use remora for an approval-gated, verifiable install whose model and gateway overrides disappear with the child process.

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 -->|Plan challenge| PV["plan-verifier<br>opus · read-only"]
    PV -->|READY / REVISE| O
    O -->|mechanical spec| M["mech-executor<br>sonnet · effort low"]
    O -->|judgment work| E["executor<br>opus · effort medium"]
    O -->|security evidence| SR["security-reviewer<br>opus · read-only"]
    SR --> O
    O -->|approved security work| SEC["security-executor<br>opus · effort high"]
    M --> V["verifier<br>opus · fresh context"]
    E --> V
    SEC --> V
    V -->|CONFIRMED / REFUTED| O

The eight roles:

The policy layer now uses phase-specific dispatch brakes rather than requiring a finished implementation outcome before any delegation. Small, stable work stays direct. Large or ambiguous work may begin with bounded read-only discovery, then returns to the main session for one Plan; material Plans can receive a fresh readiness review and wait for user approval before writing agents start. Execution still requires stable scope, exclusive ownership, done criteria, integration, and verification. Every named role takes its model only from its agent definition, independent work runs in the background, and foreground agents remain reserved for immediate dependencies whose net benefit stays positive.

Long-running processes remain main-session owned. Every Bash-capable leaf role (mech-executor, executor, verifier, security-executor) runs bounded commands in the foreground and never detaches with nohup, setsid, trailing &, or subagent-side background execution; if work cannot finish within 10 minutes, it returns the exact command, absolute worktree or working directory, required environment, and input paths to the orchestrator. The orchestrator runs it in that same context, never implicitly from the parent checkout. Any agent likely to run a long command must itself be spawned with run_in_background: true, preserving harness tracking and completion notification.

Install

The recommended path is to clone the pinned v1.2.1 release locally, then start Claude Code from that checkout so it can read the runbook as a local file:

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

In that Claude Code session, paste this prompt:

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 anythin