CCB (Claude Codex Bridge) Documentation

The Install Update Stability Plan for CCB (Claude Codex Bridge) ensures that fresh installations and managed updates are stable across supported environments (Linux, macOS, and WSL).

Key objectives include:

• Ensuring the ccb entrypoint remains usable after updates.
• Implementing idempotency to avoid repeated installs of dependencies or Role Packs when no changes are detected.
• Handling legacy state (e.g., migrating ccb.archi to agentroles.archi) without user-facing errors.
• Providing localized prompts in Chinese and English.
• Managing provider-native update prompts by suppressing them inside CCB-managed panes and delegating version management to ccb update.

The CCB TUI Workbench is a terminal-based interface designed for Agentic Loop projects. It serves as a managed client of ccbd and the scripted workflow state machine.

Key Features:

• Layout: A split-pane view featuring the Frontdesk conversation on the left and a conditional workflow panel on the right.
• Workflow Visibility: The right panel displays the task queue, workflow state, clarifications, internal activity, verification, and collected results.
• Integration: It is designed to be the first visible tmux window (topology order zero) for opted-in projects.
• Persistence: Supports reconnection and state restoration without cancelling ongoing backend work.
• Interaction: Optimized for keyboard-first operation with mouse parity and support for narrow-terminal layouts.

The Windows WezTerm Native Plan explores the feasibility of implementing a Windows-native WezTerm backend for the Claude Codex Bridge (CCB) project. The goal is to allow CCB to operate on Windows using WezTerm without relying on tmux-based communication, while maintaining the core v7 project authority, supervision, configuration, and tool-window semantics.

This is currently a planning phase and not an implementation commitment. The proposed architecture involves creating a MuxBackend contract to abstract backend-specific details, allowing both TmuxBackend and WezTermBackend to coexist without leaking implementation details into provider runtimes.

CCB Mobile acts as a native remote controller for server-side CCB tmux projects. It is designed for use with real server-side projects rather than demo environments.

Key features include:

• Project Discovery: Connects to the server-wide mobile gateway to list mounted CCB projects.
• Agent Interaction: Renders agent transcripts and sends pane-native text input.
• Terminal Access: Opens terminal views for remote control.
• File Management: Supports image and document upload/download through the authenticated gateway.
• System Access: Provides notifications and local/Tailnet gateway access.

The Inter-Agent Communication Reliability plan tracks proposals and source slices for improving the reliability of message transport between agents in CCB. It focuses on ensuring stable communication paths, particularly regarding Codex FIFO readers, bounded non-blocking FIFO writes, and failure diagnosability.

Supported Platforms:

• Linux
• macOS
• WSL (Windows Subsystem for Linux)

Note: Native Windows transport is currently out of scope for this reliability plan.

The Mobile Tmux Control Plan outlines the design for a mobile and iPad remote-control surface for CCB. This surface connects to server-side CCB tmux workspaces while maintaining CCB's multi-project and multi-agent ownership model.

Key design principles:

• Agent-first and server-remote: The primary focus is readable control of CCB projects and named agents running on a server.
• Terminal as fallback: Raw terminal/tmux control is provided as an explicit control/debug fallback rather than the default project page.
• Managed Runtime: CCB treats tmux as a managed runtime detail where ccbd reconciles panes, windows, and provider runtime records.

The Managed Provider Completion Reliability plan tracks implementation slices for improving the reliability of managed pane-backed provider completions. It focuses on normalizing provider terminal evidence, ensuring prompt-delivery acceptance for pane-backed runtimes, and managing edge cases like empty replies, timeouts, and subagent session fencing.

Key areas of focus include:

• Terminalization: Converting provider-specific terminal evidence into normalized completion items.
• Prompt-Delivery: Ensuring prompt-delivery acceptance evidence is captured before completion tracking begins.
• Session Boundaries: Managing SessionBoundaryDetector empty boundary behavior.
• Subagent Fencing: Ensuring Codex native subagents that inherit a CCB_REQ_ID do not have their results incorrectly surfaced as the target agent's caller-visible reply.

The Managed Provider and Job Integrity plan coordinates correctness repairs across several CCB domains, including provider asset projection, native session resume, provider-turn binding, job execution diagnostics, cancellation, and active-job control.

Primary Invariant: CCB must not lose, misattribute, or silently overwrite provider or job state while attempting to improve continuity or diagnostics.

Key Scopes include:

• Safe Codex plugin marketplace/cache projection.
• Claude plugin marketplace and cache discovery in managed isolated homes.
• Kimi exact-session restart behavior.
• Claude queued-prompt activation and turn attribution.
• Inbound reply-routing instructions.
• Correlated execution phases and stuck-job evidence.
• Cancellation terminalization and callback continuation.
• Capability-gated follow-up delivery to active jobs.

The Config Designer UI Plan outlines a focused configuration experience for Claude Codex Bridge (CCB). The goal is to provide a cleaner ccb-config skill, an optional local browser editor for .ccb/ccb.config, and a native sidebar entry point.

Key principles:

• Single Source of Truth: Configuration authority remains in .ccb/ccb.config. The UI is a local editor and does not become a second source of truth or a tool for workflow-memory authoring.
• Hot Reloading: Hot reload functionality is delegated to the existing mounted-daemon control plane rather than being an independent runtime authority.
• Topology Authority: Topology authority is maintained in [windows], while [agents.<name>] sections are used strictly as overlays.

The agentroles.ccb_checker is a simplified RolePack designed for node-level checking. Its primary function is to review individual worker results to ensure quality and compliance.

Specifically, the checker validates that results do not contain:

• Missing evidence: Lack of supporting data for claims.
• Hidden fallback: Undisclosed use of fallback mechanisms.
• Degradation: Reductions in quality or performance.
• Scope shrinkage: Unintended narrowing of the task scope.

The Sidebar Provider Activity layer is designed to ensure accurate agent status reporting in the sidebar for manual pane work, CCB-managed jobs, provider failures, and interrupted turns.

Key Architectural Constraint: The sidebar operates strictly as a project_view client. While provider hooks, session logs, and runtime artifacts enrich the project_view, they do not serve as the primary authority for:

• Project identity
• Agent identity
• Pane ownership
• Job state
• Layout