Documentation

One command installs the OmO agent harness for Codex without a global package install.

Prerequisites

• Node.js — any maintained LTS; npx ships with it. Bun is not required: the installer runs on plain Node.
• OpenAI Codex: the Codex App (recommended) or the Codex CLI.

LazyCodex runs inside Codex. Codex must be installed and logged in before you start. If you are setting up for the first time, the Codex App is the easier path — you can open a project and run $command directly from the GUI.

Do NOT use npm install -g or bun add -g. Always invoke via npx.

Install

The command is one line. No global install, no setup files.

npx lazycodex-ai install

This is exactly equivalent to npx --yes --package oh-my-openagent omo install --platform=codex.

To skip the TUI and run a fully autonomous, prompt-free setup:

npx lazycodex-ai install --no-tui --codex-autonomous

The installer connects commands, skills, hooks, model routing, and verification defaults into your Codex configuration. It is strongly recommended to let an LLM agent run the install — the agent handles subscription detection, model selection, and provider auth automatically.

After install, the next Codex launch asks you to approve the omo hooks in the startup review. Hooks do not run before approval.

If the install feels like too many steps, you do not have to run the command yourself. Open Codex and give it the lazycodex.ai link, then ask it to install LazyCodex. The agent reads the docs and walks the setup.

Stuck? Join the LazyCodex Discord and ask Jobdori for help.

Install from the Codex marketplace (experimental)

The npx installer above stays the primary path. As an additive, experimental alternative you can install from inside Codex itself: type /plugins, open the Add Marketplace tab ("Add a marketplace from a Git repo or local root."), and enter https://github.com/code-yeongyu/lazycodex, then install omo from the sisyphuslabs marketplace. Or from the CLI:

codex plugin marketplace add https://github.com/code-yeongyu/lazycodex
codex plugin add omo@sisyphuslabs

On the next launch, approve the omo hooks in Codex's startup review — hooks never run before approval. The first approved session prints LazyCodex bootstrap running in background — restart the session when it completes while a background worker finishes the setup (config blocks, agent roles, bin links, a pinned sg binary for the ast_grep MCP); restart when it is done. The marketplace path never touches Codex permission settings — autonomous mode remains the explicit npx lazycodex-ai install --no-tui --codex-autonomous choice.

Upgrade with codex plugin marketplace upgrade sisyphuslabs. The next startup review shows the hooks as Modified — expected after every upgrade, because the plugin files changed and the previous trust hashes no longer match — re-approve them and the following session re-runs bootstrap on the new version. If anything looks pending or degraded, npx lazycodex-ai doctor explains what and why.

Authentication

Auth targets Codex itself, not LazyCodex. The Codex CLI logs in during its own setup; the Codex App logs in through the app UI. There is no separate LazyCodex login command.

Once Codex is logged in, npx lazycodex-ai install handles subscription detection, model selection, and provider routing. If you let an LLM agent run the install, it walks the same process for you.

To check what is configured:

npx lazycodex-ai doctor

doctor explains what is set up, what is missing, and why it matters. See Configuration for provider and routing details.

Windows

Native Windows works with both install paths.

• Node: npx lazycodex-ai install needs Node.js on PATH (LTS recommended). On marketplace installs the bootstrap step provisions a pinned Node LTS runtime into %USERPROFILE%\.codex\runtime\node\ automatically when node is missing — installing Node yourself first also works and skips the download.
• Git Bash: required for shell hooks. The installer and the marketplace bootstrap both try winget install --id Git.Git -e --source winget when Git Bash is missing. If Git lives somewhere custom, set OMO_CODEX_GIT_BASH_PATH to a path like C:\Program Files\Git\bin\bash.exe.
• where bash shows C:\Windows\System32\bash.exe: that is the WSL launcher, not Git Bash — LazyCodex intentionally ignores System32 and WindowsApps bash.exe shims when resolving Git Bash. Install Git for Windows or point OMO_CODEX_GIT_BASH_PATH at a real Git Bash so the resolver finds it.
• Troubleshooting: the Windows marketplace bootstrap writes a transcript to %USERPROFILE%\.codex\plugins\data\omo-sisyphuslabs\bootstrap\ps-bootstrap.log; degraded lines look like degraded component=node reason=... hint=npx lazycodex-ai doctor. Run npx lazycodex-ai doctor for the full health report.

Let an agent do it

It is strongly recommended to let an LLM agent run the install and walk the setup for you. The agent handles subscription detection, model selection, and provider auth automatically.

The smoothest environment for LazyCodex is Ubuntu or macOS. The harness leans on shell, Git, Node.js/npm, Codex config files, and hooks — all of which behave predictably on Unix-like systems.

Operating system

If you must use Windows, run Codex and LazyCodex inside WSL2 Ubuntu rather than native Windows. Keep the project on the WSL2 filesystem for the most stable experience.

Before you install

You do not need to install Bun unless you are building LazyCodex from source. Normal install and usage go through the npx path.

Check your versions first:

node -v
npm -v
npx -v

If they are missing, install Node.js:

# Ubuntu or WSL2 Ubuntu
sudo apt update
sudo apt install -y nodejs npm

# macOS
brew install node

Author recommendations

• Start with the Codex App. Install, login, session management, and skill invocation are all visible in the GUI, which is less confusing for first-time users.
• Use ChatGPT Pro or above. The docs assume the Codex usage environment that comes with ChatGPT Pro and above.
• Try bare Codex first. If you have never used a coding agent before, spend a session with Codex alone before adding LazyCodex on top. Understanding how the base agent responds and edits files makes the harness layer easier to follow.
• Stick to supported models. Mixing in GLM, Kimi, Mimo, or other non-default model stacks is not recommended. The docs and skill flows are written around Codex and OmO defaults.

LazyCodex is a light port of OmO into Codex. It does not ship the full harness — it ports one role, Hephaestus, the autonomous deep worker, and the workflows that keep its runs honest. Think LazyVim for lazy.nvim, but for Codex.

"LazyVim made Neovim usable for the rest of us. LazyCodex does the same for Codex."

Thin distribution

LazyCodex itself is close to a small install alias. lazycodex-ai runs the OmO installer targeting the Codex platform, and the actual features come from the omo plugin.

What gets installed

Where it comes from

OmO is the full agent harness: a primary orchestrator (Sisyphus) with .omo/boulder.json session continuity, a deep worker (Hephaestus), specialist agents, multi-model routing, 54+ lifecycle hooks, and team mode. That is a lot. LazyCodex takes only the piece that matters for a focused Codex setup and packages it as a repeatable install.

What you get

The Hephaestus deep worker, ported into Codex with:

• Goal-oriented execution — you give it objectives, not step-by-step recipes.
• A tight operating loop: Explore → Plan → Implement → Verify → Manually QA.
• Parallel explore subagents so it maps the terrain before writing anything.
• The $ulw-plan, $start-work, and $ulw-loop workflows that keep complex work moving until it is verified.
• Skills, hooks, model routing, and verification defaults wired into Codex in one pass.

Remember these four

1. $init-deep creates project memory.
2. $ulw-plan "what to build" sets the work order.
3. $start-work executes the plan.
4. $ulw-loop "task" keeps going until verified.

LazyCodex wires rules loading, skills, hooks, model routing, and verification habits around this flow. Browse the sidebar docs one section at a time when you need the details.

The harness workflow

Use {your prompt} ultrawork when the job needs the deep worker to run as one coordinated, evidence-bound loop instead of a single turn.

How it fits together

LazyCodex is a thin distribution layer over OmO. The core engine is OmO; LazyCodex packages OmO's Hephaestus for Codex.

Credit: The LazyCodex name idea is inspired by LazyVim. The Ultragoal and UltraQA ideas are inspired by oh-my-codex, reimplemented from concept for this Codex setup.

• LazyCodex on GitHub
• OmO on GitHub
• Discord — #building-in-public
• lazycodex.ai

LazyCodex is most useful as a harness for complex codebases: project memory, planning, execution, verified completion, skills, hooks, model routing, and diagnostics. This page walks through install verification and the four commands you will reach for most often.

Prerequisites

• npx available from a Node.js/npm install. Bun is not required.
• Codex App or OpenAI Codex CLI.

LazyCodex connects OmO commands, skills, and hooks into Codex configuration. If Codex is working normally, the install flow is the same for App and CLI.

Install

The simplest approach: open a new task in Codex, give it the LazyCodex GitHub link, and ask it to install.

https://github.com/code-yeongyu/lazycodex

Install LazyCodex from this repository.

If you prefer running the command directly:

npx lazycodex-ai install

After install, reopen Codex and check that OmO commands and skills appear in the $ menu. The next launch asks you to approve the omo hooks in the startup review — hooks do not run before approval.

If the status shows pending or degraded, run the diagnostic first:

npx lazycodex-ai doctor

Authentication

LazyCodex has no separate login. The installer (or the agent running it) handles subscription detection, model selection, and provider auth. Codex App or Codex CLI must already be logged in, but that is a prerequisite rather than a LazyCodex-specific step.

See Configuration for provider and routing details.

The four commands

Your first run

Start by giving the agent project context with hierarchical AGENTS.md memory:

$init-deep

Then pick the command that matches your task.

If you need to plan first — this reads the repository and writes a decision-complete plan without touching product code. Approve the plan before it executes.

$ulw-plan "add a done-toggle helper to the small task app"

If a plan already exists — execute it. All checkboxes must complete before it stops.

$start-work

If you want end-to-end verified completion — the loop keeps going until evidence proves the result.

$ulw-loop "fix the payment flow failure and verify end to end"

How to choose

Start with $init-deep once per repository so agents have hierarchical AGENTS.md context to work from.

For anything ambiguous, run $ulw-plan first. It interviews you, explores the codebase in parallel, and writes a decision-complete plan to plans/<slug>.md without touching product code.

Hand that plan to $start-work to execute it: durable Boulder state, parallel subagents, strict TDD, and five evidence gates. It prints ORCHESTRATION COMPLETE when every checkbox is done.

$ulw-loop is the tightest loop — use it for a single task that must run until an oracle verifies completion. It does not plan; it executes and verifies.

A typical session

$init-deep
$ulw-plan "add rate limiting to the api gateway"
$start-work plans/add-rate-limiting.md

If the job is small and well-understood, skip the plan and loop directly:

ulw fix the flaky checkout test

See Feature coverage for the skills that add specialist judgment around these commands.

Quick answers to common sticking points. Start with Install & environment if you are setting up, First use if you are choosing a command, Execution & verification if something seems off during a run, and Conflicts & limits if you hit a wall.

Install & environment

What is LazyCodex? A light port of OmO for Codex. It layers commands, skills, hooks, and model routing onto Codex so the agent plans before it edits, verifies before it claims done, and keeps project context across sessions.

Is LazyCodex a replacement for OmO? No. It is a focused subset. The full OmO has deeper orchestration. LazyCodex takes the parts that work well inside Codex and packages them as a repeatable install.

Can I ask Codex to install it for me? Yes. Open Codex and give it the LazyCodex GitHub link or lazycodex.ai, then ask it to install. Or run npx lazycodex-ai install yourself.

Is there a difference between Codex App and Codex CLI installs? They follow the same flow. LazyCodex installs into the Codex environment. Use whichever surface you prefer — App or CLI.

Do I need Bun? No. Unless you are building LazyCodex from source, Bun is not required. Install and usage go through npx with plain Node.js/npm.

Does it work on Windows? Yes. Both the npx installer and the Codex marketplace path support Windows natively. The installer provisions Node.js and Git Bash automatically when they are missing, and shell hooks run through Git Bash. If you already have Node.js and Git for Windows installed, everything works out of the box. See the Windows section in Installation for environment variable overrides and bootstrap logs.

First use

What kind of tasks is LazyCodex best at? Large, long-running work where planning and verification matter. Small questions or one-line fixes can go straight to Codex without the harness.

Do I need to study every skill before using it? No. Skills auto-activate when a task matches their domain. Learn the four commands first; dig into individual skills when you hit a specific need.

Which commands should I learn first? $init-deep for project memory, $ulw-plan for planning, $start-work for executing a plan, and $ulw-loop for open-ended tasks that need verified completion.

How do I know the install worked? Open Codex and type $ in the input — you should see OmO commands and skills listed. On the CLI, typing ulw should activate ultrawork mode. The first real command is usually $init-deep.

The $ menu does not show any commands after install. Open a new Codex session to reload the plugin, then check whether the startup review has a pending omo hook approval. If it still does not show, run npx lazycodex-ai doctor to check install and skill loading state.

Execution & verification

Is npx lazycodex-ai doctor a real thing? Yes. It runs the OmO doctor flow and reports what is configured, what is missing, and why. Use it whenever something looks off.

Why does it ask me to approve hooks? Codex reviews hooks at startup. The omo hooks do not run until you approve them. After each upgrade the hooks show as Modified because the plugin files changed — re-approve to pick up the new version.

What should I check after an upgrade? If hooks show as Modified, re-approve them. If anything looks pending or degraded, run npx lazycodex-ai doctor for the full picture.

$ulw-loop keeps finishing too quickly — what do I do? Iteration alone does not fix vague completion criteria. Be specific about what you want collected, what verification must pass, and what the agent should investigate when data is missing. Or run $ulw-plan first to nail down the scope.

Do I need a bigger token budget? LazyCodex is not a token-saving tool. It pushes good models and enough tokens through planning, execution, and verification. For large tasks, split work into smaller units before a single thread gets too heavy.

How do I pick a thinking/reasoning level? Do not overthink it. Avoid low; use medium for everyday work; use high when failure cost is significant or review matters; save xhigh for genuinely heavy tasks.

Can LazyCodex do computer-use? It can, if the Codex session has computer-use tools connected. LazyCodex does not provide those tools itself — it directs the agent to use them during workflows and enforces stronger verification when they are available.

Conflicts & limits

Can I use it on desktop and continue on mobile/remote? LazyCodex installs into Codex, so it works wherever Codex works. The Codex App's desktop/mobile remote flow pairs well. Some features may only be fully available on the desktop app.

Team mode shows up but thread creation fails. Update LazyCodex and Codex to latest, then run npx lazycodex-ai doctor. Team mode depends on Codex desktop app features that may differ between App and CLI.

Can I use OMX alongside LazyCodex? Not recommended. Running both together can cause conflicts that burn tokens and fail silently. If the installer warns about a conflict, remove one. LazyCodex is meant to run as the sole thin layer on top of Codex.

$init-deep generates hierarchical AGENTS.md context so agents start from local guidance before touching a large repository. Run it once per project, and again whenever the architecture shifts enough that the existing context no longer reflects reality.

What it produces

• A root AGENTS.md that orients agents to the project: stack, layout, conventions, and where to look first.
• Nested AGENTS.md files in the directories that matter most, so an agent descending into a package gets scoped guidance instead of guessing.
• References to project rules, skills, and instruction files the harness should respect.

When to run it

• Onboarding a repository that is too large or too old to explain from memory.
• After a major refactor, migration, or layout change.
• When agents keep picking the wrong files or ignoring local conventions.

How to use it

$init-deep

The command walks the tree, reads the files that define how the project actually works, and writes the context. Review the generated AGENTS.md files, trim anything stale, and commit them. Agents in later turns read that context before they edit, so the first session pays for every session after it.

After init

With context in place, move to $ulw-plan when the work needs a plan, or $ulw-loop for a single verified task.

$ulw-plan is the strategic planning consultant (Prometheus). It turns an idea into a decision-complete work plan. It is a planner, NOT an implementer. When you say "do X" it produces a plan for X and never writes product code.

The flow

1. Socratic interview — ask only the forks that exploration cannot resolve. When intent is fuzzy, research to best practice instead of interrogating.
2. Parallel codebase exploration — fan out read-only subagents to ground every decision in the actual code, never in memory.
3. Metis gap analysis — name every unknown the plan depends on and either close it or surface it as an explicit fork.
4. Write the plan to plans/<slug>.md — one decision-complete plan a worker executes with zero further interview.
5. Optional Momus high-accuracy review — an adversarial pass that tries to break the plan before it ships.

Output

Questions, research, and a work plan whose every todo carries references, acceptance criteria, a QA plan, and a commit boundary. The plan records status: awaiting-approval and waits — it never begins execution itself.

Handoff

Once you approve, hand the plan to $start-work, which executes it against durable Boulder state with the five evidence gates.

$start-work executes a Prometheus work plan until every top-level checkbox is done.

How it works

• Durable Boulder state in .omo/boulder.json survives across turns and sessions
• A Stop-hook re-injects the next turn until the plan is complete
• Independent sub-tasks fan out to parallel subagents
• Strict TDD plus five evidence gates: plan reread, automated verification, manual-QA, adversarial QA, cleanup
• Progress is recorded to a ledger

Syntax

$start-work [plan-name] [--worktree <absolute-path>]

Done

It prints an ORCHESTRATION COMPLETE block when every checkbox is checked.

$ulw-loop is a self-referential development loop that decomposes work into systematic, evidence-bound steps and runs until verified completion.

How it works

The agent works continuously and emits <promise>DONE</promise> when it believes the task is complete, but that does NOT end the loop. An Oracle must verify the result first. The loop ends only after the system confirms the Oracle verified it. If verification fails, it continues with the message: "Oracle verification failed. Continuing ULTRAWORK loop."

Each step carries its own evidence: a real artifact, not a dry-run claim. Progress is checkpointed, so a long run survives restarts without losing what was already proven.

Bootstrap

Before the first run, the loop reads its full workflow reference (Bootstrap tier triage, the Execution Loop, and the Manual-QA channels table) so every later phase executes the same way. It only reads the sections the current phase needs.

Manual-QA channels

A step does not close on a status string. It closes on a captured artifact from a real surface — an HTTP call, a tmux session, or a browser — plus an adversarial pass and a cleanup receipt. See manual QA.

Syntax

$ulw-loop "task description" [--completion-promise=TEXT] [--strategy=reset|continue]

Limits

The iteration cap is 500 in ultrawork mode (100 in normal mode).

Reading more

• ultrawork mode — the mode that turns the loop into a binding verified run.
• Hooks & Lifecycle — how the Stop-hook re-injects the next turn.

Skills are specialist playbooks that LazyCodex loads on top of the command pillars. They auto-activate when a task matches their domain — you do not need to study or memorize them. Include ultrawork (or the short alias ulw) in your prompt and the harness picks the right skills internally.

When you want to call a skill explicitly, put its name in the prompt: $review-work, $remove-ai-slops, $ulw-research, and so on.

Commands

The command pillars stay simple:

• $init-deep — project memory
• $ulw-plan — decision-complete planning before coding
• $start-work — execute a plan with durable Boulder progress
• $ulw-loop — evidence-bound loop until verified completion

Skills add specialist judgment around those pillars. The sections below describe each skill and how it is typically used.

Skill index

Most skills auto-activate when a request matches their domain, so you do not need to study or manually select every skill before using LazyCodex. When you want to be explicit, put the skill name in the prompt — for example $visual-qa, $git-master, or $ulw-research.

Skill highlights

review-work

Five-lane parallel post-implementation review.

After significant work, review-work launches five sub-agents in parallel — each covering a different angle: goal/constraint verification, hands-on QA execution, code quality, security, and context mining from git history and issues. All five must pass for the review to pass. One failure means the review fails.

When it activates: After completing any meaningful implementation — especially when the change touches 3+ files or runs for 20+ minutes.

Example: After finishing a PR, the user says:

review my work

The harness spawns five parallel reviewers in separate threads, each with a focused lens. The final verdict is PASS only when every lane agrees.

remove-ai-slops

Behavior-preserving cleanup of AI-generated code smells.

The safety invariant: regression tests lock behavior before a single line is deleted. Covers obvious comments, excessive defensive code, unnecessary abstractions, dead code, duplicates, and oversized modules (250+ pure LOC triggers a full modular refactoring). Workers run in parallel batches of five, and any test failure triggers an immediate revert.

When it activates: When asked to clean, deslop, or remove AI-generated patterns.

Example: Combining with refactor and programming for a full cleanup pass:

ulw plan and manual qa, no behaviour changes, no regressions
/refactor /remove-ai-slops through /programming

The harness plans the cleanup first, locks behavior with tests, then dispatches parallel workers by slop category — safe to dangerous order.

frontend

UI, UX, design, performance, accessibility, and visual QA — all in one router.

Not a single rule file but a router. It reads design, perfection, and ui-ux-db references based on the task, then builds and verifies against the actual browser. Covers UI implementation, styling, layout, animation, Lighthouse 100, Core Web Vitals, accessibility, SEO, and React dev tools like react-scan and react-doctor.

When it activates: Any task involving UI, styling, layout, animation, design, or performance auditing.

Example:

redesign the sidebar with better spacing and hit Lighthouse 100

The skill routes to the right design references, builds to match the existing design system, then runs a real Playwright Chromium Lighthouse audit — never the Lighthouse CLI, never by weakening UX.

programming

One philosophy across four languages: strict types, modern stacks, TDD.

Applies to every .py, .pyi, .rs, .ts, .tsx, .mts, .cts, .go file. The skill gates on language, loads the matching reference set, and enforces: parse-don't-validate at boundaries, exhaustive variant matching, typed errors, no escape hatches (any, unwrap, @ts-ignore), 250 pure LOC ceiling per file, and mandatory TDD (RED → GREEN → REFACTOR).

When it activates: Automatically on any code file edit in the supported languages.

Example: The skill is always on. When editing TypeScript, it loads the TypeScript reference (Bun + Biome + strict tsconfig), enforces branded types and discriminated unions, and runs the post-write review loop: measure pure LOC, self-review seven questions, refactor if over 250 LOC.

debugging

Hypothesis-driven runtime debugging across any language or binary.

Every claim about why a bug happens must come from observed runtime state, not code reading. The skill runs a phased loop: setup and journal, form 3+ orthogonal hypotheses, investigate in parallel, escalate to independent verifiers after 2 failed rounds, confirm root cause by toggling, lock with a failing test, fix minimally, QA on the real surface, then clean up every debug artifact.

When it activates: Crashes, silent failures, wrong responses, stuck processes, memory leaks, async misbehavior, or reverse engineering.

Example:

debug this — the API returns 200 but the body is empty

The skill fires parallel investigation lanes, attaches real debuggers (pdb, node inspect, lldb, dlv), and does not close the bug until the root cause is confirmed by toggling and a failing test goes GREEN.

refactor

Codemap-aware, LSP- and AST-grep-powered restructuring.

Maps the codebase before touching anything, evaluates test coverage to set the verification strategy, plans atomic steps with rollback points, then executes with LSP renames and AST-grep structural rewrites. Any test failure during execution triggers an immediate stop and revert.

When it activates: Requests to refactor, restructure, extract, simplify, or modernize code.

Example:

refactor the validation logic into its own module --scope=module

The skill builds a dependency graph of the target, runs characterization tests to pin current behavior, then executes the restructuring step by step — verifying after each step.

visual-qa

Screenshot and TUI diff plus dual-oracle visual QA.

Captures reference and actual evidence — screenshots for web UIs, tmux capture-pane for terminal UIs — then runs a bundled pixel-diff or column-width script. Two parallel read-only oracle passes evaluate: one for design-system and functional integrity, one for visual fidelity and CJK text precision. The final verdict is a single good/bad score.

When it activates: After building or changing any UI, or when asked to verify visual correctness.

git-master

Atomic commits, rebase/squash, push safety, history investigation.

Handles commit message style detection, semantic grouping, fixup autosquash, blame, bisect, log -S, and questions like "who wrote this" or "when was this added."

When it activates: Any git operation — committing, rebasing, squashing, history search.

ulw-research

Maximum-saturation research mode (formerly ultraresearch).

Orchestrates parallel explore and librarian swarms across the codebase, the web, official documentation, and OSS repositories. Runs a recursive EXPAND loop driven by leads that workers return, verifies findings empirically by running code, and produces cited synthesis with optional reports.

When it activates: Only on explicit demand — the word ulw-research, the legacy alias ultraresearch, or any request for deep research or an ultra-precise investigation.

Example:

ulw-research the typeclaw architecture — map every module and find the official docs

The skill fans out 10+ parallel search lanes across GitHub, official docs, and web sources, recursively expands promising leads, then synthesizes a cited report.

LSP

Language-server diagnostics, definitions, references, symbols, and safe renames.

Gives the agent language-server precision via MCP tool calls. Runs diagnostics after every edit, finds definitions and references across the workspace, and performs safe renames through the language server's own workspace edit — not text find-and-replace.

When it activates: Automatically after edit-like tool calls (diagnostics), and on demand for navigation and renames.

AST-grep

Structural search and rewrite across 25 languages.

Finds code by syntactic shape rather than text — every function call matching a pattern, every import shaped like X. Rewrites are deterministic and always previewed with dryRun=true before applying. Pairs with the refactor skill for safe, large-scale codemods.

When it activates: Structural code matching, pattern-based search, or deterministic rewrites (strip as any, migrate require() to import, find empty catch blocks).

lsp-setup

Language-server installation and workspace wiring.

Configures language servers when a project does not already expose reliable diagnostics, definitions, references, and safe renames. It detects the language stack, installs or points to the right server, and validates that LSP calls work before higher-level coding or refactor skills depend on them.

When it activates: When diagnostics are missing, definitions cannot be resolved, or a project needs LSP support before a refactor or programming task.

rules

Project instruction injection from repository and user rule files.

Automatically loads project instructions from sources such as AGENTS.md, CONTEXT.md, .omo/rules/, .claude/rules/, .github/instructions/, and .github/copilot-instructions.md. There is no command to run — the harness treats these rules as active context when the plugin is enabled.

When it activates: At session start and prompt submission, so agents inherit project constraints before planning or editing.

comment-checker

Immediate feedback after edit-like operations.

After code changes, comment-checker inspects comments near the edited lines. If it flags comment drift — a comment that no longer matches the code below it — the agent must fix or justify the comment before proceeding. This catches stale comments at the moment they are introduced rather than during a later review.

When it activates: After write, edit, patch, or other edit-like tool calls when the plugin has the guardrail enabled.

Where skills live

LazyCodex installs skills as part of the OmO plugin. OmO can also load skills from project and user locations such as .codex/skills, ~/.codex/skills, .opencode/skills, ~/.config/opencode/skills, .claude/skills, .agents/skills, and ~/.agents/skills.

LazyCodex installs the Codex Light setup with:

npx lazycodex-ai install

That installer wires the Codex marketplace plugin as omo@sisyphuslabs while keeping the public package alias easy to remember.

Each skill carries deep internal references — detailed playbooks, language-specific recipes, and per-phase instructions — but none of that is something you need to read. The harness reads it for you when the skill activates.

The command pillars and the disciplines behind them are covered in depth: ulw-plan, ulw-loop, start-work, TDD, manual QA, and git workflow.

ultrawork is the headline mode. Include ultrawork (or the short alias ulw) anywhere in your prompt — like adding ultrathink — and the harness switches to maximum-precision, outcome-first, evidence-driven orchestration. Skills activate internally; you do not need to name them.

"Plan, execute, verify, and keep the evidence attached."

The principle is simple. An agent saying it is done does not mean the work is done. The work is done when observable evidence verifies it.

Usage

Just include the word in your prompt. Nothing else to configure.

ulw add authentication

fix the flaky checkout test ultrawork

The harness reads the task, picks the right skills (programming, debugging, refactor, etc.), and runs the evidence-bound loop automatically. You do not choose skills yourself unless you want to be explicit — for example $review-work or $ulw-research.

What it enforces

• Strict TDD: RED → GREEN → SURFACE → CLEAN
• At least 3 realistic QA scenarios scaled to the risk of the task
• Real manual-QA channels (HTTP call, tmux, browser, computer use, CLI stdout, data diff)
• A binding verification gate that loops until the work is genuinely done

Relationship to $ulw-loop

$ulw-loop is the command form of ultrawork discipline. The latest flow stores request, goals, success criteria, and an evidence ledger under .omo/ulw-loop:

Saying "done" is not enough. Each success criterion requires evidence captured from a real surface, and that evidence must pass before the loop stops.

The exact syntax and flags live in the $ulw-loop command docs.

Failure limits

The loop does not run forever. The latest $ulw-loop workflow uses these caps:

Evidence over hope

The loop does not stop at "I wrote some code." It stops when the result is confirmed by evidence — what check ran and what it showed — not by the agent's expected status report.

Position among commands

$ulw-loop is one of several commands, each for a different shape of work.

The typical flow: $ulw-plan produces a decision-complete plan, $start-work executes it checkpoint by checkpoint, and $ulw-loop keeps open-ended work running until a verifier approves. Detailed syntax for each command is in the Commands section.

LazyCodex ports a single discipline agent from OmO into Codex: Hephaestus, the autonomous deep worker. There is no Sisyphus orchestrator in the Codex package — Hephaestus is the one role, and it carries the whole run itself with read-only subagents for parallel exploration.

What Hephaestus is

Named after the Greek god of the forge. Goal-oriented: you give it objectives, not step-by-step recipes, and it executes them end-to-end. "The Legitimate Craftsman." Methodical, thorough, obsessive — built for deep architectural reasoning, complex debugging, and cross-domain synthesis.

Installed roles

As of 4.12.1, the following roles are installed. When Codex exposes agent_type, the role is set directly; otherwise the role description is included in the message as a fallback.

Parent session ownership

Even with multiple roles, completion judgment is never handed wholesale to a sub-agent. The parent Codex session keeps ownership of goals, constraints, and final judgment. Sub-agents are used to read terrain, find gaps, or assist review.

The operating loop

Hephaestus runs a short, tight loop on every unit of work:

1. Explore — map the terrain. Read the code with tools, never speculate. Fire 2-5 parallel explore subagents before writing anything.
2. Plan — chart the course. Record files to modify, specific changes, and dependencies via update_plan.
3. Implement — build with precision. Surgical edits that match codebase style (naming, indentation, imports, error handling) even when a greenfield would read differently.
4. Verify — prove it works. LSP diagnostics on changed files, related tests, and build — in parallel where possible.
5. Manually QA — drive the artifact through its real surface (HTTP call, tmux, browser), then write the final message.

Non-goals

• Never trusts subagent self-reports. Verification is independent; a child saying "done" does not close the work.
• Never proposes when you asked for code. Unless you explicitly want a plan or a brainstorm, it implements.
• Never speculates about code it has not read. Exploration is cheap; assumption is expensive.
• Never leaves work unresolved at end of turn. Every plan step is reconciled: completed, blocked (one-line reason), or removed (one-line reason).

Delegation, not orchestration

Hephaestus stays the parent. For parallel exploration it spawns read-only Codex subagent roles (multi_agent_v1.spawn_agent) and keeps the parent session live with brief status updates while children run. It does not hand the run off to a separate orchestrator — it owns the goal, delegates the grunt work, and verifies the results itself.

Boulder state

$start-work uses .omo/boulder.json to persist progress and the Stop-hook continuation to keep plan execution moving. This is the core visible behavior: checkboxes advance, and when all are done it prints ORCHESTRATION COMPLETE.

Where the boulder comes from

The full OmO has a second primary agent, Sisyphus, the orchestrator with .omo/boulder.json session continuity. The Codex package is the Hephaestus-only light port, so on Codex the durable progress state lives in .omo/boulder.json as written by $start-work and the Stop-hook continuation — without the Sisyphus orchestration layer.

Reading more

• ultrawork mode — the mode that turns the loop into a binding verified run.
• Hooks & Lifecycle — how the Stop-hook re-injects the next turn until the plan is complete.

Multi-model routing sends each part of a run to the model that fits it best, instead of running everything on one model. LazyCodex installs OmO's routing defaults into Codex so a serious repository is not bottlenecked by a single context window or price point.

Current baseline

The 4.12.1 bundled model-catalog.json centers the default profile on gpt-5.5:

The actual model name you see may differ as Codex and OpenAI update their model lineup. This doc focuses on how LazyCodex uses model profiles, not on comparing specific models.

What gets routed

• Planning and exploration go to a strong reasoning model that can hold a large context and weigh trade-offs.
• Implementation turns go to a fast, capable coding model for the bulk of the edit loop.
• Verification goes to a model used as an oracle, chosen for judgment rather than throughput.
• Specialist skills can target their own model when a skill benefits from a specific profile.

Why role profiles exist

Role-based profiles separate work by nature:

• General tasks follow the default model setting.
• Plan mode may demand stronger reasoning.
• Worker and verifier are kept separate so the same result is checked from a different angle.

This pairs with Agent Roles. Even when multiple roles move in parallel, each role's model profile is tracked in the Codex configuration.

How it fits the harness

Routing is part of the harness setup that npx lazycodex-ai install wires into Codex. It detects the available subscriptions and provider auth, then maps roles to models so you do not hand-configure each one.

Provider auth

Auth targets Codex itself, not LazyCodex. Once Codex is logged in, the installer's subscription detection and provider routing take over. If you let an LLM agent run the install, it walks the same detection and selection for you.

User notes

• The model name you see after install may differ from what the docs list. The installed model-catalog.json and the models your Codex build supports take precedence.
• Model settings balance quality and speed. Lowering them arbitrarily can degrade planning, review, and QA quality together.
• When in doubt, check install state and Codex config first.

Customizing it

Routing and provider settings live in the configuration. See Configuration for the fields that control which model handles which role, and how to override the defaults per project.

Hooks and lifecycle are how the harness keeps a long run moving without you re-prompting every turn. OmO installs lifecycle hooks into Codex that observe each turn and decide what happens next.

Trigger matrix

The core mechanism

A Stop-hook fires when a turn ends. If a plan is still in progress, the hook re-injects the next turn automatically — the agent continues from durable progress state instead of waiting for you to say "continue". The run only stops when the plan is complete or a gate fails in a way that needs a human.

Where progress lives

Progress state is written to .omo/boulder.json and survives across turns and sessions. That is what lets $start-work resume a plan after a restart, and what keeps $ulw-loop honest about how far it has actually gotten.

Approval and trust

Hooks never run before approval. On the first launch after install, Codex's startup review asks you to approve the omo hooks. After every upgrade the hooks show as Modified — expected, because the plugin files changed and the previous trust hashes no longer match — re-approve and the next session re-runs bootstrap on the new version.

Evidence gates

During execution the lifecycle enforces five evidence gates before a step can close: plan reread, automated verification, manual-QA, adversarial QA, and cleanup. A step that cannot pass its gates does not advance, regardless of what the status text claims.

Installed components

The hooks above are thin entry points into these installed components:

Reading more

• ultrawork mode — the mode that turns these gates into a binding loop.
• Configuration — how to tune hook behavior and lifecycle defaults.

Git work runs through the git-master skill. It is exact, conservative, and evidence-led: the agent reads the repository state before it infers anything, and never commits, rebases, pushes, force-pushes, resets, or stash-pops unless you explicitly asked for that operation.

Mode gate

Every request is classified first:

• COMMIT — stage and commit local changes.
• REBASE — rebase, squash, fixup, autosquash, reorder, or split branch history.
• HISTORY — answer when, where, who, why, or which commit changed something.
• STATUS — inspect branch, diff, or working-tree state without changing it.

Investigative requests report findings and stop.

Commit mode

Commits are atomic by behavior, module, and revertability. The agent detects message style from recent history (dominant pattern, language, casing — it does not default to Conventional Commits unless the repo uses them), inspects the full diff, and stages by path or hunk so each commit contains only its group. Implementation and its direct tests land together; unrelated concerns split into separate commits. Before each commit it verifies git diff --staged --stat; after, git log -1 --oneline.

Rebase and merge

History rewriting is a shared-impact operation. The agent never rebases or rewrites main, master, dev, release, or protected branches unless you named that exact operation. If commits may already be pushed, it asks before force-pushing and uses --force-with-lease, never plain --force. Conflicts are resolved by intent — never a blind ours/theirs. If a rebase goes wrong, git rebase --abort is the first move; the reflog is the recovery path, explained before use.

Push safety

Before any write to history: the current branch is known, dirty work is accounted for, upstream/pushed status is known or explicitly unknown, the operation matches your request, and the recovery path is known. Afterward it runs the cheapest relevant verification and leaves the worktree state explicit.

Reading more

• start-work — the executor that lands planned work as commits.
• manual QA — the gates a step passes before it is allowed to close.

Strict test-driven development is the discipline that lets the harness call work "done" without hoping. Every change follows the red → green → refactor loop, in that order. Reverse it and you have written speculative code.

The order

1. Red. Write a failing test that names the behavior in Given / When / Then. Run it. Confirm it fails for the right reason — not a typo or a missing import.
2. Green. Write the minimum code to make it pass. Resist the second case until the first passes; the second case is the next red.
3. Refactor. With the test green, restructure ruthlessly. If the test is hard to refactor against, the test is bad — fix it before the code.

The test pyramid

Every feature ships all three rungs: many fast units (pure-function correctness across happy, edge, boundary, and error paths, < 10 ms each), some integrations against the real downstream via testcontainers or httptest (< 1 s each), and a few E2E scenarios that drive the binary through its real surface and assert the observable outcome. A feature with zero E2E coverage is undone, even if every unit passes.

Deterministic, or it is broken

A test that passes 9 of 10 times is failing 10% of the time. Forbidden in test bodies unless time itself is the system under test: setTimeout(resolve, N), await sleep(N), "wait long enough for X". The replacement is subscribe-first, timeout-bound — register the listener before the trigger, then race against an explicit circuit breaker that fails with a useful message on timeout. The whole repo must pass bun test in one process, one go, no isolation flags, no retries.

Prompt tests assert behavior, not text

When testing code that builds an LLM prompt, never pin the current wording (toContain("You are Sisyphus"), toMatchSnapshot, toBe(EXPECTED_PROMPT)). Assert the structural invariant the logic enforces — the conditional branch, the negative branch, the redaction, the skill inclusion/exclusion. Test what would break the behavior, never what would only break a diff.

The five evidence gates

During execution the lifecycle enforces five gates before a step can close: plan reread, automated verification, manual QA, adversarial QA, and cleanup. A step that cannot pass its gates does not advance, regardless of what the status text claims.

Reading more

• ultrawork mode — the mode that makes the loop binding.
• start-work — where the five gates are enforced per checkbox.

Manual QA is the gate that turns "it should work" into "it works, here is the proof". No step closes on a status string; it closes on a captured artifact from a real surface, plus an adversarial pass and a cleanup receipt. Two skills carry this: visual-qa for UI surfaces, review-work for whole-implementation review.

visual-qa

For any UI you built or changed — web page or TUI — visual QA runs three phases. First it captures objective reference evidence with a bundled diff script: image-diff for screenshots (similarity score, hotspots, alphaChannelIntact), tui-check for terminal captures (maxWidth, overflowLines, borderMisaligned, wide-char columns). That JSON is reference, not the verdict.

Then it dispatches two read-only oracle subagents in parallel:

• Pass A — design-system and functional integrity. The deeper, stricter pass. Proves the surface is a real design-system implementation driven by coherent tokens and reused primitives, not a mock-only screen or a pasted raster faked as live elements. Checks alpha, responsiveness, and that the user-intended features actually work.
• Pass B — visual fidelity and CJK precision. The focused pass. Opens the screenshots directly and inspects source/content for clipping, baseline drop, glyph breakage, and Korean/Japanese/Chinese precision.

The harness synthesizes the two passes into one PASS | REVISE | FAIL verdict with located findings.

review-work

After significant implementation, review-work launches five parallel background subagents. All five must pass for the review to pass; if one fails, the review fails.

Oracle lanes receive the diff plus full file contents in the prompt (they cannot read files). A crashed, BLOCKED:, or inconclusive lane is never counted as a pass — it is respawned smaller, and if the retry budget is exhausted it stays INCONCLUSIVE while the aggregate result still emits.

Adversarial classes and cleanup

Within $start-work, every checkbox probes each applicable adversarial class and records the observable result for each; skipped classes need a one-line not-applicable reason in the ledger. Every QA resource — scripts, tmux assets, browser sessions, PIDs, ports, containers, temp dirs — is registered as its own teardown todo and executed with a captured receipt. No QA asset is left running.

Reading more

• TDD — the automated-verification gate that precedes manual QA.
• ulw-loop — the loop whose completion depends on this gate.

LazyCodex is a thin distribution layer over OmO. The configuration that the installer writes into Codex controls model routing, hooks, skills, and the agent roles the harness uses.

Zero-config by default

LazyCodex ships with sensible defaults and works immediately after install. You only need to touch configuration when the defaults do not fit your repository. There are no config files to create in advance — install and start working.

npx lazycodex-ai install

No global install. Always npx. This is shorthand for npx --yes --package oh-my-openagent omo install --platform=codex.

Codex target

LazyCodex always targets Codex. The --platform=codex argument is baked into the lazycodex-ai bin's install path, so the harness connects to the OpenAI Codex CLI and not another platform. You do not pass --platform yourself.

Prerequisites:

• Node.js — any maintained LTS; npx ships with it. Bun is not required.
• OpenAI Codex CLI or the Codex App, logged in.

Where config lives

• Codex configuration that the installer connects to.
• Project-level AGENTS.md and rule files that shape agent behavior per repository.
• User-level skill locations such as ~/.config/opencode/skills and ~/.agents/skills.

Install flags

The default installer is interactive (TUI). It detects subscriptions, helps with model selection, and walks provider auth.

npx lazycodex-ai install

For a fully autonomous, prompt-free setup, add both flags together:

npx lazycodex-ai install --no-tui --codex-autonomous

--no-tui --codex-autonomous are passed through to omo install — the lazycodex-ai bin does not interpret them itself. It is strongly recommended to let an LLM agent run the install: the agent handles subscription detection, model selection, and provider auth automatically.

What you can tune

• Model routing — which model handles planning, implementation, verification, and specialist skills. The installer sets sensible defaults from your detected subscriptions; override per role when a project needs a different profile.
• Hooks and lifecycle — whether the Stop-hook auto-continues a plan, iteration caps (500 in ultrawork mode, 100 in normal mode), and how completion is gated.
• Skills — which skills are active and where they load from.
• Agent — Hephaestus, the autonomous deep worker, and its model/prompt overrides. The Codex package is the Hephaestus-only light port; the full OmO's Sisyphus orchestrator is not included.

Hooks & lifecycle

Hooks never run before approval. On the first launch after install, Codex's startup review asks you to approve the omo hooks. After every upgrade the hooks show as Modified — expected, because the plugin files changed and the previous trust hashes no longer match. Re-approve and the next session runs the new version's bootstrap.

Provider & model settings

Provider and model settings are managed by OmO, not LazyCodex directly. During install, OmO reads the Codex configuration and the bundled model-catalog.json to align model profiles — this is the model routing layer.

• The installer connects provider auth for you. Letting an agent run the install is the recommended path.
• Provider keys are read from the environment. All *_API_KEY and OAuth credentials are secrets — never log or commit them.
• Deeper provider and model tuning beyond the install follows OmO conventions. See the OmO docs for provider environment variables and model resolution rules.

Do not fabricate provider keys. Supply the key your chosen provider documents, via the environment, and let the installer's routing interpret it.

Diagnosing config

If something looks pending or degraded, run:

npx lazycodex-ai doctor

It explains what is misconfigured and why, and points at the specific field to fix. It checks plugin cache, hooks, MCP servers, agent roles, and Codex config state.

Re-running setup

The installer is idempotent. Re-running npx lazycodex-ai install rewrites the config blocks, agent roles, and bin links on top of what is there, so it is safe to run after editing configuration by hand.

See the CLI reference for every command the installer exposes.

The docs site at lazycodex.ai deploys automatically to Cloudflare Workers. There is no manual publish step for the web — a push to main that touches the web package ships it.

Trigger

The Web Deploy (Cloudflare Workers) workflow runs on push to main when packages/web/** or the workflow file itself changes, and on manual workflow_dispatch. A concurrency group keyed by ref serializes runs and never cancels an in-flight deploy.

Build

Inside packages/web, the prebuild step regenerates lib/docs-content.generated.ts from content/docs/*.md. The site is then built with OpenNext for Cloudflare (pnpm exec opennextjs-cloudflare build).

Deploy

cloudflare/wrangler-action@v4 runs wrangler deploy (or deploy --env <environment> when an environment is supplied) against the web-production environment, whose URL is https://lazycodex.ai.

Post-deploy smoke checks

The workflow fails the job if any check breaks:

• Apex https://lazycodex.ai/ returns 200.
• www.lazycodex.ai, lazycodex.dev, and www.lazycodex.dev each return 301 redirecting to https://lazycodex.ai.

A PageSpeed Insights pass audits the live URL for Lighthouse 100/100/100/100 across performance, accessibility, best-practices, and SEO, on both mobile and desktop. It is non-blocking here because PSI shared quota throttles frequent CI; the gating Lighthouse check runs in web-ci.yml via real Playwright Chromium.

Local preview

cd packages/web
pnpm preview   # opennextjs-cloudflare build && preview
pnpm deploy    # build && deploy (requires Cloudflare auth)

Reading more

• Skills — what the docs site documents.
• Configuration — tuning that affects the build.

The lazycodex-ai CLI is the entry point for installing and diagnosing the harness. It is meant to be run through npx — never install it globally.

Forwarding to OmO

The bin reads its arguments and forwards them to oh-my-openagent. The install subcommand is special-cased to lock the Codex platform target; everything else passes through as-is.

install expands to:

npx lazycodex-ai install
# → npx --yes --package oh-my-openagent omo install --platform=codex

Arguments after install are appended verbatim:

npx lazycodex-ai install --no-tui --codex-autonomous
# → npx --yes --package oh-my-openagent omo install --platform=codex --no-tui --codex-autonomous

Other subcommands forward without the platform lock:

npx lazycodex-ai <args...>
# → npx --yes --package oh-my-openagent omo <args...>

install

npx lazycodex-ai install

Installs the OmO agent harness into Codex: commands, skills, hooks, model routing, and verification defaults in one pass.

To skip the TUI and let the installer run autonomously:

npx lazycodex-ai install --no-tui --codex-autonomous

--dry-run

Place --dry-run as the first argument to print the resolved npx command without executing it:

npx lazycodex-ai --dry-run install --no-tui --codex-autonomous

Output:

npx --yes --package oh-my-openagent omo install --platform=codex --no-tui --codex-autonomous

--dry-run is stripped before forwarding, so the remaining arguments are interpreted exactly as they would be in a real run. Use it to verify the exact omo call before executing.

doctor

npx lazycodex-ai doctor

Prints a health report: what is configured, what is missing, and why. Checks plugin cache, hooks, MCP servers, agent roles, and Codex config state. Run this first when a hook is pending, a skill is not loading, or routing looks wrong.

Prerequisites

• Node.js — any maintained LTS; npx ships with it. Bun is not required for the installer.
• The OpenAI Codex CLI or the Codex app, logged in.

Do not use npm install -g or bun add -g. Always invoke via npx.

Marketplace alternative

As an additive, experimental path you can install from inside Codex: type /plugins, open the Add Marketplace tab, and enter https://github.com/code-yeongyu/lazycodex, then install omo from the sisyphuslabs marketplace. Or from the CLI:

codex plugin marketplace add https://github.com/code-yeongyu/lazycodex
codex plugin add omo@sisyphuslabs

Upgrade with codex plugin marketplace upgrade sisyphuslabs. After an upgrade the hooks show as Modified — expected, because plugin files changed and the previous trust hashes no longer match. Re-approve and the next session runs the new version's bootstrap.

The npx installer above stays the primary path. See Installation for the full walkthrough.

Exit behavior

The bin executes the resolved command with inherited stdio and exits with that command's status code. If npx itself fails to spawn, it prints the error and exits non-zero.

In-session commands

Once installed, LazyCodex registers OmO commands inside Codex. These are $command invocations in the Codex input — not shell commands. Syntax and usage flows are collected in the Commands section.