This project provides a multi-model orchestration layer for Claude Code, designed to significantly reduce costs associated with using powerful frontier AI models for routine tasks. It targets users of Claude Code who want to leverage advanced AI for planning and decision-making while offloading execution to more cost-effective models, thereby optimizing subscription quotas and API spending without compromising quality. The primary benefit is substantial cost savings (claimed up to 74%) through intelligent delegation and verification.

How It Works

Pilotfish employs a three-layer architecture: machine-level settings, role-based agents, and a central policy file. The core approach is to use expensive frontier models (like Claude Fable 5 or Opus) for planning, decision-making, and review, while cheaper models (Sonnet, Haiku) handle high-volume, less complex execution tasks. Six distinct role agents are defined (scout, Explore, mech-executor, executor, verifier, security-executor), each mapped to specific Claude models and "effort" tiers. A role-based policy dictates delegation logic, prioritizing cheaper agents and escalating only when necessary. Quality is maintained via a dedicated verifier agent that uses fresh-context adversarial checks, a method noted to outperform self-critique. This design ensures cost efficiency and robust quality control, with graceful degradation if the frontier model is unavailable.

Quick Start & Requirements

Installation is achieved by pasting a single prompt into any Claude Code session, directing it to fetch and apply changes from https://raw.githubusercontent.com/Nanako0129/pilotfish/main/install/AGENT-INSTALL.md. The process requires user approval before modifying the global ~/.claude/ configuration. A reasonably current version of Claude Code is recommended; older builds may have compatibility issues with certain features like effort and model frontmatter. Native Windows users without WSL should be aware that shell snippets assume a POSIX environment, though the installer includes a fallback. Installation is idempotent and serves as the update mechanism.

Highlighted Details

• Cost Efficiency: Anthropic benchmarks indicate a Fable 5 orchestrator with Sonnet workers achieves 96% of all-Fable performance at 46% of the cost. Community experiments show potential savings ranging from 58% (Sonnet) to 74% (Haiku) for execution tasks.
• Subscription Optimization: Leverages Claude's dual-bucket weekly limits by routing execution to Sonnet subagents, utilizing dedicated Sonnet headroom and reducing overall token costs.
• Quality Assurance: Utilizes a dedicated verifier agent employing "fresh-context adversarial verification" to ensure task quality, a strategy officially recommended over self-critique.
• Global Installation: Designed for "one setup, every project," installing globally into ~/.claude/ for seamless use across all projects without per-project configuration.

Maintenance & Community

Updates are handled by re-running the installer prompt, which detects the installed version, presents a changelog, and applies upgrades upon approval. Users can monitor GitHub releases for notifications. Pinning the installation to a specific release tag or commit SHA is recommended for stability and reproducibility. While specific community channels like Discord/Slack are not detailed, the project references community experiments and Anthropic's official documentation.

Licensing & Compatibility

The project is released under the MIT license, permitting broad use and modification. It is designed to integrate with Claude Code's user memory system. However, compatibility can be affected by managed or enterprise settings on user machines, which may override pilotfish's configurations (e.g., managed model or availableModels). Project-specific CLAUDE.md files can also introduce local policies that take precedence over the global pilotfish setup.

Limitations & Caveats

Pilotfish requires a sufficiently recent version of Claude Code; older versions may not fully support its features. Native Windows installations without WSL might encounter shell compatibility issues, although a fallback mechanism exists. The custom Explore agent, while saving costs by forcing Haiku, trades some functionality compared to the built-in agent. Furthermore, managed environment settings can override the user-level pilotfish configuration, requiring administrator intervention if issues arise.