Oh-My-OpenAgent Features Reference

Agents

Oh-My-OpenAgent provides 11 specialized AI agents. Each has distinct expertise, optimized models, and tool permissions.

Core Agents

Core-agent tab cycling is deterministic via injected runtime order field. The fixed priority order is Sisyphus (order: 1), Hephaestus (order: 2), Prometheus (order: 3), and Atlas (order: 4). Remaining agents follow after that stable core ordering.

Planning Agents

Orchestration Agents

Invoking Agents

The main agent invokes these automatically, but you can call them explicitly:

Ask @oracle to review this design and propose an architecture
Ask @librarian how this is implemented - why does the behavior keep changing?
Ask @explore for the policy on this feature

Tool Restrictions

Background Agents

Run agents in the background and continue working:

• Have GPT debug while Claude tries different approaches
• Gemini writes frontend while Claude handles backend
• Fire massive parallel searches, continue implementation, use results when ready

# Launch in background
task(subagent_type="explore", load_skills=[], prompt="Find auth implementations", run_in_background=true)

# Continue working...
# System notifies on completion

# Retrieve results when needed
background_output(task_id="bg_abc123")

Visual Multi-Agent with Tmux

Enable tmux.enabled to see background agents in separate tmux panes:

{
  "tmux": {
    "enabled": true,
    "layout": "main-vertical"
  }
}

When running inside tmux:

• Background agents spawn in new panes
• Watch multiple agents work in real-time
• Each pane shows agent output live
• Auto-cleanup when agents complete
• Stable agent ordering: core-agent tab cycling is deterministic via injected runtime order field (Sisyphus: 1, Hephaestus: 2, Prometheus: 3, Atlas: 4)

Customize agent models, prompts, and permissions in oh-my-opencode.jsonc.

Category System

A Category is an agent configuration preset optimized for specific domains. Instead of delegating everything to a single AI agent, it is far more efficient to invoke specialists tailored to the nature of the task.

What Categories Are and Why They Matter

• Category: "What kind of work is this?" (determines model, temperature, prompt mindset)
• Skill: "What tools and knowledge are needed?" (injects specialized knowledge, MCP tools, workflows)

By combining these two concepts, you can generate optimal agents through task.

Built-in Categories

Usage

Specify the category parameter when invoking the task tool.

task({
  category: "visual-engineering",
  prompt: "Add a responsive chart component to the dashboard page",
});

Custom Categories

You can define custom categories in your plugin config file. During the rename transition, both oh-my-openagent.json[c] and legacy oh-my-opencode.json[c] basenames are recognized.

Category Configuration Schema

Example Configuration

{
  "categories": {
    // 1. Define new custom category
    "korean-writer": {
      "model": "google/gemini-3-flash",
      "temperature": 0.5,
      "prompt_append": "You are a Korean technical writer. Maintain a friendly and clear tone.",
    },

    // 2. Override existing category (change model)
    "visual-engineering": {
      "model": "openai/gpt-5.4",
      "temperature": 0.8,
    },

    // 3. Configure thinking model and restrict tools
    "deep-reasoning": {
      "model": "anthropic/claude-opus-4-7",
      "thinking": {
        "type": "enabled",
        "budgetTokens": 32000,
      },
      "tools": {
        "websearch_web_search_exa": false,
      },
    },
  },
}

Sisyphus-Junior as Delegated Executor

When you use a Category, a special agent called Sisyphus-Junior performs the work.

• Characteristic: Cannot re-delegate tasks to other agents.
• Purpose: Prevents infinite delegation loops and ensures focus on the assigned task.

Advanced Configuration

Rename Compatibility

The published package and binary remain oh-my-opencode. Inside opencode.json, the compatibility layer now prefers the plugin entry oh-my-openagent, while legacy oh-my-opencode entries still load with a warning. Plugin config files (oh-my-openagent.json[c] or legacy oh-my-opencode.json[c]) are recognized during the transition. Run bunx oh-my-opencode doctor to check for legacy package name warnings.

Fallback Models

Configure per-agent fallback chains with arrays that can mix plain model strings and per-model objects:

{
  "agents": {
    "sisyphus": {
      "fallback_models": [
        "opencode/glm-5",
        { "model": "openai/gpt-5.4", "variant": "high" },
        { "model": "anthropic/claude-sonnet-4-6", "thinking": { "type": "enabled", "budgetTokens": 64000 } }
      ]
    }
  }
}

When a model errors, the runtime can move through the configured fallback array. Object entries let you tune the backup model itself instead of only swapping the model name.

File-Based Prompts

Load agent system prompts from external files using file:// URLs in the prompt field, or append additional content with prompt_append. The prompt_append field also works on categories.

{
  "agents": {
    "sisyphus": {
      "prompt": "file:///path/to/custom-prompt.md"
    },
    "oracle": {
      "prompt_append": "file:///path/to/additional-context.md"
    }
  },
  "categories": {
    "deep": {
      "prompt_append": "file:///path/to/deep-category-append.md"
    }
  }
}

Supports ~ expansion for home directory and relative file:// paths.

Useful for:

• Version controlling prompts separately from config
• Sharing prompts across projects
• Keeping configuration files concise
• Adding category-specific context without duplicating base prompts

The file content is loaded at runtime and injected into the agent's system prompt.

Session Recovery

The system automatically recovers from common session failures without user intervention:

• Missing tool results: reconstructs recoverable tool state and skips invalid tool-part IDs instead of failing the whole recovery pass
• Thinking block violations: Recovers from API thinking block mismatches
• Empty messages: Reconstructs message history when content is missing
• Context window limits: Gracefully handles Claude context window exceeded errors with intelligent compaction
• JSON parse errors: Recovers from malformed tool outputs

Recovery happens transparently during agent execution. You see the result, not the failure.

Skills

Skills provide specialized workflows with embedded MCP servers and detailed instructions. A Skill is a mechanism that injects specialized knowledge (Context) and tools (MCP) for specific domains into agents.

Built-in Skills

git-master Core Principles

Multiple Commits by Default:

3+ files -> MUST be 2+ commits
5+ files -> MUST be 3+ commits
10+ files -> MUST be 5+ commits

Automatic Style Detection:

• Analyzes last 30 commits for language (Korean/English) and style (semantic/plain/short)
• Matches your repo's commit conventions automatically

Usage:

/git-master commit these changes
/git-master rebase onto main
/git-master who wrote this authentication code?

frontend-ui-ux Design Process

• Design Process: Purpose, Tone, Constraints, Differentiation
• Aesthetic Direction: Choose extreme - brutalist, maximalist, retro-futuristic, luxury, playful
• Typography: Distinctive fonts, avoid generic (Inter, Roboto, Arial)
• Color: Cohesive palettes with sharp accents, avoid purple-on-white AI slop
• Motion: High-impact staggered reveals, scroll-triggering, surprising hover states
• Anti-Patterns: Generic fonts, predictable layouts, cookie-cutter design

Browser Automation Options

Oh-My-OpenAgent provides two browser automation providers, configurable via browser_automation_engine.provider.

Option 1: Playwright MCP (Default)

mcp:
  playwright:
    command: npx
    args: ["@playwright/mcp@latest"]

Usage:

/playwright Navigate to example.com and take a screenshot

Option 2: Agent Browser CLI (Vercel)

{
  "browser_automation_engine": {
    "provider": "agent-browser"
  }
}

Requires installation:

bun add -g agent-browser

Usage:

Use agent-browser to navigate to example.com and extract the main heading

Capabilities (Both Providers):

• Navigate and interact with web pages
• Take screenshots and PDFs
• Fill forms and click elements
• Wait for network requests
• Scrape content

Custom Skill Creation (SKILL.md)

You can add custom skills directly to .opencode/skills/ in your project root or ~/.claude/skills/ in your home directory.

Example: .opencode/skills/my-skill/SKILL.md

---
name: my-skill
description: My special custom skill
mcp:
  my-mcp:
    command: npx
    args: ["-y", "my-mcp-server"]
---

# My Skill Prompt

This content will be injected into the agent's system prompt.
...

Skill Load Locations (priority order, highest first):

• .opencode/skills/*/SKILL.md (project, OpenCode native)
• ~/.config/opencode/skills/*/SKILL.md (user, OpenCode native)
• .claude/skills/*/SKILL.md (project, Claude Code compat)
• .agents/skills/*/SKILL.md (project, Agents convention)
• ~/.agents/skills/*/SKILL.md (user, Agents convention)

Same-named skill at higher priority overrides lower.

Disable built-in skills via disabled_skills: ["playwright"] in config.

Category + Skill Combo Strategies

You can create powerful specialized agents by combining Categories and Skills.

The Designer (UI Implementation)

• Category: visual-engineering
• load_skills: ["frontend-ui-ux", "playwright"]
• Effect: Implements aesthetic UI and verifies rendering results directly in browser.

The Architect (Design Review)

• Category: ultrabrain
• load_skills: [] (pure reasoning)
• Effect: Leverages GPT-5.4 xhigh reasoning for in-depth system architecture analysis.

The Maintainer (Quick Fixes)

• Category: quick
• load_skills: ["git-master"]
• Effect: Uses cost-effective models to quickly fix code and generate clean commits.

task Prompt Guide

When delegating, clear and specific prompts are essential. Include these 7 elements:

1. TASK: What needs to be done? (single objective)
2. EXPECTED OUTCOME: What is the deliverable?
3. REQUIRED SKILLS: Which skills should be loaded via load_skills?
4. REQUIRED TOOLS: Which tools must be used? (whitelist)
5. MUST DO: What must be done (constraints)
6. MUST NOT DO: What must never be done
7. CONTEXT: File paths, existing patterns, reference materials

Bad Example:

"Fix this"

Good Example:

TASK: Fix mobile layout breaking issue in LoginButton.tsx CONTEXT: src/components/LoginButton.tsx, using Tailwind CSS MUST DO: Change flex-direction at md: breakpoint MUST NOT DO: Modify existing desktop layout EXPECTED: Buttons align vertically on mobile

Commands

Commands are slash-triggered workflows that execute predefined templates.

Built-in Commands

/init-deep

Purpose: Generate hierarchical AGENTS.md files throughout your project

Usage:

/init-deep [--create-new] [--max-depth=N]

Creates directory-specific context files that agents automatically read:

project/
├── AGENTS.md              # Project-wide context
├── src/
│   ├── AGENTS.md          # src-specific context
│   └── components/
│       └── AGENTS.md      # Component-specific context

/ralph-loop

Purpose: Self-referential development loop that runs until task completion

Named after: Anthropic's Ralph Wiggum plugin

Usage:

/ralph-loop "Build a REST API with authentication"
/ralph-loop "Refactor the payment module" --max-iterations=50

Behavior:

• Agent works continuously toward the goal
• Detects <promise>DONE</promise> to know when complete
• Auto-continues if agent stops without completion
• Ends when: completion detected, max iterations reached (default 100), or /cancel-ralph

Configure: { "ralph_loop": { "enabled": true, "default_max_iterations": 100 } }

/ulw-loop

Purpose: Same as ralph-loop but with ultrawork mode active

Everything runs at maximum intensity - parallel agents, background tasks, aggressive exploration.

/refactor

Purpose: Intelligent refactoring with full toolchain

Usage:

/refactor <target> [--scope=<file|module|project>] [--strategy=<safe|aggressive>]

Features:

• LSP-powered rename and navigation
• AST-grep for pattern matching
• Architecture analysis before changes
• TDD verification after changes
• Codemap generation

/start-work

Purpose: Start execution from a Prometheus-generated plan

Usage:

/start-work [plan-name]

Uses atlas agent to execute planned tasks systematically.

/stop-continuation

Purpose: Stop all continuation mechanisms for this session

Stops ralph loop, todo continuation, and boulder state. Use when you want the agent to stop its current multi-step workflow.

/handoff

Purpose: Create a detailed context summary for continuing work in a new session

Generates a structured handoff document capturing the current state, what was done, what remains, and relevant file paths — enabling seamless continuation in a fresh session.

Custom Commands

Load custom commands from:

• .opencode/command/*.md (project, OpenCode native)
• ~/.config/opencode/command/*.md (user, OpenCode native)
• .claude/commands/*.md (project, Claude Code compat)
• ~/.config/opencode/commands/*.md (user, Claude Code compat)

Tools

Code Search Tools

Edit Tools

LSP Tools (IDE Features for Agents)

AST-Grep Tools

Delegation Tools

Visual Analysis Tools

Skill Tools

Session Tools

Task Management Tools

Requires experimental.task_system: true in config.

Task System Details

Note on Claude Code Alignment: This implementation follows Claude Code's internal Task tool signatures (TaskCreate, TaskUpdate, TaskList, TaskGet) and field naming conventions (subject, blockedBy, blocks, etc.). However, Anthropic has not published official documentation for these tools. This is Oh My OpenAgent's own implementation based on observed Claude Code behavior and internal specifications.

Task Schema:

interface Task {
  id: string; // T-{uuid}
  subject: string; // Imperative: "Run tests"
  description: string;
  status: "pending" | "in_progress" | "completed" | "deleted";
  activeForm?: string; // Present continuous: "Running tests"
  blocks: string[]; // Tasks this blocks
  blockedBy: string[]; // Tasks blocking this
  owner?: string; // Agent name
  metadata?: Record<string, unknown>;
  threadID: string; // Session ID (auto-set)
}

Dependencies and Parallel Execution:

[Build Frontend]    ──┐
                      ├──→ [Integration Tests] ──→ [Deploy]
[Build Backend]     ──┘

• Tasks with empty blockedBy run in parallel
• Dependent tasks wait until blockers complete

Example Workflow:

TaskCreate({ subject: "Build frontend" }); // T-001
TaskCreate({ subject: "Build backend" }); // T-002
TaskCreate({ subject: "Run integration tests", blockedBy: ["T-001", "T-002"] }); // T-003

TaskList();
// T-001 [pending] Build frontend        blockedBy: []
// T-002 [pending] Build backend         blockedBy: []
// T-003 [pending] Integration tests     blockedBy: [T-001, T-002]

TaskUpdate({ id: "T-001", status: "completed" });
TaskUpdate({ id: "T-002", status: "completed" });
// T-003 now unblocked

Storage: Tasks are stored as JSON files in .sisyphus/tasks/.

Difference from TodoWrite:

When to Use: Use Tasks when work has multiple steps with dependencies, multiple subagents will collaborate, or progress should persist across sessions.

Interactive Terminal Tools

Usage Examples:

# Create a new session
interactive_bash(tmux_command="new-session -d -s dev-app")

# Send keystrokes to a session
interactive_bash(tmux_command="send-keys -t dev-app 'vim main.py' Enter")

# Capture pane output
interactive_bash(tmux_command="capture-pane -p -t dev-app")

Key Points:

• Commands are tmux subcommands (no tmux prefix)
• Use for interactive apps that need persistent sessions
• One-shot commands should use regular Bash tool with &

Hooks

Hooks intercept and modify behavior at key points in the agent lifecycle across the full session, message, tool, and parameter pipeline.

Hook Events

Built-in Hooks

Context & Injection

Productivity & Control

Quality & Safety

Recovery & Stability

Truncation & Context Management

Notifications & UX

Task Management

Continuation

Integration

Specialized

Claude Code Hooks Integration

Run custom scripts via Claude Code's settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "eslint --fix $FILE" }]
      }
    ]
  }
}

Hook locations:

• ~/.claude/settings.json (user)
• ./.claude/settings.json (project)
• ./.claude/settings.local.json (local, git-ignored)

Disabling Hooks

Disable specific hooks in config:

{
  "disabled_hooks": ["comment-checker"]
}

MCPs

Built-in MCPs

Skill-Embedded MCPs

Skills can bring their own MCP servers:

---
description: Browser automation skill
mcp:
  playwright:
    command: npx
    args: ["-y", "@anthropic-ai/mcp-playwright"]
---

The skill_mcp tool invokes these operations with full schema discovery.

OAuth-Enabled MCPs

Skills can define OAuth-protected remote MCP servers. OAuth 2.1 with full RFC compliance (RFC 9728, 8414, 8707, 7591) is supported:

---
description: My API skill
mcp:
  my-api:
    url: https://api.example.com/mcp
    oauth:
      clientId: ${CLIENT_ID}
      scopes: ["read", "write"]
---

When a skill MCP has oauth configured:

• Auto-discovery: Fetches /.well-known/oauth-protected-resource (RFC 9728), falls back to /.well-known/oauth-authorization-server (RFC 8414)
• Dynamic Client Registration: Auto-registers with servers supporting RFC 7591 (clientId becomes optional)
• PKCE: Mandatory for all flows
• Resource Indicators: Auto-generated from MCP URL per RFC 8707
• Token Storage: Persisted in ~/.config/opencode/mcp-oauth.json (chmod 0600)
• Auto-refresh: Tokens refresh on 401; step-up authorization on 403 with WWW-Authenticate
• Dynamic Port: OAuth callback server uses an auto-discovered available port

Pre-authenticate via CLI:

bunx oh-my-opencode mcp oauth login <server-name> --server-url https://api.example.com

Model Capabilities

Model capabilities are models.dev-backed, with a refreshable cache and compatibility diagnostics. The system combines bundled models.dev snapshot data, optional refreshed cache data, provider runtime metadata, and heuristics when exact metadata is unavailable.

Refreshing Capabilities

Update the local cache with the latest model information:

bunx oh-my-opencode refresh-model-capabilities

Configure automatic refresh at startup:

{
  "model_capabilities": {
    "enabled": true,
    "auto_refresh_on_start": true,
    "refresh_timeout_ms": 5000,
    "source_url": "https://models.dev/api.json"
  }
}

Capability Diagnostics

Run bunx oh-my-opencode doctor to see capability diagnostics including:

• effective model resolution for agents and categories
• warnings when configured models rely on compatibility fallback
• override compatibility details alongside model resolution output

Context Injection

Directory AGENTS.md

Auto-injects AGENTS.md when reading files. Walks from file directory to project root:

project/
├── AGENTS.md              # Injected first
├── src/
│   ├── AGENTS.md          # Injected second
│   └── components/
│       ├── AGENTS.md      # Injected third
│       └── Button.tsx     # Reading this injects all 3

Conditional Rules

Inject rules from .claude/rules/ when conditions match:

---
globs: ["*.ts", "src/**/*.js"]
description: "TypeScript/JavaScript coding rules"
---

- Use PascalCase for interface names
- Use camelCase for function names

Supports:

• .md and .mdc files
• globs field for pattern matching
• alwaysApply: true for unconditional rules
• Walks upward from file to project root, plus ~/.claude/rules/

Claude Code Compatibility

Full compatibility layer for Claude Code configurations.

Config Loaders

MCP configs support environment variable expansion: ${VAR}.

Compatibility Toggles

Disable specific features:

{
  "claude_code": {
    "mcp": false,
    "commands": false,
    "skills": false,
    "agents": false,
    "hooks": false,
    "plugins": false
  }
}

Disable specific plugins:

{
  "claude_code": {
    "plugins_override": {
      "claude-mem@thedotmack": false
    }
  }
}