Skip to content

🌉 bridge_CC-Codex — Claude Code ↔ Codex

bridge_CC-Codex lets Claude Code and OpenAI Codex hand one another bounded implementation, advice, and review requests. Its normalized plugin identifier is bridge. It is one repository with two independently installable host integrations: the Claude Code half calls the codex CLI, and the Codex half calls Claude through the bridge's host-launched MCP server.

The bridge is useful with either host integration installed and has no dependency on another plugin from this repository. Existing-plugin replacement and consumer migration are deliberately outside this standalone package.

Contributing or want internals? See Development and release verification and Security and privacy.

Release: 0.12.4. Claude- and Codex-side setup skills provide an approval-bound lifecycle for safe configuration and repair while retaining full caller-input, workspace/session authority, recursion, asynchronous lifecycle, envelope/transcript, and approval boundaries.

🚀 After installation

  1. Run $bridge:setup in Codex to configure Claude provider consent once.
  2. To approve that consent without typing the confirmation in the setup flow, run bin/bridge_consent.py issue-token in your own terminal and pass the printed one-time token: $bridge:setup --approve-claude-consent --consent-token <token>.

Consent details:

  • The token is valid 5 minutes and consumed by one grant. grant --approve run from a script without a terminal needs it as BRIDGE_OPERATOR_TOKEN and otherwise exits 2 without writing. Plain setup retains operator-terminal confirmation.
  • The approval covers task-relevant private code Claude reads in confirmed projects and ordinary inference, with explicit exclusions; installation alone grants nothing. Later calls check and reuse the grant without per-file prompts.
  • The operator can revoke it with bridge_consent.py revoke.
  • Stored user policy does not prove the active host loaded it: a fresh session may be needed, and project/managed restrictions remain authoritative.
  • Python 3.10 needs an existing tomli for this optional policy stage.
  • Codex setup helper recipes use the quoted packaged Python launcher (bin/python, or bin/python.cmd on native Windows). Direct MCP startup retains its separate Python 3.10+ host-PATH prerequisite.

How Codex asks questions

Codex asks only for a genuinely missing decision, material input or protected action. Authorized preparation, internal recovery and completion need no new consent. Existing answers, scope/digest confirmation and runtime permission remain authoritative.

  • Order of controls: Codex prefers permitted synchronous input, then this plugin's packaged native terminal form (ask_user, served by bin/user_questions_mcp.py). Each plugin ships its own provider; no sibling installation or user-settings change is required.
  • The local form waits for the answer and binds it to the decision ID and frozen scope digest. Closed choices use a selectable list; open-ended indexes, ranges, severity combinations and exact-token confirmations use native text input with the complete grammar. It performs no commands, repository writes, credential reads, network access or permission changes.
  • Approve/Deny replies bind to one unchanged, unambiguous conversational decision without demanding its displayed key again. Ambiguity, supersession, exact-token/digest and runtime-permission rules remain enforced.
  • No consent by default: no answer, cancellation or unsupported input grants consent.
  • Plain text: when required, all context, reports, confidence and limitations come before the question; the question and complete options or accepted input syntax are the final terminal block, with no trailing summary or status. Headless hosts retain an explicit unresolved-input fallback.
  • Dismissed question: a user-reported dismissed question leaves its decision pending. The root checks another suitable control, then asks once in its final plain-chat response if no control remains usable; the dismissed transport stays unsuitable for later required questions in that host until delivery is verified again. Rejected question calls resume at the pending decision without replaying delivered report context.
  • Claude-specific question behavior is unchanged.
📋 Contents

🎯 What it provides

The two hosts expose the same three bridge request operations and an approval-bound setup lifecycle:

Operation Purpose Default access
implement Complete a bounded change and report the resulting files and limits. Write-capable (workspace-write for Codex, acceptEdits for Claude).
advise Answer a focused question without editing files. Read-only.
review Perform an adversarial review of the current diff or supplied artifact. Read-only.
setup Inspect, configure, repair, authenticate, and verify one bridge direction. Safe inspection/configuration by default; authentication and live inference require separate approval.

Every bridge request call carries a model and reasoning-effort selection:

  • An omitted model uses the target CLI's configured host default; the envelope records model: "host-default".
  • An omitted skill effort is classified from the complete task using the shipped effort policy; direct CLI or MCP calls that bypass a skill use medium.
  • Supported effort aliases are normalized before dispatch, invalid values are blocked, and an explicitly supplied supported-effort list may cause one recorded downgrade.

Every call also carries a soft wall-clock budget and a recursion depth:

  • The budget is announced to the callee, which is asked to return a useful partial result with remaining and blockers instead of waiting indefinitely.
  • The bridge enforces a hard cutoff at 1.2 times the soft budget.
  • A depth of one or greater is refused, so a Claude → Codex → Claude loop cannot continue.

Results are compact envelopes rather than transcripts:

  • The public envelope carries decision-critical status, verdict, findings, files_touched, remaining, and blockers, plus observed harness metadata such as model, effort, cost, duration, depth, run_id, and a session identifier when applicable.
  • Required result fields and string/list types are checked without presentation item-count or string-length limits; actual child-record, output-capture, and transcript byte limits still apply.
  • Incomplete work and blockers must stay in those public fields; transcript-only details hold additional evidence and never hide required work.
  • The envelope carries workspace-relative transcript_path and, for faults, an incident path; open the referenced JSON file and inspect its fault member only when the compact result needs investigation.
  • Detached calls return their job identifier separately.

The model-authored core is validated separately from harness metadata; model output cannot claim observed cost, timing, process, or correlation fields.

Skills and contract rules

Every skill and shipped rule is listed here; each links to its own file.

Skill Host Purpose
/bridge:implement Claude Code Bounded write-capable change by Codex; supports --background.
/bridge:advise Claude Code Read-only answer from Codex.
/bridge:review Claude Code Read-only adversarial review by Codex.
/bridge:setup Claude Code Approval-bound check, configure, repair, authenticate, verify.
/bridge:status Claude Code Inspect a detached implement job.
/bridge:result Claude Code Read a detached job's result.
/bridge:cancel Claude Code Cancel a detached job.
$bridge:implement Codex Bounded write-capable change by Claude Code.
$bridge:advise Codex Read-only answer from Claude Code.
$bridge:review Codex Read-only adversarial review by Claude Code.
$bridge:setup Codex Approval-bound setup lifecycle for the peer.
Rule Covers
envelope.md Result envelope: model-authored core and harness metadata.
escalation-policy.md Effort and timeout policy.
prompting.md Neutral task prompting and budget preamble.
recursion-guard.md Depth and run_id propagation.
self-healing.md Bounded self-healing; no write-timeout retries.
provider-consent.md Claude provider consent.
claude-transfer-policy.txt Exact approved consent block.
codex-user-questions.md Codex question routing; details in codex-user-questions-details.md.
cli-baseline.json Verified host CLI surface baseline.

✅ Requirements

  • Claude Code with plugin support for the Claude half.
  • OpenAI Codex CLI for Claude → Codex calls, available as codex on PATH and authenticated for the requested model.
  • Claude Code CLI for Codex → Claude calls, available as claude on PATH and authenticated for the requested model.
  • A python executable on PATH that reports Python 3.10 or newer for the bridge's Python entry points; the same launcher is used on POSIX and Windows.
  • The plugin's bin/python and native Windows bin/python.cmd probe candidates for Python 3.10+ before running Claude Code shell workloads once, preserving an eligible system python.
  • The direct MCP command still requires Python 3.10+ available as python on the host search path. Codex Rig sync validates this prerequisite without installing a global interpreter shim, and a missing eligible runtime keeps the affected interaction unresolved.
  • A writable project-local .temp/bridge/ directory for bridge state and transcripts.
  • A writable platform user-state directory for the host-held approval-integrity key, one-use approval receipts, per-target mutation locks, and sanitized setup records; setup never stores provider credentials or raw login output there.

The setup skill can orchestrate verified native plugin/configuration operations and one closed repair per fault after an exact plan approval.

It never installs runtimes, replaces the current host invocation surface, reads credentials, or grants permissions. Provider-owned authentication and live inference retain separate approvals and terminal/network boundaries. The Codex-side MCP server is host-launched outside the model's sandbox so it can reach the Claude CLI's normal authentication path; a Claude CLI that is not logged in remains a reported setup/authentication failure.

🧭 Set up the bridge

The loaded host is the current host and target=peer resolves to the other integration.

A current-host plugin, trust, authentication, and fresh session are external bootstrap prerequisites; a setup skill cannot repair the invocation surface from which it was loaded.

After bootstrap, run the same command on either host:

/bridge:setup action=all target=peer scope=auto live=prompt
$bridge:setup action=all target=peer scope=auto live=prompt

Plain /bridge:setup and $bridge:setup invocations use those defaults. all:

  1. Inspects, proposes, and reports every supported stage.
  2. Asks for one expiring, one-use approval before safe configuration or repair, bound to the exact action, target, resolved scope, workspace, observed-state fingerprint, native argv, external capability, rollback record, and stop condition.

The digest is authenticated with a host-held per-user HMAC key so a caller cannot forge or alter a plan, but the digest is not consent: the operator or host permission surface must still approve the displayed operation. A denial, changed or expired digest, replay, failed probe, or failed operation stops without an equivalent retry.

The remaining setup stages have distinct boundaries:

Stage Behavior and boundary
action=check Credential-free inspection only.
action=configure and action=repair Apply one approved native operation, then re-inspect the host inventory before reporting whether a fresh session is required.
action=authenticate Launches only the peer's official no-capture login through a separately planned provider-owned interactive flow that the operator runs in their own terminal, outside model-captured tool streams, so Bridge can inherit the terminal without receiving login output.
action=verify-live Performs one separately approved live probe through the same planner/executor; live verification uses a third action-bound approval for one paid provider call.
live=skip Finishes at inference-unverified.
live=required Is non-ready when the live approval or probe fails.

One setup run owns one peer target. To prepare both integrations, complete the peer lifecycle from one host, honor any fresh-session boundary, then run the other host's setup skill; no approval or readiness claim is shared across them.

The setup result is defined by schemas/setup-result.schema.json, separate from the model bridge envelope:

  • It reports the strongest evidence level reached: static, host-authenticated, session-ready, workspace-ready, or live-verified.
  • It never treats process exit, authentication, or static checks as proof of inference.
  • The deterministic setup CLI cannot prove the loaded session/workspace and therefore remains non-ready even after a successful point-in-time live probe; the host skill may claim a stronger lifecycle result only after applicable loaded-session evidence is also present.
  • The read-only MCP tool bridge_status returns sanitized server identity, version, schema/protocol version, explicit binding status, binding identity, confirmed canonical workspace, workspace fingerprint, and expected tool inventory without calling a provider or writing state.

🔌 Is MCP required?

MCP is complementary to the bridge as a whole but mandatory for the Codex → Claude Code direction.

  • Claude Code → Codex launches codex exec directly and does not need MCP.
  • Codex → Claude Code must use the packaged MCP server: a claude --print process started from a sandboxed Codex model turn cannot rely on the normal Claude authentication context, while the Codex host launches the MCP server outside that model sandbox.

If you install only the Claude Code half to call Codex, MCP is not required. If you install only the Codex half or want the complete bidirectional bridge, the .codex-mcp.json declaration and bin/bridge_mcp.py are required transport components, not optional enhancements. The MCP boundary provides the three request tools plus read-only status and native workspace binding tools and prevents model-controlled workspace, background, or session selection.

Architecture — animated diagrams of both hosts and their own engines, MCP surface, setup lifecycle, permissions, workspace binding and the request lifecycle

Bridge architecture: Claude Code to Codex and Codex to Claude Code over one shared supervisor (animated)

The request lifecycle diagram follows one advise, review or implement call from entry through model, effort and budget selection, authority gates and peer launch to the result envelope, then covers the detached-job status, result and cancel controls and their terminal states.

Bridge request lifecycle: entry, selection, gates, peer launch, result envelope and detached job states (animated)

📦 Install for Claude Code

The Codex-facing MCP surface has five tools: bridge_implement, bridge_advise, bridge_review, the zero-provider read-only bridge_status, and bridge_bind_workspace. MCP is required for Codex → Claude Code and full bidirectional use, but not for Claude Code → Codex-only use.

Add the AI-Rig marketplace and install bridge_CC-Codex:

claude plugin marketplace add Borda/AI-Rig
claude plugin install bridge@borda-ai-rig

Start a fresh Claude Code session after installation. Run the static local CLI check with:

/bridge:setup

The default setup path is end-to-end and approval-bound:

  1. Check the installed payload and native CLI capabilities.
  2. Propose safe configuration or repair.
  3. Apply only the approved exact operations.
  4. Separately offer provider-owned authentication when needed.
  5. Verify each applicable evidence level.

It never captures sensitive login material or claims readiness beyond the evidence returned. Use the canonical syntax above; the legacy --live and --direction forms are accepted only for one release and are normalized to the same approval boundaries:

/bridge:setup action=verify-live target=peer live=required

⚡ Use from Claude Code

Invoke the namespaced skills directly. Pass a concrete task or question and select the model and effort when the host default is not appropriate:

/bridge:implement --model <codex-model> --effort <effort> --timeout-seconds 600 "Run the focused test and fix the smallest verified defect."
/bridge:advise --model <codex-model> --effort <effort> --timeout-seconds 120 "Which files own this behavior, and what evidence should I collect first?"
/bridge:review --model <codex-model> --effort <effort> --timeout-seconds 300 "Review the current diff for correctness, regressions, and missing tests."

The verb skills accept the bridge's task text and these caller-selected fields:

Applies to Fields and behavior
All verbs --timeout-seconds, --depth, --run-id, and --workspace. Omitted budget uses the per-verb default (advise 120 seconds, review 300 seconds, implement 600 seconds); omitted depth starts an outermost call at zero.
implement --background and --session-id. A write-capable implementation is never automatically retried after timeout because its process may already have changed the worktree.
advise, review, implement --network none\|github-read (default none; caller opt-in, Codex peer only).
advise and review May receive one bounded retry at the next lower supported effort tier, so the retry can finish within the same budget.

Task text and timing

  • Pass task text with --task, or with --task-file <path> when it contains a backtick, $, double quote, backslash or a flag-shaped token. The two are mutually exclusive, and the file must be a regular file of at most 16 KiB.
  • Worst-case wall time of one call is --timeout-seconds × 2.4: the hard cutoff is × 1.2, and a timed-out advise or review retries once at the next lower effort with the same budget.
  • Foreground calls set their Bash timeout above that figure; when it can reach the ~10 min foreground cap, run the call in the background.
  • A status=error object (exit 2) is a refused invocation, such as passing both --task and --task-file: fix the invocation rather than retrying it unchanged.

Detached jobs

Long-running implementation work may be detached. Use the job identifier printed by the bridge to inspect or stop it — one check when you have a reason to look, never a polling loop; any state other than queued or running is final:

/bridge:status [--workspace PATH] <job-id>
/bridge:result [--workspace PATH] <job-id>
/bridge:cancel [--workspace PATH] <job-id>

Pass the same --workspace the originating call used; when it omitted the option, pass the absolute directory it ran from, never ., since a different or omitted value resolves to another workspace and reports missing. Job states:

State Meaning
queued, running Not final; check again only when there is a reason to.
cancel_requested Not final: the supervisor and any write-capable child are still being torn down; ends as cancelled.
finished The job completed; read it with /bridge:result.
cancelled Cancellation completed.
failed The supervisor itself errored; its error is returned. An implement job may already have edited files.
stalled The supervisor is gone, or the job is still queued after 120 seconds. Route to /bridge:result.
missing No such job in this workspace: a wrong workspace, a job that never existed, or one already pruned.

Background execution and lifecycle controls are available only for Claude Code → Codex implement.

  • advise and review are ephemeral calls without job records; the Claude skills run them as background Bash calls (run_in_background: true) when the budget can reach the ~10 min foreground cap or the caller has independent work, so the host shows a task row and a completion notification at no extra model cost.
  • Every Claude skill reply ends with one usage line copied from the envelope (codex <model>/<effort> · in … (cached …) · out … · N s).
  • The Codex → Claude MCP transport does not expose reverse background requests or separate status/result/cancel skills.

After an implementation returns:

  1. Re-read every path in files_touched[] before making another edit.
  2. Do not edit paths named by a still-running implementation task; the job record is the coordination boundary.

Session continuation is also limited to Claude Code → Codex implement:

  • Pass the explicit session identifier returned by a prior implementation.
  • Keep the same workspace.
  • Never use a “most recent session” selector.
  • Advice and review always start fresh ephemeral Codex runs.
  • The reverse MCP path does not resume Claude sessions.

📦 Install for Codex

Register the repository marketplace and add the Codex plugin:

codex plugin marketplace add Borda/AI-Rig
codex plugin add bridge@borda-ai-rig

The Codex manifest declares the bridge MCP server via .codex-mcp.json, which starts bin/bridge_mcp.py. Claude Code ships no .mcp.json: the Claude-to-Codex direction is CLI-only (bin/bridge_call.py), and the plugin deliberately never ships that file because Claude Code would auto-discover it and register a server it has no use for.

If Codex asks you to trust or enable the installed MCP content, review the displayed command and approve it according to your local policy.

Workspace binding

The server starts unbound; its launch directory locates installed code and never grants project authority.

  1. Call bridge_bind_workspace with the known absolute project folder as untrusted proposed_workspace. Empty arguments retain manual selection followed by confirmation.
  2. Confirm its exact canonical target in one native form, which states that Codex proposed the folder.
  3. Every advise/review/implement call then requires the current binding_id returned by binding/status; missing or stale IDs fail before provider work. Rebinding clears old authority immediately, including cancellation. Folder resolution and directory identity are rechecked before each executable call.

Binding is process-local project identity, not editing approval, runtime permission, authentication, or paid-call consent.

Refused folders (bridge_setup.py --workspace refuses the same ones, with no marker rule, for every action except the read-only check):

  • Filesystem root, home itself and every directory above it, and installed payload/cache folders.
  • Agent configuration homes with everything inside them (~/.claude, ~/.codex, and the directories CLAUDE_CONFIG_DIR and CODEX_HOME name).
  • User credential directories with everything inside them (~/.ssh, ~/.aws, ~/.gnupg, ~/.kube, ~/.docker).
  • Outside Windows, /etc with everything inside it.

Project subdirectories of home are allowed. bridge_implement additionally needs project evidence in the bound folder or an ancestor below the home: .git (directory or worktree file), .hg, .svn, pyproject.toml, setup.py, setup.cfg, package.json, Cargo.toml, go.mod, pom.xml, build.gradle, build.gradle.kts, CMakeLists.txt or Makefile; advise and review need none.

Start a fresh Codex session after installation, then run the Codex-side setup skill:

$bridge:setup

The Codex half degrades cleanly when claude is absent or unauthenticated: setup reports the prerequisite and bridge calls return a structured blocked result.

The static planner does not establish that the current MCP session is loaded or workspace-bound; use bridge_status from a fresh Codex session for that evidence. The bridge does not install Claude, read credentials from files, or fall back to a shell call inside the Codex sandbox.

Codex questions use a short shared guide shipped locally by this plugin. The root uses a permitted question route with meaningful presets and built-in custom input; children hand decisions back to the root. Host restrictions still apply; this does not override a plain-text-only host.

⚡ Use from Codex

Use the Codex skills for the same three operations:

$bridge:implement --model <claude-model> --effort <effort> --timeout-seconds 600 "Implement the bounded change and report the files touched."
$bridge:advise --model <claude-model> --effort <effort> --timeout-seconds 120 "Explain the smallest safe next step without editing files."
$bridge:review --model <claude-model> --effort <effort> --timeout-seconds 300 "Review the current diff and list actionable findings."

The skills invoke the bridge MCP tools bridge_implement, bridge_advise, bridge_review, bridge_status, and bridge_bind_workspace.

Tool group Contract
Bridge request tools Accept task, optional model and effort, and optional timeout_seconds, depth, run_id, and supported-effort capability data. Omitted model, effort, depth, and run ID use the host-default, medium, zero, and a new UUID respectively.
bridge_bind_workspace Accepts optional untrusted proposed_workspace; user confirms the exact canonical project in one native form. Empty arguments retain manual selection and confirmation. Rebinding clears old authority; no form support means unbound.
bridge_status Accepts no workspace override and performs no peer, provider, write, repair, or authentication operation.
Reverse timeouts Implementations accept at most 700 seconds; advice and review accept at most 350 seconds because their one allowed timeout retry, including per-attempt termination and drain overhead, must also finish within the MCP host's 900-second deadline.
Host boundary The server requires native user-confirmed project binding and the current binding ID, and rejects model-supplied workspace, background, and session fields.

The bridge supplies the budget preamble, invokes claude -p with the narrowest permission mode for the verb, and returns the same compact envelope used by the Claude half. The peer's bounded verbose details remain in the transcript referenced by the envelope; they are not copied into the caller's context.

Do not invoke claude -p directly from a sandboxed Codex model turn: the bridge MCP server is the supported transport because it runs in the host context where the normal Claude authentication path is available.

🎚️ Model, effort, budget, and depth

Model and effort selection:

  • The caller's explicit model is passed to the target CLI; the bridge does not discover or validate model availability before dispatch.
  • An omitted model uses the target host default and is represented as host-default in the envelope.
  • The caller's explicit effort is normalized before dispatch. Supported values are minimal, low, medium, high, xhigh, and max, with trivial and none accepted as aliases for minimal.
  • An invalid value returns blocked; when a caller supplies supported-effort capabilities, one lower supported value may be recorded in effort_substituted.

Budget and result states:

Item Contract
Soft budget Two minutes for advise, five minutes for review, and ten minutes for implement. A callee receives the budget in-band and is expected to scope its work to fit.
Hard cutoff 1.2× the soft budget.
Transport input MCP accepts at most 16,384 task characters; Bridge rejects task UTF-8 over 16 KiB or a constructed prompt over 20 KiB before creating artifacts or launching a peer.
Child output Raw stdout records and every compacted record are bounded to 256 KiB, as is retained combined stdout/stderr. Overflow terminates the peer tree with output-limit.
partial Valid work with explicit remaining.
blocked Names the permission, authentication, or input blocker.
timeout Identifies a cutoff.
refused Identifies recursion protection or another deliberate refusal.

Child output details:

  • Codex commands keep only a UTF-8-safe 4 KiB prefix of completed output plus byte count and SHA-256 digest; prompts warn Codex to keep commands small without inline scripts or data and Claude to keep final JSON within the derived cap.
  • Overflow still terminates the peer tree with output-limit, including final flush, timeout and cancellation paths. Optional Codex-only partial_output salvages at most 4 KiB of the last complete agent message in the envelope and incident, labelled an unverified fragment for scoping follow-ups, never findings or a verdict.
  • On Windows the full argv is measured with list2cmdline UTF-16 semantics; .cmd/.bat shims use a conservative 8,000-unit ceiling below Cmd.exe's 8,191-character limit. The exact record-admission rules are in docs/security.md.

Depth and correlation:

  • depth starts at zero for a caller-originated request.
  • Before launching the peer, the transport increments it in CC_CODEX_BRIDGE_DEPTH; the peer CLI and MCP process inherit that trusted value, and caller input cannot lower it.
  • Negative depth is rejected, and a call received at trusted depth one or greater returns refused: recursion-depth.
  • run_id is minted once at the outermost call and echoed through the call chain, so health records from both hosts can be correlated without conflating a Codex thread identifier with a Claude session identifier.

📊 Results and artifacts

Each child attempt writes its bounded host transcript once. Complete Codex command-output payloads are summarized by their UTF-8 byte counts and SHA-256 digest; other retained events and Claude output remain unchanged. The digest can compare separately retained output but cannot reconstruct discarded content, and capture-byte savings do not establish provider token savings.

The public envelope returns the compact decision core, including decisions, blockers, and remaining work, with observed metadata and workspace-relative transcript or incident references; verbose peer details stay in the transcript as additional evidence and never substitute for required public fields.

Bridge state is project-local:

.temp/bridge/raw-<timestamp>.txt                    bounded transcript, referenced by the envelope
.temp/bridge/jobs/<job-id>.json                     detached-job metadata and lifecycle state
.temp/bridge/jobs/<job-id>.cancel.json              durable cooperative-cancellation request
.temp/bridge/health.jsonl                           one health/cost record per completed bridge call
.temp/bridge/incidents/<timestamp>-<fault>.json     sanitized fault and recovery evidence

Artifact handling:

  • Artifact directories and members are rechecked against the bound project and store before reads, creation, and writes. Escaping parents and linked file leaves are rejected; directory aliases contained within the store remain usable. These checks do not promise immunity to concurrent path replacement during an OS operation.
  • Incident records do not persist child command arguments or environment data. They preserve the classified fault, reason, model, effort, verb, budget, transcript path, and—when a write-capable process is killed—the observed worktree delta. That delta is advisory: unchanged dirty status or unavailable Git can produce an empty delta despite edits, so inspect the actual worktree independently.
  • The optional health log records direction, verb, model, effort, cost/tokens when reported by the host, duration, status, depth, and run_id. A write failure appends a sanitized nonblocking telemetry warning to public findings, preserving the original status, verdict, decision fields and incident without rerunning the child. A symlink, reparse point, hard link, or nonregular health.jsonl is refused without writing its target.
  • Setup summarizes blocked/timeout/refused counts, their latest timestamps, and reported cost by direction, verb, and model; static CLI findings are reported separately.

Artifacts are evidence, not authority. Read the envelope, source changes, tests, permissions, and remaining limits before accepting consequential work. Delete .temp/bridge/ only under your project's normal retention policy and only after preserving any incident or review evidence you still need.

For an output-limit incident, use the bounded-work recovery steps. A compact final answer alone does not cap tool output, and the Bridge does not automatically retry this fault.

🔒 Privacy and security boundaries

The bridge sends the task text and the selected project context to the provider CLI named by the direction of the call. Provider billing, retention, account access, and model availability remain governed by the provider and your host configuration. The bridge does not upload artifacts to a separate service or persist credentials.

Safety boundaries:

  • Use advise and review for read-only work.
  • A review's confidence gaps or unavailable checks are factual limits, not authority for another review; an out-of-scope pass requires one explicit user decision naming its gap, expected evidence/output, and stop condition.
  • implement can modify the current worktree under the host's normal permission policy.
  • Setup configuration and repair are state-changing operations bound to an exact approval digest.
  • Authentication failures, permission denials, unsupported models, and unknown faults are surfaced as structured results or incidents.
  • Provider login output is never captured, and rollback never touches credentials.
  • The peer child receives an allowlisted environment, not the caller's: base process keys, provider authentication keys, and on Windows the interpreter start-up keys. Unrelated API keys, cloud credentials, and the session's inter-agent messaging variables are dropped. A host whose proxy or enterprise provider path needs more names them in BRIDGE_CHILD_ENV_EXTRA (comma-separated).
  • Timeout and cancellation give POSIX peer groups a two-second cooperative grace, then force termination of any members left; Windows invokes taskkill /T /F. Native Windows reparse and tree behavior still require native-host verification. A failed output drain returns a non-retrying blocked result rather than timeout or cancellation unless output-limit was already observed.

Network access:

! BREAKING — unless the caller opts in with --network github-read, every Codex invocation pins sandbox_workspace_write.network_access=false, so an implement task that installed a dependency, refreshed a lockfile, or ran a network-touching hook now fails inside the sandbox. The control is Codex-side only; the Claude child is constrained by permission mode instead.

--network github-read is an opt-in per call; the default stays none, and the Claude peer refuses it:

  • It swaps that pin for a profile that allows GET, HEAD and OPTIONS to api.github.com only, and keeps .git, .codex and .agents at the workspace root read-only.
  • It relies on Codex's experimental network_proxy feature (an unknown profile key is silently ignored by Codex, so re-check after upgrades).
  • A GET can still carry workspace content in its URL, so prefer fetching GitHub data yourself and passing it in the task file.
  • Each opted-in call first proves the limits with a sandbox preflight (a few requests to api.github.com and example.com) and is refused if any fails.
  • The opt-in is refused outside macOS until enforcement there is verified. See docs/security.md.

The bridge never bypasses host permission prompts, invents a credential, retries a write-capable timeout, or silently replaces a requested effort tier.

⬆️ Updating, uninstalling, and human-owned gates

  • Update the marketplace snapshot through the host's normal plugin manager, then restart the host session.
  • Uninstalling one half does not remove the other half or alter host credentials.
  • Remote publication, marketplace refresh, provider login, MCP trust approval, and any permission escalation remain human-owned operations.
  • The bridge's checked-in manifests and host baseline describe the CLI surface it was verified against. If setup reports missing or changed flags, upgrade the host or use a bridge release that supports the installed host; do not patch the baseline at runtime.
  • Ordinary make sync-* runs invoke only the direct static doctor with explicit read-only semantics; they never invoke a setup skill, model, approval token, authentication, repair, restart, or provider call.
  • After source changes, run the local verification commands in Development and release verification: the focused plugin test suite, the whitespace check, and the disposable install-shaped package build and validation, with both Linux/macOS and native Windows PowerShell variants.

Run action=verify-live ... live=required only after explicitly accepting the separate provider call and its cost. A live setup probe verifies one selected path at that moment; it is diagnostic evidence, not proof that a future task will succeed. This documentation does not claim that either host is currently authenticated or live-verified.

📚 Maintainer documentation

  • Architecture and transport shows the Claude Code and Codex hosts as mirrored planes, with the user's skills on top and each host's own engine at the bottom, plus process boundaries, permissions, and exactly where MCP is required; the request lifecycle diagrams one call's gates, retries, result envelope and detached-job states.
  • Security and privacy defines authority, data flow, artifacts, result integrity, recovery, and cancellation boundaries.
  • Operations and troubleshooting covers prerequisites, diagnosis, foreground calls, detached jobs, common failures, and artifact inspection.
  • Development and release verification records the package layout, local gates, installed-shape validation, and release responsibilities.

📄 License and attribution

This plugin is distributed under the Apache License, Version 2.0; see LICENSE. Repository attribution is in NOTICE. The bridge's implementation is maintained as a self-contained package and does not require a sibling plugin.