codex_adopt_workflow_plan
Adopt a valid newer Plan Mode candidate already present in the workflow thread. Use this only when status or diagnostics reports an adoptable plan. Next poll codex_get_workflow_status.
LABSCO SUMMARY
It turns a Codex run from something you watch into something you poll.
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.
What it is
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.
What you get
- 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
Requirements
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.
Setup effort
One command — uvx codex-control-plane-mcp
USE CASES
01
Starting a long refactor you do not intend to sit and watch
Find the project, check it is safe to write to, then queue the work and poll the operation id it returns. The status response carries the recommendation about whether to wait, which is what keeps a stalled-looking run from being duplicated.
02
Seeing the plan before any code moves
Plan Mode runs as its own workflow: it returns a workflow id straight away, the status call reports when a plan is ready, and execution is only queued once the plan is approved under the same id.
03
Unblocking a turn that stopped to ask permission
When status reports a pending interaction, the approval or input request is listed with its id and answered directly, and the owning turn is then polled until it moves again.
04
Getting a code review on the branch before you open the PR
Start the review against a base branch, a commit or the uncommitted changes, then poll until the final report is there. The review itself writes no files.
05
Working out why nothing is running
Queue pressure, scheduler locks and worker health fail separately, so they are read separately before anything is restarted. Diagnostics collects the evidence and the analysis step turns it into a next action rather than a retry.
06
Stopping work that has gone the wrong way
A running turn is interrupted by its ids or through the operation that owns it, and status is polled until terminal evidence appears. Where the fault is in the control plane itself, repairs run from an allowlist and dry-run first.
38 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
codex_analyze_issue
Analyze scoped diagnostics and recommend safe next actions. Use this after collect_diagnostics or when a human needs a compact root-cause summary. Follow agentGuidance rather than inventing retries.
codex_answer_pending_interaction
Answer one pending Codex interaction so a turn can continue. Use this only for a listed interaction id. Next poll the owning operation, turn, or workflow.
codex_approve_plan
Approve the latest ready plan and queue execution. Use this after codex_get_workflow_status reports plan_ready and a valid latestPlan. Next poll codex_get_workflow_status with the same workflowId.
codex_archive_thread
Archive a known Codex thread through the worker or app-server command lane. Use this only when the thread has no active work. Next poll codex_get_worker_command_status when commandId is returned.
codex_collect_diagnostics
Collect a scoped diagnostic snapshot with compact evidence and guidance. Use this before repair when status reports failed, stale, orphaned, or degraded state. It does not execute repairs.
codex_execute_plan
Compatibility write for executing an approved plan. Prefer codex_approve_plan or codex_submit_task with operation_type='execute_plan'. In client mode this delegates to durable workflow execution.
codex_get_agent_contract
Read the machine-readable agent guide for this MCP server. Use this when tools/list metadata was unavailable or when a client wants the full contract examples. It is passive and the next normal startup call is codex_health_summary.
codex_get_app_server_status
Read MCP-owned app-server status without starting it. Use this with worker, queue, and concurrency status to verify active work. In client mode prefer worker-derived active turns over local guesses.
codex_get_chat
Read bounded chat content from hook history, transcripts, or legacy fallback. Use this for context recovery and final report inspection. It is not a write path and should not trigger retries.
codex_get_chat_status
Read lightweight chat status and safe previews. Use this to inspect a known thread without starting live work. Next call codex_get_chat for content or codex_submit_task for a new operation.
codex_get_concurrency_status
Read active turn counts and scheduler resource locks. Use this with queue status when diagnosing parallel work. Active locks are not a retry instruction by themselves.
codex_get_diagnostic_logs
Read redacted diagnostic log and app-server audit entries with filters. Use this only for targeted troubleshooting, not normal polling. Raw payload mode is for local audit and remains secret-redacted.
codex_get_operation_status
Poll a durable operation from storage. Use this after codex_submit_task and follow nextRecommendedAction, pollRecommended, queueState, and agentGuidance. Never create a new retry while an existing operation is active.
codex_get_queue_status
Read durable queue state, queued reasons, running operations, and worker assignment. Use this to understand slot pressure or lock waits. Do not retry when queued work already exists.
codex_get_runtime_capabilities
Read compact runtime capabilities, models, permissions, hooks, account state, and supported methods. Use this after health or before new work. In client mode refresh queues a worker command.
codex_get_thread_compaction_status
Poll a thread compaction action. Use this with actionId from codex_start_thread_compaction. It is passive and should return a bounded status or guidance.
codex_get_turn_status
Read one tracked Codex turn, including safe progress and terminal evidence. Use this when you have threadId and turnId. Do not infer stalled state from row age alone.
codex_get_worker_command_status
Poll a worker command created by a client-mode control action. Use this for archive, unarchive, compaction, restart, runtime refresh, and delegated lifecycle commands. Keep include_result=false unless the result is needed.
codex_get_worker_status
Read central worker heartbeat and execution-mode state without starting app-server. Use this when health or queue guidance says inspect_worker_health. Next compare with queue and concurrency status.
codex_get_workflow_status
Poll workflow state from storage by default. Use this for Plan Mode, execution, and review workflows. Follow nextRecommendedAction and do not create replacement work unless guidance tells you to.
codex_health_summary
Read compact MCP readiness and contract metadata. Use this first on startup, reconnect, and after MCP restart. Next inspect runtime capabilities or follow agentGuidance if health is degraded.
codex_interrupt_turn
Interrupt a running Codex turn by direct ids or durable operation/workflow context. Use this for explicit cancellation or stop conditions. Next poll status until terminal evidence is visible.
codex_list_active_chats
List chats that look active from tracked, hook, transcript, or cached evidence. Use this for operator inspection, not for creating retries. Next call codex_get_turn_status or codex_get_operation_status when ids are available.
codex_list_pending_interactions
List pending approvals, input requests, or elicitation requests. Use this when operation or workflow status reports pending interaction. Next answer with codex_answer_pending_interaction or ask a human.
codex_list_project_chats
List chats for one project from the bounded read model. Use this to find existing threads before continuation or review. Next call codex_get_chat_status, codex_get_chat, or codex_submit_task.
codex_list_projects
List known Codex projects from registry, hook history, transcripts, and cached Codex state. Use this before preflight or submit when you need a project reference; later tools accept projectId, project name, or project path and return canonical projectId. Next call codex_preflight_project_run for a concrete project.
codex_preflight_project_run
Check whether a project is safe to use before a Codex run. Use this after project discovery and before write operations. Do not treat skipped worker-managed account checks as hard auth failures.
codex_repair_issue
Run an allowlisted repair action with dry-run first by default. Use this only when diagnostics or agentGuidance recommends a specific action. Stop when loopGuard.allowed is false.
codex_restart_app_server
Restart only the MCP-owned codex-app-server subprocess. Use this only when guidance recommends restart and active work is absent or explicitly handled. In client mode this delegates to the worker command lane.
codex_search_chats
Search chat history through the MCP-owned index and safe fallback sources. Use this for discovery or recovery when ids were lost. Do not use search results as proof that a turn is still active.
codex_send_message
Compatibility write for sending a message to an existing Codex thread. Prefer codex_submit_task with operation_type='send_message' for durable long work. In client mode this delegates to the durable queue.
codex_start_chat
Compatibility write for starting a new Codex chat. Prefer codex_submit_task with operation_type='start_chat' for durable long work. In client mode this delegates to the durable queue.
codex_start_plan_workflow
Start a durable Plan Mode workflow and return workflowId immediately. Use this when a plan must be prepared before implementation. Next poll codex_get_workflow_status, then call codex_approve_plan when latestPlan is ready.
codex_start_review_workflow
Start a durable Codex review workflow and return workflowId immediately. Use this for code review tasks. Next poll codex_get_workflow_status for progress and final report.
codex_start_thread_compaction
Start context compaction for a known thread and return actionId. Use this after active work is terminal. Next poll codex_get_thread_compaction_status.
codex_submit_task
Queue a durable Codex write operation and return operationId immediately. For project-scoped work, pass project_id from codex_list_projects.projectId; project name or project path are accepted aliases and MCP stores the canonical projectId. Always pass client_request_id and poll codex_get_operation_status.
codex_unarchive_thread
Unarchive a known Codex thread through the worker or app-server command lane. Use this only for an existing archived thread. Next poll codex_get_worker_command_status when commandId is returned.
BEFORE YOU INSTALL
What to know first
Tools you get
38 tools when we connected. Seven tools, including codex_get_worker_status and codex_preflight_project_run, are missing from the main tool list and documented only in the API contract and worker-mode sections.
Requires
uvx on PATH
CONTEXT COST
Moderate Standing cost
Rated by the size of the 38 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Add the block to your client, or run the command directly.
Server setup
Configuration file
JSON
{
"mcpServers": {
"codex-control-plane-mcp": {
"command": "uvx",
"args": [
"codex-control-plane-mcp"
]
}
}
}uvx
TERMINAL
uvx codex-control-plane-mcp
