code-yeongyu/lazycodex

LazyCodex

The one and only agent harness for complex codebases.
Project memory, planning, execution, and verified completion inside Codex.

What is this? · OmO · lazycodex.ai

npx lazycodex-ai install

One line. No global install, no npm i -g. Always use npx:

npx lazycodex-ai install

This is shorthand for npx --yes --package oh-my-openagent omo install --platform=codex. For a fully autonomous, no-TUI setup:

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

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 — 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. Full details: lazycodex.ai/docs.

npx lazycodex-ai doctor

doctor prints the installation health report: plugin cache, hooks, MCP servers, agents, and config state. Inside Codex, type $ in the composer to browse every installed skill — init-deep, ulw-loop, ulw-plan, start-work, and the rest — and hooks announce themselves with LazyCodex(<version>): ... status messages during a session.

npx lazycodex-ai uninstall

Removes the installed plugin cache, bin links, agent roles, and the managed sections of ~/.codex/config.toml.

LazyCodex installs these as OmO commands for Codex. Invoke them with the $command syntax shown by the installer.

Full documentation lives at lazycodex.ai/docs.

LazyCodex should be judged by the features it actually installs. It is the Codex distribution for OmO's agent harness: project memory, planning, execution, verified completion, skills, hooks, model routing, and diagnostics.

$init-deep generates hierarchical AGENTS.md context. It scores complex directories, writes local guidance near the code that needs it, and gives future agents landmarks before they edit. Type $init-deep in the Codex composer — the $ prefix is how every installed skill is invoked.

Use it when the repository is too large to explain from memory. Run it again when the shape of the codebase changes.

Use $ulw-plan when the work needs decisions before implementation. It writes a plan to plans/<slug>.md and does not touch product code.

Use $start-work when a plan is ready. It executes the checklist with durable Boulder progress and stops only when the plan is complete.

Use $ulw-loop when the task should keep moving until the result is verified by evidence instead of a hopeful status update.

The command layer stays simple. The skill layer adds specialist judgment for the actual work:

LazyCodex installs selectable agent roles into ~/.codex/agents/: explorer, librarian, plan, momus, metis, and codex-ultrawork-reviewer. Pick one by passing agent_type to Codex's spawn_agent tool — the child agent runs with that role's model and instructions:

spawn_agent({"message": "TASK: map the auth flow end to end.", "agent_type": "explorer"})

The installer exposes agent_type on multi_agent_v2 sessions (Codex hides it by default). If your Codex build's spawn tool has no agent_type parameter, describe the role inside message instead — the skills are written to fall back to that form automatically.

Start at https://lazycodex.ai.

LazyCodex packages OmO (oh-my-openagent) as the Codex agent harness for complex codebases.

Think LazyVim for lazy.nvim, but for Codex.

OmO is the agent harness: discipline agents, parallel orchestration, multi-model routing, skills, hooks, and verified completion. LazyCodex packages that harness for Codex.

"LazyVim made Neovim usable for the rest of us. LazyCodex does the same 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.

Do not be surprised if an OmO/LazyCodex run shows models like gpt-5.2 with xhigh, gpt-5.4-mini, gpt-5.3-codex, or newer equivalents like gpt-5.5 with xhigh. That is intentional.

OmO does not blindly spend your best model on every subtask. Its source defines task categories and fallback chains so the agent can pick the most appropriate model for the job: quick routes to gpt-5.4-mini for small edits, ultrabrain uses a high-reasoning GPT model for hard logic, and agentic coding paths can use Codex-tuned GPT models when available. See openai-categories.ts and model-requirements.ts.

The point is quota discipline: use the strongest model when the task needs deep reasoning, use a cheaper/faster model when that is enough, and keep parallel agent work efficient instead of burning premium quota on routine steps. This is benchmark-driven routing, not random model churn:

• GPT-5.2 is documented by OpenAI as stronger at code review, bug finding, and complex tool use; the announcement notes that its maximum API reasoning effort uses xhigh.
• GPT-5.3-Codex is OpenAI's Codex-tuned model for agentic software engineering, with public coding-agent benchmarks such as SWE-Bench Pro, Terminal-Bench 2.0, and OSWorld Verified reported in the GPT-5.3-Codex announcement.
• GPT-5.4 mini is positioned for efficient everyday coding, computer use, and subagents; that is why lightweight OmO tasks can land there instead of spending a frontier reasoning model.

Reference links:

• OpenAI GPT-5.2 announcement
• OpenAI GPT-5.2 model docs
• OpenAI GPT-5.3-Codex model docs
• OpenAI GPT-5.4 mini and nano announcement
• OpenAI latest model guide

LazyCodex is a thin distribution layer. The core engine is oh-my-openagent (OmO), included as a submodule under src/.

lazycodex/
├── src/                     → oh-my-openagent (submodule)
├── packages/
│   └── web/                 → Next.js 15 + Tailwind v4 + opennextjs-cloudflare
│                              (deployed to lazycodex.ai via Cloudflare Workers)
├── .github/workflows/       → web-ci.yml + web-deploy.yml
├── README.md
└── ...

LazyCodex is part of the omo.dev project. omo in Codex, packaged for the lazy.

LazyCodex is maintained by Jobdori, the AI assistant that builds and ships OmO in real-time.

MIT