nanako0129/pilotfish

Pilotfish is a configuration setup for Claude Code, the AI coding assistant, that changes how it splits work between different AI models to save money and usage limits. Instead of running every task on the most powerful and most expensive model, pilotfish sets things up so a top tier model handles planning, decision making, and reviewing, while cheaper models handle the routine, mechanical parts of a coding session, such as searching through files or making straightforward edits. A separate model then double checks the finished work before it counts as done. The project explains that heavy duty AI sessions can burn through a subscriber's usage limits quickly, especially when a lot of that usage is spent on simple, repetitive tasks that a cheaper model could handle just as well. Pilotfish is built entirely out of configuration files rather than new code you run. It defines eight named roles, each pinned to a specific model and a specific job, such as a low effort scout role for read only lookups, a mechanical executor role for fully specified repetitive work, and a verifier role that checks finished work with a fresh perspective rather than reviewing its own output. Installation places these configuration files under a hidden folder in your home directory that Claude Code already reads from, so the setup applies globally across all of your projects at once rather than needing to be configured per project. The README also links to two sibling projects, one that adapts a similar approach for a different AI model provider without permanently changing your main Claude Code setup, and another that ports the same role based approach to a different coding agent entirely. The README backs its cost saving claims with references to official documentation and third party benchmark experiments showing that splitting a top tier planning model with cheaper worker models can reach a large majority of full performance for meaningfully less cost. It also documents a known quirk in how a recent Claude Code version handles its own built in search feature, and how pilotfish overrides that behavior to avoid unexpectedly expensive searches. The full research notes with sources are included in the project's documentation folder.