Architecture

How oh-my-claudecode orchestrates multi-agent workflows.

Overview

oh-my-claudecode enables Claude Code to orchestrate specialized agents through a skill-based routing system. It is built on four interlocking systems: Hooks detect lifecycle events, Skills inject behaviors, Agents execute specialized work, and State tracks progress across context resets.

┌─────────────────────────────────────────────────────────────────────────┐
│                         OH-MY-CLAUDECODE                                 │
│                     Intelligent Skill Activation                         │
└─────────────────────────────────────────────────────────────────────────┘

  User Input                      Skill Detection                 Execution
  ──────────                      ───────────────                 ─────────
       │                                │                              │
       ▼                                ▼                              ▼
┌─────────────┐              ┌──────────────────┐           ┌─────────────────┐
│  "ultrawork │              │   CLAUDE.md      │           │ SKILL ACTIVATED │
│   refactor  │─────────────▶│   Auto-Routing   │──────────▶│                 │
│   the API"  │              │                  │           │ ultrawork +     │
└─────────────┘              │ Task Type:       │           │ default +       │
                             │  - Implementation│           │ git-master      │
                             │  - Multi-file    │           │                 │
                             │  - Parallel OK   │           │ ┌─────────────┐ │
                             │                  │           │ │ Parallel    │ │
                             │ Skills:          │           │ │ agents      │ │
                             │  - ultrawork ✓   │           │ │ launched    │ │
                             │  - default ✓     │           │ └─────────────┘ │
                             │  - git-master ✓  │           │                 │
                             └──────────────────┘           │ ┌─────────────┐ │
                                                            │ │ Atomic      │ │
                                                            │ │ commits     │ │
                                                            │ └─────────────┘ │
                                                            └─────────────────┘

The four systems flow in sequence:

User Input --> Hooks (event detection) --> Skills (behavior injection)
           --> Agents (task execution) --> State (progress tracking)

Agent System

Overview

OMC provides 19 specialized agents organized into 4 lanes. Each agent is invoked as oh-my-claudecode:<agent-name> and runs on the appropriate model tier.

Build/Analysis Lane

Covers the full development lifecycle from exploration to verification.

Agent	Default Model	Role
`explore`	haiku	Codebase discovery, file/symbol mapping
`analyst`	opus	Requirements analysis, hidden constraint discovery
`planner`	opus	Task sequencing, execution plan creation
`architect`	opus	System design, interface definition, trade-off analysis
`debugger`	sonnet	Root-cause analysis, build error resolution
`executor`	sonnet	Code implementation, refactoring
`verifier`	sonnet	Completion verification, test adequacy confirmation
`tracer`	sonnet	Evidence-driven causal tracing, competing hypothesis analysis

Review Lane

Quality gates before handoff. Catches correctness and security issues.

Agent	Default Model	Role
`security-reviewer`	sonnet	Security vulnerabilities, trust boundaries, authn/authz review
`code-reviewer`	opus	Comprehensive code review, API contracts, backward compatibility

Domain Lane

Domain experts called in when needed.

Agent	Default Model	Role
`test-engineer`	sonnet	Test strategy, coverage, flaky-test hardening
`designer`	sonnet	UI/UX architecture, interaction design
`writer`	haiku	Documentation, migration notes
`qa-tester`	sonnet	Interactive CLI/service runtime validation via tmux
`scientist`	sonnet	Data analysis, statistical research
`git-master`	sonnet	Git operations, commits, rebase, history management
`document-specialist`	sonnet	External documentation, API/SDK reference lookup
`code-simplifier`	opus	Code clarity, simplification, maintainability improvement

Coordination Lane

Challenges plans and designs made by other agents. A plan passes only when no gaps can be found.

Agent	Default Model	Role
`critic`	opus	Gap analysis of plans and designs, multi-angle review

Model Routing

OMC uses three model tiers:

Tier	Model	Characteristics	Cost
LOW	haiku	Fast and inexpensive	Low
MEDIUM	sonnet	Balanced performance and cost	Medium
HIGH	opus	Highest-quality reasoning	High

Default assignments by role:

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

Work is delegated through the Task tool with intelligent model routing:

Task(
  subagent_type="oh-my-claudecode:executor",
  model="sonnet",
  prompt="Implement feature..."
)

Delegate to agents when:

Multiple files need to change
Refactoring is required
Debugging or root-cause analysis is needed
Code review or security review is needed
Planning or research is required

Handle directly when:

Simple file lookups
Straightforward question answering
Single-command operations

Agent Selection Guide

Task Type	Recommended Agent	Model
Quick code lookup	`explore`	haiku
Feature implementation	`executor`	sonnet
Complex refactoring	`executor` (model=opus)	opus
Simple bug fix	`debugger`	sonnet
Complex debugging	`architect`	opus
UI component	`designer`	sonnet
Documentation	`writer`	haiku
Test strategy	`test-engineer`	sonnet
Security review	`security-reviewer`	sonnet
Code review	`code-reviewer`	opus
Data analysis	`scientist`	sonnet

Typical Agent Workflow

explore --> analyst --> planner --> critic --> executor --> verifier
(discover)  (analyze)   (sequence)  (review)   (implement)  (confirm)

Agent Role Boundaries

Agent	Does	Does Not
`architect`	Code analysis, debugging, verification	Requirements gathering, planning
`analyst`	Find requirements gaps	Code analysis, planning
`planner`	Create task plans	Requirements analysis, plan review
`critic`	Review plan quality	Requirements analysis, code analysis

Skills System

Overview

Skills are behavior injections that modify how the orchestrator operates. Instead of swapping agents, skills add capabilities on top of existing agents. OMC provides 31 skills total (28 user-invocable + 3 internal/pipeline).

Skill Layers

Skills compose in three layers:

┌─────────────────────────────────────────────────────────────┐
│  GUARANTEE LAYER (optional)                                  │
│  ralph: "Cannot stop until verified done"                   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  ENHANCEMENT LAYER (0-N skills)                              │
│  ultrawork (parallel) | git-master (commits) | frontend-ui-ux│
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  EXECUTION LAYER (primary skill)                             │
│  default (build) | orchestrate (coordinate) | planner (plan) │
└─────────────────────────────────────────────────────────────┘

Formula: [Execution Skill] + [0-N Enhancements] + [Optional Guarantee]

Example:

Task: "ultrawork: refactor API with proper commits"
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 fullstack app"

Magic keywords — include a keyword in natural language and the skill activates automatically:

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

Core Workflow Skills

autopilot

Full autonomous 5-stage pipeline from idea to working code.

Trigger: autopilot, build me, I want a

autopilot build me a REST API with authentication

ralph

Repeating loop that does not stop until work is verified complete. The verifier agent confirms completion before the loop exits.

Trigger: ralph, don't stop, must complete

ralph: refactor the authentication module

ultrawork

Maximum parallelism — launches multiple agents simultaneously.

Trigger: ultrawork, ulw

ultrawork implement user authentication with OAuth

team

Coordinates N Claude agents with a 5-stage pipeline: plan → prd → exec → verify → fix

/oh-my-claudecode:team 3:executor "implement fullstack todo app"

ccg (Claude-Codex-Gemini)

Fans out to Codex and Gemini simultaneously; Claude synthesizes the results.

Trigger: ccg, claude-codex-gemini

ccg: review this authentication implementation

ralplan

Iterative planning: Planner, Architect, and Critic loop until they reach consensus.

Trigger: ralplan

ralplan this feature

Utility Skills

Skill	Description	Command
`cancel`	Cancel active execution mode	`/oh-my-claudecode:cancel`
`hud`	Status bar configuration	`/oh-my-claudecode:hud`
`omc-setup`	Initial setup wizard	`/oh-my-claudecode:omc-setup`
`omc-doctor`	Diagnose installation	`/oh-my-claudecode:omc-doctor`
`learner`	Extract reusable skills from session	`/oh-my-claudecode:learner`
`skill`	Manage local skills (list/add/remove)	`/oh-my-claudecode:skill`
`trace`	Evidence-driven causal tracing	`/oh-my-claudecode:trace`
`release`	Automated release workflow	`/oh-my-claudecode:release`
`deepinit`	Generate hierarchical AGENTS.md	`/oh-my-claudecode:deepinit`
`deep-interview`	Socratic deep interview	`/oh-my-claudecode:deep-interview`
`sciomc`	Parallel scientist agent orchestration	`/oh-my-claudecode:sciomc`
`external-context`	Parallel document-specialist research	`/oh-my-claudecode:external-context`
`ai-slop-cleaner`	Clean AI expression patterns	`/oh-my-claudecode:ai-slop-cleaner`
`writer-memory`	Memory system for writing projects	`/oh-my-claudecode:writer-memory`

Magic Keyword Reference

Keyword	Effect
`ultrawork`, `ulw`, `uw`	Parallel agent orchestration
`autopilot`, `build me`, `I want a`, `handle it all`, `end to end`, `e2e this`	Autonomous execution pipeline
`ralph`, `don't stop`, `must complete`, `until done`	Loop until verified complete
`ccg`, `claude-codex-gemini`	3-model orchestration
`ralplan`	Consensus-based planning
`deep interview`, `ouroboros`	Socratic deep interview
`code review`, `review code`	Comprehensive code review mode
`security review`, `review security`	Security-focused review mode
`deepsearch`, `search the codebase`, `find in codebase`	Codebase search mode
`deepanalyze`, `deep-analyze`	Deep analysis mode
`ultrathink`, `think hard`, `think deeply`	Deep reasoning mode
`tdd`, `test first`, `red green`	TDD workflow
`deslop`, `anti-slop`	AI expression cleanup
`cancelomc`, `stopomc`	Cancel active execution mode

Keyword Detection Sources

Keywords are processed in two places:

Source	Role	Customizable
`config.jsonc` `magicKeywords`	4 categories (ultrawork, search, analyze, ultrathink)	Yes
`keyword-detector` hook	11+ triggers (autopilot, ralph, ccg, etc.)	No

The autopilot, ralph, and ccg triggers are hardcoded in the hook and cannot be changed through config.

Hooks

Overview

Hooks are code that reacts to Claude Code lifecycle events. They run automatically when a user submits a prompt, uses a tool, or starts/ends a session. OMC implements agent delegation, keyword detection, and state persistence through this hook system.

Lifecycle Events

Claude Code provides 11 lifecycle events. OMC registers hooks on these events:

Event	When It Fires	OMC Usage
`UserPromptSubmit`	User submits a prompt	Magic keyword detection, skill injection
`SessionStart`	Session begins	Initial setup, project memory load
`PreToolUse`	Before a tool is used	Permission validation, parallel execution hints
`PermissionRequest`	Permission requested	Bash command permission handling
`PostToolUse`	After a tool is used	Result validation, project memory update
`PostToolUseFailure`	After a tool fails	Error recovery handling
`SubagentStart`	Subagent starts	Agent tracking
`SubagentStop`	Subagent stops	Agent tracking, output verification
`PreCompact`	Before context compaction	Preserve critical information, save project memory
`Stop`	Claude is about to stop	Persistent mode enforcement, code simplification
`SessionEnd`	Session ends	Session data cleanup

system-reminder Injection

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

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

Injected pattern meanings:

Pattern	Meaning
`hook success: Success`	Hook ran normally, continue as planned
`hook additional context: ...`	Additional context information, take note
`[MAGIC KEYWORD: ...]`	Magic keyword detected, execute indicated skill
`The boulder never stops`	ralph/ultrawork mode is active

Key Hooks

keyword-detector — fires on UserPromptSubmit. Detects magic keywords in user input and activates the corresponding skill.

persistent-mode — fires on Stop. When a persistent mode (ralph, ultrawork) is active, prevents Claude from stopping until work is verified complete.

pre-compact — fires on PreCompact. Saves critical information to the notepad before the context window is compressed.

subagent-tracker — fires on SubagentStart and SubagentStop. Tracks currently running agents; validates output on stop.

context-guard-stop — fires on Stop. Monitors context usage and warns when approaching the limit.

code-simplifier — fires on Stop. Disabled by default. When enabled, automatically simplifies modified files when Claude stops.

Enable via config:

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

Hook Registration Structure

OMC hooks are declared in hooks.json. Each hook is a Node.js script with a 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)

Disabling Hooks

Disable all hooks:

export DISABLE_OMC=1

Skip specific hooks (comma-separated):

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

State Management

Overview

OMC stores task progress and project knowledge in the .omc/ directory. The state system preserves critical information even when context compaction resets the context window.

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 memo pad
├── 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

Global State:

~/.omc/state/{name}.json — user preferences and global config

Legacy locations are auto-migrated on read.

Notepad

File: .omc/notepad.md

The notepad survives context compaction. Content written to it persists even after the context window is reset.

Notes can be saved using the notepad_write_manual MCP tool or the notepad_write_priority tool for persistent notes.

MCP Tools:

Tool	Description
`notepad_read`	Read notepad contents
`notepad_write_priority`	Write high-priority memo (permanent retention)
`notepad_write_working`	Write working memo
`notepad_write_manual`	Write manual memo
`notepad_prune`	Clean up old memos
`notepad_stats`	View notepad statistics

How it works:

On PreCompact event, important information is saved to the notepad
After compaction, notepad contents are re-injected into context
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. It survives across sessions.

MCP Tools:

Tool	Description
`project_memory_read`	Read project memory
`project_memory_write`	Overwrite entire project memory
`project_memory_add_note`	Add a note
`project_memory_add_directive`	Add a directive

Lifecycle integration:

SessionStart: Load project memory and inject into context
PostToolUse: Extract project knowledge from tool results and save
PreCompact: Save project memory before context compaction

Session Scope

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

Stores state isolated per session. Multiple sessions on the same project run simultaneously without state conflicts.

Plan Notepad (Per-Plan Knowledge Capture)

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

Stores learnings from each execution plan separately.

File	Contents
`learnings.md`	Discovered patterns, successful approaches
`decisions.md`	Architecture decisions and rationale
`issues.md`	Problems and blockers
`problems.md`	Technical debt and cautions

All entries are timestamped automatically.

Centralized State (Optional)

By default, state is stored in the project's .omc/ directory and is deleted when the worktree is removed.

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"

State is then stored at ~/.claude/omc/{project-identifier}/. The project identifier is a hash of the Git remote URL, so the same repository shares state across different worktrees.

Persistent Memory Tags

For critical information, use <remember> tags:

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

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

Tag	Retention
`<remember>`	7 days
`<remember priority>`	Permanent

Verification Protocol

The verification module ensures work completion with evidence:

Standard Checks:

BUILD: Compilation passes
TEST: All tests pass
LINT: No linting errors
FUNCTIONALITY: Feature works as expected
ARCHITECT: Opus-tier review approval
TODO: All tasks completed
ERROR_FREE: No unresolved errors

Evidence must be fresh (within 5 minutes) and include actual command output.

For More Details

Complete Reference: See REFERENCE.md
Internal API: See FEATURES.md
User Guide: See README.md
Skills Reference: See CLAUDE.md in your project

Uh oh!

FilesExpand file tree

ARCHITECTURE.md

Latest commit

History

ARCHITECTURE.md

File metadata and controls

Architecture

Overview

Agent System

Overview

Build/Analysis Lane

Review Lane

Domain Lane

Coordination Lane

Model Routing

Delegation

Agent Selection Guide

Typical Agent Workflow

Agent Role Boundaries

Skills System

Overview

Skill Layers

How to Invoke Skills

Core Workflow Skills

autopilot

ralph

ultrawork

team

ccg (Claude-Codex-Gemini)

ralplan

Utility Skills

Magic Keyword Reference

Keyword Detection Sources

Hooks

Overview

Lifecycle Events

system-reminder Injection

Key Hooks

Hook Registration Structure

Disabling Hooks

State Management

Overview

Directory Structure

Notepad

Project Memory

Session Scope

Plan Notepad (Per-Plan Knowledge Capture)

Centralized State (Optional)

Persistent Memory Tags

Verification Protocol

For More Details