{"id":51165582,"url":"https://github.com/aresyn/codex-control-plane-mcp","last_synced_at":"2026-07-15T03:00:33.622Z","repository":{"id":365442057,"uuid":"1272121729","full_name":"aresyn/codex-control-plane-mcp","owner":"aresyn","description":"Durable MCP control plane for long-running Codex Desktop tasks","archived":false,"fork":false,"pushed_at":"2026-06-17T11:33:05.000Z","size":1998,"stargazers_count":0,"open_issues_count":8,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-17T11:33:07.394Z","etag":null,"topics":["agent-tools","agentic-workflows","ai-agents","automation","codex","codex-desktop","developer-tools","hermes","hermes-agent","long-running-tasks","mcp","mcp-server","model-context-protocol","openai-codex","openclaw","orchestration","python"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/codex-control-plane-mcp/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aresyn.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-17T10:02:02.000Z","updated_at":"2026-06-17T11:30:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aresyn/codex-control-plane-mcp","commit_stats":null,"previous_names":["aresyn/codex-control-plane-mcp"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/aresyn/codex-control-plane-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aresyn%2Fcodex-control-plane-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aresyn%2Fcodex-control-plane-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aresyn%2Fcodex-control-plane-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aresyn%2Fcodex-control-plane-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aresyn","download_url":"https://codeload.github.com/aresyn/codex-control-plane-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aresyn%2Fcodex-control-plane-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35488230,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-15T02:00:06.706Z","response_time":131,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-tools","agentic-workflows","ai-agents","automation","codex","codex-desktop","developer-tools","hermes","hermes-agent","long-running-tasks","mcp","mcp-server","model-context-protocol","openai-codex","openclaw","orchestration","python"],"created_at":"2026-06-26T19:00:22.701Z","updated_at":"2026-07-15T03:00:33.615Z","avatar_url":"https://github.com/aresyn.png","language":"Python","funding_links":[],"categories":["MCP 服务器精选列表"],"sub_categories":["💻 开发与代码执行"],"readme":"[![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)\n\n# Codex Control Plane MCP\n\nEnglish | [Русский](README.ru.md)\n\n\u003c!-- mcp-name: io.github.aresyn/codex-control-plane-mcp --\u003e\n\n[![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)\n[![PyPI](https://img.shields.io/pypi/v/codex-control-plane-mcp.svg)](https://pypi.org/project/codex-control-plane-mcp/)\n[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)\n[![MCP](https://img.shields.io/badge/MCP-stdio-green.svg)](docs/API_CONTRACT.md)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/aresyn/codex-control-plane-mcp/main/assets/repo_image.png\" alt=\"Codex Control Plane MCP\" width=\"100%\"\u003e\n\u003c/p\u003e\n\nReliable Codex Desktop automation for long tasks.\n\n`codex-control-plane-mcp` turns Codex Desktop and `codex-app-server` into a\ndurable worker that an MCP client can drive safely. Send a task, get an\n`operationId` or `workflowId` right away, poll until the work finishes, approve\nPlan Mode when needed, then read the final report.\n\nThe server handles the awkward parts that thin wrappers usually leave to the\ncaller: app-server startup, thread and turn creation, retry safety, duplicate\nprompt protection, Plan Mode, approvals, local history, diagnostics, and repair.\n\nOpenClaw and Hermes are first-class clients, but the server is useful for any\nlocal orchestrator that needs Codex Desktop to do long-running work without\nholding one MCP call open for hours.\n\n## The short version\n\n```text\nMCP client / orchestrator\n  -\u003e submit a task or start a Plan Mode workflow\n  \u003c- receive operationId or workflowId immediately\n  -\u003e poll status\n  -\u003e answer approvals or approve the plan\n  \u003c- read final report, diagnostics, threadId, and turnId\n```\n\nThat gives you a simple contract:\n\n- no multi-hour MCP calls;\n- no duplicate Codex turns after a client retry;\n- no blind fire-and-forget task submission;\n- a local SQLite record of operations, workflows, turns, hooks, and diagnostics.\n\n## Why not just call Codex directly?\n\n| Capability | Thin Codex wrapper | Codex Control Plane MCP |\n|---|---:|---:|\n| Multi-hour tasks | blocking / fragile | durable async operation |\n| Client timeout recovery | manual | retry-safe `client_request_id` |\n| Duplicate turn protection | no | active prompt detection |\n| Plan Mode workflow | human / manual | pollable workflow state |\n| Approvals and questions | blocking / opaque | pending interactions API |\n| Restart recovery | ad hoc | persisted operation state |\n| Diagnostics | logs only | health, diagnostics, repair tools |\n\nFor a more detailed decision guide, see\n[docs/THIN_WRAPPERS.md](docs/THIN_WRAPPERS.md).\n\n## Current support\n\n- Full live target: Windows with Codex Desktop and `codex-app-server`.\n- Linux and macOS: protocol-only checks for now.\n- Local-first: not intended to be exposed as a public network service.\n\n## Security model\n\nThis is a local-first control plane for trusted Codex Desktop environments.\n\nDo not expose it as a network service without authentication.\n\nRecommended first-run posture:\n\n- use `read-only` for untrusted repositories;\n- use `on-request` approval when testing new workflows;\n- Plan Mode never runs with a `read-only` sandbox. If a caller requests\n  `read-only`, MCP raises that turn to `workspace-write` and reports the\n  adjustment in status output;\n- keep `state/`, `logs/`, `.env`, and `.codex/` private.\n\n## What it does\n\n- Durable async queue for Codex write operations.\n- Retry-safe `client_request_id` handling.\n- Active duplicate prompt detection.\n- SQLite leases and heartbeats for competing MCP processes.\n- Recovery after MCP restart during `thread/start` or `turn/start`.\n- Durable `turn/steer` for adding context to an active turn without creating a second turn.\n- Durable `thread/fork` for branching an existing thread, with or without an initial message.\n- Plan Mode workflows: start plan, poll, approve, execute, read final report.\n- Plan Mode runtime floor: `workspace-write`, with `runtimePolicyAdjusted` in\n  status when MCP raises a `read-only` request.\n- Code review workflows through app-server `review/start`, with polling and final report capture.\n- Structured final reports with `output_schema`.\n- Thread lifecycle tools for archive, unarchive, and pollable compaction.\n- Workflow goal sync with Codex Desktop thread goals.\n- Image and local image inputs for turns that start through `turn/start`.\n- Pending approvals and questions exposed as pollable MCP state.\n- Turn interrupts by `threadId`/`turnId`, `operationId`, or `workflowId`.\n- Runtime inventory for models, permission profiles, sandbox readiness, hooks, skills, provider features, account status, usage bands, rate-limit state, and supported app-server methods.\n- Health checks, diagnostics, issue analysis, and dry-run repairs.\n- MCP-owned hook history in SQLite for search, summaries, and fallback reads.\n- Redacted app-server progress journal for deltas, warnings, model reroutes, and token usage.\n- Structured MCP errors that automation code can branch on.\n\nWrite and control actions go through `codex-app-server`. The server does not\nmutate Codex internal SQLite databases or transcript files.\n\n## Install\n\nRecommended:\n\n```powershell\npipx install codex-control-plane-mcp\n```\n\nOr run directly:\n\n```powershell\nuvx codex-control-plane-mcp\n```\n\nFrom GitHub:\n\n```powershell\npython -m pip install \"codex-control-plane-mcp @ git+https://github.com/aresyn/codex-control-plane-mcp.git\"\n```\n\nFor local development:\n\n```powershell\ngit clone https://github.com/aresyn/codex-control-plane-mcp.git\ncd codex-control-plane-mcp\npy -m venv .venv\n.\\.venv\\Scripts\\Activate.ps1\npython -m pip install -e \".[dev]\"\npython -m pytest -q\n```\n\n## MCP client config\n\nAfter installation, generate a config:\n\n```powershell\ncodex-control-plane-mcp-admin init --state-db .\\state\\codex-mcp-state.sqlite3 --projects-root C:\\Users\\you\\Projects\n```\n\nMinimal stdio entry:\n\n```json\n{\n  \"mcpServers\": {\n    \"codex-control-plane\": {\n      \"command\": \"codex-control-plane-mcp\",\n      \"args\": []\n    }\n  }\n}\n```\n\nRun the MCP stdio server:\n\n```powershell\ncodex-control-plane-mcp\n```\n\nOr run it as a module:\n\n```powershell\npy -m codex_control_plane_mcp.server\n```\n\nThe old `openclaw-codex-mcp` and `openclaw-codex-mcp-hooks` commands remain as\ncompatibility aliases for one release line.\n\n## Central worker mode\n\nThe default `inline` mode is still the simplest setup: one MCP process can submit\nand execute operations. For OpenClaw, Hermes, or any setup with several MCP\nclients, use a central worker instead.\n\nRecommended local shape:\n\n- every MCP client uses the same `CODEX_HOME` and `CODEX_MCP_STATE_DB`;\n- OpenClaw gateway entries run with `CODEX_MCP_EXECUTION_MODE=client`;\n- one long-running `codex-control-plane-mcp-worker` process owns\n  `codex-app-server`, leases, queue slots, and resource locks;\n- clients call `codex_submit_task`, then poll status. They do not execute queued\n  operations themselves.\n\nWorker command:\n\n```powershell\n$env:CODEX_MCP_EXECUTION_MODE = \"worker\"\ncodex-control-plane-mcp-worker\n```\n\nSafe observation mode, useful before switching a live gateway:\n\n```powershell\ncodex-control-plane-mcp-worker --observe\n```\n\nConcurrency defaults:\n\n```powershell\nCODEX_MCP_MAX_ACTIVE_TURNS_GLOBAL=4\nCODEX_MCP_MAX_ACTIVE_TURNS_PER_PROJECT=3\nCODEX_MCP_MAX_ACTIVE_TURNS_PER_AGENT=3\nCODEX_MCP_MAX_ACTIVE_TURNS_PER_THREAD=1\nCODEX_MCP_MAX_ACTIVE_WRITE_TURNS_PER_PROJECT=1\nCODEX_MCP_MAX_APP_SERVER_PENDING_REQUESTS=8\n```\n\nFor write turns in the same project, pass `resource_keys` to\n`codex_submit_task`. Without them, `workspace-write` and `danger-full-access`\nturns take a broad project write lock. With disjoint keys, the worker may run\nseveral write turns in parallel.\n\nNew status tools:\n\n- `codex_get_worker_status`\n- `codex_get_queue_status`\n- `codex_get_concurrency_status`\n- `codex_get_worker_command_status`\n\n`codex_get_operation_status` also returns `queueState`, `workerState`,\n`slotState`, and `resourceLockState`. A running turn has\n`slotState.claimed=true` and a `slotClaim` with the worker id, slot type, and\nclaim time. `codex_get_queue_status` separates queued work from running turn\noperations, auxiliary operations, active turn slots, and lock conflicts.\n\nWhen a workflow is waiting for capacity, `codex_get_workflow_status` mirrors the\nnested operation queue state in `workflowOperationQueueState`. Use\n`nextRecommendedAction=\"wait_for_worker_slot\"` for slot pressure and\n`nextRecommendedAction=\"wait_for_resource_lock\"` for write lock conflicts. Do\nnot create another operation for the same work while either action is returned.\n\n## First setup\n\nThe admin helper can generate a fuller client config, install hooks, and run a\nprotocol smoke:\n\n```powershell\ncodex-control-plane-mcp-admin init --state-db .\\state\\codex-mcp-state.sqlite3 --projects-root C:\\Users\\you\\Projects\n```\n\nThe command prints a JSON block you can copy into an MCP client config. It does\nnot print secrets or private prompts.\n\nYou can also install only the Codex hooks:\n\n```powershell\ncodex-control-plane-mcp-hooks install --state-db .\\state\\codex-mcp-state.sqlite3\ncodex-control-plane-mcp-hooks status\ncodex-control-plane-mcp-hooks doctor\n```\n\nThe installer backs up `~/.codex/hooks.json`, merges its handlers with your\nexisting hooks, stores `stateDb` as an absolute path, and writes prompts, visible\nagent progress text, final answers, and turn status into the MCP state DB. Tool\ncalls and command outputs are not recorded by default. Restart Codex after\ninstalling or changing hooks.\n\nFor turns launched through `codex-app-server`, the server mirrors the accepted\nprompt, visible assistant messages, and turn status into the same SQLite\nhistory. That keeps search and status reads useful even when app-server does not\nexecute user hooks itself.\n\n## Main workflows\n\nSubmit a durable task:\n\n```text\ncodex_submit_task\n  -\u003e operationId\ncodex_get_operation_status(operationId)\n  -\u003e queued / running / waiting_for_approval / completed / failed\n```\n\nUse the same `client_request_id` when a caller retries after a transport timeout.\nThe retry returns the existing operation instead of creating another turn.\n\nAttach screenshots or other image evidence:\n\n```text\ncodex_submit_task(\n  operation_type=\"start_chat\",\n  message=\"Analyze this screen.\",\n  input_items=[\n    {\"type\": \"localImage\", \"path\": \".\\\\screens\\\\error.png\", \"detail\": \"low\"},\n    {\"type\": \"image\", \"url\": \"https://example.com/screenshot.png\", \"detail\": \"high\"}\n  ]\n)\n```\n\nImage inputs are accepted only for operation types that start a new turn:\n`start_chat`, `send_message`, `execute_plan`, and `fork_thread` with an initial\nmessage. MCP sends the path or URL to `codex-app-server`, but operation status\nand diagnostics return only safe metadata such as type, detail, size, extension,\nand hashes. Binary image content, raw URLs, and full local image paths are not\nstored in public status payloads.\n\nSteer an active turn:\n\n```text\ncodex_submit_task(operation_type=\"steer_turn\", thread_id=..., expected_turn_id=..., message=...)\n  -\u003e operationId\ncodex_get_operation_status(operationId)\n  -\u003e follows the target turn until completed / failed / interrupted\n```\n\nUse `steer_turn` only while the target turn is active. For a completed thread,\nuse `send_message` instead.\n\nFork a thread:\n\n```text\ncodex_submit_task(operation_type=\"fork_thread\", source_thread_id=...)\n  -\u003e operationId\ncodex_get_operation_status(operationId)\n  -\u003e completed, threadId=\u003cforkedThreadId\u003e\n```\n\nStart work in the fork right away:\n\n```text\ncodex_submit_task(operation_type=\"fork_thread\", source_thread_id=..., message=...)\n  -\u003e operationId\ncodex_get_operation_status(operationId)\n  -\u003e follows the first turn in the forked thread\n```\n\nUse `client_request_id` for retry-safe fork requests. Without it, each call is\ntreated as a new fork request. `threadId` in operation status is the forked\nthread; the source thread is reported in `forkState.sourceThreadId`.\n\nManage thread lifecycle:\n\n```text\ncodex_archive_thread(thread_id)\n  -\u003e completed\ncodex_unarchive_thread(thread_id)\n  -\u003e completed\ncodex_start_thread_compaction(thread_id)\n  -\u003e actionId\ncodex_get_thread_compaction_status(actionId)\n  -\u003e running / completed / unknown_after_app_server_exit\n```\n\nArchive and unarchive are audit actions around app-server `thread/archive` and\n`thread/unarchive`. They refuse to run while the thread has an active turn or a\npending interaction. Compaction uses its own lightweight `actionId` because\n`thread/compact/start` is asynchronous. Public `thread/delete` is intentionally\nnot exposed.\n\nAsk for a structured final report:\n\n```text\ncodex_submit_task(operation_type=\"start_chat\", message=..., output_schema={...})\ncodex_approve_plan(workflowId, output_schema={...})\n  -\u003e operationId / executionOperationId\ncodex_get_operation_status(operationId)\ncodex_get_workflow_status(workflowId)\n  -\u003e finalReport.text + finalReport.structured\n```\n\n`output_schema` is passed to app-server `turn/start` and is tracked by a schema\nhash in status output. Object schemas must use the strict form required by Codex:\nset `additionalProperties` to `false`. MCP stores the final assistant message\nas readable text, then parses JSON object output into `finalReport.structured`\nwhen Codex returns valid JSON. Plain text still works and stays available in\n`finalReport.text`.\n\nMCP does not extract hidden chain-of-thought and does not store raw tool\npayloads or command output in final reports.\n\nDrive Plan Mode:\n\n```text\ncodex_start_plan_workflow\n  -\u003e workflowId\ncodex_get_workflow_status(workflowId)\n  -\u003e wait_plan / review_plan / execute_plan\ncodex_approve_plan(workflowId)\n  -\u003e executionOperationId\ncodex_get_workflow_status(workflowId)\n  -\u003e finalReport\n```\n\nPlan Mode has a runtime floor. The public default write policy is still\n`read-only` and `on-request`, but Plan Mode needs a writable workspace on\nWindows. If the caller or server default resolves to `read-only`, MCP sends\n`workspace-write` to `codex-app-server` and returns `requestedSandbox`,\n`effectiveSandbox`, and `runtimePolicyAdjusted` in workflow and operation\nstatus.\n\nMirror a workflow goal into Codex Desktop when the client has one:\n\n```text\ncodex_start_plan_workflow(goal=\"Review the migration plan\", goal_completion_action=\"clear\")\ncodex_get_workflow_status(workflowId, refresh_live_goal=true)\n  -\u003e threadGoal.syncState + threadGoal.currentGoal\n```\n\nMCP writes a thread goal only when the client passes `goal`. Managed goals use\n`clear` after completion by default. Use `set_complete` or `leave` when the goal\nshould remain visible after the workflow ends. Normal workflow polling is\npassive; use `refresh_live_goal=true` only when you want MCP to call live\napp-server goal methods.\n\nRun a Codex code review:\n\n```text\ncodex_start_review_workflow(thread_id=..., target_type=\"base_branch\", base_branch=\"main\")\n  -\u003e workflowId\ncodex_get_workflow_status(workflowId)\n  -\u003e wait_review / read_review_report\n```\n\nOr let MCP create a service thread for a local checkout:\n\n```text\ncodex_start_review_workflow(cwd=..., target_type=\"uncommitted_changes\")\n  -\u003e workflowId\ncodex_get_workflow_status(workflowId)\n  -\u003e reviewThreadId + reviewTurnId + finalReport\n```\n\nReview workflows do not write files by themselves. They run inside the selected\nCodex sandbox and approval policy. Use `client_request_id` when a caller may\nretry the start request after a transport timeout.\n\nHandle approvals and questions:\n\n```text\ncodex_list_pending_interactions\ncodex_answer_pending_interaction\n```\n\nStart diagnostics with:\n\n```text\ncodex_get_runtime_capabilities\ncodex_health_summary\ncodex_collect_diagnostics\ncodex_analyze_issue\ncodex_repair_issue\n```\n\nRepair actions default to `dry_run=true`.\n\nStatus and diagnostic tools also return `agentGuidance` and\n`agentGuidanceText` when MCP sees a blocker, failed state, stale run, pending\ninteraction, duplicate prompt, auth problem, rate limit, or unsafe recovery\nloop. Agents should follow `agentGuidance.instructions` before deciding to\nretry or stop. If `agentGuidance.loopGuard.allowed=false`, stop automatic\nrecovery, collect diagnostics, and ask a human. Do not create a new\n`client_request_id` after a timeout unless the guidance explicitly says to start\na replacement workflow.\n\nFor a broken Plan Mode workflow, use\n`retry_workflow_with_runtime_policy`. It creates a new workflow with the selected\nsandbox and approval policy, links it to the old workflow through\n`workflowRetryState`, and does not revive the old terminal turn.\n\n`codex_health_summary` is about current readiness by default. Old stale or\norphaned rows are reported in `historicalDebt`, but they do not make fresh\norchestration look broken when the worker, queue, and app-server are currently\nhealthy. Use targeted cleanup for that debt instead of blocking new work.\n\nStatus payloads now separate freshness signals:\n\n- `operationRowAgeSeconds`: age of the durable operation row;\n- `turnFreshness.lastProgressAgeSeconds`: age of the last turn progress event;\n- `workerFreshness.heartbeatAgeSeconds`: age of the worker heartbeat;\n- `stalenessMeaning=\"operation_row_age\"` for the compatibility\n  `stalenessSeconds` field.\n\nPublic status payloads are agent-safe. Operation and workflow status return\n`requestSummary` instead of raw `request`; it contains ids, runtime policy,\nscheduling intent, input item state, output schema hash, resource keys, and\ntext hashes. It does not include the full prompt, full instructions, raw title,\nraw image URL/path, exact token counts, raw command output, or private paths.\nUse your own stored task text plus `requestSummary.*.sha256` for correlation.\n\n`codex_get_queue_status` only recommends `wait_for_worker_slot` when there is\nactual queued work blocked by slots. If there are running turns but\n`queueSummary.queued == 0`, the queue action is `none`.\n\n## Runtime capabilities\n\nUse `codex_get_runtime_capabilities` before orchestration or after reconnect. It\nstarts the MCP-owned app-server if needed, calls short best-effort inventory\nmethods, and returns a cached snapshot for five minutes.\n\nIn `client` mode, the client process does not start its own app-server for live\ninventory. It returns a passive worker-managed snapshot when one exists. With\n`refresh=true`, it queues a worker command and returns `refreshCommandId`; poll\n`codex_get_worker_command_status` to read the refreshed inventory.\n\nThe response includes:\n\n- model count, default model, hidden flags, input modalities, reasoning efforts, and service tier count;\n- permission profiles by `id` and `description`;\n- Windows sandbox readiness;\n- provider capabilities for web search, image generation, and namespace tools;\n- hook and skill counts without raw hook commands or absolute skill paths;\n- redacted account status, coarse usage bands, and operational rate-limit state;\n- supported app-server schema methods with a compact source, version, and hash.\n\nAccount inventory is safe to show to an orchestrator. It reports whether Codex\nis authenticated, the account and plan type, whether an email exists, whether\nusage data is available, and whether a rate limit or credits issue is visible.\nIt does not return raw email, account identifiers, credit balances, spend\nlimits, exact spend used, daily usage buckets, or exact token counts.\n\nIf one inventory method times out or fails, the tool still returns `ok=true`\nwith `runtimeCapabilities.status=\"partial\"` and a machine-readable warning in\n`methodResults`. Set `refresh=true` to bypass the cache. `codex_health_summary`\nshows a small `runtimeCapabilities` subset from the last collected snapshot and\ndoes not start app-server on its own. Pass `include_account=false` when a client\ndoes not need account, usage, or rate-limit status.\n\n## Progress journal\n\n`codex_get_turn_status` and `codex_get_operation_status` include a compact\n`progressEvents` block by default. It captures app-server-visible progress such\nas assistant text deltas, plan deltas, reasoning summary text, token usage,\nmodel reroutes, and warnings.\n\nThe journal helps with orchestration and troubleshooting. It does not extract\nhidden chain-of-thought. It also does not store raw tool payloads, command\noutput, or full unified diffs by default. Diff events are reduced to safe\ncounts, such as changed line count and diff size.\n\nUse `progress_events=0` when a client wants the older, message-only status\nshape. Use `progress_max_chars` to cap returned progress text.\n\nPublic status returns token usage as coarse bands, not exact token counts. Raw\naudit surfaces may keep redacted event payloads for debugging, but orchestrators\nshould treat `tokenUsage.totalTokensBand` and related band fields as the public\ncontract.\n\n## Tool surface\n\nStable orchestration tools:\n\n- `codex_submit_task`\n- `codex_get_operation_status`\n- `codex_start_plan_workflow`\n- `codex_start_review_workflow`\n- `codex_get_workflow_status`\n- `codex_approve_plan`\n- `codex_list_pending_interactions`\n- `codex_answer_pending_interaction`\n- `codex_interrupt_turn`\n- `codex_archive_thread`\n- `codex_unarchive_thread`\n- `codex_start_thread_compaction`\n- `codex_get_thread_compaction_status`\n- `codex_get_runtime_capabilities`\n- `codex_health_summary`\n- `codex_collect_diagnostics`\n- `codex_repair_issue`\n\nCompatibility and read tools:\n\n- `codex_start_chat`\n- `codex_send_message`\n- `codex_execute_plan`\n- `codex_list_projects`\n- `codex_list_project_chats`\n- `codex_list_active_chats`\n- `codex_search_chats`\n- `codex_get_chat_status`\n- `codex_get_chat`\n- `codex_get_turn_status`\n- `codex_restart_app_server`\n- `codex_get_app_server_status`\n- `codex_get_diagnostic_logs`\n- `codex_analyze_issue`\n\nNew clients should use durable operations and workflows. Low-level write tools\nstay available for compatibility.\n\nRead and diagnostic calls are bounded for agent loops. `codex_list_projects`\ndefaults to compact cached output, `codex_search_chats` can return\n`timeBudgetExhausted=true` instead of blocking on a full refresh, and chat reads\nprefer tracked turn plus hook history before legacy KB fallback. Diagnostics are\nscoped-first: `scopedFindings` drive the next action, while\n`backgroundFindings` are historical context.\n\nSee [docs/API_CONTRACT.md](docs/API_CONTRACT.md) for schemas, error shape,\nstable tool groups, and versioning rules.\n\n## Result contract\n\nEvery tool declares an `outputSchema` and returns MCP `structuredContent`.\n\nSuccess:\n\n```json\n{\"ok\": true}\n```\n\nDomain or tool error:\n\n```json\n{\n  \"ok\": false,\n  \"error\": {\n    \"code\": \"CODEX_ERROR_CODE\",\n    \"message\": \"Human readable message\",\n    \"details\": {},\n    \"retryable\": false\n  }\n}\n```\n\nCall `codex_health_summary` on startup and reconnect. The `version` block\ncontains `serverName`, `serverVersion`, `contractVersion`, `toolSurfaceHash`,\n`guideHash`, `guideVersion`, recommended startup/write tools, and\nstable/compatibility tool lists.\n\nAgents can discover the operating contract without reading this README.\n`tools/list` includes:\n\n- `codexMcpGuide`: compact machine-readable guide with capabilities, flows,\n  global rules, and runtime limits;\n- `toolGroups`: ordered groups of preferred tools;\n- `recommendedStartupTool=\"codex_health_summary\"`;\n- `recommendedPrimaryWriteTool=\"codex_submit_task\"`.\n\nEvery tool also has `annotations.codexMcp` with its role, follow-up tools,\nidempotency rule, passive-read flag, and `mayStartTurn` flag. If a client\nlibrary hides top-level `tools/list` fields, call\n`codex_get_agent_contract(detail=\"compact\")` or\n`codex_get_agent_contract(detail=\"full\", include_examples=true)`.\n\n## Configuration\n\nConfiguration can come from environment variables or from a JSON file referenced\nby `CODEX_CONTROL_PLANE_MCP_CONFIG`. The old `OPENCLAW_CODEX_MCP_CONFIG` name is\nstill accepted as a fallback.\n\nCommon variables:\n\n- `CODEX_HOME`: Codex home directory. Defaults to `%USERPROFILE%\\.codex`.\n- `CODEX_PROJECTS_ROOT`: project root scanned by catalog and read tools.\n- `CODEX_ALLOWED_ROOTS`: semicolon-separated path allowlist.\n- `CODEX_PROJECTS_REGISTRY`: optional JSON project registry.\n- `CODEX_MCP_STATE_DB`: local MCP state DB.\n- `CODEX_CONTROL_PLANE_MCP_LOG`: log file path.\n- `CODEX_MCP_HOOK_HISTORY_ENABLED`: enables SQLite hook history. Defaults to `true`.\n- `CODEX_MCP_HOOK_HISTORY_MAX_TEXT_CHARS`: per-message hook capture limit.\n- `CODEX_KB_HISTORY_PROJECTS_ROOT`: optional legacy normalized KB history root.\n- `CODEX_BINARY_PATH`: optional explicit Codex binary path.\n- `CODEX_MCP_DEFAULT_SANDBOX`: default write sandbox. Defaults to `read-only`.\n- `CODEX_MCP_DEFAULT_APPROVAL_POLICY`: default write approval policy. Defaults to `on-request`.\n- `CODEX_MCP_DEFAULT_MODEL`: default Codex model passed to app-server.\n- `CODEX_MCP_DEFAULT_EFFORT`: default effort level.\n- `CODEX_MCP_MAX_IMAGE_INPUT_ITEMS`: max image attachments per `codex_submit_task`. Defaults to `10`.\n- `CODEX_MCP_MAX_IMAGE_INPUT_BYTES`: max bytes for one local image input. Defaults to `20000000`.\n- `CODEX_MCP_TURN_STALL_TIMEOUT_SECONDS`: inactivity threshold for stalled-turn reporting. Defaults to `900`.\n- `CODEX_MCP_STALLED_TURN_ACTION`: stalled-turn policy. Defaults to `diagnose_only`.\n- `CODEX_MCP_APPROVAL_RESPONSE_TIMEOUT_SECONDS`: pending interaction timeout.\n- `DEEPSEEK_ENV_PATH`: optional `.env` file for DeepSeek summary settings.\n- `DEEPSEEK_SUMMARY_ENABLED`: enables or disables remote summary calls.\n\nThe write policy values are defaults, not hard limits. A client call can pass\n`sandbox` or `approval_policy` explicitly when a trusted workflow needs a\ndifferent posture.\n\nPlan Mode is the exception to pure pass-through behavior: `read-only` is treated\nas too restrictive for Plan Mode on Windows and is raised to `workspace-write`.\nMore permissive per-call values, such as `workspace-write`, are passed through.\n\nExample:\n\n```powershell\n$env:CODEX_CONTROL_PLANE_MCP_CONFIG = Join-Path (Get-Location) \"examples\\codex-control-plane-mcp.config.json\"\n$env:CODEX_MCP_DEFAULT_SANDBOX = \"read-only\"\n$env:CODEX_MCP_DEFAULT_APPROVAL_POLICY = \"on-request\"\npy -m codex_control_plane_mcp.server\n```\n\nSee [examples/codex-control-plane-mcp.config.json](examples/codex-control-plane-mcp.config.json).\n\n## Reliability model\n\nThe server is built for common local orchestration failures:\n\n- MCP client timeout after task submission.\n- Repeated submit with the same `client_request_id`.\n- Repeated submit without an idempotency key but with the same active prompt.\n- MCP process restart between app-server `thread/start` and `turn/start`.\n- Two MCP processes sharing one SQLite state DB.\n- App-server exit while a turn is active.\n- Pending approval tied to an old app-server generation.\n- App-server or transcript gaps where hook history still captured the prompt,\n  visible agent text, final answer, and completion status.\n\nThese cases are stored in durable operation, workflow, turn, hook, and pending\ninteraction state. Terminal statuses are explicit.\n`unknown_after_app_server_exit` is not treated as success.\n\n## Safety\n\n- Live smoke prompts must include `MCP LIVE TEST / DO NOT MODIFY FILES`.\n- Repairs default to `dry_run=true`.\n- Forced app-server restart can mark active turns as unknown or orphaned. Prefer\n  `restart_app_server_idle`.\n\n## Checks\n\nFast local checks:\n\n```powershell\npython -m pytest -q\npython -m compileall -q openclaw_codex_mcp codex_control_plane_mcp tests scripts\ngit diff --check\n```\n\nProtocol-only MCP smoke:\n\n```powershell\npython .\\scripts\\mcp_live_smoke.py --scenario protocol\n```\n\nSafe live smoke with real Codex Desktop/app-server:\n\n```powershell\npython .\\scripts\\mcp_live_smoke.py --scenario safe-operation --cwd \u003cPROJECT_ROOT\u003e\n```\n\nFull live regression:\n\n```powershell\npython .\\scripts\\mcp_live_smoke.py --scenario full --safe-restart --cwd \u003cPROJECT_ROOT\u003e\n```\n\nExternal MCP client for development and long live tests:\n\n```powershell\npython .\\scripts\\external_mcp_client.py daemon-start\npython .\\scripts\\external_mcp_client.py daemon-restart-mcp --reason after_code_change\npython .\\scripts\\external_mcp_client.py run-live-test --scenario full --archive-report\n```\n\nUse the external client when you need to test the current checkout as a real MCP\nclient without restarting Codex Desktop. It runs an independent daemon, keeps\nits own MCP stdio subprocess, and can restart only that subprocess after code\nchanges. Live test findings are written to `corrective_action_plan.md`; previous\nreports can be archived with `--archive-report`.\n\nSee [docs/EXTERNAL_MCP_CLIENT.md](docs/EXTERNAL_MCP_CLIENT.md) for the daemon\ncommands and the available live scenarios.\n\nSee [docs/RELEASE_CHECKLIST.md](docs/RELEASE_CHECKLIST.md). For public launch\npositioning, see [docs/PUBLICATION_GUIDE.md](docs/PUBLICATION_GUIDE.md).\n\n## Packaging\n\nBuild locally:\n\n```powershell\npython -m pip install build\npython -m build\n```\n\nThe wheel includes the MCP server, the hook installer, the admin helper, and the\nbundled Codex hook module.\n\nThe normal install path is:\n\n```powershell\npipx install codex-control-plane-mcp\n```\n\nor:\n\n```powershell\nuvx codex-control-plane-mcp\n```\n\n## Contributing\n\nRead [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md) before\nopening issues that include diagnostics.\n\nGood GitHub topics for this repo:\n\n`python`, `mcp`, `mcp-server`, `model-context-protocol`, `openai-codex`,\n`codex`, `codex-desktop`, `agent-tools`, `ai-agents`, `developer-tools`,\n`automation`, `orchestration`, `agentic-workflows`, `long-running-tasks`,\n`openclaw`, `hermes`, `hermes-agent`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faresyn%2Fcodex-control-plane-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faresyn%2Fcodex-control-plane-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faresyn%2Fcodex-control-plane-mcp/lists"}