Acodex

acodex

[](LICENSE)

Local MCP automation for the Codex desktop app.

acodex gives scripts, tools, and agents a local bridge into a running Codex desktop session. It can relaunch Codex with a Chrome DevTools Protocol (CDP) port, run a managed HTTP/MCP server, and call the live codex_app.* tools that your Codex desktop build exposes.

[Quick Start](#quick-start) | [CLI](#cli) | [Support](#support) | [Contributing](CONTRIBUTING.md)

Why acodex

• Live Codex desktop access. Inspect and call the tools exposed by the

running desktop renderer without writing CDP plumbing.

• MCP-compatible local server. Expose Codex desktop tools at /mcp for

local automation clients.

• Practical CLI workflow. Check configuration, relaunch Codex with CDP,

manage the bridge server, and call tools from a terminal.

Quick Start

Prerequisites:

• Python 3.10 or newer.
• uv; see the official install guide.
• macOS with Codex.app installed. The relaunch flow expects

/Applications/Codex.app by default; set ACODEX_CODEX_APP_PATH if yours is elsewhere.

Install the CLI:

uv tool install acodex

Initialize config, launch Codex with CDP, and start the local bridge:

acodex config init
acodex codex relaunch --yes
acodex server start

acodex codex relaunch --yes starts or restarts Codex so acodex can reach the default CDP endpoint, http://127.0.0.1:45217.

For deeper diagnostics after the server is running, use acodex doctor --deep.

List and call Codex desktop tools:

acodex tools list
acodex tools call codex_app.list_threads --limit 1

Stop the managed bridge when you are done:

acodex server stop

CLI

Common commands:

acodex config path
acodex config show
acodex doctor --deep
acodex codex status
acodex codex relaunch --yes
acodex server start
acodex server status
acodex server logs --tail 50
acodex tools list --json
acodex tools call codex_app.list_threads --help

Tool calls use the MCP schema property names. Pass simple top-level arguments as flags, or use JSON for nested input:

acodex tools call codex_app.list_threads --limit=5
acodex tools call --args-json '{"limit":5}' codex_app.list_threads
acodex tools call --output json codex_app.list_threads --limit 5

Configuration

acodex reads JSON config from ~/.acodex/config.json by default. Set ACODEX_CONFIG to use a different file. Use acodex config path and acodex config show to inspect the active path and effective values.

Essential local endpoints:

• Codex CDP: http://127.0.0.1:45217
• Managed server health: http://127.0.0.1:45218/healthz
• MCP endpoint: http://127.0.0.1:45218/mcp

Configuration precedence and the full defaults matrix live in [CONTRIBUTING.md](CONTRIBUTING.md).

State-changing tool calls mutate the live Codex desktop app. Use acodex tools call --help before calling unfamiliar tools.

Support

When setup fails, start with the built-in diagnostics and managed server logs:

acodex doctor
acodex server logs --tail 50

If the issue continues, open a GitHub issue with what you tried, what happened, your OS and Python version, your acodex source branch or commit, your Codex desktop/CDP setup, and relevant command output with secrets removed.

Contributing

Contributor setup, architecture notes, quality gates, and documentation rules live in [CONTRIBUTING.md](CONTRIBUTING.md). Agent-specific guidance lives in [AGENTS.md](AGENTS.md).

License

acodex is released under the [MIT License](LICENSE).

acodex is independently maintained and is not affiliated with, sponsored by, or endorsed by OpenAI.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: maksimzayats
• Source: maksimzayats/acodex
• License: MIT
• Homepage: http://docs.acodex.dev/

Install and usage instructions live in the source repository linked above.