---

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

What's New

Latest release highlights

• WSL Runtime State Relocated: on mounted-drive WSL projects, project authority stays under .ccb while ccbd and agent runtime state move to a local Linux state root with explicit runtime-root markers and diagnostics mapping.
• Provider Lookup and Ask Routing Stay Stable: relocated runtime directories still resolve back to the project anchor for session discovery and ask sender attribution.
• Control-plane sockets remain resilient: slow clients no longer block new probes, and transient connect races are retried inside the existing timeout budget.
• README stays aligned with the current release: install, config, update, and delegation guidance continue to match the current CLI surface.

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.

Layout

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

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:

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"

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

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

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.

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: [email protected]
💬 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.

v6.0.29 - WSL Runtime State Relocation

• Runtime State Moved Off Mounted Drives: on WSL projects rooted under /mnt/<drive>/..., 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

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 execs 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 <project socket> 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: watch and ask wait can recover terminal results from persisted state after short daemon interruptions, while reconnect loops still honor timeout 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/<agent>/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/<agent>/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 block destructive rebuilds until the user resolves them

🔄 Upgrade Policy:

• Linux/macOS/WSL: ccb update is available on Linux, macOS, and WSL for the 6.x line
• Release-Only Upgrades: Source tags are still published with each version, but ccb update for 6.x installs the GitHub release asset, not the source archive
• Stable Release Targeting: Default upgrades now resolve to the latest stable release instead of the moving main branch
• Major Upgrade Confirmation: Upgrading into 6.0.0 requires explicit confirmation before replacing the installed runtime

🤖 Provider Reliability:

• Gemini Multi-Round Stability: Gemini completion polling now waits through tool activity and no longer exits on the first stable planning sentence

v5.3.0 - Simplified CLI, Explicit Worktree Mode, and Gemini Completion Stability

🚀 User-Facing CLI Simplification:

• Narrowed Main Surface: Public startup flow is now ccb, ccb -s, ccb -n, ccb kill, and ccb kill -f
• Model Control Plane Still Available: ask, ping, pend, and watch remain for agent-to-agent orchestration without cluttering primary help

🧱 Workspace Semantics Made Explicit:

• Default Inplace Mode: Compact ccb.config entries now expand to workspace_mode='inplace'
• Opt-In Isolation: Use agent:provider(worktree) when an agent must run in its own git worktree
• Safe Agent Churn: Adding agents no longer disturbs existing worktrees; removing or renaming worktree agents retires clean branches and blocks on dirty or unmerged ones

🛠 Recovery & Reset Hardening:

• Config-Preserving Reset: ccb -n rebuilds project runtime state while keeping .ccb/ccb.config
• Stale Registration Cleanup: Start and reset now prune missing registered git worktrees before rematerialization
• Kill Warnings: ccb kill warns clearly when a worktree agent still has unmerged or dirty state

🤖 Gemini Completion Fix:

• No Early Stop on Planning Text: Gemini completion polling now tracks tool-call activity and waits for the real final reply instead of finishing on the first stable “I will ...” message

v5.2.6 - Async Communication & Gemini 0.29 Compatibility

🔧 Gemini CLI 0.29.0 Support:

• Dual Hash Strategy: Session path discovery now supports both basename and SHA-256 formats
• Autostart: ccb-ping and ccb-mounted gain --autostart flag to launch offline provider daemons
• Cleanup Path: zombie-session cleanup is now handled by ccb kill -f

🔗 Async Communication Fixes:

• OpenCode Deadlock: Fixed session ID pinning that caused second async call to always fail
• Legacy Completion Compatibility: Legacy text-based providers still tolerate mismatched CCB_DONE lines in degraded mode
• req_id Regex: opencode_comm.py now matches both old hex and new timestamp-based formats
• Gemini Idle Timeout: Auto-detect reply completion when Gemini omits CCB_DONE marker (15s idle, configurable via CCB_GEMINI_IDLE_TIMEOUT)
• Gemini Prompt Hardening: Stronger instructions to reduce CCB_DONE omission rate

🛠 Other Fixes:

• lpend: Prefers fresh Claude session path when registry is stale

v5.2.5 - Async Guardrail Hardening

🔧 Async Turn-Stop Fix:

• Global Guardrail: Added mandatory Async Guardrail rule to claude-md-ccb.md — covers both /ask skill and direct Bash(ask ...) calls
• Marker Consistency: bin/ask now emits [CCB_ASYNC_SUBMITTED provider=xxx] matching all other provider scripts
• DRY Skills: Ask skill rules reference global guardrail with local fallback, single source of truth

This fix prevents Claude from polling/sleeping after submitting async tasks.

v5.2.3 - Project-Local History & Legacy Compatibility

📂 Project-Local History:

• Local Storage: Auto context exports now save to ./.ccb/history/ per project
• Safe Scope: Auto transfer runs only for the current working directory
• Claude /continue: New skill to attach the latest history file via @

🧩 Legacy Compatibility:

• Auto Migration: .ccb_config is detected and upgraded to .ccb when possible
• Fallback Lookup: Legacy sessions still resolve cleanly during transition

These changes keep handoff artifacts scoped to the project and make upgrades smoother.

v5.2.2 - Session Switch Capture & Context Transfer

🔁 Session Switch Tracking:

• Old Session Fields: .claude-session now records old_claude_session_id / old_claude_session_path with old_updated_at
• Auto Context Export: Previous Claude session is automatically extracted to ./.ccb/history/claude-<timestamp>-<old_id>.md
• Cleaner Transfers: Noise filtering removes protocol markers and guardrails while keeping tool-only actions

These updates make session handoff more reliable and easier to audit.

v5.2.1 - Enhanced Ask Command Stability

🔧 Stability Improvements:

• Watchdog File Monitoring: Real-time session updates with efficient file watching
• Mandatory Caller Field: Improved request tracking and routing reliability
• Unified Execution Model: Simplified ask skill execution across all platforms
• Auto-Dependency Installation: Watchdog library installed automatically during setup
• Session Registry: Enhanced Claude adapter with automatic session monitoring

These improvements significantly enhance the reliability of cross-AI communication and reduce session binding failures.

v5.2.0 - Historical mail bridge release

This release introduced the old mail gateway path. That flow is now removed from the supported agent-first surface and remains legacy code only during cleanup.

v5.1.3 - Tmux Claude Ask Stability

🔧 Fixes & Improvements:

• tmux Claude ask: read replies from pane output with automatic pipe-pane logging for more reliable completion

See CHANGELOG.md for full details.

v5.1.2 - Daemon & Hooks Reliability

🔧 Fixes & Improvements:

• Claude Completion Hook: Unified askd now triggers completion hook for Claude
• askd Lifecycle: askd is bound to CCB lifecycle to avoid stale daemons
• Mounted Detection: ccb-mounted uses ping-based detection across all platforms
• State File Lookup: askd_client falls back to CCB_RUN_DIR for daemon state files

See CHANGELOG.md for full details.

v5.1.1 - Unified Daemon + Bug Fixes

🔧 Bug Fixes & Improvements:

• Unified Daemon: All providers now use unified askd daemon architecture
• Install/Uninstall: Fixed installation and uninstallation bugs
• Process Management: Fixed kill/termination issues

See CHANGELOG.md for full details.

v5.1.0 - Unified Command System + Historical Native Windows Experiment

🚀 Unified Commands - Replace provider-specific commands with agent-first workflows:

Old Commands	New Unified Command
cask, gask, oask, dask, lask	ccb ask <agent> [from <sender>] <message>
cping, gping, oping, dping, lping	ccb ping <agent|all>
cpend, gpend, opend, dpend, lpend	ccb pend <agent|job_id> [N]

Supported providers: gemini, codex, opencode, droid, claude

🪟 Historical native Windows experiment:

• Earlier releases explored a native Windows split-pane path
• Background execution used PowerShell + DETACHED_PROCESS
• Large payload delivery used stdin-based handoff
• That backend has since been removed; future native Windows mux support is being redesigned around psmux

📦 New Skills:

• /ask <agent> <message> - Send work to a named agent
• /ping <agent|all> - Check mounted agent health
• /pend <agent|job_id> [N] - View latest agent reply

See CHANGELOG.md for full details.

v5.0.6 - Zombie session cleanup + mounted skill optimization

• Zombie Cleanup: ccb kill -f now cleans up orphaned tmux sessions globally (sessions whose parent process has exited)
• Mounted Skill: Optimized to use pgrep for daemon detection (~4x faster), extracted to standalone ccb-mounted script
• Droid Skills: Added full skill set (cask/gask/lask/oask + ping/pend variants) to droid_skills/
• Install: Added install_droid_skills() to install Droid skills to ~/.droid/skills/

v5.0.5 - Droid delegation tools + setup

• Droid: Adds delegation tools (ccb_ask_* plus cask/gask/lask/oask aliases).
• Setup: New ccb droid setup-delegation command for MCP registration.
• Installer: Auto-registers Droid delegation when droid is detected (opt-out via env).

Details & usage

Usage:

/all-plan <requirement>

Example:

/all-plan Design a caching layer for the API with Redis

Highlights:

• Socratic Ladder + Superpowers Lenses + Anti-pattern analysis.
• Availability-gated dispatch (use only mounted CLIs).
• Two-round reviewer refinement with merged design.

v5.0.0 - Any AI as primary driver

• Claude Independence: No need to start Claude first; Codex can act as the primary CLI.
• Unified Control: Single entry point controls Claude/OpenCode/Gemini.
• Simplified Launch: Dropped ccb up; use ccb ... or the default ccb.config.
• Flexible Mounting: More flexible pane mounting and session binding.
• Default Config: Uses a built-in default when .ccb/ccb.config is missing; CCB no longer creates that file automatically.
• Project askd Autostart: project askd and provider runtimes auto-start in the project tmux namespace when needed.
• Session Robustness: PID liveness checks prevent stale sessions.

v4.0 - tmux-first refactor

• Full Refactor: Cleaner structure, better stability, and easier extension.
• Terminal Runtime Cleanup: The runtime moved toward a single tmux-oriented pane/control model instead of parallel terminal backends.
• Perfect tmux Experience: Stable layouts + pane titles/borders + session-scoped theming.
• Works in Any Terminal: If your terminal can run tmux, CCB can provide the full multi-model split experience.

v3.0 - Smart daemons

• True Parallelism: Submit multiple tasks to Codex, Gemini, or OpenCode simultaneously.
• Cross-AI Orchestration: Claude and Codex can now drive OpenCode agents together.
• Bulletproof Stability: Daemons auto-start on first request and stop after idle.
• Chained Execution: Codex can delegate to OpenCode for multi-step workflows.
• Smart Interruption: Gemini tasks handle interruption safely.

Details

✨ Key Features

• 🔄 True Parallelism: Submit multiple tasks to Codex, Gemini, or OpenCode simultaneously. Provider runtimes queue and execute them serially, ensuring no context pollution.
• 🤝 Cross-AI Orchestration: Claude and Codex can now simultaneously drive OpenCode agents. All requests are arbitrated by the project askd layer.
• 🛡️ Bulletproof Stability: The runtime layer is self-managing. It starts on first use and shuts down after idleness to save resources.
• ⚡ Chained Execution: Advanced workflows supported! Codex can autonomously call oask to delegate sub-tasks to OpenCode models.
• 🛑 Smart Interruption: Gemini tasks now support intelligent interruption detection, automatically handling stops and ensuring workflow continuity.

🧩 Feature Support Matrix

Feature	Codex	Gemini	OpenCode
Parallel Queue	✅	✅	✅
Interruption Awareness	✅	✅	-
Response Isolation	✅	✅	✅

📊 View Real-world Stress Test Results

Scenario 1: Claude & Codex Concurrent Access to OpenCode
Both agents firing requests simultaneously, perfectly coordinated by the daemon.

Source	Task	Result	Status
🤖 Claude	CLAUDE-A	CLAUDE-A	🟢
🤖 Claude	CLAUDE-B	CLAUDE-B	🟢
💻 Codex	CODEX-A	CODEX-A	🟢
💻 Codex	CODEX-B	CODEX-B	🟢

Scenario 2: Recursive/Chained Calls
Codex autonomously driving OpenCode for a 5-step workflow.

Request	Exit Code	Response
ONE	0	CODEX-ONE
TWO	0	CODEX-TWO
THREE	0	CODEX-THREE
FOUR	0	CODEX-FOUR
FIVE	0	CODEX-FIVE

Older Version History

v5.0.6

• Zombie Cleanup: ccb kill -f cleans up orphaned tmux sessions globally
• Mounted Skill: Optimized with pgrep, extracted to ccb-mounted script
• Droid Skills: Full skill set added to droid_skills/

v5.0.5

• Droid: Add delegation tools (ccb_ask_* and cask/gask/lask/oask) plus ccb droid setup-delegation for MCP install

v5.0.4

• OpenCode: 修复 -r 恢复在多项目切换后失效的问题

v5.0.3

• Daemons: 全新的稳定守护进程设计

v5.0.1

• Skills: New /all-plan with Superpowers brainstorming + availability gating; Codex lping/lpend added; gask keeps brief summaries with CCB_DONE.
• Status Bar: Role label now reads role name from .autoflow/roles.json (supports _meta.name) and caches per path.
• Installer: Copy skill subdirectories (e.g., references/) for Claude/Codex installs.
• CLI: Added ccb uninstall / ccb reinstall with Claude config cleanup.
• Routing: Tighter project/session resolution (prefer .ccb anchor; avoid cross-project Claude session mismatches).

v5.0.0

• Claude Independence: No need to start Claude first; Codex (or any agent) can be the primary CLI
• Unified Control: Single entry point controls Claude/OpenCode/Gemini equally
• Simplified Launch: Removed ccb up; a built-in default is used when .ccb/ccb.config is missing
• Flexible Mounting: More flexible pane mounting and session binding
• Project askd Autostart: project askd and provider runtimes auto-start in the project tmux namespace when needed
• Session Robustness: PID liveness checks prevent stale sessions

v4.1.3

• Codex Config: Automatically migrate deprecated sandbox_mode = "full-auto" to "danger-full-access" to fix Codex startup
• Stability: Fixed race conditions where fast-exiting commands could close panes before remain-on-exit was set
• Tmux: More robust pane detection (prefer stable $TMUX_PANE env var) and better fallback when split targets disappear

v4.1.2

• Performance: Added caching for tmux status bar (git branch & ccb status) to reduce system load
• Strict Tmux: Explicitly require tmux for auto-launch; removed error-prone auto-attach logic
• CLI: Added --print-version flag for fast version checks

v4.1.1

• CLI Fix: Improved flag preservation (e.g., -a) when relaunching ccb in tmux
• UX: Better error messages when running in non-interactive sessions
• Install: Force update skills to ensure latest versions are applied

v4.1.0

• Async Guardrail: cask/gask/oask prints a post-submit guardrail reminder for Claude
• Sync Mode: add --sync to suppress guardrail prompts for Codex callers
• Codex Skills: update oask/gask skills to wait silently with --sync

v4.0.9

• Project_ID Simplification: ccb_project_id uses current-directory .ccb/ anchor (no ancestor traversal, no git dependency)
• Codex Skills Stability: Codex oask/gask skills default to waiting (--timeout -1) to avoid sending the next task too early

v4.0.8

• Codex Log Binding Refresh: the Codex runtime now periodically refreshes .codex-session log paths by parsing start_cmd and scanning latest logs
• Tmux Clipboard Enhancement: Added xsel support and update-environment for better clipboard integration across GUI/remote sessions

v4.0.7

• Tmux Status Bar Redesign: Dual-line status bar with modern dot indicators (●/○), git branch, and CCB version display
• Session Freshness: Always scan logs for latest session instead of using cached session file
• Simplified Auto Mode (Historical): auto-permission behavior was consolidated into the current primary start flow

v4.0.6

• Session Overrides: cping/gping/oping/cpend/opend support --session-file / CCB_SESSION_FILE to bypass wrong cwd

v4.0.5

• Gemini Reliability: Retry reading Gemini session JSON to avoid transient partial-write failures
• Claude Code Reliability: gpend supports --session-file / CCB_SESSION_FILE to bypass wrong cwd

v4.0.4

• Fix: Auto-repair duplicate [projects.\"...\"] entries in ~/.codex/config.toml before starting Codex

v4.0.3

• Project Cleanliness: Store session files under .ccb/ (fallback to legacy root dotfiles)
• Claude Code Reliability: cask/gask/oask support --session-file / CCB_SESSION_FILE to bypass wrong cwd
• Codex Config Safety: Write auto-approval settings into a CCB-marked block to avoid config conflicts

v4.0.2

• Clipboard Paste: Cross-platform support (xclip/wl-paste/pbpaste) in tmux config
• Install UX: Auto-reload tmux config after installation
• Stability: Default TMUX_ENTER_DELAY set to 0.5s for better reliability

v4.0.1

• Tokyo Night Theme: Switch tmux status bar and pane borders to Tokyo Night color palette

v4.0

• Full Refactor: Rebuilt from the ground up with a cleaner architecture
• Perfect tmux Support: First-class splits, pane labels, borders and statusline
• Works in Any Terminal: Recommended to run everything in tmux (except native Windows)

v3.0.0

• Smart Runtime Queue: project askd with 60s idle timeout and provider queue support
• Cross-AI Collaboration: Support multiple agents (Claude/Codex) calling one agent (OpenCode) simultaneously
• Interruption Detection: Gemini now supports intelligent interruption handling
• Chained Execution: Codex can call oask to drive OpenCode
• Stability: Robust queue management and lock files

v2.3.9

• Fix oask session tracking bug - follow new session when OpenCode creates one

v2.3.8

• Plan mode enabled for autoflow projects regardless of -a flag

v2.3.7

• Per-directory lock: different working directories can run cask/gask/oask independently

v2.3.6

• Add non-blocking lock for cask/gask/oask to prevent concurrent requests
• Unify oask with cask/gask logic (use _wait_for_complete_reply)

v2.3.5

• Fix plan mode conflict with auto mode (--dangerously-skip-permissions)
• Fix oask returning stale reply when OpenCode still processing

v2.3.4

• Auto-enable plan mode when autoflow is installed

v2.3.3

• Simplify cping.md to match oping/gping style (~65% token reduction)

v2.3.2

• Optimize skill files: extract common patterns to docs/async-ask-pattern.md (~60% token reduction)

v2.3.1

• Fix race condition in gask/cask: pre-check for existing messages before wait loop