https://github.com/seemseam/claude_codex_bridge

Visible multi-agent CLI teams for Claude, Codex, Gemini, OpenCode, and Droid with project memory and tmux supervision
https://github.com/seemseam/claude_codex_bridge

ai-collaboration ai-tools claude-code cli codex cross-platform droid gemini llm multi-agent-cli multi-agent-systems opencode python terminal

Last synced: about 6 hours ago
JSON representation

Visible multi-agent CLI teams for Claude, Codex, Gemini, OpenCode, and Droid with project memory and tmux supervision

Host: GitHub
URL: https://github.com/seemseam/claude_codex_bridge
Owner: SeemSeam
License: other
Created: 2025-10-25T13:23:08.000Z (8 months ago)
Default Branch: main
Last Pushed: 2026-05-18T04:19:53.000Z (29 days ago)
Last Synced: 2026-05-18T04:42:03.466Z (29 days ago)
Topics: ai-collaboration, ai-tools, claude-code, cli, codex, cross-platform, droid, gemini, llm, multi-agent-cli, multi-agent-systems, opencode, python, terminal
Language: Python
Homepage:
Size: 21.7 MB
Stars: 2,690
Watchers: 8
Forks: 263
Open Issues: 68
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE

Awesome Lists containing this project

README

# CCB

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

**English** | [中文](README_zh.md)

[Quick Start](#quick-start) · [v7 UI](#v7-ui-tour) · [Configure Agents](#configure-your-agent-team) · [User Guide](docs/manuals/user-guide/) · [Developer Guide](docs/manuals/developer-guide/)

CCB v7 visible multi-agent CLI workspace

---

## Supported CLIs

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

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

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

## Why CCB?

## Quick Start

### 1. Install or update

New installs should use the npm package:

```bash
npm install -g @seemseam/ccb
```

After CCB is installed, use CCB's updater:

```bash
ccb update
```

Install or refresh the optional rich media workbench; it bundles verified binaries where possible and installs only the required terminal/media/font dependencies through the platform package manager:

```bash
ccb update rich
```

After rich is enabled, plain `ccb` opens the rich WezTerm launcher when needed; use `ccb uninstall rich` to return to the normal terminal startup.

GitHub release package and source install fallbacks

If npm is not available in your environment, download the matching package from [Releases](https://github.com/SeemSeam/claude_codex_bridge/releases):

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

Source install is for development or temporary fallback use:

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

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

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

```bash
mkdir -p .ccb
```

### 2. Create project config

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

```toml
version = 2
entry_window = "main"

[windows]
main = "main:codex"
work = "worker1:codex(worktree), worker2:claude(worktree)"
review = "reviewer:claude, qa:gemini"

[ui.sidebar]
mode = "every_window"
width = "15%"
bottom_height = 20

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

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

Validate the config:

```bash
ccb config validate
```

Start the workspace:

```bash
ccb
```

### 3. Collaborate

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

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

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

### v7 UI Tour

### Rich Mode (NEW!)

Run `ccb update rich` to install the optional rich workbench; it bundles Yazi where possible, uses WezTerm for the rich terminal surface, and gives Markdown rendering plus image/PDF/video previews. After installation, plain `ccb` automatically opens this rich launcher outside WezTerm; `ccb rich` remains available as an explicit launcher.

CCB rich workbench with Yazi PDF preview in WezTerm

### Contact

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

---

## More Reading

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

### What Is CCB?

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

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

### Why Multi Agents

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

Why one agent starts to struggle

- Mixed roles reduce context focus: one conversation tries to architect, edit, test, and review itself.
- Complex task execution has a ceiling: long work needs split points, handoffs, checks, and rollback boundaries.
- Cost pressure is higher: if every step needs the strongest model, even simple sub-tasks become expensive.
- Tool and skill management becomes harder: a "does everything" agent also accumulates too much authority and instruction load.
- Serial waiting is inefficient: when one agent is reading logs or running tests, other independent work cannot naturally continue.

### Which Multi-Agent Approach Should You Use?

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

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

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

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

CCB also supports complex workflows, but it is not an automatic DAG generator. You design complexity explicitly through `.ccb/ccb.config`, windows, role memory, worktrees, model/API settings, and ask/callback routes.

### Daily Operation

### tmux Basics

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

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

Copy and paste tips:

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

More common tmux operations

New users should avoid pane/window killing shortcuts at first. To stop a CCB project, prefer CCB's project-level shutdown command instead of killing one recoverable pane by accident.

### Configure Your Agent Team

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

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

Higher layers replace lower layers as a whole; they are not merged. The project authority file is `.ccb/ccb.config`. The old `.ccb_config/ccb.config` path is legacy migration evidence only.
The built-in default is a v2 `[windows]` config with `agent1`, `agent2`, `agent3`, and `ccb_self`. The optional rich workbench can be installed with `ccb update rich`; once enabled, normal `ccb` startup uses the rich launcher unless you run `ccb uninstall rich`. The default `ccb_self` agent uses `codex` and is bound to `agentroles.ccb_self`.

`.ccb/ccb.config` mainly controls:

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

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

#### Role Packs

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

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

```bash
ccb roles update agentroles.ccb_self
ccb roles update agentroles.archi
```

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

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

```bash
ccb roles add agentroles.ccb_self:codex
ccb reload
```

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

```bash
ccb roles add agentroles.archi:codex
ccb reload
```

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

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

#### Single-window compact config

```text
cmd; main:codex, worker1:codex(worktree); reviewer:claude
```

Meaning:

- `cmd` is a shell pane, not an agent.
- `main`, `worker1`, and `reviewer` are agent names.
- `codex` and `claude` are providers.
- `;` splits left-to-right; `,` stacks top-to-bottom.
- `(worktree)` means that agent uses an isolated git worktree.

#### Multi-window topology

When you want planning, implementation, review, and research in different tmux windows, use `version = 2` and `[windows]`:

```toml
version = 2
entry_window = "main"

[windows]
main = "main:codex"
work = "worker1:codex(worktree), worker2:claude(worktree)"
review = "reviewer:claude, qa:gemini"

[ui.sidebar]
mode = "every_window"
width = "15%"
bottom_height = 20

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

Note: `cmd` belongs to compact/hybrid single-window layouts. Do not put `cmd` inside `[windows]`.

#### Rich workbench tool window

Tool windows are tmux windows managed by CCB, but they are not agents. They do not appear in `ccb ask` targets and do not create provider runtime records.

```toml
version = 2
entry_window = "main"

[windows]
main = "main:codex"

[tool_windows.rich]
command = "CCB_WORKBENCH_PROFILE=rich CCB_WORKBENCH_FORCE_RICH=1 ccb-workbench files"
label = "rich"
```

`ccb update rich` prepares the optional workbench bundle under CCB-owned XDG paths, downloads and validates bundled binaries where available, and uses the platform package manager only for required rich dependencies such as WezTerm, Markdown/PDF/image/video helpers, and recommended fonts. Under WSL, CCB can launch Windows-native `wezterm.exe` while running the rich tools inside the current Linux distro. Normal `ccb update` keeps this bundle untouched; rerun `ccb update rich` to install, repair, or refresh it. Run `ccb uninstall rich` to remove the bundle and return plain `ccb` to normal terminal startup. Set `CCB_RICH_DOWNLOAD_BINARIES=0` to skip bundled binary downloads, or `CCB_RICH_INSTALL_DEPS=0` to skip system package installation.

#### Per-agent model, API key, or base URL

Use compact format when layout is enough. If some agents need separate models or API routes, keep the compact header and add TOML overlays:

```toml
cmd; fast:codex, deep:codex; reviewer:claude

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

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

[agents.reviewer]
model = "sonnet"
```

Do not commit real API keys to a public repository. `key` / `url` are agent-local shortcuts; advanced provider environment variables belong in provider profile or agent env fields.

### Use ccb_self For CCB Config

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

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

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

Example:

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

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

ccb-config write flow and boundaries

1. Describe the project and team goal in natural language.
2. `ccb_self`'s built-in `ccb-config` reads the current config authority and decides whether this is a new config, an edit, or a migration.
3. It proposes one complete config before writing.
4. You confirm the proposal, then it edits only `.ccb/ccb.config`.
5. It validates the config and tells you to use `ccb reload --dry-run` / `ccb reload` when the change can be applied dynamically.

By default, `ccb-config` does not edit `.ccb/ccb_memory.md` or `.ccb/agents//memory.md`. It should touch those memory files only when you explicitly ask `ccb_self` for workflow memory or role memory design.

### Agent Collaboration

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

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

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

Why callback matters

If agent A is handling a user-originated CCB task and needs agent B's result to finish, A should use callback. CCB records the parent/child relationship, lets A's current turn end, and later delivers B's result back to A as a continuation. That avoids polling, queue blocking, and wasted context.

### Install And Update

#### Requirements

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

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

#### npm first

For first install, prefer npm:

```bash
npm install -g @seemseam/ccb
```

For later updates:

```bash
ccb update
```

[GitHub Releases](https://github.com/SeemSeam/claude_codex_bridge/releases) remain available for environments where npm is unavailable. Source checkout install is for development, fix validation, or temporary fallback.

#### Uninstall

```bash
ccb uninstall
ccb reinstall

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

### FAQ

The expected agents did not appear

Run `ccb config validate` and check that `config_source_kind` is the layer you expected. Project config `.ccb/ccb.config` has highest priority; if it is missing, CCB uses `~/.ccb/ccb.config` or the built-in default.

Copy/paste is awkward

First try mouse-drag copy and `Ctrl+Shift+V` / `Cmd+V` paste. If tmux captures the drag, use function key `[` after `` to enter copy / scroll mode. If you only want native terminal selection, many terminals support `Shift + mouse drag`.

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

Ask `ccb_self` to use its built-in `ccb-config` and describe your target window groups, such as main/work/review. Migration should preserve old agent names, providers, worktree markers, model/key/url fields, and write `[windows]` only after confirmation.

The sidebar helper is unavailable

Prefer a release package because it carries or handles the sidebar helper. Source installs may need a local Rust toolchain if no compatible prebuilt helper is available.

### Community And Credits

Thanks to the [Linux.do community](https://linux.do) for testing, feedback, and discussion.

Thanks to [tmux-agent-sidebar](https://github.com/hiroppy/tmux-agent-sidebar) for the sidebar ideas and inspiration.

### Release Notes

v7 highlights:

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

v7.6.4 - macOS Release Install Smoke

- Keeps the 7.6.3 macOS temporary-root hardening and updates the CI release
install smoke to use the explicit temporary-bin override for its isolated
sibling `CODEX_BIN_DIR`.
- Leaves user-facing installer safety intact while allowing the release
workflow to validate macOS package installation from a temporary smoke root.
- Keeps the v7.6.2 rich workbench and tmux single-status-row fixes intact for
user install testing.

v7.6.3 - macOS CI Green Patch

- Fixes macOS temporary-root detection for install guards by recognizing the
resolved `${TMPDIR:-/tmp}` parent used by GitHub Actions runners.
- Aligns doctor temporary implementation detection with macOS `/tmp` symlink
behavior, preventing false red CI on `/private/tmp` and
`/private/var/folders/...` paths.
- Keeps the v7.6.2 rich workbench and tmux single-status-row fixes intact for
user install testing.

v7.6.2 - Rich Workbench Hotfix

- Allows `rich` in `.ccb/ccb.config` as a tool/layout alias without requiring
a provider runtime; it materializes as a managed tool pane/window and is not
an `ask` target.
- After `ccb update rich` enables the bundle, plain `ccb` can use the rich
launcher outside an existing rich/WezTerm session while avoiding recursive
WezTerm launches.
- Adds `ccb uninstall rich`, `ccb rich uninstall`, and `ccb rich disable` for
returning to normal CCB startup without changing full `ccb uninstall`
behavior.
- Rich updates clean only CCB-owned legacy editor roots and links, leaving
user-owned editor installs and personal config untouched.

v7.6.1 - Rich Workbench Binary Packaging

- `ccb update rich` now bundles verified Yazi/ya binaries where possible before
falling back to package managers.
- Linux rich installs prefer official Yazi musl builds before GNU builds to
avoid newer glibc requirements on older stable distributions.
- Downloaded Yazi binaries must pass `--version` validation before activation,
and invalid managed binaries are removed so fallback paths remain available.
- Under WSL, rich launchers can use Windows-native `wezterm.exe` while keeping
CCB, Yazi, and preview helpers inside the current Linux distro.

v7.6.0 - Rich Workbench Lifecycle

- Makes rich workbench an explicit optional bundle installed with
`ccb update rich`.
- Keeps ordinary `install.sh install` and `ccb update` focused on CCB itself;
they no longer auto-provision standalone Neovim.
- Public `ccb tools ... neovim` routes now refuse standalone provisioning and
point users to `ccb update rich`; `ccb rich` launches only an installed and
enabled rich bundle.
- Restores the CCB tmux status bar to one line by removing the old second-line
copy hint.

v7.5.3 - Kimi Runtime Reliability And Hindsight Compatibility

- Adds Kimi runtime hardening without changing other provider execution paths:
Kimi can fall back to stable pane evidence for K2.7 Code when the native turn
log does not expose a completed reply in time.
- Makes Kimi Hindsight memory opt-in at the CCB execution boundary. It activates
only when `.hindsight/kimi.json`, `.hindsight/codex.json`,
`HINDSIGHT_API_URL`, or `HINDSIGHT_BANK_ID` is configured, and failures remain
non-blocking provider diagnostics.
- Accepts both `HINDSIGHT_API_KEY` and `HINDSIGHT_API_TOKEN` for the Kimi
bridge and the `scripts/hindsight` helper.
- Documents the supported provider surface more clearly in the README while
keeping unrelated provider behavior unchanged.

v7.5.2 - Native CLI Provider Wave

- Adds built-in optional provider ids for Qwen Code (`qwen`), Cursor Agent
(`cursor`), GitHub Copilot CLI (`copilot`), Crush (`crush`), Kiro CLI
(`kiro`), and Pi (`pi`).
- Uses native per-job CLI execution and provider-owned completion signals:
stream-json / JSON result events for Qwen, Cursor, Copilot, and Pi; process
exit plus stdout for Crush and Kiro. These adapters do not require
model-printed `CCB_DONE`; Pi terminalizes on native `turn_end`.
- Adds `QWEN_START_CMD`, `CURSOR_START_CMD`, `COPILOT_START_CMD`,
`CRUSH_START_CMD`, `KIRO_START_CMD`, and `PI_START_CMD` command overrides plus provider
session bindings, runtime launchers, deterministic stubs, and focused
execution tests.

v7.5.1 - MiMo Provider Release Surface

- Adds MiMo Code to the public README provider strip with a Xiaomi-branded
MiMo badge and updates the top-level positioning to eight CLI families.
- Publishes the committed MiMo native provider integration in the 7.5 line:
managed `mimo` panes, `MIMO_START_CMD`, generated MiMo instructions, and
`mimo run --pure --format json` completion parsing.
- Synchronizes npm package metadata and release workflow defaults with the
new patch release.

v7.5.0 - Native CLI Providers And Homepage Sync

- Adds managed native CLI provider support for Kimi plus broader native CLI
runtime groundwork, including runtime specs, session bindings, command
overrides, and cleanup coverage.
- Moves Kimi and Antigravity completion detection toward provider-owned
session or transcript evidence instead of requiring model-printed `CCB_DONE`.
- Uses Kimi's current `--auto-approve` flag for CCB auto-permission while
recognizing legacy/alias flags such as `--auto`, `--yes`, `-y`, and `--yolo`.
- Synchronizes the English and Chinese README homepages with refreshed hero
assets and the seven public CLI-family positioning.

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

- Completes Claude pane-backed asks promptly when a primary assistant response
emits `stop_reason=end_turn` with an observed request anchor and non-empty
reply, avoiding the previous 900-second timeout path.
- Treats empty session-boundary terminal events with no prior assistant reply
as `incomplete/task_complete_empty_reply` with empty-provider diagnostics.
- Restores the `@seemseam/ccb` npm release surface with package metadata, CLI
runner wrappers, and tag-triggered Trusted Publishing after GitHub release
assets are available.
- Refreshes the v7 README homepage around canonical hero assets, npm-first
install, and clearer `ccb_self` guidance.

v7.4.3 - PR #225 Reliability Follow-Up

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

v7.4.2 - Self-Supervision And Empty Reply Guards

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

v7.4.1 - Maintenance Heartbeat And ccb_self Defaults

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

v7.4.0 - ccb_self Maintenance Role

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

v7.3.8 - AGY Adapter And Project Tmux History

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

v7.3.7 - Ask Parameter Policy And Skill Guidance

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

v7.3.6 - Provider Memory Ownership Cleanup

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

v7.3.5 - Tmux Border Hook Hotfix

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

v7.3.4 - Withdrawn Prerelease

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

v7.3.3 - Withdrawn Draft

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

v7.3.2 - First-Install Role Pack Provisioning Hotfix

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

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

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

v7.3.0 - Superseded Prerelease

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

v7.2.12 - Agent Roles Store Migration Release

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

v7.2.11 - Superseded Agent Roles Opt-In Preview

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

v7.2.10 - Role Pack Post-Update Hotfix

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

v7.2.9 - Agent Roles Catalog Release

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

v7.2.8 - Superseded Role Fixture Hotfix

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

v7.2.7 - Superseded WSL Mounted Smoke Hotfix

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

v7.2.6 - Superseded Official Smoke Root Hotfix

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

v7.2.5 - Superseded Source Runtime Guard Hotfix

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

v7.2.4 - Superseded Agent Roles Catalog Release

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

v7.2.3 - Root Install Support Validation Hotfix

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

v7.2.2 - Root Install Confirmation Release

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

v7.2.1 - Antigravity Runtime Follow-Up

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

v7.2.0 - Role Packs And Managed Tools Release

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

v7.1.1 - Sidebar View Height Release

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

v7.1.0 - Dynamic Reload Release

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

v7.0.11 - Provider Activity And Sidebar Focus Release

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

v7.0.10 - Sidebar Tips And Tmux Controls Release

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

v7.0.9 - README v7 Redesign Release

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

See [CHANGELOG.md](CHANGELOG.md) for the full history.

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/seemseam/claude_codex_bridge

Awesome Lists containing this project

README