oh-my-codex 0.1.1

package/skills/git-master/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: git-master
+description: Git expert for atomic commits, rebasing, and history management
+---
+
+# Git Master Command
+
+Routes to the git-master agent for git operations.
+
+## Usage
+
+```
+/git-master <git task>
+```
+
+## Routing
+
+```
+spawn_sub_agent(subagent_type="oh-my-codex:git-master", model="sonnet", prompt="{{ARGUMENTS}}")
+```
+
+## Capabilities
+- Atomic commits with conventional format
+- Interactive rebasing
+- Branch management
+- History cleanup
+- Style detection from repo history
+
+Task: {{ARGUMENTS}}

package/skills/help/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: help
+description: Guide on using oh-my-codex plugin
+---
+
+# How OMX Works
+
+**You don't need to learn any commands!** OMX enhances Codex CLI with intelligent behaviors that activate automatically.
+
+## What Happens Automatically
+
+| When You... | I Automatically... |
+|-------------|-------------------|
+| Give me a complex task | Parallelize and delegate to specialist agents |
+| Ask me to plan something | Start a planning interview |
+| Need something done completely | Persist until verified complete |
+| Work on UI/frontend | Activate design sensibility |
+| Say "stop" or "cancel" | Intelligently stop current operation |
+
+## Magic Keywords (Optional Shortcuts)
+
+You can include these words naturally in your request for explicit control:
+
+| Keyword | Effect | Example |
+|---------|--------|---------|
+| **ralph** | Persistence mode | "ralph: fix all the bugs" |
+| **ralplan** | Iterative planning | "ralplan this feature" |
+| **ulw** | Max parallelism | "ulw refactor the API" |
+| **plan** | Planning interview | "plan the new endpoints" |
+
+**ralph includes ultrawork:** When you activate ralph mode, it automatically includes ultrawork's parallel execution. No need to combine keywords.
+
+## Stopping Things
+
+Just say:
+- "stop"
+- "cancel"
+- "abort"
+
+I'll figure out what to stop based on context.
+
+## First Time Setup
+
+If you haven't configured OMX yet:
+
+```
+/omc-setup
+```
+
+This is the **only command** you need to know. It downloads the configuration and you're done.
+
+## For 2.x Users
+
+Your old commands still work! `/ralph`, `/ultrawork`, `/plan`, etc. all function exactly as before.
+
+But now you don't NEED them - everything is automatic.
+
+---
+
+## Usage Analysis
+
+Analyze your oh-my-codex usage and get tailored recommendations to improve your workflow.
+
+> Note: This replaces the former `/learn-about-omc` skill.
+
+### What It Does
+
+1. Reads token tracking from `~/.omx/state/token-tracking.jsonl`
+2. Reads session history from `.omx/state/session-history.json`
+3. Analyzes agent usage patterns
+4. Identifies underutilized features
+5. Recommends configuration changes
+
+### Step 1: Gather Data
+
+```bash
+# Check for token tracking data
+TOKEN_FILE="$HOME/.omx/state/token-tracking.jsonl"
+SESSION_FILE=".omx/state/session-history.json"
+CONFIG_FILE="$HOME/.claude/.omx-config.json"
+
+echo "Analyzing OMX Usage..."
+echo ""
+
+# Check what data is available
+HAS_TOKENS=false
+HAS_SESSIONS=false
+HAS_CONFIG=false
+
+if [[ -f "$TOKEN_FILE" ]]; then
+  HAS_TOKENS=true
+  TOKEN_COUNT=$(wc -l < "$TOKEN_FILE")
+  echo "Token records found: $TOKEN_COUNT"
+fi
+
+if [[ -f "$SESSION_FILE" ]]; then
+  HAS_SESSIONS=true
+  SESSION_COUNT=$(cat "$SESSION_FILE" | jq '.sessions | length' 2>/dev/null || echo "0")
+  echo "Sessions found: $SESSION_COUNT"
+fi
+
+if [[ -f "$CONFIG_FILE" ]]; then
+  HAS_CONFIG=true
+  DEFAULT_MODE=$(cat "$CONFIG_FILE" | jq -r '.defaultExecutionMode // "not set"')
+  echo "Default execution mode: $DEFAULT_MODE"
+fi
+```
+
+### Step 2: Analyze Agent Usage (if token data exists)
+
+```bash
+if [[ "$HAS_TOKENS" == "true" ]]; then
+  echo ""
+  echo "TOP AGENTS BY USAGE:"
+  cat "$TOKEN_FILE" | jq -r '.agentName // "main"' | sort | uniq -c | sort -rn | head -10
+
+  echo ""
+  echo "MODEL DISTRIBUTION:"
+  cat "$TOKEN_FILE" | jq -r '.modelName' | sort | uniq -c | sort -rn
+fi
+```
+
+### Step 3: Generate Recommendations
+
+Based on patterns found, output recommendations:
+
+**If high Opus usage (>40%) and no ecomode:**
+- "Consider using ecomode for routine tasks to save tokens"
+
+**If no pipeline usage:**
+- "Try /pipeline for code review workflows"
+
+**If no security-reviewer usage:**
+- "Use security-reviewer after auth/API changes"
+
+**If defaultExecutionMode not set:**
+- "Set defaultExecutionMode in /omc-setup for consistent behavior"
+
+### Step 4: Output Report
+
+Format a summary with:
+- Token summary (total, by model)
+- Top agents used
+- Underutilized features
+- Personalized recommendations
+
+### Example Output
+
+```
+📊 Your OMX Usage Analysis
+
+TOKEN SUMMARY:
+- Total records: 1,234
+- By Model: opus 45%, sonnet 40%, haiku 15%
+
+TOP AGENTS:
+1. executor (234 uses)
+2. architect (89 uses)
+3. explore (67 uses)
+
+UNDERUTILIZED FEATURES:
+- ecomode: 0 uses (could save ~30% on routine tasks)
+- pipeline: 0 uses (great for review workflows)
+
+RECOMMENDATIONS:
+1. Set defaultExecutionMode: "ecomode" to save tokens
+2. Try /pipeline review for PR reviews
+3. Use explore agent before architect to save context
+```
+
+### Graceful Degradation
+
+If no data found:
+
+```
+📊 Limited Usage Data Available
+
+No token tracking found. To enable tracking:
+1. Ensure ~/.omx/state/ directory exists
+2. Run any OMX command to start tracking
+
+Tip: Run /omc-setup to configure OMX properly.
+```
+
+## Need More Help?
+
+- **README**: https://github.com/Yeachan-Heo/oh-my-codex
+- **Issues**: https://github.com/Yeachan-Heo/oh-my-codex/issues
+
+---
+
+*Version: 4.2.3*

package/skills/hud/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: hud
+description: Show or configure the OMX HUD (two-layer statusline)
+role: display
+scope: .omx/**
+---
+
+# HUD Skill
+
+The OMX HUD uses a two-layer architecture:
+
+1. **Layer 1 - Codex built-in statusLine**: Real-time TUI footer showing model, git branch, and context usage. Configured via `[tui] status_line` in `~/.codex/config.toml`. Zero code required.
+
+2. **Layer 2 - `omx hud` CLI command**: Shows OMX-specific orchestration state (ralph, ultrawork, autopilot, team, pipeline, ecomode, turns). Reads `.omx/state/` files.
+
+## Quick Commands
+
+| Command | Description |
+|---------|-------------|
+| `omx hud` | Show current HUD (modes, turns, activity) |
+| `omx hud --watch` | Live-updating display (polls every 1s) |
+| `omx hud --json` | Raw state output for scripting |
+| `omx hud --preset=minimal` | Minimal display |
+| `omx hud --preset=focused` | Default display |
+| `omx hud --preset=full` | All elements |
+
+## Presets
+
+### minimal
+```
+[OMX] ralph:3/10 | turns:42
+```
+
+### focused (default)
+```
+[OMX] ralph:3/10 | ultrawork | team:3 workers | turns:42 | last:5s ago
+```
+
+### full
+```
+[OMX] ralph:3/10 | ultrawork | autopilot:execution | team:3 workers | pipeline:exec | turns:42 | last:5s ago | total-turns:156
+```
+
+## Setup
+
+`omx setup` automatically configures both layers:
+- Adds `[tui] status_line` to `~/.codex/config.toml` (Layer 1)
+- Writes `.omx/hud-config.json` with default preset (Layer 2)
+
+## Layer 1: Codex Built-in StatusLine
+
+Configured in `~/.codex/config.toml`:
+```toml
+[tui]
+status_line = ["model-with-reasoning", "git-branch", "context-remaining"]
+```
+
+Available built-in items (Codex CLI v0.101.0+):
+`model-name`, `model-with-reasoning`, `current-dir`, `project-root`, `git-branch`, `context-remaining`, `context-used`, `five-hour-limit`, `weekly-limit`, `codex-version`, `context-window-size`, `used-tokens`, `total-input-tokens`, `total-output-tokens`, `session-id`
+
+## Layer 2: OMX Orchestration HUD
+
+The `omx hud` command reads these state files:
+- `.omx/state/ralph-state.json` - Ralph loop iteration
+- `.omx/state/ultrawork-state.json` - Ultrawork mode
+- `.omx/state/autopilot-state.json` - Autopilot phase
+- `.omx/state/team-state.json` - Team workers
+- `.omx/state/pipeline-state.json` - Pipeline stage
+- `.omx/state/ecomode-state.json` - Ecomode active
+- `.omx/state/hud-state.json` - Last activity (from notify hook)
+- `.omx/metrics.json` - Turn counts
+
+## Configuration
+
+HUD config stored at `.omx/hud-config.json`:
+```json
+{
+  "preset": "focused"
+}
+```
+
+## Color Coding
+
+- **Green**: Normal/healthy
+- **Yellow**: Warning (ralph >70% of max)
+- **Red**: Critical (ralph >90% of max)
+
+## Troubleshooting
+
+If the TUI statusline is not showing:
+1. Ensure Codex CLI v0.101.0+ is installed
+2. Run `omx setup` to configure `[tui]` section
+3. Restart Codex CLI
+
+If `omx hud` shows "No active modes":
+- This is expected when no workflows are running
+- Start a workflow (ralph, autopilot, etc.) and check again

package/skills/learn-about-omx/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: learn-about-omx
+description: Learn about your OMX usage patterns and get personalized recommendations
+---
+
+# Learn About OMX
+
+Analyze your OMX usage patterns and provide personalized recommendations for getting more out of oh-my-codex.
+
+## Usage
+
+```
+/learn-about-omx
+```
+
+## Behavior
+
+1. **Scan usage data** from:
+   - `.omx/sessions/` for session history
+   - `.omx/state/` for mode usage patterns
+   - `.omx/notepad.md` for working memory
+   - `.omx/project-memory.json` for project context
+   - Agent flow traces for tool and agent usage
+2. **Analyze patterns**:
+   - Most-used modes and skills
+   - Agent types spawned most frequently
+   - Common workflows and task types
+   - Session durations and completion rates
+3. **Generate recommendations**:
+   - Underused features that match your workflow
+   - More efficient skill combinations
+   - Configuration optimizations
+   - Tips based on your usage profile
+
+## Output
+
+A personalized report with usage statistics and actionable recommendations for improving your OMX workflow.

package/skills/learner/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: learner
+description: Extract a learned skill from the current conversation
+---
+
+# Learner Skill
+
+## The Insight
+
+Reusable skills are not code snippets to copy-paste, but **principles and decision-making heuristics** that teach Claude HOW TO THINK about a class of problems.
+
+**The difference:**
+- BAD (mimicking): "When you see ConnectionResetError, add this try/except block"
+- GOOD (reusable skill): "In async network code, any I/O operation can fail independently due to client/server lifecycle mismatches. The principle: wrap each I/O operation separately, because failure between operations is the common case, not the exception."
+
+A good skill changes how Claude APPROACHES problems, not just what code it produces.
+
+## Why This Matters
+
+Before extracting a skill, ask yourself:
+- "Could someone Google this in 5 minutes?" → If yes, STOP. Don't extract.
+- "Is this specific to THIS codebase?" → If no, STOP. Don't extract.
+- "Did this take real debugging effort to discover?" → If no, STOP. Don't extract.
+
+If a potential skill fails any of these questions, it's not worth saving.
+
+## Recognition Pattern
+
+Use /learner ONLY after:
+- Solving a tricky bug that required deep investigation
+- Discovering a non-obvious workaround specific to this codebase
+- Finding a hidden gotcha that wastes time when forgotten
+- Uncovering undocumented behavior that affects this project
+
+## The Approach
+
+### Extraction Process
+
+**Step 1: Gather Required Information**
+
+- **Problem Statement**: The SPECIFIC error, symptom, or confusion that occurred
+  - Include actual error messages, file paths, line numbers
+  - Example: "TypeError in src/hooks/session.ts:45 when sessionId is undefined after restart"
+
+- **Solution**: The EXACT fix, not general advice
+  - Include code snippets, file paths, configuration changes
+  - Example: "Add null check before accessing session.user, regenerate session on 401"
+
+- **Triggers**: Keywords that would appear when hitting this problem again
+  - Use error message fragments, file names, symptom descriptions
+  - Example: ["sessionId undefined", "session.ts TypeError", "401 session"]
+
+- **Scope**: Almost always Project-level unless it's a truly universal insight
+
+**Step 2: Quality Validation**
+
+The system REJECTS skills that are:
+- Too generic (no file paths, line numbers, or specific error messages)
+- Easily Googleable (standard patterns, library usage)
+- Vague solutions (no code snippets or precise instructions)
+- Poor triggers (generic words that match everything)
+
+**Step 3: Save Location**
+
+- **User-level**: ~/.claude/skills/omc-learned/ - Rare. Only for truly portable insights.
+- **Project-level**: .omx/skills/ - Default. Version-controlled with repo.
+
+### What Makes a USEFUL Skill
+
+**CRITICAL**: Not every solution is worth saving. A good skill is:
+
+1. **Non-Googleable**: Something you couldn't easily find via search
+   - BAD: "How to read files in TypeScript" ❌
+   - GOOD: "This codebase uses custom path resolution in ESM that requires fileURLToPath + specific relative paths" ✓
+
+2. **Context-Specific**: References actual files, error messages, or patterns from THIS codebase
+   - BAD: "Use try/catch for error handling" ❌
+   - GOOD: "The aiohttp proxy in server.py:42 crashes on ClientDisconnectedError - wrap StreamResponse in try/except" ✓
+
+3. **Actionable with Precision**: Tells you exactly WHAT to do and WHERE
+   - BAD: "Handle edge cases" ❌
+   - GOOD: "When seeing 'Cannot find module' in dist/, check tsconfig.json moduleResolution matches package.json type field" ✓
+
+4. **Hard-Won**: Took significant debugging effort to discover
+   - BAD: Generic programming patterns ❌
+   - GOOD: "Race condition in worker.ts - the Promise.all at line 89 needs await before the map callback returns" ✓
+
+### Anti-Patterns (DO NOT EXTRACT)
+
+- Generic programming patterns (use documentation instead)
+- Refactoring techniques (these are universal)
+- Library usage examples (use library docs)
+- Type definitions or boilerplate
+- Anything a junior dev could Google in 5 minutes
+
+## Skill Format
+
+Skills are saved as markdown with this structure:
+
+### YAML Frontmatter
+
+Standard metadata fields:
+- id, name, description, source, triggers, quality
+
+### Body Structure (Required)
+
+```markdown
+# [Skill Name]
+
+## The Insight
+What is the underlying PRINCIPLE you discovered? Not the code, but the mental model.
+Example: "Async I/O operations are independently failable. Client lifecycle != server lifecycle."
+
+## Why This Matters
+What goes wrong if you don't know this? What symptom led you here?
+Example: "Proxy server crashes on client disconnect, taking down other requests."
+
+## Recognition Pattern
+How do you know when this skill applies? What are the signs?
+Example: "Building any long-lived connection handler (proxy, websocket, SSE)"
+
+## The Approach
+The decision-making heuristic, not just code. How should Claude THINK about this?
+Example: "For each I/O operation, ask: what if this fails right now? Handle it locally."
+
+## Example (Optional)
+If code helps, show it - but as illustration of the principle, not copy-paste material.
+```
+
+**Key**: A skill is REUSABLE if Claude can apply it to NEW situations, not just identical ones.
+
+## Related Commands
+
+- /note - Save quick notes that survive compaction (less formal than skills)
+- /ralph - Start a development loop with learning capture

package/skills/note/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: note
+description: Save notes to notepad.md for compaction resilience
+---
+
+# Note Skill
+
+Save important context to `.omx/notepad.md` that survives conversation compaction.
+
+## Usage
+
+| Command | Action |
+|---------|--------|
+| `/note <content>` | Add to Working Memory with timestamp |
+| `/note --priority <content>` | Add to Priority Context (always loaded) |
+| `/note --manual <content>` | Add to MANUAL section (never pruned) |
+| `/note --show` | Display current notepad contents |
+| `/note --prune` | Remove entries older than 7 days |
+| `/note --clear` | Clear Working Memory (keep Priority + MANUAL) |
+
+## Sections
+
+### Priority Context (500 char limit)
+- **Always** injected on session start
+- Use for critical facts: "Project uses pnpm", "API in src/api/client.ts"
+- Keep it SHORT - this eats into your context budget
+
+### Working Memory
+- Timestamped session notes
+- Auto-pruned after 7 days
+- Good for: debugging breadcrumbs, temporary findings
+
+### MANUAL
+- Never auto-pruned
+- User-controlled permanent notes
+- Good for: team contacts, deployment info
+
+## Examples
+
+```
+/note Found auth bug in UserContext - missing useEffect dependency
+/note --priority Project uses TypeScript strict mode, all files in src/
+/note --manual Contact: api-team@company.com for backend questions
+/note --show
+/note --prune
+```
+
+## Behavior
+
+1. Creates `.omx/notepad.md` if it doesn't exist
+2. Parses the argument to determine section
+3. Appends content with timestamp (for Working Memory)
+4. Warns if Priority Context exceeds 500 chars
+5. Confirms what was saved
+
+## Integration
+
+Notepad content is automatically loaded on session start:
+- Priority Context: ALWAYS loaded
+- Working Memory: Loaded if recent entries exist
+
+This helps survive conversation compaction without losing critical context.