CodexPro Runtime

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/codexpro is intentionally not published and package.json remains private: 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.

Why CodexPro exists

AI coding systems can generate useful plans and patches, but maintainers still need answers to four operational questions:

1. Which workspace and files may the assistant access?

2. Which side effects are enabled for this session?

3. What evidence proves that a task actually completed?

4. 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: lazy-mcp-router

Core value

90-second source verification

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:help

Optional package-surface check:

npm run pack:dry-run

These commands verify the public source tree. They do not publish a package, create a release, start a public tunnel, or connect an external account.

What you can inspect today

After building from source:

node dist/stdio.js --help
node dist/http.js --help
node scripts/codexpro-cli.mjs --help
node scripts/codexpro.mjs --help

Public entry points reserved in package.json:

How it works

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 --> M

The 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.

Why this matters for OSS maintainers

Pull requests

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.

Issues and bug reports

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.

Releases

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.

Security work

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.

Product boundary

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.

Threat boundary

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.

Execution modes

The underlying runtime supports different capability profiles. Exact flags and availability may evolve while the npm package is unpublished.

The public repository documents these concepts without claiming that a hosted service or reviewed ChatGPT app is currently available.

Public component map

See Architecture for the component relationships and trust boundaries.

Source quickstart

Install dependencies

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.

Validate

npm run typecheck
npm run build
npm run cli:help
npm run pack:dry-run

Inspect MCP server help

node dist/stdio.js --help
node dist/http.js --help

Inspect the local CLI

node scripts/codexpro-cli.mjs --help
node scripts/codexpro.mjs --help

For a fuller walkthrough, read Quickstart. Do not expose the HTTP server publicly until you understand the authentication and workspace-root controls.

Validation and evidence

The public CI workflow runs:

1. dependency installation with lifecycle scripts disabled;

2. documentation-link checks;

3. TypeScript type checking and build;

4. CLI help verification;

5. reproducible security-control and demo checks;

6. npm package-boundary verification;

7. source-candidate release-readiness checks; and

8. 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.

Adoption snapshot

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.

Public and private boundary

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.

Documentation

Repository 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.

Contributing

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-run

Do 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.

Security reporting

Please do not place vulnerability details or secrets in a public issue. Follow SECURITY.md for private reporting options and disclosure expectations.

Independent project and attribution

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.

See NOTICE.md and LICENSE.

License

MIT License. See LICENSE.