Nanako0129/pilotfish

What it solves

pilotfish is a multi-model orchestration layer for Claude Code. It solves the problem of high token costs and quota exhaustion when using frontier models (like Fable 5 or Opus) for every task. By routing routine work to smaller, cheaper models (Sonnet and Haiku) while reserving high-intelligence models for planning and verification, it reduces costs and preserves quota without sacrificing quality.

How it works

It implements a role-based delegation system using three configuration layers in the ~/.claude/ directory:

1. Machine Layer (settings.json): Sets the primary orchestrator model (e.g., opus) and a fallback chain.
2. Roles Layer (agents/*.md): Defines eight specialized agents (e.g., scout, executor, verifier) each pinned to a specific model tier (Haiku, Sonnet, or Opus) based on the required effort and capability.
3. Policy Layer (CLAUDE.md): Defines the rules for how to delegate work to these roles without naming specific models.

Work flows from the main orchestrator session to specialized subagents for discovery, execution, and verification. For example, a verifier agent in a fresh Opus context is used to challenge completed work to ensure quality.

Who it’s for

Developers using Claude Code who want to optimize their API spend or subscription quota by using a tiered model approach to software engineering tasks.

Highlights

• Cost-Aware Routing: Routes low-effort tasks (like symbol lookups) to Haiku and medium-effort implementation to Sonnet, while keeping planning and security reviews in Opus.
• Independent Verification: Uses fresh-context verifier subagents to outperform self-critique.
• Graceful Degradation: Uses model aliases and fallback chains to ensure the system remains functional if a primary model becomes unavailable.
• Global Installation: One-time setup in the global Claude configuration that applies across all projects.
• Subscription Optimization: Specifically leverages the additional Sonnet-only quota bucket available in Claude subscriptions.