---
name: oh-my-opencode-agents
description: Deep dive into each oh-my-opencode agent - Sisyphus, Hephaestus, Oracle, Librarian, Explore - their characteristics,
  use cases, and when to use each. Use when working with oh my opencode agents.
domain: integrations
author: mahipal
license: Apache-2.0
subdomain: integrations
tags:
- agents
- ai-agent
- api
- integrations
- opencode
- third-party
version: 1.0.0
---

# Oh My OpenCode Agents

## Overview

Oh My OpenCode provides a curated suite of specialized agents, each optimized for specific tasks. This skill provides detailed guidance on when and how to use each agent effectively.

## When to Use
**Trigger phrases:**
- "oh my opencode agents"
- "Deep dive into each oh-my-opencode agent - Sisyphus, Hephaestus, Oracle, Librari"


- **Sisyphus**: When you have complex multi-step tasks that need agent autonomy to figure out the approach
- **Hephaestus**: When you need autonomous problem-solving with thorough research, especially for complex refactoring or feature implementation
- **Oracle**: After 2+ failed approaches, when you need architectural guidance, debugging strategy, or multi-system tradeoffs analysis
- **Librarian**: When you need to consult official documentation, open-source implementations, or best practices for unfamiliar libraries
- **Explore**: When you need rapid codebase exploration, pattern discovery across modules, or quick file/symbol location


## When NOT to Use

- When the platform has a native solution that works
- For one-time data imports (use CSV/JSON instead)
- When the API is deprecated or being sunset


## The Agent Team
- Primary agent handles core task execution
- Validator agent checks output quality
- Reporter agent formats and delivers results
- Each agent operates with clear input/output contracts


### Sisyphus — Main Orchestrator Agent

**Model**: Opus 4.6 (primary), with Prometheus (Planner) and Metis (Plan Consultant)

**Characteristics**:
- Goal-oriented execution without step-by-step instructions
- Fires 2-5 parallel explore/librarian agents before writing code
- Follows TODO lists strictly — forces continuation if quitting halfway
- Leverages LSP for refactoring — deterministic and surgical
- Comment checker — prevents AI from adding excessive comments

**Best For**:
- Complex multi-step tasks requiring coordination
- Tasks where you want the agent to figure out the approach
- Long-running autonomous work with minimal intervention

**When NOT to Use**:
- Simple, single-file changes (use quick category instead)
- When you need to closely control every step

**Key Patterns**:
- "Sisyphus doesn't waste time hunting for files himself; he keeps the main agent's context lean. Instead, he fires off background tasks to faster, cheaper models in parallel to map the territory for him."
- Uses hash-anchored edit tool (`LINE#ID` format) to validate content before changes
- Multi-model orchestration — delegates to specialists based on task type

### Hephaestus — Autonomous Deep Worker

**Model**: GPT 5.3 Codex Medium

**Characteristics**:
- Goal-oriented: Give objective, not recipe — determines steps itself
- Explores before acting: 2-5 parallel explore/librarian agents first
- End-to-end completion: Doesn't stop until 100% done with verification
- Pattern matching: Searches existing codebase for style consistency
- "Legitimate" precision — surgical, minimal code

**Best For**:
- Autonomous problem-solving with thorough research
- Complex refactoring requiring deep codebase understanding
- Feature implementation from scratch
- Tasks that need careful planning before execution

**When NOT to Use**:
- Quick fixes or trivial changes
- When you need to approve each step
- Tasks outside of software development

**Key Principles**:
- Explores existing patterns before writing
- Verifies all changes with lsp_diagnostics, build, tests
- Matches project's coding style

### Oracle — Architecture & Debugging Consultant

**Model**: GPT 5.2

**Characteristics**:
- High-IQ strategic consultation
- Complex debugging after 2+ failed fix attempts
- Architecture design decisions
- Multi-system tradeoffs analysis

**Best For**:
- Complex architecture design
- After completing significant work (self-review)
- 2+ failed fix attempts
- Unfamiliar code patterns
- Security/performance concerns
- Multi-system tradeoffs

**When NOT to Use**:
- Simple file operations (use direct tools)
- First attempt at any fix (try yourself first)
- Questions answerable from code already read
- Trivial decisions

**Consultation Pattern**:
1. Implement first attempt yourself
2. If 2+ attempts fail → Consult Oracle
3. Oracle provides architectural guidance
4. Implement Oracle's recommendations
5. Verify thoroughly

### Librarian — Documentation & Search Agent

**Model**: GLM-4.7

**Characteristics**:
- Official documentation search
- Open source implementation patterns
- Real-time source code digestion
- External library best practices

**Best For**:
- Working with unfamiliar libraries/APIs
- Finding how others solved similar problems
- Official API documentation lookup
- OSS implementation examples

**When NOT to Use**:
- Questions answerable from codebase already read
- Simple codebase questions (use Explore)
- Things inferable from existing patterns

**Trigger Phrases**:
- "How do I use [library]?"
- "Best practice for [framework feature]?"
- "Find examples of [library] usage"
- "Working with unfamiliar [package]"

### Explore — Fast Codebase Explorer

**Model**: Grok Code Fast 1

**Characteristics**:
- Blazing fast contextual grep
- Pattern discovery across modules
- Quick file and symbol location
- Multiple search angles in parallel

**Best For**:
- Finding specific patterns in codebase
- Locating files/functions/classes
- Cross-layer pattern discovery
- Quick codebase mapping

**When NOT to Use**:
- You know exactly what to search (use direct grep)
- Single keyword search (use grep)
- Known file location (use read)

**Usage Pattern**:
- Fire liberally for any non-trivial codebase question
- Use direct tools when you know the pattern
- Use Explore when multiple angles needed

## Agent Selection Matrix

| Task Type | Primary Agent | Secondary Agent |
|-----------|---------------|-----------------|
| Complex multi-step | Sisyphus | Hephaestus |
| Autonomous deep work | Hephaestus | Sisyphus |
| Architecture design | Oracle | Sisyphus |
| Complex debugging | Oracle | Hephaestus |
| Library integration | Librarian | Explore |
| Codebase exploration | Explore | Librarian |
| Quick fixes | Direct tools | Sisyphus |
| Unknown scope | Hephaestus | Oracle |

## Agent-Model Matching

For optimal performance, match agents to models:

| Agent | Recommended Model | Fallback |
|-------|------------------|----------|
| Sisyphus | Opus 4.6 | GPT-4.5, Claude 3.7 |
| Hephaestus | GPT 5.3 Codex Medium | GPT-4.5, Claude 3.7 |
| Oracle | GPT 5.2 | GPT-4.5, Claude 3.7 |
| Librarian | GLM-4.7 | GPT-4.5, Claude 3.7 |
| Explore | Grok Code Fast 1 | Any fast model |

## Parallel Execution Patterns
This section covers parallel execution patterns for the oh-my-opencode-agents skill.
Key operations include input validation, core processing, and output verification.
Refer to the skill overview for detailed usage instructions.


### Pattern 1: Multi-Agent Discovery
```
// Fire 2-5 agents in parallel for comprehensive understanding
- Hephaestus: Deep research on the problem domain
- Librarian: External documentation and examples
- Explore: Internal codebase patterns
- Oracle: Architecture considerations (if complex)
```

### Pattern 2: Sequential with Parallel Discovery
```
// Hephaestus fires parallel agents first, then synthesizes
1. Hephaestus launches parallel exploration
2. Waits for results
3. Synthesizes information
4. Implements solution
5. Verifies end-to-end
```

### Pattern 3: Emergency Consultation
```
// Hephaestus tries 2-3 approaches, then consults Oracle
1. First approach attempt
2. If fails → Alternative approach
3. If fails → Oracle consultation
4. Implement Oracle's recommendations
5. Verify
```

## Skill Integration
- Connects with existing toolchain via standard interfaces
- Supports webhook-based event notifications
- Compatible with CI/CD pipelines for automated workflows
- Provides structured output for downstream consumption


### Required Workflow Skills
- **superpowers:using-git-worktrees** — REQUIRED: Isolated workspace
- **superpowers:writing-plans** — Creates plans Sisyphus executes
- **superpowers:requesting-code-review** — Code review template
- **superpowers:finishing-a-development-branch** — Complete development

### Subagents Should Use
- **superpowers:test-driven-development** — Subagents follow TDD
- **superpowers:systematic-debugging** — Debug failures properly

## Quality Gates

All agents must follow:

1. **Before Implementation**: Explore existing patterns
2. **After Implementation**: 
   - lsp_diagnostics on all modified files
   - Run related tests
   - Run build/typecheck
3. **Before Completion**: Verify 100% of requirements met

## Common Mistakes
This section covers common mistakes for the oh-my-opencode-agents skill.
Key operations include input validation, core processing, and output verification.
Refer to the skill overview for detailed usage instructions.


### Sisyphus
- Providing step-by-step instructions ( defeats autonomy)
- Skipping parallel agent launches
- Not following TODO list

### Hephaestus
- Not exploring before acting
- Not matching codebase patterns
- Skipping verification

### Oracle
- Consulting too early (before trying yourself)
- Consulting for simple questions
- Not following Oracle's recommendations

### Librarian
- Using for simple questions answerable from code
- Not being specific enough in queries
- Ignoring results

### Explore
- Using when direct tools suffice
- Not providing enough context
- Limiting search scope

## Red Flags

**Never**:
- Use Sisyphus for trivial tasks
- Skip Hephaestus's parallel exploration
- Consult Oracle before trying 2+ approaches
- Use Explore when you know the answer
- Skip verification after any agent work

## The Process

1. **Identify task type** – Determine if task is complex (Sisyphus), autonomous (Hephaestus), strategic (Oracle), documentation (Librarian), or exploration (Explore)
2. **Choose agent** – Select agent based on task requirements, skill level of existing codebase, and collaboration needs
3. **Configure agent** – Set model, temperature, and any agent-specific options in configuration
4. **Load skill** – Ensure oh-my-opencode-agents skill is available to agent environment
5. **Initiate work** – Invoke agent with clear objectives, task context, and success criteria
6. **Monitor progress** – Track agent output, verify tool usage, adjust parameters if needed
7. **Verify completion** – Run lsp_diagnostics, build, and tests for agent-generated code

## Red Flags

- **Assigning trivial work to complex agents** – Using Sisyphus for single-file edits or Hephaestus for quick fixes wastes resources
- **Consulting Oracle too early** – Oracle should be invoked after 2+ failed attempts, not as first resort
- **Using Explore for documentation** – Explore is for codebase exploration, not reading official docs (use Librarian)
- **Ignoring agent characteristics** – Not leveraging parallel exploration (Hephaestus), not using TODO lists (Sisyphus)
- **Skipping verification steps** – Agent work should be verified with lsp_diagnostics, build, and tests before commit
- **Config mismatch** – Using wrong models, temperatures, or permissions for agent capabilities

## Verification

- **Skill loaded**: Invoke skill tool and verify all agents have correct model assignments and characteristics
- **Agent selection**: `/agent sisyphus`, `/agent hephaestus`, `/agent oracle` should all switch without error
- **Agent behavior**: Agent follows own characteristics (Sisyphus uses TODO, Hephaestus explores first)
- **Output quality**: Agent responses match expected domain expertise (Oracle gives architectural insights, Librarian gives docs)
- **Verification hooks**: Agent completes with lsp_diagnostics, build, and tests executed
- **Parallel execution**: Hephaestus fires 2-5 explore/librarian agents before acting, Sisyphus fires parallel tasks
- **No redundancy**: Each agent used for purpose it's designed for, not confused with others

## References

- Agent System: https://github.com/code-yeongyu/oh-my-opencode#for-those-who-want-to-read-meet-sisyphus
- Agent-Model Matching: https://github.com/code-yeongyu/oh-my-opencode/blob/master/docs/guide/agent-model-matching.md
- Quality Standards: https://github.com/code-yeongyu/oh-my-opencode/blob/master/docs/features.md

## Anti-Rationalization Table

| Rationalization | Reality |
|---|---|
| "I will handle auth later" | Retrofitting auth is 10x harder. Build it from day one. |
| "APIs do not change" | APIs change. Version your integrations and handle deprecations. |
| "Webhooks are optional" | Without webhooks, you miss real-time events. They are essential. |

## Related Skills

- oh-my-opencode: Overall integration overview
- oh-my-opencode-installation: Setup guide
- oh-my-opencode-configuration: Configuration options
- oh-my-opencode-features: Complete features list

## Process

1. Analyze the task requirements
2. Apply domain expertise
3. Verify output quality