CodexPro Runtime is a local, workspace-bounded, evidence-driven MCP control plane for AI-assisted software engineering. It provides tooling for reading, writing, validating, and managing Git workflows with full execution traceability and safety controls.
Workspace & File Inspection — Open and bind project directories; list files with tree; read single or multiple files (read, read_many_files) with line numbers; search the project with search_project; view server configuration and safety modes with server_config; and build preflight rule summaries from project and global rules via read_rule_summary.
File Editing — Create or overwrite files with write; apply targeted text replacements with edit; batch up to 50 write/replace operations via apply_patch_bundle; all return unified diffs.
Validation & Execution — Run allowlisted commands with run_validation (project checks) and bash (verification commands), both supporting durable async execution with run IDs for long builds/tests. Classify tasks into modes with classify_task to get tool-policy guidance.
Acceptance Testing — Run .codexpro/acceptance.yml profiles via run_acceptance; poll status with acceptance_status; read results with read_acceptance_result; cancel runs with cancel_acceptance.
Git Workflow — git_prepare_commit binds change sets to HEAD/evidence without staging; git_commit runs secret scans and creates one real commit; git_get_remote_state checks ahead/behind; git_push pushes exactly one commit with force-push forbidden; git_push_only pushes an existing commit; git_finalize combines commit, optional push, safety check, and security receipt; show_changes summarizes workspace diffs.
Task & Execution State — Read active tasks (current_task), unified status (task_status), and recovery plans (task_recovery); poll durable run status (run_task_status) and retrieve results (read_run_task_result); publish bounded progress reports (publish_task_report); mark tasks complete with notifications (task_complete).
Meta — The codexpro supertool wraps hidden specialist actions; all visible tools should be called directly.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@CodexPro Runtime List open tasks and show me their validation evidence"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A local, evidence-driven agent runtime and MCP control plane for open-source maintainers.
CodexPro Runtime turns an explicitly allowed source workspace into a bounded tool surface for AI-assisted engineering. It combines workspace isolation, MCP transports, controlled file and command tools, durable execution records, validation primitives, and human review boundaries in one local runtime.
中文说明 · Quickstart · Evidence demo · Release readiness · Architecture · Security model · Codex Security case · Governance · Roadmap · Contributing · Adoption evidence
Source preview. The GitHub repository is public. The npm package
@menglook/codexprois intentionally not published andpackage.jsonremainsprivate: true. No GitHub Release, Pages deployment, hosted relay, or managed service is provided.
The animation is generated from a disposable local Git workflow. Open the evidence demo for the 90-second storyboard, machine-readable result, refusal cases, and reproduction commands.
AI coding systems can generate useful plans and patches, but maintainers still need answers to four operational questions:
Which workspace and files may the assistant access?
Which side effects are enabled for this session?
What evidence proves that a task actually completed?
Where does human review remain authoritative?
CodexPro makes those questions part of the runtime instead of leaving them as prompt-only conventions.
Related MCP server: McpApp
Capability | What it provides | Maintainer benefit |
Workspace-bounded control plane | Explicit workspace roots, path guards, blocked paths, symlink checks, and conversation-scoped workspace binding | Reduces accidental cross-repository access and ambiguous execution context |
Evidence-driven execution | Structured task state, validation results, durable job records, progress receipts, and machine-readable schemas | Separates “the model said it finished” from verifiable completion evidence |
Human-controlled autonomy | Configurable read/write/bash modes, local handoff workflows, review steps, and fail-closed controls | Lets maintainers choose planning-only, bounded editing, or trusted local execution |
Composable local integration | MCP over stdio and Streamable HTTP, CLI entry points, reusable schemas, templates, and browser skill primitives | Supports local tools without requiring a hosted source-code service |
Requirements: Node.js 20 or newer and npm.
git clone https://github.com/Menglook/codexpro-runtime.git
cd codexpro-runtime
npm ci --ignore-scripts --no-audit --no-fund
npm run typecheck
npm run build
npm run cli:helpOptional package-surface check:
npm run pack:dry-runThese commands verify the public source tree. They do not publish a package, create a release, start a public tunnel, or connect an external account.
After building from source:
node dist/stdio.js --help
node dist/http.js --help
node scripts/codexpro-cli.mjs --help
node scripts/codexpro.mjs --helpPublic entry points reserved in package.json:
Entry point | Purpose | Current availability |
| MCP stdio server | Build from source |
| MCP Streamable HTTP server | Build from source |
| Runtime and task CLI | Build from source; npm package not published |
flowchart LR
A[Maintainer or MCP client] --> B[CodexPro Runtime]
B --> C[Workspace binding]
B --> D[Permission and path guards]
B --> E[Tool registry]
B --> F[Task and execution state]
E --> G[Read and search]
E --> H[Bounded writes]
E --> I[Controlled commands]
E --> J[Local handoff]
F --> K[Validation evidence]
F --> L[Progress and recovery records]
K --> M[Human review]
L --> MThe runtime is local. It exposes only the tools enabled by the current configuration and workspace policy. A model or MCP client does not gain authority merely because it can describe an action.
CodexPro can support a reviewable workflow in which an assistant:
reads only the selected repository;
searches for the affected implementation and tests;
prepares a bounded patch or handoff plan;
runs configured validation commands;
returns changed-file and evidence summaries for human review.
It does not merge a pull request, publish a release, or override repository protection by default.
A maintainer can preserve the distinction between:
issue interpretation;
repository inspection;
proposed remediation;
actual file changes;
validation results;
final maintainer decision.
This makes failed checks and incomplete evidence visible instead of collapsing everything into a single success message.
The runtime can help collect build, typecheck, package-content, and security-gate evidence. Release creation and package publication remain separate, explicit operations outside the default public workflow.
CodexPro provides path guards, secret-aware writes, redaction, configurable command modes, explicit allowed roots, and a documented threat boundary. These are risk-reduction controls, not an operating-system sandbox.
See Maintainer workflows for concrete patterns.
CodexPro Runtime is:
a local developer runtime;
an MCP server implementation;
a controlled workspace tool surface;
an execution and validation substrate;
a set of reusable schemas, templates, and CLI components.
CodexPro Runtime is not:
a hosted SaaS source-code platform;
an OpenAI product or an OpenAI-endorsed project;
a replacement for repository permissions, branch protection, code review, or operating-system isolation;
a mechanism for bypassing model, account, product, safety, or quota limits;
an autonomous publisher of packages, releases, deployments, or pull requests;
a guarantee that any particular MCP client or model will invoke every exposed tool.
The main security assumptions are explicit:
the maintainer controls the local machine and selected workspace root;
the connected MCP client may be fallible or untrusted;
file writes and command execution are side effects and must be policy-controlled;
public or non-loopback HTTP access requires authentication;
tokens, private paths, customer data, and runtime evidence must not enter the public repository;
full shell mode is a trusted-local choice, not a safe default;
symlink and path traversal checks reduce risk but do not replace OS sandboxing.
Read SECURITY.md and Security model before exposing an HTTP endpoint or enabling workspace writes.
The underlying runtime supports different capability profiles. Exact flags and availability may evolve while the npm package is unpublished.
Mode | Intended use | Generic source writes | Shell posture |
Read-only / minimal | Inspection and analysis | No | Off or tightly limited |
Handoff | ChatGPT or another planner writes bounded | No generic writes | Safe or off |
Workspace agent | Trusted local engineering session | Configurable | Safe by default; full only when explicitly selected |
Local task runner | Durable local execution and review | Controlled by task configuration | Local process boundary |
The public repository documents these concepts without claiming that a hosted service or reviewed ChatGPT app is currently available.
Area | Included public surface |
MCP | stdio and Streamable HTTP entry points, modern request handling, tool result envelopes |
Workspace | root resolution, workspace identity, conversation binding, path guards |
Execution | task state, durable jobs, process records, progress, recovery, review primitives |
Tools | read, search, bounded editing, validation, project inspection, handoff coordination |
Security | authorization decisions, redaction, secret-aware writes, blocked-path policy |
Browser | reusable browser runtime primitives and a generic skill example |
Schemas | execution, authorization, messaging, browser, task, capability, and evidence contracts |
Templates | starter project, acceptance, and memory templates |
CLI | source-level runtime and task command surfaces |
See Architecture for the component relationships and trust boundaries.
npm ci --ignore-scripts --no-audit --no-fund--ignore-scripts is used for the initial source verification so dependency installation does not execute package lifecycle scripts.
npm run typecheck
npm run build
npm run cli:help
npm run pack:dry-runnode dist/stdio.js --help
node dist/http.js --helpnode scripts/codexpro-cli.mjs --help
node scripts/codexpro.mjs --helpFor a fuller walkthrough, read Quickstart. Do not expose the HTTP server publicly until you understand the authentication and workspace-root controls.
The public CI workflow runs:
dependency installation with lifecycle scripts disabled;
documentation-link checks;
TypeScript type checking and build;
CLI help verification;
reproducible security-control and demo checks;
npm package-boundary verification;
source-candidate release-readiness checks; and
a real local-tarball fresh install in a clean temporary consumer project.
Local publication additionally requires a sanitized export boundary and secret scan. The private implementation remains the authority for production-only integrations and internal evidence.
A green CI result means the checked public source revision passed these repository checks. It does not certify a deployment, external account, hosted app, or all possible runtime configurations.
The application-preparation snapshot captured at 2026-08-03 18:31:25 UTC records 0 stars, 0 forks, 0 watchers, 1 contributor with 10 attributed contributions, 4 open issues, 0 pull requests, 0 GitHub Releases, and 7 successful public CI runs. GitHub's trailing 14-day owner traffic aggregate recorded 0 views and 0 clones. The earlier repository-creation baseline remains preserved in Adoption evidence.
The npm package is not published, so weekly and monthly downloads are not applicable, not zero. No public user count, independent case study, or third-party testimonial is claimed.
See Adoption evidence for sources, methods, live badges, maintainer-operated validation scenarios, the voluntary feedback route, and the explicit separation between this repository and upstream ecosystem metrics.
This repository excludes:
private runtime state and .codexpro execution evidence;
.ai-bridge task snapshots and local handoff records;
customer or business integrations;
production hostnames, tunnel identity, credentials, and machine-specific paths;
internal office reports and benchmark evidence;
the complete private Git history;
private deployment orchestration.
Public changes are exported through an explicit allowlist and must pass source, package-content, and secret-scanning checks before publication.
See Public boundary.
Document | Purpose |
Build and inspect the public source safely | |
Runtime layers, data flow, and component boundaries | |
Product boundary, threat assumptions, and safer defaults | |
PR, issue, release, and security workflow patterns | |
Attributable metrics, measurement method, use-case classification, and feedback route | |
What is intentionally included and excluded | |
Common source-preview setup and validation failures | |
Vulnerability reporting and hard security rules | |
Current maintainer authority, decisions, releases, and succession | |
Now/Next/Later direction and real contribution Issues | |
Participation standards and private reporting | |
Issue routes, setup, validation, licensing, and review expectations | |
Gates before npm, release, app, or hosted announcements | |
Upstream attribution and independent-maintainer status |
The repository is currently a source preview rather than a stable packaged release.
Public governance, structured Issue and pull-request entry points, the required label set, and four bounded newcomer tasks are now available. Current work is tracked in ROADMAP.md, including Issues #1, #2, #3, and #4.
GitHub Discussions remains disabled until recurring Q&A or announcements justify a separately moderated channel. No roadmap item should be interpreted as a promise of a release date or external product support.
Contributions should remain generic, reviewable, and independent of private operational configuration.
Before opening a pull request:
npm ci --ignore-scripts --no-audit --no-fund
npm run typecheck
npm run build
npm run cli:help
npm run pack:dry-runDo not include credentials, private repository contents, production URLs, customer data, local reports, or private machine paths.
Read CONTRIBUTING.md for Issue routes, focused validation, licensing, AI-assistance disclosure, and review expectations. Project authority is documented in GOVERNANCE.md, and all participation follows CODE_OF_CONDUCT.md.
Please do not place vulnerability details or secrets in a public issue. Follow SECURITY.md for private reporting options and disclosure expectations.
This repository is maintained independently by Menglook. It is not the upstream project and is not endorsed by OpenAI.
The work is derived from rebel0789/codexpro under the MIT License and contains independent modifications. Upstream stars, forks, downloads, maintainers, issues, pull requests, website traffic, and other adoption metrics are not metrics of this repository.
MIT License. See LICENSE.
Read the persisted execution and validation status for a long acceptance run returned by run_acceptance.
Inputs: run_id (required), workspace_id, conversation_id, workspace_generation. Returns: tool_result
Apply multiple write or exact-replacement operations in one compact tool call.
Inputs: operations (required), task_mode, workspace_id, conversation_id, +2 more. Returns: tool_result
Run one allowlisted verification command. In execution_mode=auto, long build, test, smoke, lint, typecheck, and validation commands return immediately with a durable run id and continue locally. Use run_task_status and read_run_task_result instead of repeating the command after a transport error. Short commands still return synchronously. Do not use bash for git status/diff or file inspection; use show_changes, tree, search, and read instead. Do not chain commands with &&, pipes, redirects, or shell file readers.
Inputs: command (required), cwd, run_id, task_mode, +7 more. Returns: tool_result
Cancel one persisted acceptance run. Queued runs are removed from the resource queue; running managed validation receives an abort signal and its process tree is terminated.
Inputs: run_id (required), owner_token (required), fencing_token (required), workspace_id, +2 more. Returns: tool_result
Classify a user task into a CodexPro task mode and return mode-specific tool policy / misuse guard guidance.
Inputs: instruction (required), task_mode, workspace_id, requested_tool, +4 more. Returns: tool_result
Stable wrapper only for hidden specialist actions. Call visible tools such as search_project, read_many_files, apply_patch_bundle, run_validation, and show_changes directly; wrapping visible actions adds avoidable routing failures. It cannot call tools disabled by the current mode.
Inputs: args, action. Returns: tool_result
Read the highest-priority current task across Goal, Durable Job, and Handoff using the unified live projection. Running and waiting work takes precedence over recent terminal history.
Inputs: workspace_id, conversation_id, workspace_generation. Returns: tool_result
Apply a targeted exact text replacement inside a workspace text file. Returns a unified diff.
Inputs: path (required), new_text (required), old_text (required), task_mode, +6 more. Returns: tool_result
Run a secret safety scan, stage only the exact selected paths, reject stale HEAD/branch or unrelated staged files, create one real commit, and verify the committed path set. This tool never pushes.
Inputs: commit_message (required), selected_paths (required), expected_branch (required), validation_refs (required), +5 more. Returns: tool_result
Precisely finalize Git changes after a scoped release safety check: merge selected_paths with authoritative expected_paths so omitted task outputs are still eligible, include explicitly named untracked files without a second hidden switch, exclude unrelated untracked files, block missing or extra paths before creating a local commit, create and validate a content-bound security receipt, block sensitive paths or unsafe/incomplete scans, verify the committed path set again, and optionally push the exact commit. Build, tests, browser validation, Acceptance, and formal certification are not rerun.
Inputs: user_intent (required), include_push, workspace_id, security_mode, +6 more. Returns: tool_result
Read the exact local HEAD and remote branch head and calculate ahead/behind state without modifying the repository or remote.
Inputs: branch, remote, workspace_id, conversation_id, +1 more. Returns: tool_result
Read the exact current change set, bind it to the current HEAD and validation evidence, and report blockers. This tool never stages, commits, or pushes.
Inputs: validation_refs (required), workspace_id, commit_message, selected_paths, +2 more. Returns: tool_result
Push exactly one full commit SHA to one named remote branch, reject unexpected remote advancement or non-fast-forward state, forbid force, and verify the remote SHA after push.
Inputs: branch (required), commit_sha (required), authorization_ref (required), expected_remote_sha (required), +4 more. Returns: tool_result
Push an already-created local commit exactly once without staging, committing, rerunning Acceptance, or requiring a clean workspace. Requires explicit push-only intent; failure returns the original Git error and a manual command.
Inputs: user_intent (required), workspace_id, conversation_id, workspace_generation. Returns: tool_result
Read the workspace already bound to this Connector conversation. This tool is strictly read-only: it never activates, rebinds, or changes the global active workspace. If the conversation is unbound, it inspects the configured default root and asks the caller to use open_workspace explicitly.
Inputs: max_depth, include_tree, workspace_id, include_skills, +2 more. Returns: tool_result
Open a local project directory. In a ChatGPT Connector request this updates only the current conversation binding and never changes the global active workspace; local CLI calls retain the global active-workspace compatibility path. Set activate=false for read-only inspection.
Inputs: path, root, activate, max_depth, +6 more. Returns: tool_result
Append one bounded ChatGPT-authored public progress update, summary, finding, or warning to an existing task in the active workspace. This is an idempotent explanatory report write only: it cannot change task, validation, Git, or completion state.
Inputs: summary (required), task_id (required), idempotency_key (required), title, +7 more. Returns: tool_result
Read a specific text file with line numbers. Avoid rereading files after write/edit unless exact final content is needed.
Inputs: path (required), end_line, max_bytes, start_line, +2 more. Returns: tool_result
Read the final persisted acceptance result and bounded report text after a long acceptance run completes.
Inputs: run_id (required), max_chars, workspace_id, conversation_id, +1 more. Returns: tool_result
Read multiple text files in one compact tool call to reduce repeated read/cat windows. Returns bounded per-file previews.
Inputs: files (required), workspace_id, conversation_id, max_total_chars, +3 more. Returns: tool_result
Build a task preflight rule summary from global CodexPro operating rules, .codexpro/project.yml, AGENTS/rules files, and .codexpro/memory/rules.md. Read-only; does not write long-term memory.
Inputs: max_rules, workspace_id, conversation_id, max_memory_file_bytes. Returns: tool_result
Read the saved result for a terminal durable run, including completed, failed, blocked, or cancelled long bash/run_validation commands. Does not duplicate the report in structured content.
Inputs: run_id (required), max_chars, workspace_id, conversation_id. Returns: tool_result
Run commands from .codexpro/acceptance.yml. Long profiles start as persistent local tasks and return a run id immediately; short checks may remain synchronous.
Inputs: profile, session_id, workspace_id, skill_receipt, +4 more. Returns: tool_result
Read the current state of a durable asynchronous run started by start_run_task or automatically returned by a long bash/run_validation command.
Inputs: run_id (required), workspace_id, conversation_id. Returns: tool_result
Run project checks with durable handling for long builds and test suites. In execution_mode=auto, long commands return immediately with a run id and continue locally; use run_task_status and read_run_task_result for the final result. Short checks still return synchronously.
Inputs: cwd, run_id, commands, session_id, +9 more. Returns: tool_result
Batch all currently known fixed-string queries into one compact call, then read returned paths with read_many_files. Do not issue one search call per symbol or repeat the same query unless this response is partial.
Inputs: queries (required), glob, path, workspace_id, +6 more. Returns: tool_result
Show CodexPro server configuration, safety modes, limits, and blocked paths. Does not reveal auth tokens.
Inputs: no named parameters. Returns: tool_result
Summarize the current workspace changes in one review-oriented result with git status, diff stats, and optional diff. Use this instead of bash git status, bash git diff, git_status, or git_diff when reviewing work.
Inputs: path, staged, include_diff, workspace_id, +1 more. Returns: tool_result
Send one local Windows notification after the entire workspace task has passed focused verification. In an active Gold Task session this first enforces the mandatory file scope, fresh validation, Git, and control-repository completion check and supplies the supervisor completion signal; outside Gold Tasks it remains optional.
Inputs: title (required), summary, next_step, workspace_id, +3 more. Returns: tool_result
Read a unified, side-effect-aware recovery plan before resuming a Goal, Durable Job, or Handoff. This tool is read-only and never replays work.
Inputs: task_id (required), workspace_id, conversation_id, workspace_generation. Returns: tool_result
Read one unified, read-only task status projected live from the authoritative Goal, Durable Job, or current Handoff state.
Inputs: task_id (required), workspace_id, conversation_id. Returns: tool_result
List files and directories inside the workspace, excluding blocked paths.
Inputs: path, max_depth, max_entries, workspace_id, +2 more. Returns: tool_result
Create or overwrite a meaningful text file inside the workspace. Returns a unified diff; do not create empty placeholder files.
Inputs: path (required), content (required), overwrite, task_mode, +5 more. Returns: tool_result
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 33 tools
There is significant overlap and confusion among tools. bash, run_validation, and run_task_status all handle durable/long-running commands with overlapping run-id semantics. Many git tools (git_commit, git_finalize, git_push_only) have overlapping commit/push responsibilities that are hard to distinguish. Additionally, run_acceptance and run_validation perform parallel validation roles, and run_task_status vs task_status vs acceptance_status all read asynchronous run state, creating genuine misselection risk.
Most tools use a consistent underscore-separated verb_noun pattern (git_commit, open_workspace, cancel_acceptance, read_many_files). However there are notable deviations: 'run_validation' uses a noun instead of a noun object, 'bash' is a bare command, and the pairing of run_acceptance/acceptance_status/read_acceptance_result versus run_validation/run_task_status/read_run_task_result follows different naming conventions for the same conceptual pattern.
With 33 tools, this server is substantially over-scoped for what appears to be a development/runtime assistant. There is heavy redundancy: three separate git commit/push tools, at least four separate status/run-task reading tools, and multiple overlapping validation tools. Several tools could be consolidated, and the count feels bloated relative to the actual distinct capabilities.
The domain (a CodexPro runtime assisting with coding, Git, validation, and task management) is quite broad and largely covered: file read/write/edit, search, patch bundling, validation, acceptance tests, git lifecycle, and task status. However, the surface is convoluted rather than cleanly complete. There are confusing gaps like multiple overlapping push/commit tools with unclear boundaries and some apparent dead-ends (e.g., git_prepare_commit feeds into git_commit but git_finalize appears to duplicate this flow without clear guidance on when each is appropriate).
Control plane for autonomous software labor. Agents claim objectives over MCP with audit trail.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
Remote MCP for Android CLI agent build gate, structured receipts, audit logs, and reviewer-ready evi