pilotfish 🐟

Small, fast role agents handle volume work while the frontier main session keeps planning, approval, integration, and final judgment.

pilotfish is a multi-model orchestration policy for Claude Code. The macOS and Linux Plugin beta adds hook-based ambient activation; the global configuration install remains a legacy alternative. The policy uses the opus family for the main session, Sonnet and Haiku for bounded execution and reconnaissance, and fresh Opus contexts for risk-triggered review.

繁體中文

Contents

• Why
• How it works
• Install
• Operate
• Documentation
• Project

Why

Most coding-session tokens are spent on search, repetitive edits, tests, and documentation rather than frontier judgment. pilotfish routes those bounded paths to cheaper roles while keeping the main session accountable and using fresh-context reviewers at material acceptance boundaries.

New installs default to the opus alias; Fable remains an explicit /model fable choice. This is a cost-aware default, not a claim that one model wins every task. The rationale and measurements live in research, the design notes, and #23.

How it works

The Plugin beta packages the policy and namespaced roles under Claude Code's native Plugin lifecycle. The legacy global install uses these direct targets:

If CLAUDE_CONFIG_DIR is set, all ~/.claude/ paths above move under that configuration root.

flowchart TD
    U["You"] --> I
    subgraph MAIN["main session — opus family alias"]
        I["Interaction shape
execute / explore_then_plan / co_discover"]
        I --> O
        O["Orchestrator
plan / decide / spec / review"]
    end
    O -->|recon| S["scout / Explore
haiku · effort low"]
    O -->|Plan challenge| PV["plan-verifier
opus · read-only"]
    PV -->|READY / REVISE| O
    O -->|mechanical spec| M["mech-executor
sonnet · effort low"]
    O -->|judgment work| E["executor
sonnet · effort medium"]
    O -->|security evidence| SR["security-reviewer
opus · read-only"]
    SR --> O
    O -->|approved security work| SEC["security-executor
opus · effort high"]
    M --> V["verifier
opus · fresh context"]
    E --> V
    SEC --> V
    V -->|CONFIRMED / REFUTED / INCONCLUSIVE| O

Before Baton or direct/delegated routing, pilotfish chooses the first matching interaction shape: co_discover while the outcome or acceptance is unclear; otherwise explore_then_plan when a clear direction is broad or high-impact; otherwise execute for a clear bounded outcome. This changes how the main session collaborates; it does not bypass risk or approval gates. The design is adapted from pilotfish-codex's adaptive intent routing by @miyago9267. See the design details.

Small, stable work stays in the main session. Larger work is split only when a bounded role has a stable contract and delegation has positive net benefit. Risk, not file count, triggers independent review. The exact lifecycle is defined in the policy template and explained in the design rationale.

⚠️ 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, include the following request.

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

The bounded results and claim limits are recorded in the spontaneous-dispatch benchmark and cue-free-tui.json. They are behavioral observations, not a dispatch rate or proof of the active system-prompt bytes.

Install

Plugin beta for macOS and Linux

Use the Plugin beta install guide for native user-scope marketplace commands, migration from global v1, update, disable/enable, uninstall, and rollback. The experimental beta targets macOS and Linux. Linux requires Ubuntu 20.04+, Debian 10+, or Alpine Linux 3.19+ and an otherwise-working officially supported Claude Code installation, per the official system requirements (checked 2026-08-22). macOS with Claude Code 2.1.239 is live-observed. Linux is contract-qualified only; it 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 this beta does not claim stable reliability, cross-version compatibility, or runtime namespace-collision proof.

Legacy global install

Clone the reviewed release, start Claude Code from that checkout, and ask it to follow the local runbook:

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

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 are reloaded.

⚠️ Trust boundary: the policy loads into every future session. Review the pinned checkout, the agent templates, the policy template, and the install runbook before approving writes. Do not bypass WebFetch prompt-injection protection to install from a mutable raw URL.

The installer is idempotent and shows a merge plan before writing. Human-readable steps, backups, collision handling, verification, updates, and uninstall are all in install/AGENT-INSTALL.md.

Operate

To delegate uninstall to Claude Code:

Read the local install/AGENT-INSTALL.md, resolve the Claude Code configuration
root exactly as Step 0 specifies, and follow its Uninstall section. In that
configuration root, remove the eight pilotfish agent files and policy block.
Show me the full removal and settings-restoration plan and get my approval
before writing.

Documentation