Mastering Oh My OpenCode Agents: A Complete Guide with Real‑World Tips

Agents Overview

Sisyphus (Project Manager)

Purpose : Decompose a complex task into steps, assign each step to the most suitable agent, monitor execution, retry failures, and aggregate results.

Key capabilities :

Splits large tasks (e.g., refactor a project into dozens of steps)

Selects appropriate agent per step (code change → Oracle, search → Explore, etc.)

Monitors progress and automatically retries failed steps

Ensures all steps finish before completing the task

Typical usage :

Complex tasks involving many files or modules

Tasks that require coordination of multiple agents

When the goal can be expressed without handling low‑level details

Tasks prone to errors that need automatic retry

Example :

# User request
opencode "ulw: Refactor the entire authentication system from JWT to OAuth2"

# Sisyphus actions
# 1. Decompose: analyze → backend changes → frontend changes → tests → docs
# 2. Assign agents: analysis with Oracle, code changes with Explore, tests with Quick, docs with Writing
# 3. Monitor execution (auto‑retry on failure, switch model if needed)
# 4. Consolidate results into a complete change plan

Oracle (Architecture Advisor)

Purpose : Provide deep technical analysis, architecture decisions, and root‑cause diagnosis.

Key capabilities :

Deep analysis of bugs (e.g., concurrency issues)

Architecture evaluation (micro‑service vs monolith)

Complex problem diagnosis (intermittent time‑outs)

Reasoning about design pitfalls

Example – Concurrency bug :

# User request
opencode "Use Oracle to analyze this concurrency bug:
multiple users order the same item, stock goes negative, no logs.
Provide root cause, fix plan, updated code, and prevention steps."

# Oracle response
- Identifies race condition
- Proposes three locking strategies (pessimistic, optimistic, distributed)
- Recommends the most suitable strategy
- Supplies corrected code

Explore (Code Explorer)

Purpose : Search the repository, understand project structure, and identify code patterns.

Key capabilities :

Search code (e.g., find all API calls)

Explain project organization

Detect design patterns

Quickly describe function behavior

Example – Project onboarding :

# User request
opencode "Use Explore to quickly understand the authentication system:
show login flow, permission checks, session management,
list related files, and provide an architecture diagram."

# Explore response
- Full file paths and list
- Key code snippets
- Architecture diagram

Librarian (Documentation Retriever)

Purpose : Fetch official documentation, best practices, and reference implementations.

Key capabilities :

Search official docs (e.g., React Router v6)

Summarize best practices (e.g., JWT authentication)

Locate GitHub examples

Compare alternative solutions (MongoDB vs PostgreSQL)

Example – Redis cache design :

# User request
opencode "Help me design a Redis cache for product info, user sessions,
hot data, with key naming, expiration, consistency, and protection
against cache penetration, avalanche, and stampede."

# Librarian response
- Cache strategy and data structures
- Key naming conventions
- Expiration policies
- Consistency guarantees
- Monitoring metrics

Visual Engineering (Frontend + UI Design)

Purpose : Design, code, and style UI components.

Key capabilities :

UI design (login page, forms)

Frontend implementation (React code)

Style optimization (Tailwind, dark mode)

Responsive layout

Interaction animation

Example – Login page :

# User request
opencode "Use visual-engineering to design and implement a login page
with username/password, remember‑me, forgot password, social login,
validation, error tips, modern style, dark mode, loading animation,
and E2E tests."

# Result
- UI mockup
- React component code
- Tailwind CSS
- Playwright test scripts

Writing (Technical Documentation)

Purpose : Generate READMEs, API docs, guides, and technical blogs.

Key capabilities :

README generation

API documentation

Usage guides

Technical blog posts

Development manuals

Example – Full project docs :

# User request
opencode "Use writing to generate a complete documentation set for this project:
README, API spec, deployment guide, and development guide."

# Writing response
- Structured markdown files covering all aspects

Choosing the Right Agent

The decision process starts with the task type and matches it to the agent that specializes in that domain.

What is your task?
│
├─ Complex task requiring multiple agents? → Sisyphus
│   └─ No → Continue
│
├─ Involves architecture decision or hard‑to‑solve bug? → Oracle
│   └─ No → Continue
│
├─ Need to search or analyze code? → Explore
│   └─ No → Continue
│
├─ Need external docs or best practices? → Librarian
│   └─ No → Continue
│
├─ Frontend UI/UX task? → Visual Engineering
│   └─ No → Continue
│
└─ Need documentation? → Writing

Real‑World Selection Cases

Case 1 – Understanding a new project

Task complexity: medium → not Sisyphus

No architecture decision needed

Code search required → Choose Explore

Command:

opencode "Use Explore to map the project architecture,
list key modules, and produce a diagram"

Case 2 – Refactoring authentication from JWT to OAuth2

Complexity: high → Sisyphus

Architecture decision needed → Sisyphus invokes Oracle for design

Result: Sisyphus splits the work into ~15 steps, coordinates Explore, Oracle, and Writing, and returns a full migration plan.

Case 3 – Mysterious concurrency bug

Complexity: high → consider Oracle

Deep analysis required (not just code search) → Oracle

Result: Oracle identifies a race condition, suggests three locking strategies, and provides patched code.

Agent Collaboration Patterns

Combining agents yields higher value than using them individually.

Pattern 1 – Explore + Librarian (internal + external insight)

Use case: Onboard a new project while also learning industry best practices.

# Parallel execution
opencode "Use Explore to analyze current payment implementation"
opencode "Use Librarian to fetch payment best practices"

# After both finish
opencode "Use Oracle to synthesize an optimization plan based on both results"

Pattern 2 – Oracle + Visual Engineering (backend design + UI)

# Step 1: Backend design
opencode "Use Oracle to design a real‑time chat architecture
(10⁵ users, <100 ms latency, group & private chat, persistence, offline messages)."

# Step 2: Frontend UI based on design
opencode "Use visual-engineering to create the chat UI,
responsive layout, loading animations, and component structure"

Pattern 3 – Sisyphus orchestrating Explore + Librarian + Writing

# Single command
opencode "ulw: Generate full technical documentation for this project"

# Sisyphus automatically:
# 1. Runs Explore for code analysis
# 2. Runs Librarian for best‑practice references
# 3. Runs Writing to produce README, API docs, deployment guide
# 4. Merges everything

Parallel vs. Serial Execution

Parallel‑worthy scenarios (independent, large workload, different expertise):

Independent tasks can run simultaneously

Large modules that would take too long for a single agent

Tasks requiring distinct knowledge domains

Serial‑required scenarios (strong dependencies):

API design must precede implementation

Documentation that depends on generated code

Common Pitfalls

Using Sisyphus for every tiny task adds unnecessary overhead; prefer a single specialized agent for simple work.

Not preserving session continuity forces repeated context description; always record the session_id and reuse it for dependent steps.

Loading more skills than needed dilutes focus; load only the skills required for the current task.

Quick Reference Commands

# Sisyphus (orchestrator)
opencode "ulw: [complex task]"

# Oracle (architecture advisor)
opencode "Use Oracle to [solve complex problem]"

# Explore (code explorer)
opencode "Use Explore to [search/analyze code]"

# Librarian (doc lookup)
opencode "Use Librarian to [find docs/best practices]"

# Visual Engineering (frontend)
opencode "Use visual-engineering to [design/implement UI]"
(load_skills=["frontend-ui-ux"])

# Writing (documentation)
opencode "Use writing to [write docs]"
(category=writing)