⚡ Olympus

Multi-Agent Orchestration for Claude Code

Summon the gods of code.

Why Olympus? • Quick Start • What is Olympus? • How It Works • AI-DLC Workflow • Self-Learning • Use Cases • Reference • Docs

⚡ Why Olympus?

AI coding assistants are powerful — but out of the box, they produce prototypes, not production software. The code works, but there is no structured workflow, no learning between sessions, no persistence when tasks get complex, and no coordination between specialized capabilities. You end up doing the orchestration yourself.

Olympus adds a quality layer on top of Claude Code. It brings structured development workflows, a pantheon of specialized agents, a self-learning system that carries context across sessions, and persistence mechanisms that keep Claude working until your tasks are actually done.

The result is less "AI that answers questions" and more "AI development team that ships software."

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.

What is Olympus?

Olympus is a multi-agent orchestration system for Claude Code. It turns a single Claude session into a coordinated team of specialized agents — each optimized for a different kind of work.

Key capabilities: 20+ specialized agents (Oracle, Prometheus, Olympian, Librarian, and more), smart model routing that auto-selects Haiku/Sonnet/Opus based on task complexity, an AI-DLC structured development workflow, a self-learning system that persists context across sessions, continuation enforcement so tasks never stall, 20 slash commands, and support for any tech stack — Python, .NET, Go, Rust, Java, or anything else.

🔧 How It Works

Olympus operates as a multi-agent orchestration system with smart model routing and 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[Result]
    E --> G
    F --> G
    G --> H{Incomplete todos?}
    H -->|Yes| B
    H -->|No| I[Done]
    D -.-> J[Learning System]
    E -.-> J
    F -.-> J
    J --> K[(Feedback Storage)]
    K -.->|Next session| B

Session Flow:

1. User Request → Arrives with learned context already injected from previous sessions
2. Orchestrator → Analyzes task complexity and delegates to specialized agents
3. Model Routing → Selects the appropriate model tier: Haiku (simple), Sonnet (standard), or Opus (complex)
4. Agents Execute → Specialized subagents complete their tasks and return results
5. Learning System → Hooks passively capture corrections, preferences, and discoveries during execution
6. Persistence → If incomplete todos remain, the orchestrator continues working
7. Result → User sees the completed work

Cross-Session Learning:

The learning system operates across session boundaries:

• During Session: Hooks passively capture 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 reads stored learnings and injects relevant context into the initial prompt
• Context Injected:
  • User preferences (verbosity, autonomy, explicit rules)
  • Recurring corrections (mistakes to avoid)
  • Project conventions (tech stack, patterns)
  • 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. 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 Continuation - Blocks session exit when incomplete tasks remain
• 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 |

🗺️ AI-DLC Workflow

Olympus includes a structured development workflow inspired by AWS AI-DLC (AI-Driven Development Life Cycle). It guides you through three phases — Inception (what and why), Construction (how), and Operations (deploy, placeholder) — with human approval gates at every stage. The workflow adapts to your project: stages are conditionally executed based on complexity, scope, and whether you are working on a greenfield or brownfield codebase.

Phases and Stages

Inception — determine what to build and why:

• Workspace Detection (always) — scans for existing code, resumes prior workflows
• Reverse Engineering (brownfield only) — analyzes existing codebase
• Requirements Analysis (always) — gathers functional and non-functional requirements
• Workflow Planning (always) — determines which construction stages to execute
• Units Generation (conditional) — decomposes work into implementable units
• User Stories (conditional) — generates per-unit personas and acceptance criteria
• Bolt Planning (conditional) — decomposes units into executable bolts with dependency tracking

Construction — determine how to build it:

• Per-unit loop (for each unit of work):
  • Functional Design, NFR Requirements, NFR Design, Infrastructure Design (all conditional)
  • Code Generation (always)
• Build and Test (always) — after all units complete

Operations — placeholder for future deployment and monitoring workflows.

How to Use

# Start a new AI-DLC workflow
/plan build a user authentication system

# Resume an interrupted workflow
/continue

# Review at any gate
/review

State is tracked in aidlc-docs/{workflow-id}/aidlc-state.md and aidlc-docs/{workflow-id}/checkpoint.json. Use /continue to resume from exactly where you left off, even across sessions.

• Start AI-DLC workflow: /plan build a new feature
• Inception phase: Prometheus interviews you about requirements, generates user stories, and plans the architecture
• Workflow planning: Determines which stages to execute based on project needs
• Construction phase: Per-unit functional design, NFR assessment, and code generation
• Resume if interrupted: /continue picks up from the last checkpoint
• Review at any gate: /review to evaluate plans before proceeding

Plans and artifacts are saved to aidlc-docs/{workflow-id}/ in your project directory.

Skill stacking: Combine /plan with /ascent for persistent execution that never stops, or with /ultrawork for maximum parallelism across units.

🧠 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.

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:

• Starts an AI-DLC workflow with full Inception phase
• Prometheus interviews you about requirements
• Generates requirements, user stories, and application design
• Creates a construction plan with units of work
• Each unit goes through design, code generation, and testing
• All artifacts saved to aidlc-docs/{workflow-id}/ with full audit trail

🧠 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.

Reference

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 | | /archive [id\|--all] | Archive completed AI-DLC workflows to aidlc-docs/completed/ | | /continue | Resume an active AI-DLC workflow from last checkpoint | | /retro | Run a guardrail retrospective on the current AI-DLC workflow | | /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 |

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

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

What Gets Installed

~/.claude/
├── agents/                  # 19 agent definitions (tiered variants)
│   ├── oracle.md
│   ├── prometheus.md
│   ├── olympian.md
│   └── ...
├── skills/                  # 19 slash commands
│   ├── olympus/SKILL.md
│   ├── ultrawork/SKILL.md
│   ├── plan/SKILL.md
│   ├── continue/SKILL.md
│   └── ...
├── hooks/                   # Event handlers
│   ├── keyword-detector.mjs
│   ├── persistent-mode.mjs
│   └── ...
├── olympus/
│   ├── rules/              # AI-DLC workflow rules
│   │   ├── common/
│   │   ├── inception/
│   │   └── construction/
│   └── learning/           # Global learning data
└── CLAUDE.md               # Olympus system prompt

Installation

Prerequisites

• Claude Code installed
• Node.js 20+ (node -v to check)

Global Installation (Recommended)

Install Olympus globally to enable it across all your projects:

npm install -g olympus-ai
olympus-ai install

This installs agents, skills, rules, and hooks to ~/.claude/ so every Claude Code session has access to Olympus.

Local Project Installation

Install Olympus as a dev dependency for a specific project. This is useful for teams that want Olympus pinned to a specific version in their repo:

# Install as a dev dependency
npm install --save-dev olympus-ai

# Run the installer for this project only
npx olympus-ai install --local

This installs agents, skills, rules, hooks, and settings to ./.claude/ in your current project directory.

Note: You can use both. A global install provides Olympus across all projects, while a local install scopes everything to the current project. Local files take precedence over global ones.

Uninstall

Olympus provides a safe uninstall that only removes Olympus-owned files — your own Claude Code agents, skills, hooks, and CLAUDE.md content are preserved.

Quick Uninstall (One Command)

For global installations, a single npm command handles everything — the preuninstall hook automatically cleans up Olympus config files before removing the package:

npm uninstall -g olympus-ai

For local project installations:

npm uninstall olympus-ai

Note: Local npm uninstall removes the package dependency but does not clean up .claude/ config files. Run npx olympus-ai uninstall --local first if you need to remove those, or see the manual steps below.

Manual Uninstall

If you prefer more control, or need to remove config files without uninstalling the package:

# Remove Olympus config files from ~/.claude/ (global)
olympus-ai uninstall

# Remove Olympus config files from ./.claude/ (current project)
olympus-ai uninstall --local

# Preview what would be removed without deleting anything
olympus-ai uninstall --dry-run

Then remove the npm package:

# Global
npm uninstall -g olympus-ai

# Local
npm uninstall olympus-ai

What Gets Removed

The uninstall command removes only files that Olympus installed:

• Olympus agent definitions from agents/ (e.g., oracle.md, prometheus.md)
• Olympus skill directories from skills/ (e.g., ultrawork/, plan/)
• The olympus/ directory (rules, learning data)
• Olympus hook scripts from hooks/
• Olympus hook entries from settings.json
• The Olympus section from CLAUDE.md (user content is preserved)
• The .olympus-version.json metadata file
• The Olympus plugin registration

Any custom agents, skills, hooks, or CLAUDE.md content you added yourself will not be touched.

Requirements

• Claude Code installed and configured
• 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/
│   ├── cli/          # CLI entry point (olympus-ai command)
│   ├── installer/    # Installation logic
│   ├── hooks/        # Event handlers (session, tools, learning)
│   ├── learning/     # Self-learning system
│   ├── features/     # Core features
│   │   └── workflow-engine/  # AI-DLC workflow engine
│   ├── config/       # Configuration management
│   ├── shared/       # Shared types and utilities
│   └── __tests__/    # Test suite (3100+ tests)
├── resources/
│   ├── agents/       # Agent markdown definitions
│   ├── skills/       # Slash command definitions
│   └── rules/        # AI-DLC workflow rules
├── dist/             # Build output
├── docs/             # Documentation
└── scripts/          # Build scripts

Documentation

• Getting Started Guide
• CLI Reference
• Workflow Guide — AI-DLC workflow for structured development
• Brownfield Projects — Working with existing codebases
• Learning System — How Olympus learns from your interactions
• Changelog

License

MIT - see LICENSE

Credits

Summon the gods of code.