pilotfish: a routing policy that moves Claude Code's execution work off the frontier model

The token problem pilotfish is aimed at

The README makes a specific claim about where coding-session tokens go: search, repetitive edits, tests and documentation, rather than frontier judgment. That is the problem statement. The policy routes those bounded paths to cheaper roles and keeps the main session accountable, with fresh-context reviewers placed at what the project calls material acceptance boundaries. The intended user is someone already running Claude Code interactively, with an Opus-family main session, who notices that a large share of the session is mechanical. It is not a library you import and not a wrapper around the Claude API. It is a set of files that change how Claude Code behaves: a settings entry for the main-model alias and fallback chain, agent definition files, and a CLAUDE.md policy. New installs default to the opus alias, and the README is explicit that this is a cost-aware default rather than a claim that one model wins every task. That framing matters, because the rest of the design only holds up if you accept the premise that planning and execution deserve different budgets.

Eight roles, three models, and where freshness is enforced

The role table is the most concrete artifact in the repository. scout and Explore run on Haiku at low effort and are read-only, covering repository reconnaissance and broad search without inheriting the main model. plan-verifier runs on Opus at medium effort and is read-only, returning either READY or a structured REVISE before approval. security-reviewer is Opus at high effort, read-only, producing evidence before approval. mech-executor is Sonnet at low effort for fully specified mechanical repetition. executor is Sonnet at medium effort for approved implementation that needs local judgment. verifier is Opus at medium effort and runs in a fresh context to falsify the outcome after implementation, returning CONFIRMED, REFUTED or INCONCLUSIVE. security-executor is Opus at high effort for approved security-sensitive implementation. The flow in the README diagram is orchestrator to role to verifier and back to the orchestrator. Two design choices stand out. First, effort is set per role, not per session, so a mechanical edit and a security review do not share a reasoning budget. Second, freshness is a property of one role only: the verifier. The other reviewers are read-only but not described as fresh. That asymmetry is deliberate in the sense that verification is where the project spends a new context, but it also means a plan-verifier that shares context with the planner is a weaker check than the name suggests.

Interaction shape decides routing before any agent is named

Before Baton or direct and delegated routing, pilotfish picks the first matching interaction shape. co_discover applies while the outcome or acceptance criteria are unclear. Otherwise explore_then_plan applies when a clear direction is broad or high-impact. Otherwise execute applies for a clear bounded outcome. The README states that this changes how the main session collaborates and does not bypass risk or approval gates. The design is credited to adaptive intent routing in pilotfish-codex, contributed by @miyago9267, with a link to design.md for the details. This is the part of the policy that is easiest to misread. It is not a scheduler that inspects file counts. The README says directly that risk, not file count, triggers independent review, and that larger work is split only when a bounded role has a stable contract and delegation has positive net benefit. So the routing question is answered twice: once by shape, which sets the collaboration mode, and once by the dispatch brake, which decides whether a named agent is called at all. Small, stable work stays in the main session by design.

Installing it: a pinned checkout and an approval gate

The legacy global install is the path with the most explicit instructions. You clone the reviewed release tag at depth one, change into the checkout, start Claude Code from there, and ask it to follow the local runbook. The README gives these commands:

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

and 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 anything.

The install writes to three targets. ~/.claude/settings.json holds the main-model alias and fallback chain. ~/.claude/agents/*.md holds the model, effort and capability boundary for each role. ~/.claude/CLAUDE.md holds dispatch, approval, verification and long-run behavior. If CLAUDE_CONFIG_DIR is set, all of those paths move under that configuration root. The macOS and Linux Plugin beta is the newer path, with its own guide covering native user-scope marketplace commands, migration from global v1, update, disable and enable, uninstall and rollback. Note that the install prompt asks for the full plan before anything is written, which is the right shape for a change that edits your global CLAUDE.md, but it also means the quality of the install depends on you reading that plan.

The dispatch brake is the honest limitation

The README carries a warning that automatic delegation is not guaranteed. Higher-priority Claude Code instructions can suppress Agent dispatch, and user-level CLAUDE.md cannot override them. When the lifecycle matters, the README suggests including this request in the session:

Use pilotfish. Follow its dispatch brake: keep direct work in the main session and call the named agents only when the policy selects delegation.

That is a significant admission: the policy is advisory relative to whatever else is in your instruction stack. If you install pilotfish and never see a Haiku scout fire, the failure mode is not a crash, it is silence. The repository points to a spontaneous-dispatch benchmark and a cue-free-tui.json file, and describes the results as behavioral observations rather than a dispatch rate or proof of the active system-prompt bytes. Read that sentence carefully. The project is not claiming a measured delegation percentage, and you should not read its benchmark directory as one. The Plugin beta has its own set of disclaimers: it targets macOS and Linux, Linux requires Ubuntu 20.04+, Debian 10+ or Alpine Linux 3.19+ plus a working officially supported Claude Code install, macOS with Claude Code 2.1.239 is described as live-observed while Linux is contract-qualified only and has not been tested, verified or live-observed, Windows is excluded, SessionStart hooks are required, the Plugin must not coexist with the legacy global install, and the beta does not claim stable reliability, cross-version compatibility or runtime namespace-collision proof. That is an unusually candid list, and it should be read as a boundary rather than boilerplate.

remora and the sibling ports: what changes when you switch

The README's host table names four projects. This repository is the Claude Code global policy. remora-cc is Claude Code with session-scoped GPT routing. pilotfish-grok targets Grok Build. pilotfish-codex targets Codex CLI and is maintained by a different author, miyago9267, whose adaptive intent routing pilotfish adapted. The real difference between pilotfish and remora is scope: remora routes per session to GPT models, while pilotfish fixes a model family per role and keeps the main session on the opus alias with a fallback chain in settings.json. If your reason for looking at pilotfish is that you want a single session pinned to a non-Anthropic model, remora is the closer fit and pilotfish is the wrong tool. If your reason is that you want Claude Code's own session to stay on the frontier while bounded work goes to cheaper Claude models, pilotfish is the one that matches. The sibling ports matter for a different reason: if you use Codex CLI or Grok Build rather than Claude Code, the policy has been ported, and the ports are separate repositories with their own release cadence. Nothing in the material indicates the ports share a version number or a compatibility guarantee.

Maintenance surface and licence

The project ships frequently. v1.4.1 on 2026-08-27 is titled safe CLAUDE.md symlinks, v1.4.0 on 2026-08-22 is titled Plugin beta and ambient activation, and v1.3.10 on 2026-08-07 is titled lowercase policy, full Gate. Those titles describe changes to the policy text, the install mechanism and the agent definitions, which are exactly the files that land in your global configuration. A release titled safe CLAUDE.md symlinks tells you the install touches symlinks around a file you probably already have opinions about. The practical upgrade cost is that every policy release is a diff against ~/.claude/CLAUDE.md and ~/.claude/agents/*.md, so a pinned checkout plus a re-read of the runbook is the only way to know what changed on your machine. The licence is MIT, which permits modification and redistribution; the repository does not state a separate licence for the templates or the Plugin beta, so if you plan to redistribute a modified policy, confirm the terms on the specific files you copy. This is a description of the licence identifier in the repository, not legal advice.

Who this fits, and what to check before you commit

pilotfish fits engineers who already run Claude Code interactively, accept that the main session stays on an Opus-family alias by default, and want a written policy for when a cheaper role is allowed to act. The role table is the strongest part: model, effort and read-only status are declared per role rather than left to session defaults, and the verifier's fresh context is the one mechanism here that a plain model switch cannot replicate. It does not fit anyone on Windows, anyone who needs the Plugin path to be more than an experimental beta, anyone who wants session-scoped routing to non-Anthropic models, or anyone whose instruction stack will suppress Agent dispatch anyway. Before installing, check two things in your own environment. First, whether your existing user-level CLAUDE.md and any higher-priority instructions leave room for dispatch, because the README says they can suppress it and cannot be overridden from the user level. Second, whether you are willing to keep the legacy global install pinned to a tag such as v1.4.1 and re-run install/AGENT-INSTALL.md on each policy release, since the Plugin beta and the global install must not coexist and the beta makes no cross-version compatibility claim. If both answers are yes, the install is three commands and one prompt. If either is no, the policy will sit in your configuration without changing what your sessions actually do.

Editorial conclusion

Adopt pilotfish if you already run Claude Code daily and your sessions are dominated by search, repetitive edits and test runs that a Haiku or Sonnet role could absorb, and if you are willing to run the legacy global install from a pinned checkout so the CLAUDE.md changes stay reviewable. Do not adopt it on Windows, do not adopt it if you need a stable interface rather than an experimental macOS and Linux Plugin beta, and do not install it alongside the legacy global configuration. Before trusting it, verify two things yourself: whether your own CLAUDE.md and higher-priority instructions let Agent dispatch fire at all, and whether the verifier role actually runs in a fresh context in your setup.

Official sources

1. Issues
2. License: MIT
3. Nanako0129/pilotfish on GitHub
4. README
5. Releases