The write tools return an id and hand the caller guidance fields whose whole purpose is to stop an agent from queueing a replacement while the first attempt is still alive — the same request id after a timeout returns the original operation instead of a second turn. The older direct-write tools remain for compatibility and point at the durable path instead, so fresh wiring can ignore all three. Repairs run allowlisted and dry-run by default, and the diagnostic tools collect and analyse without executing anything, which keeps the recovery path readable before it becomes destructive.
A control plane in front of Codex Desktop and codex-app-server: a durable operation queue, plan and review workflows, and diagnostics over chats, turns and app-server state, backed by a local SQLite record.
- Durable submission: a task returns an operationId immediately, and status carries nextRecommendedAction, pollRecommended, queueState and agentGuidance so a caller waits instead of firing a second attempt
- Retry safety by design — the same client_request_id returns the existing operation rather than starting another Codex turn, and an identical active prompt is detected as a duplicate
- Plan Mode as a tracked workflow: start it, poll until a plan is ready, approve it, and have execution queued under the same workflowId
- Review workflows scoped to a base branch, a commit or uncommitted changes, followed through to a final report, with a structured report available through an output schema
- Pending approvals, input requests and elicitations listed and answered, so a turn that stopped for a human is resumed rather than restarted
- Chat discovery across registry, hook history, transcripts and cached state, with search for recovering lost ids and bounded reads that will not pull a whole thread into context
- Health split into the surfaces that fail separately: worker heartbeat, durable queue state, active turn counts with scheduler locks, and app-server status read without starting it
- A diagnostic path that collects a scoped snapshot, analyses it, and runs allowlisted repairs that dry-run first and stop when the loop guard says stop
Python 3.11 or newer and Codex Desktop with codex-app-server on the same machine — Windows is the fully supported target, with Linux and macOS at protocol-level checks. CODEX_HOME and a state database path are the two settings that matter, and the admin helper generates the client config, installs the Codex hooks and runs a smoke test. Write defaults are conservative: read-only sandbox and on-request approval, except Plan Mode, which is raised to workspace-write and reports the adjustment. It is built for a trusted local machine and should not be exposed as a network service. Apache-2.0.
One command — uvx codex-control-plane-mcp