# oh-my-codex (OMX)

> A workflow layer that makes OpenAI Codex CLI sessions start stronger

- Category: AI Coding / AI SDLC Automation
- Language: TypeScript
- Licence: MIT
- Repository: https://github.com/Yeachan-Heo/oh-my-codex
- Website: https://oh-my-codex.dev
- Canonical page: https://ai-tldr.dev/tools/oh-my-codex/
- Updated: 2026-04-07

## In short

oh-my-codex (OMX) is a workflow layer that makes OpenAI Codex CLI sessions start stronger. It sits in the AI SDLC Automation category of the AI Coding tools and is open-source, written in TypeScript and licensed MIT. To get started: install OMX.

## Overview

OMX keeps the OpenAI Codex CLI as the execution engine and wraps a workflow around it. Instead of replacing the agent, it makes a session start stronger by default, gives you one consistent path from clarification to completion, and keeps project guidance, plans, logs and state under a `.omx/` directory in the repo. The canonical workflow commands — `$deep-interview`, `$ralplan`, `$ultragoal`, `$team`, `$code-review`, `$ultraqa` — are invoked independently, not as a fixed chain.

The recommended day-to-day flow is clarify, approve a plan, then run `$ultragoal` as the durable multi-goal completion wrapper, reaching for `$team` only when a story genuinely needs coordinated parallel work and `$ralph` when you want a single-owner completion loop instead. Research has its own bounded lanes: `$best-practice-research` for ordinary upstream evidence gathering and `$autoresearch` / `$autoresearch-goal` for validator-gated research artifacts, all of which feed back into `$ralplan` for architecture synthesis.

Isolation is taken seriously. `--worktree` launches into a separate git checkout under `../<repo>.omx-worktrees/`, which is the safer default when combined with `--madmax` (OMX shorthand for Codex's `--dangerously-bypass-approvals-and-sandbox`, so it removes approval and sandbox guardrails and belongs only in trusted repositories). Each standard launch owns one writable session pointer under its `OMX_ROOT`, so a second launch from the same checkout fails closed rather than silently sharing state. macOS and Linux are the actively tuned path; native Windows and the Codex App are explicitly not the default experience.

## What it does

- Canonical workflow commands — `$deep-interview`, `$ralplan`, `$ultragoal`, `$team`, `$code-review`, `$ultraqa` — each usable independently
- Git-worktree launch isolation, named or detached, with fail-closed session-root ownership per checkout
- Agent teams over a durable tmux runtime (psmux on Windows), for coordinated parallel work inside one goal
- Durable state under `.omx/` for plans, logs, memory and mode tracking, plus scoped `AGENTS.md` project guidance
- Reasoning-effort shorthands (`--high`, `--xhigh`) and `--madmax` for Codex's bypass mode, with worktree launch recommended alongside it
- `omx doctor` install-shape checks plus an `omx exec` smoke test that proves the live Codex runtime can authenticate and complete a call
- An official Codex plugin layout at `plugins/oh-my-codex` with marketplace metadata, alongside the global CLI

## Getting started

Requirements: Node.js 20+, an installed and authenticated Codex CLI (`codex --version`), and tmux on macOS/Linux for the recommended durable team runtime. Do not reinstall @openai/codex through npm if Homebrew already owns the codex binary — npm can fail with EEXIST.

1. Install OMX

   If Codex CLI is already installed, just add OMX. Otherwise let npm manage both.

```bash
npm install -g oh-my-codex
# or, if you have no Codex CLI yet:
npm install -g @openai/codex
npm install -g oh-my-codex
```

2. Choose a setup scope

   Project scope makes the repository own the durable AGENTS.md guidance; user scope configures Codex at the user level. Avoid running project-scoped setup from your home directory.

```bash
omx setup --scope project --merge-agents
# or: omx setup --scope user
```

3. Check both boundaries

   `omx doctor` catches missing OMX files, hooks and prerequisites; the exec smoke test catches auth, profile and provider/base-URL problems that only appear on a real request.

```bash
omx doctor
codex login status
omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"
```

4. Launch the recommended way

   Run from the git project you want Codex to edit, with a branch-like task name. This starts the leader in an OMX-managed detached tmux so the HUD and runtime panes can be created and recovered.

```bash
omx --worktree=feat/task --madmax --xhigh
```

5. Work inside Codex

   Set a durable objective, clarify, approve the plan, then wrap it in durable goals.

```text
/goal Create a safe authentication refactor plan, implement it, and verify login, logout, and refresh-token behavior.

$deep-interview "clarify the authentication change"
$ralplan "approve the auth plan and review tradeoffs"
$ultragoal "turn the approved plan into durable Codex goals"
```

6. Run concurrent conversations

   Each additional conversation needs its own explicit root — reusing one is a fatal owner conflict by design.

```bash
omx
OMX_ROOT="$HOME/.omx/instances/second-conversation" omx
```

## When to use it

- Run long refactors through a repeatable clarify → plan → execute → verify loop instead of ad-hoc Codex prompts
- Keep risky bypass-mode sessions off your main checkout by launching each one into its own git worktree
- Split one story across coordinated parallel agents when a single-owner loop is too slow
- Carry plans, logs and mode state in-repo under `.omx/` so a session can be picked up later or by someone else

## Version history

- 2026-04-07: Covered on AI/TLDR as a workflow layer for the OpenAI Codex CLI adding multi-agent teams, persistent memory, git worktree isolation and 33 specialized prompts across build, review and product domains.