Oh my Claudecode: Complete Framework Guide

Multi-agent orchestration system for Claude Code Version 3.3.8 | GitHub | npm

Table of Contents

1. What is Oh my Claudecode?
2. Core Concepts
3. Installation & Setup
4. Architecture Overview
5. The 28 Specialized Agents
6. Skills System
7. Hooks & Lifecycle
8. Key Features
9. Usage Patterns
10. Advanced Features
11. Configuration
12. Troubleshooting

What is Oh my Claudecode?

Oh my Claudecode (OMC) is an intelligent multi-agent orchestration framework that transforms Claude Code from a single AI assistant into a coordinated team of specialized agents. Instead of one Claude doing everything, OMC enables:

• Delegation-first philosophy: The main Claude instance acts as a conductor, delegating work to specialized agents
• Smart model routing: Automatically selects the optimal model (Opus/Sonnet/Haiku) based on task complexity
• Parallel execution: Independent tasks run concurrently for maximum efficiency
• Persistent memory: Three-tier notepad system survives conversation compaction
• Automatic skill activation: Detects task patterns and activates appropriate behaviors
• Completion guarantee: Tasks continue until verified complete by specialized reviewers

The Flagship Experience: Autopilot Mode

Autopilot is the recommended starting point that provides fully autonomous execution from high-level ideas to working, tested code:

# Just describe what you want to build
> "I want a REST API for managing tasks with authentication"
> "Build me a React dashboard with real-time charts"
> "Create a CLI tool that processes CSV files"

Autopilot automatically:

1. Expands your idea into detailed requirements (Analyst + Architect)
2. Plans the implementation strategy (Architect + Critic review)
3. Executes with parallel agents (Ralph + Ultrawork)
4. Tests until all checks pass (UltraQA cycles)
5. Validates with security, functional, and quality reviews

No commands needed. No manual orchestration. Just describe your goal.

Core Concepts

1. Delegation-First Philosophy

The main Claude instance is an orchestrator, not a performer:

Iron Rule: Never do substantive work directly. Always delegate to specialized agents.

2. Smart Model Routing

OMC automatically selects the optimal model tier to save tokens and maximize quality:

3. Skill Composition

Skills are behavior injections that modify how Claude operates. They compose in layers:

[Execution Layer]     +  [Enhancement Layer]    +  [Guarantee Layer]
     planner                ultrawork                  ralph
   orchestrate              git-master                   -
     default              frontend-ui-ux                 -

Example Combinations:

• default + frontend-ui-ux + git-master → UI implementation with proper commits
• ultrawork + orchestrate + ralph → Maximum speed + completion guarantee
• planner → orchestrate + ultrawork → Strategic planning then parallel execution

4. Agent Architecture: Fixed Master with Skill Activation

Unlike some systems with swappable master agents, Claude Code has a fixed master that gains capabilities through skills:

┌─────────────────────────────────────────┐
│         CLAUDE CODE MASTER              │
│         (Fixed, Cannot Swap)            │
│                                         │
│  ┌───────────────────────────────┐     │
│  │  SKILL LAYER                  │     │
│  │  (Injected Behaviors)         │     │
│  │  - autopilot                  │     │
│  │  - ralph (persistence)        │     │
│  │  - ultrawork (parallelism)    │     │
│  │  - planner (strategic)        │     │
│  └───────────────────────────────┘     │
└─────────────────┬───────────────────────┘
                  │
      ┌───────────┼───────────┐
      ▼           ▼           ▼
  ┌─────────┐ ┌─────────┐ ┌─────────┐
  │architect│ │ executor│ │ designer│
  │ (Opus)  │ │(Sonnet) │ │(Sonnet) │
  └─────────┘ └─────────┘ └─────────┘

Advantages:

• Context preserved across mode changes
• Skills can stack (multiple active simultaneously)
• Natural language activation (no explicit mode switching)
• Seamless transitions between behaviors

Installation & Setup

Step 1: Choose Installation Method

Option A: Claude Code Plugin (Recommended)

# From terminal
claude plugin install oh-my-claude-sisyphus

# Or from within Claude Code
/oh-my-claudecode:plugin oh-my-claude-sisyphus

Option B: npm (Windows & Cross-Platform)

npm install -g oh-my-claudecode

Option C: curl One-Liner (macOS/Linux)

curl -fsSL https://raw.githubusercontent.com/Yeachan-Heo/oh-my-claudecode/main/scripts/install.sh | bash

Step 2: Configure OMC

For Current Project (Recommended):

/oh-my-claudecode:omc-default

Creates ./.claude/CLAUDE.md in your project directory.

For All Projects (Global):

/oh-my-claudecode:omc-default-global

Creates ~/.claude/CLAUDE.md globally.

What This Does

✅ Downloads latest CLAUDE.md with full orchestration prompt ✅ Configures 28 agents with intelligent model routing ✅ Enables magic keyword detection (ultrawork, search, analyze) ✅ Activates continuation enforcement ✅ Sets up skill composition

Platform Support

Requirements

• Claude Code installed
• Claude Max/Pro subscription OR Anthropic API key (ANTHROPIC_API_KEY)
• Windows: Node.js 20+
• macOS/Linux: Bash shell (default) or Node.js 20+

Architecture Overview

System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     OH-MY-CLAUDECODE SYSTEM                      │
└─────────────────────────────────────────────────────────────────┘
                              │
          ┌───────────────────┼───────────────────┐
          │                   │                   │
          ▼                   ▼                   ▼
┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│    PLANNING     │  │   EXECUTION     │  │    SUPPORT      │
├─────────────────┤  ├─────────────────┤  ├─────────────────┤
│ planner (Opus)  │  │ architect(Opus) │  │ researcher(Son) │
│ critic (Opus)   │  │ designer (Son)  │  │ explore (Haiku) │
│ analyst (Opus)  │  │ executor (Son)  │  │ writer (Haiku)  │
│                 │  │ qa-tester (Son) │  │ vision (Son)    │
└─────────────────┘  └─────────────────┘  └─────────────────┘

How It Works

1. Orchestrator: Main Claude instance coordinates all work
2. Specialized Subagents: Each agent has focused expertise and tools
3. Parallel Execution: Independent tasks run concurrently
4. Continuation Enforcement: Agents persist until ALL tasks complete
5. Context Injection: Project-specific instructions from CLAUDE.md files

Plugin Structure

oh-my-claudecode/
├── .claude-plugin/
│   └── plugin.json            # Plugin manifest
├── agents/                    # 28 specialized subagents
├── commands/                  # Slash commands
├── skills/                    # Composable skills
├── hooks/
│   └── hooks.json             # Hook configuration
└── scripts/                   # Hook implementation

The 28 Specialized Agents

OMC provides 28 specialized agents organized by complexity tier (LOW/MEDIUM/HIGH):

Analysis & Architecture

Code Execution

Search & Exploration

Research & Documentation

Frontend & Design

Planning & Review

Quality Assurance

Security

Build & Test

Code Review

Data Science

Visual Analysis

Agent Invocation

Always use the oh-my-claudecode: prefix when calling via Task tool:

Task({
  subagent_type: "oh-my-claudecode:architect",
  model: "opus",
  prompt: "Debug the memory leak in worker process"
})

Skills System

All 26+ Skills

Skill Composition Examples

UI Implementation with Proper Commits:

Skills: default + frontend-ui-ux + git-master
Result: Design sensibility + atomic commits per feature

Maximum Speed Refactoring:

Skills: ultrawork + orchestrate + ralph
Result: Parallel execution + completion guarantee

Strategic Planning Then Execution:

Phase 1: planner (strategic planning)
Phase 2: orchestrate + ultrawork (parallel implementation)

Magic Keywords

Users don't need to learn commands. Just say:

Combine keywords: "ralph ulw: migrate database" = persistence + parallelism

Hooks & Lifecycle

OMC includes 19 lifecycle hooks that enhance Claude Code's behavior:

Core Hooks

Context & Recovery

Quality & Validation

Environment & Notifications

Key Features

1. Three-Tier Memory System

The Problem: Long sessions lose context through compaction. Critical discoveries vanish.

The Solution: Persistent notepad system that survives compaction:

Usage:

# Agents persist discoveries automatically
<remember>Project uses pnpm not npm</remember>
<remember priority>API client at src/api/client.ts</remember>

# Or save notes manually
/oh-my-claudecode:note Database schema uses PostgreSQL with Prisma ORM

2. Ralph Loop PRD Support

Structured task tracking inspired by Ralph:

• Product Requirements Document (PRD) format with user stories
• Progress tracking with learnings and patterns
• Completion guarantee - loop continues until ALL stories pass

Three Powerful Modes:

# Self-referential loop until completion
/oh-my-claudecode:ralph implement user authentication

# Maximum intensity + completion guarantee
/oh-my-claudecode:ultrawork + /oh-my-claudecode:ralph refactor API

# Autonomous test-verify-fix cycles
/oh-my-claudecode:ultraqa all tests must pass with 90%+ coverage

3. Notepad Wisdom System (v3.1)

Plan-scoped wisdom capture for persistent learnings, decisions, issues, and problems.

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

API Functions:

• initPlanNotepad(planName) - Initialize notepad
• addLearning(planName, content) - Record learning
• addDecision(planName, content) - Record decision
• addIssue(planName, content) - Record issue
• addProblem(planName, content) - Record problem
• getWisdomSummary(planName) - Get formatted summary

Benefits:

• Separates learnings by plan for better organization
• Automatic timestamp tracking
• Structured wisdom capture
• Persistent storage survives session resets

4. Delegation Categories (v3.1)

Semantic task categorization that auto-maps to model tier, temperature, and thinking budget:

Auto-Detection: Categories automatically detect from prompt keywords.

API Functions:

• detectCategoryFromPrompt(taskPrompt) - Auto-detect category
• getCategoryForTask(context) - Get category with full config
• enhancePromptWithCategory(prompt, category) - Add category guidance

5. Directory Diagnostics (v3.1)

Project-level type checking with dual strategy:

1. Primary (tsc): Fast TypeScript compilation check via tsc --noEmit
2. Fallback (LSP): File-by-file Language Server Protocol diagnostics

Usage:

import { runDirectoryDiagnostics } from '@/tools/diagnostics';

const result = await runDirectoryDiagnostics(process.cwd());
console.log(result.success);        // true if no errors
console.log(result.errorCount);     // Number of errors
console.log(result.diagnostics);    // Formatted output

6. Session Resume (v3.1)

Background agents can be resumed with full context preservation:

import { resumeSession } from '@/tools/resume-session';

const result = resumeSession({ sessionId: 'ses_abc123' });
if (result.success && result.context) {
  console.log(result.context.previousPrompt);
  console.log(result.context.toolCallCount);

  // Use continuation prompt in next Task delegation
  Task({
    subagent_type: "oh-my-claudecode:executor",
    prompt: result.context.continuationPrompt
  });
}

7. Auto-Update System

Silent auto-update checks for updates in the background:

• Rate-limited: Checks at most once every 24 hours
• Concurrent-safe: Lock file prevents simultaneous updates
• Cross-platform: Works on macOS and Linux

To manually update, re-run plugin install or use Claude Code's update mechanism.

Usage Patterns

Autopilot Workflow (Recommended)

Zero Learning Curve: Just describe what you want to build.

# In Claude Code, just say:
> "I want a REST API for task management with authentication"
> "Build me a React dashboard with real-time charts"
> "Create a CLI tool that processes CSV files"

What Happens:

1. Expansion Phase (Analyst + Architect)

   • Extract detailed requirements
   • Create technical specification
   • Save to .omc/autopilot/spec.md

2. Planning Phase (Architect + Critic)

   • Create comprehensive execution plan
   • Critic reviews for completeness
   • Save to .omc/plans/autopilot-impl.md

3. Execution Phase (Ralph + Ultrawork)

   • Parallel task execution
   • Track progress in TODO list
   • Record learnings in notepad

4. QA Phase (UltraQA)

   • Run build → lint → test
   • Fix failures automatically
   • Repeat until all pass

5. Validation Phase (3 Architects in parallel)

   • Functional: Verify requirements implemented
   • Security: Check for vulnerabilities
   • Quality: Review code quality and tests
   • Retry until all approved

Control:

# Cancel at any time
> "stop" or "cancel autopilot"

# Check status
> "autopilot status"

# Resume after interruption
> Automatically resumes from last phase

Basic Orchestration

Multi-Step Implementation:

# Manual approach
/oh-my-claudecode:orchestrate refactor the authentication module

# Natural language (auto-activates)
> "Refactor the authentication module"

Claude will:

1. Analyze requirements
2. Create TODO list
3. Delegate to appropriate agents
4. Execute in parallel where possible
5. Verify completion before reporting

Planning Workflows

Strategic Planning:

# Start planning session
/oh-my-claudecode:planner design new API layer

# Or just say
> "Plan the new API layer"

Planner conducts an interview:

• Asks about requirements
• Explores constraints
• Identifies risks
• Creates comprehensive plan

Iterative Planning (Ralplan):

/oh-my-claudecode:ralplan implement user authentication

Combines Planner + Architect + Critic in an iterative loop until consensus.

Persistence Mode (Ralph)

When to Use: Tasks that must complete fully, no matter what.

# Explicit command
/oh-my-claudecode:ralph migrate database schema to PostgreSQL

# Natural language trigger
> "Migrate database schema to PostgreSQL and don't stop until it's done"

How It Works:

• Creates structured PRD with user stories
• Tracks progress with learnings
• Self-referential loop continues until verified complete
• Cannot stop until ALL stories pass

Combined with Ultrawork:

> "ralph ulw: refactor entire API layer"

= Persistence + Maximum parallelism

Maximum Performance (Ultrawork)

When to Use: Tasks with 3+ independent subtasks.

# Explicit command
/oh-my-claudecode:ultrawork implement user dashboard with charts

# Magic keyword
> "ulw fix all type errors across the codebase"

What It Does:

• Identifies parallelizable subtasks
• Spawns multiple executor agents
• Runs tasks concurrently (max 5)
• Aggregates results

QA & Testing (UltraQA)

When to Use: Ensure all tests pass, fix issues automatically.

/oh-my-claudecode:ultraqa all tests must pass with 90%+ coverage

Workflow:

1. Run build → lint → test
2. For each failure: diagnose → fix → re-run
3. Repeat until all pass or max cycles (5)
4. Record learnings in notepad

Research & Analysis

Deep Analysis:

/oh-my-claudecode:analyze why are tests failing in the checkout flow

Delegates to architect for root cause analysis.

Codebase Search:

/oh-my-claudecode:deepsearch all API endpoints that handle user data

Uses explore agents with multiple search strategies.

Data Analysis:

/oh-my-claudecode:research analyze user engagement patterns from CSV data

Spawns scientist agents in parallel for comprehensive analysis.

UI/Frontend Work

Automatic Design Sensibility:

> "Add dark mode toggle to settings page"

Auto-activates frontend-ui-ux skill for design guidance + delegates to designer agent.

Git Workflows

Atomic Commits:

> "Implement user authentication with proper commit history"

Auto-activates git-master skill for atomic commits per logical change.

Creating Pull Requests:

Uses gh CLI via Bash tool for all GitHub operations.

Advanced Features

1. Dynamic Prompt Generation

Agent prompts are generated dynamically from definitions:

import { getAgentDefinitions } from '@/agents/definitions';
import { generateOrchestratorPrompt, convertDefinitionsToConfigs } from '@/agents/prompt-generator';

const definitions = getAgentDefinitions();
const agents = convertDefinitionsToConfigs(definitions);
const prompt = generateOrchestratorPrompt(agents);

Benefits:

• Adding new agent automatically updates orchestrator
• Consistent prompt structure
• Easy customization via definitions

2. Agent Templates

Standardized prompt structures for common task types:

Exploration Template (src/agents/templates/exploration-template.md):

• TASK: What needs to be explored
• EXPECTED OUTCOME: What orchestrator expects
• CONTEXT: Background information
• MUST DO / MUST NOT DO: Constraints
• REQUIRED SKILLS / TOOLS: Capabilities needed

Implementation Template (src/agents/templates/implementation-template.md):

• TASK: Implementation goal
• EXPECTED OUTCOME: Deliverable
• CONTEXT: Project background
• VERIFICATION CHECKLIST: Pre-completion checks

3. Verification-Before-Completion Protocol

Iron Law: No completion claims without fresh verification evidence.

Before ANY agent says "done" or "fixed":

Red Flags (must stop and verify):

• Using "should", "probably", "seems to"
• Expressing satisfaction before verification
• Claiming completion without fresh test/build run

Evidence Types:

4. Background Execution Rules

Run in Background (run_in_background: true):

• Package installs: npm install, pip install, cargo build
• Builds: npm run build, make, tsc
• Tests: npm test, pytest, cargo test

Run Blocking (foreground):

• git status, ls, pwd
• File reads/edits
• Quick commands (<10 seconds)

Maximum 5 concurrent background tasks.

5. Context Persistence with Remember Tags

Survive conversation compaction:

DO capture:

• Architecture decisions
• Error resolutions
• User preferences
• Key file locations

DON'T capture:

• Progress (use todos)
• Temporary state
• Info already in AGENTS.md

6. Continuation Enforcement

Claude is bound to the task list. Cannot stop until EVERY task is COMPLETE.

Pre-Conclusion Checklist:

• TODO LIST: Zero pending/in_progress tasks
• FUNCTIONALITY: All requested features work
• TESTS: All tests pass (if applicable)
• ERRORS: Zero unaddressed errors
• ARCHITECT: Verification passed

If ANY unchecked → CONTINUE WORKING.

Configuration

Project-Level Config

Create .claude/CLAUDE.md in your project:

# Project Context

This is a TypeScript monorepo using:
- Bun runtime
- React for frontend
- PostgreSQL database

## Conventions
- Use functional components
- All API routes in /src/api
- Tests alongside source files

Agent Customization

Edit agent files in ~/.claude/agents/:

---
name: architect
description: Your custom description
tools: Read, Grep, Glob, Bash, Edit
model: opus  # or sonnet, haiku
---

Your custom system prompt here...

Configuration Precedence

If both exist, project-scoped takes precedence over global:

./.claude/CLAUDE.md  (project)  →  Overrides  →  ~/.claude/CLAUDE.md  (global)

MCP Server Configs

OMC includes server definitions for:

• Exa: Semantic search
• Context7: Code context understanding
• grep.app: GitHub code search

LSP Tools Integration

Real LSP server integration with 11 tools:

Requirements: Language servers must be installed (typescript-language-server, pylsp, rust-analyzer, gopls, etc.)

AST Tools Integration

Pattern-based code search and transformation:

Uses @ast-grep/napi with meta-variables like $VAR and $$$.

Troubleshooting

Diagnosis Tool

/oh-my-claudecode:doctor

Automatically checks:

• Plugin installation
• Hook configuration
• Agent availability
• Skill registration
• CLAUDE.md presence

Common Issues

Issue: "Agent not found"

• Solution: Ensure plugin is installed and agents are in ~/.claude/agents/

Issue: "Skills not activating"

• Solution: Run /oh-my-claudecode:omc-default to update CLAUDE.md

Issue: "Hooks not working"

• Solution: Check ~/.claude/hooks.json exists and contains OMC hooks

Issue: "HUD not showing"

• Solution: Run /oh-my-claudecode:hud setup to install/repair statusline

Manual Uninstall

# Remove agents
rm ~/.claude/agents/{architect,researcher,explore,designer,writer,vision,critic,analyst,executor,planner,qa-tester}*.md

# Remove commands
rm ~/.claude/commands/{orchestrate,omc-default,ultrawork,deepsearch,analyze,plan,review,planner,ralph-loop,cancel-ralph}*.md

# Remove skills
rm -rf ~/.claude/skills/{ultrawork,deepinit,git-master,frontend-ui-ux}

# Or use uninstall script
curl -fsSL https://raw.githubusercontent.com/Yeachan-Heo/oh-my-claudecode/main/scripts/uninstall.sh | bash

Getting Help

• Documentation: Full README
• Issues: GitHub Issues
• Website: Project Website

Migration from 2.x

All old commands still work:

What's New in 3.x:

• Autopilot mode: Full autonomous execution (flagship feature)
• Auto-activation: No need for explicit commands
• Enhanced memory: Three-tier notepad system
• Better planning: Ralplan iterative consensus
• Advanced features: Delegation categories, directory diagnostics, session resume

Quick Reference

Essential Commands

# Setup (one-time)
/oh-my-claudecode:omc-setup

# Autopilot (recommended)
> "autopilot: build a REST API for tasks"

# Manual modes
/oh-my-claudecode:orchestrate <task>
/oh-my-claudecode:ralph <task>
/oh-my-claudecode:ultrawork <task>
/oh-my-claudecode:planner <task>

# Utilities
/oh-my-claudecode:note <content>
/oh-my-claudecode:deepsearch <query>
/oh-my-claudecode:doctor

Magic Keywords

Just include in natural language:

• autopilot → Full autonomous execution
• ralph or "don't stop" → Persistence mode
• ulw or "fast" → Maximum parallelism
• plan → Planning session
• analyze → Deep analysis
• search → Deep search

Cancellation

# Generic stop
> "stop" or "cancel"

# Specific cancellation
/oh-my-claudecode:cancel-autopilot
/oh-my-claudecode:cancel-ralph
/oh-my-claudecode:cancel-ultrawork
/oh-my-claudecode:cancel-ultraqa

Architecture Comparison: vs. oh-my-opencode

Oh my Claudecode is inspired by oh-my-opencode, reimagined for Claude Code.

Key Differences

What You Gain

• Simpler Setup: One command vs. multi-step plugin installation
• Native Integration: Works directly with Claude Code
• Consistent Behavior: All agents use Claude models
• Easier Customization: Edit markdown files to customize agents
• Context Preservation: Same conversation, different behaviors

What You Lose

• Model Diversity: Can't use GPT-5.2 or Gemini models
• Advanced Terminal: No Tmux integration (standard Bash sufficient)

Migration Tips

Credits & License

• Inspired by: oh-my-opencode by code-yeongyu
• License: MIT
• Author: Yeachan Heo
• Version: 3.3.8

Summary

Oh my Claudecode transforms Claude Code into an intelligent multi-agent orchestration system:

✅ 28 specialized agents with smart model routing ✅ Autopilot mode for zero-effort autonomous execution ✅ 26+ composable skills that auto-activate based on context ✅ 19 lifecycle hooks for enhanced behavior ✅ Three-tier memory that survives context compaction ✅ Persistence mode (Ralph) for completion guarantee ✅ Parallel execution (Ultrawork) for maximum speed ✅ Strategic planning with interactive interviews ✅ Quality assurance with automated fix cycles ✅ No learning curve - just describe what you want

Get Started: Install the plugin, run setup, then just say what you want to build. Autopilot handles the rest.

# Install
claude plugin install oh-my-claude-sisyphus

# Setup
/oh-my-claudecode:omc-setup

# Build something
> "autopilot: build a REST API for task management"

That's it. Welcome to the future of AI-assisted development.