# pilotfish: a multi-model orchestration policy for Claude Code

> pilotfish routes bounded work in a Claude Code session to cheaper models while the main session keeps planning and approval, with fresh-context reviewers at acceptance boundaries. The install is a prompt-driven runbook, and the project is explicit about what it does not guarantee.

**Nanako0129/pilotfish** — Multi-model orchestration layer for Claude Code — the frontier model plans, cheaper models execute, verification guards quality. One-prompt install.

- Repository: https://github.com/Nanako0129/pilotfish
- Stars: 697 · Forks: 45
- Language: Python
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/nanako0129-pilotfish

## The token problem pilotfish is aimed at

Most of a long coding session is not frontier judgment. It is grep, file reading, mechanical edits, test runs and documentation updates. Those tasks need a capable model but not the most expensive one, and running them all in the main session is what makes a session costly. pilotfish is a policy that splits those paths off to smaller roles while keeping the main session accountable for planning, approval and integration.

The intended user is someone who already works inside Claude Code for extended sessions and wants the cost profile to reflect task difficulty. The README frames the default as a cost-aware choice rather than a quality claim: new installs default to the `opus` alias for the main session, and Fable remains an explicit `/model fable` choice. The project does not argue that one model wins every task, and it points to docs/research.md and docs/design.md for the reasoning behind the routing.

## Roles, models and the dispatch brake

The policy installs three layers. The machine layer is `~/.claude/settings.json`, which holds the main-model alias and fallback chain. The roles layer is `~/.claude/agents/*.md`, one file per role, carrying the model, effort level and capability boundary. The policy layer is `~/.claude/CLAUDE.md`, which describes dispatch, approval, verification and long-run behavior. If `CLAUDE_CONFIG_DIR` is set, all of those paths move under that configuration root.

Eight roles are defined. `scout` and `Explore` run on Haiku at low effort for read-only reconnaissance and broad search. `mech-executor` runs on Sonnet at low effort for fully specified mechanical repetition, and `executor` on Sonnet at medium effort for approved work that needs local judgment. `plan-verifier` runs on Opus at medium effort and returns `READY` or a structured `REVISE` before approval. `security-reviewer` and `security-executor` run on Opus at high effort, the first read-only and the second for approved security-sensitive implementation. `verifier` runs on Opus at medium effort in a fresh context after implementation and returns `CONFIRMED`, `REFUTED` or `INCONCLUSIVE`.

Before any routing happens, the policy picks an interaction shape: `co_discover` while the outcome or acceptance criteria are unclear, otherwise `explore_then_plan` when the direction is clear but the work is broad or high-impact, otherwise `execute` for a clear bounded outcome. That shapes how the main session collaborates; it does not bypass the risk or approval gates. The README states plainly that automatic delegation is not guaranteed, because higher-priority Claude Code instructions can suppress Agent dispatch and user-level `CLAUDE.md` cannot override them. The suggested mitigation is an explicit request in the prompt, quoted in the README, asking the session to follow the dispatch brake and call named agents only when the policy selects delegation.

## Installing pilotfish from a reviewed checkout

The stable path is the legacy global install. Clone the reviewed release tag, start Claude Code from that checkout, and ask it to follow the local runbook. The runbook is install/AGENT-INSTALL.md, which the README says shows the full plan of changes and requires your approval before writing anything.

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

After Claude Code starts in that directory, paste this request so the agent reads the runbook from the checkout rather than from memory:

```text
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.
```

You should see a plan listing the files it intends to write under `~/.claude/`, including `settings.json`, the agent definitions under `agents/`, and `CLAUDE.md`. Read that plan before approving, because the policy layer edits a file that also governs your other Claude Code behavior. The README also notes a runtime requirement starting with "Claude Co" in the truncated text, so check the full README section before you begin.

There is also a Plugin beta for macOS and Linux, installed through native user-scope marketplace commands described in install/PLUGIN-INSTALL.md. That guide covers migration from global v1, update, disable and enable, uninstall, and rollback. The beta requires SessionStart hooks and must not coexist with the legacy global install.

## What the beta does not promise

The Plugin beta is the part to read carefully before choosing it. The README states that it targets macOS and Linux, that Linux requires Ubuntu 20.04+, Debian 10+ or Alpine Linux 3.19+ plus an otherwise-working officially supported Claude Code installation, and that Windows is excluded. macOS with Claude Code 2.1.239 is described as live-observed. Linux is described as contract-qualified only, meaning it has not been tested, verified or live-observed. Those are the project's own words, and they set the boundary of what you can expect.

The beta also does not claim stable reliability, cross-version compatibility, or runtime namespace-collision proof. If your team needs a plugin contract that survives Claude Code upgrades without re-checking, this is the wrong layer to depend on today. The legacy global install avoids the plugin lifecycle but gives up ambient activation, and the README warns the two must not coexist.

A second limitation is dispatch itself. Because Agent dispatch can be suppressed by higher-priority instructions, the routing is a policy the main session follows, not a mechanism the tooling enforces. The README points to a spontaneous-dispatch benchmark directory and a `cue-free-tui.json` result file, and describes those results as behavioral observations rather than a dispatch rate or proof of the active system-prompt bytes. Treat the routing as best-effort.

## How pilotfish differs from remora and pilotfish-codex

The README's comparison table points to three sibling projects. remora-cc is for Claude Code with session-scoped GPT routing, so the alternative model family enters at the session level rather than through named roles on the Anthropic side. pilotfish-grok targets Grok Build. pilotfish-codex targets Codex CLI and, according to the README, is where the adaptive intent routing used here originated; the design was adapted from a pull request in that repository by @miyago9267.

The practical difference is where the routing decision lives. In pilotfish, the decision is a policy document plus per-role agent files inside `~/.claude/`, and the main session remains the orchestrator. A session-scoped router such as remora changes which model backs the session, which is a coarser lever: you get a different model for the whole session rather than Haiku for reconnaissance and Opus for verification inside one session. If your work is uniformly hard, session-level routing is simpler. If your work is mostly bounded execution punctuated by judgment calls, the per-role split is the point.

## Maintenance, releases and the MIT licence

The repository is not archived, and the last push was on 2026-08-28. Releases are frequent and narrowly scoped: v1.4.1 on 2026-08-27 covers safe CLAUDE.md symlinks, v1.4.0 on 2026-08-22 introduced the Plugin beta and ambient activation, and v1.3.10 on 2026-08-07 covers a lowercase policy and the full Gate. The changelog and a RELEASING.md file sit at the repository root, and the install directory holds the two runbooks, so the upgrade path is documented in-tree rather than only in release notes.

Upgrade cost is mostly re-reading a runbook. Because the policy writes into `~/.claude/CLAUDE.md` and `~/.claude/settings.json`, an upgrade can touch files you have customized, and the v1.4.1 release title suggests symlink handling around CLAUDE.md was a real problem worth a patch release. Budget time to diff your configuration after each upgrade rather than assuming it is additive.

The licence is MIT, which permits commercial use and modification with the licence and copyright notice retained. That is a permissive baseline, but note that pilotfish configures Claude Code, and your use of the underlying models is governed by your agreement with Anthropic, not by this repository's licence. Nothing here is legal advice; check your own terms.

## Conclusion

Adopt pilotfish if you already run Claude Code daily, your sessions are dominated by search, repetitive edits and test runs, and you want those paths on Haiku and Sonnet with an Opus main session. Skip it if you work on Windows, if you need a stable plugin contract rather than a beta, or if you cannot tolerate the possibility that higher-priority Claude Code instructions suppress Agent dispatch entirely. Before installing, read install/AGENT-INSTALL.md and templates/claude-md.orchestration.md in a v1.4.1 checkout, and confirm that no existing global CLAUDE.md or higher-priority instruction already governs agent dispatch in your setup, because the README states user-level CLAUDE.md cannot override those.

## FAQ

### What is pilotfish software?

pilotfish is a multi-model orchestration policy for Claude Code. It keeps an Opus-family main session for planning and approval, routes bounded work to Sonnet and Haiku roles, and uses fresh Opus contexts for risk-triggered review.

### What does pilotfish do in a Claude Code session?

It installs a main-model alias and fallback chain in `~/.claude/settings.json`, per-role agent files under `~/.claude/agents/`, and a dispatch and verification policy in `~/.claude/CLAUDE.md`. The main session then delegates bounded work to named roles and calls a verifier after implementation.

### Is pilotfish the same as remora?

No. The README lists remora-cc as the project for Claude Code with session-scoped GPT routing, while pilotfish keeps the Anthropic model families and splits work across named roles inside one session.

## Sources

- [Issues](https://github.com/Nanako0129/pilotfish/issues)
- [License: MIT](https://github.com/Nanako0129/pilotfish/blob/main/LICENSE)
- [Nanako0129/pilotfish on GitHub](https://github.com/Nanako0129/pilotfish)
- [README](https://github.com/Nanako0129/pilotfish/blob/main/README.md)
- [Releases](https://github.com/Nanako0129/pilotfish/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nanako0129-pilotfish