codex-control-plane-mcp — Claude Code skill: install, how it works
codex-control-plane-mcp is a Claude Code and Codex skill that turns Codex Desktop into a durable worker for long tasks via an MCP server.
no license 100 installs ★ 9 updated 2026-10-09
npx skills add reason-machines/mcp-skills --skill codex-control-plane-mcp -a claude-codeWhat codex-control-plane-mcp does
Instead of blocking multi-hour calls, the skill provides an async model: submit a task, get an operationId, poll until done. The same client_request_id returns the existing operation rather than spawning a duplicate. For Plan Mode, it starts a plan, waits for approval, executes, and fetches the final report. Uses a SQLite database to persist operations, workflows, hooks, and diagnostics.
Requires Python (for pipx or uvx) and environment variables CODEX_MCP_STATE_DB and CODEX_PROJECTS_ROOT. After installing hooks with codex-control-plane-mcp-hooks install, restart Codex Desktop. MCP client config goes into a JSON block in claude_desktop_config.json or the equivalent for your platform.
Built for automation that must not break on retries or lose state: lengthy refactors, database migrations, batch file processing. Without SQLite and the CODEX_MCP_STATE_DB variable, the server will not start.
What it helps with
- run a long Codex Desktop task without blocking
- retry a Codex request without creating duplicate operations
- manage Plan Mode: approve a plan and wait for execution
- track operation or workflow status by ID
- persist operation and hook history in SQLite
Example prompts for the agent
- Set up the MCP server for long Codex Desktop tasks with a database at
./state/codex-mcp-state.sqlite3 - Submit an auth module refactor via
codex_submit_taskand return theoperationId - Start a Plan Mode workflow for MySQL to PostgreSQL migration and wait for approval
How to install codex-control-plane-mcp
1Skills CLI (Vercel)
npx skills add reason-machines/mcp-skills --skill codex-control-plane-mcp -a claude-code2Manually: put the files in place
~/.claude/skills/codex-control-plane-mcp/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/codex-control-plane-mcp/
1Skills CLI (Vercel)
npx skills add reason-machines/mcp-skills --skill codex-control-plane-mcp -a codex2Manually: put the files in place
.agents/skills/codex-control-plane-mcp/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add reason-machines/mcp-skills --skill codex-control-plane-mcp -a cursor2Manually: put the files in place
.cursor/skills/codex-control-plane-mcp/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install reason-machines/mcp-skills skills/codex-control-plane-mcp2Manually: put the files in place
.github/skills/codex-control-plane-mcp/SKILL.md1Skills CLI (Vercel)
npx skills add reason-machines/mcp-skills --skill codex-control-plane-mcp -a gemini-cli2Platform CLI
gemini skills install https://github.com/reason-machines/mcp-skills --path skills/codex-control-plane-mcpManually: put the files in place
.devin/skills/codex-control-plane-mcp/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add reason-machines/mcp-skills --skill codex-control-plane-mcp -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about codex-control-plane-mcp
How do I install codex-control-plane-mcp in Claude Code?
Run npx skills add reason-machines/mcp-skills --skill codex-control-plane-mcp -a claude-code, then open ~/.claude/skills/codex-control-plane-mcp/SKILL.md for MCP client setup instructions.
What does codex-control-plane-mcp do?
Turns Codex Desktop into a durable worker: submit a task asynchronously, get an ID, poll for status, retry without duplicates. Supports Plan Mode with approval and stores history in SQLite.
What does the skill need to run?
Python, pipx or uvx, environment variables CODEX_MCP_STATE_DB and CODEX_PROJECTS_ROOT. After installing hooks with codex-control-plane-mcp-hooks install, restart Codex Desktop.