Core Concepts

OMC Building Blocks

OMC runs on four systems.

Summary of Each Concept

Agents

19 specialized agents perform tasks according to their role. Each agent operates with an appropriate AI model (haiku, sonnet, or opus).

Examples: explore (discovery), executor (implementation), architect (design), verifier (validation)

Skills

37 skills compose and extend how agents behave. They are activated via slash commands (/oh-my-claudecode:skill-name) or magic keywords.

Examples: autopilot (autonomous execution), ralph (loop until complete), team (parallel collaboration)

Hooks

React to Claude Code lifecycle events to activate skills and agents. They fire when users submit prompts, use tools, or when a session starts or ends.

State Management

Stores task progress, notes, and project knowledge in the .omc/ directory. Important information is preserved even when the context window is reset (compacted).

What Are Agents?

Agents are AI workers specialized for specific roles. OMC organizes its 19 agents into 4 lanes.

Each agent is invoked with the format oh-my-claudecode:agent-name.

Build/Analysis Lane

Handles the entire development flow — from exploration to verification.

Review Lane

The quality gate before handing off code. Catches quality and security issues.

Domain Lane

Domain specialists called in as needed.

Coordination Lane

Challenges plans made by other agents. If no gaps are found, the plan passes.

Model Routing

OMC uses three model tiers.

Default tiers vary by agent.

• haiku: fast lookups and simple tasks (explore, writer)
• sonnet: code implementation, debugging, testing (executor, debugger, test-engineer)
• opus: architecture, strategic analysis, review (architect, planner, critic, code-reviewer)

Delegation Rules

The OMC orchestrator delegates to the appropriate agent based on task type.

When to Delegate to an Agent

• When multiple files need to be changed
• When refactoring is needed
• When debugging or root cause analysis is needed
• When code review or security review is needed
• When planning or research is needed

When to Handle Directly

• Simple file lookups
• Straightforward question answering
• Single-line command execution

Example Agent Workflow

A typical task flow looks like this.

Agent Role Boundaries

Agent Selection Guide

What Are Skills?

Skills are a behavior injection system that defines how agents act. They do not replace agents — they add extra capabilities to existing agents.

Skills are divided into three layers.

Skills can be composed.

Task: "ultrawork: refactor the API and commit it"
Active skills: ultrawork + default + git-master

How to Invoke Skills

Slash Commands

/oh-my-claudecode:autopilot build me a todo app
/oh-my-claudecode:ralph refactor the auth module
/oh-my-claudecode:team 3:executor "implement a full-stack app"

Magic Keywords

Include a keyword in natural language and the corresponding skill activates automatically.

autopilot build me a todo app          # activates autopilot skill
ralph: refactor the auth module        # activates ralph skill
ultrawork implement OAuth              # activates ultrawork skill

Key Workflow Skills

autopilot

A 5-stage autonomous execution pipeline from idea to finished code.

autopilot build me a REST API with authentication

Trigger keywords: autopilot, build me, I want a

ralph

A loop that does not stop until the task is verified complete. Keeps working until the verifier confirms completion.

ralph: refactor the authentication module

Trigger keywords: ralph, don't stop, must complete

ultrawork

Runs multiple agents simultaneously with maximum parallelism.

ultrawork implement user authentication with OAuth

Trigger keywords: ultrawork, ulw

team

Coordinates N Claude agents simultaneously. Operates through a 5-stage pipeline: plan → prd → exec → verify → fix

/oh-my-claudecode:team 3:executor "implement a full-stack todo app"

ccg (Claude-Codex-Gemini)

Queries Codex and Gemini simultaneously, then Claude synthesizes the results.

ccg: review this authentication implementation

Trigger keywords: ccg, claude-codex-gemini

ralplan

A planning process where Planner, Architect, and Critic iterate until reaching consensus.

ralplan this feature

Trigger keywords: ralplan

Utility Skills

Full Magic Keyword List

config.jsonc vs keyword-detector

Keywords are processed in two places.

The keywords you can change in config.jsonc are limited. Major triggers like autopilot, ralph, and ccg are hardcoded in the hook.

What Are Hooks?

Hooks are code that reacts to Claude Code lifecycle events. They run automatically when users submit prompts, use tools, or when sessions start or end.

OMC uses this hook system to implement agent delegation, keyword detection, and state persistence.

Lifecycle Events

Claude Code provides 11 lifecycle events, and OMC registers hooks on them.

system-reminder Injection

Hooks inject additional context to Claude via <system-reminder> tags.

<system-reminder>
hook success: Success
</system-reminder>

The meaning depends on the injected pattern.

Key Hook Descriptions

keyword-detector

Fires on the UserPromptSubmit event. Detects magic keywords in user input and activates the corresponding skill.

persistent-mode

Fires on the Stop event. Prevents Claude from stopping when a persistent mode like ralph or ultrawork is active.

pre-compact

Fires on the PreCompact event. Saves important information to the notepad before the context window is compacted.

subagent-tracker

Fires on SubagentStart and SubagentStop events. Tracks currently running agents and verifies their output when they stop.

context-guard-stop

Fires on the Stop event. Monitors context usage and warns when approaching the limit.

code-simplifier

Fires on the Stop event. Disabled by default. When enabled, automatically simplifies modified files when Claude stops.

To enable:

{
  "codeSimplifier": {
    "enabled": true,
    "extensions": [".ts", ".tsx", ".js", ".jsx", ".py", ".go", ".rs"],
    "maxFiles": 10
  }
}

Disabling Hooks

Disable All Hooks

export DISABLE_OMC=1

Skip Specific Hooks

export OMC_SKIP_HOOKS="keyword-detector,persistent-mode"

Multiple hooks can be skipped at once using comma separation.

Hook Registration Structure

OMC hooks are defined declaratively in a hooks.json file. Each hook is implemented as a Node.js script with a configured timeout.

{
  "UserPromptSubmit": [
    {
      "matcher": "*",
      "hooks": [
        {
          "type": "command",
          "command": "node scripts/keyword-detector.mjs",
          "timeout": 5
        }
      ]
    }
  ]
}

• matcher: Pattern the hook responds to (* matches all input)
• timeout: Timeout in seconds
• type: Always "command" (runs an external command)

State Management Overview

OMC stores task progress and project knowledge in the .omc/ directory. Even when context compaction occurs, this state system preserves important information.

Directory Structure

.omc/
├── state/                    # Per-mode state files
│   ├── autopilot-state.json  # autopilot progress
│   ├── ralph-state.json      # ralph loop state
│   ├── team/                 # team task state
│   └── sessions/             # per-session state
│       └── {sessionId}/
├── notepad.md                # Compaction-resistant notes
├── project-memory.json       # Project knowledge store
├── plans/                    # Execution plans
├── notepads/                 # Per-plan knowledge capture
│   └── {plan-name}/
│       ├── learnings.md
│       ├── decisions.md
│       ├── issues.md
│       └── problems.md
├── autopilot/                # autopilot artifacts
│   └── spec.md
├── research/                 # Research results
└── logs/                     # Execution logs

Notepad

File: .omc/notepad.md

The notepad is a memo pad that survives context compaction. Even when Claude's context window is reset, content written to the notepad is preserved.

Usage

# Save a note using the skill
/oh-my-claudecode:note "Use /api/v2 for the API endpoint"

MCP Tools

How It Works

1. When a PreCompact event fires, important information is saved to the notepad
2. After context compaction, notepad content is re-injected
3. Agents use the notepad to recover previous context

Project Memory

File: .omc/project-memory.json

Project memory is a persistent store for project-level knowledge. Knowledge about the project is retained across sessions.

MCP Tools

Lifecycle Integration

• SessionStart: Loads project memory and injects it into the context
• PostToolUse: Extracts and saves project knowledge from tool use results
• PreCompact: Saves project memory before context compaction

Session Scope

Path: .omc/state/sessions/{sessionId}/

Stores state isolated per session. Multiple sessions running simultaneously on the same project do not have state conflicts.

Plan Notepad (Per-plan Knowledge Capture)

Path: .omc/notepads/{plan-name}/

Stores learnings for each execution plan separately.

All entries are automatically timestamped.

Centralized State Management

By default, state is stored in the .omc/ directory inside the project. If the worktree is deleted, the state is lost with it.

To preserve state across worktree deletions, set the OMC_STATE_DIR environment variable.

# Add to ~/.bashrc or ~/.zshrc
export OMC_STATE_DIR="$HOME/.claude/omc"

With this setting, state is stored at ~/.claude/omc/{project-identifier}/. The project identifier is a hash of the Git remote URL, so state can be shared across different worktrees of the same repository.

Persistent Memory (remember tags)

Especially important information can be stored with <remember> tags.

<!-- Retained for 7 days -->
<remember>API endpoint changed to /v2</remember>

<!-- Retained permanently -->
<remember priority>Never access the production DB directly</remember>