Skip to content
Back to search

pilotfish

MarketplaceWorks with Claude CodeGitHub

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/nanako0129-pilotfish/badge.svg)](/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)

  1. {
  2. "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
  3. "name": "pilotfish",
  4. "owner": {
  5. "name": "Nanako0129",
  6. "url": "https://github.com/Nanako0129"
  7. },
  8. "description": "Marketplace for the pilotfish macOS and Linux Claude Code Plugin.",
  9. "plugins": [
  10. {
  11. "name": "pilotfish",
  12. "source": "./plugin",
  13. "version": "1.5.0",
  14. "description": "Hook-based ambient orchestration for macOS and Linux Claude Code.",
  15. "category": "productivity",
  16. "tags": [
  17. "orchestration",
  18. "subagents",
  19. "delegation"
  20. ]
  21. }
  22. ]
  23. }
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)

  1. # pilotfish 🐟
  2. > Small, fast role agents handle volume work while the frontier main session
  3. > keeps planning, approval, integration, and final judgment.
  4. **pilotfish** is a multi-model orchestration policy for
  5. [Claude Code](https://code.claude.com). The [macOS and Linux Plugin](./install/PLUGIN-INSTALL.md)
  6. adds hook-based ambient activation; the global configuration install remains a
  7. legacy alternative. The policy uses the `opus` family for the main session,
  8. Sonnet for bounded execution, Haiku for reconnaissance, and fresh Opus contexts
  9. for risk-triggered review.
  10. [繁體中文](./README.zh-TW.md)
  11. ## Contents
  12. - [Why](#why)
  13. - [How it works](#how-it-works)
  14. - [Install](#install)
  15. - [Operate](#operate)
  16. - [Documentation](#documentation)
  17. - [Project](#project)
  18. ## Why
  19. Most coding-session tokens are spent on search, repetitive edits, tests, and
  20. documentation rather than frontier judgment. pilotfish routes those bounded
  21. paths to cheaper roles while keeping the main session accountable and using
  22. fresh-context reviewers at material acceptance boundaries.
  23. New installs default to the `opus` alias; Fable remains an explicit
  24. `/model fable` choice. This is a cost-aware default, not a claim that one model
  25. wins every task. The rationale and measurements live in
  26. [research](./docs/research.md), the [design notes](./docs/design.md), and
  27. [#23](https://github.com/Nanako0129/pilotfish/issues/23).
  28. | Host or use case | Project |
  29. |---|---|
  30. | Claude Code global policy | This repository |
  31. | Claude Code with session-scoped GPT routing | [remora](https://github.com/Nanako0129/remora-cc) |
  32. | Grok Build | [pilotfish-grok](https://github.com/Nanako0129/pilotfish-grok) |
  33. | Codex CLI | [pilotfish-codex](https://github.com/miyago9267/pilotfish-codex) |
  34. ## How it works
  35. The Plugin packages the policy and namespaced roles under Claude Code's
  36. native Plugin lifecycle. The legacy global install uses these direct targets:
  37. | Layer | Installed target | Responsibility |
  38. |---|---|---|
  39. | Machine | `~/.claude/settings.json` | Main-model alias and fallback chain |
  40. | Roles | `~/.claude/agents/*.md` | Model, effort, and capability boundary for each role |
  41. | Policy | `~/.claude/CLAUDE.md` | Dispatch, approval, verification, and long-run behavior |
  42. If `CLAUDE_CONFIG_DIR` is set, all `~/.claude/` paths above move under that
  43. configuration root.
  44. ```mermaid
  45. flowchart TD
  46. U["You"] --> I
  47. subgraph MAIN["main session — opus family alias"]
  48. I["Interaction shape
  49. execute / explore_then_plan / co_discover"]
  50. I --> O
  51. O["Orchestrator
  52. plan / decide / spec / review"]
  53. end
  54. O -->|recon| S["scout
  55. haiku · effort low"]
  56. O -.->|recon, legacy only| X["Explore
  57. haiku · effort low"]
  58. O -->|Plan challenge| PV["plan-verifier
  59. opus · read-only"]
  60. PV -->|READY / REVISE| O
  61. O -->|mechanical spec| M["mech-executor
  62. sonnet · effort low"]
  63. O -->|judgment work| E["executor
  64. sonnet · effort medium"]
  65. O -->|security evidence| SR["security-reviewer
  66. opus · read-only"]
  67. SR --> O
  68. O -->|approved security work| SEC["security-executor
  69. opus · effort medium"]
  70. M --> V["verifier
  71. opus · fresh context"]
  72. E --> V
  73. SEC --> V
  74. V -->|CONFIRMED / REFUTED / INCONCLUSIVE| O
  75. ```
  76. | Role | Model | Default effort | Purpose |
  77. |---|---|---|---|
  78. | `scout` | haiku | low | Read-only repository reconnaissance |
  79. | `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)) |
  80. | `plan-verifier` | opus | medium | Pre-approval Plan challenge: `READY` or structured `REVISE` |
  81. | `security-reviewer` | opus | high | Read-only security evidence before approval |
  82. | `mech-executor` | sonnet | low | Fully specified mechanical repetition |
  83. | `executor` | sonnet | medium | Approved implementation requiring local judgment |
  84. | `verifier` | opus | medium | Fresh-context outcome falsification after implementation |
  85. | `security-executor` | opus | medium | Approved security-sensitive implementation |
  86. Each role's effort is a recommended default, not a fixed setting. The policy asks
  87. the main session to pass the Agent tool's `effort` (Claude Code 2.1.292 or newer)
  88. for each delegation, chosen from the task's difficulty, ambiguity and cost of
  89. error: a lookup can stay at `low` while a hard investigation runs at `high`. The
  90. reviewers have a floor at their defaults: `verifier` and `plan-verifier` never
  91. below `medium`, `security-reviewer` never below `high`. Model routing stays fixed;
  92. per Claude Code's documentation, `CLAUDE_CODE_EFFORT_LEVEL`, when set, overrides
  93. both ([evidence](./benchmarks/effort-selection/README.md)).
  94. Before Baton or direct/delegated routing, pilotfish chooses the first matching
  95. interaction shape: `co_discover` while the outcome or acceptance is unclear;
  96. otherwise `explore_then_plan` when a clear direction is broad or high-impact;
  97. otherwise `execute` for a clear bounded outcome. This changes how the main
  98. session collaborates; it does not bypass risk or approval gates. The design is
  99. adapted from
  100. [pilotfish-codex's adaptive intent routing](https://github.com/miyago9267/pilotfish-codex/pull/14)
  101. by [@miyago9267](https://github.com/miyago9267). See the
  102. [design details](./docs/design.md#interaction-shape-before-worker-routing).
  103. Small, stable work stays in the main session. Larger work is split only when a
  104. bounded role has a stable contract and delegation has positive net benefit.
  105. Risk, not file count, triggers independent review. The exact lifecycle is
  106. defined in the [policy template](./templates/claude-md.orchestration.md) and
  107. explained in the [design rationale](./docs/design.md).
  108. > ⚠️ **Automatic delegation is not guaranteed.** Higher-priority Claude Code
  109. > instructions can suppress Agent dispatch, and user-level `CLAUDE.md` cannot
  110. > override them. When the lifecycle matters, include the following request.
  111. ```text
  112. Use pilotfish. Follow its dispatch brake: keep direct work in the main session
  113. and call the named agents only when the policy selects delegation.
  114. ```
  115. The bounded results and claim limits are recorded in the
  116. [spontaneous-dispatch benchmark](./benchmarks/spontaneous-dispatch/README.md)
  117. and [`cue-free-tui.json`](./benchmarks/spontaneous-dispatch/cue-free-tui.json).
  118. They are behavioral observations, not a dispatch rate or proof of the active
  119. system-prompt bytes.
  120. ## Install
  121. ### Plugin for macOS and Linux
  122. Use the [Plugin install guide](./install/PLUGIN-INSTALL.md) for native
  123. user-scope marketplace commands, migration from global v1, update,
  124. disable/enable, uninstall, and rollback. The Plugin targets macOS
  125. and Linux. Linux requires Ubuntu 20.04+, Debian 10+, or Alpine Linux 3.19+ and
  126. an otherwise-working officially supported Claude Code installation, per the
  127. [official system requirements](https://code.claude.com/docs/en/setup#system-requirements)
  128. (checked 2026-08-22). macOS with Claude Code 2.1.239 is live-observed. Linux is
  129. contract-qualified only; it has not been tested, verified, or live-observed.
  130. Windows is excluded. SessionStart hooks are required, the Plugin must not
  131. coexist with the legacy global install, and the Plugin does not claim stable
  132. reliability, cross-version compatibility, or runtime namespace-collision proof.
  133. ### Legacy global install
  134. Clone the reviewed release, start Claude Code from that checkout, and ask it to
  135. follow the local runbook:
  136. ```bash
  137. git clone --branch v1.5.0 --depth 1 https://github.com/Nanako0129/pilotfish.git
  138. cd pilotfish
  139. claude
  140. ```
  141. ```text
  142. Read the local file install/AGENT-INSTALL.md in the current checkout and follow
  143. it to install pilotfish into my global Claude Code configuration. Show me the
  144. full plan of changes and get my approval before writing anything.
  145. ```
  146. > **Runtime requirement:** Claude Code **2.1.219 or newer**. Restart Claude Code
  147. > after installation so the agent directory and model setting are reloaded.
  148. > ⚠️ **Trust boundary:** the policy loads into every future session. Review the
  149. > pinned checkout, the [agent templates](./templates/agents/), the
  150. > [policy template](./templates/claude-md.orchestration.md), and the
  151. > [install runbook](./install/AGENT-INSTALL.md) before approving writes. Do not
  152. > bypass WebFetch prompt-injection protection to install from a mutable raw URL.
  153. | Target | Installed change | Reversible |
  154. |---|---|---|
  155. | `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 |
  156. | `agents/` | Eight role-agent files | Yes |
  157. | `CLAUDE.md` | One versioned `pilotfish:begin/end` policy block | Yes |
  158. The installer is idempotent and shows a merge plan before writing. Human-readable
  159. steps, backups, collision handling, verification, updates, and uninstall are all
  160. in [install/AGENT-INSTALL.md](./install/AGENT-INSTALL.md).
  161. ## Operate
  162. | Task | Where to go |
  163. |---|---|
  164. | Install, update, disable, or remove the macOS and Linux Plugin | [Plugin guide](./install/PLUGIN-INSTALL.md) |
  165. | Tune models, effort, delegation, or managed settings | [Usage guide](./docs/usage.md) |
  166. | Activate pilotfish for a task or session | [Install `/pilotfish` or the CLI wrapper](./install/ACTIVATION-INSTALL.md) |
  167. | Update an existing install | [Runbook: Updating an existing install](./install/AGENT-INSTALL.md#updating-an-existing-install) |
  168. | Review release changes | [CHANGELOG.md](./CHANGELOG.md) |
  169. | Disable pilotfish for one project | Use a separate `CLAUDE_CONFIG_DIR`; details are in the [usage guide](./docs/usage.md#disable-update-or-uninstall) |
  170. | Uninstall safely | [Runbook: Uninstall](./install/AGENT-INSTALL.md#uninstall) |
  171. To delegate uninstall to Claude Code:
  172. ```text
  173. Read the local install/AGENT-INSTALL.md, resolve the Claude Code configuration
  174. root exactly as Step 0 specifies, and follow its Uninstall section. In that
  175. configuration root, remove the eight pilotfish agent files and policy block.
  176. Show me the full removal and settings-restoration plan and get my approval
  177. before writing.
  178. ```
  179. ## Documentation
  180. | Topic | Document |
  181. |---|---|
  182. | Daily use and troubleshooting | [docs/usage.md](./docs/usage.md) · [繁體中文](./docs/usage.zh-TW.md) |
  183. | Architecture and policy decisions | [docs/design.md](./docs/design.md) |
  184. | Model economics and source research | [docs/research.md](./docs/research.md) · [繁體中文](./docs/research.zh-TW.md) |
  185. | Real long-session field report | [docs/field-report-tokscale-2026-07.zh-TW.md](./docs/field-report-tokscale-2026-07.zh-TW.md) |
  186. | 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) |
  187. | Contribution and evidence contracts | [CONTRIBUTING.md](./CONTRIBUTING.md) |
  188. ## Project
  189. pilotfish is MIT licensed. Behavioral compatibility claims require paid model
  190. runs, fresh verification, and maintained evidence; sponsorship helps fund those
  191. gates.
  192. [![Support pilotfish on Patreon](https://img.shields.io/badge/Support_on_Patreon-FF424D?style=for-the-badge&logo=patreon&logoColor=white)](https://www.patreon.com/cw/Nanako0129/membership)
  193. [License](./LICENSE) · [Contributing](./CONTRIBUTING.md)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.