• Mixed roles reduce context focus: one conversation tries to architect, edit, test, and review itself.
• Complex task execution has a ceiling: long work needs split points, handoffs, checks, and rollback boundaries.
• Cost pressure is higher: if every step needs the strongest model, even simple sub-tasks become expensive.
• Tool and skill management becomes harder: a "does everything" agent also accumulates too much authority and instruction load.
• Serial waiting is inefficient: when one agent is reading logs or running tests, other independent work cannot naturally continue.

CCB also supports complex workflows, but it is not an automatic DAG generator. You design complexity explicitly through .ccb/ccb.config, windows, role memory, worktrees, model/API settings, and ask/callback routes.

New users should avoid pane/window killing shortcuts at first. To stop a CCB project, prefer CCB's project-level shutdown command instead of killing one recoverable pane by accident.

Single-window compact config

cmd; main:codex, worker1:codex(worktree); reviewer:claude

Meaning:

• cmd is a shell pane, not an agent.
• main, worker1, and reviewer are agent names.
• codex and claude are providers.
• ; splits left-to-right; , stacks top-to-bottom.
• (worktree) means that agent uses an isolated git worktree.

Multi-window topology

When you want planning, implementation, review, and research in different tmux windows, use version = 2 and [windows]:

version = 2
entry_window = "main"

[windows]
main = "main:codex"
work = "worker1:codex(worktree), worker2:claude(worktree)"
review = "reviewer:claude, qa:gemini"

[ui.sidebar]
mode = "every_window"
width = "15%"
bottom_height = 20
agents_height = "50%"
comms_height = "15%"
tips_height = "35%"
comms_limit = 3

Note: cmd belongs to compact/hybrid single-window layouts. Do not put cmd inside [windows].

Rich workbench tool window

Tool windows are tmux windows managed by CCB, but they are not agents. They do not appear in ccb ask targets and do not create provider runtime records.

version = 2
entry_window = "main"

[windows]
main = "main:codex"

[tool_windows.rich]
command = "CCB_WORKBENCH_PROFILE=rich CCB_WORKBENCH_FORCE_RICH=1 ccb-workbench files"
label = "rich"

ccb update rich prepares the optional workbench bundle under CCB-owned XDG paths, downloads and validates bundled binaries where available, and uses the platform package manager only for required rich dependencies such as WezTerm, Markdown/PDF/image/video helpers, and recommended fonts. Under WSL, CCB can launch Windows-native wezterm.exe while running the rich tools inside the current Linux distro. Normal ccb update keeps this bundle untouched; rerun ccb update rich to install, repair, or refresh it. Run ccb uninstall rich to remove the bundle and return plain ccb to normal terminal startup. Set CCB_RICH_DOWNLOAD_BINARIES=0 to skip bundled binary downloads, or CCB_RICH_INSTALL_DEPS=0 to skip system package installation.

Per-agent model, API key, or base URL

Use compact format when layout is enough. If some agents need separate models or API routes, keep the compact header and add TOML overlays:

cmd; fast:codex, deep:codex; reviewer:claude

[agents.fast]
model = "gpt-5-mini"

[agents.deep]
key = "sk-..."
url = "https://api.example.com/v1"
model = "gpt-5"

[agents.reviewer]
model = "sonnet"

Do not commit real API keys to a public repository. key / url are agent-local shortcuts; advanced provider environment variables belong in provider profile or agent env fields.

1. Describe the project and team goal in natural language.
2. ccb_self's built-in ccb-config reads the current config authority and decides whether this is a new config, an edit, or a migration.
3. It proposes one complete config before writing.
4. You confirm the proposal, then it edits only .ccb/ccb.config.
5. It validates the config and tells you to use ccb reload --dry-run / ccb reload when the change can be applied dynamically.

By default, ccb-config does not edit .ccb/ccb_memory.md or .ccb/agents/<agent>/memory.md. It should touch those memory files only when you explicitly ask ccb_self for workflow memory or role memory design.

If agent A is handling a user-originated CCB task and needs agent B's result to finish, A should use callback. CCB records the parent/child relationship, lets A's current turn end, and later delivers B's result back to A as a continuation. That avoids polling, queue blocking, and wasted context.

Run ccb config validate and check that config_source_kind is the layer you expected. Project config .ccb/ccb.config has highest priority; if it is missing, CCB uses ~/.ccb/ccb.config or the built-in default.

First try mouse-drag copy and Ctrl+Shift+V / Cmd+V paste. If tmux captures the drag, use function key [ after <prefix> to enter copy / scroll mode. If you only want native terminal selection, many terminals support Shift + mouse drag.

Ask ccb_self to use its built-in ccb-config and describe your target window groups, such as main/work/review. Migration should preserve old agent names, providers, worktree markers, model/key/url fields, and write [windows] only after confirmation.

Prefer a release package because it carries or handles the sidebar helper. Source installs may need a local Rust toolchain if no compatible prebuilt helper is available.

• Repairs managed Codex logs_2.sqlite temp symlink targets when /tmp/ccb-codex-logs-* cleanup removes the target directory between starts.
• Falls back by removing an unrecoverable broken symlink and restoring the local backup before Codex initializes its SQLite databases.
• Adds regression coverage for the missing symlink target parent startup path.

• Fixes the managed Codex logs_2.sqlite redirect so CCB no longer pre-creates Codex-owned SQLite schema; Codex runs its own migrations first.
• Installs the CCB diagnostic insert-block trigger only after Codex has created the log database and _sqlx_migrations records.
• Repairs bad temporary log databases left by the intermediate policy by moving them aside and letting Codex recreate them through the normal migration path.

• Redirects managed Codex logs_2.sqlite diagnostic writes to temporary storage by default and blocks diagnostic log inserts, while diagnostics mode can restore the original database path for troubleshooting.
• Falls back to the in-place diagnostic trigger path when the temporary SQLite symlink cannot be installed.
• Fixes sidebar clicks for agents in other tmux windows by selecting the target window before selecting the pane, with pane-id fallback when window metadata is missing.

• Adds the mobile gateway alpha surface: authenticated pairing, focus routes, terminal open/resume/history routes, websocket terminal frames, public route metadata, and device revocation commands.
• Adds right-side sidebar placement and flattened [ui.sidebar] rendering while keeping legacy [ui.sidebar.view] input compatible.
• Supports multiple local agents sharing one Role Pack role id without collapsing them into a single runtime identity.
• Reduces Codex diagnostic SQLite churn by filtering TRACE/DEBUG log rows by default while preserving INFO/ERROR rows; CCB_CODEX_DIAGNOSTIC_LOGS=1 disables the filter.

• Codex plugin overrides now resolve in the intended order: inherited source config, provider_profile.plugins, then CCB_CODEX_PLUGIN_OVERRIDES_JSON / CCB_CODEX_PLUGIN_OVERRIDES.
• Codex agents without an inherited config.toml now still materialize provider_profile.plugins into managed config.toml.
• Claude provider_profile.mcp_servers now works even when the source .claude.json does not exist, and enabled = false clears stale managed MCP servers from the agent trust file.
• Callback continuations now preserve the upstream finalization target, and inherited ask skills remind agents not to answer callback continuations before upstream results are available.

• Managed Claude agents now inherit Claude Code MCP configuration from the source .claude.json, including global mcpServers and current project/workspace MCP server state.
• Project-level MCP state is mapped only onto the current managed workspace key, so unrelated source project records are not copied into the agent home.
• Source-home Claude Code hooks are merged with CCB-managed finish/activity hooks, so installed user hook tools stay visible after agent restart.
• Managed Claude .claude.json is treated as secret provider state because MCP definitions may include environment variables or auth-adjacent launch data.

• Adds explicit pane split ratios in layout tokens, such as agent1:codex@30, while preserving the existing even-split default when no suffix is present.
• Adds source-controlled per-agent Codex MCP overlays through provider_profile.mcp_servers; same-name MCP servers override inherited Codex config and different names are additive.
• Preserves trusted Codex command hooks during managed Codex home projection, improves sidebar Comms/Tips scrolling and resizing, and exposes more reply artifact evidence in ccb trace.

• Adds managed optional Z.ai CLI provider support with provider = "zai", visible zai --directory panes, and per-job zai --prompt execution.
• Uses Z.ai's native subprocess completion boundary: process exit plus assistant stdout extraction from JSONL output, without model-printed CCB_DONE.
• Adds ZAI_START_CMD, provider session/pathing support, deterministic stubs, focused execution tests, and README/provider list updates.

• Kimi execution now records receipt, no-captured-output diagnostics, trace, and resume metadata so missing replies and recovered turns are easier to diagnose.
• AGY prompt delivery now waits for ready evidence, handles pane fallback and ambiguous tmux send outcomes, and reports coalesced request diagnostics more clearly.
• Dispatcher, mailbox trace, and text artifact diagnostics now expose the provider details needed to investigate Kimi/AGY delivery and completion edge cases.

• Role Pack runtime lookup now follows the installed current package under .roles/installed/<role-id>/current; legacy multi-version stores remain compatibility input only.
• Project .ccb/role-lock.json files are now legacy diagnostics: CCB no longer writes them, adopts from them, or suppresses role memory and skills because of stale lock residue.
• Provider launch sessions record role id, version, and digest; restart now fails explicitly when the launch digest differs from installed current instead of silently resuming an old provider conversation.
• Release artifact metadata patching now targets ccb.py after the bash launcher split, keeping built tarballs on the intended version.

• Plain ccb and ccb rich now launch the CCB-managed rich WezTerm unless already inside that managed rich session; ordinary external WezTerm sessions no longer suppress rich auto-start.
• Runtime entrypoints share the _ccb-python launcher, keeping installed and source command execution pinned to the intended Python interpreter.
• Built-in defaults keep ccb_self in its own claude window, while ordinary default startup still avoids standalone Neovim tool windows.

• Pins role store lookup outside managed provider homes so provider session HOME rewrites no longer make role checks search provider-local .roles directories.
• Preserves AGENT_ROLES_STORE through CCB launch boundaries and falls back to the real source/account home role store when no explicit store is set.
• Missing role diagnostics now print the resolved role store path, making provider-home drift easier to identify.

• Enables IME support in the generated rich WezTerm config and maps XMODIFIERS=@im=... into WezTerm's XIM name so X11 fcitx/ibus input works for Chinese and other IME-backed text.
• Generated ccb-workbench wrappers now detect running or installed fcitx5, fcitx, or ibus-daemon before launching WezTerm, while preserving any user-provided input-method environment.
• Keeps the v7.6.4 green release surface and all v7.6.2 rich/tmux fixes intact for npm latest install testing.

• Keeps the 7.6.3 macOS temporary-root hardening and updates the CI release install smoke to use the explicit temporary-bin override for its isolated sibling CODEX_BIN_DIR.
• Leaves user-facing installer safety intact while allowing the release workflow to validate macOS package installation from a temporary smoke root.
• Keeps the v7.6.2 rich workbench and tmux single-status-row fixes intact for user install testing.

• Fixes macOS temporary-root detection for install guards by recognizing the resolved ${TMPDIR:-/tmp} parent used by GitHub Actions runners.
• Aligns doctor temporary implementation detection with macOS /tmp symlink behavior, preventing false red CI on /private/tmp and /private/var/folders/... paths.
• Keeps the v7.6.2 rich workbench and tmux single-status-row fixes intact for user install testing.

• Allows rich in .ccb/ccb.config as a tool/layout alias without requiring a provider runtime; it materializes as a managed tool pane/window and is not an ask target.
• After ccb update rich enables the bundle, plain ccb can use the rich launcher outside an existing rich/WezTerm session while avoiding recursive WezTerm launches.
• Adds ccb uninstall rich, ccb rich uninstall, and ccb rich disable for returning to normal CCB startup without changing full ccb uninstall behavior.
• Rich updates clean only CCB-owned legacy editor roots and links, leaving user-owned editor installs and personal config untouched.

• ccb update rich now bundles verified Yazi/ya binaries where possible before falling back to package managers.
• Linux rich installs prefer official Yazi musl builds before GNU builds to avoid newer glibc requirements on older stable distributions.
• Downloaded Yazi binaries must pass --version validation before activation, and invalid managed binaries are removed so fallback paths remain available.
• Under WSL, rich launchers can use Windows-native wezterm.exe while keeping CCB, Yazi, and preview helpers inside the current Linux distro.

• Makes rich workbench an explicit optional bundle installed with ccb update rich.
• Keeps ordinary install.sh install and ccb update focused on CCB itself; they no longer auto-provision standalone Neovim.
• Public ccb tools ... neovim routes now refuse standalone provisioning and point users to ccb update rich; ccb rich launches only an installed and enabled rich bundle.
• Restores the CCB tmux status bar to one line by removing the old second-line copy hint.

• Adds Kimi runtime hardening without changing other provider execution paths: Kimi can fall back to stable pane evidence for K2.7 Code when the native turn log does not expose a completed reply in time.
• Makes Kimi Hindsight memory opt-in at the CCB execution boundary. It activates only when .hindsight/kimi.json, .hindsight/codex.json, HINDSIGHT_API_URL, or HINDSIGHT_BANK_ID is configured, and failures remain non-blocking provider diagnostics.
• Preserves trusted Codex command hooks, including Hindsight Codex hooks, when CCB materializes managed Codex homes. Operators can extend the allowlist with CCB_CODEX_INHERITED_HOOK_EVENTS and CCB_CODEX_INHERITED_COMMAND_HOOK_MARKERS; arbitrary root hooks remain filtered out.
• Accepts both HINDSIGHT_API_KEY and HINDSIGHT_API_TOKEN for the Kimi bridge and the scripts/hindsight helper.
• Documents the supported provider surface more clearly in the README while keeping unrelated provider behavior unchanged.

• Adds built-in optional provider ids for Qwen Code (qwen), Cursor Agent (cursor), GitHub Copilot CLI (copilot), Crush (crush), Kiro CLI (kiro), Pi (pi), and Z.ai CLI (zai).
• Uses native per-job CLI execution and provider-owned completion signals: stream-json / JSON result events for Qwen, Cursor, Copilot, and Pi; process exit plus stdout for Crush, Kiro, and Z.ai CLI. These adapters do not require model-printed CCB_DONE; Pi terminalizes on native turn_end.
• Adds QWEN_START_CMD, CURSOR_START_CMD, COPILOT_START_CMD, CRUSH_START_CMD, KIRO_START_CMD, PI_START_CMD, and ZAI_START_CMD command overrides plus provider session bindings, runtime launchers, deterministic stubs, and focused execution tests.

• Adds MiMo Code to the public README provider strip with a Xiaomi-branded MiMo badge and updates the top-level positioning to eight CLI families.
• Publishes the committed MiMo native provider integration in the 7.5 line: managed mimo panes, MIMO_START_CMD, generated MiMo instructions, and mimo run --pure --format json completion parsing.
• Synchronizes npm package metadata and release workflow defaults with the new patch release.

• Adds managed native CLI provider support for Kimi plus broader native CLI runtime groundwork, including runtime specs, session bindings, command overrides, and cleanup coverage.
• Moves Kimi and Antigravity completion detection toward provider-owned session or transcript evidence instead of requiring model-printed CCB_DONE.
• Uses Kimi's current --auto-approve flag for CCB auto-permission while recognizing legacy/alias flags such as --auto, --yes, -y, and --yolo.
• Synchronizes the English and Chinese README homepages with refreshed hero assets and the seven public CLI-family positioning.

• Completes Claude pane-backed asks promptly when a primary assistant response emits stop_reason=end_turn with an observed request anchor and non-empty reply, avoiding the previous 900-second timeout path.
• Treats empty session-boundary terminal events with no prior assistant reply as incomplete/task_complete_empty_reply with empty-provider diagnostics.
• Restores the @seemseam/ccb npm release surface with package metadata, CLI runner wrappers, and tag-triggered Trusted Publishing after GitHub release assets are available.
• Refreshes the v7 README homepage around canonical hero assets, npm-first install, and clearer ccb_self guidance.