claude_codex_bridge Agent工作流

How to Install

Install or update an npm-managed CCB with npm:

npm install -g @seemseam/ccb@latest

For GitHub release-package or source installs, use CCB's transactional updater:

ccb update

On an npm-managed install, ccb update prints the equivalent npm command and does not modify npm's vendored payload in place.

<details> <summary><b>Native Windows x64 beta</b></summary>

The Windows beta artifact is attached to the matching stable CCB GitHub release. Download ccb-windows-x86_64.zip and its .sha256 sidecar, verify the digest, extract the ZIP, then run:

.\install.ps1 install -Yes
ccb --print-version

It requires native Windows x64, Python 3.10+, WezTerm, Git Bash, and Herdr 0.8.0 or newer. The installer creates an install-local managed Python runtime. The binaries are unsigned, and ccb update remains diagnostic-only for this beta support tier; install a later Windows build by rerunning its validated install.ps1.

</details>

CCB-managed provider panes suppress known provider-native startup update prompts. After updating CCB—or immediately when CCB is already current—ccb update checks installed provider CLIs and offers supported updates once. Use --providers check, --providers all, or --providers none for explicit report-only, non-interactive update, or skip behavior. Declining prompts again on the next ccb update; skipping a version hides only that exact version. CCB never restarts active provider panes during this flow, so an accepted provider update applies when that pane next starts or is explicitly restarted.

After a release change, the newly installed CCB also retires old project-scoped Claude/Gemini caches. Manifest-valid caches for deleted projects are removed immediately. A stopped current project is cleaned immediately; active or other existing projects are preserved and cleaned after their next successful ccb kill. Unknown providers, malformed manifests, foreign symlinks, sessions/auth, and the user-scoped Gemini cache are never removed by this migration. Use ccb update --no-cache-cleanup to skip it for one update.

To roll back, use the same transactional updater with an older released version, for example ccb update 8.1.3. CCB rejects a same-version artifact whose build identity differs from the installed build, and restores the prior local prefix if the update transaction fails. If restoration itself cannot complete, CCB retains and reports the external recovery backup path.

<details> <summary><b>GitHub release package and source install fallbacks</b></summary>

If npm is not convenient in your environment, download the matching package from Releases, unpack it, and install:

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

Source install is intended only for development or temporary fallback:

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

Source install links global ccb / ask back to the checkout. Regular users should prefer the npm package.

</details>

<a id="quick-start"></a>

Quick Start

2. Configure The Workspace

A blank project starts light: CCB opens one main window with a single agent named demo, selecting the first supported CLI available on the machine (Codex, Claude, Gemini, then other providers). It no longer mounts a multi-agent team by default.

Click the ⚙ Settings icon at the top-left of the CCB sidebar to open the local configuration control panel. You can also run ccb config ui from the project directory.

Persistent local Config UI access

The Config UI always binds to loopback. To use a stable local port and token, configure a token source in .ccb/ccb.config; never put a literal token in that file:

```toml [config_ui] port = 43123 token_env = "CCB_CONFIG_UI_TOKEN"

Or use this instead of token_env:

token_file = ".ccb/config-ui.token"

`--port` remains a one-run override. `token_file` must be project-relative, non-symlinked, and owner-only (`chmod 600 .ccb/config-ui.token` on POSIX). Without a token source, CCB keeps the existing random token and ephemeral-port behavior. The CLI prints only the loopback URL and token source, never the token value.

<p align="center">
  <img src="assets/readme_v7/config-control-panel.png" alt="CCB configuration control panel editing the default demo agent" width="960">
</p>

The panel edits windows, pane splits, providers, models, thinking levels, API overrides, workspaces, Rich mode, and sidebar settings. It validates changes before saving and supports reload dry-runs and guarded hot reload. Saving creates `.ccb/ccb.config` and pins the selected provider and topology for this project.

For an advanced multi-agent topology, edit it visually or create `.ccb/ccb.config` manually. In v2 `[windows]`, `,` and `;` control vertical stacking and horizontal splits inside each window, so `A,B;C,D` is close to a four-pane layout.

[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 agents_height = "50%" comms_height = "15%" tips_height = "35%" comms_limit = 3

Validate the config and start the workspace:

Config And Shared Memory

Use the ⚙ Settings control panel for normal project configuration. If you want agent-assisted configuration and runtime diagnosis, ccb_self remains available as an optional Role Pack and can be added with ccb roles add agentroles.ccb_self:codex.

Supported managed Agents receive the built-in ask, ccb-clear, ccb-compact, and ccb-diagnose control skills even when optional skill inheritance is disabled. Use $ccb_diagnose <agentname> to inspect one Agent's authoritative runtime/job state and live pane evidence, apply bounded recovery when safe, and review a redacted issue draft before explicitly authorizing GitHub submission. Managed Codex also keeps reconnect.

.ccb/ccb_memory.md is the project-wide shared memory document. Use it for team collaboration rules, project constraints, long-lived context, and agent handoff conventions. Stable cross-agent information belongs there instead of being copied into several provider-private memory files.

<a id="contact"></a>