acodex

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 | CLI | Support | Contributing

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.

State-changing tool calls mutate the live Codex desktop app. Use acodex tools call <tool> --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. Agent-specific guidance lives in AGENTS.md.

License

acodex is released under the MIT License.

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