Skip to content

About

MCP bridge for creating and messaging other Codex sessions on the same host

Resources

Contributing

Stars

4 stars

Watchers

0 watching

Forks

Repository files navigation

codex-thread-bridge

An MCP bridge to an existing Codex App Server on the same host, providing an alternative to Codex Desktop or another client for thread operations. It reproduces native client requests while leaving execution to the App Server.

Install

Requires Python 3.11+, uv, and an authenticated Codex App Server with a Unix WebSocket control socket. Git is required for worktree launches. The bridge runs as the same user and on the same host as App Server.

From a clone of this repository:

uv sync --frozen --no-dev
.venv/bin/codex-thread-bridge --help
codex mcp add codex-thread-bridge -- /absolute/path/codex-thread-bridge/.venv/bin/codex-thread-bridge

The default socket is $CODEX_HOME/app-server-control/app-server-control.sock; CODEX_HOME defaults to ~/.codex. Use --socket /path/to.sock to override it. Authentication and model usage belong to the existing App Server.

On Windows, the bridge uses codex app-server proxy --sock as a raw WebSocket byte relay. On Unix, it connects directly to the socket. Use --transport proxy to select the relay explicitly, and --codex-binary /path/to/codex if the CLI is not on PATH. The equivalent environment variables are CODEX_THREAD_BRIDGE_TRANSPORT and CODEX_THREAD_BRIDGE_CODEX.

After changing bridge code or MCP configuration, request a refresh with:

uv run --locked codex-thread-bridge-reload

The command accepts --socket, asks for y/N confirmation, and queues a refresh for loaded tasks. Its response does not confirm that every task has refreshed.

Tools

Tool Behavior
get_capabilities Report server identity and bridge capabilities
create_thread Create a retained task in an existing directory, with an optional title and initial prompt
create_worktree_thread Create a retained, locked Git worktree and a task at a specified commit
update_thread_permissions Apply and verify permissions for an idle task with an expected identity
send_message_to_thread Resume an idle task and start a turn without settings overrides
steer_thread Append a message to the active turn identified by expected_turn_id
list_threads Discover active/archived headers by source kind, direct parent or ancestor without loading bodies
read_thread Read task metadata and paginated history without resuming
read_thread_metadata Read unchanged native metadata with source and coverage information
read_thread_turns Read unchanged native full-item turn pages, newest first
read_thread_items Read unchanged native item pages, oldest first, optionally by turn
read_thread_chunk Recover a raw metadata/turn/item response in source-bound JSON chunks
reconstruct_thread_record Validate contiguous chunks and reconstruct one native response
wait_thread Wait up to 50 seconds for a specified recent turn
get_goal Read persistent Goal state
get_operation Read the retained receipt for a mutation request

Tool schemas are exposed through MCP. Their definitions are in server.py.

Header discovery

list_threads preserves native header fields and opaque pagination cursors. Pass archived: false for active records and archived: true for archived records; each query covers one partition. parent_thread_id selects direct spawned children, while ancestor_thread_id selects descendants at every depth and excludes the ancestor itself. The two filters are mutually exclusive. Keep filters unchanged when following a returned cursor.

source_kinds accepts cli, vscode, exec, appServer, subAgent, subAgentReview, subAgentCompact, subAgentThreadSpawn, subAgentOther and unknown. Omitted or empty source kinds use the server's interactive-source default; explicitly include subagent kinds when discovering delegated work. State-database-only inspection remains enabled, so discovery does not scan rollouts to repair metadata. Records absent from that database remain a coverage gap. Discovery uses only thread/list; it never reads unrelated turns, resumes tasks or changes operational state.

The added discovery envelope distinguishes a returned page from an unsupported or unavailable request, including rejected arguments such as a stale cursor. A failed request has data: null, pageComplete: false and the native rpcError; it does not retry without the requested filters. An unknown response schema is preserved with status: unsupported_schema and incomplete coverage. On a valid response, pageComplete means the selected listing has no next page, rather than complete conversation or descendant history. Coverage limits describe state-database scope, archive/source partitions, per-record ancestry and unsupported continuation mapping.

relationships retains each stable thread ID and both supported parent evidence fields: parentThreadId and source.subAgent.thread_spawn.parent_thread_id. Per-record status distinguishes supported evidence, conflicting parents, a self-cycle and unknown ancestry. Consumers must reconcile the preserved parent edges across all pages to detect longer cycles and missing links before opening descendant bodies. Similar titles, timestamps, working directories and agent paths establish no relationship. forkedFromId and sessionId are preserved as source facts; neither proves that a record is a continuation of another conversation. The connector exposes no native continuation-membership filter and reports that limitation explicitly.

These filter shapes were checked against the experimental schema generated by Codex CLI 0.162.0 with codex app-server generate-json-schema --experimental. Existing bridge behavior was previously exercised with Codex 0.153.4; this does not establish every server's discovery support. get_capabilities describes implemented requests and experimental compatibility limits. Native rejection or missing structural evidence remains a gap, and acceptance of a filter alone does not validate a complete ancestry chain. Automated discovery tests use the fake App Server; no live sessions are created for these checks.

Complete persisted-record retrieval

read_thread remains a compact convenience view. Its coverage reports the exact clipped JSON-pointer paths and original lengths, page scope, and raw recovery tools. Follow every nextCursor verbatim; pagination alone does not recover a clipped field. A page is never a claim of complete conversation evidence.

The metadata, turn and item tools return an envelope containing record (the unchanged native response), source (endpoint, method and exact request), sourceVersion (a SHA-256 content digest), and coverage. Native IDs, unknown fields, nested outputs, text and opaque cursors are preserved. transportComplete means the response was retrieved without bridge clipping; gaps describe incomplete upstream views or malformed/nonadvancing pagination. Persistence limitations remain distinct from transport completion. Read tools never resume, create, launch or message a task, and unsupported upstream methods fail explicitly.

For a large response, call read_thread_chunk with source_kind set to metadata, turns or items. Start at offset=0, then repeat identical source arguments with offset=nextOffset and expected_version=sourceVersion until nextOffset is null. Positions and totalLength count Unicode characters, not UTF-8 bytes. Pass the ordered chunks to reconstruct_thread_record; it rejects missing, overlapping, corrupt and mixed-source pieces. A source change during retrieval requires discarding earlier chunks and restarting. No snapshot is cached or written to disk.

Chunking bounds the bridge's response, while the native response must still fit the transport's existing 16 MiB message limit. Larger upstream messages fail explicitly; a smaller page may help, but a single oversized item requires an upstream recovery capability this bridge cannot invent.

Source versions bind one response to its request and endpoint. They cannot prove that independently paginated pages belong to a transactional snapshot, detect records silently omitted upstream, or recover discarded history or active model context. Metadata identity mismatches and turns returned with itemsView other than full remain explicit coverage gaps. Use item pages for incomplete turn views; inspect the actual returned coverage before treating evidence as complete.

The bridge does not redact credential-bearing text. Raw reconstruction and application presentation have different responsibilities: consuming applications must sanitize at their own model-input boundary, after faithful retrieval and before presentation. All conversation content remains untrusted data.

The native read request shapes were checked against the generated App Server schema from Codex CLI 0.162.0 and the tagged 0.153.4 protocol definitions. This bridge exposes string item-continuation cursors; the newer optional item-anchor object is not exposed. Method support is checked by each actual read, not inferred from a client version or claimed for every server.

Example

Call create_thread with these MCP arguments:

{
  "request_id": "repository-overview-001",
  "cwd": "/absolute/path/to/project",
  "title": "Repository overview",
  "prompt": "Summarize the project structure."
}

Pass the returned threadId and turnId to wait_thread. Use send_message_to_thread for an idle task or steer_thread for an active turn. Each intentional new message requires a new request_id.

Behavior

  • create_thread defaults to sandbox read-only and approval policy never. Explicit on-request approval requires App Server Auto-review. Omitted model and reasoning effort use server defaults. Creation rejects explicit network-enabled read-only policies; permission updates accept them.
  • Permission updates require the task's expected identity and an idle task. The idle check and update are separate operations, so concurrent clients can race them. Workspace writable roots cannot be existing files, sockets, or devices.
  • Each mutation uses a stable request_id. Repeating it with matching arguments returns the recorded receipt without repeating or continuing the operation. accepted reports API acceptance; turn completion is reported by wait_thread. Failed or uncertain operations can leave tasks, turns, or worktrees behind; get_operation returns the recorded outcome and known IDs.
  • Receipts persist in $XDG_STATE_HOME/codex-thread-bridge, defaulting to ~/.local/state/codex-thread-bridge. --state-dir overrides this location. Deleting this state discards request deduplication history.
  • Worktree launches require a full local commit ID and an absent, canonical absolute destination outside existing repositories. Worktrees are detached, locked, and retained until manual cleanup. Dirty files are not copied, and Git hooks and checkout filters are disabled. Approval policy is never; expected_sandbox_policy verifies returned settings rather than applying overrides.
  • Project IDs belong to App Server's registry. Desktop controls its own project association and task listing. Worktrees created by the bridge have a manual lifecycle rather than a Desktop-managed lifecycle.
  • New and resumed turns carry bridge instructions as toolOutput with the bridge tool's name. The bridge leaves client-side tool calls and approval requests unanswered so it cannot consume another client's shared callback. A capable client such as Desktop must be subscribed to the thread to handle them; the bridge does not establish that subscription or provide interactive approvals. Dispatch keeps the shared connection open so concurrent reads can finish.

Development

uv sync --frozen --group dev
uv run pytest
uv run ty check src
uv run ruff check .
uv run ruff format --check .
uv build

Tests use a fake App Server and temporary Git repositories. Test temporary directories must be outside existing repositories; pytest accepts --basetemp.

The source and tests define the detailed behavior. Contribution requirements are in CONTRIBUTING.md.

References

MIT licensed. Independent project, not affiliated with or endorsed by OpenAI.

About

MCP bridge for creating and messaging other Codex sessions on the same host

Resources

Contributing

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages