Pilotfish Multi-Model Claude Code Orchestration Pipeline

Pilotfish is a multi-model orchestration layer for Claude Code that lets the frontier model (Fable 5 or Opus) plan, decide, and review while cheaper models execute volume work through global subagents. It installs as a three-layer global configuration: Machine layer (settings.json with best alias and fallbackModel chain), Roles layer (6 role agent files in ~/.claude/agents/), and Policy layer (CLAUDE.md delegation rules). The six roles are scout (Haiku, read-only lookups), Explore (Haiku, overrides built-in Explore), mech-executor (Sonnet, mechanical work), executor (Opus, judgment work), verifier (Opus, fresh-context adversarial verification), and security-executor (Opus, security-sensitive work kept off Fable 5). Quality is protected by fresh-context verification, not by running the biggest model on everything. Built by Nanako0129 and published under MIT license on July 8, 2026, hitting 339 GitHub stars in its first 3 days.

BUSINESS PROBLEM

According to Anthropic's multi-agent documentation (July 2026), Fable 5 consumes subscription quota approximately 2x faster than Opus. A heavy agentic coding session can burn the 5-hour rolling window in as little as 13 minutes. A senior developer at a 20-person startup running Claude Code daily for multi-file refactors, codebase audits, and test generation spends 40-60 hours per week in agentic sessions. At $200/month for Claude Max subscription, running every session on Fable 5 exhausts quota by mid-week, forcing a choice between reduced productivity and API pay-per-use spillover at $10/$50 per million tokens. Most teams cannot afford to run the frontier model on every task, but switching models manually is disruptive and error-prone.

WHO BENEFITS

For a senior full-stack developer at a 30-person SaaS company using Claude Code daily. Situation: Weekly Fable 5 quota runs out by Thursday. Remaining tasks get the same model at the same cost, or you stop coding. Payoff: Pilotfish routes mechanical work to Haiku/Sonnet. Weekly quota stretches 2-3x. $200 subscription covers the entire week. For a solo founder building an MVP with Claude Code. Situation: Every API dollar counts. Using Fable 5 for every task means burning through API credits too fast. Payoff: Fable 5 only handles architecture planning and code review. Mechanical implementation goes to Sonnet. 46% of the cost, 96% of the quality. For a platform engineer at a 200-person company standardizing Claude Code usage. Situation: No consistent approach to model tiering across the engineering org. Each developer configures their own model strategy. Payoff: A single policy layer enforces role-based delegation. Security work is pre-routed to Opus away from Fable 5's safety classifier misfires.

HOW IT WORKS

Step 1. Install pilotfish (5 min). Paste the one-prompt install command into any Claude Code session. Claude Code fetches the runbook, inspects existing config, shows a merge plan, and applies after approval. Step 2. Configure the Machine layer (automatic). Installer sets model to best and adds fallbackModel: [opus, sonnet]. If Fable 5 is unavailable, best automatically resolves to the latest Opus. Step 3. Set up the Roles layer (automatic). Installer creates 6 role agent files in ~/.claude/agents/. Each has one line of frontmatter pinning it to the right model tier (Haiku/Sonnet/Opus). Step 4. Apply the Policy layer (automatic). Installer adds the delegation policy to ~/.claude/CLAUDE.md. Policy never names a model — it says delegate mechanical work to mech-executor, not delegate to Sonnet. Step 5. Start coding (ongoing). Claude Code uses best as orchestrator. When you ask for reconnaissance, scout (Haiku) handles it. When you need a feature built, executor (Opus) handles it. The verifier reviews non-trivial work. Step 6. Review and iterate (ongoing). If the verifier REFUTED a result, the policy auto-escalates: try the next tier up after two failures. Manual model switching never needed.

TOOL INTEGRATION

TOOL: Pilotfish v1.1.2 (MIT, July 8, 2026, 339+ stars). Role: Multi-model orchestration layer for Claude Code. Install: One-prompt agent-guided setup. Auth: None — uses your existing Claude Code auth. Cost: Free. Gotcha: The CLAUDE_CODE_SUBAGENT_MODEL env var overrides every per-agent frontmatter globally. Pilotfish deliberately does not set it. If you set it, all subagents run on the same model, defeating the architecture. TOOL: Claude Code v2.1.198+ (Anthropic). Role: Primary coding agent hosting the pilotfish orchestration layer. API access: code.claude.com. Auth: Claude subscription. Cost: $20-200/month + API usage. Gotcha: Since Claude Code v2.1.198, the built-in Explore subagent inherits your main-session model. Pilotfish overrides it back to Haiku, but this means your Explore loads user memory like any subagent (the built-in skips this). Policy block self-disables for subagent roles to keep this overhead small. TOOL: Anthropic Models (Fable 5, Opus 4.8, Sonnet 4.6, Haiku 4.5). Role: Model tiers for orchestration. API access: platform.claude.com. Auth: API key. Cost: Fable 5 $10/$50 per MTok, Opus $5/$25 per MTok, Sonnet $3/$15 per MTok, Haiku $1/$5 per MTok. Gotcha: After July 12, 2026, Fable 5 leaves subscription plans — prepaid usage credits at API rates required. The best alias resolves to the latest Opus, but the exact boundary UX is unpublished.

ROI METRICS

Metric Before (all-Fable) After (pilotfish) Source BrowseComp accuracy 90.8% 86.8% Anthropic multi-agent docs (July 2026) Cost per problem $40.56 $18.53 Anthropic multi-agent docs (July 2026) Performance vs all-Fable 100% ~96% Anthropic multi-agent docs (July 2026) Weekly quota consumption 100% (by Thu) 35-50% (full wk) Community estimate

The week-1 win: install pilotfish, then run your normal workflow for one day. Run /usage at end of day. Compare token burn and quota consumption to the previous day without pilotfish. The strategic implication: multi-model orchestration is the next frontier in AI-assisted development. Running the biggest model on every task is economically unsustainable — and unnecessary.

CAVEATS

1. (moderate risk) Subagent spawning overhead: Every spawn = fresh context + re-reads codebase slice + spec-writing tokens. Do not delegate single-file reads or quick judgments. Mitigation: The policy says start with the cheapest plausible role and escalate after two failures. Use scout for lookups, not executor.
2. (significant risk) Fable 5 subscription transition: After July 12, 2026, Fable 5 leaves subscription plans. The exact boundary behavior is unpublished. Mitigation: Do not pin Fable 5 model IDs. Use the best alias which resolves gracefully. Test with prepaid usage credits enabled.
3. (minor risk) Verifier limitations: The verifier runs on Opus. An Opus verifier cannot catch what Opus does not know — capability-ceiling errors pass through. Mitigation: For critical code (security, compliance), add a manual review step after automated verification.
4. (minor risk) Windows without WSL: Shell snippets assume POSIX. Installing via Claude Code's file tools works, but manual inspection commands may not. Mitigation: Use the agent-guided install prompt, which falls back to file tools. Manual operations need WSL.