oh-my-codex

oh-my-codex (OMX)

OMX is a powerful workflow layer designed to enhance the capabilities of the OpenAI Codex CLI. It acts as a sophisticated wrapper, providing a more structured and efficient environment for developers to leverage AI for coding tasks. By integrating seamlessly with Codex, OMX aims to streamline the development process, offering features like reusable role and task invocations, advanced workflow management, and persistent project state tracking.

Core Philosophy

The fundamental principle behind OMX is to augment, not replace, the core functionality of Codex. It recognizes Codex as the primary execution engine for AI-driven coding and focuses on building a robust layer around it to improve usability, organization, and efficiency. The goal is to provide a better day-to-day runtime experience, allowing developers to start their coding sessions with a stronger foundation and access advanced features only when needed.

Key Features and Benefits

• Enhanced Default Experience: OMX allows users to start their Codex sessions with a more powerful and opinionated default configuration, potentially leading to better initial results and a more productive workflow.
• Reusable Role Keywords: OMX introduces custom keywords (e.g., $architect, $executor) that encapsulate common roles and tasks. This promotes code reuse and consistency, allowing developers to quickly invoke predefined behaviors without repetitive setup.
• Workflow Skills: The system supports a range of workflow skills (e.g., $plan, $ralph, $team, $deep-interview) that can be invoked within the Codex session. These skills automate complex processes, such as generating project plans, executing tasks sequentially or in parallel, and conducting in-depth requirement analysis.
• Project State Management: OMX utilizes a dedicated directory (.omx/) within projects to store crucial runtime information. This includes plans, execution logs, memory states, and mode tracking, enabling persistent and reproducible workflows.
• Agent Catalog and Skills Reference: Developers can explore a catalog of available agents and a detailed reference for skills, facilitating the discovery and application of various AI-driven functionalities.
• Integration Capabilities: The project supports integrations with external tools and services, such as OpenClaw for notification gateways, further extending its utility.
• Multi-language Support: Recognizing the global nature of software development, OMX provides documentation in multiple languages, including English, Korean, Japanese, Chinese, Vietnamese, Spanish, Portuguese, Russian, Turkish, German, French, and Italian.
• Operator/Support Surfaces: For advanced users and administrators, OMX offers specific command-line tools for setup (omx setup), diagnostics (omx doctor), monitoring (omx hud --watch), and team-based runtime management (omx team).

Use Cases

OMX is particularly beneficial for:

• Streamlining AI-assisted coding: Developers who already appreciate Codex can use OMX to enhance their daily workflow, making AI assistance more integrated and efficient.
• Managing complex projects: For projects requiring detailed planning, execution tracking, and coordination, OMX's workflow skills and state management provide a robust solution.
• Rapid Prototyping: The ability to quickly invoke predefined roles and workflows can accelerate the prototyping phase of new projects.
• Ensuring Reproducibility: By storing project state and logs, OMX helps in reproducing results and debugging complex AI-driven processes.
• Collaborative Development: The team runtime features are designed to support coordinated efforts among multiple agents or developers working on the same project.

Target Audience

OMX is primarily targeted at developers who are already familiar with and utilize AI coding assistants like OpenAI Codex. It's for those who seek to:

• Optimize their workflow: Improve efficiency and reduce repetitive tasks.
• Manage complexity: Handle larger, more intricate projects with better organization.
• Leverage advanced AI patterns: Utilize sophisticated workflows like planning, parallel execution, and deep requirement analysis.
• Maintain project state: Keep track of progress, decisions, and execution details for better reproducibility and debugging.

Getting Started

The recommended way to start with OMX is:

1. Install: npm install -g @openai/codex oh-my-codex
2. Setup: Run omx setup to install necessary prompts, skills, and configuration.
3. Launch: Start your session with omx --madmax --high for the default enhanced experience.
4. Engage: Use role keywords like $architect for analysis or $plan for planning, and let the agent decide when to escalate to more complex workflows like $team or $ralph.

For specific advanced use cases, operators can utilize commands like omx explore, omx sparkshell, omx team status, omx team resume, and omx team shutdown. The project also provides detailed documentation on agents, skills, integrations, and contributing guidelines.

Technical Stack

• Core Language: TypeScript
• Runtime: Node.js 20+
• Dependencies: OpenAI Codex CLI, Tmux (for team runtime on macOS/Linux), psmux (for team runtime on Windows)
• Build/Configuration: Biome, Cargo, npm

Community and Support

OMX fosters a community around AI-driven development. Users can connect via Discord for support, discussions, and contributions. The project is actively maintained and encourages community involvement through its contributing guidelines and changelog.