CCB: Running Codex, Claude and Gemini Side by Side in One Terminal Workspace

The problem CCB solves: agents that cannot see each other

Running Codex in one terminal tab and Claude in another is easy. Getting the second one to act on what the first one produced is not. You copy output between panes, lose the reasoning trail, and end up as the message bus. CCB (the repository is SeemSeam/claude_codex_bridge, the installed command is ccb) targets exactly that gap. Its README frames the goal as "stable inter-agent communication for complex collaboration graphs such as `A -> B -> C`, `A,B -> C`, and `A -> B,C`." That is a fan-out and fan-in problem, not a chat problem.

The audience is narrow and specific. You need at least two provider CLIs already installed and authenticated on the machine, a terminal you are willing to keep open, and a project where you want a second opinion inside the same working directory rather than in a separate review step. The package.json lists linux and darwin under os, with x64 and arm64 CPUs, so the npm path is a Unix path. The README badges add WSL and a Windows beta tier, and the Windows artifact is described as unsigned.

CCB does not host models and does not proxy requests to provider APIs. It orchestrates the CLIs you already have. That distinction matters for cost: your existing subscriptions or API keys keep doing the billing, and CCB adds no inference layer of its own.

How the collaboration layer actually works

The README is explicit about one architectural choice: interactive CLI agents are presented as "full native terminals with visible layout control and direct takeover." CCB is not wrapping provider APIs in a normalized message format and rendering a summary. It is running the real terminal programs inside panes and giving you a layout you can watch and interrupt. The trade-off is honest but real: what you get depends on what each provider CLI does in a terminal, and anything a provider only exposes over an API is out of reach.

A background daemon holds project state. The README states that it "keeps project state alive even when the foreground UI is closed," which is why you can close the TUI and come back to a running collaboration rather than a fresh session. It also means a project has a lifecycle outside your terminal window, and the cleanup rules described later in the README only make sense because of that.

There is a hub mode for running multiple CLI providers concurrently from one command, and a mobile remote controller that the README describes as offering cross-provider voice control, file transfer and remote terminal access. The mobile side lives in a mobile/ directory at the repository root, so it is part of the same tree rather than a separate product. Configuration is project-scoped: the README tells you to run ccb from your working directory and notes that if startup reports that .ccb cannot be created automatically, you create it with mkdir -p .ccb.

Install and first run with npm

The documented install path is npm. The package is published as @seemseam/ccb, requires Node 18 or newer, and ships a postinstall script that runs bin/ccb-npm-install.js.

npm install -g @seemseam/ccb@latest

After that, ccb is on your PATH (the package also exposes ask, autonew and ctx-transfer as bin entries). To update, the README points at CCB's own transactional updater:

ccb update

On an npm-managed install, the README says ccb update prints the equivalent npm command rather than modifying npm's vendored payload in place. That is a deliberate split, and it means the update path you use depends on how you installed.

For a first session, run the command from the directory you want the agents to work in:

ccb

If startup complains that .ccb cannot be created or that the project anchor is missing, the README gives the fallback directly:

mkdir -p .ccb

Then configure the workspace so CCB knows which providers to start. The README's Configure Agents section is where that happens; it is not reproduced here, and the repository keeps the fuller walkthrough under docs/manuals/user-guide/.

Release packages, source installs and the rollback story

If npm is not workable, the README documents a release tarball fallback: download the matching package from Releases, unpack it, and run the installer.

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

A source install is described as intended only for development or temporary fallback, and it links global ccb and ask back to the checkout. The README states plainly that regular users should prefer the npm package. Take that at face value: a checkout-linked install means your global command changes whenever the working tree changes.

Rollback is documented, which is unusual for a project this young. The README says to use the same transactional updater with an older released version, for example ccb update 8.1.3. It also states that 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 an external recovery backup path. That last sentence is the interesting one: it admits a failure mode where the updater cannot put things back, and responds by telling you where the pieces are rather than pretending the transaction is atomic.

The Windows beta is a separate tier. The README describes downloading ccb-windows-x86_64.zip plus its .sha256 sidecar, verifying the digest, extracting, then running install.ps1 install -Yes followed by ccb --print-version. It requires native Windows x64, Python 3.10+, WezTerm, Git Bash, and Herdr 0.8.0 or newer. Two constraints stand out: the binaries are unsigned, and ccb update is diagnostic-only on that tier, so you install a later Windows build by rerunning the validated install.ps1.

Where CCB is the wrong tool

If you want to call an agent from a script, CCB is the wrong layer. Every architectural decision in the README points at interactive terminals: native panes, visible layout, direct takeover, a TUI. There is no documented programmatic interface for driving a collaboration from your own code, and the ask and ctx-transfer binaries are CLI entry points, not a documented API surface. For batch pipelines, a provider SDK is the shorter path.

The second mismatch is environment. CCB assumes provider CLIs exist and are authenticated outside it. It orchestrates; it does not supply credentials or models. If your team's policy is that agents run in a sandbox without interactive terminals, or if you cannot install tmux and the provider binaries, the whole design is unavailable to you.

The third is the Windows beta tier, and this is a documentation problem as much as a support problem. Unsigned binaries plus a diagnostic-only updater means every upgrade is a manual download, digest check and installer run. The README is clear about it, but a team that expects ccb update to just work will be surprised. And note the licence: package.json declares AGPL-3.0-only, while the repository metadata reports NOASSERTION. Those two disagree, and the README does not reconcile them. If you plan to redistribute anything built on CCB, resolve that discrepancy before you build on it, and get your own legal read rather than relying on either field.

How CCB differs from wiring an MCP server into one agent

The common alternative is to keep one host agent and give it tools through MCP, so a single Claude Code or Codex session calls out to other models as tools. That approach has one orchestrator and one conversation history; the other models are functions. CCB inverts it. Each provider gets a real terminal pane, and the collaboration is between peers with a visible layout, which is why the README talks about takeover and about graphs like A,B -> C rather than about tool calls.

The practical difference shows up in debugging. With an MCP tool call, you inspect one transcript and the tool result. With CCB, you watch the panes. You can see a provider stall, type into it, and restart it. You also inherit every quirk of that provider's terminal UI, including startup prompts, which is why the README notes that CCB-managed panes suppress known provider-native startup update prompts.

There is a cost dimension too. An MCP bridge typically sends a request to a model API and bills per token. CCB drives the CLI you already installed, so it rides whatever plan or key that CLI uses. Neither approach is cheaper in the abstract; they bill against different things.

Maintenance, upgrades and cache cleanup

The repository is not archived and the last push was on 2026-09-19, with v8.6.19 released the same day and v8.6.18 and v8.6.17 earlier that month. That is a fast release cadence, and it is the main ongoing cost: three patch releases in the week before this was written. Frequent small releases usually mean frequent small behaviour changes, so pin a version you have validated rather than tracking @latest blindly.

Provider updates are handled inside ccb update. The README says it checks installed provider CLIs and offers supported updates once, with --providers check for report-only, --providers all for non-interactive updates, and --providers none to skip. Declining prompts again hides them until the next ccb update, and skipping a version hides only that exact version. CCB never restarts active provider panes during this flow, so an accepted update applies when that pane next starts or is explicitly restarted. That is a sensible boundary, and it also means an update you accepted may not be live in a long-running pane.

There is also a migration step on release changes. The README states that a newly installed CCB retires old project-scoped Claude and Gemini caches: manifest-valid caches for deleted projects are removed immediately, a stopped current project is cleaned immediately, and active or other existing projects are preserved and cleaned after their next successful ccb kill. Unknown providers, malformed manifests, foreign symlinks, sessions and auth, and the user-scoped Gemini cache are never removed. You can skip the whole thing for one update with ccb update --no-cache-cleanup. If you keep long-lived project directories, know that cleanup is tied to ccb kill, not to the upgrade itself.

Editorial conclusion

Adopt CCB if you already run two or more provider CLIs interactively and want them in one visible workspace with handoffs between them, and if AGPL-3.0-only licensing is acceptable for how you ship. Do not adopt it if you want a programmatic agent API, if you cannot install tmux and a provider CLI per agent, or if you need signed Windows binaries today. Verify first that your provider CLIs are installed and authenticated outside CCB, that your project directory allows a .ccb folder to be created, and that your install path is npm-managed so that ccb update behaves as documented rather than diagnostic-only.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. SeemSeam/claude_codex_bridge on GitHub