Skip to content
Back to search

codex-control-plane-mcp

Durable MCP control plane for long-running Codex Desktop tasks

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/aresyn--codex-control-plane-mcp/badge.svg)](/listings/aresyn--codex-control-plane-mcp)

HTML

<a href="/listings/aresyn--codex-control-plane-mcp"><img src="/api/listings/aresyn--codex-control-plane-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Recommended:

pipx install codex-control-plane-mcp

Or run directly:

uvx codex-control-plane-mcp

From GitHub:

python -m pip install "codex-control-plane-mcp @ git+https://github.com/aresyn/codex-control-plane-mcp.git"

For local development:

git clone https://github.com/aresyn/codex-control-plane-mcp.git
cd codex-control-plane-mcp
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
python -m pytest -q

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 808 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. [![MseeP.ai Security Assessment Badge](https://mseep.net/pr/aresyn-codex-control-plane-mcp-badge.png)](https://mseep.ai/app/aresyn-codex-control-plane-mcp)
  2. # Codex Control Plane MCP
  3. English | [Русский](README.ru.md)
  4. <!-- mcp-name: io.github.aresyn/codex-control-plane-mcp -->
  5. [![CI](https://github.com/aresyn/codex-control-plane-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/aresyn/codex-control-plane-mcp/actions/workflows/ci.yml)
  6. [![PyPI](https://img.shields.io/pypi/v/codex-control-plane-mcp.svg)](https://pypi.org/project/codex-control-plane-mcp/)
  7. [![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
  8. [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
  9. [![MCP](https://img.shields.io/badge/MCP-stdio-green.svg)](docs/API_CONTRACT.md)
  10. <p align="center">
  11. <img src="https://raw.githubusercontent.com/aresyn/codex-control-plane-mcp/main/assets/repo_image.png" alt="Codex Control Plane MCP" width="100%">
  12. </p>
  13. Reliable Codex Desktop automation for long tasks.
  14. `codex-control-plane-mcp` turns Codex Desktop and `codex-app-server` into a
  15. durable worker that an MCP client can drive safely. Send a task, get an
  16. `operationId` or `workflowId` right away, poll until the work finishes, approve
  17. Plan Mode when needed, then read the final report.
  18. The server handles the awkward parts that thin wrappers usually leave to the
  19. caller: app-server startup, thread and turn creation, retry safety, duplicate
  20. prompt protection, Plan Mode, approvals, local history, diagnostics, and repair.
  21. OpenClaw and Hermes are first-class clients, but the server is useful for any
  22. local orchestrator that needs Codex Desktop to do long-running work without
  23. holding one MCP call open for hours.
  24. ## The short version
  25. ```text
  26. MCP client / orchestrator
  27. -> submit a task or start a Plan Mode workflow
  28. <- receive operationId or workflowId immediately
  29. -> poll status
  30. -> answer approvals or approve the plan
  31. <- read final report, diagnostics, threadId, and turnId
  32. ```
  33. That gives you a simple contract:
  34. - no multi-hour MCP calls;
  35. - no duplicate Codex turns after a client retry;
  36. - no blind fire-and-forget task submission;
  37. - a local SQLite record of operations, workflows, turns, hooks, and diagnostics.
  38. ## Why not just call Codex directly?
  39. | Capability | Thin Codex wrapper | Codex Control Plane MCP |
  40. |---|---:|---:|
  41. | Multi-hour tasks | blocking / fragile | durable async operation |
  42. | Client timeout recovery | manual | retry-safe `client_request_id` |
  43. | Duplicate turn protection | no | active prompt detection |
  44. | Plan Mode workflow | human / manual | pollable workflow state |
  45. | Approvals and questions | blocking / opaque | pending interactions API |
  46. | Restart recovery | ad hoc | persisted operation state |
  47. | Diagnostics | logs only | health, diagnostics, repair tools |
  48. For a more detailed decision guide, see
  49. [docs/THIN_WRAPPERS.md](docs/THIN_WRAPPERS.md).
  50. ## Current support
  51. - Full live target: Windows with Codex Desktop and `codex-app-server`.
  52. - Linux and macOS: protocol-only checks for now.
  53. - Local-first: not intended to be exposed as a public network service.
  54. ## Security model
  55. This is a local-first control plane for trusted Codex Desktop environments.
  56. Do not expose it as a network service without authentication.
  57. Recommended first-run posture:
  58. - use `read-only` for untrusted repositories;
  59. - use `on-request` approval when testing new workflows;
  60. - Plan Mode never runs with a `read-only` sandbox. If a caller requests
  61. `read-only`, MCP raises that turn to `workspace-write` and reports the
  62. adjustment in status output;
  63. - keep `state/`, `logs/`, `.env`, and `.codex/` private.
  64. ## What it does
  65. - Durable async queue for Codex write operations.
  66. - Retry-safe `client_request_id` handling.
  67. - Active duplicate prompt detection.
  68. - SQLite leases and heartbeats for competing MCP processes.
  69. - Recovery after MCP restart during `thread/start` or `turn/start`.
  70. - Durable `turn/steer` for adding context to an active turn without creating a second turn.
  71. - Durable `thread/fork` for branching an existing thread, with or without an initial message.
  72. - Plan Mode workflows: start plan, poll, approve, execute, read final report.
  73. - Plan Mode runtime floor: `workspace-write`, with `runtimePolicyAdjusted` in
  74. status when MCP raises a `read-only` request.
  75. - Code review workflows through app-server `review/start`, with polling and final report capture.
  76. - Structured final reports with `output_schema`.
  77. - Thread lifecycle tools for archive, unarchive, and pollable compaction.
  78. - Workflow goal sync with Codex Desktop thread goals.
  79. - Image and local image inputs for turns that start through `turn/start`.
  80. - Pending approvals and questions exposed as pollable MCP state.
  81. - Turn interrupts by `threadId`/`turnId`, `operationId`, or `workflowId`.
  82. - Runtime inventory for models, permission profiles, sandbox readiness, hooks, skills, provider features, account status, usage bands, rate-limit state, and supported app-server methods.
  83. - Health checks, diagnostics, issue analysis, and dry-run repairs.
  84. - MCP-owned hook history in SQLite for search, summaries, and fallback reads.
  85. - Redacted app-server progress journal for deltas, warnings, model reroutes, and token usage.
  86. - Structured MCP errors that automation code can branch on.
  87. Write and control actions go through `codex-app-server`. The server does not
  88. mutate Codex internal SQLite databases or transcript files.
  89. ## Install
  90. Recommended:
  91. ```powershell
  92. pipx install codex-control-plane-mcp
  93. ```
  94. Or run directly:
  95. ```powershell
  96. uvx codex-control-plane-mcp
  97. ```
  98. From GitHub:
  99. ```powershell
  100. python -m pip install "codex-control-plane-mcp @ git+https://github.com/aresyn/codex-control-plane-mcp.git"
  101. ```
  102. For local development:
  103. ```powershell
  104. git clone https://github.com/aresyn/codex-control-plane-mcp.git
  105. cd codex-control-plane-mcp
  106. py -m venv .venv
  107. .\.venv\Scripts\Activate.ps1
  108. python -m pip install -e ".[dev]"
  109. python -m pytest -q
  110. ```
  111. ## MCP client config
  112. After installation, generate a config:
  113. ```powershell
  114. codex-control-plane-mcp-admin init --state-db .\state\codex-mcp-state.sqlite3 --projects-root C:\Users\you\Projects
  115. ```
  116. Minimal stdio entry:
  117. ```json
  118. {
  119. "mcpServers": {
  120. "codex-control-plane": {
  121. "command": "codex-control-plane-mcp",
  122. "args": []
  123. }
  124. }
  125. }
  126. ```
  127. More copy-paste examples for Claude Desktop, Cursor, VS Code-style MCP clients,
  128. local checkouts, installed packages, and central worker mode are available in
  129. [`examples/mcp-client-configs.md`](examples/mcp-client-configs.md).
  130. Run the MCP stdio server:
  131. ```powershell
  132. codex-control-plane-mcp
  133. ```
  134. Or run it as a module:
  135. ```powershell
  136. py -m codex_control_plane_mcp.server
  137. ```
  138. The old `openclaw-codex-mcp` and `openclaw-codex-mcp-hooks` commands remain as
  139. compatibility aliases for one release line.
  140. ## Central worker mode
  141. The default `inline` mode is still the simplest setup: one MCP process can submit
  142. and execute operations. For OpenClaw, Hermes, or any setup with several MCP
  143. clients, use a central worker instead.
  144. Recommended local shape:
  145. - every MCP client uses the same `CODEX_HOME` and `CODEX_MCP_STATE_DB`;
  146. - OpenClaw gateway entries run with `CODEX_MCP_EXECUTION_MODE=client`;
  147. - one long-running `codex-control-plane-mcp-worker` process owns
  148. `codex-app-server`, leases, queue slots, and resource locks;
  149. - clients call `codex_submit_task`, then poll status. They do not execute queued
  150. operations themselves.
  151. Worker command:
  152. ```powershell
  153. $env:CODEX_MCP_EXECUTION_MODE = "worker"
  154. codex-control-plane-mcp-worker
  155. ```
  156. Safe observation mode, useful before switching a live gateway:
  157. ```powershell
  158. codex-control-plane-mcp-worker --observe
  159. ```
  160. Concurrency defaults:
  161. ```powershell
  162. CODEX_MCP_MAX_ACTIVE_TURNS_GLOBAL=4
  163. CODEX_MCP_MAX_ACTIVE_TURNS_PER_PROJECT=3
  164. CODEX_MCP_MAX_ACTIVE_TURNS_PER_AGENT=3
  165. CODEX_MCP_MAX_ACTIVE_TURNS_PER_THREAD=1
  166. CODEX_MCP_MAX_ACTIVE_WRITE_TURNS_PER_PROJECT=1
  167. CODEX_MCP_MAX_APP_SERVER_PENDING_REQUESTS=8
  168. ```
  169. For write turns in the same project, pass `resource_keys` to
  170. `codex_submit_task`. Without them, `workspace-write` and `danger-full-access`
  171. turns take a broad project write lock. With disjoint keys, the worker may run
  172. several write turns in parallel.
  173. New status tools:
  174. - `codex_get_worker_status`
  175. - `codex_get_queue_status`
  176. - `codex_get_concurrency_status`
  177. - `codex_get_worker_command_status`
  178. `codex_get_operation_status` also returns `queueState`, `workerState`,
  179. `slotState`, and `resourceLockState`. A running turn has
  180. `slotState.claimed=true` and a `slotClaim` with the worker id, slot type, and
  181. claim time. `codex_get_queue_status` separates queued work from running turn
  182. operations, auxiliary operations, active turn slots, and lock conflicts.
  183. When a workflow is waiting for capacity, `codex_get_workflow_status` mirrors the
  184. nested operation queue state in `workflowOperationQueueState`. Use
  185. `nextRecommendedAction="wait_for_worker_slot"` for slot pressure and
  186. `nextRecommendedAction="wait_for_resource_lock"` for write lock conflicts. Do
  187. not create another operation for the same work while either action is returned.
  188. ## First setup
  189. The admin helper can generate a fuller client config, install hooks, and run a
  190. protocol smoke:
  191. ```powershell
  192. codex-control-plane-mcp-admin init --state-db .\state\codex-mcp-state.sqlite3 --projects-root C:\Users\you\Projects
  193. ```
  194. The command prints a JSON block you can copy into an MCP client config. It does
  195. not print secrets or private prompts.
  196. You can also install only the Codex hooks:
  197. ```powershell
  198. codex-control-plane-mcp-hooks install --state-db .\state\codex-mcp-state.sqlite3
  199. codex-control-plane-mcp-hooks status
  200. codex-control-plane-mcp-hooks doctor
  201. ```
  202. The installer backs up `~/.codex/hooks.json`, merges its handlers with your
  203. existing hooks, stores `stateDb` as an absolute path, and writes prompts, visible
  204. agent progress text, final answers, and turn status into the MCP state DB. Tool
  205. calls and command outputs are not recorded by default. Restart Codex after
  206. installing or changing hooks.
  207. For turns launched through `codex-app-server`, the server mirrors the accepted
  208. prompt, visible assistant messages, and turn status into the same SQLite
  209. history. That keeps search and status reads useful even when app-server does not
  210. execute user hooks itself.
  211. ## Main workflows
  212. Submit a durable task:
  213. ```text
  214. codex_submit_task
  215. -> operationId
  216. codex_get_operation_status(operationId)
  217. -> queued / running / waiting_for_approval / completed / failed
  218. ```
  219. Use the same `client_request_id` when a caller retries after a transport timeout.
  220. The retry returns the existing operation instead of creating another turn.
  221. Attach screenshots or other image evidence:
  222. ```text
  223. codex_submit_task(
  224. operation_type="start_chat",
  225. message="Analyze this screen.",
  226. input_items=[
  227. {"type": "localImage", "path": ".\\screens\\error.png", "detail": "low"},
  228. {"type": "image", "url": "https://example.com/screenshot.png", "detail": "high"}
  229. ]
  230. )
  231. ```
  232. Image inputs are accepted only for operation types that start a new turn:
  233. `start_chat`, `send_message`, `execute_plan`, and `fork_thread` with an initial
  234. message. MCP sends the path or URL to `codex-app-server`, but operation status
  235. and diagnostics return only safe metadata such as type, detail, size, extension,
  236. and hashes. Binary image content, raw URLs, and full local image paths are not
  237. stored in public status payloads.
  238. Steer an active turn:
  239. ```text
  240. codex_submit_task(operation_type="steer_turn", thread_id=..., expected_turn_id=..., message=...)
  241. -> operationId
  242. codex_get_operation_status(operationId)
  243. -> follows the target turn until completed / failed / interrupted
  244. ```
  245. Use `steer_turn` only while the target turn is active. For a completed thread,
  246. use `send_message` instead.
  247. Fork a thread:
  248. ```text
  249. codex_submit_task(operation_type="fork_thread", source_thread_id=...)
  250. -> operationId
  251. codex_get_operation_status(operationId)
  252. -> completed, threadId=<forkedThreadId>
  253. ```
  254. Start work in the fork right away:
  255. ```text
  256. codex_submit_task(operation_type="fork_thread", source_thread_id=..., message=...)
  257. -> operationId
  258. codex_get_operation_status(operationId)
  259. -> follows the first turn in the forked thread
  260. ```
  261. Use `client_request_id` for retry-safe fork requests. Without it, each call is
  262. treated as a new fork request. `threadId` in operation status is the forked
  263. thread; the source thread is reported in `forkState.sourceThreadId`.
  264. Manage thread lifecycle:
  265. ```text
  266. codex_archive_thread(thread_id)
  267. -> completed
  268. codex_unarchive_thread(thread_id)
  269. -> completed
  270. codex_start_thread_compaction(thread_id)
  271. -> actionId
  272. codex_get_thread_compaction_status(actionId)
  273. -> running / completed / unknown_after_app_server_exit
  274. ```
  275. Archive and unarchive are audit actions around app-server `thread/archive` and
  276. `thread/unarchive`. They refuse to run while the thread has an active turn or a
  277. pending interaction. Compaction uses its own lightweight `actionId` because
  278. `thread/compact/start` is asynchronous. Public `thread/delete` is intentionally
  279. not exposed.
  280. Ask for a structured final report:
  281. ```text
  282. codex_submit_task(operation_type="start_chat", message=..., output_schema={...})
  283. codex_approve_plan(workflowId, output_schema={...})
  284. -> operationId / executionOperationId
  285. codex_get_operation_status(operationId)
  286. codex_get_workflow_status(workflowId)
  287. -> finalReport.text + finalReport.structured
  288. ```
  289. `output_schema` is passed to app-server `turn/start` and is tracked by a schema
  290. hash in status output. Object schemas must use the strict form required by Codex:
  291. set `additionalProperties` to `false`. MCP stores the final assistant message
  292. as readable text, then parses JSON object output into `finalReport.structured`
  293. when Codex returns valid JSON. Plain text still works and stays available in
  294. `finalReport.text`.
  295. MCP does not extract hidden chain-of-thought and does not store raw tool
  296. payloads or command output in final reports.
  297. Drive Plan Mode:
  298. ```text
  299. codex_start_plan_workflow
  300. -> workflowId
  301. codex_get_workflow_status(workflowId)
  302. -> wait_plan / review_plan / execute_plan
  303. codex_approve_plan(workflowId)
  304. -> executionOperationId
  305. codex_get_workflow_status(workflowId)
  306. -> finalReport
  307. ```
  308. Plan Mode has a runtime floor. The public default write policy is still
  309. `read-only` and `on-request`, but Plan Mode needs a writable workspace on
  310. Windows. If the caller or server default resolves to `read-only`, MCP sends
  311. `workspace-write` to `codex-app-server` and returns `requestedSandbox`,
  312. `effectiveSandbox`, and `runtimePolicyAdjusted` in workflow and operation
  313. status.
  314. Mirror a workflow goal into Codex Desktop when the client has one:
  315. ```text
  316. codex_start_plan_workflow(goal="Review the migration plan", goal_completion_action="clear")
  317. codex_get_workflow_status(workflowId, refresh_live_goal=true)
  318. -> threadGoal.syncState + threadGoal.currentGoal
  319. ```
  320. MCP writes a thread goal only when the client passes `goal`. Managed goals use
  321. `clear` after completion by default. Use `set_complete` or `leave` when the goal
  322. should remain visible after the workflow ends. Normal workflow polling is
  323. passive; use `refresh_live_goal=true` only when you want MCP to call live
  324. app-server goal methods.
  325. Run a Codex code review:
  326. ```text
  327. codex_start_review_workflow(thread_id=..., target_type="base_branch", base_branch="main")
  328. -> workflowId
  329. codex_get_workflow_status(workflowId)
  330. -> wait_review / read_review_report
  331. ```
  332. Or let MCP create a service thread for a local checkout:
  333. ```text
  334. codex_start_review_workflow(cwd=..., target_type="uncommitted_changes")
  335. -> workflowId
  336. codex_get_workflow_status(workflowId)
  337. -> reviewThreadId + reviewTurnId + finalReport
  338. ```
  339. Review workflows do not write files by themselves. They run inside the selected
  340. Codex sandbox and approval policy. Use `client_request_id` when a caller may
  341. retry the start request after a transport timeout.
  342. Handle approvals and questions:
  343. ```text
  344. codex_list_pending_interactions
  345. codex_answer_pending_interaction
  346. ```
  347. Start diagnostics with:
  348. ```text
  349. codex_get_runtime_capabilities
  350. codex_health_summary
  351. codex_collect_diagnostics
  352. codex_analyze_issue
  353. codex_repair_issue
  354. ```
  355. Repair actions default to `dry_run=true`.
  356. Status and diagnostic tools also return `agentGuidance` and
  357. `agentGuidanceText` when MCP sees a blocker, failed state, stale run, pending
  358. interaction, duplicate prompt, auth problem, rate limit, or unsafe recovery
  359. loop. Agents should follow `agentGuidance.instructions` before deciding to
  360. retry or stop. If `agentGuidance.loopGuard.allowed=false`, stop automatic
  361. recovery, collect diagnostics, and ask a human. Do not create a new
  362. `client_request_id` after a timeout unless the guidance explicitly says to start
  363. a replacement workflow.
  364. For a broken Plan Mode workflow, use
  365. `retry_workflow_with_runtime_policy`. It creates a new workflow with the selected
  366. sandbox and approval policy, links it to the old workflow through
  367. `workflowRetryState`, and does not revive the old terminal turn.
  368. `codex_health_summary` is about current readiness by default. Old stale or
  369. orphaned rows are reported in `historicalDebt`, but they do not make fresh
  370. orchestration look broken when the worker, queue, and app-server are currently
  371. healthy. Use targeted cleanup for that debt instead of blocking new work.
  372. Status payloads now separate freshness signals:
  373. - `operationRowAgeSeconds`: age of the durable operation row;
  374. - `turnFreshness.lastProgressAgeSeconds`: age of the last turn progress event;
  375. - `workerFreshness.heartbeatAgeSeconds`: age of the worker heartbeat;
  376. - `stalenessMeaning="operation_row_age"` for the compatibility
  377. `stalenessSeconds` field.
  378. Public status payloads are agent-safe. Operation and workflow status return
  379. `requestSummary` instead of raw `request`; it contains ids, runtime policy,
  380. scheduling intent, input item state, output schema hash, resource keys, and
  381. text hashes. It does not include the full prompt, full instructions, raw title,
  382. raw image URL/path, exact token counts, raw command output, or private paths.
  383. Use your own stored task text plus `requestSummary.*.sha256` for correlation.
  384. `codex_get_queue_status` only recommends `wait_for_worker_slot` when there is
  385. actual queued work blocked by slots. If there are running turns but
  386. `queueSummary.queued == 0`, the queue action is `none`.
  387. ## Runtime capabilities
  388. Use `codex_get_runtime_capabilities` before orchestration or after reconnect. It
  389. starts the MCP-owned app-server if needed, calls short best-effort inventory
  390. methods, and returns a cached snapshot for five minutes.
  391. In `client` mode, the client process does not start its own app-server for live
  392. inventory. It returns a passive worker-managed snapshot when one exists. With
  393. `refresh=true`, it queues a worker command and returns `refreshCommandId`; poll
  394. `codex_get_worker_command_status` to read the refreshed inventory.
  395. The response includes:
  396. - model count, default model, hidden flags, input modalities, reasoning efforts, and service tier count;
  397. - permission profiles by `id` and `description`;
  398. - Windows sandbox readiness;
  399. - provider capabilities for web search, image generation, and namespace tools;
  400. - hook and skill counts without raw hook commands or absolute skill paths;
  401. - redacted account status, coarse usage bands, and operational rate-limit state;
  402. - supported app-server schema methods with a compact source, version, and hash.
  403. Account inventory is safe to show to an orchestrator. It reports whether Codex
  404. is authenticated, the account and plan type, whether an email exists, whether
  405. usage data is available, and whether a rate limit or credits issue is visible.
  406. It does not return raw email, account identifiers, credit balances, spend
  407. limits, exact spend used, daily usage buckets, or exact token counts.
  408. If one inventory method times out or fails, the tool still returns `ok=true`
  409. with `runtimeCapabilities.status="partial"` and a machine-readable warning in
  410. `methodResults`. Set `refresh=true` to bypass the cache. `codex_health_summary`
  411. shows a small `runtimeCapabilities` subset from the last collected snapshot and
  412. does not start app-server on its own. Pass `include_account=false` when a client
  413. does not need account, usage, or rate-limit status.
  414. ## Progress journal
  415. `codex_get_turn_status` and `codex_get_operation_status` include a compact
  416. `progressEvents` block by default. It captures app-server-visible progress such
  417. as assistant text deltas, plan deltas, reasoning summary text, token usage,
  418. model reroutes, and warnings.
  419. The journal helps with orchestration and troubleshooting. It does not extract
  420. hidden chain-of-thought. It also does not store raw tool payloads, command
  421. output, or full unified diffs by default. Diff events are reduced to safe
  422. counts, such as changed line count and diff size.
  423. Use `progress_events=0` when a client wants the older, message-only status
  424. shape. Use `progress_max_chars` to cap returned progress text.
  425. Public status returns token usage as coarse bands, not exact token counts. Raw
  426. audit surfaces may keep redacted event payloads for debugging, but orchestrators
  427. should treat `tokenUsage.totalTokensBand` and related band fields as the public
  428. contract.
  429. ## Tool surface
  430. Stable orchestration tools:
  431. - `codex_submit_task`
  432. - `codex_get_operation_status`
  433. - `codex_start_plan_workflow`
  434. - `codex_start_review_workflow`
  435. - `codex_get_workflow_status`
  436. - `codex_approve_plan`
  437. - `codex_list_pending_interactions`
  438. - `codex_answer_pending_interaction`
  439. - `codex_interrupt_turn`
  440. - `codex_archive_thread`
  441. - `codex_unarchive_thread`
  442. - `codex_start_thread_compaction`
  443. - `codex_get_thread_compaction_status`
  444. - `codex_get_runtime_capabilities`
  445. - `codex_health_summary`
  446. - `codex_collect_diagnostics`
  447. - `codex_repair_issue`
  448. Compatibility and read tools:
  449. - `codex_start_chat`
  450. - `codex_send_message`
  451. - `codex_execute_plan`
  452. - `codex_list_projects`
  453. - `codex_list_project_chats`
  454. - `codex_list_active_chats`
  455. - `codex_search_chats`
  456. - `codex_get_chat_status`
  457. - `codex_get_chat`
  458. - `codex_get_turn_status`
  459. - `codex_restart_app_server`
  460. - `codex_get_app_server_status`
  461. - `codex_get_diagnostic_logs`
  462. - `codex_analyze_issue`
  463. New clients should use durable operations and workflows. Low-level write tools
  464. stay available for compatibility.
  465. Read and diagnostic calls are bounded for agent loops. `codex_list_projects`
  466. defaults to compact cached output, `codex_search_chats` can return
  467. `timeBudgetExhausted=true` instead of blocking on a full refresh, and chat reads
  468. prefer tracked turn plus hook history before legacy KB fallback. Diagnostics are
  469. scoped-first: `scopedFindings` drive the next action, while
  470. `backgroundFindings` are historical context.
  471. See [docs/API_CONTRACT.md](docs/API_CONTRACT.md) for schemas, error shape,
  472. stable tool groups, and versioning rules.
  473. ## Result contract
  474. Every tool declares an `outputSchema` and returns MCP `structuredContent`.
  475. Success:
  476. ```json
  477. {"ok": true}
  478. ```
  479. Domain or tool error:
  480. ```json
  481. {
  482. "ok": false,
  483. "error": {
  484. "code": "CODEX_ERROR_CODE",
  485. "message": "Human readable message",
  486. "details": {},
  487. "retryable": false
  488. }
  489. }
  490. ```
  491. Call `codex_health_summary` on startup and reconnect. The `version` block
  492. contains `serverName`, `serverVersion`, `contractVersion`, `toolSurfaceHash`,
  493. `guideHash`, `guideVersion`, recommended startup/write tools, and
  494. stable/compatibility tool lists.
  495. Agents can discover the operating contract without reading this README.
  496. `tools/list` includes:
  497. - `codexMcpGuide`: compact machine-readable guide with capabilities, flows,
  498. global rules, and runtime limits;
  499. - `toolGroups`: ordered groups of preferred tools;
  500. - `recommendedStartupTool="codex_health_summary"`;
  501. - `recommendedPrimaryWriteTool="codex_submit_task"`.
  502. Every tool also has `annotations.codexMcp` with its role, follow-up tools,
  503. idempotency rule, passive-read flag, and `mayStartTurn` flag. If a client
  504. library hides top-level `tools/list` fields, call
  505. `codex_get_agent_contract(detail="compact")` or
  506. `codex_get_agent_contract(detail="full", include_examples=true)`.
  507. ## Configuration
  508. Configuration can come from environment variables or from a JSON file referenced
  509. by `CODEX_CONTROL_PLANE_MCP_CONFIG`. The old `OPENCLAW_CODEX_MCP_CONFIG` name is
  510. still accepted as a fallback.
  511. Common variables:
  512. - `CODEX_HOME`: Codex home directory. Defaults to `%USERPROFILE%\.codex`.
  513. - `CODEX_PROJECTS_ROOT`: project root scanned by catalog and read tools.
  514. - `CODEX_ALLOWED_ROOTS`: semicolon-separated path allowlist.
  515. - `CODEX_PROJECTS_REGISTRY`: optional JSON project registry.
  516. - `CODEX_MCP_STATE_DB`: local MCP state DB.
  517. - `CODEX_CONTROL_PLANE_MCP_LOG`: log file path.
  518. - `CODEX_MCP_HOOK_HISTORY_ENABLED`: enables SQLite hook history. Defaults to `true`.
  519. - `CODEX_MCP_HOOK_HISTORY_MAX_TEXT_CHARS`: per-message hook capture limit.
  520. - `CODEX_KB_HISTORY_PROJECTS_ROOT`: optional legacy normalized KB history root.
  521. - `CODEX_BINARY_PATH`: optional explicit Codex binary path.
  522. - `CODEX_MCP_DEFAULT_SANDBOX`: default write sandbox. Defaults to `read-only`.
  523. - `CODEX_MCP_DEFAULT_APPROVAL_POLICY`: default write approval policy. Defaults to `on-request`.
  524. - `CODEX_MCP_DEFAULT_MODEL`: default Codex model passed to app-server.
  525. - `CODEX_MCP_DEFAULT_EFFORT`: default effort level.
  526. - `CODEX_MCP_MAX_IMAGE_INPUT_ITEMS`: max image attachments per `codex_submit_task`. Defaults to `10`.
  527. - `CODEX_MCP_MAX_IMAGE_INPUT_BYTES`: max bytes for one local image input. Defaults to `20000000`.
  528. - `CODEX_MCP_TURN_STALL_TIMEOUT_SECONDS`: inactivity threshold for stalled-turn reporting. Defaults to `900`.
  529. - `CODEX_MCP_STALLED_TURN_ACTION`: stalled-turn policy. Defaults to `diagnose_only`.
  530. - `CODEX_MCP_APPROVAL_RESPONSE_TIMEOUT_SECONDS`: pending interaction timeout.
  531. - `DEEPSEEK_ENV_PATH`: optional `.env` file for DeepSeek summary settings.
  532. - `DEEPSEEK_SUMMARY_ENABLED`: enables or disables remote summary calls.
  533. The write policy values are defaults, not hard limits. A client call can pass
  534. `sandbox` or `approval_policy` explicitly when a trusted workflow needs a
  535. different posture.
  536. Plan Mode is the exception to pure pass-through behavior: `read-only` is treated
  537. as too restrictive for Plan Mode on Windows and is raised to `workspace-write`.
  538. More permissive per-call values, such as `workspace-write`, are passed through.
  539. Example:
  540. ```powershell
  541. $env:CODEX_CONTROL_PLANE_MCP_CONFIG = Join-Path (Get-Location) "examples\codex-control-plane-mcp.config.json"
  542. $env:CODEX_MCP_DEFAULT_SANDBOX = "read-only"
  543. $env:CODEX_MCP_DEFAULT_APPROVAL_POLICY = "on-request"
  544. py -m codex_control_plane_mcp.server
  545. ```
  546. See [examples/codex-control-plane-mcp.config.json](examples/codex-control-plane-mcp.config.json).
  547. ## Reliability model
  548. The server is built for common local orchestration failures:
  549. - MCP client timeout after task submission.
  550. - Repeated submit with the same `client_request_id`.
  551. - Repeated submit without an idempotency key but with the same active prompt.
  552. - MCP process restart between app-server `thread/start` and `turn/start`.
  553. - Two MCP processes sharing one SQLite state DB.
  554. - App-server exit while a turn is active.
  555. - Pending approval tied to an old app-server generation.
  556. - App-server or transcript gaps where hook history still captured the prompt,
  557. visible agent text, final answer, and completion status.
  558. These cases are stored in durable operation, workflow, turn, hook, and pending
  559. interaction state. Terminal statuses are explicit.
  560. `unknown_after_app_server_exit` is not treated as success.
  561. ## Safety
  562. - Live smoke prompts must include `MCP LIVE TEST / DO NOT MODIFY FILES`.
  563. - Repairs default to `dry_run=true`.
  564. - Forced app-server restart can mark active turns as unknown or orphaned. Prefer
  565. `restart_app_server_idle`.
  566. ## Checks
  567. Fast local checks:
  568. ```powershell
  569. python -m pytest -q
  570. python -m compileall -q openclaw_codex_mcp codex_control_plane_mcp tests scripts
  571. git diff --check
  572. ```
  573. Protocol-only MCP smoke:
  574. ```powershell
  575. python .\scripts\mcp_live_smoke.py --scenario protocol
  576. ```
  577. Safe live smoke with real Codex Desktop/app-server:
  578. ```powershell
  579. python .\scripts\mcp_live_smoke.py --scenario safe-operation --cwd <PROJECT_ROOT>
  580. ```
  581. Full live regression:
  582. ```powershell
  583. python .\scripts\mcp_live_smoke.py --scenario full --safe-restart --cwd <PROJECT_ROOT>
  584. ```
  585. External MCP client for development and long live tests:
  586. ```powershell
  587. python .\scripts\external_mcp_client.py daemon-start
  588. python .\scripts\external_mcp_client.py daemon-restart-mcp --reason after_code_change
  589. python .\scripts\external_mcp_client.py run-live-test --scenario full --archive-report
  590. ```
  591. Use the external client when you need to test the current checkout as a real MCP
  592. client without restarting Codex Desktop. It runs an independent daemon, keeps
  593. its own MCP stdio subprocess, and can restart only that subprocess after code
  594. changes. Live test findings are written to `corrective_action_plan.md`; previous
  595. reports can be archived with `--archive-report`.
  596. See [docs/EXTERNAL_MCP_CLIENT.md](docs/EXTERNAL_MCP_CLIENT.md) for the daemon
  597. commands and the available live scenarios.
  598. See [docs/RELEASE_CHECKLIST.md](docs/RELEASE_CHECKLIST.md). For public launch
  599. positioning, see [docs/PUBLICATION_GUIDE.md](docs/PUBLICATION_GUIDE.md).
  600. ## Packaging
  601. Build locally:
  602. ```powershell
  603. python -m pip install build
  604. python -m build
  605. ```
  606. The wheel includes the MCP server, the hook installer, the admin helper, and the
  607. bundled Codex hook module.
  608. The normal install path is:
  609. ```powershell
  610. pipx install codex-control-plane-mcp
  611. ```
  612. or:
  613. ```powershell
  614. uvx codex-control-plane-mcp
  615. ```
  616. ## Contributing
  617. Read [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md) before
  618. opening issues that include diagnostics.
  619. Good GitHub topics for this repo:
  620. `python`, `mcp`, `mcp-server`, `model-context-protocol`, `openai-codex`,
  621. `codex`, `codex-desktop`, `agent-tools`, `ai-agents`, `developer-tools`,
  622. `automation`, `orchestration`, `agentic-workflows`, `long-running-tasks`,
  623. `openclaw`, `hermes`, `hermes-agent`.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.