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.
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-bridgeThe 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-reloadThe 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.
| 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.
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.
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.
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.
create_threaddefaults to sandboxread-onlyand approval policynever. Expliciton-requestapproval 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.acceptedreports API acceptance; turn completion is reported bywait_thread. Failed or uncertain operations can leave tasks, turns, or worktrees behind;get_operationreturns the recorded outcome and known IDs. - Receipts persist in
$XDG_STATE_HOME/codex-thread-bridge, defaulting to~/.local/state/codex-thread-bridge.--state-diroverrides 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_policyverifies 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
toolOutputwith 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.
uv sync --frozen --group dev
uv run pytest
uv run ty check src
uv run ruff check .
uv run ruff format --check .
uv buildTests 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.
- Codex App Server API documentation
- RPC method definitions
- Request, response, and notification types
- App Server implementation
- Shared callback routing in Codex 0.153.4
MIT licensed. Independent project, not affiliated with or endorsed by OpenAI.