Pilotfish

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
adds hook-based ambient activation; the global configuration install remains a
legacy alternative. The policy uses the opus family for the main session,
Sonnet for bounded execution, Haiku for 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 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.

Each role's effort is a recommended default, not a fixed setting. The policy asks
the main session to pass the Agent tool's effort (Claude Code 2.1.292 or newer)
for each delegation, chosen from the task's difficulty, ambiguity and cost of
error: a lookup can stay at low while a hard investigation runs at high. The
reviewers have a floor at their defaults: verifier and plan-verifier never
below medium, security-reviewer…