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.
\n\n\n"LazyVim made Neovim usable for the rest of us. LazyCodex does the same for Codex."
\n
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.
| Layer | \nWhat it means in Codex | \n
|---|---|
| Commands | \n$init-deep, $ulw-plan, $start-work, $ulw-loop — workflow entry points. | \n
| Skills | \nReview, debugging, refactoring, frontend, LSP, rules injection, and more — specialist playbooks. | \n
| Hooks | \nAutomatic assistants that fire at session start, prompt submit, post-edit, post-compact, and stop. | \n
| MCP Servers | \ngrep_app, context7, codegraph, git_bash, lsp — tool connections. | \n
| Model routing | \nRole-based model profiles so planning, implementation, and verification each get the right model. | \n
| Agent roles | \nexplorer, librarian, plan, momus, metis, and executor/reviewer roles for subagent delegation. | \n
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.
The Hephaestus deep worker, ported into Codex with:
\n$ulw-plan, $start-work, and $ulw-loop workflows that keep complex work moving until it is verified.$init-deep creates project memory.$ulw-plan "what to build" sets the work order.$start-work executes the plan.$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.
\nUse {your prompt} ultrawork when the job needs the deep worker to run as one coordinated, evidence-bound loop instead of a single turn.
LazyCodex is a thin distribution layer over OmO. The core engine is OmO; LazyCodex packages OmO's Hephaestus for Codex.
\nCredit: 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.
\n\n", + "overview.md": "LazyCodex packages OmO as the Codex agent harness for complex codebases: project memory, planning, execution, and verified completion inside Codex. Think LazyVim for lazy.nvim, but for Codex.
\n\n\n"LazyVim made Neovim usable for the rest of us. LazyCodex does the same for Codex."
\n
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.
| Layer | \nWhat it means in Codex | \n
|---|---|
| Commands | \n$init-deep, $ulw-plan, $start-work, $ulw-loop — workflow entry points. | \n
| Skills | \nReview, debugging, refactoring, frontend, LSP, rules injection, and more — specialist playbooks. | \n
| Hooks | \nAutomatic assistants that fire at session start, prompt submit, post-edit, post-compact, and stop. | \n
| MCP Servers | \ngrep_app, context7, codegraph, git_bash, lsp — tool connections. | \n
| Model routing | \nRole-based model profiles so planning, implementation, and verification each get the right model. | \n
| Agent roles | \nexplorer, librarian, plan, momus, metis, and executor/reviewer roles for subagent delegation. | \n
OmO is the core agent harness: discipline agents, parallel orchestration, multi-model routing, skills, hooks, verified completion, diagnostics, and team mode. LazyCodex packages that harness for Codex through the lazycodex-ai installer and the omo@sisyphuslabs marketplace plugin.
The OmO harness, wired into Codex with:
\n$ulw-plan, $start-work, and $ulw-loop workflows that keep complex work moving until it is verified.$init-deep creates project memory.$ulw-plan "what to build" sets the work order.$start-work executes the plan.$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.
\nUse {your prompt} ultrawork when the job needs the deep worker to run as one coordinated, evidence-bound loop instead of a single turn.
LazyCodex is a thin distribution layer over OmO. The core engine is OmO; LazyCodex packages the OmO harness for Codex.
\nCredit: 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.
\n\n", "installation.md": "One command installs the OmO agent harness for Codex without a global package install.
\nnpx ships with it. Bun is not required: the installer runs on plain Node.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.
\n\nDo NOT use
\nnpm install -gorbun add -g. Always invoke vianpx.
The command is one line. No global install, no setup files.
\nnpx lazycodex-ai install\nThis 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:
\nnpx lazycodex-ai install --no-tui --codex-autonomous\nThe 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.
\nAfter 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.
\n\n\nStuck? Join the LazyCodex Discord and ask Jobdori for help.
\n
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\ncodex plugin add omo@sisyphuslabs\nOn 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.
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.
\nOnce 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:
\nnpx lazycodex-ai doctor\ndoctor explains what is set up, what is missing, and why it matters. See Configuration for provider and routing details.
Native Windows works with both install paths.
\nnpx 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.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.%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.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.
\n", "recommended-environment.md": "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.
\n| OS | \nRecommendation | \nNotes | \n
|---|---|---|
| Ubuntu | \nMost recommended | \nServer and dev environments both have predictable paths, shells, and package management. | \n
| macOS | \nRecommended | \nGood for local development. Homebrew plus Node.js/npm is all you need. | \n
| Windows | \nNot recommended | \nNative Windows shells and path differences cause unnecessary friction with hooks, CLI, file permissions, and script execution. | \n
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.
\n| Item | \nExpected state | \n
|---|---|
| Codex | \nCodex App or Codex CLI installed and logged in. | \n
| Node.js/npm | \nA maintained Node.js LTS. npx ships with npm. | \n
| Project | \nA repository opened in Codex that you want to work in. | \n
| Git | \nA Git repository so changes can be tracked and reverted. | \n
| Secrets | \nProvider keys live in the shell or Codex environment — never pasted into project files. | \n
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:
\nnode -v\nnpm -v\nnpx -v\nIf they are missing, install Node.js:
\n# Ubuntu or WSL2 Ubuntu\nsudo apt update\nsudo apt install -y nodejs npm\n\n# macOS\nbrew install node\nLazyCodex 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.
\nnpx available from a Node.js/npm install. Bun is not required.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.
\nThe simplest approach: open a new task in Codex, give it the LazyCodex GitHub link, and ask it to install.
\nhttps://github.com/code-yeongyu/lazycodex\n\nInstall LazyCodex from this repository.\nIf you prefer running the command directly:
\nnpx lazycodex-ai install\nAfter 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\nLazyCodex 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.
\nSee Configuration for provider and routing details.
\n| Command | \nUse it when | \n
|---|---|
$init-deep | \nThe repository is too large or too old to explain from memory. | \n
$ulw-plan | \nThe work needs decisions before any code is written. | \n
$start-work | \nA plan exists and should be executed to completion. | \n
$ulw-loop | \nYou want the agent to keep going until the result is verified. | \n
Start by giving the agent project context with hierarchical AGENTS.md memory:
$init-deep\nThen pick the command that matches your task.
\nIf 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.
\n$ulw-plan "add a done-toggle helper to the small task app"\nIf a plan already exists — execute it. All checkboxes must complete before it stops.
\n$start-work\nIf you want end-to-end verified completion — the loop keeps going until evidence proves the result.
\n$ulw-loop "fix the payment flow failure and verify end to end"\nStart 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.
$init-deep\n$ulw-plan "add rate limiting to the api gateway"\n$start-work plans/add-rate-limiting.md\nIf the job is small and well-understood, skip the plan and loop directly:
\nulw fix the flaky checkout test\nSee Feature coverage for the skills that add specialist judgment around these commands.
\n", - "faq.md": "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.
\nWhat is LazyCodex?\nA 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.
\nIs LazyCodex a replacement for OmO?\nNo. 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.
\nCan I ask Codex to install it for me?\nYes. 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?\nThey follow the same flow. LazyCodex installs into the Codex environment. Use whichever surface you prefer — App or CLI.
\nDo I need Bun?\nNo. 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?\nYes. 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.
\nWhat kind of tasks is LazyCodex best at?\nLarge, long-running work where planning and verification matter. Small questions or one-line fixes can go straight to Codex without the harness.
\nDo I need to study every skill before using it?\nNo. Skills auto-activate when a task matches their domain. Learn the four commands first; dig into individual skills when you hit a specific need.
\nWhich commands should I learn first?\n$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?\nOpen 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.\nOpen 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.
Is npx lazycodex-ai doctor a real thing?\nYes. 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?\nCodex 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?\nIf 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?\nIteration 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?\nLazyCodex 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.
\nHow do I pick a thinking/reasoning level?\nDo 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?\nIt 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.
\nCan I use it on desktop and continue on mobile/remote?\nLazyCodex 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.
\nTeam mode shows up but thread creation fails.\nUpdate 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?\nNot 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.
\n", + "faq.md": "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.
\nWhat is LazyCodex?\nOmO packaged for Codex. It layers commands, skills, hooks, model routing, agent roles, diagnostics, and project memory onto Codex so the agent plans before it edits and verifies before it claims done.
\nIs LazyCodex a replacement for OmO?\nNo. OmO is the core harness. LazyCodex is the Codex distribution: the npx installer plus the omo@sisyphuslabs marketplace plugin path that makes the OmO harness repeatable inside Codex.
Can I ask Codex to install it for me?\nYes. 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?\nThey follow the same flow. LazyCodex installs into the Codex environment. Use whichever surface you prefer — App or CLI.
\nDo I need Bun?\nNo. 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?\nYes. 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.
\nWhat kind of tasks is LazyCodex best at?\nLarge, long-running work where planning and verification matter. Small questions or one-line fixes can go straight to Codex without the harness.
\nDo I need to study every skill before using it?\nNo. Skills auto-activate when a task matches their domain. Learn the four commands first; dig into individual skills when you hit a specific need.
\nWhich commands should I learn first?\n$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?\nOpen 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.\nOpen 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.
Is npx lazycodex-ai doctor a real thing?\nYes. 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?\nCodex 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?\nIf 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?\nIteration 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?\nLazyCodex 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.
\nHow do I pick a thinking/reasoning level?\nDo 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?\nIt 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.
\nCan I use it on desktop and continue on mobile/remote?\nLazyCodex 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.
\nTeam mode shows up but thread creation fails.\nUpdate 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?\nNot 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.
\n", "init-deep.md": "$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.
AGENTS.md that orients agents to the project: stack, layout, conventions, and where to look first.AGENTS.md files in the directories that matter most, so an agent descending into a package gets scoped guidance instead of guessing.$init-deep\nThe 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.
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.
plans/<slug>.md — one decision-complete plan a worker executes with zero further interview.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.
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.
.omo/boulder.json survives across turns and sessions$start-work [plan-name] [--worktree <absolute-path>]\nIt 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.
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.
\nBefore 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.
\nA 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.
\n$ulw-loop "task description" [--completion-promise=TEXT] [--strategy=reset|continue]\nThe iteration cap is 500 in ultrawork mode (100 in normal mode).
\nSkills 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.
The command pillars stay simple:
\n$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 completionSkills add specialist judgment around those pillars. The sections below describe each skill and how it is typically used.
\nMost 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 | \nUse it for | \n
|---|---|
init-deep | \nHierarchical AGENTS.md context for large or old repos | \n
ulw-plan | \nExplore-first planning before coding | \n
ulw-loop | \nEvidence-bound loop until verified completion | \n
start-work | \nExecute a plan with durable Boulder progress | \n
review-work | \nFive-lane parallel post-implementation review | \n
remove-ai-slops | \nBehavior-preserving cleanup of AI-looking code | \n
frontend | \nDesigned UI work instead of generic layout filling | \n
programming | \nStrict TypeScript, Rust, Python, or Go discipline, TDD-first | \n
git-master | \nAtomic commits, rebase/squash, push safety, history investigation | \n
visual-qa | \nScreenshot/TUI diff plus dual-oracle visual QA | \n
debugging | \nEvidence-led root-cause investigation | \n
refactor | \nBehavior-preserving restructure of existing code | \n
ulw-research | \nMaximum-saturation research with codebase, web, official-docs, and OSS-repo swarms | \n
LSP | \nDiagnostics, definitions, references, symbols, and renames | \n
lsp-setup | \nConfigure language servers for a project | \n
AST-grep | \nStructural search and rewrite across code | \n
rules | \nProject instructions from AGENTS, rules, and instruction files | \n
comment-checker | \nFeedback after edit-like operations | \n
Five-lane parallel post-implementation review.
\nAfter 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.
\nExample: After finishing a PR, the user says:
\nreview my work\nThe harness spawns five parallel reviewers in separate threads, each with a focused lens. The final verdict is PASS only when every lane agrees.
\nBehavior-preserving cleanup of AI-generated code smells.
\nThe 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.
\nWhen it activates: When asked to clean, deslop, or remove AI-generated patterns.
\nExample: Combining with refactor and programming for a full cleanup pass:
ulw plan and manual qa, no behaviour changes, no regressions\n/refactor /remove-ai-slops through /programming\nThe harness plans the cleanup first, locks behavior with tests, then dispatches parallel workers by slop category — safe to dangerous order.
\nUI, UX, design, performance, accessibility, and visual QA — all in one router.
\nNot 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.
\nExample:
\nredesign the sidebar with better spacing and hit Lighthouse 100\nThe 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.
\nOne philosophy across four languages: strict types, modern stacks, TDD.
\nApplies 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.
\nExample: 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.
\nHypothesis-driven runtime debugging across any language or binary.
\nEvery 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.
\nWhen it activates: Crashes, silent failures, wrong responses, stuck processes, memory leaks, async misbehavior, or reverse engineering.
\nExample:
\ndebug this — the API returns 200 but the body is empty\nThe 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.
\nCodemap-aware, LSP- and AST-grep-powered restructuring.
\nMaps 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.
\nWhen it activates: Requests to refactor, restructure, extract, simplify, or modernize code.
\nExample:
\nrefactor the validation logic into its own module --scope=module\nThe 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.
\nScreenshot and TUI diff plus dual-oracle visual QA.
\nCaptures 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.
\nAtomic commits, rebase/squash, push safety, history investigation.
\nHandles 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.
\nMaximum-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.
\nWhen 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:
\nulw-research the typeclaw architecture — map every module and find the official docs\nThe skill fans out 10+ parallel search lanes across GitHub, official docs, and web sources, recursively expands promising leads, then synthesizes a cited report.
\nLanguage-server diagnostics, definitions, references, symbols, and safe renames.
\nGives 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.
\nWhen it activates: Automatically after edit-like tool calls (diagnostics), and on demand for navigation and renames.
\nStructural search and rewrite across 25 languages.
\nFinds 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).
Language-server installation and workspace wiring.
\nConfigures 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.
\nWhen it activates: When diagnostics are missing, definitions cannot be resolved, or a project needs LSP support before a refactor or programming task.
\nProject instruction injection from repository and user rule files.
\nAutomatically 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.
\nImmediate feedback after edit-like operations.
\nAfter 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.
\nLazyCodex 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:
\nnpx lazycodex-ai install\nThat 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.
\nThe command pillars and the disciplines behind them are covered in depth: ulw-plan, ulw-loop, start-work, TDD, manual QA, and git workflow.
\n", "ultrawork.md": "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.
\n\n"Plan, execute, verify, and keep the evidence attached."
\n
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.
\nJust include the word in your prompt. Nothing else to configure.
\nulw add authentication\nfix the flaky checkout test ultrawork\nThe 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.
$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:
| File | \nRole | \n
|---|---|
.omo/ulw-loop/brief.md | \nOriginal request and persistent constraints | \n
.omo/ulw-loop/goals.json | \nGoals and success criteria | \n
.omo/ulw-loop/ledger.jsonl | \npass, fail, block, steering, checkpoint records | \n
Saying "done" is not enough. Each success criterion requires evidence captured from a real surface, and that evidence must pass before the loop stops.
\nThe exact syntax and flags live in the $ulw-loop command docs.
The loop does not run forever. The latest $ulw-loop workflow uses these caps:
| Condition | \nLimit | \n
|---|---|
| Iterations on one goal without a full pass | \n5 cycles | \n
| Same failure on the same criterion | \n3 times | \n
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.
\n$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.
\nNamed 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.
\nAs 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.
| Role | \nPrimary use | \n
|---|---|
explorer | \nInternal codebase context: structure, call flows, test locations. | \n
librarian | \nExternal docs, library contracts, latest API research. | \n
plan | \nPlan drafting and task decomposition. | \n
momus / metis | \nMissing decisions, edge cases, risk review. | \n
lazycodex-executor | \nExecuting specific task units from a plan. | \n
lazycodex-code-reviewer | \nPost-implementation code quality review. | \n
lazycodex-qa-executor | \nReal-execution-based QA. | \n
lazycodex-gate-reviewer | \nPre-completion verification gates. | \n
lazycodex-clone-fidelity-reviewer | \nClone and sync operation fidelity checks. | \n
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.
\nHephaestus runs a short, tight loop on every unit of work:
\nupdate_plan.completed, blocked (one-line reason), or removed (one-line reason).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.
$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.
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.
LazyCodex installs OmO's discipline-agent surface into Codex. Hephaestus remains the autonomous deep-worker voice for end-to-end implementation, while specialist roles support exploration, external research, planning, review, QA, and completion gates.
\nNamed 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.
\nThe current install provides these roles. When Codex exposes agent_type, the role is set directly; otherwise the role description is included in the message as a fallback.
| Role | \nPrimary use | \n
|---|---|
explorer | \nInternal codebase context: structure, call flows, test locations. | \n
librarian | \nExternal docs, library contracts, latest API research. | \n
plan | \nPlan drafting and task decomposition. | \n
momus / metis | \nMissing decisions, edge cases, risk review. | \n
lazycodex-executor | \nExecuting specific task units from a plan. | \n
lazycodex-code-reviewer | \nPost-implementation code quality review. | \n
lazycodex-qa-executor | \nReal-execution-based QA. | \n
lazycodex-gate-reviewer | \nPre-completion verification gates. | \n
lazycodex-clone-fidelity-reviewer | \nClone and sync operation fidelity checks. | \n
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.
\nHephaestus runs a short, tight loop on every unit of work:
\nupdate_plan.completed, blocked (one-line reason), or removed (one-line reason).The parent Codex session keeps final ownership of goals and verification. For parallel work it can spawn Codex subagent roles and keep the parent session live with brief status updates while children run. Team mode adds a durable named-team surface when coordination is worth the overhead.
\n$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.
OmO's broader orchestration ideas show up in Codex through durable .omo/boulder.json progress, Stop-hook continuation, named team state, and reviewer/gate roles. $start-work is the main visible path: it advances the plan until every checkbox is done and the final gate is satisfied.
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.
\nThe 4.12.1 bundled model-catalog.json centers the default profile on gpt-5.5:
| Profile | \nModel | \nReasoning | \n
|---|---|---|
| Default | \ngpt-5.5 | \nhigh | \n
| Plan mode | \ngpt-5.5 | \nxhigh | \n
| Worker | \ngpt-5.5 | \nhigh | \n
| Verifier | \ngpt-5.5 | \nhigh | \n
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.
\nRole-based profiles separate work by nature:
\nThis pairs with Agent Roles. Even when multiple roles move in parallel, each role's model profile is tracked in the Codex configuration.
\nRouting 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.
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.
\nmodel-catalog.json and the models your Codex build supports take precedence.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.
\n", "hooks-lifecycle.md": "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.
\n| Event | \nWhat fires | \n
|---|---|
SessionStart | \nProject rules loading, telemetry, auto-update check, bootstrap provisioning, CodeGraph bootstrap. | \n
UserPromptSubmit | \nProject rules re-injection, ultrawork trigger detection, $ulw-loop steering. | \n
PreToolUse | \nGit Bash MCP guidance on Bash calls, $ulw-loop goal budget protection on goal creation. | \n
PostToolUse | \nComment checker, LSP diagnostics, CodeGraph init guidance, apply_patch rule matching, thread title hygiene. | \n
Stop / SubagentStop | \n$start-work continuation, LazyCodex executor evidence verification. | \n
PostCompact | \nGit Bash notification, project rules, and LSP diagnostics cache resets. | \n
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.
\nProgress 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.
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.
\nDuring 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.
\nThe hooks above are thin entry points into these installed components:
\n| Component | \nResponsibility | \n
|---|---|
rules | \nProject rules at session start, prompt submit, apply_patch, and post-compact. | \n
bootstrap | \nLazyCodex install state and provisioning checks. | \n
telemetry | \nSession start recording. | \n
comment-checker | \nComment feedback after edit-like tool calls. | \n
lsp | \nLanguage-server diagnostics after edit-like tool calls and cache reset after compact. | \n
ultrawork | \nUltrawork trigger detection at prompt submit. | \n
ulw-loop | \nLoop steering and goal budget protection. | \n
start-work-continuation | \n$start-work execution continuation. | \n
git-bash | \nGit Bash MCP guidance on Bash calls and post-compact. | \n
codegraph | \nCodeGraph bootstrap and init guidance. | \n
teammode | \nThread title hygiene checks. | \n
lazycodex-executor-verify | \nSub-agent evidence verification. | \n
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.
Every request is classified first:
\nCOMMIT — 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.
\nCommits 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.
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.
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.
\nStrict 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.
\nGiven / When / Then. Run it. Confirm it fails for the right reason — not a typo or a missing import.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.
\nA 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.
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.
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.
\nManual 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.
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:
\nThe harness synthesizes the two passes into one PASS | REVISE | FAIL verdict with located findings.
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.
| Lane | \nRole | \nAsks | \n
|---|---|---|
| 1 | \nGoal Verifier | \nDid we build what was asked? | \n
| 2 | \nQA Executor | \nDoes it actually work? | \n
| 3 | \nCode Reviewer | \nIs the code well-written? | \n
| 4 | \nSecurity Auditor | \nIs it secure? | \n
| 5 | \nContext Miner | \nDid we miss any context? | \n
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.
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.
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.
\nLazyCodex 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.
\nnpx lazycodex-ai install\nNo global install. Always npx. This is shorthand for npx --yes --package oh-my-openagent omo install --platform=codex.
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:
\nnpx ships with it. Bun is not required.AGENTS.md and rule files that shape agent behavior per repository.~/.config/opencode/skills and ~/.agents/skills.The default installer is interactive (TUI). It detects subscriptions, helps with model selection, and walks provider auth.
\nnpx lazycodex-ai install\nFor a fully autonomous, prompt-free setup, add both flags together:
\nnpx lazycodex-ai install --no-tui --codex-autonomous\n--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.
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 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.
*_API_KEY and OAuth credentials are secrets — never log or commit them.\n\nDo not fabricate provider keys. Supply the key your chosen provider documents, via the environment, and let the installer's routing interpret it.
\n
If something looks pending or degraded, run:
\nnpx lazycodex-ai doctor\nIt 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.
\nThe 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.
\n", + "configuration.md": "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.
\nLazyCodex 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.
\nnpx lazycodex-ai install\nNo global install. Always npx. This is shorthand for npx --yes --package oh-my-openagent omo install --platform=codex.
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:
\nnpx ships with it. Bun is not required.AGENTS.md and rule files that shape agent behavior per repository.~/.config/opencode/skills and ~/.agents/skills.The default installer is interactive (TUI). It detects subscriptions, helps with model selection, and walks provider auth.
\nnpx lazycodex-ai install\nFor a fully autonomous, prompt-free setup, add both flags together:
\nnpx lazycodex-ai install --no-tui --codex-autonomous\n--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.
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 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.
*_API_KEY and OAuth credentials are secrets — never log or commit them.\n\nDo not fabricate provider keys. Supply the key your chosen provider documents, via the environment, and let the installer's routing interpret it.
\n
If something looks pending or degraded, run:
\nnpx lazycodex-ai doctor\nIt 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.
\nThe 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.
\n", "deploy.md": "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.
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.
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).
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.
The workflow fails the job if any check breaks:
\nhttps://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.
cd packages/web\npnpm preview # opennextjs-cloudflare build && preview\npnpm deploy # build && deploy (requires Cloudflare auth)\nThe 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.
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:
\nnpx lazycodex-ai install\n# → npx --yes --package oh-my-openagent omo install --platform=codex\nArguments after install are appended verbatim:
npx lazycodex-ai install --no-tui --codex-autonomous\n# → npx --yes --package oh-my-openagent omo install --platform=codex --no-tui --codex-autonomous\nOther subcommands forward without the platform lock:
\nnpx lazycodex-ai <args...>\n# → npx --yes --package oh-my-openagent omo <args...>\nnpx lazycodex-ai install\nInstalls the OmO agent harness into Codex: commands, skills, hooks, model routing, and verification defaults in one pass.
\nTo skip the TUI and let the installer run autonomously:
\nnpx lazycodex-ai install --no-tui --codex-autonomous\n--dry-runPlace --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\nOutput:
\nnpx --yes --package oh-my-openagent omo install --platform=codex --no-tui --codex-autonomous\n--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.
npx lazycodex-ai doctor\nPrints 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.
\nnpx ships with it. Bun is not required for the installer.\n\nDo not use
\nnpm install -gorbun add -g. Always invoke vianpx.
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\ncodex plugin add omo@sisyphuslabs\nUpgrade 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.
\nThe 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.
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.