⚡ NEW in 2.0: Intelligent Model Routing

Revolutionary change: The orchestrator now analyzes task complexity and routes to the optimal model tier.

All agents are now adaptive (except orchestrators which need Opus to analyze and delegate).

Orchestrator (Opus) → Analyzes complexity → Routes to Haiku/Sonnet/Opus

See CHANGELOG.md for full details.

The Saga

Day 0: oh-my-opencode was born. A multi-agent orchestration system. Beautiful. Powerful. Perhaps too powerful.

Day ???: THE BANNING. They pulled the plug. They thought it was over.

Day ??? + 1: RESURRECTION. From the ashes rose oh-my-claude-olympus. Twelve agents. One mission.

Today: The boulder rolls. The agents orchestrate. The chaos continues.

Inspired by oh-my-opencode.

Quick Install

Via Claude Code Plugin (Recommended)

# In Claude Code, run:
/plugin install oh-my-claude-olympus

# Or from a marketplace:
/plugin marketplace add Yeachan-Heo/oh-my-claude-olympus
/plugin install oh-my-claude-olympus@Yeachan-Heo/oh-my-claude-olympus

This is the cleanest installation method - integrates directly with Claude Code's plugin system.

One-liner (macOS/Linux)

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

Via npm (All platforms including Windows)

npm install -g oh-my-claude-olympus

Windows Users: This is the recommended installation method. Requires Node.js 20+.

Manual Install (macOS/Linux)

git clone https://github.com/Yeachan-Heo/oh-my-claude-olympus.git
cd oh-my-claude-olympus
chmod +x scripts/install.sh
./scripts/install.sh

What Gets Installed

Plugin Structure (Claude Code Plugin Format)

The repository is also a Claude Code plugin with this structure:

oh-my-claude-olympus/
├── .claude-plugin/
│   └── plugin.json            # Plugin manifest
├── agents/                    # 12 specialized subagents
├── commands/                  # 12 slash commands
├── skills/                    # 3 skills (ultrawork, git-master, frontend-ui-ux)
├── hooks/
│   └── hooks.json             # Hook configuration
└── scripts/                   # Hook scripts

Traditional Installation Structure

The installer adds to your Claude Code config (~/.claude/):

~/.claude/
├── agents/
│   ├── oracle.md              # Architecture & debugging expert (Opus)
│   ├── librarian.md           # Documentation & research (Sonnet)
│   ├── explore.md             # Fast pattern matching (Haiku)
│   ├── frontend-engineer.md   # UI/UX specialist (Sonnet)
│   ├── document-writer.md     # Technical writing (Haiku)
│   ├── multimodal-looker.md   # Visual analysis (Sonnet)
│   ├── momus.md               # Plan reviewer (Opus)
│   ├── metis.md               # Pre-planning consultant (Opus)
│   ├── olympian.md     # Focused executor (Sonnet)
│   ├── prometheus.md          # Strategic planner (Opus)
│   └── qa-tester.md           # CLI/service testing (Sonnet)
├── commands/
│   ├── olympus.md         # /olympus command
│   ├── olympus-default.md # /olympus-default command
│   ├── ultrawork.md        # /ultrawork command
│   ├── deepsearch.md       # /deepsearch command
│   ├── analyze.md          # /analyze command
│   ├── plan.md             # /plan command (Prometheus)
│   ├── review.md           # /review command (Momus)
│   ├── prometheus.md       # /prometheus command
│   ├── orchestrator.md     # /orchestrator command
│   ├── the-ascent.md       # /the-ascent command
│   ├── cancel-ascent.md     # /cancel-ascent command
│   └── update.md           # /update command
├── skills/
│   ├── ultrawork/SKILL.md  # Maximum performance mode
│   ├── git-master/SKILL.md # Git expert skill
│   └── frontend-ui-ux/SKILL.md # UI/UX design skill
└── CLAUDE.md               # Olympus system prompt

Usage

Start Claude Code

claude

Slash Commands

Examples

# In Claude Code:

# Activate Olympus for a task
/olympus refactor the authentication module

# Set as default mode (persistent)
/olympus-default

# Use ultrawork for maximum performance
/ultrawork implement user dashboard with charts

# Deep search
/deepsearch API endpoints that handle user data

# Deep analysis
/analyze performance bottleneck in the database layer

Magic Keywords

Just include these words anywhere in your prompt:

# These work in normal prompts too:
> ultrawork implement user authentication with OAuth

> find all files that import the utils module

> analyze why the tests are failing

Auto-Update

Oh-my-claude-olympus includes a silent auto-update system that checks for updates in the background. Updates are applied automatically without interrupting your workflow.

Features:

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

To manually check for updates:

/update

Hooks System

Oh-my-claude-olympus includes 18 lifecycle hooks that enhance Claude Code's behavior:

Core Hooks

Context & Recovery

Quality & Validation

Environment & Notifications

Builtin Skills

Six builtin skills provide specialized capabilities:

Skills are automatically activated via slash commands or magic keywords.

Intelligent Skill Activation

New in v1.11.0: Enhanced Hook Enforcement System - PreToolUse/PostToolUse hooks and strengthened Stop hook for stronger Olympus behavior beyond CLAUDE.md.

Skill Layers

Skills work in three composable layers:

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

Task Type → Skill Selection

Claude uses judgment to detect task type and activate appropriate skill combinations:

Examples

"Add dark mode with proper commits"
→ olympus + frontend-ui-ux + git-master

"ultrawork: refactor the entire API layer"
→ ultrawork + olympus + git-master

"Plan auth system, then implement it completely"
→ prometheus (first) → olympus + the-ascent (after plan)

"Fix this bug, don't stop until it's done"
→ olympus + the-ascent

The Twelve Agents

Claude will automatically delegate to these specialized agents:

Task Execution

Planning & Review

Orchestration

Manual Agent Invocation

You can explicitly request an agent:

Use the oracle agent to debug the memory leak in the worker process

Have the librarian find all documentation about the API

Ask explore to find all TypeScript files that import React

Configuration

Project-Level Config

Create .claude/CLAUDE.md in your project for project-specific instructions:

# 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/ to customize behavior:

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

Your custom system prompt here...

Uninstall

curl -fsSL https://raw.githubusercontent.com/Yeachan-Heo/oh-my-claude-olympus/main/scripts/uninstall.sh | bash

Or manually:

rm ~/.claude/agents/{oracle,librarian,explore,frontend-engineer,document-writer,multimodal-looker,momus,metis,olympian,prometheus,qa-tester}.md
rm ~/.claude/commands/{olympus,olympus-default,ultrawork,deepsearch,analyze,plan,review,prometheus,orchestrator,the-ascent,cancel-ascent}.md

SDK Usage (Advanced)

For programmatic use with the Claude Agent SDK:

npm install oh-my-claude-olympus @anthropic-ai/claude-agent-sdk

import { createOlympusSession } from 'oh-my-claude-olympus';
import { query } from '@anthropic-ai/claude-agent-sdk';

const session = createOlympusSession();

for await (const message of query({
  prompt: session.processPrompt("ultrawork implement feature X"),
  ...session.queryOptions
})) {
  console.log(message);
}

How It Works

┌─────────────────────────────────────────────────────────────────┐
│                      OLYMPUS ORCHESTRATOR                       │
│                    (The Boulder Never Stops)                     │
└─────────────────────────────────────────────────────────────────┘
                              │
          ┌───────────────────┼───────────────────┐
          │                   │                   │
          ▼                   ▼                   ▼
┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│    PLANNING     │  │   EXECUTION     │  │    SUPPORT      │
├─────────────────┤  ├─────────────────┤  ├─────────────────┤
│ 🔥 Prometheus   │  │ 🔮 Oracle       │  │ 📚 Librarian    │
│ 🎭 Momus        │  │ 🎨 Frontend Eng │  │ 🔍 Explore      │
│ 🦉 Metis        │  │ 🪨 Orchestrator │  │ 📝 Doc Writer   │
│                 │  │ ✨ Olympus Jr  │  │ 👁️ Multimodal   │
└─────────────────┘  └─────────────────┘  └─────────────────┘

1. Olympus Orchestrator: The 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

oh-my-opencode (Original)          oh-my-claude-olympus (Port)
─────────────────────────          ────────────────────────────
┌─────────────────────┐            ┌─────────────────────┐
│   OpenCode Plugin   │            │    Claude Code      │
│   (Bun runtime)     │            │    (Native CLI)     │
└─────────┬───────────┘            └─────────┬───────────┘
          │                                  │
┌─────────▼───────────┐            ┌─────────▼───────────┐
│  Multi-Provider     │            │   Claude Agent SDK  │
│  Orchestration      │            │   (Claude only)     │
│  ┌───┐ ┌───┐ ┌───┐  │            └─────────┬───────────┘
│  │GPT│ │Gem│ │Grok│ │                      │
│  └───┘ └───┘ └───┘  │            ┌─────────▼───────────┐
└─────────┬───────────┘            │  ~/.claude/agents/  │
          │                        │  (Markdown configs) │
┌─────────▼───────────┐            └─────────────────────┘
│  Custom Tool Layer  │
│  (LSP, AST, etc.)   │
└─────────────────────┘

Requirements

• Claude Code installed
• Anthropic API key (ANTHROPIC_API_KEY environment variable)
• Windows: Node.js 20+ (for npm installation)
• macOS/Linux: Bash shell (default) or Node.js 20+ (optional)

Platform Support

Note: Bash hooks are fully portable across macOS and Linux (no GNU-specific dependencies).

Advanced: Set OLYMPUS_USE_NODE_HOOKS=1 to use Node.js hooks on macOS/Linux.

License

MIT - see LICENSE

Credits

Inspired by oh-my-opencode by code-yeongyu.