Agent Bridge first use: Codex↔Claude
Review alpha conditions, then follow installation decisions, enrollment, routes, real acknowledgement and shutdown in one small pair. A human bounds model use and operational changes.
Documentation reviewed 2026-11-05 · Alpha · macOS · UNLICENSED
Check the conditions first
Release 0.1.0-alpha.1 installs on macOS only and requires Node >=26.5.1 <27. Stop on Windows/Linux. Kit is not required.
UNLICENSED: public download is not an open-source license grant. Review alpha use and license suitability. Real multi-pair isolation, Claude/AGY receiver crash boundaries and long-running operation are unverified. An intermittent test failure and possible store race remain unresolved in the published notes.
Terminal in your selected practice workspace. Replace every placeholder; inspect results before continuing.
uname -s node --version npm --version git --version
Choose version policy, location and scope
Choose guide basis 0.1.0-alpha.1 or review current releases. Latest may still be alpha. Inspect current/proposed Node/npm/Git/Bridge versions, compatibility and impact first. Published native evidence names macOS Node 26.5.1; exact verified npm/Git versions are not recorded.
A separate folder needs path management, local changes project dependencies, global affects a shared install. The example below is only for a human-selected guide basis plus separate folder. Other combinations have labeled commands in the AI source.
Terminal in your selected practice workspace. Replace every placeholder; inspect results before continuing.
# macOS only. Confirm engines/platform/license and both human choices first. BRIDGE_APPROVED_VERSION="<HUMAN_APPROVED_BRIDGE_VERSION>" BRIDGE_VERSION="0.1.0-alpha.1" && test "$BRIDGE_VERSION" = "$BRIDGE_APPROVED_VERSION" && npm install --prefix "$HOME/holmes-tools/agent-bridge/$BRIDGE_VERSION" --save-exact "@holmes-lab/agent-bridge@$BRIDGE_VERSION" && BRIDGE_CLI="$HOME/holmes-tools/agent-bridge/$BRIDGE_VERSION/node_modules/@holmes-lab/agent-bridge/dist/cli.js" && test -f "$BRIDGE_CLI" && BRIDGE_ACTUAL_VERSION="$(node "$BRIDGE_CLI" --version)" && test "$BRIDGE_ACTUAL_VERSION" = "$BRIDGE_VERSION" && node "$BRIDGE_CLI" --help
Prepare isolated workspaces and a private runtime
Use two new practice workspaces. Replace placeholders with actual canonical absolute paths and distinct private credential files for each session. Initialization writes state: review scope/authorization first. Never copy credentials into a web page or message.
Terminal in your selected practice workspace. Replace every placeholder; inspect results before continuing.
RUNTIME="<NEW_PRIVATE_ABSOLUTE_RUNTIME>" CLAUDE_WS="<CANONICAL_ABSOLUTE_WORKSPACE_A>" CODEX_WS="<CANONICAL_ABSOLUTE_WORKSPACE_B>" CLAUDE_CREDENTIAL="<NEW_PRIVATE_ABSOLUTE_FILE_A>" CODEX_CREDENTIAL="<NEW_PRIVATE_ABSOLUTE_FILE_B>" node "$BRIDGE_CLI" init --runtime-dir "$RUNTIME" node "$BRIDGE_CLI" allow-workspace --path "$CLAUDE_WS" --runtime-dir "$RUNTIME" node "$BRIDGE_CLI" allow-workspace --path "$CODEX_WS" --runtime-dir "$RUNTIME"
Explicitly enroll the Claude session
The operator chooses SESSION_UUID for the new Claude session and defines it below. Enroll, review the config preview, then apply. Review and run the launch command printed by install-claude. Claude development-channel trust is a native human decision, never automatically accepted.
Terminal in your selected practice workspace. Replace every placeholder; inspect results before continuing.
CLAUDE_SESSION_UUID="<UUID_FOR_THE_CLAUDE_SESSION_YOU_WILL_LAUNCH>" node "$BRIDGE_CLI" enroll --engine claude --native-session "$CLAUDE_SESSION_UUID" --workspace "$CLAUDE_WS" --display-name claude-a --transport claude-channel --credential-out "$CLAUDE_CREDENTIAL" --runtime-dir "$RUNTIME" node "$BRIDGE_CLI" install-claude --workspace "$CLAUDE_WS" --credential-file "$CLAUDE_CREDENTIAL" --dry-run --runtime-dir "$RUNTIME" # Apply only after reviewing the preview; then inspect the printed launch command. node "$BRIDGE_CLI" install-claude --workspace "$CLAUDE_WS" --credential-file "$CLAUDE_CREDENTIAL" --runtime-dir "$RUNTIME"
Configure Codex, then enroll its actual thread
Set CODEX_SOCKET from the daemon version output socketPath. Starting a missing daemon is a separate operational change. Respect socket/parent ownership and permission checks. Configure, launch Codex using the printed command, check /new and /mcp, then enroll the actual thread ID.
Terminal in your selected practice workspace. Replace every placeholder; inspect results before continuing.
codex app-server daemon version CODEX_SOCKET="<ACTUAL_SOCKET_PATH_FROM_DAEMON>" node "$BRIDGE_CLI" install-codex --workspace "$CODEX_WS" --credential-file "$CODEX_CREDENTIAL" --codex-socket "$CODEX_SOCKET" --dry-run --runtime-dir "$RUNTIME" # Review, apply, launch the printed Codex command, then /new and /mcp. node "$BRIDGE_CLI" install-codex --workspace "$CODEX_WS" --credential-file "$CODEX_CREDENTIAL" --codex-socket "$CODEX_SOCKET" --runtime-dir "$RUNTIME" node "$BRIDGE_CLI" codex-threads --codex-socket "$CODEX_SOCKET" --runtime-dir "$RUNTIME" THREAD_ID="<ACTUAL_NEW_CODEX_THREAD_ID>" node "$BRIDGE_CLI" enroll --engine codex --native-session "$THREAD_ID" --workspace "$CODEX_WS" --display-name codex-a --transport codex-app-server --credential-out "$CODEX_CREDENTIAL" --runtime-dir "$RUNTIME"
Allow both routes and make one bounded round trip
The runtime starts paused. Allow only the two required directions; run the broker in a dedicated terminal. Define the same RUNTIME/BRIDGE_CLI in another terminal before resume. A human must first bound the model request count, elapsed time, cost and stop conditions. This website runs no sessions or models.
- Transport acceptance
- Receiver bridge_ack
- Separate work completion
Terminal in your selected practice workspace. Replace every placeholder; inspect results before continuing.
node "$BRIDGE_CLI" allow-route --from "$CLAUDE_WS" --to "$CODEX_WS" --runtime-dir "$RUNTIME" node "$BRIDGE_CLI" allow-route --from "$CODEX_WS" --to "$CLAUDE_WS" --runtime-dir "$RUNTIME" # Dedicated foreground terminal: node "$BRIDGE_CLI" run --codex-socket "$CODEX_SOCKET" --runtime-dir "$RUNTIME" # Another terminal with the same selected runtime: node "$BRIDGE_CLI" resume --reason "bounded pair ready" --runtime-dir "$RUNTIME" node "$BRIDGE_CLI" status --runtime-dir "$RUNTIME"
Observe evidence and stop
Ask the sender to inspect actual bridge_peers and send one greeting with no execution instructions using bridge_send. The receiver reads bridge_inbox and calls bridge_ack. An acknowledgement is not work completion; bridge_work_receipt is separate. A reply stays within the authorized round-trip budget. /mcp visibility alone is not delivery proof.
Never automatically retry delivery_unknown. Inspect the receiver before official reconcile; confirmed_not_sent can queue another delivery. Finish with pause/stop and revoke practice registrations when appropriate.
Terminal in your selected practice workspace. Replace every placeholder; inspect results before continuing.
node "$BRIDGE_CLI" messages --state delivery_unknown --runtime-dir "$RUNTIME" node "$BRIDGE_CLI" pause --reason "practice complete" --runtime-dir "$RUNTIME" node "$BRIDGE_CLI" stop --runtime-dir "$RUNTIME" # Optional, after inspecting actual practice registration IDs: # node "$BRIDGE_CLI" revoke --registration "<ACTUAL_ID>" --reason "practice complete" --runtime-dir "$RUNTIME"