Pilotfish Multi-Model Orchestration
Frontier models plan, cheaper models execute, and fresh-context verification guards quality — a one-prompt-install orchestration policy for Claude Code.
Evidence shows solid least-privilege (read-only tool allowlists, verifier write denials, test-enforced) and user confirmation (installer shows merge plan and requires approval before writes); rollback paths (backups, uninstall, restore plan, plugin disable/enable) are complete — full marks. Deductions: data-flow and sensitive-data handling rely on prompt-text warnings (WebSearch/WebFetch egress, 'never transmit secrets') rather than structured disclosure; global config writes and SessionStart hook injection are disclosed but broad in effect; attribution exists (ATTRIBUTION.md, design credit) but publisher identity is unverified, so source_attribution stays at 2.
Self-consistency is exceptional: byte-exact tests enforce consistency across README, install docs, manifests, and policy templates. Deductions: dependency availability is pinned to Claude Code 2.1.219+ with Linux only contract-qualified; failure messages are documented troubleshooting only and actual runtime failure behavior cannot be verified statically, hence 2.
Audience/scenarios are clear (host table, multiple install paths) and capability boundaries/limitations are unusually well disclosed (dispatch not guaranteed, beta reliability disclaimers, Linux/Windows limits) — full marks. Deductions: trigger precision is host-limited — higher-priority instructions can suppress dispatch, with only mitigation wording offered; environment fit has macOS live-observed but Linux unverified and Windows excluded — honest but narrow.
Information architecture, install notes, naming stability, known limitations, license, and versioning are handled thoroughly: TOC, tables, runbooks, versioned pilotfish:begin/end block, VERSION/CHANGELOG/manifest linkage test-locked, plugin LICENSE copied and tested — full marks justified. Deductions: no dedicated FAQ, examples concentrate on install/uninstall prompts; maintenance responsibility shows only sponsorship and contributing guidance without explicit governance or maintenance commitment.
Output usability is supported by defined role contracts (READY/REVISE, CONFIRMED/REFUTED/INCONCLUSIVE), but full output specs are not directly present in the static source, so 2. Marginal value and cost-benefit cite research docs and benchmarks, yet quantitative savings claims are labeled behavioral observations needing paid re-verification — a fair deduction from full marks.
Claim traceability is strong: links to issue #23, upstream PR, multiple benchmark directories, dated doc checks, with tests locking claims phrase-by-phrase. Fact/inference separation is a highlight — behavioral observations are explicitly distinguished from dispatch-rate conclusions and Linux status is plainly marked untested — full marks. Deduction: cross-source corroboration rests mainly on internal consistency tests and upstream credit, with no independent third-party evidence.
- The policy writes into global ~/.claude/CLAUDE.md and agents/, affecting all future sessions; review the pinned checkout and approve the merge plan before any writes.
- The Plugin beta's SessionStart hook injects policy text into every session; the beta explicitly claims no stable reliability, cross-version compatibility, or namespace-collision proof — use cautiously in production.
- Linux support is contract-qualified only, untested and unverified; Windows is excluded. Automatic dispatch is not guaranteed; use the manual activation prompt when the lifecycle matters.
- Publisher identity is unverified; cost-savings and behavioral claims are not independently corroborated and require paid re-verification.
- Installer additions to an existing settings. availableModels allowlist persist by default; request restoration explicitly when uninstalling.
What does this agent do, and when should you use it?
Pilotfish (GitHub: Nanako0129/pilotfish) is a multi-model orchestration policy for Claude Code, not a standalone executable. It consists of three installed targets: a main-model alias and fallback chain in ~/.claude/settings., eight role-agent files under ~/.claude/agents/, and a versioned policy block in ~/.claude/CLAUDE.md. The division of labor is explicit: the main session runs on the opus family alias for planning, deciding, specifying and reviewing; scout and Explore use Haiku for read-only reconnaissance; mech-executor and executor use Sonnet for mechanical or approved implementation work; plan-verifier, security-reviewer, verifier and security-executor use Opus at approval boundaries and risk-triggered reviews with fresh contexts. Two install paths exist: a macOS/Linux Plugin beta with hook-based ambient activation, and a legacy global install requiring Claude Code 2.1.219+. The installer is idempotent, shows a merge plan before writing, requires user approval, and all changes are reversible. The project is MIT licensed and ships benchmarks and behavioral-evidence documents that explicitly bound its claims.
Once installed, pilotfish dispatches work within every Claude Code session according to its policy. The main session first selects an interaction shape: co_discover when the outcome or acceptance is unclear, explore_then_plan when direction is broad or high-impact, or execute for a clear bounded outcome. The orchestrator can then call named agents: scout (Haiku, low effort) performs read-only repository reconnaissance; plan-verifier (Opus, read-only) challenges the plan pre-approval with READY or structured REVISE; mech-executor (Sonnet) runs fully specified mechanical repetition; executor (Sonnet) does approved implementation requiring local judgment; security-reviewer (Opus, read-only) gathers security evidence before approval; security-executor (Opus, high effort) implements approved security-sensitive work; and verifier (Opus, fresh context) falsifies outcomes with CONFIRMED / REFUTED / INCONCLUSIVE verdicts. A dispatch brake keeps small, stable work in the main session and splits larger work only when a bounded role has a stable contract and delegation has positive net benefit. The Plugin beta uses Claude Code's native Plugin lifecycle with SessionStart hooks for ambient activation; an optional /pilotfish slash command or CLI wrapper enables activation per task.
- Users running long coding sessions who want search, repetitive edits, tests and documentation routed to Haiku/Sonnet while only frontier judgment stays on Opus, cutting token cost
- Teams that want an independent fresh-context plan challenge via plan-verifier's READY/REVISE gate before implementation is approved
- Developers handling security-sensitive code who use read-only security-reviewer for pre-approval evidence and security-executor for approved implementation
- Existing Claude Code global v1 users migrating to the native Plugin lifecycle for ambient activation via the Plugin beta guide
- Users working across multiple host tools who can pair this with sibling projects: remora (GPT routing), pilotfish-grok, or pilotfish-codex
What are this agent's strengths and limitations?
- Explicit cost division: mechanical and reconnaissance work runs on Haiku/Sonnet while Opus handles only planning, review and verification — directly targeting the problem that most session tokens go to non-judgment work
- Fresh-context quality gates: verifier issues CONFIRMED/REFUTED/INCONCLUSIVE verdicts and plan-verifier challenges plans pre-approval, rather than relying on main-session self-assessment
- Idempotent installer with a merge plan and approval before writing, fully reversible changes, and benchmark/evidence documents that clearly bound claims
- Locked to the Claude Code ecosystem: the core policy only applies to Claude Code; GPT/Grok/Codex hosts require sibling variants (remora, pilotfish-grok, pilotfish-codex)
- Automatic delegation is not guaranteed: higher-priority Claude Code instructions can suppress agent dispatch and user-level CLAUDE.md cannot override them, so you must manually include the dispatch-brake prompt
- The Plugin beta is macOS/Linux only: Linux is contract-qualified but untested, Windows is excluded, the Plugin cannot coexist with the legacy global install, and the beta claims no stable reliability or cross-version compatibility
- Cost structure shifts toward Opus for the main session, verification and security roles — for inherently simple tasks this can raise frontier-model spend rather than lower it
How do you install or deploy this agent?
Option 1 (Plugin beta, macOS/Linux): follow install/PLUGIN-INSTALL.md using Claude Code's native marketplace commands; Linux requires Ubuntu 20.04+, Debian 10+, or Alpine 3.19+; the guide covers migration from global v1, update, disable/enable, uninstall and rollback. Option 2 (legacy global install): run git clone --branch v1.4.1 --depth 1 https://github.com/Nanako0129/pilotfish.git && cd pilotfish && claude, then 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." Runtime requirement: Claude Code 2.1.219 or newer; restart Claude Code after installation so the agent directory and model setting reload. Requires paid access to Anthropic models (Opus/Sonnet/Haiku).
How do you use this agent?
After installing and restarting Claude Code, the policy loads into every new session. The README recommends adding this request when the lifecycle matters: "Use pilotfish. Follow its dispatch brake: keep direct work in the main session and call the named agents only when the policy selects delegation." Tune models, effort, delegation and managed settings per docs/usage.md; activate per task with the /pilotfish slash command or CLI wrapper (install/ACTIVATION-INSTALL.md). To disable for one project, use a separate CLAUDE_CONFIG_DIR. To uninstall, delegate to Claude Code: have it read install/AGENT-INSTALL.md, resolve the configuration root, remove the eight agent files and policy block, and get your approval before writing.
How does this agent compare with similar options?
The README positions this repository as the "Claude Code global policy" project within a family of siblings: remora-cc (Claude Code with session-scoped GPT routing), pilotfish-grok (Grok Build), and pilotfish-codex (Codex CLI). If your primary host is Codex CLI or Grok Build, choose the corresponding variant instead of this repository.