⚡ Olympus

Multi-Agent Orchestration for Claude Code

Summon the gods of code.

Why Olympus? • Quick Start • Self-Learning • Use Cases • Agents • Docs

What is Olympus?

Olympus is a multi-agent orchestration system for Claude Code. It provides:

• 🧠 Self-Learning System - Learns your preferences, patterns, and codebase over time
• 🤖 20+ Specialized Agents - Oracle, Prometheus, Olympian, Librarian, and more
• ⚡ Smart Model Routing - Auto-selects Haiku/Sonnet/Opus based on task complexity
• 📋 Todo Management - Tracks progress with real-time updates
• 🔄 Background Execution - Long-running tasks run async with notifications
• 🎯 Continuation Enforcement - Never stops until all tasks are complete
• 💬 18+ Slash Commands - /ultrawork, /plan, /ascent, /idea, /prd, /spec, /intents, and more
• 🔮 Structured Workflows - IDEA → PRD → SPEC → INTENTS pipeline for complex features
• 🔮 Magic Keywords - Natural language triggers for enhanced modes

Why Olympus?

Olympus transforms Claude Code from a single agent into a pantheon of specialized experts that work together seamlessly.

🧠 Self-Learning System

Olympus learns from your preferences and evolves over time.

• Active Agent Learning - Agents proactively record patterns, gotchas, and workarounds they discover during work
• Passive Feedback Capture - Automatically detects corrections, preferences, and patterns from your interactions
• Pattern Extraction - Identifies recurring feedback and adapts behavior accordingly
• Preference Learning - Infers your communication style (concise vs. detailed, autonomous vs. collaborative)
• Agent Performance Tracking - Monitors which agents succeed or fail for specific tasks
• Token Efficiency Tracking - Automatically tracks token usage per agent to optimize cost without manual intervention
• Discovery Storage - Structured JSONL storage with verification tracking and confidence scoring
• Context Injection - Learned preferences and discoveries are automatically applied in new sessions

The more you use Olympus, the better it understands your workflow.

⚡ Intelligent Orchestration

• Smart Delegation - Routes tasks to specialized agents based on complexity
• Model Routing - Automatically selects Haiku/Sonnet/Opus to optimize cost and performance
• Parallel Execution - Runs independent tasks concurrently for maximum throughput

🎯 Continuous Delivery

• Todo Management - Tracks progress across complex multi-step tasks
• Continuation Enforcement - Never stops until all tasks are verified complete
• Background Operations - Long-running builds, tests, and installs run async with notifications

🔧 Developer Experience

• Zero Configuration - Works out-of-the-box with sensible defaults
• Slash Commands - 13+ productivity commands (/ultrawork, /plan, /ascent)
• Magic Keywords - Natural language triggers for enhanced modes

📊 Olympus vs. Manual Claude Usage

| Feature | Manual Claude | Olympus | |---------|---------------|---------| | Multi-Step Tasks | Sequential, manual tracking | Automatic todo management | | Parallel Execution | One task at a time | 3-5x faster with concurrent agents | | Learning | Repeats mistakes | Learns from corrections automatically | | Model Selection | Manual switching | Smart routing (cost optimized) | | Task Persistence | Stops when asked | Continues until verified complete | | Background Tasks | Blocks waiting | Runs async with notifications | | Agent Specialization | Generic responses | 20+ experts for specific domains | | Token Awareness | Manual tracking | Automatic efficiency guidance |

Quick Start

Get started in under 60 seconds:

# Install globally
npm install -g olympus-ai

# Initialize Olympus
olympus-ai install

# Start Claude Code
claude

# Try it out
/olympus implement a REST API for user management

That's it. Olympus is now active and learning from your interactions.

Installation

Global Installation (Recommended)

Install Olympus globally to use across all projects:

npm install -g olympus-ai
olympus-ai install

This installs agents, commands, and hooks to ~/.claude/.

Local Project Installation

Install Olympus for a specific project only:

npm install -g olympus-ai
olympus-ai install --local

This installs to ./.claude/ in your current project directory.

Usage

Start Claude Code

claude

Slash Commands

| Command | Description | | ----------------------- | ---------------------------------------------------------------------- | | /olympus <task> | Activate multi-agent orchestration mode | | /olympus-default | Set Olympus as your permanent default mode | | /ultrawork <task> | Maximum performance mode with parallel agents | | /plan <description> | Start planning session with Prometheus | | /prometheus <task> | Strategic planning with interview workflow | | /review [plan-path] | Review a plan with Momus | | /ascent <task> | Persistence loop until task completion | | /cancel-ascent | Cancel active The Ascent | | /deepsearch <query> | Thorough multi-strategy codebase search | | /analyze <target> | Deep analysis and investigation | | /complete-plan [path] | Verify and complete a plan after implementation | | /idea <feature> | Manually generate IDEA artifact for a feature | | /prd <feature> | Manually generate PRD artifact for a feature | | /spec <feature> | Manually generate SPEC artifact for a feature | | /intents <feature> | Manually generate INTENTS artifact for a feature | | /workflow-status | View all active structured workflows and their status | | /olympus next | Get the next ready task from current workflow | | /doctor | Diagnose and fix olympus installation issues | | /deepinit | Deep codebase initialization with hierarchical AGENTS.md documentation | | /update | Check for and install updates |

Examples

# 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

# Start planning
/plan build a task management application

# Deep search
/deepsearch API endpoints that handle user data

Magic Keywords

Include these words anywhere in your prompt to activate enhanced modes:

| Keyword | Effect | | -------------------------- | -------------------------------------- | | ultrawork, ulw, uw | Activates parallel agent orchestration | | search, find, locate | Enhanced search mode | | analyze, investigate | Deep analysis mode |

Use Cases

🏗️ Complex Refactoring

/ascent refactor the entire authentication module to use OAuth 2.0

What happens:

• Creates todo list for all subtasks
• Delegates to specialized agents (Oracle for architecture, Olympian for execution)
• Runs tests in background
• Continues until all tasks verified complete

📊 Multi-Agent Research

/ultrawork research and document all API endpoints in the codebase

What happens:

• Spawns multiple agents in parallel (Explore for search, Librarian for docs)
• Aggregates findings
• Generates comprehensive documentation
• ~3x faster than sequential execution

📋 Strategic Planning

/plan build a real-time chat application with WebSocket support

What happens:

• Prometheus interviews you about requirements
• Creates detailed work plan with phases
• Identifies dependencies and risks
• Saves plan to .olympus/plans/ for execution

🧠 Learning Your Workflow

Automatic - no command needed

You: "No, use TypeScript interfaces instead of types" → Olympus records this preference

You: "Use functional components, not class components" → Olympus learns your React style

Next session: Claude automatically applies these preferences without being told.

Architecture

Olympus operates as a three-tier orchestration system with a continuous learning loop:

graph TD
    A[User Request] --> B[Orchestrator]
    B --> C{Task Analysis}
    C -->|Simple| D[Haiku Agent]
    C -->|Standard| E[Sonnet Agent]
    C -->|Complex| F[Opus Agent]
    D --> G[Learning System]
    E --> G
    F --> G
    G --> H[Feedback Storage]
    H -.->|Next Session| B
    B --> I[Todo Manager]
    I --> J[Background Executor]
    J --> K[Result]

How It Works

Current Session Flow:

1. User Request → Arrives with learned context already injected at SessionStart
2. Orchestrator → Analyzes task complexity and delegates to appropriate agents
3. Model Router → Selects Haiku (simple), Sonnet (standard), or Opus (complex)
4. Agents Execute → Specialized agents complete their tasks
5. Learning System → Passively captures feedback from corrections, preferences, and patterns
6. Feedback Storage → Stores learned preferences, agent performance, and discoveries
7. Result → User sees the completed work

Learning & Context Injection (Between Sessions):

The learning system operates across session boundaries:

• During Session: Captures feedback from user corrections ("No, use async/await"), preferences ("Always use TypeScript"), and agent discoveries (gotchas, workarounds)
• Storage: Writes to ~/.claude/olympus/learning/ (global) and .olympus/learning/ (project-specific)
• Next Session Start: SessionStart hook automatically injects learned context into the initial prompt
• Context Types Injected:
  • User preferences (verbosity, autonomy, explicit rules)
  • Recurring corrections (mistakes to avoid)
  • Project conventions (tech stack, patterns)
  • Agent performance notes (weak areas to watch)
  • Recent discoveries (technical insights about your codebase)

Key Insight: Context injection happens at the beginning of each session (via SessionStart hook), not in the result. This means every new conversation starts with Claude already aware of your preferences and past learnings.

Key Components:

• Orchestrator - Delegates tasks to specialized agents based on complexity
• Model Router - Selects optimal tier (Haiku/Sonnet/Opus) to balance cost and capability
• Learning System - Captures feedback passively and builds preference models
• Todo Manager - Tracks multi-step task progress with real-time status updates
• Background Executor - Runs long-running operations (builds, tests, installs) async with notifications
• Feedback Storage - Persists learned preferences, patterns, and discoveries across sessions

Available Agents

Task Execution

| Agent | Model | Best For | | --------------------- | ------ | -------------------------------------------------------------- | | Oracle | Opus | Complex debugging, architecture decisions, root cause analysis | | Librarian | Sonnet | Finding documentation, understanding code organization | | Explore | Haiku | Quick file searches, pattern matching, reconnaissance | | Frontend Engineer | Sonnet | UI components, styling, accessibility | | Document Writer | Haiku | README files, API docs, code comments | | Multimodal Looker | Sonnet | Analyzing screenshots, diagrams, mockups | | QA Tester | Sonnet | Interactive CLI/service testing with tmux | | Olympian | Sonnet | Focused task execution, direct implementation |

Planning & Review

| Agent | Model | Best For | | -------------- | ----- | ----------------------------------------------------------------- | | Prometheus | Opus | Strategic planning, work plans, requirement gathering | | Momus | Opus | Critical plan review, feasibility assessment, risk identification | | Metis | Opus | Pre-planning analysis, hidden requirement detection |

Tiered Variants (Smart Model Routing)

| Domain | LOW (Haiku) | MEDIUM (Sonnet) | HIGH (Opus) | | ------------- | ----------------------- | ------------------- | ------------------------ | | Analysis | oracle-low | oracle-medium | oracle | | Execution | olympian-low | olympian | olympian-high | | Search | explore | explore-medium | - | | Research | librarian-low | librarian | - | | Frontend | frontend-engineer-low | frontend-engineer | frontend-engineer-high |

The Ascent

The Ascent is a persistence loop that binds Claude to your task until verified completion.

/ascent implement the entire authentication system

How it works:

1. Creates a todo list for all subtasks
2. Works continuously until all tasks complete
3. Can only exit by outputting <promise>DONE</promise> after verification
4. If stopped prematurely, continuation is enforced

Exit conditions:

• <promise>DONE</promise> - Work verified complete
• /cancel-ascent - User cancels the loop
• Max iterations (100) - Safety limit

Planning Workflow

1. Start planning: /plan build a new feature
2. Interview: Prometheus asks clarifying questions
3. Generate plan: Say "Create the plan" when ready
4. Review (optional): /review .olympus/plans/my-feature.md
5. Execute: Use /olympus or /ascent to implement

Plans are saved to .olympus/plans/ in your project directory.

Self-Learning System

Olympus continuously learns from your interactions to provide increasingly personalized assistance.

How It Works

Phase 1: Passive Feedback Capture

• Detects corrections: "No, that's wrong"
• Identifies rejections: "Stop", "Cancel"
• Recognizes clarifications: "I meant X"
• Captures enhancements: "Also add Y"
• Records praise: "Perfect", "Thanks"
• Extracts explicit preferences: "Always use X"

Phase 2: Pattern Extraction

• Clusters similar feedback using Jaccard similarity
• Identifies recurring corrections (minimum 3 occurrences)
• Categorizes patterns: style, behavior, tooling, communication

Phase 3: Preference Learning

• Infers verbosity level (concise vs. detailed)
• Determines autonomy preference (ask first vs. just do it)
• Tracks agent-specific performance
• Implements 30-day decay for outdated patterns

Phase 4: Context Injection

• Automatically applies learned preferences at session start
• Injects relevant discoveries about your codebase
• Limits injection to ~500 tokens to avoid context bloat

Phase 5: Agent Discovery

• Agents record technical insights about your project
• Discoveries include: gotchas, workarounds, patterns, dependencies
• Validated and deduplicated before storage
• Retrieved contextually in future sessions

Storage Locations

Global Learning:

~/.claude/olympus/learning/
├── feedback-log.jsonl          # All feedback entries (auto-rotates at 10k lines)
├── user-preferences.json        # Learned preferences
├── agent-performance.json       # Per-agent metrics
└── discoveries.jsonl            # Global discoveries (auto-rotates at 10k lines)

Project-Specific Learning:

.olympus/learning/
├── session-state.json           # Current session state
├── patterns.json                # Project patterns
└── discoveries.jsonl            # Project discoveries (auto-rotates at 10k lines)

Data Lifecycle:

• JSONL files automatically rotate when they exceed 10,000 lines
• Archived files are saved with timestamps (e.g., feedback-log.2026-01-28.old.jsonl)
• Manual cleanup available via CLI (see Managing Learning Data below)

Managing Learning Data

View learning statistics and manage stored data using the CLI:

# View learning statistics
olympus-ai learn --stats

# Preview cleanup (dry run)
olympus-ai learn --cleanup --dry-run

# Clean up entries older than 180 days (default)
olympus-ai learn --cleanup

# Clean up with custom age threshold
olympus-ai learn --cleanup --age 90

# Remove archived files
olympus-ai learn --cleanup --remove-archived

# View current learnings
olympus-ai learn --show

# Analyze feedback and update patterns
olympus-ai learn --analyze

# Forget all learnings
olympus-ai learn --forget

Example output:

Learning System Statistics
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Feedback Entries:    1247 (1.2 MB)
Discoveries:         123
Total Storage:       1.5 MB

Top Verified Discoveries:
  1. Prisma migrations must run before seeding (8×)
  2. This codebase uses kebab-case for files (6×)
  3. Environment variable DATABASE_URL required (5×)

Example

Session 1: You tell Claude "No, use async/await instead of .then()" → Olympus records this as a correction

Session 2: Similar situation arises → You provide the same feedback

Session 3: Olympus detects the pattern (3+ occurrences) → Learns your preference: "Use async/await over Promise chains"

Session 4+: This preference is automatically injected → Claude proactively uses async/await without being told

The learning happens silently in the background. No configuration required.

What Gets Installed

~/.claude/
├── agents/                  # 20+ agent definitions
│   ├── oracle.md
│   ├── prometheus.md
│   ├── olympian.md
│   └── ...
├── commands/                # 13+ slash commands
│   ├── olympus/skill.md
│   ├── ultrawork/skill.md
│   ├── plan.md
│   └── ...
├── hooks/                   # Event handlers
│   ├── keyword-detector.mjs
│   ├── persistent-mode.mjs
│   └── ...
└── CLAUDE.md               # Olympus system prompt

Configuration

Project-Level Config

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

# Project Context

This is a TypeScript monorepo using:

- React for frontend
- Node.js backend
- PostgreSQL database

## Conventions

- Use functional components
- All API routes in /src/api

Uninstall

# Remove agents and commands
rm -rf ~/.claude/agents ~/.claude/commands ~/.claude/hooks ~/.claude/CLAUDE.md

Requirements

• Claude Code installed
• Anthropic API key (ANTHROPIC_API_KEY environment variable)
• Node.js 20+ (for npm installation)

Contributing

We welcome contributions! Here's how to get started:

Development Setup

# Clone the repository
git clone https://github.com/mikev10/olympus.git
cd olympus

# Install dependencies
npm install

# Build the project
npm run build

# Test locally
node dist/cli/index.js install --local

Running Tests

npm test              # Run tests in watch mode
npm run test:run      # Run tests once
npm run test:coverage # Generate coverage report

Project Structure

olympus/
├── src/
│   ├── agents/       # Agent definitions
│   ├── features/     # Core features (routing, learning, etc.)
│   ├── hooks/        # Event handlers
│   ├── learning/     # Self-learning system
│   └── cli/          # CLI commands
├── agents/           # Agent markdown files (installed)
├── commands/         # Slash command files (installed)
└── scripts/          # Build and installation scripts

Documentation

• 📖 Getting Started Guide
• 💻 CLI Reference Guide - Complete command-line tool reference
• 🔄 Workflow Selection Guide - Choose the right workflow for your task
• 📋 Structured Workflows Guide - IDEA → PRD → SPEC → INTENTS pipeline for complex features
• 🤖 Agent Reference
• 🏗️ Architecture Overview
• 🗺️ Roadmap
• 📋 Changelog

License

MIT - see LICENSE

Credits

Summon the gods of code.