CCB

Designed around agent parity Visible, controllable multi-agent cooperative TUI workspace

English | 中文

Quick Start · v7 UI · Configure Agents · User Guide · Developer Guide

---

Supported CLIs

Mix CLIs per agent in .ccb/ccb.config; actual availability depends on the local CLI installation and account access.

• Codex (codex)
• Claude (claude)
• Gemini (gemini)
• Kimi (kimi)
• MiMo (mimo)
• Qwen (qwen)
• Cursor (cursor)
• GitHub Copilot CLI (copilot)
• Crush (crush)
• Kiro CLI (kiro)
• Pi (pi)
• OpenCode (opencode)
• Antigravity (agy)
• Droid (droid)

New role specification: package skills, memory, and tool dependencies into self-contained Role Packs, then create hot-loadable and removable specialist agents.

Why CCB?

See the work	Mix providers	Keep control
Every agent is a real terminal with layout control.	Run multiple CLIs concurrently from one command.	Stable background communication for multi-line task orchestration.

Quick Start

1. Install or update

New installs should use the npm package:

npm install -g @seemseam/ccb

After CCB is installed, use CCB's updater:

ccb update

GitHub release package and source install fallbacks

If npm is not available in your environment, download the matching package from Releases:

tar -xzf ccb-*.tar.gz
cd ccb-*
./install.sh install

Source install is for development or temporary fallback use:

git clone https://github.com/SeemSeam/claude_codex_bridge.git
cd claude_codex_bridge
./install.sh install

Source installs link global ccb / ask back to the checkout. Regular users should prefer the npm package.

Out of the box, run ccb from your project directory. If startup reports that .ccb cannot be created automatically or that the project anchor is missing, create .ccb manually:

mkdir -p .ccb

2. Create project config

Create .ccb/ccb.config in your project root. For v7, it is better to understand config from multi-window topology first: [windows] defines tmux windows and agent groups, agent:provider defines which CLI each agent uses, and (worktree) gives an agent its own git worktree.

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

[ui.sidebar.view]
agents_height = "50%"
comms_height = "15%"
tips_height = "35%"
comms_limit = 3

If you are not sure how to group windows, how many workers you need, which agents should use worktrees, or which agents need separate models or API routes, ask ccb_self. It is CCB's built-in self-agent: it understands CCB commands, config authority, roles, windows, reload behavior, and common recovery paths, and can design the config with its private ccb-config skill. Blank projects include ccb_self; existing custom configs can add it with ccb roles add agentroles.ccb_self:codex.

Validate the config:

ccb config validate

Start the workspace:

ccb

3. Collaborate

Type directly in an agent pane, or route work between agents:

/ask reviewer review the latest parser changes and list blocking issues.

Agents can also call /ask from workflow orchestration to delegate and hand off work automatically.

v7 UI Tour

Region	Purpose
Sidebar	Shows refresh/close CCB controls, windows and agents, internal communication state, and tips that can be edited in config and hot-reloaded.
Mouse control	Click to switch windows, agents, and panes; refresh, kill, or delete communication entries from the communication area.
Workspace	Every pane is a real CLI. Switch by mouse or tmux shortcuts.
Useful shortcuts	Ctrl-b h/j/k/l switches adjacent panes; Ctrl-b z zooms or restores the current CLI pane.

Contact

• Email: bfly123@126.com
• WeChat: seemseam-com

---

More Reading

Start with Quick Start for first use; the sections below cover CCB's design boundaries, comparisons, daily operations, and configuration model.

What Is CCB?

CCB is a project-level agent CLI workspace. It uses tmux to manage multiple real CLI agents and unifies startup, restore, communication, configuration, windows, and runtime state for one project.

• Real CLI sessions, not fake panels: every agent pane runs the actual provider CLI.
• Visible collaboration: the sidebar shows windows, agents, status, and communication; users can switch panes by mouse.
• Mixed providers: one project can run Codex, Claude, Gemini, Kimi (kimi), MiMo (mimo), Qwen (qwen), Cursor (cursor), Copilot (copilot), Crush (crush), Kiro (kiro), Pi (pi), OpenCode, Droid, and Antigravity (agy) together.
• Project config: .ccb/ccb.config defines the team, layout, windows, worktrees, model, key, and url.
• Built-in CCB expert: blank projects include ccb_self, a self-maintenance agent with deep CCB knowledge for usage guidance, config design, diagnostics, recovery, and workflow repair.
• Roles: a new role packaging model that lets specialized agents carrying "heavy weapons" such as independent skills, memory, and tool dependencies instantly land in a target project as hot-loadable, removable agents, while leaving the main environment, user global config, and project runtime state unchanged.
• Recoverable runtime: CCB supervises agent panes and supports attach, restore, and project-scoped cleanup.
• Explicit collaboration channel: agents can delegate through /ask, $ask, callback, and silence routes.

Why Multi Agents

A single agent is enough for small tasks. Once work needs planning, parallel edits, review, testing, and handoff, multi agents help separate roles, context, models, and execution. CCB focuses on putting multiple real CLI agents into one visible terminal workspace.

Value	Plain meaning
Role separation	main plans, worker implements, reviewer checks risk.
Parallel progress	One agent can edit while another reads docs, validates, or reviews.
Model and context layering	Different agents can use different providers, models, APIs, worktrees, and memory.

Why one agent starts to struggle

• 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.

Which Multi-Agent Approach Should You Use?

Multi-agent systems are not one fixed shape. Use the short table first; expand the details only if you are comparing tradeoffs.

Approach	One-line summary	Best fit
Claude Code native subagents / agent teams	Native delegation inside Claude Code.	You mostly stay in Claude Code and want more coordination handled by a Claude lead.
Hive / OpenHive	Production-oriented multi-agent workflow harness.	You need state, recovery, observability, cost controls, and graph workflows.
CCB	Visible, controllable local CLI-agent workspace with mixed providers.	You want Codex, Claude, Gemini, Kimi, MiMo, Qwen, Cursor, Copilot, Crush, Kiro, OpenCode, Antigravity, and other real CLIs in one project terminal.

Details: model choice, control, context, and complex workflows

Question	Claude Code native	Hive / OpenHive	CCB
Different model vendors?	Can choose Claude models for teammates/subagents; overall path is still Claude Code.	LiteLLM route covers many hosted and local providers.	Choose Codex, Claude, Gemini, Kimi, MiMo, Qwen, Cursor, Copilot, Crush, Kiro, OpenCode, Droid, Antigravity, and per-agent model/key/url.
Is the process visible?	In-process or split panes depending on mode.	Runtime observability and dashboard-style control.	Real tmux panes by default; users can click, type, copy, and inspect each CLI.
Is topology controllable?	Natural-language teammate setup, with much coordination handled by the lead.	Goal-generated graph-like topology, harness oriented.	Config explicitly defines agents, windows, panes, worktrees, and sidebar behavior.
Is context manageable?	Subagents/teammates have separate contexts; teams have task and message state.	Role memory, durable state, and recovery are core design points.	Each CLI keeps its provider session; shared project memory and per-agent memory are optional.
Best landing zone	Fast delegation inside Claude Code.	Business automation, long-running workflows, production reliability.	Local development with visible cross-provider CLI agents.

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.

Daily Operation

Goal	Command
Start or reattach the current project workspace	ccb
Safe start, keeping configured/manual permission behavior	ccb -s
Rebuild runtime state while keeping config and same-name managed agent history	ccb -n
Stop this project's background runtime	ccb kill
Force cleanup before rebuilding	ccb kill -f then ccb -n
Update to the latest stable release	ccb update
Inspect the active config layer	ccb config validate
Preview a config reload plan without changing tmux	ccb reload --dry-run
Apply supported config changes without restarting other agents	ccb reload

tmux Basics

CCB can be used mostly with the mouse, but learning a few tmux shortcuts makes daily work much faster. This section lists only common tmux keyboard operations.

In this section, <prefix> means Ctrl-b: press Ctrl-b, release it, then press the function key. Use an English input method for the function key so punctuation keys are not intercepted by another IME.

Goal	Function key	Notes
Move to an adjacent pane	h / j / k / l or Arrow keys	CCB-managed tmux sessions enable Vim-style pane focus keys.
Resize current pane	H / J / K / L	Repeatable resize keys in Vim directions.
Move to the next pane	o	Fast rotation when direction does not matter.
Zoom / unzoom current pane	z	Useful for long output, diffs, and logs.
Open window / pane list	w	Pick a target in larger layouts.
Next window	n	Switch to the next tmux window.
Previous window	p	Switch to the previous tmux window.
Jump to numbered window	0 to 9	Jump directly by tmux window number.
Enter copy / scroll mode	[	Review history, scroll, and select text.
Exit copy / scroll mode	q or Esc	Return to normal input.
Paste tmux buffer	]	Paste content copied into tmux's own buffer.
Detach session	d	Leave the display without stopping CCB; you can reattach later.

Copy and paste tips:

• Mouse copy: in most terminals, drag with the left mouse button to copy; if tmux captures the drag, enter copy / scroll mode first.
• Bypass tmux selection: many terminals support Shift + mouse drag for native terminal selection.
• System paste: Linux/Windows terminals usually use Ctrl+Shift+V; macOS terminals usually use Cmd+V.
• tmux paste: if the content is in the tmux buffer, use function key ].

More common tmux operations

Goal	Function key	Notes
Scroll in copy / scroll mode	PageUp / PageDown / Arrow keys	Terminal support can vary.
Start selection in copy / scroll mode	v	CCB uses tmux vi copy mode.
Copy selection in copy / scroll mode	y	Copies to the tmux buffer and exits copy mode.
Search in copy / scroll mode	Ctrl-s / Ctrl-r	Commonly forward / backward search.
Create a window	c	Use only when you intentionally need another shell.
Rename a window	,	Helps identify multi-window workflows.
Show tmux key help	?	Useful when you forget a shortcut.

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.

Configure Your Agent Team

CCB resolves config in three layers, from lowest to highest priority:

1. Built-in default config.
2. User config at ~/.ccb/ccb.config.
3. Project config at .ccb/ccb.config.

Higher layers replace lower layers as a whole; they are not merged. The project authority file is .ccb/ccb.config. The old .ccb_config/ccb.config path is legacy migration evidence only. The built-in default is a v2 [windows] config with agent1, agent2, agent3, and ccb_self. The default ccb_self agent uses codex and is bound to agentroles.ccb_self.

.ccb/ccb.config mainly controls:

Config area	Syntax or location	Notes
Window grouping	[windows]	Group agents into tmux windows such as main, work, review, or research.
Agent name and provider	main:codex, reviewer:claude	Names are used by the UI, ask routing, and memory files; provider decides which CLI starts.
Workspace isolation	worker1:codex(worktree)	Gives implementation agents isolated git worktrees to reduce accidental overlap.
Sidebar behavior	[ui.sidebar]	Controls whether the sidebar appears in every window, plus width and Comms height.
Tool windows	[tool_windows.<name>]	Add managed non-agent windows such as Neovim; they appear as one sidebar row and are not ask targets.
Per-agent model/API	[agents.<name>]	Configure model, key, url, and related agent-local overrides.
Role Pack binding	agentroles.archi:codex	Bind a reusable role package through a window leaf; role assets are installed once and projected into the derived agent.
Role description	[agents.<name>] description = "..."	Give an agent a short responsibility note; longer workflow rules belong in memory.

After editing .ccb/ccb.config in a mounted project, run ccb reload --dry-run to preview the plan and ccb reload to apply it. The explicit reload path can dynamically add agents, add windows, add/remove managed tool windows, unload idle agents, and remove idle windows while keeping unrelated agents and panes running. It does not run as a background file watcher, and unsafe changes such as busy unloads, provider replacement, agent moves, tool command replacement, and arbitrary reshapes are rejected without killing existing panes.

If you want to discuss the configuration before writing it by hand, ask ccb_self to describe the target team. Blank projects include this route by default; projects with a user or project config should add agentroles.ccb_self if they have overridden the built-in default. Its built-in ccb-config skill proposes a complete config first, then writes .ccb/ccb.config only after confirmation.

Role Packs

Role Packs define reusable agent roles. A role can carry a stable identity, responsibilities, memory, provider-specific skills, tool hooks, and dependency setup. This keeps project config short and makes specialized agents reusable instead of copying long role instructions into every project.

The recommended default catalog roles are agentroles.ccb_self, the CCB self-maintenance role, and agentroles.archi, an architecture reviewer role from agent-roles-spec backed by Architec. install.sh install automatically attempts to install or refresh these recommended roles by default; ccb update refreshes installed roles and installs missing recommended roles in the user environment. You can also refresh manually:

ccb roles update agentroles.ccb_self
ccb roles update agentroles.archi

Project role bindings stay pinned by .ccb/role-lock.json. ccb update does not rewrite project locks. When you run ccb inside a project, CCB checks bound role locks against the current installed roles; interactive starts ask whether to refresh stale project locks in place, and non-interactive starts print a warning only.

ccb_self is strongly recommended for CCB projects because it is the built-in CCB expert agent. It carries CCB-specific knowledge about project config, command usage, role binding, reload boundaries, runtime diagnostics, guarded recovery, workflow repair, and single-agent restart assistance without taking over product work. Blank projects include it in the built-in default. Existing projects, and projects with user or project config that replace the built-in default, should add it explicitly where they want that maintenance agent:

ccb roles add agentroles.ccb_self:codex
ccb reload

To use agentroles.archi in a project, add it as a window leaf:

ccb roles add agentroles.archi:codex
ccb reload

This writes the compact form agentroles.archi:codex. At runtime CCB resolves it to the project-local agent archi, then projects the role memory and skills into that agent's managed provider home.

Config format examples: single window, multi-window, per-agent model/API

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

[ui.sidebar.view]
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].

Managed Neovim 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.neovim]
command = "ccb-nvim"
label = "neovim"

Rich workbench tools, including the managed Neovim profile, are installed and updated explicitly with ccb update rich. Ordinary install.sh install, ccb update, and ccb tools ... neovim do not provision standalone Neovim; the public Neovim tool route now directs users to ccb update rich. If nvim is not already on PATH, rich provisioning may download the official Neovim release tarball for Linux/macOS and verifies the release sha256 before activating it. It does not write ~/.config/nvim. The managed profile defaults to ASCII icons so terminals without Nerd Font support do not show unreadable boxes. To opt back into LazyVim glyph icons, launch the rich workbench with CCB_LAZYVIM_ICON_STYLE=glyph ccb rich. Use ccb tools doctor workbench --profile rich to verify the installed rich bundle. ccb rich launches only an already installed and enabled rich bundle; run ccb update rich first if the bundle is missing or disabled.

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.

Use ccb_self For CCB Config

The full ccb-config skill belongs to the agentroles.ccb_self role. It is not a globally inherited skill for every agent. CCB installs or refreshes this Role Pack by default, and blank projects include ccb_self in the built-in default config. Existing projects, or projects with a user/project config that replaces the built-in default, should bind it where they want the maintenance assistant.

ccb_self is more than a config helper: it is designed as CCB's self-understanding agent. Use it when you need help using CCB, explaining the active layout, choosing an agent topology, migrating .ccb/ccb.config, diagnosing project runtime state, or repairing a CCB workflow.

If you do not want to hand-write .ccb/ccb.config, ask ccb_self and describe your project goal, parallelism, window grouping, worktree isolation, provider/model/API preferences. ccb_self uses its built-in ccb-config skill to discuss the shape with you and propose a complete config.

Example:

ccb ask ccb_self "Design a team for a Python library: main coordinates work, three workers implement in worktrees, and one reviewer checks regressions and risks. Recommend whether this should stay single-window or become main/work/review windows."

For an existing project that does not already configure ccb_self, run ccb roles add agentroles.ccb_self:codex and ccb reload first.

ccb-config write flow and boundaries

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.

Agent Collaboration

Normal ask is submit-and-return: after handing work to the target agent, the current agent should not poll and wait.

Scenario	Recommended route
Human directly targets an agent	/ask reviewer ... or $ask reviewer ...
Current agent is inside an active CCB task and needs a child result before replying	ask --callback reviewer
Current agent sends independent work whose successful result does not need to return	ask --silence worker1
Queue or status diagnostics	pend, watch, ping, and similar commands are diagnostics only

When an agent submits a child task, choose flags from the result intent first, then add dependency and artifact preservation only when needed:

Need	Recommended flags
Publish or execute work; successful result is not useful	--silence
Get a short outcome: status, findings, risks, blockers, or next steps	--compact
Get full consultation, analysis, report, generated doc, or structured findings	--artifact-reply
Continue an active parent task only after the child result arrives	add --callback
Preserve exact pasted logs, diff, JSON/YAML, table, or copied text	add --artifact-request
Preserve exact input and full output	--artifact-io
Short question or short handoff where inline text is enough	plain ask

--callback and --silence control task relationship. Artifact flags control content preservation. The automatic long-message spill is only a fallback, so use artifact flags proactively when exact input or full output matters.

Why callback matters

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.

Editor Workflow

CCB does not require leaving your editor. A common setup is: editor for code, CCB terminal for multi-agent planning, implementation, review, testing, and handoff.

Install And Update

Requirements

• Node.js and npm for the recommended npm install path
• Python 3.10+
• tmux
• At least one agent CLI you plan to use, such as Codex, Claude, Gemini, Kimi, MiMo, Qwen, Cursor, Copilot, Crush, Kiro, OpenCode, Droid, or Antigravity
• Linux, macOS, or WSL

Current v7 / newer versions do not claim native Windows support. Native Windows support only applies to the v5 line. If you are on Windows and want current versions, use WSL and keep both ccb and agent CLIs inside WSL.

npm first

For first install, prefer npm:

npm install -g @seemseam/ccb

For later updates:

ccb update

GitHub Releases remain available for environments where npm is unavailable. Source checkout install is for development, fix validation, or temporary fallback.

Uninstall

ccb uninstall
ccb reinstall

# Fallback from the package or source directory:
./install.sh uninstall

FAQ

The expected agents did not appear

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.

Copy/paste is awkward

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.

I want to migrate an old compact config to multi-window

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.

The sidebar helper is unavailable

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.

Community And Credits

Thanks to the Linux.do community for testing, feedback, and discussion.

Thanks to tmux-agent-sidebar for the sidebar ideas and inspiration.

Release Notes

v7 highlights:

• Native CCB sidebar with per-window project view, agent status, and mouse switching.
• Comms split from agent activity, making communication status and provider pane activity clearer.
• version = 2 [windows] topology for workflow-oriented tmux window grouping.
• Explicit ccb reload support for dynamic agent/window load and idle unload without restarting unrelated agents.
• Compact / hybrid config compatibility, so single-window teams do not need forced migration.
• Hardened tmux, Ghostty, release helper, Codex trust, and provider session restore paths.

v7.6.0 - Rich Workbench Lifecycle

• 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.

v7.5.3 - Kimi Runtime Reliability And Hindsight Compatibility

• 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.
• 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.

v7.5.2 - Native CLI Provider Wave

• Adds built-in optional provider ids for Qwen Code (qwen), Cursor Agent (cursor), GitHub Copilot CLI (copilot), Crush (crush), Kiro CLI (kiro), and Pi (pi).
• 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 and Kiro. 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, and PI_START_CMD command overrides plus provider session bindings, runtime launchers, deterministic stubs, and focused execution tests.

v7.5.1 - MiMo Provider Release Surface

• 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.

v7.5.0 - Native CLI Providers And Homepage Sync

• 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.

v7.4.4 - Claude End-Turn And npm Release Surface

• 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.

v7.4.3 - PR #225 Reliability Follow-Up

• Restores the Claude launcher contract: inline --settings now reflects the materialized settings overlay without injecting provider env into settings JSON.
• Fixes Claude WSL Windows-executable environment forwarding so path variables use /p translation while ANTHROPIC_* API values pass through as raw env names.
• Hardens Antigravity resume lookup for SQLite bytes, str, and memoryview metadata and falls back to --continue if lookup fails.
• Adds regression tests for the Claude settings contract, WSL API env forwarding, and AGY resume fallback behavior.

v7.4.2 - Self-Supervision And Empty Reply Guards

• Hardens CCB self-supervision with bounded provider-runtime snapshots, project-view activity evidence, suspicion envelopes, and a self-first diagnosis path.
• Treats empty Claude/Gemini hook replies, Codex protocol task_complete empty replies, and AGY done-marker empty replies as incomplete with diagnostics.
• Preserves intentional no-reply behavior: --silence success remains completed, callback parent callback_pending remains legal, and abnormal silent completions stay diagnosable.
• Tightens default Role Pack install and project role-lock refresh handling for agentroles.archi and agentroles.ccb_self.

v7.4.1 - Maintenance Heartbeat And ccb_self Defaults

• Hardens the project-scoped maintenance heartbeat runner, schedule handling, activation suppression, and diagnostics evidence paths while keeping heartbeat opt-in.
• Adds ccb_self:codex bound to canonical agentroles.ccb_self in the built-in blank-project default and refreshes the recommended role during install/update provisioning without rewriting existing custom configs.
• Aligns CCB source with the agent-roles-spec role id agentroles.ccb_self; agentrole.ccb_self is accepted only as legacy input compatibility.
• Tightens generated config authority, Role Pack hook paths, and Codex prompt delivery acceptance guards.
• Adds the ccb_self expert manual, plan decisions, and tests for expert reference and communication recovery guidance.

v7.4.0 - ccb_self Maintenance Role

• Adds the agentroles.ccb_self self-maintenance Role Pack path for CCB config ownership, diagnostics, guarded recovery, chain repair, and single-agent restart assistance.
• Moves full ccb-config into the private ccb_self Role skill instead of a globally inherited skill.
• Installs or refreshes recommended default Role Packs, including agentroles.ccb_self, during install/update Role Pack provisioning.
• Adds ccb_self:codex bound to agentroles.ccb_self in the built-in blank project default; existing custom configs can still add agentroles.ccb_self:codex explicitly.

v7.3.8 - AGY Adapter And Project Tmux History

• Adds the Antigravity (agy) pane_quiet execution adapter with protocol parsing, command dispatch, polling, and docs for managed provider operation.
• Preserves 50000 lines of scrollback history for CCB-managed project tmux sessions, including project namespace create/reuse and detached runtime fallback paths.
• Keeps tmux mouse, vi key, clipboard, focus, and history policies consistently reapplied after the authoritative project session exists.
• Hardens Claude startup by passing inline --settings JSON when possible, preserving non-ASCII source paths through provider launch.

v7.3.7 - Ask Parameter Policy And Skill Guidance

• Updates inherited Claude, Codex, and Droid ask skills to choose flags from result intent first: --silence, --compact, --artifact-reply, or plain ask.
• Keeps dependency handling explicit by adding --callback only when an active parent job must wait for a child result.
• Separates artifact transport from task relationship: use --artifact-request and --artifact-io when exact input or input/output preservation matters.
• Adds the Agent Collaboration ask-parameter quick reference to README and README_zh.
• Adds the ask-parameter-policy plan tree, decision records, parameter matrix, and validation notes.

v7.3.6 - Provider Memory Ownership Cleanup

• Adds provider memory ownership policy: Claude, Codex, and OpenCode managed contexts no longer duplicate provider-native project memory inside the CCB generated bundle; Gemini keeps the previous behavior pending audit.
• Filters legacy CCB install marker blocks and old collaboration sections only from provider user memory, without rewriting user-owned memory files.
• Updates the default .ccb/ccb_memory.md template to v5 and removes the duplicate Ask Communication block already supplied by managed CCB memory.
• Adds seed-aware shared memory migration, upgrading only unedited old generated templates while preserving edited project memory.
• Stops Claude route-mode installs from writing ~/.claude/rules/ccb-config.md; install/uninstall now remove only CCB-marked legacy external config and preserve unmarked user files.
• Keeps source runtime startup import-safe by avoiding the tmux UI version detection cycle under ccb_test.

v7.3.5 - Tmux Border Hook Hotfix

• Fixes tmux after-select-pane hooks that could persist temporary release paths like /tmp/ccb-v...-release.../config/ccb-border.sh and later report returned 127 when clicking panes.
• Makes border hooks use run-shell -b with an executable guard, so stale script paths do not spam tmux errors.
• Refreshes active tmux UI hooks after ccb update on a best-effort basis, so users upgrading from v7.3.4 automatically rewrite bad hooks without failing Role Pack provisioning.
• v7.3.4 is withdrawn/prerelease; use v7.3.5 or newer as the stable upgrade target.

v7.3.4 - Withdrawn Prerelease

• Simplifies agentroles.archi tooling around the global @seemseam/archi npm package; CCB no longer manages separate Hippo, llmgateway, pip, venv, git, or editable Archi dependencies.
• Aligns ccb roles install/update/doctor agentroles.archi with the npm-provided archi CLI and bundled Hippo/llmgateway capabilities.
• Updates bin/ccb-arch to forward to archi, with a clear npm install -g @seemseam/archi hint when the CLI is missing.
• Fixes sidebar focus/refresh handling so selecting agents from the sidebar no longer restarts panes unnecessarily.
• Withdrawn because tmux border hooks could persist temporary release paths and later report ccb-border.sh ... returned 127; use v7.3.5 or newer.
• Adds the guarded ccb_test source entrypoint for isolated source-checkout validation without affecting installed CCB.
• Disables OpenCode autoupdate for managed panes through opencode.json and OPENCODE_DISABLE_AUTOUPDATE=true.
• Refreshes inherited ccb-config skills for config-only use, language-following behavior, YAML description quoting, clearer menu grouping, and sidebar pane restart guidance.
• Adds the config-designer UI plan tree and includes the main-branch @percent layout token plus Antigravity lifecycle cleanup updates.

v7.3.3 - Withdrawn Draft

• Withdrawn before stable rollout because it carried a sidebar focus/refresh regression. It is not the recommended release and should not be used for upgrades; use v7.3.5 or newer.

v7.3.2 - First-Install Role Pack Provisioning Hotfix

• Fixes a blank-environment first install bug where install.sh tried to update agentroles.archi before it was installed, leaving Role Pack provisioning incomplete.
• Keeps the existing install refresh path: ccb roles update agentroles.archi is still attempted first, then falls back to ccb roles install agentroles.archi when the role is missing.
• Aligns optional Role Pack skip messaging with the install path.
• Supersedes v7.3.1 as the recommended stable release for new installs; v7.3.1 is published but has the blank first-install Role Pack provisioning bug.

v7.3.1 - Agent Roles, Artifact Ask, And Shared Workspace Release

• Adds daemon-managed ask artifact transport with --artifact-request, --artifact-reply, and --artifact-io, including callback-compatible artifact replies for long outputs.
• Finalizes the Agent Roles store path around the external agent-roles manager and .roles/installed, while preserving ccb.archi compatibility for agentroles.archi.
• Adds shared workspace controls with workspace_path and workspace_group, plus provider_command_template for wrapping the CCB-built provider command without breaking resume handling.
• Fixes Claude startup under root, OpenCode ccb clear submit timing after restored sessions, and managed Neovim activation so the original runtime path is preserved.
• Refreshes inherited ask and ccb-config skills for submit-only ask rules, artifact modes, windows-first config, shared workspaces, and provider command templates.
• Stabilizes WSL/root release tests by making non-root Claude command assertions independent from the runner UID.

v7.3.0 - Superseded Prerelease

• Superseded by v7.3.1 after the remote WSL Tests workflow exposed root-sensitive Claude command assertions. The v7.3.0 GitHub release was kept as a prerelease and did not upload official release artifacts.

v7.2.12 - Agent Roles Store Migration Release

• Uses the external agent-roles package manager by default for Role Pack install, update, and sync.
• Writes Role Pack payloads into the spec-owned .roles/installed store.
• Copies existing legacy installed role snapshots into .roles/installed without deleting the old store; runtime lookup reads the spec-owned store only after migration.
• Routes ccb roles update --path ... through the Agent Roles manager so path updates also write .roles/installed.
• Supersedes v7.2.11, which was an incomplete opt-in preview release and should not be used as the recommended release.

v7.2.11 - Superseded Agent Roles Opt-In Preview

• Superseded by v7.2.12 after the release direction changed from an opt-in CCB_AGENT_ROLES_MANAGER=1 preview to a default-on Agent Roles manager migration.

v7.2.10 - Role Pack Post-Update Hotfix

• Fixes managed ccb update so optional Role Pack and Neovim provisioning runs through the newly installed ccb __post-update entrypoint instead of the old updater process.
• Repairs legacy installed ccb.archi role metadata under canonical agentroles.archi and falls back to the current catalog source when old source paths are gone.
• Preserves optional post-update provisioning as warnings, while CCB_INSTALL_ROLES=1, CCB_INSTALL_NEOVIM=1, or CCB_POST_UPDATE_REQUIRED=1 still fail the parent update when required provisioning fails.
• Keeps new config guidance on agentroles.archi; ccb.archi remains a legacy input alias only.

v7.2.9 - Agent Roles Catalog Release

• Moves the production architecture role out of the CCB source tree and consumes agentroles.archi from agent-roles-spec.
• Adds catalog-backed role list/install/update/sync/add/doctor behavior with installed-role metadata, project locks, digest pinning, and explicit re-add updates.
• Projects role memory, CCB adapter memory, provider skills, and Architec adapter hooks into managed provider homes.
• Keeps ccb.archi as a compatibility alias while writing canonical agentroles.archi bindings and locks.
• Fixes the source runtime guard so ccb --project <allowed-test-dir> ... smoke commands launched from the source checkout pass the release gate.
• Passes generated soak, fastpath, and storage cleanup smoke roots through CCB_SOURCE_ALLOWED_ROOTS.
• Passes the WSL mounted startup smoke project under /mnt/c/Temp through CCB_SOURCE_ALLOWED_ROOTS.
• Hardens the Claude restart provider blackbox test to wait for the running partial reply before asserting it.
• Hardens Role Pack CI fixtures so full GitHub Actions tests do not require a sibling agent-roles-spec checkout.

v7.2.8 - Superseded Role Fixture Hotfix

• Superseded by v7.2.9 after the release gate found that full GitHub Actions runners did not have the sibling agent-roles-spec checkout expected by Role Pack tests.

v7.2.7 - Superseded WSL Mounted Smoke Hotfix

• Superseded by v7.2.8 after the release gate found a provider blackbox timing race in the Claude restart partial-reply assertion.

v7.2.6 - Superseded Official Smoke Root Hotfix

• Superseded by v7.2.7 after the release gate found that the WSL mounted startup smoke in the main Tests workflow also needed its generated /mnt/c/Temp project in CCB_SOURCE_ALLOWED_ROOTS.

v7.2.5 - Superseded Source Runtime Guard Hotfix

• Superseded by v7.2.6 after the release gate found that official soak, fastpath, and storage cleanup smoke checks needed explicit generated test roots in CCB_SOURCE_ALLOWED_ROOTS.

v7.2.4 - Superseded Agent Roles Catalog Release

• Superseded by v7.2.5 after the release gate found that source checkout --project commands were rejected from the source cwd during CCBD real platform smoke checks.

v7.2.3 - Root Install Support Validation Hotfix

• Keeps the root install confirmation behavior from v7.2.2: root installs require explicit confirmation, while uninstall remains ungated.
• Preserves install identity metadata and ccb doctor runtime user/owner/root diagnostics.
• Fixes WSL release validation by making install metadata tests explicitly simulate non-root identity where required.

v7.2.2 - Root Install Confirmation Release

• Adds an explicit root install confirmation gate: install.sh install refuses root by default, accepts interactive yes, and requires CCB_ALLOW_ROOT_INSTALL=1 for non-interactive root installs.
• Keeps uninstall cleanup outside the root confirmation gate, so root-owned installs can still be removed.
• Records install identity metadata including root status, install user, and sudo user details.
• Extends ccb doctor with runtime user, owner, root state, and a warning when root runs inside a non-root project.
• Fixes the non-blocking build-info type hygiene issue by returning dict[str, object] from read_build_info().

v7.2.1 - Antigravity Runtime Follow-Up

• Completes agy / Google Antigravity runtime and session plumbing with provider runtime specs, client specs, public provider-core exports, and .agy-<agent>-session naming.
• Adds regression coverage for named Antigravity pane launches using AGY_START_CMD, auto-permission, restore continuation, and prepared-state compatibility.
• Aligns README provider lists and release surface so Antigravity is visible alongside Codex, Claude, Gemini, OpenCode, and Droid.
• Clarifies no-change reload semantics: non-dry-run ccb reload with no config delta returns noop / no_op without publishing a graph.
• Adds Agent Roles public specification planning notes for the future host-neutral RolePack project.

v7.2.0 - Role Packs And Managed Tools Release

• Adds the Role Pack surface with the built-in ccb.archi architecture role, role memory, Codex/Claude skill projection, and project role locks.
• Makes ccb roles add ccb.archi:codex the primary role onboarding command; config stores the shorthand while runtime resolves it to the local archi agent.
• Makes ccb roles install/update ccb.archi refresh role assets and dependencies by default; install/update prompts interactive users and gives non-interactive users the follow-up command.
• Adds managed tool windows such as [tool_windows.neovim], plus ccb tools install/doctor neovim, sidebar rows, and safe reload add/remove behavior for non-agent tools.
• Includes the new agy / Google Antigravity provider support from main.

v7.1.1 - Sidebar View Height Release

• Adds three configurable sidebar sections under [ui.sidebar.view]: agents_height, comms_height, and tips_height.
• Changes the default native sidebar split to Agents 50%, Comms 15%, and Tips 35%.
• Carries the height settings through config parsing, project_view payloads, reload planning, and the Rust sidebar TUI.
• Fixes reload reliability for same-name agent remounts: a dynamically unloaded retired agent can be rebuilt under the same name without runtime_authority_already_exists, while old stopped session records remain available for inheritance.
• Updates the inherited Codex/Claude ccb-config skill docs and references so generated or migrated windows topology exposes all three values.

v7.1.0 - Dynamic Reload Release

• Adds explicit hot reload for .ccb/ccb.config: use ccb reload --dry-run to preview and ccb reload to apply supported changes.
• Dynamically mounts append-only agents and new windows under the existing ccbd daemon without interrupting unrelated panes.
• Dynamically unloads idle removed agents and idle removed windows while preserving remaining agent panes.
• Treats config signature drift as reload-pending instead of a daemon restart trigger; busy unloads and unsafe replacements still fail closed.
• Starts the Role Pack surface with ccb.archi, ccb roles ..., project role locks, role memory inclusion, and provider skill projection.

v7.0.11 - Provider Activity And Sidebar Focus Release

• Records provider-native activity evidence from hook artifacts so sidebar status can reflect active, pending, idle, and failed provider work more accurately.
• Refreshes sidebar panes immediately after project focus changes by invalidating the cached project view and sending an in-session refresh.
• Restores fast tmux pane click focus with direct select-pane -t = ; send-keys -M, avoiding the slower hidden subprocess path for ordinary pane clicks.
• Hardens namespace config, provider hook install settings, clipboard/runtime launch paths, and Codex managed trust handling with focused regression coverage.

v7.0.10 - Sidebar Tips And Tmux Controls Release

• Keeps the native sidebar as a stable three-panel view: Tree 1/3, compact Comms 1/4, and Tips 5/12.
• Expands default Tips for projects without custom tips, covering pane movement and resize, window switching, copy mode, paste, and help.
• Preserves the top-right ↻ and × controls: × runs project-level ccb kill, while q and Esc exit only the sidebar.
• Documents and keeps CCB-managed tmux Vim controls: mode-keys vi, copy-mode v / C-v / y, prefix+h/j/k/l, and prefix+H/J/K/L.

v7.0.9 - README v7 Redesign Release

• Rebuilds README.md around the v7 visible multi-agent workspace, task-first onboarding, multi-agent approach comparison, v7 UI tour, Quick Start, tmux basics, config examples, and install/update flow.
• Adds real v7 terminal screenshots under assets/readme_v7/ for the public README walkthrough.
• Preserves the README redesign plan and supporting notes under docs/plantree/.
• Keeps the v7.0.8 runtime, ccb clear, config overlay, and sidebar fixes intact while refreshing the GitHub-facing documentation package.

See CHANGELOG.md for the full history.