claude_codex_bridge Agent工作流

1. Install or update

New installs should use the npm package:

npm install -g @seemseam/ccb

After CCB is installed, use CCB's updater:

ccb update

Install or refresh the optional mobile controller setup:

ccb update mobile

This command checks the local mobile gateway prerequisites, guides Tailscale login/Serve setup when needed, keeps the gateway loopback-only, and prints the current Android APK download link plus pairing steps.

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:

ccb update rich

After rich is enabled, plain ccb opens the rich WezTerm launcher unless it is already running inside a CCB-managed rich WezTerm; use ccb uninstall rich to return to the normal terminal startup.

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

If npm is not available in your environment, download the matching package from Releases:

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

Source install is for development or temporary fallback use:

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.

</details>

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:

mkdir -p .ccb

<a id="create-project-config"></a>

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, Z.ai CLI, 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:

npm install -g @seemseam/ccb

For later updates:

ccb update

GitHub 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

Quick Start

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.

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

ccb config validate

Start the workspace:

ccb

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 through the Agent Roles Spec. The spec is a host-neutral package format for specialist agents: a Role carries a stable identity, responsibilities, non-goals, memory, skills, prompts, references, tools, plugin content, validation notes, and host adapter metadata as one reviewable unit.

The practical value is separation. Role source stays portable and versioned; project bindings decide where that Role is mounted; runtime provider state, credentials, task progress, and generated projection output stay outside the Role. That makes specialist agents easier to install, update, audit, migrate, and remove without copying long prompts into every project or mutating user global configuration.

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:

ccb roles list
ccb roles show agentroles.archi
ccb roles install agentroles.archi
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:

ccb roles add agentroles.ccb_self:codex
ccb reload

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

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.

<details> <summary><b>Config format examples: single window, multi-window, per-agent model/API</b></summary>

Single-window compact config

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

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

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:

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.

</details>

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:

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.

<details> <summary><b>ccb-config write flow and boundaries</b></summary>

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/<agent>/memory.md. It should touch those memory files only when you explicitly ask ccb_self for workflow memory or role memory design.

</details>

</details>

<details> <summary><b>Collaboration and maintenance</b></summary>

Fallback from the package or source directory:

./install.sh uninstall ```

FAQ

<details> <summary><b>The expected agents did not appear</b></summary>

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.

</details>

<details> <summary><b>Copy/paste is awkward</b></summary>

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

</details>

<details> <summary><b>I want to migrate an old compact config to multi-window</b></summary>

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.

</details>

<details> <summary><b>The sidebar helper is unavailable</b></summary>

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.

</details>