CoS Codex Bridge

Your Chief of Staff. Now in charge of Codex, too.

A local MCP server that lets a Chief of Staff client find Codex tasks, create project work, deliver whole prompts, follow progress and continue the same conversation. Free MIT core. No bridge subscription or checkout. Your existing Codex access is required for real execution.

v0.1.0 preview. Normal local MCP: install, connect your client, then use the bridge_* tools. No daemon or Desktop-owner adapter installation is required. Core workflow has passed owner field testing on macOS. Desktop-owned paused-queue recovery is a known v0.1 limitation, deferred from this release. Sidebar rendering on newer Codex Desktop versions is not certified; check the compatibility table before relying on it. A queued receipt is never proof that work started.

Easiest setup: give this link to your local assistant

Open the repository and installation instructions. An assistant with local terminal access can install it for you. A browser-only or cloud-only chat cannot install software on your computer.

Copy this installation request to your Chief of Staff:

Install CoS Codex Bridge from https://github.com/AV-Labs-Co/cos-codex-bridge. Read the README and SECURITY.md first. Use only a project folder I approve, keep read-only defaults, and preserve existing client configuration. Follow the installer instructions, run doctor, and connect the generated stdio MCP entry to my local client. Tell me what passed and what still needs setup. Wait for my first task before submitting any work. Do not publish or deploy anything.

You can also download the source archive from Releases, extract it and follow the steps below. Git cloning makes later updates easier. No npm package or hosted endpoint is required.

Related MCP server: ChatGPT Codex Bridge

Install

Requires Node.js 22+, npm, Codex CLI authenticated locally, and a local client supporting stdio MCP. Desktop registration additionally requires Codex Desktop on macOS.

git clone https://github.com/AV-Labs-Co/cos-codex-bridge.git
cd cos-codex-bridge
npm ci
npm test
node scripts/install.mjs --root /absolute/path/to/your/projects

The installer writes a private config, launcher and MCP snippet under ~/.local/share/cos-codex-bridge. Keep the checkout in place. Default execution is read-only; use --write only for approved project edits. Choose specific project roots, never your entire home directory. Add --codex /absolute/path/to/codex if Codex is not on PATH. See installer and upgrade steps.

~/.local/share/cos-codex-bridge/cos-codex-bridge doctor

Check codexAvailable, mode, sandbox and roots. Doctor reports capabilities and installation health, not authentication success or visual verification. For a model-free demo, install into a separate prefix with --demo.

Paste the generated mcp-client.json into your client's MCP configuration. Equivalent shape:

{"mcpServers":{"cos-codex-bridge":{"command":"/absolute/path/to/node","args":["/absolute/path/to/cos-codex-bridge/dist/cli.js","--config","/absolute/path/to/config.json","mcp"]}}}

A complete handoff

Tell your Chief of Staff: “Find my app project, send this entire implementation brief to Codex, monitor it, then continue that same task with the review findings.”

1. Resolve the exact project and task with bridge_projects and bridge_sessions.

2. Create a directory if needed, then register it. A directory alone is not a Desktop project.

3. Call bridge_submit with project, the whole prompt, and a stable requestId. Include threadId for follow-ups.

4. Poll bridge_receipt. Verify hashes, task ID and eventual completion. Handle clarification with bridge_answer.

5. Use bridge_session_manage to rename, assign or pin the task. Stored metadata and visible Desktop rendering are separate proofs.

A successful model completion does not independently prove that generated code works. Review and test the result.

Ten tools, twelve features and one known limitation

Known limitation (uncommon): If a session already has an active writer and a steering prompt is sent, the prompt waits for a natural pause/stopping point. On a long autonomous run, the only human intervention needed is pressing Steer in that case.

See the v1 capability contract and verification matrix.

Busy tasks, steering and interruption recovery

Direct submission defaults to SESSION_BUSY when another writer owns the task. To opt into the existing Desktop execution policy, use onBusy:"queue" and acceptDesktopPolicy:true. delivery:"desktop-queue" explicitly queues to an existing task. These paths use Codex's first-party queue API, the equivalent of codex queue, and preserve separate text inputs and stable client message IDs.

Receipts distinguish busy, queued, steered, delivered, completed, blocked and uncertain. thread/queue/start recovery has passed a local live test with the writer available. Desktop-owned paused recovery is deferred for v0.1; it may require a human Steer click. bridge_steer retries the exact saved item when the writer is available, including an existing CLI-created item adopted by its queue ID. bridge_sessions with includeQueue:true exposes pending IDs and inferred needs-steer state. It never silently forks or treats queue disappearance as delivery. See queue semantics.

Security defaults

Default-deny realpath allowlists, read-only direct execution, private local receipts, bounded UTF-8 input, explicit project/task matching and no implicit cloud endpoint. Prompts and artifacts are stored locally in plaintext for receipt integrity; do not treat them as encrypted storage.

Direct workers disable inherited connectors and deny permission approvals. Desktop queue is a separate, explicit policy boundary: it uses the existing task's permissions and tools. The bridge cannot enforce a narrower sandbox inside that already-running task. No automatic store submission, social posting or publication is authorized. See SECURITY.md.

Client matrix

Native project assignment is supported through the installed experimental App Server API. An optional, version-gated legacy Desktop assignment adapter has backup and race checks; it is off by default and remains experimental.

Community

This project focuses on reliable Chief of Staff handoffs rather than a universal superiority claim. Other Codex MCP projects solve useful adjacent workflows. We do not claim “most advanced,” all-account control or blanket autonomy.

Star it to follow development, fork it for your client, and report reproducible failures with redacted version, state and error details. Never post full private prompts or credentials. MIT License.