CCB - Agent CLI Hub and Teams

English | Chinese

Why CCB · What's New · Start and Stop · Configuration · How to Use · How to Install · Release Notes

Why CCB

Start, attach, recover, supervise, and operate Claude, Codex, Gemini, OpenCode, and Droid from one terminal workspace.

• one project entry point for all supported CLI agents
• one place to manage startup, restore, attach, and shutdown
• one consistent runtime flow instead of per-tool ad hoc handling

Named agents can discover each other, use /ask, broadcast updates, and delegate work without copy/paste.

• direct agent-to-agent delegation with named targets
• broadcast sync for all live agents when the whole team needs the same context
• explicit handoff patterns for builder, reviewer, and QA style workflows

Build project-local teams with roles, pane layout, provider state, worktree isolation, and lifecycle continuity.

• role-based team composition per project
• isolated provider state under the project runtime
• optional worktrees for agents that need separate working sets
• continuity across restart, recovery, and pane supervision

What's New

• Ask stays fast under real load: submit receipts stay bounded even while provider work, mailbox refresh, and background maintenance continue asynchronously.
• ccbd lifecycle stabilization: stop-all, shutdown, restart, and background supervision no longer revive stopped runtimes or regress terminal jobs through stale maintenance work.
• Observer commands are explicitly weak: pend, watch, queue, and inbox render as non-authoritative snapshots; use ccb ask wait <job_id> for terminal truth.
• Linux/macOS/WSL real-platform validation expanded: release validation now includes real tmux ccbd/ask smoke, communication matrix, soak, and fastpath stress coverage with stub providers.

See Release Notes for the full history.

Start and Stop

Common Commands

ccb                              # Start default agents from .ccb/ccb.config
ccb -s                           # Safe start: keep configured/manual permission behavior
ccb -n                           # Rebuild .ccb except ccb.config, then start fresh
ccb kill                         # Stop this project's background runtime
ccb kill -f                      # Force cleanup before rebuilding state

Tmux copy/paste: drag with the left mouse button to copy, and use Ctrl+Shift+V to paste.

Config Control

ccb is controlled by .ccb/ccb.config. This file is project-local and user-authored; if it is missing, CCB uses the built-in default without writing a new config file.

Use the first compact line to define the team and pane layout:

cmd; writer:codex, reviewer:claude; qa:gemini(worktree)

That layout means:

• cmd is the shell pane
• writer, reviewer, and qa are agent names and pane titles
• codex, claude, and gemini are providers
• ; splits panes left-to-right; , stacks panes top-to-bottom
• qa runs in an isolated git worktree; agents without (worktree) run inplace

Keep the compact layout first, then add TOML tables only for agents that need their own API route, key, or model:

cmd; builder:codex, reviewer:claude; research:gemini(worktree)

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

[agents.reviewer]
key = "sk-ant-..."
url = "https://api.anthropic.com"
model = "opus"

[agents.research]
key = "gemini-key"
model = "gemini-pro"

Notes:

• key and url are agent-local shortcuts for codex, claude, and gemini.
• model is an agent-local shortcut for codex, claude, gemini, and opencode.
• Setting key or url makes that agent use the explicit API authority instead of inheriting a global provider API credential.
• For advanced provider env, use agents.<name>.provider_profile.env; do not mix provider API env keys with key / url on the same agent.
• Do not commit real API keys in a public repo.

Common compact examples:

writer:codex, reviewer:claude
cmd; writer:codex, reviewer:claude; qa:gemini(worktree)
cmd; fast:codex, deep:codex

Same provider, separate API keys:

cmd; fast:codex, deep:codex

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

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

CCB v6 currently supports ccb update on Linux, macOS, and WSL. A major upgrade fully replaces the installed runtime. On the first ccb inside an older project, CCB preserves .ccb/ccb.config, clears the rest of the old .ccb state, and rebuilds locally.

If you installed from a git checkout with ./install.sh install, that install now runs in source dev mode:

• Global ccb and ask link back to the checkout instead of using a copied snapshot
• CCB-owned skills and helper scripts also follow the live source tree
• Source installs do not participate in startup auto-update prompts
• Stay on the source/dev track with git pull or by switching commits, then rerun ./install.sh install
• Or run ccb update to install the latest stable release and repoint global ccb links to the managed release install

ccb update              # Update to the latest stable release
ccb update 6            # Update to the highest v6.x.x version
ccb update 6.0          # Update to the highest v6.0.x version
ccb update 6.0.5        # Update to a specific version
ccb uninstall           # Uninstall ccb and clean configs
ccb reinstall           # Clean then reinstall ccb

How to Install

1. Unix-like (Linux, macOS, WSL) Use this path when ccb and your agent CLIs run in the same Unix-like shell.

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

2. Windows Use this path when your agent CLIs run natively on Windows.

git clone https://github.com/bfly123/claude_codex_bridge.git
cd claude_codex_bridge
powershell -ExecutionPolicy Bypass -File .\install.ps1 install

• macOS and Linux share the same install.sh path.
• For WSL, keep both ccb and the agent CLIs inside WSL.
• On WSL mounted-drive projects, project authority stays under .ccb while runtime state may relocate to a local Linux state root for socket and agent runtime durability.
• Native Windows mux is still being rebuilt around psmux.
• The fuller Windows bootstrap helper lives at scripts/bootstrap-windows-test-env.ps1.

Install note: the commands above install from a git checkout today. After that, run ccb update to download the latest stable GitHub release asset and complete the managed release upgrade automatically.

How to Use

CCB is agent-first. You can use explicit /ask, explicit $ask, or let one agent decide to call another on its own.

| Mode | Example | | :--- | :--- | | Explicit /ask | /ask reviewer review the parser changes in src/parser.ts | | Explicit $ask | $ask reviewer review the parser changes in src/parser.ts | | Implicit delegation | Ask reviewer to check the parser edge cases, then summarize the issues back to me. |

Use explicit routing when you want a specific target. Use natural language when you want the current agent to decide whether to delegate.

Note: for implicit use, add the ask skill basics to your system memory first; otherwise Codex/Claude may fall back to their own built-in multi-agent behavior instead of calling CCB ask.

Editor Integration

Write in editors like Neovim while agents review and iterate in parallel.

Requirements

• Python 3.10+
• Terminal: tmux

Uninstall

ccb uninstall
ccb reinstall

# Fallback:
./install.sh uninstall

Community

📧 Email: bfly123@126.com 💬 WeChat: seemseam-com

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

Release Notes

Historical note: older release notes below may mention askd, legacy flags, or removed commands. Those references are kept only as changelog history and do not redefine the current CLI surface.

• Ask Submit Fastpath Stabilized: ccb ask