Codex Reasonix

CI CodeQL License: MIT

codex-reasonix-mcp is a security-first MCP bridge that lets Codex supervise Reasonix as the implementation worker. Codex owns the immutable contract, review, and final commit decision. Reasonix works in an isolated Git worktree through ACP Goal mode. The bridge never pushes, merges, or changes the caller's main worktree.

The core is generic to Git repositories. It contains no application-specific paths, LLM router, native-Windows implementation, or Codex source modification.

Release status

The last published stable npm release is 0.1.1. This source tree is prepared as 0.2.0-rc.4; that version is not available from npm until its GitHub prerelease and trusted-publishing workflow complete successfully. Official Reasonix v1.19.0 remains the documented compatibility baseline, while runtime capability checks—not a version string—remain authoritative.

Requirements

• Node.js 22 or newer
• pnpm 10 for source development
• Git 2.36 or newer
• Linux, macOS, or Windows through WSL; native Windows is rejected
• Reasonix v1.19.0 or a compatible newer build with ACP v1 supervisor/status capabilities and static command metadata v1
• Bubblewrap on Linux/WSL or Seatbelt on macOS (required: verification, the secret scanner, and Git hooks execute inside the OS command sandbox and fail closed when no engine is available)
• A configured Reasonix provider exposing the selected model

Reasonix, provider credentials, and provider billing remain user-managed. This package neither downloads nor bundles Reasonix.

Security posture

Repository-controlled content never executes unsandboxed: verification commands, the external secret scanner, and (when explicitly enabled) Git hooks run inside a network-disabled, filesystem-restricted OS sandbox with hidden credential stores. Git hooks are off by default (CODEX_REASONIX_RUN_GIT_HOOKS=true re-enables them through the sandbox). The Reasonix worker receives an explicitly allowlisted environment (CODEX_REASONIX_ENV_ALLOWLIST) instead of the host environment; injection variables are hard-denied. Finalize approvals and pause acknowledgments are bound to reviewed-snapshot and pause tokens, journal appends are crash-consistent, and the bridge commit requires the exact task branch.

See docs/security.md for the threat model, the proof matrix, and the configuration knobs. The matrix gates run on Linux and macOS in CI.

Install for Codex

Use the published stable package today:

codex mcp add reasonix-worker -- npx -y [email protected]

For a local checkout of this release-candidate tree:

pnpm install --frozen-lockfile
pnpm build
codex mcp add reasonix-worker -- node /absolute/path/to/codex-reasonix-mcp/dist/index.js

After 0.2.0-rc.4 is actually published, consumers can pin that exact version instead of relying on a moving dist-tag. Prereleases publish under next; stable releases publish under latest.

Diagnostics

Standard doctor is local-only and does not create an ACP session or call a provider:

codex-reasonix-mcp doctor

It checks Node, Git, platform/WSL, the Reasonix binary and supervisor flags, OS sandbox availability, state permissions, network posture, and that Codex has tool_timeout_sec = 900 under [mcp_servers.reasonix-worker]. This explicit value is required even when a Codex release provides a shorter default.

The deep lane is explicit, bounded to one Goal, 50,000 cumulative provider tokens, and ten minutes, and may incur provider cost:

codex-reasonix-mcp doctor --deep --allow-provider-call

It creates temporary source/state, proves a structured edit, static command, exact verification, final worker commit, and unchanged source repository, reports duration/usage/estimated cost, and always attempts cleanup. This lane is never implied by standard doctor. Failure reports preserve only bounded, privacy-safe partial proof and event-type diagnostics before cleanup.

MCP surface

The reasonix_worker server exposes exactly three tools:

• reasonix_delegate validates TaskContractV1, creates or resumes the isolated task, and by default waits for review, interaction, failure, or a bounded timeout.
• reasonix_control steers, answers an interaction, cancels, finalizes, or closes a task. At most two post-review repair rounds are accepted.
• reasonix_inspect reads bounded status, evidence, interactions, collision evidence, and optional paginated diffs. Events are opt-in.

Each tool advertises a concrete success schema and every successful response contains matching structuredContent. Errors remain isError responses with a redacted code, message, retryable, closed-enum next_action, and optional safe details. Delegate/control are annotated mutating, destructive, non-idempotent, and open-world; inspect is read-only, idempotent, and closed-world.

Codex calls reasonix_delegate only after explicit user request or approval for Reasonix implementation. Delegate and finalization derive repository authority from codex/sandbox-state-meta; no model-provided repository path is accepted.

The normal success path is exactly two long-running calls: one delegate with the default wait_mode: "review", then one finalize that waits for a terminal result and returns the worker commit hash. Finalize echoes the reviewed snapshot by mapping review_revision to expected_review_revision and review_tree_hash to expected_review_tree_hash. New tasks run on the worker_lane: "fast" (direct edits in Reasonix economy + normal mode, no Goal/AutoResearch/ subagents, 600-second default deadline); choose worker_lane: "deep" only for explicitly long-horizon Delivery + Goal work (3,600-second default). reasoning_effort is selected per task (low, medium, high, or max); precedence is task field, then CODEX_REASONIX_EFFORT, then medium. Choose the lowest sufficient effort. execution_timeout_seconds is a persisted per-task execution deadline; new tasks default by lane (600 fast / 3,600 deep) and may request 60–14,400 seconds. The separate delegate wait remains bounded to 600 seconds: if it expires, the call returns a recoverable running view while the worker continues. Re-delegating the same immutable task can wait again without changing its stored execution profile. There is no hard worker token ceiling. path_base defaults to the invocation cwd; use repository only for legacy repository-root path semantics. Inspect/steer are recovery tools, not happy-path polling steps.

If finalization fails, keep the retained task at review, inspect or repair it there, and finalize again using the newly reviewed snapshot. Do not manually copy the diff into the source checkout and do not close the task as a recovery shortcut.

Completion creates a commit on the retained worker branch. It does not integrate the caller's checkout: after reviewing the returned hash, Codex may explicitly git cherry-pick <hash>. The bridge never pushes or merges.

Shell-first supervision

Reasonix shell requests must carry private _meta.reasonix.io static argv v1 metadata and a cwd inside the worker worktree. The bridge then applies this precedence:

1. Audited reads such as safe rg, non-in-place sed, cat, ls, safe find, and sanitized Git reads receive one-time approval.
2. Tests, builds, formatters, package managers, project scripts, and restricted env wrappers require an exact argv plus cwd match in contract verification or allowed_commands.
3. Git mutations or ref/history rewrites, gh, remotes, publish/release, network access, credentials, privilege escalation, destructive filesystem operations, shell/eval, inline interpreters, cwd escape, and metadata mismatch are always denied. A contract cannot override these rules.
4. Unknown executables are denied with a recovery hint.

Every allowed command has a watchdog and immediate post-command scope, symlink, size, secret, and source-collision checks. Repeated identical immutable denials receive one recovery steer; the third denial in the same prompt cancels the turn and pauses the task instead of opening a permission interaction.

allowed_commands expands execution permission only. Verification commands are implicitly allowed and remain the sole source of automated acceptance evidence. See task contracts.

Collision safety and optional Codex hook

The bridge compares source dirty paths and committed movement since the task's base against write_scope on resume, before and after worker mutation, at review readiness, and throughout finalization. Overlap pauses or blocks the task without reset, stash, or deletion. This core scanner is authoritative.

An optional user hook provides an earlier guardrail for Codex Bash and apply_patch calls:

codex-reasonix-mcp hooks install --user
codex-reasonix-mcp hooks install --user --apply
codex-reasonix-mcp hooks status --user

Install/uninstall are dry runs without --apply. Installation atomically merges ~/.codex/hooks.json, preserves third-party hooks, and installs a versioned runtime in private state. You must still inspect and trust it manually through Codex /hooks; the installer does not bypass trust. The hook is a guardrail, never the collision authority.

Task retention

codex-reasonix-mcp task list
codex-reasonix-mcp task list --all --json
codex-reasonix-mcp task archive <id>
codex-reasonix-mcp task archive <id> --apply
codex-reasonix-mcp task prune --older-than 30d
codex-reasonix-mcp task prune --older-than 30d --apply

List shows active tasks by default; --all includes terminal live tasks, archives, and tombstones. Archive accepts only a terminal task whose worker worktree is clean or missing. It moves the full audit atomically and may detach a clean worktree, but never deletes the branch, ref, or commit. Prune applies only to archives at least the requested age and replaces them with permanent, integrity-bound tombstones. Mutations are dry runs unless --apply is present.

Local data and metrics

Task state uses a validated, version-gated v2 schema. Valid v1 records migrate atomically on read; corrupt, noncanonical, and unknown future versions fail closed. Private local metrics record only closed numeric/outcome classes for permissions, denial loops, commands/timeouts, collisions, lifecycle duration, verification, and provider usage. They hash task identity and never store raw prompts, argv, command output, secrets, or file contents. There is no telemetry or upload.

Develop

corepack enable
pnpm install --frozen-lockfile
pnpm check
pnpm audit --audit-level high

pnpm check includes lint, formatting, TypeScript, V8 coverage, build, package allowlist, and pack dry-run. Coverage minimums are 80% for lines, statements, and functions and 75% for branches. CI runs Verify on Node 22/24 Linux and Node 22 macOS, plus dependency audit and CodeQL—the five protected checks expected by the release train.

GitHub OIDC trusted publishing uses provenance and no long-lived npm token. The release workflow validates exact v<package-version> tags and maps prereleases to next and stable versions to latest. No local npm publish is part of the release process.

See architecture, configuration, security, troubleshooting, and CONTRIBUTING.md.

Community

• Use the structured bug report or feature request.
• Follow the Code of Conduct.
• Report vulnerabilities privately through GitHub Security Advisories, as described in SECURITY.md.

License

MIT. See LICENSE.