# codex-control-plane-mcp

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.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 100 installs · ★ 9 repo stars
- Author: reason-machines
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/reason-machines/mcp-skills/tree/HEAD/skills/codex-control-plane-mcp/SKILL.md
- Updated: 2026-10-09
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/codex-control-plane-mcp

## What it 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.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add reason-machines/mcp-skills --skill codex-control-plane-mcp -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/codex-control-plane-mcp/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/codex-control-plane-mcp/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add reason-machines/mcp-skills --skill codex-control-plane-mcp -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/codex-control-plane-mcp/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add reason-machines/mcp-skills --skill codex-control-plane-mcp -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/codex-control-plane-mcp/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install reason-machines/mcp-skills skills/codex-control-plane-mcp
```

2. **Manually: put the files in place**
- File: `.github/skills/codex-control-plane-mcp/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add reason-machines/mcp-skills --skill codex-control-plane-mcp -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/reason-machines/mcp-skills --path skills/codex-control-plane-mcp
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/codex-control-plane-mcp/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add reason-machines/mcp-skills --skill codex-control-plane-mcp -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/reason-machines/mcp-skills/tree/HEAD/skills/codex-control-plane-mcp/SKILL.md

## When to use it
- 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
- 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_task` and return the `operationId`
- Start a Plan Mode workflow for MySQL to PostgreSQL migration and wait for approval

## Similar
- [Codex Control Plane MCP](https://affpapa.org/en/nevibecode/mcp/codex-control-plane-mcp.md) — MCP server · ★ 114 repo stars
- [ThinkNEO Control Plane](https://affpapa.org/en/nevibecode/mcp/thinkneo-control-plane.md) — MCP server · ★ 3 repo stars
- [Control Plane](https://affpapa.org/en/nevibecode/mcp/control-plane.md) — MCP server · ★ 11 repo stars
- [Desktop Control](https://affpapa.org/en/nevibecode/skills/desktop-control.md) — skill · 4000 installs
- [design-control-loop](https://affpapa.org/en/nevibecode/skills/design-control-loop.md) — skill · 1800 installs
- [droid-control](https://affpapa.org/en/nevibecode/skills/droid-control.md) — skill · 118 installs

From the same set: [reason-machines/mcp-skills](https://affpapa.org/en/nevibecode/by/reason-machines/mcp-skills.md) — 98 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
