pilotfish: model orchestration for Claude Code
pilotfish
A Claude Code plugin where the main model plans and signs off while search, edits and verification go to roles running on cheaper models
- 718 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The legacy install changes the global `settings.json` and `CLAUDE.md`, and the policy loads into every future session
- Executor roles edit project files and run commands, and the plugin attaches through a hook that fires at the start of every session
- The author warns about a trust boundary: review the role templates and the policy before agreeing to any write
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add plugins/pilotfishDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The legacy install changes the global `settings.json` and `CLAUDE.md`, and the policy loads into every future session
- Executor roles edit project files and run commands, and the plugin attaches through a hook that fires at the start of every session
- The author warns about a trust boundary: review the role templates and the policy before agreeing to any write
This is third-party code. Review the repository files before installing.
What it does
pilotfish gives Claude Code a set of delegation rules. The main session runs on the opus family and decides what to keep and what to hand to narrow roles. `scout` on haiku does repository reconnaissance, `mech-executor` on sonnet makes mechanical edits from a finished spec, and `executor`, also on sonnet, takes tasks that need local judgment. `plan-verifier` challenges a plan before approval, `verifier` checks the result in a fresh context after implementation, and `security-reviewer` and `security-executor` handle security work. The macOS and Linux plugin installs the roles and attaches a session-start hook that loads the policy on its own. The legacy install clones the repository, and Claude Code follows `install/AGENT-INSTALL.md`: it shows a plan and, once you agree, writes eight role files to `~/.claude/agents/`, a policy block to `CLAUDE.md`, and the `model` and `fallbackModel` fields to `settings.json`. Before a task starts, the policy picks an interaction shape: discussion, plan first or direct execution. Small, clear work stays in the main session, and roles join only when the task boundary is stable and delegation has a positive net benefit. The cost of a mistake triggers independent review, and the number of files plays no part.
Who it is for. For developers whose long Claude Code sessions burn tokens on search, repetitive edits and tests, and who want controlled savings without giving up control of the decisions.
Good fit when
- A large repository where reconnaissance and file search should go to a haiku role, leaving the main model free
- You have a batch of similar edits from a finished spec and want them executed on sonnet
- Before implementation you want an independent look at the plan, and after it a check of the result in a fresh context
- The task touches security: the scheme includes a read-only reviewer and a separate executor
- You want to see session cost broken down by role and model
Not a fit when
- You are on Windows: the plugin does not target it, and the legacy install needs Claude Code 2.1.219 or newer
- Tasks are short and unambiguous: the role overhead will not pay off and the main session can handle them alone
- You want roles to run on a schedule with no human involved: pilotfish sets delegation rules inside a session and does not schedule jobs
- `CLAUDE.md` already holds the old pilotfish policy: the plugin then refuses to run and asks you to migrate
Example request
Use pilotfish. Follow its dispatch brake: find every place that uses the old payment client, rewrite them for the new one, and hand the check to a separate roleLimitations
Automatic delegation is not guaranteed. Claude Code's system instructions outrank the user-level `CLAUDE.md`, so sometimes you need to ask directly in a message: "Use pilotfish" with a reference to the dispatch brake. The author states separately that this is a cost-aware default and makes no claim that one model wins everywhere.
The plugin targets macOS and Linux. The author verified it live on macOS with Claude Code 2.1.239; for Linux they confirm only contract compliance without a live run. It needs a session-start hook, and it cannot sit next to the legacy global install: the hook refuses to run and asks you to migrate.
The overridden `Explore` role is not part of the plugin: Claude Code names plugin roles by namespace, so only the legacy install can replace the built-in scout. The `CLAUDE_CODE_SUBAGENT_MODEL` variable overrides the model for every role, and if it is set the pre-install check stops.
How to disable. Disable the plugin with `claude plugin disable --scope user pilotfish@pilotfish`, remove it with `claude plugin uninstall --scope user pilotfish@pilotfish` and `claude plugin marketplace remove --scope user pilotfish`. The legacy install is removed by the Uninstall section of `install/AGENT-INSTALL.md`: eight role files and the policy block.
FAQ
How do I install pilotfish in Claude Code?
Add the marketplace with `claude plugin marketplace add --scope user Nanako0129/pilotfish`, then install the plugin: `claude plugin install --scope user pilotfish@pilotfish`. It runs on macOS and Linux and needs Claude Code 2.1.219 or newer.
Which roles and models does pilotfish use?
The main session runs on the opus family. The `scout` role works on haiku, `mech-executor` and `executor` on sonnet, the reviewers `plan-verifier`, `verifier` and `security-reviewer` on opus, and `security-executor` is also on opus.
How is the plugin different from the legacy global install?
The plugin attaches as an ordinary Claude Code plugin and loads the policy with a session-start hook. The legacy install writes roles to `~/.claude/agents/`, a block to `CLAUDE.md` and model fields to `settings.json`, but it can replace the built-in `Explore` role.
Why do agents not start by themselves?
Higher-priority Claude Code instructions can suppress subagent dispatch. Ask directly: "Use pilotfish. Follow its dispatch brake: keep direct work in the main session and call the named agents only when the policy selects delegation."
Are there similar projects for other agents?
Yes, the project has siblings: remora for Claude Code with GPT routing, pilotfish-grok for Grok Build and pilotfish-codex for Codex CLI. Each lives in its own repository.
Discussion
No questions or reviews yet.
Related
PluginsMulti-agent orchestration for Claude Code: teams, roles, autopilot and task routing across skills and subagents
A Claude Code plugin that hands coding tasks to Codex agents, monitors them and verifies the results independently
A Claude Code plugin that runs one task across several external models and surfaces disagreements before you ship
claude-mods adds 112 skills, 3 agents and 3 commands to Claude Code: stacks, agent operation, defense, session continuity.
Workflows for Claude Code: /do, /omo, /bmad-pilot and more commands, with Codex, Gemini or OpenCode writing the code through codeagent-wrapper
Claude Code supervises while Codex, opencode and pi work on your quota: delegated edits, independent review, model discussions
README in short
The documentation explains the layer scheme of machine settings, roles and policy, backed by a flow diagram and a table of roles with default effort. Nearby are the author's measurements on spontaneous role dispatch, prompt compression and the verifier boundary.