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

| 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
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 command or the cx short alias 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.2 stable contract is intentionally narrow: live app-server turns, routine live model replay, and automatic prompt injection remain gated off. Architecture checks and manual wiki context are stable only for the bounded evidence surfaces documented in Status.

Use It In Codex CLI Chat

Codexus is not only a standalone codexus 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.

Project Management Wiki

Maintainers and LLM agents should use the checked-in Project LLM Wiki for fast project context. It is a management/navigation artifact, not the experimental generated repository wiki and not a completion authority.

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.2.x is usable as a local harness with a narrow stable path around codex exec --json, stable local evidence gates, and a first stable promotion of architecture and manual wiki context surfaces. Live app-server turns, routine live model replay, and automatic prompt injection remain intentionally gated.

Support Matrix

| Surface | 0.2 status | | --- | --- | | Supervised codex exec --json runs, verification/repair, run ledger, resume/cancel/status/events | Stable path | | Codex-native $codexus skill, session status/checkpoint/verify/hud, notify-hook evidence | Stable session evidence surface | | slop check, supply-chain check, schema subset engine, replay parity, memory/skill lifecycle | Stable local evidence surfaces | | architecture check --gate, repo check --gate, release check --gate, lsp check --gate, wiki context --fresh-only --gate | Stable local evidence gates for their documented bounded contracts | | repo graph build/check/import/search/explain, wiki build/check/export, wiki context approve | Experimental graph/wiki evidence surface; context approval artifacts are visible and non-injected | | app instance profile list/status/logs/start/stop/evidence record/evidence list/probe/logs/metrics/screenshot | Experimental owned-process and observation-evidence surface; live start/stop work only for Codexus-owned instances, and observations cite an instanceId without becoming authority | | app-server, cron/gateway, LSP adapters, model replay, adapter injection, tmux workers, native subagent launch | Experimental/deferred; app-server remains read-only, cron/gateway can dispatch with explicit approval while reporting scheduler readiness gaps, LSP protocol-server lifecycle remains unavailable, and other surfaces stay status/record/launch-contract/gated | | autopilot contract layer | Experimental foundation slice implemented (plan, contract validate/approve/scope-check, run-gate, relay recorder/checker, relay adapter status); live autopilot run and active relay drivers remain deferred to the 0.2/0.3 track |

See Feature reference, 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

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

Canonical bin: codexus. Supported short alias: cx.

Documentation

• Documentation index
• Quick start
• Feature reference
• 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.2.2 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.