oh-my-codex

Overview

oh-my-codex (OMX) is a comprehensive orchestration layer for OpenAI Codex that provides structured workflows and persistent state management. It features an MCP server implementation that exposes tools for task management (omx_task_*), state manipulation (omx_state_*), memory operations (omx_memory_*), note management (omx_note_*), exploration (omx_explore_*), team coordination (omx_team_*), plugin management (omx_plugin_*), hook handling (omx_hook_*), and agent operations (omx_agent_*). The system includes a CLI interface, durable contracts through .omx/ directory structure, and an agent catalog for different roles like architect, planner, researcher, executor, reviewer, and operator.

Try asking AI

After installing, here are 6 things you can ask your AI assistant:

• omx_task_list

  List tasks in the task queue

  Try:Show me all tasks in the queueTry:List pending tasks
• omx_task_queue

  Queue a new task for team execution

  Try:Queue this task for implementationTry:Add a new task to the work queue
• omx_claim

  Claim a task for execution by a specific team member

  Try:Claim task 123 for executorTry:I want to work on this task
• omx_complete

  Mark a task as completed with a status update

  Try:Mark task 123 as completedTry:Finish this task with implementation notes
• omx_state_get

  Retrieve state information from the persistent state store

  Try:Get the current state of projectTry:Retrieve saved configuration data
• omx_memory_save

  Save information to persistent memory

  Try:Save this context for later referenceTry:Store this information in memory
• omx_explore_index

  Explore and index project resources

  Try:Explore the current project structureTry:Index all project files
• omx_team_init

  Initialize a new team runtime environment

  Try:Set up a new team workspaceTry:Initialize team execution environment
• omx_spawn_executor

  Spawn a new executor worker in the team runtime

  Try:Start a new executor workerTry:Spawn an additional executor
• omx_review

  Review a completed task and provide feedback

  Try:Review this completed taskTry:Approve or reject task implementation
• omx_ultrawork

  Execute the ultrawork skill for end-to-end feature implementation

  Try:Implement this feature end to endTry:Work through the full feature path
• omx_doctor

  Check system health and diagnose issues

  Try:Check system healthTry:Diagnose any configuration issues

Comparable tools

Installation

# Install via npm
npm install
npm run build
cd packages/cli && npm link

# Or use direct installation
omx setup

# For Claude Desktop integration, add to config.json:
{
  "mcpServers": {
    "omx": {
      "command": "node",
      "args": ["/path/to/omx/packages/cli/dist/bin.js", "mcp"]
    }
  }
}

FAQ

What is the difference between OMX v1 and v2?

OMX v2 is a complete rewrite that focuses exclusively on Codex, removing the Claude bridge. It introduces a durable state system, agent catalog, plugin SDK, and tmux-aware team execution.

Can I use OMX without tmux?

Yes, OMX has a degraded mock mode that works when tmux is not available, though tmux-first worker runtime provides full functionality on macOS/Linux.

Compare oh-my-codex with