[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-92648":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":9,"languages":9,"totalLinesOfCode":9,"stars":10,"forks":11,"watchers":12,"openIssues":13,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":14,"stars7d":14,"stars30d":15,"stars90d":14,"forks30d":14,"starsTrendScore":14,"compositeScore":16,"rankGlobal":9,"rankLanguage":9,"license":17,"archived":18,"fork":18,"defaultBranch":19,"hasWiki":20,"hasPages":18,"topics":21,"createdAt":9,"pushedAt":9,"updatedAt":28,"readmeContent":29,"aiSummary":30,"trendingCount":14,"starSnapshotCount":14,"syncStatus":13,"lastSyncTime":31,"discoverSource":32},92648,"pilotfish","Nanako0129\u002Fpilotfish","Nanako0129","Multi-model orchestration layer for Claude Code — the frontier model plans, cheaper models execute, verification guards quality. One-prompt install.",null,437,33,4,2,0,206,54.59,"MIT License",false,"main",true,[22,23,24,25,26,27],"ai-agents","anthropic","claude","claude-code","multi-agent","orchestration","2026-07-22 04:02:06","# pilotfish 🐟\n\n> Pilot fish swim alongside the ocean's largest predators — small, fast, and doing the routine work so the big one doesn't have to.\n\n**pilotfish** is a multi-model orchestration layer for [Claude Code](https:\u002F\u002Fcode.claude.com): the frontier model (Claude Fable 5 \u002F Opus) plans, decides, and reviews in your main session, while cheaper models (Opus \u002F Sonnet \u002F 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.\n\n**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\u002F](.\u002Fdocs\u002F).\n\n[繁體中文說明](.\u002FREADME.zh-TW.md)\n\n## Contents\n\n- [Why](#why)\n- [How it works](#how-it-works)\n- [Install](#install)\n- [Trust & security](#trust--security)\n- [What gets installed](#what-gets-installed)\n- [Updating](#updating)\n- [The fallback story](#the-fallback-story)\n- [Tuning & FAQ](#tuning--faq)\n- [Research & design](#research--design)\n- [Uninstall](#uninstall)\n- [License](#license)\n\n## Why\n\nFrontier-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.\n\nEvery piece of this now carries Anthropic backing. The [Fable 5 prompting guide](https:\u002F\u002Fplatform.claude.com\u002Fdocs\u002Fen\u002Fbuild-with-claude\u002Fprompt-engineering\u002Fprompting-claude-fable-5) 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](https:\u002F\u002Fplatform.claude.com\u002Fdocs\u002Fen\u002Fmanaged-agents\u002Fmulti-agent)). A community experiment points the same direction at hobby scale — a delegation-heavy 12-worker audit ([Developers Digest](https:\u002F\u002Fwww.developersdigest.tech\u002Fblog\u002Ffable-5-orchestrator-model-playbook)), best-case-shaped, in API dollars:\n\n| Setup (12-worker audit experiment, Developers Digest) | Cost | Savings |\n|---|---|---|\n| Everything on Fable 5 | $14.50 | — |\n| Fable 5 orchestrates + Sonnet workers | $6.10 | 58% |\n| Fable 5 orchestrates + Haiku workers | $3.70 | 74% |\n\nTwo subscription-specific bonuses stack on top:\n\n> **Tip:** Claude subscriptions use a two-bucket weekly limit ([official article](https:\u002F\u002Fsupport.claude.com\u002Fen\u002Farticles\u002F14552983-models-usage-and-limits-in-claude-code)) — 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.)\n\n> ⚠️ **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.)\n\n> **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 \u002F Vertex \u002F 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.\n\n## How it works\n\nThree layers, three files' worth of configuration, all under `~\u002F.claude\u002F`:\n\n| Layer | File(s) | Job |\n|---|---|---|\n| Machine | `~\u002F.claude\u002Fsettings.json` | Who orchestrates (`best`) + automatic `fallbackModel` chain |\n| Roles | `~\u002F.claude\u002Fagents\u002F*.md` | Six role agents, each pinned to the right model tier via one line of frontmatter |\n| Policy | `~\u002F.claude\u002FCLAUDE.md` | *How* to delegate — written in terms of roles, never model names |\n\n```mermaid\nflowchart TD\n    U[You] --> O\n    subgraph MAIN[\"main session — 'best' alias (Fable 5 when available, else latest Opus)\"]\n        O[\"Orchestrator\u003Cbr>plan \u002F decide \u002F spec \u002F review\"]\n    end\n    O -->|recon| S[\"scout \u002F Explore\u003Cbr>haiku · effort low\"]\n    O -->|mechanical spec| M[\"mech-executor\u003Cbr>sonnet · effort low\"]\n    O -->|judgment work| E[\"executor\u003Cbr>opus · effort medium\"]\n    O -->|security-sensitive| SEC[\"security-executor\u003Cbr>opus · effort high\"]\n    M --> V[\"verifier\u003Cbr>opus · fresh context\"]\n    E --> V\n    SEC --> V\n    V -->|CONFIRMED \u002F REFUTED| O\n```\n\nThe six roles:\n\n| Role | Model | Effort | Used for |\n|---|---|---|---|\n| `scout` | haiku | low | Read-only lookups: \"where\u002Fhow is X\", symbol usages, config values |\n| `Explore` | haiku | low | Overrides the built-in Explore agent (see warning above) |\n| `mech-executor` | sonnet | low | Fully-specified mechanical work: pattern refactors, convention tests, docs, bulk edits |\n| `executor` | opus | medium | Implementation needing judgment: features, bug fixes, design-sensitive refactors |\n| `verifier` | opus | medium | Fresh-context adversarial verification; returns CONFIRMED\u002FREFUTED, never fixes |\n| `security-executor` | opus | high | Anything security-sensitive — deliberately kept off Fable 5, whose safety classifiers can refuse benign defensive-security work |\n\nThe 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.\n\n## Install\n\nPaste this single prompt into any Claude Code session:\n\n```text\nRead https:\u002F\u002Fraw.githubusercontent.com\u002FNanako0129\u002Fpilotfish\u002Fmain\u002Finstall\u002FAGENT-INSTALL.md\nand follow it to install pilotfish into my global Claude Code configuration.\nShow me the full plan of changes and get my approval before writing anything.\n```\n\nClaude 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.\n\n> **Note:** Requires a reasonably current Claude Code — on older builds the `best` alias may be rejected, and `effort`\u002F`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.\n\nPrefer to do it by hand? The same steps are written for humans in [install\u002FAGENT-INSTALL.md](.\u002Finstall\u002FAGENT-INSTALL.md), and every file it installs lives under [templates\u002F](.\u002Ftemplates\u002F).\n\n## Trust & security\n\npilotfish installs by having Claude fetch a runbook and template files from this repo and merge them into your global `~\u002F.claude\u002F` 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:\n\n- **Read the actual bytes that get installed**, not just the runbook: the six files in [templates\u002Fagents\u002F](.\u002Ftemplates\u002Fagents\u002F) and [templates\u002Fclaude-md.orchestration.md](.\u002Ftemplates\u002Fclaude-md.orchestration.md). Nothing else is written to disk.\n- **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](https:\u002F\u002Fgithub.com\u002FNanako0129\u002Fpilotfish\u002Freleases)) or, for the strictest guarantee, a full commit SHA:\n\n```text\nRead https:\u002F\u002Fraw.githubusercontent.com\u002FNanako0129\u002Fpilotfish\u002F\u003CTAG_OR_SHA>\u002Finstall\u002FAGENT-INSTALL.md\nand follow it to install pilotfish. Fetch every template from that same \u003CTAG_OR_SHA>, never from main.\nShow me the full plan of changes and get my approval before writing anything.\n```\n\n- **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.\n\n## What gets installed\n\n| Target | Change | Reversible |\n|---|---|---|\n| `~\u002F.claude\u002Fsettings.json` | `model` → `\"best\"`, adds `fallbackModel: [\"opus\", \"sonnet\"]`, extends `availableModels` (only if you already restrict it) | Yes — keys are independent |\n| `~\u002F.claude\u002Fagents\u002F` | Six role agent files (listed above) | Yes — delete the files |\n| `~\u002F.claude\u002FCLAUDE.md` | One `## Orchestration` section between `\u003C!-- pilotfish:begin\u002Fend -->` markers | Yes — remove the marker block |\n\nNothing is written into any project. That's deliberate — see the design doc.\n\n## Updating\n\nThe 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:\n\n```text\nRead https:\u002F\u002Fraw.githubusercontent.com\u002FNanako0129\u002Fpilotfish\u002Fmain\u002Finstall\u002FAGENT-INSTALL.md\nand follow its \"Updating an existing install\" section: detect my installed pilotfish version,\nshow me the changelog since then, and upgrade after my approval.\n```\n\n| Want to… | How |\n|---|---|\n| Check what you have installed | `grep -o \"pilotfish v[0-9.]*\" ~\u002F.claude\u002FCLAUDE.md` — no output with markers present = pre-v1.1.0, update recommended |\n| Get notified of new releases | GitHub → **Watch → Custom → Releases** on this repo |\n| See what changed | [CHANGELOG.md](.\u002FCHANGELOG.md) — every release is also a git tag |\n| Stay frozen on a reviewed version | Install pinned to a tag or SHA (see [Trust & security](#trust--security)); pinned installs never move until you re-pin |\n\n## The fallback story\n\nThe whole stack keeps working when the frontier model disappears, because no policy text ever names a model:\n\n| Failure mode | What catches it | Your action |\n|---|---|---|\n| Fable 5 leaves your plan (e.g. the July 2026 subscription changes) | `best` re-resolves to the latest Opus — the documented rule, and how the June 2026 outage actually behaved (notice banner, new sessions continued on Opus) | Likely none — the exact boundary UX is unpublished; worst case is one `\u002Fmodel` switch or enabling usage credits. Never pin `fable`\u002Ffull IDs: pinned IDs hard-errored in June |\n| Model overloaded \u002F API errors | `fallbackModel: [\"opus\", \"sonnet\"]` switches automatically with a notice | None |\n| A tier gets deprecated (Opus 4.8 → 4.9, Sonnet 5 → next) | Role agents use aliases (`opus`, `sonnet`, `haiku`) that track the recommended version | None |\n| Frontier refuses a security task mid-run | Security work is pre-routed to `security-executor` (Opus), so it never reaches the classifier | None |\n\nThe 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.\n\n## Tuning & FAQ\n\n| Question | Answer |\n|---|---|\n| I want to save even more quota | Switch the main session to `\u002Fmodel opusplan` — Opus thinks in plan mode, Sonnet executes. The role agents keep working unchanged underneath. |\n| Can I force every subagent onto one model? | `CLAUDE_CODE_SUBAGENT_MODEL` overrides *all* per-agent frontmatter — that's why pilotfish doesn't set it. Leave it unset unless you want a temporary global override. |\n| I use `availableModels` as an allowlist | Then it must contain every alias the agents use (`opus`, `sonnet`, `haiku`), or those agents silently fall back to inheriting the main-session model. The installer checks this. |\n| Why `effort: low` on the cheap roles? | Effort is the second big quota lever. Fable-5-generation models at low effort routinely match previous-generation `xhigh`; recon and mechanical work don't need deep thinking. |\n| Which effort for the main session? | `high`. Official guidance for Fable 5: `high` for most work, `xhigh` only for the longest-horizon tasks, `max` rarely — diminishing returns. |\n| Do I lose the 1M context window? | No — Fable 5 is 1M by default, so `best` gives you 1M whenever it resolves to Fable 5. If you want *guaranteed* 1M even when `best` would fall back to Opus, set `model` to `\"opus[1m]\"` instead (the `[1m]` suffix is documented for `sonnet`\u002F`opus`\u002F`opusplan`\u002Ffull IDs, not for `best`). |\n| Does the orchestrator ever do work itself? | Yes — quick single-file reads, decisions, and anything you explicitly asked *it* to judge. Delegation has overhead; the policy says so. |\n| My project has its own CLAUDE.md — conflict? | No file is ever touched: pilotfish writes only under `~\u002F.claude\u002F`. At runtime Claude Code *stacks* project memory and user memory — both load together, neither overrides the other. If one repo needs different behavior, add a local note there (e.g. \"work inline in this repo, don't delegate\") — the more specific instruction wins in practice. |\n| Subagent quality worries me | That's what `verifier` is for: an independent fresh-context pass that tries to *refute* the work. Official guidance: fresh-context verifiers beat self-critique. Escalation (two strikes → higher tier) handles the rest. Note verification isn't free either — it re-reads context on Opus — which is why the policy scopes it to non-trivial work only. |\n| Doesn't spawning agents cost extra? | Yes — every spawn is a fresh context that re-reads its slice of the codebase, and spec-writing costs main-session tokens. That overhead is why the policy says don't delegate single-file reads or quick judgments. The savings come from volume work (search, bulk edits, test runs), where the cheaper tier's per-token price dwarfs the spawn overhead. |\n| Turn it off fast? | **This session:** tell Claude \"don't delegate this session — work inline\"; it's just policy text, it obeys immediately. **This repo:** add a local note to the repo's CLAUDE.md. **Whole machine:** comment out the `pilotfish:begin\u002Fend` block in `~\u002F.claude\u002FCLAUDE.md` — the agent files just sit unused. No reinstall needed to switch back. |\n| Managed \u002F enterprise machine? | Managed settings outrank user settings: a managed `model`, `availableModels` allowlist, or a managed agent with the same name will override pilotfish's user-level install. If roles don't take effect after restart, ask your admin — pilotfish can't (and shouldn't) override managed policy. |\n\n## Research & design\n\nThis repo is the packaged result of a sourced research pass (official docs, Anthropic announcements, community measurements) plus a design rationale:\n\n| Document | Language | Contents |\n|---|---|---|\n| [docs\u002Fresearch.md](.\u002Fdocs\u002Fresearch.md) | English | Full research findings: Fable 5 strengths & when it's wasteful, subscription economics, official Claude Code mechanisms, community measurements — with sources |\n| [docs\u002Fresearch.zh-TW.md](.\u002Fdocs\u002Fresearch.zh-TW.md) | 繁體中文 | 研究報告原版（the original the English version translates） |\n| [docs\u002Fdesign.md](.\u002Fdocs\u002Fdesign.md) | English | Why three layers, why role-based policy, why aliases over pinned IDs, effort tiering, what was deliberately left out |\n\n**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](https:\u002F\u002Fwww.anthropic.com\u002Fengineering\u002Fmanaged-agents)) frames it, Claude Code ships [`opusplan`](https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Fmodel-config) built in — if all you want is cheaper sessions, `\u002Fmodel opusplan` needs no repo at all — and [Rylaa\u002Ffable5-orchestrator](https:\u002F\u002Fgithub.com\u002FRylaa\u002Ffable5-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.\n\n## Uninstall\n\nTell Claude Code:\n\n```text\nUninstall pilotfish: remove the six pilotfish agent files from ~\u002F.claude\u002Fagents\u002F,\ndelete the \u003C!-- pilotfish:begin --> ... \u003C!-- pilotfish:end --> block from ~\u002F.claude\u002FCLAUDE.md,\nand offer to restore my previous \"model\" \u002F remove \"fallbackModel\" in ~\u002F.claude\u002Fsettings.json.\n```\n\n## License\n\n[MIT](.\u002FLICENSE)\n","pilotfish 是一个面向 Claude Code 的多模型协同编排层，实现前沿模型（如 Claude Fable 5）负责规划与质量审查，低成本模型（如 Sonnet、Haiku）执行具体编码任务的分工机制。其核心技术包括基于独立上下文的验证式质量守卫、全局子代理调度、零运行时代码配置（仅需三个配置文件），以及优雅降级能力——当前沿模型不可用时自动切换至次优但可用的模型组合。适用于需要平衡开发效率、成本控制与输出质量的日常编程场景，尤其适合订阅制 API 频繁调用的个人开发者与中小型团队。","2026-07-10 02:30:03","CREATED_QUERY"]