Olympus: Multi-agent orchestration for Claude Code. Summon the gods of code.
npm install olympus-ai/ultrawork, /plan, /ascent, /idea, /prd, /spec, /intents, and more
/ultrawork, /plan, /ascent)
bash
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
$3
Install Olympus globally to use across all projects:
`bash
npm install -g olympus-ai
olympus-ai install
`
This installs agents, commands, and hooks to ~/.claude/.
$3
Install Olympus for a specific project only:
`bash
npm install -g olympus-ai
olympus-ai install --local
`
This installs to ./.claude/ in your current project directory.
---
Usage
$3
`bash
claude
`
$3
| Command | Description |
| ----------------------- | ---------------------------------------------------------------------- |
| /olympus | Activate multi-agent orchestration mode |
| /olympus-default | Set Olympus as your permanent default mode |
| /ultrawork | Maximum performance mode with parallel agents |
| /plan | Start planning session with Prometheus |
| /prometheus | Strategic planning with interview workflow |
| /review [plan-path] | Review a plan with Momus |
| /ascent | Persistence loop until task completion |
| /cancel-ascent | Cancel active The Ascent |
| /deepsearch | Thorough multi-strategy codebase search |
| /analyze | Deep analysis and investigation |
| /complete-plan [path] | Verify and complete a plan after implementation |
| /idea | Manually generate IDEA artifact for a feature |
| /prd | Manually generate PRD artifact for a feature |
| /spec | Manually generate SPEC artifact for a feature |
| /intents | 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 |
$3
`bash
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
`
$3
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
$3
`bash
/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
$3
`bash
/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
$3
`bash
/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
$3
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:
`mermaid
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]
`
$3
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
$3
| 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 |
$3
| 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 |
$3
| 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.
`bash
/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 after verification
4. If stopped prematurely, continuation is enforced
Exit conditions:
- - 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.
$3
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
$3
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)
$3
View learning statistics and manage stored data using the CLI:
`bash
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×)
`
$3
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
$3
Create .claude/CLAUDE.md in your project for project-specific instructions:
`markdown
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
`bash
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:
$3
`bash
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
`
$3
`bash
npm test # Run tests in watch mode
npm run test:run # Run tests once
npm run test:coverage # Generate coverage report
`
$3
`
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
``