oh-my-codex

KO | EN

gitlite — search

#python #react #golang #go #linux #nodejs #macos #windows #awesome #cli #kubernetes #security #mcp #open-source

(★ 20)

Sigrid's personal codex plugin

oh-my-codex Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# oh-my-codex

[![npm version](https://img.shields.io/npm/v/oh-my-codex?color=cb3837)](https://www.npmjs.com/package/oh-my-codex)
[![npm downloads](https://img.shields.io/npm/dm/oh-my-codex?color=1f6feb)](https://www.npmjs.com/package/oh-my-codex)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://raw.githubusercontent.com/realsigridjin/oh-my-codex/main/LICENSE)

Multi-agent orchestration for Codex with structured planning, specialized agents, lifecycle hooks, LSP/AST tooling, and automation skills.

oh-my-codex is designed to make Codex behave like a practical engineering conductor: plan first, delegate by role, verify outputs, detect drift, and keep sessions resumable.

## Table of Contents

- [Why oh-my-codex](#why-oh-my-codex)
- [Core Capabilities](#core-capabilities)
- [Architecture Overview](#architecture-overview)
- [Requirements](#requirements)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Execution Modes](#execution-modes)
- [Agents and Tier Routing](#agents-and-tier-routing)
- [Hooks and Runtime Behavior](#hooks-and-runtime-behavior)
- [HUD and Usage Telemetry](#hud-and-usage-telemetry)
- [Rate Limit Recovery](#rate-limit-recovery)
- [Project Session Manager](#project-session-manager)
- [Update and Uninstall](#update-and-uninstall)
- [Developer Guide](#developer-guide)
- [Troubleshooting](#troubleshooting)
- [Security Notes](#security-notes)
- [License](#license)

## Why oh-my-codex

Base Codex is excellent at direct implementation. oh-my-codex adds a full orchestration layer for larger or riskier workflows:

- Reusable specialized agents with explicit responsibilities
- Multi-step planning and review-first patterns
- Enforcement and verification hooks
- Parallel execution modes for speed
- Type-aware and syntax-aware tooling (LSP + AST)
- Runtime utilities for drift detection and resumable sessions

## Core Capabilities

### 1. Agent orchestration

- 30+ agent prompts for architecture, execution, review, QA, security, docs, and research
- Tier routing strategy (low/medium/high) to control cost and depth
- Team-style delegation patterns for parallel work

### 2. Skill-based workflows

- 35+ workflow skills such as planning, deep search, build fixing, review, and setup
- Command/skill organization for repeatable execution patterns
- Project bootstrap and configuration setup helpers

### 3. Hook system

- Lifecycle hook support for session start, prompt submit, pre/post tool use, stop, and failures
- Runtime safety checks, input handling, and persistence helpers
- Upgrade-aware behavior for mixed legacy/current environments

### 4. Developer tooling

- LSP tool family for definitions, references, symbols, diagnostics, and rename
- AST search/replace tools for structural code edits
- HUD usage integration and statusline support
- Rate-limit wait detection and tmux-based resume helpers

## Architecture Overview

```text
Codex CLI
  -> oh-my-codex runtime
     -> Agents (specialized prompts)
     -> Skills (workflow templates)
     -> Hooks (lifecycle enforcement)
     -> Tools (LSP + AST + utilities)
     -> Features (state, routing, drift, wait/resume)
```

Key source areas:

- `src/installer/` - installation, migration, and conflict handling
- `src/hooks/` - lifecycle hook logic
- `src/features/` - execution modes and runtime features
- `src/hud/` - usage telemetry and statusline integration
- `agents/` - agent prompt files
- `skills/` - skill instructions
- `commands/` - command definitions
- `scripts/` - setup/update/runtime scripts

## Requirements

- Node.js `>=20`
- Codex CLI installed and authenticated
- macOS/Linux/WSL recommended for tmux workflows

Optional:

- `tmux` for session recovery and rate-limit resume flow
- Additional MCP servers depending on your workflow

## Installation

There are two supported install paths.

### Option A: Codex plugin install (preferred when available)

Some Codex builds expose plugin marketplace commands.

```bash
codex plugin marketplace add https://github.com/sigridjineth/oh-my-codex
codex plugin install oh-my-codex
```

For local development plugin install:

```bash
codex plugin marketplace add /path/to/oh-my-codex
codex plugin install oh-my-codex@oh-my-codex
```

If your Codex CLI does not provide `codex plugin ...`, use Option B.

### Option B: CLI install from source (works across more Codex builds)

```bash
git clone https://github.com/sigridjineth/oh-my-codex.git
cd oh-my-codex
npm install
npm run build
node dist/cli/index.js install
```

This installs OMC resources into `~/.codex/` (hooks, agents, CODEX.md, HUD config).

### Verify installation

```bash
node dist/cli/index.js doctor conflicts --json
codex exec "Reply exactly: OK"
```

Expected outcomes:

- `doctor conflicts` reports `"hasConflicts": false`
- `codex exec` completes successfully

## Quick Start

### 1. Start Codex

```bash
codex
```

### 2. Run setup command

In a Codex session, run:

```text
/oh-my-codex:omc-setup
```

This prepares project/global `CODEX.md` instructions.

### 3. Use orchestration commands

Examples:

```text
/oh-my-codex:plan Build a migration-safe auth refactor
/oh-my-codex:review
/oh-my-codex:ultrawork Refactor service boundaries
/oh-my-codex:security-review
/oh-my-codex:code-review
```

### 4. Use agent delegation

When using task delegation, use `oh-my-codex:<agent>` identifiers.

## Execution Modes

| Mode | Purpose |
|---|---|
| `autopilot` | Broad autonomous execution from prompt to implementation |
| `ultrawork` | Maximum parallelism for throughput |
| `ultrapilot` | Parallel autopilot strategy with ownership patterns |
| `swarm` | N-agent coordinated execution with claim/checkpoint logic |
| `pipeline` | Ordered stage handoff between agents |
| `ecomode` | Cost-sensitive execution mode |
| `ralph` | Persistence mode with repeated verification |
| `ultraqa` | QA-heavy cycles and validation loops |

## Agents and Tier Routing

oh-my-codex includes role-specific agents (architecture, execution, QA, research, security, review).

Tier intent:

- `-low` agents: quick/simple tasks
- base agents: balanced complexity
- `-high` agents: deeper reasoning and critical reviews

Recommended strategy:

1. plan with high-level agent
2. execute with balanced agent(s)
3. verify with critic/reviewer/security roles
4. finalize with QA and user-flow checks

## Hooks and Runtime Behavior

Installed hooks typically include:

- `UserPromptSubmit` -> keyword/mode detector
- `SessionStart` -> restore context, drift check, startup info
- `PreToolUse` -> preflight enforcement and policy checks
- `PostToolUse` -> verification/recording logic
- `PostToolUseFailure` -> failure handling
- `Stop` -> persistence and continuation support

Notes:

- Current hook paths use `.codex/hooks/`
- Upgrade logic recognizes legacy `.claude/hooks/` ownership patterns
- Mixed legacy/current installs are handled to reduce false conflict detection

## HUD and Usage Telemetry

HUD module includes:

- statusline integration
- token/usage polling
- OAuth credential handling with legacy wrapper compatibility
- refresh behavior aligned to Anthropic OAuth host for current auth flow

Run HUD helper commands in Codex:

```text
/oh-my-codex:hud
```

## Rate Limit Recovery

`omc wait` and related runtime helpers support:

- waiting on API quota reset windows
- tmux pane scanning for blocked sessions
- automated resume patterns when sessions become available

Detection includes both Codex and legacy markers to support migration environments.

## Project Session Manager

Project session manager supports isolated workflows with worktrees + tmux.

Typical use cases:

- running multiple implementation branches in parallel
- one task per pane/worktree
- fast context switching between active features

Codex launch behavior in tmux is configured for `codex` runtime.

## Update and Uninstall

### Update source install

```bash
cd /path/to/oh-my-codex
git pull
npm install
npm run build
node dist/cli/index.js install
```

### Update plugin install

```bash
codex plugin marketplace update oh-my-codex
codex plugin update oh-my-codex@oh-my-codex
```

### Uninstall

If installed by plugin, use Codex plugin uninstall commands.

If installed by CLI/source, remove OMC resources from `~/.codex/` based on your install footprint (hooks, agents, HUD assets, and command files).

## Developer Guide

### Local development

```bash
npm install
npm run build
npm test
npm run lint
```

### Common scripts

```bash
npm run dev
npm run test:coverage
npm run sync-metadata
npm run compose-docs
```

### Recommended workflow

1. Implement changes in `src/`
2. Add or update tests in `src/__tests__/`
3. Run `npm run build` and targeted tests
4. Validate install/runtime path (`node dist/cli/index.js install`, `doctor conflicts`)
5. Verify Codex execution flow (`codex exec ...`)

## Troubleshooting

### `codex plugin marketplace` not found

Your Codex CLI build may not support plugin marketplace subcommands.
Use source install path:

```bash
node dist/cli/index.js install
```

### Install fails with permissions writing `~/.codex`

Run install with an environment that allows home directory writes.

### Hook conflict warnings after migration

Use:

```bash
node dist/cli/index.js doctor conflicts --json
```

Legacy `.claude/hooks` and current `.codex/hooks` signatures are recognized for ownership checks.

### Usage telemetry unavailable

Check credential source files and login state. Usage credential parsing supports both wrapper shapes:

- `codexAiOauth` (current)
- `claudeAiOauth` (legacy)

### tmux wait/resume does not detect blocked pane

Confirm tmux is installed and pane content includes Codex/rate-limit text patterns.

## Security Notes

- Hook and tool execution should stay scoped to trusted working directories
- Review generated commands before enabling full automation modes
- Keep tokens/credentials only in secure stores and avoid committing secrets

## License

MIT. See [LICENSE](./LICENSE).

oh-my-codex

oh-my-codex Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

oh-my-codex

oh-my-codex Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README