hooks— hook

cc-fleet — plug any third-party model into Claude Code's Dynamic Workflows, Agent Teams, and Subagents

<h1 align="center">🚢 cc-fleet</h1>

<p align="center"><strong>🤖 Plug any third-party model into Claude Code's ⚙️ Dynamic Workflows, 👥 Agent Teams, and ⚡ Subagents — from DeepSeek · GLM · Kimi · Qwen … to your Codex subscription, with your main session's auth untouched; no Claude subscription needed to run a full Claude Code on any provider 🚀</strong></p>

<div align="center">

English · 简体中文

</div>

Claude Code's multi-agent orchestration — Dynamic Workflows, Agent Teams, Subagents — only runs Anthropic's own models. cc-fleet lets any model with an Anthropic- or OpenAI-compatible API, even your Codex subscription, join as a workflow leaf, a long-lived teammate, or a one-shot subagent — scheduled by your main session, with the same identity and capabilities as a native Claude agent.

Every third-party worker is a real claude process with its LLM backend swapped to the provider, so Claude Code drives it exactly like a native agent. Your main session's own auth (OAuth subscription or API key) is untouched, and provider keys never enter env, argv, or shell history — zero leak risk.

Two steps to get going: one-line install, register a provider. Then state your intent in Claude Code with /workflow, /team, or /subagent — or just describe the task in plain language, and Claude figures out the rest.

No Claude subscription? ccf run <provider> starts an interactive session driven by that provider — the same `claude` you know, just running on the provider's model.

cc-fleet can be driven from Codex too: a Codex plugin gives a Codex session the same fan-out — cc-fleet subagent and cc-fleet workflow, with the claude engine as the worker. (Teammates stay Claude-Code-only.)

Install

0. Install Claude Code first — cc-fleet drives the official claude CLI, so install it if you don't have it yet (skip if claude is already on your PATH):

macOS / Linux:

curl -fsSL https://claude.ai/install.sh | bash

Windows (PowerShell):

irm https://claude.ai/install.ps1 | iex

1. Install cc-fleet with the one-line script (recommended) — one command does it all: downloads and verifies the CLI, puts it on your PATH (with a ccf alias, so ccf launches it from then on), and installs the Claude Code plugin (skill + session hook) via the marketplace. Ready to use right after:

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/ethanhq/cc-fleet/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/ethanhq/cc-fleet/main/install.ps1 | iex

Codex plugin — to drive cc-fleet from a Codex session, after the install above run codex plugin marketplace add ethanhq/cc-fleet then codex plugin add cc-fleet.

Other channels (npm / go install / Releases / source) and adding the Claude Code plugin, installer overrides, and requirements & maintenance live in [Install & maintenance](docs/install.md).

Common commands:

ccf                      # open the interactive TUI
ccf doctor               # health check: dependencies, providers, plugin status
ccf update               # self-update by install channel + refresh the plugin
ccf uninstall --all      # remove the binary and plugin too

Once installed, run ccf to register a provider and start delegating.

Quickstart

<table> <tr> <td width="50%" valign="top"> <div align="center">

🔌 Provider management — one API key, connected

<img src="docs/assets/demo-provider.webp" alt="provider management demo" width="100%" />

</div>

1. `ccf` opens the TUI; choose Add provider
2. Pick any Anthropic / OpenAI-compatible vendor
3. Enter the API key and default model; optionally an effort level and a Claude permission mode
4. Save and go; add more models and toggle them in the list, s sets the default, d deletes
5. (Optional) Add Codex: reuse an existing OAuth, or log in fresh

</td> <td width="50%" valign="top"> <div align="center">

🖥️ `ccf run` — run Claude Code on any provider

<img src="docs/assets/demo-run.webp" alt="ccf run demo" width="100%" />

</div>

1. `ccf run` launches an interactive `claude` on your default provider; ccf run <provider> picks one
2. All tools, the full REPL; no Anthropic subscription, your main session's login untouched
3. Switch anytime mid-session: /model for the model, /effort for thinking effort, Shift+Tab for permission mode

</td> </tr> <tr> <td width="50%" valign="top"> <div align="center">

⚙️ Dynamic Workflows — the same orchestration API as native workflows

<img src="docs/assets/demo-workflow.webp" alt="dynamic workflow demo" width="100%" />

</div>

1. `/workflow` to kick it off, or just tell Claude: "map each module with deepseek, glm drafts an audit checklist per module, gpt synthesizes"
2. Claude writes the JS script and runs it in the background — no tokens off your main session
3. `workflow wait` blocks until it finishes — event-driven, no polling
4. The TUI board shows every leaf and phase live — x to hold / r to rerun a single leaf or a whole phase

</td> <td width="50%" valign="top"> <div align="center">

👥 Agent Teams — native multi-agent collaboration in tmux panes

<img src="docs/assets/demo-team.webp" alt="agent team demo" width="100%" />

</div>

1. `/team` to kick it off, or just tell Claude: "start a glm and a deepseek teammate, then compare their strengths"
2. Each teammate is a real `claude` process working live in a side tmux pane — mix providers in one team, hand follow-ups across turns
3. The TUI board shows each teammate's full inbox and status; h hides / s shows a pane — split in the foreground or run in the background

</td> </tr> <tr> <td width="50%" valign="top"> <div align="center">

⚡ Subagents — the lightest one-shot delegation

<img src="docs/assets/demo-subagent.webp" alt="subagent demo" width="100%" />

</div>

1. `/subagent` to kick it off, or just tell Claude: "fan out kimi, qwen, and glm over these three files in parallel"
2. Claude runs the models and collects results synchronously — dispatch as many in parallel as you like
3. `slim-ro` read-only mode: let a provider analyze your repo safely, without touching code
4. The TUI board shows each job's prompt, answer, and spend

</td> <td width="50%" valign="top"> <div align="center">

📊 The TUI board — your whole fleet on one screen

<img src="docs/assets/demo-tui.webp" alt="TUI board demo" width="100%" />

</div>

1. After `ccf` launches, press `Tab` for the Agents Board — every Workflow / Team / Subagent laid out by project → session
2. Open any one for detail: a Workflow's run → phase → leaf progress tree, a Team's teammate inbox, each drilling into prompt, answer, and spend
3. Act inside the board: x / r to stop or rerun, p to pin against cleanup, c to clear finished, d to delete, h / s to hide or show a pane
4. Finished teams stay on record; the UI follows your system light / dark theme

</td> </tr> </table>

Deep dive

cc-fleet's capabilities fall into two groups:

• Three delegation lanes (Workflow / Agent Team / Subagent) — scheduled automatically by Claude: say what you want and the skills pick the lane and the model for you, no manual choice.
• Provider and `ccf run` — tools you configure and use directly.

⚙️ Dynamic Workflows

<table> <tr> <td width="50%" align="center"><img src="docs/assets/workflow-board.webp" width="100%" /><br/>_{Agents Board: the phase → leaf tree}</td> <td width="50%" align="center"><img src="docs/assets/workflow-leaf.webp" width="100%" /><br/>_{drill into one leaf: full prompt and synthesized output}</td> </tr> </table>

Orchestration API: multi-phase orchestration lives in a JavaScript file, with an API identical to Claude Code's native Workflow tool — agent() starts a node, parallel() fans out, pipeline() chains a flow. The one difference is that agent() takes a provider option to assign each node's model, so different vendors mix and run in parallel within a single run:

const meta = {
  name: "api audit",
  description: "map endpoints, then draft audit checklists",
  phases: [{ title: "map" }, { title: "build" }, { title: "judge" }],
};

phase("map");
const maps = (await parallel(
  ["auth", "billing", "users"].map((m) =>
    () => agent("List the exported endpoints in module " + m, { provider: "deepseek" }))
)).filter(Boolean);

phase("build");
const checklists = await pipeline(maps,
  (endpoints, _, i) => agent("Draft an audit checklist:\n" + endpoints,
                             { provider: "glm", label: "build:" + i }));

phase("judge");
const verdict = await agent("Pick the strongest one and say why:\n" + checklists.join("\n---\n"),
                            { provider: "claude", model: "opus", label: "judge" });
return { checklists, verdict };

Running and managing: once kicked off, the whole run executes in a background engine, managed by a small command set. Runs are journaled by content hash, and budgets cap spend in USD or tokens:

RUN=$(ccf workflow run audit.js)            # starts in the background, prints the run id
ccf workflow wait "$RUN" --timeout 10m      # blocks until done, event-driven
ccf workflow stop "$RUN" --leaf build:1     # hold a single leaf (run keeps going)
ccf workflow restart "$RUN" --leaf build:1  # resume it
ccf workflow run audit.js --resume "$RUN"   # replay the journal, finished leaves hit cache

Holding and restarting: ccf workflow stop --leaf / --phase doesn't fail the run — it just pauses the named node: the run keeps going and other nodes carry on, until you restart it to run again. If every node currently running gets paused, the whole run settles into a parked state that needs you to step in before it continues.

Wait without polling: ccf workflow wait blocks until the run ends, then exits — drop it in the background and come back when it exits, no repeated checking. The exit code states the outcome: 0 succeeded, 1 failed, 3 parked and waiting, 124 wait timed out (run still going), 130 interrupted.

Budget-adaptive: budget.spent() / budget.remaining() are readable live inside the script (USD or tokens), so a workflow can decide for itself whether to dispatch another batch.

Mixing in your own subscription: a node assigned provider: "claude" runs on your own Claude login — the judge above uses your subscription, not a provider key, which suits a synthesis-and-finish node.

👥 Agent Teams

<table> <tr> <td width="50%" align="center"><img src="docs/assets/team-panes.webp" width="100%" /><br/>_{four teammates working side by side in tmux panes}</td> <td width="50%" align="center"><img src="docs/assets/team-board.webp" width="100%" /><br/>_{a teammate's overview / messages / output on the board}</td> </tr> </table>

Prerequisites: Agent Team is the only lane that needs setup up front, and it doesn't support Windows yet. Before you use it:

1. Claude Code ≥ 2.1.278, the terminal `claude`, inside tmux or iTerm2 (tmux new-session -s work) so teammate panes can show up alongside you. The Claude desktop app, claude -p and SDK sessions have no agent team — there, Claude uses subagents and workflows instead;
2. Run the one-time setup: the first time you start ccf with a provider enabled, it offers to do this for you — or run it yourself, then restart claude:

cc-fleet teammate setup --yes --teammate-mode tmux

It installs a small launcher (~/.config/cc-fleet/bin/claude-teammate), one ccf-<provider> agent type per provider (~/.claude/agents/ccf-*.md), and in ~/.claude/settings.json turns on agent teams and points CLAUDE_CODE_TEAMMATE_COMMAND at the launcher; --teammate-mode tmux makes teammates open as split panes (an existing auto / tmux / iterm2 is left alone). Without --yes it only lists what it would change. cc-fleet teammate setup --remove --yes undoes it.

How they collaborate: each teammate is a native Claude Code teammate — Claude starts it with the Agent tool using a ccf-<provider> agent type (ccf-glm.strong for the strong slot), assigns work with native SendMessage, and the launcher runs that teammate's claude on the provider. Teammates stay alive across turns so you can keep adding tasks. One team can use several providers at once, then have one teammate gather and compare the results. Before each teammate, Claude runs cc-fleet teammate check, and a plugin hook blocks a provider teammate that would silently run on Claude instead.

Permission inheritance: Claude Code hands each teammate your main session's permission posture (plan / acceptEdits / default), exactly as for its own teammates.

Park and restore: ccf hide <name>@<team> tucks a teammate's pane out of the way while the process keeps running — messages and context are never lost — and ccf show brings it back. Claude Code closes its teammates when you exit claude; to end one early, Claude asks it to shut down or stops it. ccf teardown is for leftovers — say, after the lead crashed: it kills only provider teammates it can verify (pane, exact command line, process start time), and never touches your lead, native teammates, or Claude Code's team files. ccf ps lists them with a state (running, orphaned, failed, bypassed).

Outside tmux: with teammateMode set to tmux, Claude Code runs the teammates on its own background tmux server (claude-swarm-<pid>), exactly the same flow with the pane just not on screen; ccf ps --json shows the tmux_socket_path to attach with tmux -S <path> attach.

⚡ Subagents

<table> <tr> <td width="50%" align="center"><img src="docs/assets/subagent-fanout.webp" width="100%" /><br/>_{fan out three subagents in parallel from one ask}</td> <td width="50%" align="center"><img src="docs/assets/subagent-board.webp" width="100%" /><br/>_{the job list and one job's detail}</td> </tr> </table>

Three run modes: the default slim sends the model a trimmed system prompt with a narrowed tool set, so the first request is much smaller than a full session — cheaper and faster on metered providers. --profile slim-ro is read-only, with tools cut to inspection only (Bash / Glob / Grep / Read / Skill) and no creating, editing, or deleting files, so a provider can read code and check logs without touching your workspace. Use --profile full when you need full-session capability.

Tool trimming and parallelism: --tools takes a comma-separated list to set exactly which tools are open (a replacement, not an addition to the defaults), --skills=false turns off the Skill tool, and --mcp controls whether the host MCP config carries over. A subagent builds no team, takes no pane, and holds no locks, so running many against one provider doesn't interfere — ideal for large batches in parallel.

Background and wake-up: add --background to send a long job to the background, then ccf subagent-status <job> --wait blocks until it's done and wakes the session that launched it — no repeated checking. Each job is capped by spend (USD), turns, and timeout, and a failure returns a fixed error_code your program can branch on.

Structured result: with --json you get a result object with fixed fields, easy for scripts to parse — besides the answer text it includes the model id that actually responded, the call's spend, token usage, turns, and session_id.

Run key nodes on your own subscription: as with Workflow, setting the provider to the reserved name claude (ccf subagent claude --model opus …) uses your own Claude login and bills your subscription — good for a synthesis-and-finish node, not large parallel batches.

🧩 Drive from Codex

cc-fleet plugs into OpenAI Codex too: a Codex plugin lets a Codex session fan out the same provider workers — one-shot or batch subagents (cc-fleet subagent) and multi-phase JS workflows (cc-fleet workflow), each a real claude process on the provider's model. Install it with codex plugin marketplace add ethanhq/cc-fleet then codex plugin add cc-fleet (the cc-fleet and claude binaries install separately). The teammate lane stays Claude-Code-only; from Codex you get the subagent and workflow fan-out.

🔌 Provider management

<table> <tr> <td width="50%" align="center"><img src="docs/assets/provider-presets.webp" width="100%" /><br/>_{presets for many vendors}</td> <td width="50%" align="center"><img src="docs/assets/provider-config.webp" width="100%" /><br/>_{set each tier's model, effort, and permission}</td> </tr> </table>

Broad compatibility: works with any Anthropic- or OpenAI-compatible API endpoint — the former includes DeepSeek, Kimi, GLM, Qwen, and more; the latter Groq, Together, Fireworks, a local vLLM, and OpenAI itself. Common vendors ship as presets — select one and the endpoint and protocol are filled in, no manual entry; for anything not listed, pick Custom and enter the address.

Model tiers: each provider can carry default / strong / fast model slots, each separately taggable with 1M context and a reasoning effort. So Claude just asks for "the strong model" — no hardcoded model IDs. ccf default <provider> sets the fleet-wide default provider, and any call that doesn't name one goes to it.

Multi-key rotation: one provider can hold several API keys, rotated by off / round_robin / random to spread quota and avoid rate limits.

API key protection: a key is fetched only at request time, emitted once, and never written into environment variables, command-line arguments, or shell history. A worker keeps the main session's credentials out two ways: its environment is cleared of Anthropic credentials and cloud-backend switches, and its provider profile blanks the same keys in case your Claude Code settings set them (organization-managed settings are the one layer a profile can't override), so the two never leak into each other. On disk it's saved 0600, readable only by you, or handed to pass, 1Password, Vault, or your OS keyring; every UI and log shows the key masked (sk-…238).

Codex (ChatGPT subscription): one device-code login and your ChatGPT subscription becomes a regular provider — usable across Workflow / Team / Subagent / run.

[!WARNING] Codex is unofficial. Reusing a ChatGPT subscription outside the codex CLI may violate OpenAI's terms, and ccf codex login asks you to confirm first. The OAuth token lives only inside the local conversion daemon; cc-fleet keeps its own login chain and never writes the codex CLI's auth (without its own login, the codex provider on the default credential rides it read-only).

🖥️ ccf run

<table> <tr> <td width="50%" align="center"><img src="docs/assets/run-launch.webp" width="100%" /><br/>_{one-line launch: ccf run / ccf run codex}</td> <td width="50%" align="center"><img src="docs/assets/run-session.webp" width="100%" /><br/>_{inside, it's a full claude — here on gpt-5.5}</td> </tr> </table>

Launch: ccf run <provider> opens an interactive claude on the named provider; with no provider (ccf run) it resolves to the fleet-wide default.

ccf run deepseek        # an interactive claude, on DeepSeek, billing the provider key

It's just native claude: ccf run adds no extra process layer — it replaces itself with claude, cc-fleet steps out entirely, and from then on it's a plain claude process whose feel and exit behavior match typing claude yourself.

Credentials isolated automatically: even if you run it from inside a logged-in Claude Code session, it first clears any leftover Anthropic auth from the environment and uses the chosen provider's auth instead — so billing lands on the provider's key, never your own subscription.

Flags:

• --model strong / fast — override the default with the provider's strong or fast model
• --permission-mode — set the permission posture
• -- <claude args> — everything after is passed through verbatim to the underlying claude

[!NOTE] This lane is for hands-on interactive use: it needs a real terminal and doesn't support pipes or redirects — for non-interactive, one-shot output use a Subagent instead.

Documentation

• [CLI reference & advanced usage](docs/cli.md) — every command, flag, and envelope.
• [Writing workflows](docs/workflows.md) — the JS scripting API for the workflow lane.
• [Architecture](docs/architecture.md) — how the teammate launcher, key safety, the conversion daemon, and the workflow engine actually work.
• ccf <cmd> --help — always authoritative.

Contributing

PRs are very welcome — bug fixes, new provider presets, docs, tests, features. Please read the [contribution guide](.github/CONTRIBUTING.md) first; a few house rules:

• UI changes and bug fixes need a screenshot or GIF in the PR.
• *AI-assisted*** commits credit the tool with a Co-Authored-By trailer.
• *Fully AI-authored*** PRs add an autonomous-PR marker at the bottom of the PR body.

License

Apache-2.0.