# subagent

Adopt this skill: https://proskills.md/skills/other/ethanhq-cc-fleet-codex-plugin-skills-subagent

Page: https://proskills.md/skills/other/ethanhq-cc-fleet-codex-plugin-skills-subagent
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: codex-plugin/skills/subagent/SKILL.md
size: 21770
sha: 9e1481945926e95b65c504b13062ed438fa79df6
upstream: https://github.com/ethanhq/cc-fleet/blob/main/codex-plugin/skills/subagent/SKILL.md

````text
---
name: subagent
description: Fan out a one-shot or flat parallel batch of cc-fleet PROVIDER subagents (headless `cc-fleet subagent`) that return a result — DeepSeek / GLM / Kimi / Qwen / MiniMax, or a Codex/Claude subscription. Trigger ONLY to delegate a task to a cc-fleet provider worker (parallel research, bulk per-file work, a specialized model). Do NOT trigger for a multi-phase pipeline (that is /cc-fleet:workflow), for ordinary local shell/coding, or for editing or researching cc-fleet's own code.
---

# subagent — one-shot / batch / background provider subagent

**Wrong lane?** A multi-phase pipeline with dependencies or resume → /cc-fleet:workflow.

When this skill cites `cc-fleet-shared/<file>.md`, read `../cc-fleet-shared/<file>.md` relative to this SKILL.md (load-bearing, not optional background).

> **Execution environment — check before running anything.** Confirm this shell runs on the machine where cc-fleet is installed. In a remote or split-host agent session the shell can run on a separate machine with its own filesystem and PATH, so `cc-fleet: command not found` or a wrong working directory can indicate that the shell is running on the wrong machine, not that cc-fleet is broken — route commands through a host-executing bridge and pass host paths for the files you reference, and stop cleanly if no such bridge exists. (Different-machine case only; for the same-machine codex sandbox — a clean `doctor` but network-blocked leaves — see Approval & sandbox below.)

`cc-fleet subagent` runs a provider model headless and returns the result directly on your shell's stdout — no tmux pane, no team, no locks. A one-shot provider agent whose model can be a provider id. It reuses the same provider selection and claude-binary gate as the rest of cc-fleet. It's the lightweight synchronous branch.

**Preflight (first fan-out per session).** Run `cc-fleet doctor --json` once and read the per-check results. The ONLY hard stop is check 4, the **claude binary** check (the worker engine) — if it fails, tell the user to install or fix Claude Code, and stop. Do **not** stop on the "all configured providers' keys reachable" check: it aggregates every enabled provider, so one unrelated provider — especially a daemon-backed `codex` / `openai-*`, whose loopback proxy is only up while one of its workers runs — flips `ok:false` / exit 1 while your target provider is fine. Provider API keys are configured separately in cc-fleet, so a provider model needs the claude **binary** but not a Claude subscription. To check the provider you'll actually use, run `cc-fleet models <provider> --json` (`PROVIDER_UNKNOWN` ⇒ not configured) and confirm its `"enabled": true` in `cc-fleet list --json` (skip both for the native `claude` leaf, which has no providers.toml row). Neither proves it's reachable — the run itself does.

## Approval & sandbox (non-bypass codex)
`cc-fleet` spawns a **network-using child** (`claude -p` → the provider API) and writes a job record (plus a file when you use `--prompt-file` or redirect `--json` to one). On a codex that is **not** in full-bypass mode, expect two things — neither is a cc-fleet bug, so set the user's expectation rather than reporting a failure:
- **Approval depends on the active policy.** Check the current session's approval policy; a shell call or chunked wait may prompt, but non-bypass mode alone does not imply approval for every call. Preserve any approval actually required by the host.
- **A sandbox can block network access.** If leaves report transport failures, inspect the actual sandbox/network policy and error before blaming either the sandbox or provider. A clean local doctor check is only a diagnostic clue. Use a supported, narrowly scoped network permission path if needed; do not suggest full bypass as routine troubleshooting.

## When to use it
- **One-shot research / analysis / judgement** — you want an answer, not a long-lived colleague.
- **Batch fan-out** — N independent tasks in parallel. subagent is **lock-free**, so N calls don't serialize behind each other — true parallelism.
- **Cost-bounded probes** — `--timeout` caps wall-clock; the return value carries `usage` / `total_cost_usd`; it stops when done (nothing to forget to tear down).

## The provider ask ladder (ask at most once per task)
1. The user named a provider or model → use it.
2. Else run `cc-fleet default --json`: if it returns a provider (source "configured" or "auto"), use it and STATE it in your kickoff line (e.g. "using glm (default)").
3. Else (several providers, none default) ask the user ONCE which to use — list the enabled providers from `cc-fleet list --json` (name + default_model + the one-line note in cc-fleet-shared/providers.md). After they pick, run `cc-fleet default <chosen>` so you never ask again. (`cc-fleet default <p>` is user-layer; only run it to FILL a blank default, never with --force.)
4. A mid-task provider failure (insufficient balance / rate limit / auth) → STOP, tell the user what happened, propose the next provider, and WAIT for their confirmation. Never switch providers silently.
   STOP freezes the affected provider operation and any unapproved provider switch, not independent authorized work. The error table's single rate-limit retry remains allowed; do not retry uncertain writes before establishing their prior result. Main-session handling is allowed only where the workflow already permits it and the user has not required that provider. Changing a provider or the saved default still requires the corresponding explicit authorization.

Model tier within a provider: fan-out / leaf work → omit `--model` (or `--model fast`); judge / synthesis / sustained work → `--model strong`. The provider's roster decides the actual model — see cc-fleet-shared/providers.md.

**The reserved native leaf — `claude`.** `cc-fleet subagent claude …` runs the official `claude` CLI on the user's OWN Claude Code login (their subscription OAuth or whatever they're logged in as) — no providers.toml row, no profile, no key material. A NAMED deliberate choice, never the auto-default (`cc-fleet default claude` errors; it never auto-resolves). `--model` takes a literal id (`fable` / `opus` / `sonnet` / a full id) — the slot keywords `default`/`strong`/`fast` are rejected (no roster); omitted = claude's login default, which is typically the most expensive tier, so naming a model is usually wise. Profiles apply unchanged. The leaf spends the **lead session's own subscription window** — use it for one or two synthesis / judgement nodes, never a wide fan-out.

```bash
cc-fleet subagent claude --model opus --prompt "<synthesis over the gathered notes>" --json
```

## Calling it (run with your shell tool, always with `--json`)
```bash
cc-fleet subagent --prompt "<task>" --label "codex/<cwd-basename>/<short>" --json   # no provider arg → default provider
cc-fleet subagent deepseek --model strong \
  --prompt "Analyze the worst-case complexity of quicksort in src/sort.go; give a triggering input" \
  --label "codex/cc-fleet/quicksort" --json
```

**Label every job.** A codex-launched job is grouped on the Agents Board under your Codex launcher (a `codex <thread>` header, not `(no session)`); a `--label "codex/<cwd-basename>/<short>"` still helps you tell your jobs apart within that group.

**Expected-large output** → redirect `--json` to a file and read the file, sidestepping any shell-output cap: `cc-fleet subagent … --json > out.json`, then read `out.json`.

The provider arg is **optional** — with no provider, cc-fleet uses the default. `NO_DEFAULT_PROVIDER` / `DEFAULT_PROVIDER_DISABLED` / `DEFAULT_PROVIDER_UNKNOWN` in the failure envelope mean there is no usable default — apply the provider ask ladder above.

Useful flags (full list: `cc-fleet subagent --help`):
- **Name it** → `--label "<short-alias>"` (e.g. `--label sort-complexity`). The Agents Board shows the label instead of the opaque job id — pass one on every launch. Display-only metadata; capped at 256 bytes.
- **Large / sensitive prompt** → `--prompt-file <path>` (read from file, piped via stdin, kept out of argv / `ps`). Use it once a single prompt approaches **~128 KiB** (`MAX_ARG_STRLEN`, the per-argument cap — not the ~2 MB total `ARG_MAX`). `--prompt-file -` reads stdin.
- **Long task** → `--timeout 600s` (default 300s). For tasks that may exceed the timeout, raise `--timeout` or use `--background` (below). Note: a provider that's down on **auth (401) or quota (429)** makes claude retry **~180s** before surfacing `KEY_INVALID` / `INSUFFICIENT_BALANCE`, so keep `--timeout ≥ ~200s` (the 300s default is fine) — a shorter timeout reports those as `SUBAGENT_TIMEOUT` instead. `--probe` does **not** catch a bad key (the models endpoint may not 401 it).
- **Cost / runaway gates** → `--max-budget-usd 0.5` (cap spend) and `--max-turns` (cap the agentic tool loop). On fan-out, strongly consider a budget cap on every call. **Size `--max-turns` generously up front** — a read-heavy / multi-file / git-inspecting task spends ~1 turn per file read or command, so give it **30–50 (or omit it)**; a small cap (8/10) starves it and the leaf fails `SUBAGENT_MAX_TURNS` mid-task (budget ~$0.3–0.9 for such a leaf).
- **Prompt profile** — `slim` is the DEFAULT; read-only research → `--profile slim-ro`; `--profile full` ONLY to compare against a full session or diagnose a suspected slim regression. `--tools` REPLACES the whole tool set, never appends. Write prescriptive prompts ("Run `cmd`", "Use the Read tool on X"), not "look at" / "check" — weak provider models skip tools on weak imperatives under any profile. Tool whitelists / `--skills` / `--mcp` defaults / downgrade behavior: cc-fleet-shared/providers.md.
- **Probe** is **off by default** (`--probe` to opt in): the inner `claude -p` call is itself the authoritative reachability + auth test. On a big fan-out, run one shared `cc-fleet doctor` / probe up front rather than paying up to 10s × N.
- `--prompt` and `--prompt-file` are mutually exclusive — pass exactly one (else `error_code=SUBAGENT_BAD_ARGS`, no claude launched).

## Success envelope
```json
{"ok":true,"result":"<answer text>","provider":"deepseek","model":"deepseek-reasoner",
 "duration_ms":12044,"usage":{"input_tokens":812,"output_tokens":1530},
 "total_cost_usd":0.0031,"session_id":"…"}
```
→ Take `.result` as this subagent's output and hand it back / continue orchestrating. `model` is the model the provider actually billed (routing evidence). Keep `.session_id` if you intend a multi-turn follow-up (below).

## Failure envelope — dispatch on `error_code` (do not parse prose)
`error_msg` is a canonical string only; never matched on. Dispatch on `error_code`:

| `error_code` | Meaning | What you do |
|---|---|---|
| `SUBAGENT_BAD_ARGS` | The call itself is invalid (a missing or conflicting prompt flag, a flag value cc-fleet rejects, or a slot keyword on the native `claude` leaf — `error_msg` says which) — or, from `subagent-status`, an invalid or unknown job id (e.g. one already pruned). An unknown flag or an unparsable value (`--timeout 5zz`) never gets here: it exits 1 with one stderr line and no JSON. | Fix the call and re-issue; never retry it unchanged. An unknown job id on `--wait` means the record is gone — stop waiting on it. |
| `NO_DEFAULT_PROVIDER` | No provider arg and no default configured. | Apply the provider ask ladder. |
| `DEFAULT_PROVIDER_DISABLED` | The default provider is disabled. | Apply the provider ask ladder; or the user re-enables via `cc-fleet edit <provider> --enable`. |
| `DEFAULT_PROVIDER_UNKNOWN` | The default names a provider that no longer exists. | Apply the provider ask ladder; the user re-pins with `cc-fleet default <p>`. |
| `DEFAULT_PROVIDER_RESERVED` | `default_provider` is hand-set to the reserved `claude` (explicit-only). | The user runs `cc-fleet default --unset` or re-pins a real provider; don't retry. |
| `CONFIG_LOAD_FAILED` | `providers.toml` failed to load/validate. | `cc-fleet doctor`; surface to the user — don't retry. |
| `UNKNOWN_PROVIDER` / `PROVIDER_DISABLED` | Provider not configured / disabled. | Tell the user to `cc-fleet add` / `cc-fleet edit <provider> --enable`. |
| `PROVIDER_RESERVED` | A providers.toml row is named `claude` (reserved for the native leaf). | Tell the user to rename or `cc-fleet remove claude`. The subagent and workflow lanes refuse that row; only `cc-fleet run claude` launches it (cc-fleet-shared/providers.md). |
| `FINGERPRINT_STALE` | The `claude` binary was not found (the code keeps its old name). | Tell the user to install/fix Claude Code or PATH, then retry. `cc-fleet doctor` confirms. |
| `KEY_INVALID` | Provider 401/403 (on a codex provider: no usable codex login). | Have the user rotate the key; do not retry blindly. A codex provider has no key: the user runs `cc-fleet codex login --credential <its secret_ref>` (`protocol` `codex-oauth` and `secret_ref` in `cc-fleet list --json`). |
| `INSUFFICIENT_BALANCE` | Out of balance / quota (429/402 + balance signature). | Retry can't help — propose the next provider (provider ask ladder, step 4) or handle it in the main session yourself; tell the user they're out of credit. |
| `RATE_LIMITED` | Provider 429. | Wait briefly, retry once, or propose a switch (provider ask ladder, step 4). |
| `MODEL_NOT_FOUND` | Model name rejected (400). | Drop `--model`, or pass a slot (`default`/`strong`/`fast`; see `cc-fleet models <provider> --json`), and retry. If the user named that model, tell them it was rejected and confirm the substitute before retrying. If a configured slot itself is rejected, the user fixes it with `cc-fleet edit <provider> --default-model/--strong-model/--fast-model <id>` (or the TUI); `cc-fleet refresh` changes nothing a run uses. |
| `PROVIDER_UNREACHABLE` | Transport failure (with `--probe`, or at runtime when claude reports one). | Check the sandbox / network policy first (Approval & sandbox above), then `cc-fleet doctor`; if urgent, handle it in the main session yourself. |
| `SUBAGENT_TIMEOUT` | Exceeded `--timeout`. | Real long task → raise `--timeout` (or use `--background`) and retry; suspected hang → switch provider / fall back (with user confirmation). |
| `PROVIDER_API_ERROR` | Other provider failure (5xx / overloaded). | Retry once or propose a switch. |
| `CODEX_PROXY_UNAVAILABLE` | The codex / openai-* conversion daemon could not start (e.g. its loopback port is held; `error_msg` names the cause — only `did not become ready on port <n>` when the daemon exited on start). A missing codex login does not cause this — it fails on the request as `KEY_INVALID`. | Run `cc-fleet codex-proxy status`; tell the user to free the port in the provider's `base_url` or move it (`cc-fleet edit <provider> --base-url http://127.0.0.1:<n>/`, a codex provider also `--models-endpoint http://127.0.0.1:<n>/v1/models`), or fix the named cause. |
| `CODEX_CLOUDFLARE_BLOCKED` | The ChatGPT backend's edge blocked this IP/client — not a key problem. | Switch network/IP or retry later; don't rotate credentials. |
| `SUBAGENT_MAX_TURNS` | claude hit the `--max-turns` cap without finishing (the spent cost is surfaced — not silently $0). | Raise `--max-turns` (or omit it) and retry — a read-heavy / multi-file task needs ~1 turn per file read or command; a genuinely long task can use `--background`. |
| `SUBAGENT_FAILED` | claude exited with no parseable result (or budget exhaustion). For a `claude` native leaf on a logged-out machine, this is the login failure — the error preview names it (no dedicated code). | Inspect; retry or switch provider. A logged-out native leaf → tell the user to log in to Claude Code interactively. |
| `SUBAGENT_OUTPUT_TOO_LARGE` | The child's stdout/stderr exceeded the byte cap; the run was killed. | Have it write its output to a file and return a short answer (or narrow the ask) — a blind retry overflows again. |
| `SUBAGENT_STOPPED` | An operator stopped the job (`workflow stop` / a leaf stop) — terminal, NOT a failure. | Never auto-retry; surface it. |

## Batch fan-out (parallel, each returns synchronously)
```bash
# These calls are independent; subagent is lock-free, so running them
# concurrently won't queue them behind a shared lock.
cc-fleet subagent glm      --prompt "Summarize docs/a.md" --label "codex/docs/a" --json
cc-fleet subagent glm      --prompt "Summarize docs/b.md" --label "codex/docs/b" --json
cc-fleet subagent deepseek --prompt "Summarize docs/c.md" --label "codex/docs/c" --json
# Each returns its own {ok, result, total_cost_usd}; aggregate them.
```
A flat fan-out only — phases, dependencies, or dynamic orchestration over the results is /cc-fleet:workflow.

## Long tasks: synchronous — set `--timeout`, or `--background` + poll
`cc-fleet subagent` is **synchronous** — your shell tool blocks until it returns the envelope; set `--timeout` for long tasks (default 300s; raise it for research / many-turn work). If a job must outlive the call (or you want it on the Agents Board), launch it detached and poll yourself:
```bash
cc-fleet subagent --prompt "<long task>" --label "codex/<cwd-basename>/<short>" --background --json
# → {"ok":true,"job_id":"<uuid>","status":"running","output_file":"…","pid":…}
cc-fleet subagent-status <job_id> --wait --timeout 120s --json
```
`subagent-status --wait` blocks up to `--timeout`, then exits **124** while the job is still pending — re-issue it in chunks until it settles (codex has no background-task wake). If the codex shell yields with "Process running with session id …", that backgrounded `--wait` is STILL the live wait — do NOT start a second one; let it return (size each `--timeout` shorter than your shell's foreground window so it returns cleanly). Exit dispatch: **0** done (envelope has `.result`) · **1** failed OR stopped — check `.status` first: `stopped` is an operator stop, never auto-retry; `failed`, or no `.status` (an invalid or unknown job id) → dispatch on `.error_code` · **3** held (a workflow-leaf an operator parked — surface it, never wait it out) · **124** still pending (re-issue) · **130** interrupted. Never spawn an agent to poll.

`cc-fleet subagent-gc --json` prunes finished job files.

## Multi-turn: `--resume`
Continue a prior subagent session (stateful, but not long-lived between turns — each turn is a fresh `claude -p --resume`):
```bash
cc-fleet subagent --resume <session_id> --prompt "<follow-up>" --json
```
`<session_id>` is the `.session_id` from the previous turn's envelope. A default-profile (slim) resume is silent; an explicitly passed `--profile` over `--resume` warns on stderr — it swaps the system prompt mid-session. Keep the profile constant across a session's turns.

## Cleanup vs. resume — they're independent
A **sync** subagent has nothing to tear down; "cleanup" only concerns `--background` job records on the Agents Board. The rules:

- **The one rule that matters: capture `.session_id` BEFORE pruning** if a follow-up is likely. gc deletes cc-fleet's job record (which holds the envelope with the id) but never Claude's transcript — so `--resume` works after gc *iff* you kept the id, and keeping the record without the id buys you nothing.
- **Prune finished, scoped to this thread:** `cc-fleet subagent-gc --session <lead_session_id> --json`, with the `lead_session_id` your envelopes carry (`codex:<thread>` from Codex — copy it, don't rebuild it from `$CODEX_THREAD_ID`). Immediate, skips pinned — prefer it over `--older-than 0s`, which is machine-wide and also sweeps other sessions' finished records. Default gc only removes finished jobs older than 24h; running jobs are always kept; pinned records are user-owned — never force-remove them.
- **gc also deletes workflow runs.** Any `subagent-gc` deletes the runs it reaches (`--session`: that thread's finished runs, at once; the default: runs idle past the cutoff; `--older-than 0s`: every finished run) with their journals and saved scripts, so `workflow run --resume` / `restart` can no longer replay them — resume or abandon a stopped or failed run before pruning. A stopped or killed run's leftover isolation worktree is first saved to a `cc-fleet/wf-salvage-*` branch (or kept with a `.cc-fleet-keep` marker if that fails); gc prints no notice, so check `git branch --list 'cc-fleet/wf-*'`, and `git worktree list` for a kept directory.

## Anti-patterns
- Using subagent as a sustained back-and-forth collaborator → it's one-shot/batch; `--resume` is for a short follow-up, not a long conversation.
- Chaining subagents into a dependent pipeline by hand → /cc-fleet:workflow.
- Polling `cc-fleet ps --check` for a subagent → unnecessary; the result is on stdout.
- Stuffing a giant prompt into `--prompt` (hits `MAX_ARG_STRLEN` ~128 KiB) → use `--prompt-file`.
- Running a possibly-stuck provider with no bound → the default `--timeout 300s` caps it, but tune per task on fan-out, and run genuinely long work via `--background` (Long tasks above).
- Spawning / delegating an agent to watch a job → never; re-issue `subagent-status --wait --timeout 120s --json` yourself in chunks (codex has no background-task wake).
- Looping on a failure without dispatching `.error_code` → every `--json` failure carries a code; switch on it (table above).
- Switching providers silently after a balance / rate-limit / auth failure → stop, tell the user, wait for their pick (provider ask ladder, step 4).
- Fanning out N `claude` native leaves → drains your own subscription window; use a metered provider for breadth, `claude` only for one or two synthesis nodes.
````

## File: README.md
upstream: https://github.com/ethanhq/cc-fleet/blob/main/README.md

````text
![cc-fleet — plug any third-party model into Claude Code's Dynamic Workflows, Agent Teams, and Subagents](docs/assets/cc-fleet-banner.png)

<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">

[![Release](https://img.shields.io/github/v/release/ethanhq/cc-fleet?style=for-the-badge&color=2ea043&label=release)](https://github.com/ethanhq/cc-fleet/releases) [![npm](https://img.shields.io/npm/v/@ethanhq/cc-fleet?style=for-the-badge&color=cb3837)](https://www.npmjs.com/package/@ethanhq/cc-fleet) [![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-8957e5?style=for-the-badge)](https://github.com/ethanhq/cc-fleet/releases) [![License](https://img.shields.io/badge/license-Apache%202.0-1f6feb?style=for-the-badge)](LICENSE)

**English** · [简体中文](docs/README_zh.md)

</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:**
```bash
curl -fsSL https://claude.ai/install.sh | bash
```
**Windows (PowerShell):**
```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:**
```bash
curl -fsSL https://raw.githubusercontent.com/ethanhq/cc-fleet/main/install.sh | sh
```
**Windows (PowerShell):**
```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:**

```bash
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
````
