cc-fleet

module

v0.2.1 Latest Latest Go to latest Published: Jun 11, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/ethanhq/cc-fleet

Links

Open Source Insights

README ¶

🚢 cc-fleet

🤖 Spawn any provider LLM — DeepSeek · GLM · Qwen · Kimi · MiniMax … — as real Claude Code teammates or ⚡ one-shot subagents 🚀

Provider workers are real Claude Code teammates — driven exactly like native ones — with the LLM backend swapped to any provider that exposes an Anthropic-compatible API. Your main session's own auth (OAuth subscription or API key) is untouched; provider workers bill the provider API key via apiKeyHelper, and the key never enters env, argv, or shell history.

cc-fleet is a small Go CLI plus one Claude Code skill. The CLI manages per-provider profiles, dispatches API keys via apiKeyHelper, and spawns teammate sessions in tmux panes. The skill teaches Claude Code when to delegate work to those teammates.

Requirements

Claude Code (the claude CLI) on your PATH.
macOS, Linux, or Windows, amd64 or arm64. On Windows the one-shot subagent, workflow, and interactive cc-fleet run lanes plus the TUI run natively.
tmux — needed only for the live teammate lane (the teammate panes run in tmux), so that lane is unix/WSL only.
Teammate mode needs Claude Code's agent-teams enabled. Turn it on in your global ~/.claude/settings.json and restart Claude Code (cc-fleet also nudges you on first run):
```
{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }
```
The one-shot subagent mode and the interactive cc-fleet run work without it.

Quick Install

One-line (recommended)

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

npm (also the Windows install channel)

npm install -g @ethanhq/cc-fleet      # or run once: npx @ethanhq/cc-fleet

Binary only — also install the skill (see The skill) so Claude Code can use it. On Windows, install via npm or download the cc-fleet-windows-<arch>.zip from Releases (the one-line installer is unix-only).

go install

go install github.com/ethanhq/cc-fleet/cmd/cc-fleet@latest
ln -sf "$(go env GOPATH)/bin/cc-fleet" "$(go env GOPATH)/bin/ccf"   # optional ccf alias

Binary only — also install the skill (see The skill) so Claude Code can use it.

Prebuilt tarball — download from Releases:

tar -xzf cc-fleet-*.tar.gz && cd cc-fleet-*/ && ./install.sh

From source

git clone https://github.com/ethanhq/cc-fleet.git && cd cc-fleet && make install

[!NOTE] cc-fleet is a binary + a skill. The one-line installer and tarball set up both; npm, go install, and source install the binary only — add the skill via the plugin so Claude Code knows when to delegate to it.

Getting Started

Run cc-fleet (or the ccf alias) with no arguments to open the interactive TUI:

cc-fleet

In the TUI you register a provider — give it a name, its Anthropic-compatible base URL, a models endpoint, a default model, and paste the API key. The key is written 0600 under ~/.config/cc-fleet/secrets/ and is never passed via argv or shell history.

The config tree is created automatically on first save, so there is no separate init step. The TUI also lists your providers, lets you edit them, and manage multiple keys per provider.

Press tab to switch to the Agents Board — it shows every live teammate grouped by session → team, with its provider, model, pane, PID, health, and hidden state, plus a list of subagent jobs. From here you can hide (h) / show (s) a teammate pane or refresh (r).

Once at least one provider is registered, just talk to Claude Code in plain language. The skill reads your request and picks how to run the work — there are two execution modes.

Teammate mode — a long-lived provider worker on your team

"Spawn a deepseek teammate to refactor the parser package, then report back."

Runs the provider as a real Claude Code agent-team teammate:

Claude calls native TeamCreate; cc-fleet launches the provider's own claude process in a tmux pane.
Claude drives it with native SendMessage — you assign tasks, it works and reports back.
The teammate stays alive across turns, so you keep handing it follow-ups. Run several in parallel.
Your main session keeps its own auth — only the teammate pane bills the provider key (via apiKeyHelper).

[!NOTE] Teammate mode needs Claude Code's agent-teams enabled — see Requirements.

Start inside a tmux session so the teammates split into panes alongside your lead:

tmux new-session -s cc-fleet

Lead session on the left; a deepseek and a glm teammate in their own panes on the right — each a real claude process, driven by SendMessage exactly like a native teammate.

[!TIP] Not in tmux? cc-fleet runs the teammate in a detached cc-fleet-swarm-<team> server instead — same TeamCreate / SendMessage flow, the pane just isn't on screen. Attach with tmux -L cc-fleet-swarm-<team> attach to watch it.

Subagent mode — a one-shot headless call

"Use deepseek to summarize this 2,000-line log file."

cc-fleet subagent [provider] runs the provider model headless and returns the result synchronously — no pane, no team, no agent-teams. Ideal for one-off analysis and batch fan-out of independent tasks.

Flag	Use
`--background`	run detached; `cc-fleet subagent-status` checks it, `--wait` blocks until it settles
`--resume <id>`	continue a previous subagent (multi-turn)
`--max-budget-usd` / `--max-turns`	bound cost and runtime

[!NOTE] You never pick the mode by hand — Claude decides teammate vs subagent from the request, spawns the provider worker, and coordinates it for you.

Run a provider in your own session

Not delegation — this one is all you.

cc-fleet run deepseek                          # an interactive claude, on DeepSeek
cc-fleet run deepseek --dangerously-skip-permissions

cc-fleet run [provider] drops you straight into an interactive Claude Code session with the LLM backend swapped to the provider — the same claude you know, just on DeepSeek / GLM / Qwen / … and billing the provider key. Reach for a cheaper or different-jurisdiction model for your own day-to-day coding, not only for delegated work. --model overrides the default; --permission-mode / --dangerously-skip-permissions set the permission posture. No tmux, no agent-teams — just a terminal.

ChatGPT subscription as a provider (codex)

Have a Codex / ChatGPT subscription? Drive gpt-5.x with it too.

cc-fleet codex add && cc-fleet codex login

One codex add plus a device-code login turns the subscription into a regular provider — teammate, subagent, workflow leaf, or cc-fleet run, all answering through gpt-5.x. A local conversion daemon translates Claude's Anthropic calls to the OpenAI Responses API; the OAuth token stays inside the daemon (never in env, argv, or a profile), and cc-fleet keeps its own login so the codex CLI's auth is untouched. Unofficial — codex login asks for explicit confirmation; details in the CLI guide.

More example prompts

"Spawn a glm teammate and a deepseek teammate; have each summarize its model's strengths, then compare the two."
"Use deepseek to review the diff in internal/spawn and list any bugs you find."
"Fan out kimi, qwen, and glm subagents over these three files in parallel and collect the results."
"Spin up a deepseek teammate to port the test suite to table-driven form, then report back."

CLI & advanced usage

Claude drives the CLI for you, but every command also works by hand — multi-key rotation, hide/show, background/resumable subagents, secret backends, teardown order, and more. See CLI reference & advanced usage, or run cc-fleet <cmd> --help.

The skill

The binary is just the CLI. To teach Claude Code when to delegate, install the skill via the plugin (the one-line installer does this by default):

claude plugin marketplace add ethanhq/cc-fleet
claude plugin install cc-fleet@ethanhq

Contributing

PRs are very welcome — bug fixes, new provider recipes, docs, tests, and features. Please read the contribution guide 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.

A PR template is applied automatically when you open one.

License

Apache-2.0.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
cc-fleet command Command cc-fleet is the CLI entry point for the cc-fleet provider-profile manager.	Command cc-fleet is the CLI entry point for the cc-fleet provider-profile manager.
internal
ccver Package ccver locates the installed `claude` binary and reports its version.	Package ccver locates the installed `claude` binary and reports its version.
childenv Package childenv builds the environment handed to a child claude process that cc-fleet launches — a one-shot subagent (`claude -p`) or an interactive `run` session.	Package childenv builds the environment handed to a child claude process that cc-fleet launches — a one-shot subagent (`claude -p`) or an interactive `run` session.
codexproxy Package codexproxy hosts the local Anthropic-Messages <-> OpenAI-Responses conversion daemon that lets a Codex/ChatGPT subscription drive OpenAI models as a cc-fleet provider.	Package codexproxy hosts the local Anthropic-Messages <-> OpenAI-Responses conversion daemon that lets a Codex/ChatGPT subscription drive OpenAI models as a cc-fleet provider.
config Package config reads, writes, and validates ~/.config/cc-fleet/providers.toml.	Package config reads, writes, and validates ~/.config/cc-fleet/providers.toml.
diag Package diag is the --verbose diagnostic sink: a tiny injected logger that timestamps, redacts, and serializes step-trace lines.	Package diag is the --verbose diagnostic sink: a tiny injected logger that timestamps, redacts, and serializes step-trace lines.
doctor Package doctor implements the health checks behind `cc-fleet doctor`, split into a Core group (every run mode) and an Optional group (live teammates only — tmux).	Package doctor implements the health checks behind `cc-fleet doctor`, split into a Core group (every run mode) and an Optional group (live teammates only — tmux).
fileutil Package fileutil holds small file-system primitives shared across cc-fleet.	Package fileutil holds small file-system primitives shared across cc-fleet.
fingerprint Package fingerprint provides the per-cc-version spawn template (env vars + flag list) that cc-fleet replays when launching provider teammates.	Package fingerprint provides the per-cc-version spawn template (env vars + flag list) that cc-fleet replays when launching provider teammates.
homedir Package homedir is the single home-directory resolver for every package that roots config state under the user's home (~/.config/cc-fleet, ~/.claude).	Package homedir is the single home-directory resolver for every package that roots config state under the user's home (~/.config/cc-fleet, ~/.claude).
ids Package ids validates cc-fleet identifiers (team names, member names) that flow into filesystem paths, tmux labels, inbox file names, and agent IDs.	Package ids validates cc-fleet identifiers (team names, member names) that flow into filesystem paths, tmux labels, inbox file names, and agent IDs.
leadsession Package leadsession detects the parent Claude Code session for commands that are launched from a Claude Bash tool but do not otherwise have a team context.	Package leadsession detects the parent Claude Code session for commands that are launched from a Claude Bash tool but do not otherwise have a team context.
models Package models caches and refreshes per-provider model lists fetched from each provider's `/v1/models` endpoint.	Package models caches and refreshes per-provider model lists fetched from each provider's `/v1/models` endpoint.
neterr Package neterr centralizes the single question three call sites need to answer the same way: did a request fail at the transport layer — before any HTTP response came back?	Package neterr centralizes the single question three call sites need to answer the same way: did a request fail at the transport layer — before any HTTP response came back?
onboarding Package onboarding implements cc-fleet's first-run guided setup: it nudges about the agent-teams prerequisite for provider teammates, guides the user to fix it WITH CONSENT, and persists the user's decision so later runs never re-nag.	Package onboarding implements cc-fleet's first-run guided setup: it nudges about the agent-teams prerequisite for provider teammates, guides the user to fix it WITH CONSENT, and persists the user's decision so later runs never re-nag.
panevis Package panevis orchestrates hiding and showing a teammate's tmux pane without killing its process.	Package panevis orchestrates hiding and showing a teammate's tmux pane without killing its process.
permmode Package permmode is the shared permission-mode vocabulary for cc-fleet's claude launchers (spawn teammates and run sessions): the --permission-mode enum, its validation, and the enum→CLI-flag mapping.	Package permmode is the shared permission-mode vocabulary for cc-fleet's claude launchers (spawn teammates and run sessions): the --permission-mode enum, its validation, and the enum→CLI-flag mapping.
pinned Package pinned is an out-of-band registry of the board records a user has chosen to keep.	Package pinned is an out-of-band registry of the board records a user has chosen to keep.
procintrospect Package procintrospect provides the small set of process-introspection operations cc-fleet performs by reading process state: a process's argv, its immediate child pids, and the whole process table.	Package procintrospect provides the small set of process-introspection operations cc-fleet performs by reading process state: a process's argv, its immediate child pids, and the whole process table.
profile Package profile generates the per-provider JSON files that Claude Code loads via its `--settings` flag (a.k.a.	Package profile generates the per-provider JSON files that Claude Code loads via its `--settings` flag (a.k.a.
providerclass Package providerclass is the one shared place that turns a raw provider failure into a stable, key-safe classification.	Package providerclass is the one shared place that turns a raw provider failure into a stable, key-safe classification.
redact Package redact masks key-like tokens in any text that may flow into a JSON envelope or error message.	Package redact masks key-like tokens in any text that may flow into a JSON envelope or error message.
run Package run implements `cc-fleet run <provider>` (lane 0): launch an interactive foreground claude REPL backed by a provider's profile + default model, handing the process over to claude (an execve on unix, a wait-on-child on Windows).	Package run implements `cc-fleet run <provider>` (lane 0): launch an interactive foreground claude REPL backed by a provider's profile + default model, handing the process over to claude (an execve on unix, a wait-on-child on Windows).
secrets Package secrets dispatches provider API-key lookups across pluggable backends.	Package secrets dispatches provider API-key lookups across pluggable backends.
selfupdate Package selfupdate updates the cc-fleet binary and its Claude Code plugin to the latest GitHub release.	Package selfupdate updates the cc-fleet binary and its Claude Code plugin to the latest GitHub release.
sessiontitle Package sessiontitle resolves human-readable Claude Code session titles from transcript metadata.	Package sessiontitle resolves human-readable Claude Code session titles from transcript metadata.
spawn Package spawn orchestrates the end-to-end "spawn a provider teammate" flow: provider probe, profile install, fingerprint apply, team registration, and tmux split-window.	Package spawn orchestrates the end-to-end "spawn a provider teammate" flow: provider probe, profile install, fingerprint apply, team registration, and tmux split-window.
subagent Package subagent runs a ONE-SHOT, HEADLESS provider subagent: it launches `claude -p` backed by a third-party provider model (via the provider profile's --settings + --model) and returns the result synchronously.	Package subagent runs a ONE-SHOT, HEADLESS provider subagent: it launches `claude -p` backed by a third-party provider model (via the provider profile's --settings + --model) and returns the result synchronously.
teamhist Package teamhist persists a board-observed snapshot of every live team so a team cleaned up by its lead keeps a presence on the Agents Board until the user deletes the record.	Package teamhist persists a board-observed snapshot of every live team so a team cleaned up by its lead keeps a presence on the Agents Board until the user deletes the record.
teardown Package teardown removes cc-fleet teammates and team state.	Package teardown removes cc-fleet teammates and team state.
tmux Package tmux is a thin subprocess wrapper around the `tmux` binary covering the operations cc-fleet's spawn / teardown / ps / hide-show flows need: pick a spawn target, split a window to host a teammate or create a tiled swarm session, enumerate / kill panes, kill a server, and break / join panes for hide/show.	Package tmux is a thin subprocess wrapper around the `tmux` binary covering the operations cc-fleet's spawn / teardown / ps / hide-show flows need: pick a spawn target, split a window to host a teammate or create a tiled swarm session, enumerate / kill panes, kill a server, and break / join panes for hide/show.
tui Package tui implements the interactive terminal UI shown when cc-fleet is run bare (no subcommand) from an interactive terminal.	Package tui implements the interactive terminal UI shown when cc-fleet is run bare (no subcommand) from an interactive terminal.
userops Package userops implements the user-layer CRUD operations behind `cc-fleet init / add / edit / remove / list / repair / uninstall`.	Package userops implements the user-layer CRUD operations behind `cc-fleet init / add / edit / remove / list / repair / uninstall`.
version Package version exposes the cc-fleet build version.	Package version exposes the cc-fleet build version.
workflow Package workflow is cc-fleet's deterministic orchestration runtime: it runs a JavaScript workflow script that fans out provider subagent leaves, in a cc-fleet process OFF the main Claude context.	Package workflow is cc-fleet's deterministic orchestration runtime: it runs a JavaScript workflow script that fans out provider subagent leaves, in a cc-fleet process OFF the main Claude context.