The one and only agent harness for complex codebases. Project memory, planning, execution, and verified completion inside Codex.
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.
| Role | Primary use |
|---|---|
explorer |
Internal codebase context: structure, call flows, test locations. |
librarian |
External docs, library contracts, latest API research. |
plan |
Plan drafting and task decomposition. |
momus / metis |
Missing decisions, edge cases, risk review. |
lazycodex-executor |
Executing specific task units from a plan. |
lazycodex-code-reviewer |
Post-implementation code quality review. |
lazycodex-qa-executor |
Real-execution-based QA. |
lazycodex-gate-reviewer |
Pre-completion verification gates. |
lazycodex-clone-fidelity-reviewer |
Clone and sync operation fidelity checks. |
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:
- Explore — map the terrain. Read the code with tools, never speculate. Fire 2-5 parallel explore subagents before writing anything.
- Plan — chart the course. Record files to modify, specific changes, and dependencies via
update_plan. - Implement — build with precision. Surgical edits that match codebase style (naming, indentation, imports, error handling) even when a greenfield would read differently.
- Verify — prove it works. LSP diagnostics on changed files, related tests, and build — in parallel where possible.
- 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.