pilotfish
Marketplace for the pilotfish macOS and Linux Claude Code Plugin.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/nanako0129-pilotfish)HTML
<a href="/listings/nanako0129-pilotfish"><img src="/api/listings/nanako0129-pilotfish/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Plugin for macOS and Linux
Use the [Plugin install guide](./install/PLUGIN-INSTALL.md) for native user-scope marketplace commands, migration from global v1, update, disable/enable, uninstall, and rollback. The Plugin 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](https://code.claude.com/docs/en/setup#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 the Plugin 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.5.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](./templates/agents/), the > [policy template](./templates/claude-md.orchestration.md), and the > [install runbook](./install/AGENT-INSTALL.md) before approving writes. Do not > bypass WebFetch prompt-injection protection to install from a mutable raw URL.
| Target | Installed change | Reversible | |---|---|---| | `settings.json` | Adds missing `model` and `fallbackModel`; conditionally extends an existing `availableModels` allowlist | Restores or removes `model`; `fallbackModel` is removable, while allowlist additions remain unless requested | | `agents/` | Eight role-agent files | Yes | | `CLAUDE.md` | One versioned `pilotfish:begin/end` policy block | Yes |
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](./install/AGENT-INSTALL.md).
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 23 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- {
- "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
- "name": "pilotfish",
- "owner": {
- "name": "Nanako0129",
- "url": "https://github.com/Nanako0129"
- },
- "description": "Marketplace for the pilotfish macOS and Linux Claude Code Plugin.",
- "plugins": [
- {
- "name": "pilotfish",
- "source": "./plugin",
- "version": "1.5.0",
- "description": "Hook-based ambient orchestration for macOS and Linux Claude Code.",
- "category": "productivity",
- "tags": [
- "orchestration",
- "subagents",
- "delegation"
- ]
- }
- ]
- }
README.md · README · 235 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # 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](https://code.claude.com). The [macOS and Linux Plugin](./install/PLUGIN-INSTALL.md)
- 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.
- [繁體中文](./README.zh-TW.md)
- ## Contents
- - [Why](#why)
- - [How it works](#how-it-works)
- - [Install](#install)
- - [Operate](#operate)
- - [Documentation](#documentation)
- - [Project](#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](./docs/research.md), the [design notes](./docs/design.md), and
- [#23](https://github.com/Nanako0129/pilotfish/issues/23).
- | Host or use case | Project |
- |---|---|
- | Claude Code global policy | This repository |
- | Claude Code with session-scoped GPT routing | [remora](https://github.com/Nanako0129/remora-cc) |
- | Grok Build | [pilotfish-grok](https://github.com/Nanako0129/pilotfish-grok) |
- | Codex CLI | [pilotfish-codex](https://github.com/miyago9267/pilotfish-codex) |
- ## 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:
- | Layer | Installed target | Responsibility |
- |---|---|---|
- | Machine | `~/.claude/settings.json` | Main-model alias and fallback chain |
- | Roles | `~/.claude/agents/*.md` | Model, effort, and capability boundary for each role |
- | Policy | `~/.claude/CLAUDE.md` | Dispatch, approval, verification, and long-run behavior |
- If `CLAUDE_CONFIG_DIR` is set, all `~/.claude/` paths above move under that
- configuration root.
- ```mermaid
- 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
- haiku · effort low"]
- O -.->|recon, legacy only| X["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 medium"]
- M --> V["verifier
- opus · fresh context"]
- E --> V
- SEC --> V
- V -->|CONFIRMED / REFUTED / INCONCLUSIVE| O
- ```
- | Role | Model | Default effort | Purpose |
- |---|---|---|---|
- | `scout` | haiku | low | Read-only repository reconnaissance |
- | `Explore` | haiku | low | Broad read-only search without inheriting the main model — legacy global install only ([why](./install/PLUGIN-INSTALL.md#roles-the-plugin-ships)) |
- | `plan-verifier` | opus | medium | Pre-approval Plan challenge: `READY` or structured `REVISE` |
- | `security-reviewer` | opus | high | Read-only security evidence before approval |
- | `mech-executor` | sonnet | low | Fully specified mechanical repetition |
- | `executor` | sonnet | medium | Approved implementation requiring local judgment |
- | `verifier` | opus | medium | Fresh-context outcome falsification after implementation |
- | `security-executor` | opus | medium | Approved security-sensitive implementation |
- 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` never below `high`. Model routing stays fixed;
- per Claude Code's documentation, `CLAUDE_CODE_EFFORT_LEVEL`, when set, overrides
- both ([evidence](./benchmarks/effort-selection/README.md)).
- 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](https://github.com/miyago9267/pilotfish-codex/pull/14)
- by [@miyago9267](https://github.com/miyago9267). See the
- [design details](./docs/design.md#interaction-shape-before-worker-routing).
- 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](./templates/claude-md.orchestration.md) and
- explained in the [design rationale](./docs/design.md).
- > ⚠️ **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.
- ```text
- 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](./benchmarks/spontaneous-dispatch/README.md)
- and [`cue-free-tui.json`](./benchmarks/spontaneous-dispatch/cue-free-tui.json).
- They are behavioral observations, not a dispatch rate or proof of the active
- system-prompt bytes.
- ## Install
- ### Plugin for macOS and Linux
- Use the [Plugin install guide](./install/PLUGIN-INSTALL.md) for native
- user-scope marketplace commands, migration from global v1, update,
- disable/enable, uninstall, and rollback. The Plugin 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](https://code.claude.com/docs/en/setup#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 the Plugin 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:
- ```bash
- git clone --branch v1.5.0 --depth 1 https://github.com/Nanako0129/pilotfish.git
- cd pilotfish
- claude
- ```
- ```text
- 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](./templates/agents/), the
- > [policy template](./templates/claude-md.orchestration.md), and the
- > [install runbook](./install/AGENT-INSTALL.md) before approving writes. Do not
- > bypass WebFetch prompt-injection protection to install from a mutable raw URL.
- | Target | Installed change | Reversible |
- |---|---|---|
- | `settings.json` | Adds missing `model` and `fallbackModel`; conditionally extends an existing `availableModels` allowlist | Restores or removes `model`; `fallbackModel` is removable, while allowlist additions remain unless requested |
- | `agents/` | Eight role-agent files | Yes |
- | `CLAUDE.md` | One versioned `pilotfish:begin/end` policy block | Yes |
- 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](./install/AGENT-INSTALL.md).
- ## Operate
- | Task | Where to go |
- |---|---|
- | Install, update, disable, or remove the macOS and Linux Plugin | [Plugin guide](./install/PLUGIN-INSTALL.md) |
- | Tune models, effort, delegation, or managed settings | [Usage guide](./docs/usage.md) |
- | Activate pilotfish for a task or session | [Install `/pilotfish` or the CLI wrapper](./install/ACTIVATION-INSTALL.md) |
- | Update an existing install | [Runbook: Updating an existing install](./install/AGENT-INSTALL.md#updating-an-existing-install) |
- | Review release changes | [CHANGELOG.md](./CHANGELOG.md) |
- | Disable pilotfish for one project | Use a separate `CLAUDE_CONFIG_DIR`; details are in the [usage guide](./docs/usage.md#disable-update-or-uninstall) |
- | Uninstall safely | [Runbook: Uninstall](./install/AGENT-INSTALL.md#uninstall) |
- To delegate uninstall to Claude Code:
- ```text
- 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
- | Topic | Document |
- |---|---|
- | Daily use and troubleshooting | [docs/usage.md](./docs/usage.md) · [繁體中文](./docs/usage.zh-TW.md) |
- | Architecture and policy decisions | [docs/design.md](./docs/design.md) |
- | Model economics and source research | [docs/research.md](./docs/research.md) · [繁體中文](./docs/research.zh-TW.md) |
- | Real long-session field report | [docs/field-report-tokscale-2026-07.zh-TW.md](./docs/field-report-tokscale-2026-07.zh-TW.md) |
- | Behavioral evidence and claim limits | [dispatch brake](./benchmarks/dispatch-brake/README.md) · [spontaneous dispatch](./benchmarks/spontaneous-dispatch/README.md) · [Baton activation](./benchmarks/baton-dispatch-effect/README.md) · [prompt compression](./benchmarks/prompt-compression/README.md) · [verifier boundary](./benchmarks/verifier-boundary/README.md) |
- | Contribution and evidence contracts | [CONTRIBUTING.md](./CONTRIBUTING.md) |
- ## Project
- pilotfish is MIT licensed. Behavioral compatibility claims require paid model
- runs, fresh verification, and maintained evidence; sponsorship helps fund those
- gates.
- [](https://www.patreon.com/cw/Nanako0129/membership)
- [License](./LICENSE) · [Contributing](./CONTRIBUTING.md)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.