# CCB - Agent CLI Hub and Teams

[![Version](https://img.shields.io/badge/version-6.2.8-orange.svg)]() [![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-lightgrey.svg)]() **English** | [Chinese](README_zh.md) [Why CCB](#why-ccb) · [What's New](#whats-new) · [Start and Stop](#start-and-stop) · [Configuration](#config-control) · [How to Use](#how-to-use) · [How to Install](#how-to-install) · [Release Notes](#release-notes)

--- ## Why CCB

1. One command for all required CLI operations and management

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

2. Agents can sense and communicate with each other

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

3. Project-level professional agent teams

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

![Showcase](assets/show.png)

Demo animations

## What's New

Latest release highlights

- **Config sources are explicit**: CCB reports whether the effective config came from the built-in default, user `~/.ccb/ccb.config`, or project `.ccb/ccb.config`. - **`ccb kill` cleanup is ordered after the response**: project tmux namespace destruction is deferred until after `stop_all` finalization, so cleanup completes even when kill is launched from a CCB tmux pane. - **Managed tmux stays isolated but usable**: CCB now explicitly enables owned `mouse on` and `set-clipboard on` policy in project namespaces and detached tmux paths. See [Release Notes](#release-notes) for the full history.

## Start and Stop ### Common Commands ```bash 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` resolves config in three layers: built-in default, user config at `~/.ccb/ccb.config`, then project config at `.ccb/ccb.config`. Project config has highest priority; if it is missing, CCB uses the user config when present, then the built-in default, without writing a new project config file. `.ccb/ccb_memory.md` is the project-wide shared memory document.

Config Design Skill

Use `ccb_config` when you want an agent to design or update the CCB team instead of editing config by hand. It is inherited by Claude and Codex installs and focuses on three user-authored files: - `.ccb/ccb.config` for the team, provider choices, pane layout, and worktree policy - `.ccb/ccb_memory.md` for shared project workflow guidance - `.ccb/agents//memory.md` for per-agent role guidance Invoke it from a supported provider skill surface, for example: ```text $ccb_config Design a team for a Python library with one coordinator, two worktree implementation agents, and one reviewer. ``` The skill helps choose agent names, providers, `inplace` versus `git-worktree`, compact layout syntax, and whether role instructions belong in shared or per-agent memory. It validates which config layer is active and tells you to restart CCB after file changes are complete.

Layout

Use the first compact line to define the team and pane layout: ```text 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`

Per-Agent API And Model

Keep the compact layout first, then add TOML tables only for agents that need their own API route, key, or model: ```toml 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..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: ```text writer:codex, reviewer:claude cmd; writer:codex, reviewer:claude; qa:gemini(worktree) cmd; fast:codex, deep:codex ``` Same provider, separate API keys: ```toml 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" ```

Update

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 inherited skills under `inherit_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 ```bash 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. ```bash git clone https://github.com/SeemSeam/claude_codex_bridge.git cd claude_codex_bridge ./install.sh install ``` 2. **Windows**
Use this path when your agent CLIs run natively on Windows. ```powershell git clone https://github.com/SeemSeam/claude_codex_bridge.git cd claude_codex_bridge powershell -ExecutionPolicy Bypass -File .\install.ps1 install ```

Platform notes

- 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. ## Development Tools Maintainer-only release and repository tools live under `dev_tools/`. They are versioned in git but excluded from official release artifacts. ## Useful Tools Optional user-facing tools live under `useful_tools/`. They are versioned in git and included in release artifacts, but they are not installed by default. Copy the tools you want into a global provider home or a specific managed agent home; see `useful_tools/README.md`. ## 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. ### Chained Ask Calls Normal `ask` is asynchronous: submit the handoff, then stop. When an agent is already handling a CCB task and needs another agent's result before it can finish, it must use callback routing: ```bash ccb ask --callback reviewer <<'EOF' Review this failing test and return the minimal blocker. EOF ``` CCB records the parent/child link, lets the current turn end, and later delivers the child result back to the parent agent as a new continuation task. This supports chains such as `agent2 -> agent4 -> agent1 -> agent3` without polling or blocking the active mailbox head. Use plain `ask` only outside an active task. Inside an active CCB task, use `--callback` when the child result is required, or `--silence` for independent work whose successful result does not need to return. 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 Neovim integration with multi-AI code review

Neovim integration with multi-AI code review

Write in editors like **Neovim** while agents review and iterate in parallel. --- ## Requirements - **Python 3.10+** - **Terminal:** `tmux` ## Uninstall ```bash ccb uninstall ccb reinstall # Fallback: ./install.sh uninstall ``` --- ## Community 📧 Email: `bfly123@126.com` 💬 WeChat: `seemseam-com` Thanks to the [Linux.do community](https://linux.do) 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.

v6.2.8 - Config Source, Stop Cleanup, And Tmux Policy Release

- Includes explicit config source kinds for built-in defaults, user `~/.ccb/ccb.config`, and project `.ccb/ccb.config`, with project config taking highest priority. - Keeps project tmux namespace destruction deferred until after the stop-all response finalizer so `ccb kill` / `ccb kill -f` can complete cleanup from inside a CCB pane. - Keeps managed tmux config isolated while explicitly enabling CCB-owned mouse and clipboard support in project namespaces and detached tmux paths.

v6.2.7 - Config Source And Stop Cleanup Release

- Reports explicit config source kinds for built-in defaults, user `~/.ccb/ccb.config`, and project `.ccb/ccb.config`, with project config taking highest priority. - Updates `ccb config validate`, README/docs, and inherited `ccb_config` skill guidance to describe the active config layer. - Defers project tmux namespace destruction until after the stop-all response finalizer so `ccb kill` / `ccb kill -f` can complete cleanup from inside a CCB pane.

v6.2.6 - Tmux Isolation And Startup Hardening Release

- Runs managed tmux commands with `tmux -f /dev/null ...` by default so user tmux config, plugins, hooks, and sidebars cannot reshape CCB-managed layouts. - Adds source/dev install hardening: Python wrapper entrypoint, `CCB_PYTHON_BIN`, post-install `ccb` and `ask` smoke checks, and bounded Droid MCP registration. - Keeps restore-fresh and Claude trust setup reliable while preserving Claude auto-permission as `--permission-mode bypassPermissions`. - Keeps removed wait-alias parser hints out of the current ask surface.

v6.2.5 - Claude Managed Memory De-Duplication Hotfix

- Stops copying project-level `CLAUDE.md` into managed `.claude/CLAUDE.md`, so Claude reads it once from the working directory. - Keeps provider user memory, CCB shared project memory, and per-agent private memory in the managed Claude bundle. - Adds an opt-out flag for provider-native project memory in `load_memory_sources` while preserving default behavior for other callers.

v6.2.4 - Codex Managed Config TOML Hotfix

- Renders dict values as inline TOML tables so inherited Codex configs with inline table arrays no longer crash during managed-home projection. - Updates fallback copied Codex configs in-place without duplicating `[features]`, and respects `[table]` plus `[[array_of_tables]]` section boundaries. - Auto-installs `tomli>=2.0.0` from `install.sh` and `install.ps1` when no TOML reader is available, with `CCB_INSTALL_TOMLI=0` skip support. - Installs `tomli` inside managed venv release installs before optional watchdog dependency setup.

v6.2.3 - Architecture Hotspot Optimization Release

- Splits the GitHub release checker into focused local, Markdown, GitHub, workflow, and asset helper modules. - Moves shared provider memory projection events, markers, signatures, and bundle materialization into provider-core helpers. - Splits startup update handling into state, refresh, and flow modules. - Extracts provider-home storage cleanup classification and records the architecture optimization plan.

v6.2.2 - Codex Managed Home Migration Prompt Hotfix

- Disables `[features].external_migration` inside managed Codex homes so panes do not block on an interactive migration prompt. - Preserves inherited Codex source-home config, model/API settings, and other feature flags. - Adds coverage for parsed TOML inheritance and fallback copy behavior when TOML parsing is unavailable.

v6.2.1 - Inherited CCB Config Skill Release

- Adds inherited Claude and Codex `ccb_config` skills for designing `.ccb/ccb.config`, choosing agent roles/providers/worktree layout, and updating shared plus per-agent memory. - Moves CCB-owned inherited skills under `inherit_skills/` while keeping optional `useful_tools/` user-installable rather than inherited. - Shortens injected ask reply guidance, removes nested-routing text from every ask body, keeps injected source text English-only, and expands explicit-output detection. - Simplifies project/runtime memory wording and updates `ccb_config` memory-routing examples for direct callback handoffs and separate root work packages.

v6.2.0 - Callback Ask Chain Release

- Adds `ccb ask --callback ` so active agents can delegate work and receive the child result later as a continuation task. - Rejects accidental plain nested `ask` from active CCB tasks; `--callback` is for required child results and `--silence` is for independent no-result-needed work. - Persists callback edges and repairs missed continuation submissions across dispatcher restarts. - Updates Claude, Codex, and Droid ask skills plus generated project memory with callback-chain guidance.

v6.1.21 - Kill And Restart Cleanup Hotfix

- Keeps `ccb kill -f` finalization queued even if the client pane is destroyed before the daemon can write the socket response. - Preserves full tmux socket paths and lifecycle owner/keeper pid authority during project-scoped kill cleanup. - Narrows process fallback matching to CCB control-plane commands for the same `--project`, avoiding broad project-root matches. - Clears stale provider execution files at ccbd startup and when late updates arrive for terminal or missing jobs.

v6.1.20 - Claude Active Version Cache Release

- Detects the source home's active Claude Code symlink under `~/.local/bin/claude` and prefers that version for managed Claude startup. - Copies the active source-home Claude version into the CCB provider cache, then points managed `.local/bin/claude` at the cached active version. - Preserves previous shared-cache fallback behavior when the source active-version layout is unavailable. - Updates provider workspace preparation and the Claude binary-cache contract to document the source-home active-version preference.

v6.1.19 - Managed Ask Skill Projection Release

- Routes inherited Claude `skills/` and `commands/` through CCB projected assets instead of copy-sync, so system-installed ask skills reach managed Claude agents without duplicating provider homes. - Adds managed Droid `FACTORY_HOME` support with projected system `~/.factory/skills` and a session-scoped Droid sessions root. - Updates Droid launch, execution polling, and communicator session readers to follow the managed session root after restart or session rotation. - Adds concise default ask reply guidance plus `--compact` and `--silence` submission modes.

v6.1.18 - Heartbeat Timeout And Useful Tools Release

- Keeps running-job heartbeat observations internal until three no-progress intervals, then terminalizes once with `heartbeat_timeout` and a small communication-test recommendation. - Treats provider completion progress semantically, so cursor offsets, polling timestamps, and session snapshot bookkeeping no longer extend completion deadlines. - Preserves `reliability_*` runtime state through persistence so restored provider jobs do not reset timeout deadlines. - Adds `useful_tools/useful_tools.zip` to the versioned optional tools shipped in release artifacts.

v6.1.17 - Completion Binding And Codex Session Hotfix

- Binds Claude Stop-hook completion artifacts to the structured outer `CCB_REQ_ID`, so forwarded text or tool output cannot redirect completion events to an older job. - Keeps Codex session identity independent from memory projection freshness, allowing `.ccb/ccb_memory.md` updates to refresh memory without forcing a fresh conversation. - Includes PR #205 mailbox recovery for stale terminal `task_request` queue heads whose attempts are already terminal. - Adds regression coverage across transcript parsing, provider finish hooks, Codex resume behavior, and mailbox stale-head cleanup.

v6.1.16 - Memory Handoff And Claude Route Hotfix

- Adds CCB-owned submit-only ask coordination rules to generated managed-memory bundles, preventing stale shared memory text from reintroducing polling/waiting behavior. - Updates new `.ccb/ccb_memory.md` templates with the same fire-and-forget handoff guidance. - Makes managed Claude startup prefer ccswitch-updated `~/.claude/settings.json` route settings over stale caller-shell `ANTHROPIC_BASE_URL`. - Documents the Claude route inheritance contract and adds regression coverage for the new priority order.

v6.1.15 - Kill Shutdown Reliability Hotfix

- Waits for recorded `ccbd` and keeper pids to exit during remote `ccb kill` instead of trusting lifecycle unmounted alone. - Finalizes lifecycle to stopped/unmounted before writing the final shutdown report, allowing `ccb cleanup` to run immediately after kill. - Adds regression coverage for prepared pid snapshots, remote lifecycle finalization, and shutdown intent ordering.

v6.1.14 - macOS Claude Keychain Boundary Follow-up

- Documents the managed Claude `Library/Keychains` fallback as agent-local secret auth compatibility state. - Clarifies that support bundles must not follow the fallback Keychains symlink and storage diagnostics classify it as secret auth state.

v6.1.13 - macOS Claude Keychain Fallback

- Links `Library/Keychains` into managed Claude homes on macOS when `com.apple.security.plist` is absent, preserving Claude login lookup on newer setups. - Removes the fallback link when Claude auth inheritance is disabled. - Classifies the fallback Keychains symlink as secret auth state in storage diagnostics.

v6.1.12 - Claude Tmux Permission Release

- Packages the merged Claude auto-permission pane fix so tmux launches do not block on the bypass permissions confirmation prompt. - Carries forward the v6.1.11 WSL cleanup smoke alignment and Claude rollback-cache preservation fixes.

v6.1.11 - WSL Cleanup Smoke Alignment

- Aligns WSL mounted-drive storage cleanup smoke with the current relocated-runtime shared-cache contract. - Includes the Claude cleanup rollback preservation fix from v6.1.10.

v6.1.10 - Claude Cleanup Rollback Hotfix

- Keeps the active Claude Code version plus one rollback version during `ccb cleanup`. - Restores the real-platform storage cleanup smoke expectation across macOS and WSL.

v6.1.9 - Storage Dedup And Shutdown Hardening

- Reduces `.ccb` growth by routing Codex projected assets through symlink/shared bundle paths and by moving/pruning rebuildable Claude and Gemini cache content. - Extends `ccb cleanup` to reclaim old Claude shared versions, Gemini shared cache data, rebuildable Claude caches, and stale pane crash logs. - Hardens `ccb kill` so old `ccbd`/keeper pids are snapshotted, waited on, and terminated without racing a newer backend generation. - Prevents Claude tmux panes from blocking on the bypass permissions confirmation prompt.

v6.1.8 - macOS Claude Keychain Preference Hotfix

- Managed Claude homes on macOS now inherit `Library/Preferences/com.apple.security.plist` so Claude login lookup can resolve the expected default Keychain. - The preference projection stays tied to auth inheritance and is removed when Claude auth inheritance is disabled.

v6.1.7 - Codex Memory Freshness Hotfix

- Codex now refreshes shared project memory instead of resuming stale AGENTS context after `.ccb/ccb_memory.md` changes. - Claude and Droid ask skills now submit through heredoc and stop immediately after submit.

v6.1.6 - Startup And Claude Auth Hotfix

- Fixes a first-start race between ccbd start and heartbeat maintenance. - `.ccb/ccb_memory.md` is the only shared CCB memory anchor. - Adds Claude macOS `Claude Code-credentials` Keychain lookup.

v6.1.5 - Tmux Startup Hotfix

- Fixes startup races that could show `Cannot split: pane ... does not exist` or `respawn pane failed: can't find pane`. - Provider panes still use the managed respawn path.

v6.1.4 - Shared Project Memory V1

- `.ccb/ccb_memory.md` is the project-wide shared memory document.

v6.1.2 - Provider Storage Boundary Hardening

- **Storage Classes Made Explicit**: `ccb doctor storage` now separates authority, session state, secrets, workspaces, user content, projected config, rebuildable cache, and startup authority bundles. - **Safe Cleanup Added**: `ccb cleanup` refuses to run while `ccbd` or ask jobs are active, prunes only safe rebuildable provider caches, and preserves sessions, auth, and current Claude binaries. - **Shared Cache Guardrails Added**: future provider shared-cache paths now resolve under the effective runtime-state root with WSL drvfs safety checks and manifest creation.

v6.1.1 - Ask Skill and Memory Injection Cleanup

- **Ask Skill Kept as the Only Installed Skill**: Claude, Codex, and Droid/Factory installs now publish only the `ask` skill and remove older CCB helper skills such as `ping`, `pend`, `all-plan`, and `file-op`. - **Global Memory Injection Removed**: installers no longer append CCB collaboration blocks into global `CLAUDE.md`, installed `AGENTS.md`, or `.clinerules`; existing CCB-marked blocks are cleaned during install. - **Legacy Skill Sources Removed**: repository skill templates now keep only the provider-specific `ask` skill assets.

v6.1.0 - CCBD Ask Stability and Observer Convergence

- **Ask Submit Fastpath Stabilized**: `ccb ask` returns bounded receipts without waiting on provider readiness, mailbox history projection, or long maintenance ticks - **Lifecycle and Shutdown Races Closed**: stop-all, shutdown, restart, and background supervision now keep stopped runtimes and terminal jobs from being revived by stale work - **Provider Completion Recovery Hardened**: Codex polling follows rebound session bindings after restart so jobs complete from the current managed session log - **Mailbox Summary Read Model Landed**: routine `queue`, `inbox`, and `pend` paths prefer maintained summaries and explicitly degrade when summaries are missing or corrupt - **Observer Surfaces Weakened**: `pend`, `watch`, `queue`, and `inbox` are non-authoritative snapshots; use `ccb trace ` when lineage details are needed - **Real Platform Validation Added**: GitHub Actions now runs macOS and WSL ccbd/ask smoke, communication matrix, short soak, and fastpath stress jobs

v6.0.29 - WSL Runtime State Relocation

- **Runtime State Moved Off Mounted Drives**: on WSL projects rooted under `/mnt//...`, project authority remains in `.ccb` while `ccbd/` and agent runtime state relocate to a local Linux state root with explicit marker files - **Diagnostics and Bundle Mapping Updated**: doctor output and support bundles now expose the project anchor, runtime-state root, relocation reason, and logical `.ccb` archive paths for relocated runtime files - **Provider Lookup and Ask Routing Kept Stable**: relocated runtime directories still resolve back to the project anchor for session discovery and ask sender attribution without changing Linux or macOS default layout behavior - **Runtime Markers Are Validated**: relocated runtime markers and refs now reject malformed or mismatched payloads, so stale relocation residue cannot silently remap one project to another - **WSL Smoke Matches the Final Contract**: the release smoke now expects the runtime-root relocation path that the relocated project actually writes, instead of treating the first relocation step as the final socket fallback

v6.0.28 - WSL Control Plane Socket Hardening

- **WSL Control Plane Startup Hardened**: keeper and daemon readiness probes now share the configured control-plane RPC timeout instead of using shorter hardcoded budgets that could misread a slow mounted-drive startup as config drift - **Socket Server Accept Path Decoupled**: ccbd now accepts connections separately from a serialized worker lane, so one slow or incomplete client request no longer blocks new control-plane probes or heartbeats - **Transient Connect Retry Added**: Unix socket clients retry only short-lived connect races within the existing timeout budget, without retrying already-sent RPC requests or mutating operations - **README Refreshed**: the public README was reorganized around the current agent CLI hub/team workflow and updated release guidance

v6.0.27 - macOS Foreground Attach Timeout Hardening

- **Foreground Attach Timeout Split**: interactive `ccb` startup now uses foreground-attach-specific RPC and target-ready budgets instead of reusing the short daemon probe timeout - **macOS Attach Race Reduced**: foreground attach now tolerates slower post-start `ccbd` ping and tmux namespace/window visibility on macOS without redefining daemon startup success - **Clearer Attach Failures**: attach errors now distinguish between an unresponsive control-plane ping and a responsive daemon whose project namespace is not yet attachable

v6.0.26 - macOS Install And Claude Ask Cleanup

- **macOS Release Install Fixed**: release installs keep generated CLI wrappers bound to the managed `.venv` Python, avoiding environment drift when optional dependencies such as `watchdog` are installed - **WSL Install Tests Unblocked**: watchdog install regression tests explicitly confirm WSL non-interactive install mode so CI covers the intended optional-dependency path - **Claude Ask Prompt Slimmed Down**: managed Claude `ask` no longer injects local ask skill runtime text into the prompt body, keeping agent-to-agent asks limited to the request anchor and the user's original message

v6.0.25 - Gemini Managed Home Alignment

- **Gemini Login Inheritance Fixed**: managed Gemini panes now set `GEMINI_CLI_HOME` to the isolated home root so Gemini CLI reads the projected `.gemini/.env`, settings, and login state from the same managed boundary - **Regression Coverage Added**: launcher tests now lock the aligned `HOME`, `GEMINI_CLI_HOME`, and `GEMINI_ROOT` contract and guard against writing settings under nested `.gemini/.gemini` - **Community Contact Trimmed**: the standalone Linux.do contact entry was removed while keeping the Linux.do community acknowledgement below the contact block

v6.0.24 - WSL Official Login Transport

- **WSL Provider Transport Inherited**: managed provider panes now preserve user-session proxy, CA, browser, and WSL interop environment needed by official-login and Codex Apps/MCP networking paths - **Managed Isolation Preserved**: transport inheritance is centralized and does not allow caller-global `CODEX_HOME`, `GEMINI_ROOT`, `CLAUDE_PROJECTS_ROOT`, or `CCB_CALLER_*` runtime authority to override agent-scoped managed state - **Gemini Login Projection Extended**: managed Gemini homes now project allowlisted `.gemini/.env` API credentials, `google_accounts.json`, and `GEMINI_CLI_HOME` while diagnostics continue excluding copied auth artifacts - **Opencode Session Detection Hardened**: opencode now treats env-session mode as active only when its provider-specific runtime env is present, avoiding stale generic `CCB_SESSION_ID` contamination - **Community Entry Refreshed**: README now includes the refreshed WeChat group QR image and Linux.do community acknowledgement so users can find the current support channels from the public project page

v6.0.23 - CI Matrix Stabilization

- **Release CI Greened**: latest release validation now points at a commit whose full GitHub Actions test workflow passes across Ubuntu, macOS, WSL, and install smoke jobs - **Provider Blackbox Coverage Focused**: heavy pane-backed provider restart / rotate / settle tests now run in a dedicated Ubuntu provider-blackbox job instead of being repeated across every OS and Python matrix cell - **macOS Socket Test Race Fixed**: ccbd socket tests now wait for the daemon socket to answer ping requests before issuing RPCs, avoiding macOS runner readiness races

v6.0.22 - Claude macOS Login Inheritance

- **macOS Keychain Login Inherited**: managed Claude startup now reads official Claude Code login credentials from macOS Keychain and materializes an equivalent project-scoped `.claude/.credentials.json` inside isolated Claude homes - **Claude Account Metadata Refreshed**: inherited `.claude.json` account metadata now refreshes from the source home while preserving managed workspace trust and excluding source workspace trust or API key secrets - **Default Config Startup Fixed**: keeper startup now treats a missing `.ccb/ccb.config` as a request to use the built-in default project config instead of exiting before `ccbd` can mount - **Regression Coverage Expanded**: tests now lock Keychain projection, metadata refresh, and disabled-auth cleanup paths for managed Claude login inheritance

v6.0.21 - Claude Hook Asset Projection

- **CodeIsland Hook Assets Inherited**: managed Claude startup now copies referenced source-home hook assets such as `.codeisland/` when inherited Claude hooks call `$HOME/.codeisland/...`, preventing missing-hook failures inside isolated Claude homes - **Config Boundary Preserved**: third-party hook assets are copied only when Claude config inheritance is enabled and the inherited hook payload actually references that home-relative asset path - **Diagnostics Redaction Extended**: diagnostic bundles now exclude copied `.codeisland/` provider-state assets while still including ordinary managed Claude settings for support

v6.0.20 - Claude Official Login Source Home Fix

- **Claude Official Login Source Home Fixed**: managed Claude startup now treats `.ccb/agents/*/provider-state/*/home` as an isolated runtime home, not the user's source home, so official browser-login credentials are copied from the real account home - **Claude Credential Path Coverage**: managed Claude homes now project Claude Code official-login credentials from `.claude/.credentials.json` while retaining compatibility with `.config/claude-code/auth.json` - **Regression Coverage Added**: tests now lock source-home fallback, launcher projection, diagnostics redaction, and workspace preparation for official Claude login inheritance

v6.0.19 - Claude Official Login Inheritance

- **Claude Official Login Projection**: managed Claude homes now project Claude Code official login credentials from `.claude/.credentials.json`, so browser-login-backed auth can be inherited into isolated CCB runtimes instead of only API-token-based settings auth - **Managed Login Auth Retention**: when global Claude auth artifacts disappear but managed Claude state already holds a valid project-scoped login, startup now preserves that managed login auth across restart instead of silently dropping it - **Auth Cleanup And Regression Coverage**: disabling auth inheritance now clears stale copied Claude login credentials, and targeted tests now lock the projection, cleanup, and launcher startup paths

v6.0.18 - Gemini Hook Empty-Reply Guard

- **Empty Gemini Hook Replies No Longer Burn Jobs**: managed Gemini `AfterAgent` hooks that fire with an empty reply now downgrade to `incomplete` instead of terminalizing as a false exact completion - **Exact Hook Polling Becomes Safer**: Gemini exact-hook polling now ignores `completed` hook artifacts with no reply text, allowing observed session-stability or timeout reliability paths to converge the request instead of accepting a blank terminal result - **Regression Coverage Added**: targeted tests now lock the empty-reply guard at both the finish-hook artifact writer and Gemini execution-service polling layers

v6.0.17 - Gemini Custom Endpoint Env Propagation

- **Gemini Endpoint Override Restored**: managed Gemini startup now preserves `GOOGLE_GEMINI_BASE_URL` end to end, so custom endpoint and proxy-backed Gemini CLI setups no longer fall back to Google's default production API host - **Gemini Model Env Allowlisted**: control-plane and provider-profile env filtering now preserve `GEMINI_MODEL`, allowing isolated Gemini agents to keep explicit model selection instead of silently dropping it at startup - **Config Shortcut Alignment**: Gemini `key` / `url` shortcuts now materialize the same environment variables the current Gemini CLI actually reads, keeping explicit config-based routes aligned with shell-level env behavior

v6.0.16 - Codex Plugin Projection & Cmd Shell Compatibility

- **Codex Plugin Projection Fixed**: managed Codex homes now project plugin-bundle authority under `.tmp/plugins/` and `.tmp/plugins.sha`, so isolated agents inherit the marketplace catalog and installed plugin assets they actually need instead of starting with plugin-enabled config but missing bundles - **Plugin Refresh Semantics Tightened**: startup now refreshes managed plugin projections as one authority unit, removes stale managed plugin residue when the source projection disappears, and keeps a cheap no-recopy fast path when the source plugin freshness marker is unchanged - **Cmd Shell / Session Env Hardening**: the `cmd` pane now directly `exec`s the resolved user shell and preserves ordinary user-session transport variables such as `DISPLAY`, `WAYLAND_DISPLAY`, `DBUS_SESSION_BUS_ADDRESS`, `XAUTHORITY`, and `SSH_AUTH_SOCK`, improving fish/zsh and GUI-command compatibility

v6.0.15 - Codex Route Authority & Foreground Attach Polish

- **Codex Explicit Route Authority**: managed Codex homes now materialize agent-local `config.toml` and `auth.json` as the sole authority for explicit `key` / `url` routes, so agent-scoped API overrides replace inherited global provider routes instead of drifting back to system config - **Codex Session Namespace Rotation**: managed Codex startup now fingerprints explicit route authority, stamps reusable session bindings with that authority, and rotates stale `sessions/` namespaces before launch when the bound route no longer matches - **Foreground Attach UX Hardening**: interactive `ccb` startup now seeds tmux namespace creation from the real terminal viewport and issues a best-effort client refresh after attach so first paint matches the current terminal size without manual redraw

v6.0.14 - Claude Logout Recovery Hardening

- **Managed Claude Auth Preservation**: managed Claude homes now preserve agent-local login auth when the global Claude home has been logged out, so a project-scoped re-login survives restart instead of re-entering a browser-link loop - **Auth Projection Semantics Tightened**: Claude startup still refreshes source auth when it exists, but no longer treats missing source auth as an instruction to blank managed auth; disabled auth inheritance still clears stale copied auth state - **Startup Regression Coverage Expanded**: targeted regressions now lock this behavior at the projection layer, provider workspace preparation, and Claude launcher startup path

v6.0.13 - macOS Release Path & Preview Packaging Fix

- **macOS Release Path**: shared release artifact naming and updater resolution now cover the macOS universal bundle alongside Linux/WSL release assets - **Source Dev Install Mode**: installs from a git checkout now stay linked to the live source tree, skip startup auto-update prompts, and can switch to a managed release install through `ccb update` - **Agent API / Model Shortcuts**: `.ccb/ccb.config` now accepts flat per-agent `key`, `url`, and `model` shortcuts so common provider overrides stay concise - **Preview Packaging Hardening**: preview release exports now exclude generated output paths inside the repo, fixing recursive self-copy failures such as `dist-macos-smoke`

v6.0.12 - Non-Blocking Startup Update Prompt

- **Cached Startup Prompt**: interactive foreground `ccb` start now reads install-scoped cached release metadata and only prompts when a newer stable release is already known locally - **Background Refresh**: missing or stale update cache now refreshes in the background with short network budgets instead of delaying the project startup path - **Upgrade / Defer / Silence**: startup prompt supports upgrade now, defer for the current version, or silence that exact version - **Startup Boundary Preserved**: release-update checks remain advisory and outside the project lifecycle startup transaction

v6.0.11 - Project Startup Hotfix

- **Cold Start Namespace Fix**: project tmux namespace startup now treats `no server running on ` as an absent namespace that must be created, instead of failing startup as a generic tmux inspect error - **Release Regression Coverage**: targeted namespace backend/state regression tests now lock this cold-start path so `ccb -> ping -> kill` blackbox lifecycle stays covered - **Contract Clarification**: the startup supervision contract now explicitly defines project-socket `no server running` as a recreate signal rather than a fatal inspect failure

v6.0.10 - Startup Budget Hardening & Gemini Login Inheritance

- **Gemini Login Inheritance**: managed Gemini homes now project login-auth selection and `oauth_creds.json` for `oauth-personal` reuse, and remove stale copied credentials when auth inheritance is disabled - **Shared Tmux Ready Budget**: project-owned `respawn-pane` now uses the same tmux ready-retry budget as namespace create/reflow, reducing transient `no server running` failures during startup and supervision - **Background Startup Compatibility**: background lifecycle startup keeps supervision compatibility while separating readiness-probe timeouts from operational RPC budgets - **Diagnostics Secret Redaction**: diagnostic bundles now exclude Gemini `oauth_creds.json` alongside other provider credential artifacts

v6.0.9 - Cross-Platform Lifecycle & Watch Stability

- **WSL Compatibility Fixed**: project runtime now avoids binding Unix sockets onto unsupported WSL mounted-drive filesystems and hardens installer staging plus tmux namespace readiness - **macOS Lifecycle Hardening**: startup, restore, and project identity paths were tightened so macOS follows the same lifecycle authority model as Linux without intermittent startup drift - **Respawn Retry Boundary**: transient tmux respawn fork, server-exit, and readiness failures are retried inside runtime supervision instead of leaking outward as false lifecycle failures - **Watch Reconnect Recovery**: observer recovery can resume from persisted state after short daemon interruptions, while reconnect loops still honor their internal deadlines - **Cross-Platform CI Coverage**: GitHub Actions now exercises macOS install smoke and WSL compatibility paths alongside the existing Linux matrix

v6.0.7 - Lifecycle Authority & Shutdown Stability

- **Keeper-Owned Lifecycle Authority**: keeper now owns lifecycle progression through authoritative `lifecycle.json`, generation fencing, and namespace epoch tracking - **Mounted-State Read Fixes**: `ping ccbd` and `ping agent` now report current mounted state from live authority instead of stale failure residue after recovery - **Shutdown Transaction Hardening**: `ccb kill` and `ccb kill -f` now terminate non-terminal jobs during shutdown so restart cannot resurrect old executions via restore or auto-retry - **Real Blackbox Repro Closed**: the real `ask -> kill -f -> restart` lifecycle repro now converges cleanly to `project_shutdown` without lingering active execution

v6.0.6 - Agent Isolation Stability & Kill Lifecycle Fix

- **Agent Isolation Stability**: Codex, Claude, and Gemini managed agents keep their session state under project-scoped `.ccb/agents//provider-state/...` - **Restart Inheritance Safety**: restarts restore only the matching managed agent history instead of adopting manual provider conversations from the same working directory - **Project Dotfile Protection**: managed startup no longer rewrites project-level `.claude`, `.gemini`, or `.codex` provider dotfiles - **Kill Lifecycle Fix**: interactive `ccb` no longer reports a false attach failure after `ccb kill` intentionally tears down the current project tmux session

v6.0.5 - Agent Isolation Stability

- **Agent Isolation Stability**: Codex, Claude, and Gemini managed agents keep their session state under project-scoped `.ccb/agents//provider-state/...` - **Restart Inheritance Safety**: restarts restore only the matching managed agent history instead of adopting manual provider conversations from the same working directory - **Project Dotfile Protection**: managed startup no longer rewrites project-level `.claude`, `.gemini`, or `.codex` provider dotfiles

v6.0.4 - Legacy Update Compatibility Hotfix

- **Backward-Compatible Release Assets**: Linux release tarballs now include a compatibility alias so older 6.x updaters can still find the extracted installer path - **Old Clients Can Upgrade Again**: existing `v6.0.1` and `v6.0.2` installs can now update to the latest stable release without needing a patched local updater first - **Modern Updater Still Clean**: current runtime keeps the correct extracted-directory resolution and does not depend on the legacy alias

v6.0.3 - Self-Update Tarball Hotfix

- **Release Upgrade Fixed**: `ccb update` now resolves the extracted release directory correctly instead of treating the `.tar.gz` asset name as a folder - **Installer Handoff Restored**: self-update now finds `install.sh` inside extracted release assets and completes end to end - **Release Build Hygiene**: Linux release packaging now ignores local `.ccb-requests/` residue so official builds are reproducible

v6.0.2 - Caller Attribution, Mailbox Routing, and macOS Install Warning

- **Correct Caller Identity**: `ccb ask` now preserves the real originating agent so replies return to the right mailbox instead of being attributed as `user` - **Stable Reply Routing**: async replies for delegated jobs now land back in the expected mailbox chain, including `cmd`-anchored flows - **Mixed-Case Agent Recovery**: config layout recovery no longer drifts when configured agent names use mixed case - **macOS Homebrew Warning**: `install.sh` now warns clearly when Homebrew is missing before users try to install tmux and other dependencies

v6.0.1 - Release Archive Hygiene & Safer Upgrade Extraction

- **Source Archive Cleanup**: Removed accidentally tracked pytest temp artifacts so GitHub source archives are clean again - **Safer Tar Validation**: Upgrade extraction now rejects unsafe symlink targets before unpacking - **Clearer Failure Mode**: Unsafe archive extraction errors now point users toward release assets or clean source archives - **Regression Coverage**: Added tests to block ephemeral repo artifacts from being tracked again

v6.0.0 - Native Multi-Agent Runtime, Stable Native Communication, and Linux-Only Auto Upgrade

**🚀 New Runtime Direction:** - **Infinite Parallel Agent Foundation**: CCB v6 is built as the runtime base for effectively unbounded agent-to-agent delegation and orchestration - **Independent Agent Identity**: agents can carry different roles, task ownership, skill libraries, and personalities - **Focused User Command Surface**: the public user workflow stays centered on `ccb`, `ccb -s`, `ccb -n`, `ccb kill`, and `ccb kill -f` **🧱 Project Rebuild Semantics:** - **Config-Preserving Legacy Cleanup**: On first `ccb` inside a pre-6 project, CCB preserves `.ccb/ccb.config`, removes the rest of the old `.ccb` runtime state, and rebuilds locally - **Runtime Marker**: Modern projects now record `.ccb/project-runtime.json` so current runtime state is distinguished from legacy state - **Worktree Safety Guard**: Dirty or unmerged CCB-managed worktrees still

all-plan

Installation

SKILL.md