cc-fleet

English · 简体中文

---

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.

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

🔌 Provider management — one API key, connected

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

🖥️ ccf run — run Claude Code on any provider

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

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

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

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

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

⚡ Subagents — the lightest one-shot delegation

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

📊 The TUI board — your whole fleet on one screen

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

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

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

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