Codexus

Korean

Codexus is a harness engineering layer for OpenAI's Codex CLI.

It keeps the same local Codex engine and auth, then adds durable run ledgers, verification gates, bounded repair loops, session evidence, memory, and truthful status around the work. Tell it what to change and how to verify it; Codexus runs the local authenticated Codex CLI, runs your verification command, feeds real failure output back into a bounded repair loop when the check fails, and reports complete only when the check passes.

Every run is saved under .codexus/runs/<id>, so you can inspect, resume, verify, or cancel it even after a terminal closes or a process crashes.

Same Codex model. Same local Codex auth. More supervision, recovery, memory, and truthful status around the work.

Why Use It

See It

From a shell:

npm install -g codexus
codexus run --verify "npm test" "fix the failing parser tests"

Codexus is a command-line tool, so install it globally. The npmjs sidebar may show npm i codexus; that is npm's local dependency form and will not put the codexus / cx commands on your normal PATH.

Codexus runs Codex, then runs npm test. If the test fails, Codexus gives Codex the real failing output and retries within the configured repair budget. The run is complete only when the verification command passes.

The 0.1.x stable line is intentionally narrow: live app-server turns, routine live model replay, and automatic prompt injection remain gated off. Live cron/gateway dispatch now exists as an explicit-approval experimental surface. See Status.

Use It In Codex CLI Chat

Codexus is not only a standalone cx command. The npm package installs a Codex-native codexus skill, so you can stay inside your current Codex CLI/TUI chat and ask Codex to call the local Codexus core for evidence.

One-time project setup from a shell:

codexus setup codex-session --scope project --enable-notify-hook --json

Then type normal requests in the Codex chat:

Use the codexus skill and show the current session status.

Codexus, create a checkpoint named "before parser cleanup".

Codexus, run session verification with "npm test" and summarize the evidence.

Codexus, search memory for "parser regression" and use only relevant findings.

The current Codex conversation remains the main working loop. Codexus adds durable state, checkpoints, verification artifacts, memory lookup, replay, and skill evidence. It does not create a competing chat session.

Full guide: Using Codexus inside Codex.

Quick Start

Install the current stable package:

npm install -g codexus
codexus --version
codexus doctor --json

Use the global form above for normal CLI use. A local npm i codexus installs Codexus into the current project's node_modules and is not the recommended user install path.

Run a supervised task with verification:

codexus run --verify "npm test" "fix the failing tests"

Global npm installs also install the Codex-native skill adapter into ${CODEX_HOME:-~/.codex}/skills/codexus by default. Set CODEXUS_INSTALL_CODEX_SKILL=0 when you need a CLI-only install.

Detailed setup: Quick start.

Install Options

Install from npm:

npm install -g codexus

Install with GitHub Pages if you prefer a reviewable shell installer:

curl -fsSL https://raeseoklee.github.io/codexus/install.sh | sh

For a review-first install:

curl -fsSLO https://raeseoklee.github.io/codexus/install.sh
less install.sh
sh install.sh

Clone and verify the repository:

git clone https://github.com/raeseoklee/codexus.git
cd codexus
npm run ci
npm run lsp:check
npm run package:smoke

Core Features

• Evidence-backed run ledgers under .codexus/runs/<run-id>/
• Verification gates with bounded repair loops
• Timeout, SIGINT, and external cx cancel <run-id> cancellation paths
• Structured JSON error envelopes for automation
• Memory records, curation, and bounded retrieval
• Replay-gated skill proposal, review, promotion, improvement, export, and deprecation
• Codex-native $codexus adapter for using the same core inside a Codex session
• Session-native quality evidence guard and subagent claim recorder/completion handoff
• Schema artifact validation, stale-lock recovery, and local CI parity
• Automatic migration from legacy .codex-harness/ into .codexus/
• Gated app-server and model-replay experiments plus experimental app-instance and explicit-approval cron/gateway dispatch surfaces that do not affect the stable codex exec --json path

Status

Codexus 0.1.6 is usable as a local harness with a narrow stable path around codex exec --json; live app-server turns, routine live model replay, and automatic prompt injection remain intentionally gated. Live cron/gateway dispatch is now available as an experimental explicit-approval surface.

Support Matrix

See Implementation status and Remaining work for exact coverage and gaps.

Requirements

• Node.js 22 or newer
• npm for the installer and package workflow
• Git
• The local codex CLI for real Codex runs
• A logged-in Codex CLI session for the codex-exec driver

Most tests use a deterministic mock driver so CI does not require model or network access; real runs use the local authenticated Codex CLI.

Common Commands

cx doctor --json
cx init --with-docs --json
cx setup codex-session --scope project --always-on --enable-notify-hook --json
cx session status --json
cx session hud --json
cx session checkpoint "before risky refactor" --json
cx session verify --auto --json
cx session verify --verify "npm test" --json
cx session slop --json
cx session subagent launch --role reviewer --task "review the staged diff" --json
cx session subagent complete --task-id <id> --claim "review found no API drift" --assumptions-surfaced pass --json
cx session subagent record --file <result.json> --json
cx session workers status --json
cx lsp status --json
cx lsp check --gate --json
cx schema engine --json
cx replay parity --json
cx repo graph build --graph-provider codexus-lite --scope "src/**" --json
cx repo graph check --graph <graph-id-or-path> --gate --json
cx slop check --scope "src/**" --gate --json
cx supply-chain check --gate --json
cx release check --gate --json
cx app instance profile list --json
cx app instance start --profile web --worktree . --json
cx app instance status --json
cx app instance evidence record --instance-id <id> --kind browser --source manual --summary "checked app" --json
cx app instance evidence probe --instance-id <id> --url http://127.0.0.1:<port>/ --json
cx app instance evidence logs --instance-id <id> --json
cx app instance stop --instance-id <id> --json
cx run --verify "npm test" "fix the failing parser tests"
cx cancel <run-id> --reason "no longer needed" --json
cx status <run-id> --json
cx events tail <run-id> --json
cx verify <run-id> --json
cx replay skill <skill-id> --json
cx memory search "parser regression" --json
cx skill review <skill-id> --json
cx skill export <skill-id> --target codex --json
cx schema check --json
cx app-server experiment --dry-run --record --supervise-fake --json

Public bins: cx and codexus are canonical.

Documentation

• Documentation index
• Quick start
• Using Codexus inside Codex
• Architecture
• Detailed design
• Evolution engine
• Codex-native adapter
• Session-native supervision
• Supply-chain evidence
• Autopilot contract
• Reference governance
• Implementation status
• Remaining work
• 0.1.0 stable readiness plan
• 0.1.1 release evidence
• JSON contract
• Public release checklist

Selected documents have Korean translations under docs/ko/, and English documents link to them as Korean.

Safety Boundaries

Codexus intentionally avoids private ChatGPT/Codex backend APIs. The stable driver boundary is the local authenticated Codex CLI. Experimental surfaces are feature-gated and report dry-run, policy, approval, and evidence records before any live dispatch path is enabled.

 ░▒▓██████▓▒░ ░▒▓██████▓▒░░▒▓███████▓▒░░▒▓████████▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░░▒▓███████▓▒░
░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░      ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░
░▒▓█▓▒░      ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░      ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░
░▒▓█▓▒░      ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓██████▓▒░  ░▒▓██████▓▒░░▒▓█▓▒░░▒▓█▓▒░░▒▓██████▓▒░
░▒▓█▓▒░      ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░      ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░      ░▒▓█▓▒░
░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░      ░▒▓█▓▒░░▒▓█▓▒░▒▓█▓▒░░▒▓█▓▒░      ░▒▓█▓▒░
 ░▒▓██████▓▒░ ░▒▓██████▓▒░░▒▓███████▓▒░░▒▓████████▓▒░▒▓█▓▒░░▒▓█▓▒░░▒▓██████▓▒░░▒▓███████▓▒░

Contributing

Contributions are welcome after the repository is public. Start with CONTRIBUTING.md, SECURITY.md, and ROADMAP.md.

License

Codexus is released under the MIT License.

OpenAI and Codex are trademarks of their respective owners. This project is not affiliated with or endorsed by OpenAI.