English | Chinese
Why CCB · What's New · Start and Stop · Configuration · How to Use · How to Install · Release Notes
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
Latest release highlights
ccb clearis now built in: you can send provider-native/clearto all mounted agents or only named agents without restarting the project runtime.- Pane mouse focus is fixed: tmux pane clicks now switch focus cleanly again instead of tripping the broken
select-paneescape path. - Windows overlays behave predictably:
version = 2[windows]is now the mounted-agent authority, while matching[agents.<name>]tables work as overlays and stale unreferenced tables are ignored. - Clear workflows are installable skills: inherited Claude and Codex installs now project
ccb-clear, and Claude managed settings allowBash(ccb clear *).
See Release Notes for the full history.
ccb # Start default agents from .ccb/ccb.config
ccb -s # Safe start: keep configured/manual permission behavior
ccb -n # Rebuild runtime state; keep config and managed agent history
ccb clear [agent...] # Send /clear to all or selected managed agent panes
ccb kill # Stop this project's background runtime
ccb kill -f # Force cleanup before rebuilding stateTmux copy/paste: drag with the left mouse button to copy, and use Ctrl+Shift+V to paste.
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, migrate, or update the CCB team instead of editing config by hand. It is inherited by Claude and Codex installs and defaults to changing only the active config authority:
.ccb/ccb.configfor the team, provider choices, pane layout, and worktree policy
It can also update .ccb/ccb_memory.md and .ccb/agents/<agent>/memory.md for shared workflow or per-agent role guidance, but only when you explicitly ask for memory design.
Invoke it from a supported provider skill surface, for example:
$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, optional [windows] migration for multi-window teams, and whether a config-only change is enough. For old compact or hybrid configs, it can ask how many windows you want, propose the grouping, and migrate to the current version = 2 windows topology. 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:
cmd; writer:codex, reviewer:claude; qa:gemini(worktree)
That layout means:
cmdis the shell panewriter,reviewer, andqaare agent names and pane titlescodex,claude, andgeminiare providers;splits panes left-to-right;,stacks panes top-to-bottomqaruns in an isolated git worktree; agents without(worktree)runinplace
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:
keyandurlare agent-local shortcuts forcodex,claude, andgemini.modelis an agent-local shortcut forcodex,claude,gemini, andopencode.- Setting
keyorurlmakes 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 withkey/urlon 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
Compact and hybrid configs without [windows] remain legacy-compatible single-window layouts.
Use explicit windows topology when you want named tmux windows or per-window native sidebars:
version = 2
entry_window = "main"
[windows]
main = "main:codex"
work = "worker1:codex(worktree), worker2:codex(worktree), worker3:claude(worktree)"
review = "reviewer:claude, discuss: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
ccbandasklink 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 pullor by switching commits, then rerun./install.sh install - Or run
ccb updateto install the latest stable release and repoint globalccblinks 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- Unix-like (Linux, macOS, WSL)
Use this path whenccband your agent CLIs run in the same Unix-like shell.
git clone https://github.com/SeemSeam/claude_codex_bridge.git
cd claude_codex_bridge
./install.sh install- Windows
Use this path when your agent CLIs run natively on Windows.
git clone https://github.com/SeemSeam/claude_codex_bridge.git
cd claude_codex_bridge
powershell -ExecutionPolicy Bypass -File .\install.ps1 installPlatform notes
- macOS and Linux share the same
install.shpath. - For WSL, keep both
ccband the agent CLIs inside WSL. - On WSL mounted-drive projects, project authority stays under
.ccbwhile 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.
Maintainer-only release and repository tools live under dev_tools/. They are versioned in git but excluded from official release artifacts.
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.
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.
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:
ccb ask --callback reviewer <<'EOF'
Review this failing test and return the minimal blocker.
EOFCCB 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.
Write in editors like Neovim while agents review and iterate in parallel.
- Python 3.10+
- Terminal:
tmux
ccb uninstall
ccb reinstall
# Fallback:
./install.sh uninstall📧 Email: bfly123@126.com
💬 WeChat: seemseam-com
Thanks to the Linux.do community for testing, feedback, and discussion support.
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.
v7.0.8 - Clear Context And Config Overlay Release
- Adds
ccb clear [agent...]so mounted agents can receive provider-native/clearwithout deleting project state or restarting runtimes. - Fixes tmux pane mouse focus switching by removing the bad
select-paneescaping from the default pane click action. - Makes
version = 2[windows]topology authoritative for mounted agents, treats same-name[agents.<name>]tables as overlays, and ignores stale unreferenced agent tables. - Ships inherited
ccb-clearskills for Claude and Codex installs and grants Claude managed settingsBash(ccb clear *).
v7.0.7 - Sidebar Controls And Width Sync Release
- Adds full refresh, in-place project pane restart, and exit controls to the sidebar title bar, with matching keyboard and tmux mouse paths.
- Routes sidebar tree clicks through hidden
ccb __sidebar-clickhelpers so window and agent focus recovery goes back throughccbd. - Synchronizes sidebar width changes across windows, supports integer cell widths, and reapplies stored widths on
window-resizedinstead of treating tmux's temporary squeeze as a new user preference.
v7.0.6 - macOS Release Test Smoke Hotfix
- Fixes the macOS GitHub Tests release-install smoke by prebuilding a host-runnable
bin/ccb-agent-sidebarbefore simulating a release install from a source checkout. - Preserves the v7.0.5 fixes for Claude keychain service override, macOS update binary preservation, and explicit sidebar rebuild requirements.
v7.0.5 - Claude Keychain And macOS Update Hotfix
- Adds
CCB_KEYCHAIN_SERVICE_OVERRIDEfor managed Claude macOS Keychain binding and preserves it in control-plane environments. - Prevents
ccb updatestaging from line-ending-normalizing binary files, keeping the packagedbin/ccb-agent-sidebarintact on macOS. - Makes sidebar local rebuild requirements explicit when
cargoorrustcis missing.
v7.0.4 - Project View Refresh And Runtime Hardening Release
- Optimizes sidebar/project view refresh with short-lived response caching, bounded recent-job tail reads, and per-build tmux pane capture reuse.
- Adds targeted runtime lookup helpers for job tails, message attempts/replies, and JSONL tail reads to keep comms state responsive as runtime files grow.
- Hardens keeper/process validation and daemon/socket lifecycle paths around project-root ownership and stopping state.
- Renames inherited config skills to canonical
ccb-config, removes legacyccb_configduring install, and refreshes useful tool packages.
v7.0.3 - macOS Sidebar Universal Binary Hotfix
- Ships
ccb-macos-universal.tar.gzwith a true universalbin/ccb-agent-sidebarbuilt for bothx86_64-apple-darwinandaarch64-apple-darwin. - Adds release CI checks that inspect the macOS helper with
file, requireuniversal binary, and run a helper--helpsmoke before upload. - Extends macOS GitHub Tests so release preview packaging verifies the packaged sidebar helper, not only the archive presence.
v7.0.2 - Codex Trust And Sidebar Compatibility Hotfix
- Fixes Codex managed home directory-trust prompts by writing trusted project/workspace entries and using native auto-permission flags.
- Builds Linux release/sidebar helper assets on Ubuntu 22.04 for broader glibc compatibility.
- Verifies and rebuilds
ccb-agent-sidebarduring install when an existing or prebuilt helper cannot run on the host. - Resolves source sidebar wrapper symlinks before locating the repo target binary.
- Refines sidebar activity and width handling for active jobs, callback waits, provider background work, and multi-agent grids.
v7.0.1 - Sidebar Release Packaging Hotfix
- Fixes sidebar artifact checksum generation on macOS by using
sha256sum,shasum -a 256, orpython3, restoring GitHub Tests for the v7 release line.
v7.0.0 - Native Sidebar Control Release
- Adds the native Rust
ccb-agent-sidebarhelper with per-window project view, fixed gray sidebar identity, colored provider/runtime activity status, and mouse/keyboard focus switching. - Splits top agent activity from bottom Comms: top rows reflect provider pane/runtime activity, while Comms stays tied to CCB ask/job tracking and recovery.
- Adds
version = 2[windows]topology support for multiple named tmux windows with sidebars, while legacy compact/hybrid configs remain one business window and keepcmdsemantics. - Updates
ccb-configdocs/skills for windows topology migration and preserves explicit multi-window mounting behavior. - Hardens Ghostty/tmux
TERMcompatibility, tmux environment/mouse behavior, source-wrapper handling, release sidebar binary packaging, and Codex legacy root-only session migration.
v6.2.9 - Callback Visibility And Diagnostics Release
- Shows
callback_pendingfor delegated callback root jobs while the child chain is still running, then resolvesask getandwatchto the final message-bureau reply after continuation. - Marks
ask get,pend,watch, andpingas diagnostics-only across inherited ask skills, CLI help, memory-facing wording, and tests. - Stores oversized ask bodies, terminal replies, notices, and callback continuation text under
.ccb/ccbd/artifacts/text/with short previews and diagnostic bundle inclusion. - Hardens shutdown cleanup by tracking prepared and current control-plane pids during remote kill and best-effort stopping the backend after foreground tmux namespace exit.
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 -fcan 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 inheritedccb-configskill guidance to describe the active config layer. - Defers project tmux namespace destruction until after the stop-all response finalizer so
ccb kill/ccb kill -fcan 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-installccbandasksmoke 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.mdinto 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_sourceswhile 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.0frominstall.shandinstall.ps1when no TOML reader is available, withCCB_INSTALL_TOMLI=0skip support. - Installs
tomliinside 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_migrationinside 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-configskills 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 optionaluseful_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-configmemory-routing examples for direct callback handoffs and separate root work packages.
v6.2.0 - Callback Ask Chain Release
- Adds
ccb ask --callback <agent>so active agents can delegate work and receive the child result later as a continuation task. - Rejects accidental plain nested
askfrom active CCB tasks;--callbackis for required child results and--silenceis 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 -ffinalization 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/claudeand prefers that version for managed Claude startup. - Copies the active source-home Claude version into the CCB provider cache, then points managed
.local/bin/claudeat 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/andcommands/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_HOMEsupport with projected system~/.factory/skillsand 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
--compactand--silencesubmission 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_timeoutand 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.zipto 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.mdupdates to refresh memory without forcing a fresh conversation. - Includes PR #205 mailbox recovery for stale terminal
task_requestqueue 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.mdtemplates with the same fire-and-forget handoff guidance. - Makes managed Claude startup prefer ccswitch-updated
~/.claude/settings.jsonroute settings over stale caller-shellANTHROPIC_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
ccbdand keeper pids to exit during remoteccb killinstead of trusting lifecycle unmounted alone. - Finalizes lifecycle to stopped/unmounted before writing the final shutdown report, allowing
ccb cleanupto 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/Keychainsfallback 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/Keychainsinto managed Claude homes on macOS whencom.apple.security.plistis 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
.ccbgrowth by routing Codex projected assets through symlink/shared bundle paths and by moving/pruning rebuildable Claude and Gemini cache content. - Extends
ccb cleanupto reclaim old Claude shared versions, Gemini shared cache data, rebuildable Claude caches, and stale pane crash logs. - Hardens
ccb killso oldccbd/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.plistso 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.mdchanges. - 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.mdis the only shared CCB memory anchor.- Adds Claude macOS
Claude Code-credentialsKeychain lookup.
v6.1.5 - Tmux Startup Hotfix
- Fixes startup races that could show
Cannot split: pane ... does not existorrespawn pane failed: can't find pane. - Provider panes still use the managed respawn path.
v6.1.4 - Shared Project Memory V1
.ccb/ccb_memory.mdis the project-wide shared memory document.
v6.1.2 - Provider Storage Boundary Hardening
- Storage Classes Made Explicit:
ccb doctor storagenow separates authority, session state, secrets, workspaces, user content, projected config, rebuildable cache, and startup authority bundles. - Safe Cleanup Added:
ccb cleanuprefuses to run whileccbdor 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
askskill and remove older CCB helper skills such asping,pend,all-plan, andfile-op. - Global Memory Injection Removed: installers no longer append CCB collaboration blocks into global
CLAUDE.md, installedAGENTS.md, or.clinerules; existing CCB-marked blocks are cleaned during install. - Legacy Skill Sources Removed: repository skill templates now keep only the provider-specific
askskill assets.
v6.1.0 - CCBD Ask Stability and Observer Convergence
- Ask Submit Fastpath Stabilized:
ccb askreturns 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, andpendpaths prefer maintained summaries and explicitly degrade when summaries are missing or corrupt - Observer Surfaces Weakened:
pend,watch,queue, andinboxare non-authoritative snapshots; useccb trace <id>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/<drive>/..., project authority remains in.ccbwhileccbd/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
.ccbarchive 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
ccbstartup 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
ccbdping 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
.venvPython, avoiding environment drift when optional dependencies such aswatchdogare 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
askno 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_HOMEto 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, andGEMINI_ROOTcontract 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, orCCB_CALLER_*runtime authority to override agent-scoped managed state - Gemini Login Projection Extended: managed Gemini homes now project allowlisted
.gemini/.envAPI credentials,google_accounts.json, andGEMINI_CLI_HOMEwhile 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_IDcontamination - 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.jsoninside isolated Claude homes - Claude Account Metadata Refreshed: inherited
.claude.jsonaccount 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.configas a request to use the built-in default project config instead of exiting beforeccbdcan 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/*/homeas 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.jsonwhile 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
AfterAgenthooks that fire with an empty reply now downgrade toincompleteinstead of terminalizing as a false exact completion - Exact Hook Polling Becomes Safer: Gemini exact-hook polling now ignores
completedhook 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_URLend 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/urlshortcuts 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
cmdpane now directlyexecs the resolved user shell and preserves ordinary user-session transport variables such asDISPLAY,WAYLAND_DISPLAY,DBUS_SESSION_BUS_ADDRESS,XAUTHORITY, andSSH_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.tomlandauth.jsonas the sole authority for explicitkey/urlroutes, 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
ccbstartup 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.confignow accepts flat per-agentkey,url, andmodelshortcuts 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
ccbstart 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 -> killblackbox lifecycle stays covered - Contract Clarification: the startup supervision contract now explicitly defines project-socket
no server runningas 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.jsonforoauth-personalreuse, and remove stale copied credentials when auth inheritance is disabled - Shared Tmux Ready Budget: project-owned
respawn-panenow uses the same tmux ready-retry budget as namespace create/reflow, reducing transientno server runningfailures 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.jsonalongside 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 ccbdandping agentnow report current mounted state from live authority instead of stale failure residue after recovery - Shutdown Transaction Hardening:
ccb killandccb kill -fnow 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 -> restartlifecycle repro now converges cleanly toproject_shutdownwithout 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.codexprovider dotfiles - Kill Lifecycle Fix: interactive
ccbno longer reports a false attach failure afterccb killintentionally 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.codexprovider 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.1andv6.0.2installs 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 updatenow resolves the extracted release directory correctly instead of treating the.tar.gzasset name as a folder - Installer Handoff Restored: self-update now finds
install.shinside 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 asknow preserves the real originating agent so replies return to the right mailbox instead of being attributed asuser - 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.shnow 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, andccb kill -f
🧱 Project Rebuild Semantics:
- Config-Preserving Legacy Cleanup: On first
ccbinside a pre-6 project, CCB preserves.ccb/ccb.config, removes the rest of the old.ccbruntime state, and rebuilds locally - Runtime Marker: Modern projects now record
.ccb/project-runtime.jsonso 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 updateis available on Linux, macOS, and WSL for the 6.x line - Release-Only Upgrades: Source tags are still published with each version, but
ccb updatefor 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
mainbranch - Major Upgrade Confirmation: Upgrading into
6.0.0requires 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, andccb kill -f - Model Control Plane Still Available:
ask,ping,pend, andwatchremain for agent-to-agent orchestration without cluttering primary help
🧱 Workspace Semantics Made Explicit:
- Default Inplace Mode: Compact
ccb.configentries now expand toworkspace_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:
- History-Preserving Reset:
ccb -nrebuilds project runtime state while keeping.ccb/ccb.config, project memory, and same-name managed agent history - Stale Registration Cleanup: Start and reset now prune missing registered git worktrees before rematerialization
- Kill Warnings:
ccb killwarns 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-pingandccb-mountedgain--autostartflag 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_DONElines in degraded mode - req_id Regex:
opencode_comm.pynow matches both old hex and new timestamp-based formats - Gemini Idle Timeout: Auto-detect reply completion when Gemini omits
CCB_DONEmarker (15s idle, configurable viaCCB_GEMINI_IDLE_TIMEOUT) - Gemini Prompt Hardening: Stronger instructions to reduce
CCB_DONEomission 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 Guardrailrule toclaude-md-ccb.md— covers both/askskill and directBash(ask ...)calls - Marker Consistency:
bin/asknow 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_configis detected and upgraded to.ccbwhen 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-sessionnow recordsold_claude_session_id/old_claude_session_pathwithold_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-mounteduses ping-based detection across all platforms - State File Lookup:
askd_clientfalls back toCCB_RUN_DIRfor 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 -fnow cleans up orphaned tmux sessions globally (sessions whose parent process has exited) - Mounted Skill: Optimized to use
pgrepfor daemon detection (~4x faster), extracted to standaloneccb-mountedscript - Droid Skills: Added full skill set (cask/gask/lask/oask + ping/pend variants) to the provider skill assets
- 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_*pluscask/gask/lask/oaskaliases). - Setup: New
ccb droid setup-delegationcommand for MCP registration. - Installer: Auto-registers Droid delegation when
droidis 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; useccb ...or the defaultccb.config. - Flexible Mounting: More flexible pane mounting and session binding.
- Default Config: Uses a built-in default when
.ccb/ccb.configis 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
- 🔄 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
oaskto delegate sub-tasks to OpenCode models. - 🛑 Smart Interruption: Gemini tasks now support intelligent interruption detection, automatically handling stops and ensuring workflow continuity.
| 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
- Zombie Cleanup:
ccb kill -fcleans up orphaned tmux sessions globally - Mounted Skill: Optimized with
pgrep, extracted toccb-mountedscript - Droid Skills: Full skill set added to the provider skill assets
- Droid: Add delegation tools (
ccb_ask_*andcask/gask/lask/oask) plusccb droid setup-delegationfor MCP install
- OpenCode: 修复
-r恢复在多项目切换后失效的问题
- Daemons: 全新的稳定守护进程设计
- Skills: New
/all-planwith Superpowers brainstorming + availability gating; Codexlping/lpendadded;gaskkeeps brief summaries withCCB_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 reinstallwith Claude config cleanup. - Routing: Tighter project/session resolution (prefer
.ccbanchor; avoid cross-project Claude session mismatches).
- 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.configis 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
- 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-exitwas set - Tmux: More robust pane detection (prefer stable
$TMUX_PANEenv var) and better fallback when split targets disappear
- Performance: Added caching for tmux status bar (git branch & ccb status) to reduce system load
- Strict Tmux: Explicitly require
tmuxfor auto-launch; removed error-prone auto-attach logic - CLI: Added
--print-versionflag for fast version checks
- CLI Fix: Improved flag preservation (e.g.,
-a) when relaunchingccbin tmux - UX: Better error messages when running in non-interactive sessions
- Install: Force update skills to ensure latest versions are applied
- Async Guardrail:
cask/gask/oaskprints a post-submit guardrail reminder for Claude - Sync Mode: add
--syncto suppress guardrail prompts for Codex callers - Codex Skills: update
oask/gaskskills to wait silently with--sync
- Project_ID Simplification:
ccb_project_iduses current-directory.ccb/anchor (no ancestor traversal, no git dependency) - Codex Skills Stability: Codex
oask/gaskskills were adjusted to avoid sending the next task too early
- Codex Log Binding Refresh: the Codex runtime now periodically refreshes
.codex-sessionlog paths by parsingstart_cmdand scanning latest logs - Tmux Clipboard Enhancement: Added
xselsupport andupdate-environmentfor better clipboard integration across GUI/remote sessions
- 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
- Session Overrides:
cping/gping/oping/cpend/opendsupport--session-file/CCB_SESSION_FILEto bypass wrongcwd
- Gemini Reliability: Retry reading Gemini session JSON to avoid transient partial-write failures
- Claude Code Reliability:
gpendsupports--session-file/CCB_SESSION_FILEto bypass wrongcwd
- Fix: Auto-repair duplicate
[projects.\"...\"]entries in~/.codex/config.tomlbefore starting Codex
- Project Cleanliness: Store session files under
.ccb/(fallback to legacy root dotfiles) - Claude Code Reliability:
cask/gask/oasksupport--session-file/CCB_SESSION_FILEto bypass wrongcwd - Codex Config Safety: Write auto-approval settings into a CCB-marked block to avoid config conflicts
- 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
- Tokyo Night Theme: Switch tmux status bar and pane borders to Tokyo Night color palette
- 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)
- 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
oaskto drive OpenCode - Stability: Robust queue management and lock files
- Fix oask session tracking bug - follow new session when OpenCode creates one
- Plan mode enabled for autoflow projects regardless of
-aflag
- Per-directory lock: different working directories can run cask/gask/oask independently
- Add non-blocking lock for cask/gask/oask to prevent concurrent requests
- Unify oask with cask/gask logic (use _wait_for_complete_reply)
- Fix plan mode conflict with auto mode (--dangerously-skip-permissions)
- Fix oask returning stale reply when OpenCode still processing
- Auto-enable plan mode when autoflow is installed
- Simplify cping.md to match oping/gping style (~65% token reduction)
- Optimize skill files: extract common patterns to docs/async-ask-pattern.md (~60% token reduction)
- Fix race condition in gask/cask: pre-check for existing messages before wait loop




