Se você usou o Codex CLI para algo além de tarefas de arquivo único, certamente encontrou seus limites: ausência de fase de planejamento estruturado, nenhum estado persistente entre sessões e nenhuma forma de coordenar múltiplos agentes trabalhando em paralelo. O oh-my-codex(OMX) é a camada que adiciona tudo isso, sem substituir o Codex como motor de execução.
Versão atual: v0.13.1 (lançada em 7 de abril de 2026). Fonte: github.com/Yeachan-Heo/oh-my-codex, licença MIT.
O que é o OMX, em 30 segundos
oh-my-codex (OMX) é uma camada de workflow e orquestração que fica em cima do OpenAI Codex CLI. O Codex continua fazendo o raciocínio e a geração de código. O OMX adiciona:
- Um workflow padronizado de quatro etapas:
$$
deep-interview →
$$ralplan →$$ralph /$$team - Workers paralelos via tmux, cada um em um Git Worktree isolado
- Estado persistente e memória em um diretório
.omx/que sobrevive ao context pruning - Hooks nativos do Codex (
PreToolUse / PostToolUse) via.codex/hooks.json - Um heads-up display (
omx hud --watch) pra monitorar sessões ao vivo - 33 prompts de agente especializados e 36 skills de workflow
A analogia da documentação oficial é boa: "como oh-my-zsh, mas pro Codex." Não faz fork nem modifica o Codex. Ele envolve sessões com prompts melhores, gerenciamento de estado e coordenação de time.
OMX vs Codex CLI puro — o que muda na prática
| Codex CLI puro | Codex CLI + OMX | |
|---|---|---|
| Fase de planejamento | Nenhuma | Gate $deep-interview → $ralplan |
| Workers paralelos | Nenhum | omx team N:executor via tmux |
| Isolamento Git por worker | Nenhum | Worktrees automáticos em .omx/team/ |
| Estado de sessão | Nenhum | Diretório .omx/ persiste planos, logs, memória |
| Hooks | Não configurados por padrão | .codex/hooks.json nativo com Pre/PostToolUse |
| Memória entre resets de contexto | Perdida | Notepad de prioridade + arquivo de memória do projeto |
Nota sobre nomenclatura do pacote: repo oh-my-codex vs nome no npm
O repositório do GitHub, o pacote npm e os comandos da CLI seguem todos o mesmo nome: oh-my-codex. Instalação:
npm install -g oh-my-codex
omx setupO OMX está listado no npm como oh-my-codex. Isso difere do projeto relacionado oh-my-claudecode (OMC), cujo pacote npm é publicado como oh-my-claude-sisyphus — uma diferença de nomenclatura importante de se saber desde o início.
Capacidades Principais
$deep-interview → $ralplan → $ralph / $team: o fluxo de trabalho principal
As quatro skills definem o caminho canônico do OMX, desde um prompt vago até o código em execução.
$deep-interview — classificação de intenção e clarificação antes de qualquer plano ser formado. A classificação acontece no início, então o plano subsequente reflete o que você realmente quer.
$ralplan — gera um plano de implementação estruturado com revisão explícita de trade-offs. A aprovação é obrigatória; a execução não começa sem ela.
$ralph — "a pedra nunca para de rolar." Um loop de conclusão persistente que leva o plano aprovado até o done verificado, se recuperando de erros em vez de parar.
$team — execução paralela coordenada com N workers. Cada worker recebe um Git Worktree isolado automaticamente; o líder integra as mudanças de forma incremental.
# Caminho principal: interview → plan → execute (owner único)
$deep-interview "migrar módulo de auth de session pra JWT"
# [responder perguntas, aprovar plano]
$ralph "levar o plano de auth aprovado até a conclusão"
# Paralelo com 3 workers
$team 3:executor "executar o plano de auth aprovado em paralelo"Uma coisa que confunde muita gente: o $ralph não é só "execute isso." É um loop. Se uma ferramenta falhar, ele registra o estado, se recupera e continua. Fechar o terminal no meio de uma tarefa e retomar com omx team resume restaura o estado do .omx/. O Codex puro perde esse estado.
Workers paralelos com Git Worktrees isolados
Desde a v0.11.x, cada worker do omx team recebe automaticamente seu próprio worktree em .omx/team/<sessão>/worktrees/worker-N. Sem flags extras. Os workers escrevem em branches destacadas isoladas; o líder os integra continuamente, com conflitos aparecendo no integration-report.md.
omx team 3:executor "refatorar módulo de auth"
omx team status refactor-auth-module
# worker-1: status=in_progress
# worker-2: status=completed
# integration: merged=2 conflicts=0
omx team resume refactor-auth-module # retomar após interrupção
omx team shutdown refactor-auth-module # limparTimes com múltiplos provedores funcionam via OMX_TEAM_WORKER_CLI_MAP:
OMX_TEAM_WORKER_CLI_MAP=codex,claude,gemini \
omx team 3:executor "implementação full-stack"Cada worker recebe seu próprio worktree independente do provedor.
Memória persistente: o que sobrevive ao context pruning
.omx/
├── logs/ — logs de execução por sessão
├── memory/ — memória do projeto (sobrevive ao context pruning)
├── plans/ — artefatos de plano aprovado
├── research/ — output do autoresearch
├── sessions/ — metadados de sessão
├── state/ — estado de runtime
└── team/ — estado dos workers e worktreesO notepad de prioridade e o project-memory.json sobrevivem a resets da janela de contexto. Quando o contexto do Codex é cortado, a camada de memória retém decisões críticas do projeto e estado de tarefas — a próxima sessão continua de onde a última parou.
Hooks nativos para PreToolUse e PostToolUse
Na v0.13.1, o OMX passou a suportar hooks de forma nativa através do contrato de runtime do Codex (.codex/hooks.json), eliminando o shim externo que era necessário nas versões anteriores. PreToolUse é executado antes de qualquer chamada de ferramenta; PostToolUse é executado após a chamada.
Comandos destrutivos disparam avisos automaticamente e os erros apresentam orientação estruturada.
omx doctor # verificar a estrutura da instalação dos hooks
omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK" # teste smoke ao vivoOMX vs oh-my-claudecode (OMC): qual a diferença?
Mesmo autor (Yeachan Heo). Mesmo design conceitual. Engine de execução diferente.
| oh-my-codex (OMX) | oh-my-claudecode (OMC) | |
|---|---|---|
| Engine de execução | OpenAI Codex CLI | Claude Code |
| Prefixo CLI | omx | omc |
| Pacote npm | oh-my-codex | oh-my-claude-sisyphus |
| Repositório GitHub | Yeachan-Heo/oh-my-codex | Yeachan-Heo/oh-my-claudecode |
Uma observação importante sobre o pacote npm: o repo, o pacote e os comandos CLI são todos chamados oh-my-codex. Diferente do OMC, cujo pacote npm é publicado como oh-my-claude-sisyphus — uma inconsistência de nomenclatura que vale saber antes de instalar.
Se você usa principalmente o Codex CLI: use o OMX. Se você usa principalmente o Claude Code: use o OMC.
OMX = Orquestração do Codex CLI
O Codex é o motor de execução principal. Claude e Gemini podem aparecer como workers da equipe via OMX_TEAM_WORKER_CLI_MAP, mas o Codex é o padrão e o caminho mais bem suportado.
OMC = Plugin de orquestração do Claude Code
O OMC é instalado como um plugin do Claude Code e roda dentro das sessões do Claude Code. Ele pode delegar tarefas para workers do Codex ou Gemini via omc team, mas o Claude Code é o host. O README do OMC aponta explicitamente usuários do Codex para o OMX: “Para usuários do Codex: confira o oh-my-codex — a mesma experiência de orquestração para o OpenAI Codex CLI.”
Se você é principalmente usuário do Codex CLI, use o OMX. Se você é principalmente usuário do Claude Code, use o OMC.
Casos de Uso Reais
Refatoração paralela multi-agente
Uma grande refatoração em 15+ arquivos é onde o modo team do OMX compensa o overhead:
$deep-interviewesclarece o escopo — quais arquivos, qual padrão, quais são os critérios de aceitação.$ralplangera o plano com grupos de arquivos atribuídos a diferentes unidades de execução.omx team 3:executor "execute the approved refactor plan"cria três workers, cada um em seu próprio worktree.- O líder integra branches concluídas de forma incremental; conflitos surgem cedo no
integration-report.md.
Workers que terminam mais cedo podem pegar tarefas adicionais da fila sem coordenação manual.
Delegação assíncrona para tarefas de longa duração (sem timeouts)
Para tarefas que ultrapassam uma única sessão interativa — grandes migrações, suítes completas de testes, loops de pesquisa — o $ralph fornece a camada de persistência. Ralph não para em falhas de ferramenta ou reset de contexto; ele registra o estado, recupera e continua. O omx autoresearch estende isso para loops de pesquisa iterativos que se autoencerram quando o objetivo é atingido.
Fechar o terminal no meio da tarefa e retomar com omx team resume restaura o estado da sessão a partir de .omx/. O Codex puro perde esse estado.
Instalação e Configuração (Visão Geral)
npm install -g oh-my-codex
omx setup # instala prompts, skills, AGENTS.md, hooks
omx doctor # verifica a estrutura da instalação
omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK" # teste smokeO omx setup instala 33 prompts de agente, 36 skills de workflow, gera o AGENTS.md, configura o .codex/config.toml e conecta os hooks através do .codex/hooks.json. Execute omx doctor antes de depender do runtime — ele detecta arquivos ausentes e pré-requisitos que causariam falhas silenciosas.
Quando Não Usar o OMX
O OMX adiciona overhead significativo de configuração e planejamento. Não é a ferramenta certa quando:
- A tarefa é uma alteração simples em arquivo único ou uma correção rápida — o gate de planejamento adiciona fricção sem benefício.
- Você está em modo exploratório e não quer gates estruturados.
- Você está no Windows e precisa de confiabilidade de produção — o OMX tem como alvo oficial macOS e Linux; o suporte ao Windows existe, mas é explicitamente marcado como não padrão.
- Você é principalmente usuário do Claude Code — use o OMC.
O OMX também não é um substituto para CI. O runtime de team gerencia execução paralela dentro de uma sessão; a matriz de testes e gates de deploy do seu pipeline são preocupações separadas.
FAQ
O OMX substitui o Codex?
Não. O Codex continua sendo o motor de execução. O OMX envolve as sessões com skills de workflow estruturado e coordenação de equipe, mas todo raciocínio e geração de código ainda roda através do Codex. Remover o OMX retorna você a uma sessão normal do Codex.
Posso usar OMX com workers do Claude?
Sim, via OMX_TEAM_WORKER_CLI_MAP. Configure para incluir claude e o omx team criará workers do Claude CLI junto com workers do Codex. Cada worker recebe seu próprio git worktree, independentemente do provedor. O Claude Code CLI precisa ser instalado e autenticado separadamente.
Funciona no Windows?
Parcialmente. O README do OMX traz um aviso explícito: macOS e Linux são o caminho recomendado. O suporte ao Windows existe — a v0.13.1 inclui correções de resolução de comandos no PowerShell e melhorias de confiabilidade no tmux —, mas está listado como “não é a experiência padrão, pode quebrar ou se comportar de forma inconsistente”. Trate o OMX no Windows como experimental, e não como pronto para produção.
Qual a diferença em relação ao Superpowers?
O Superpowers (v5.0.7) é um framework de skills multiplataforma — funciona com Claude Code, Codex, Cursor, Gemini CLI e outros através de arquivos SKILL.md injetados no início da sessão. O OMX é especificamente uma camada de orquestração para Codex CLI, com paralelismo baseado em tmux, estado persistente em .omx/ e o fluxo de trabalho $deep-interview → $ralplan → $ralph/$team. Ambos impõem estrutura sobre sessões brutas de agente; o Superpowers faz isso de forma multiplataforma via sistema de skills, enquanto o OMX faz de forma nativa no Codex com um runtime completo de coordenação de equipe.
