Codexus

Korean

Codexus runs OpenAI's Codex CLI with evidence.

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

Plain Codex CLI	With Codexus
A task can look done before tests pass.	complete only after your verify command passes.
A run lives in one terminal session.	Every run has a durable ledger under .codexus/runs/<id>.
Failure output disappears into scrollback.	Failures become bounded repair context and saved evidence.
Lessons are manual.	Useful lessons can become memory or replay-gated skills.
Experimental surfaces are easy to overstate.	Gated features report what is proven, configured, or unavailable.

See It

From a shell:

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

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.

Early alpha, and intentionally honest about it: live app-server turns, routine live model replay, automatic prompt injection, and live cron/gateway dispatch remain gated off. 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 alpha package:

npm install -g codexus@next
codexus doctor --json

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@next

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 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
• Schema artifact validation, stale-lock recovery, and local CI parity
• Automatic migration from legacy .codex-harness/ into .codexus/
• Gated app-server, cron, gateway, and model-replay experiments that do not affect the stable codex exec --json path

Status

Codexus is usable as an early local harness. The stable path is the CLI around codex exec --json; live app-server turns, routine live model replay, automatic prompt injection, and live cron/gateway dispatch remain intentionally gated.

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 checkpoint "before risky refactor" --json
cx session verify --verify "npm test" --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
• Reference governance
• Implementation status
• Remaining work
• 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.

Codexus banner

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

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.