Holmes LabAgentic Software Engineering Architect

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.

Explanatory flow — not a live session or recorded execution
  1. Transport acceptance
  2. Receiver bridge_ack
  3. 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"

Continue from here