Oh My OpenCode (code-yeongyu/oh-my-openagent)

Oh My OpenCode

https://github.com/code-yeongyu/oh-my-openagent
Admin
Oh My OpenCode is a batteries-included AI agent harness and OpenCode plugin that enables multi-model...

Tokens:82,896
Snippets:960
Trust Score:10
Update:1 day ago
Show doc for...
Context Summary (auto-generated)
Raw
# Oh My OpenCode

Oh My OpenCode (OmO) is a multi-model AI agent orchestration harness and OpenCode plugin that transforms a single AI agent into a coordinated development team. It provides batteries-included features including multi-model orchestration across Claude, GPT, Gemini, Kimi, and GLM models, parallel background agents, LSP/AST tools for IDE-like precision, hash-anchored edits for reliable code modifications, and skill-embedded MCPs for context-efficient tooling.

The plugin solves common AI coding limitations through specialization and delegation. Instead of one agent doing everything, Oh My OpenCode uses specialized agents that delegate to each other based on task type—Sisyphus orchestrates, Hephaestus handles deep autonomous work, Prometheus plans strategically, Oracle consults on architecture, Librarian searches documentation, and Explore greps codebases fast. Each agent is tuned to optimal models: Claude for instruction-following, GPT for deep reasoning, Gemini for frontend/visual tasks. The system includes todo enforcement that yanks idle agents back to work, comment checking to strip AI slop, and Ralph Loop for self-referential execution until 100% completion.

## Installation

Install oh-my-opencode using the interactive CLI installer.

```bash
# Install with Bun (recommended)
bunx oh-my-opencode install

# Or with npm
npx oh-my-opencode install

# Non-interactive installation with subscription flags
bunx oh-my-opencode install --no-tui --claude=max20 --openai=yes --gemini=yes --copilot=no

# Verify installation
bunx oh-my-opencode doctor
```

## Ultrawork Mode

Type `ultrawork` or `ulw` in your prompt to activate full automatic mode. The agent figures everything out—explores codebase, researches patterns, implements features, and verifies with diagnostics.

```
# In your OpenCode session, just include the keyword:
ulw fix the failing tests

# Or:
ultrawork implement JWT authentication following our patterns

# The agent activates all discipline features automatically:
# - Parallel background agents
# - Todo enforcement
# - Comment checking
# - Hash-anchored edits
```

## Task Delegation Tool

The `task()` tool spawns specialized agents with category-based or direct agent selection for parallel work.

```typescript
// Category-based delegation - uses Sisyphus-Junior with optimized model
task({
  category: "visual-engineering",
  load_skills: ["frontend-ui-ux"],
  description: "Build responsive chart",
  prompt: "Add a responsive chart component to the dashboard page using existing design patterns",
  run_in_background: false
})

// Direct agent invocation for exploration
task({
  subagent_type: "explore",
  load_skills: [],
  description: "Find auth patterns",
  prompt: "Find all authentication implementations in this codebase",
  run_in_background: true
})

// Continue existing task session (preserves full context)
task({
  category: "quick",
  load_skills: [],
  session_id: "task_abc123",
  description: "Fix type error",
  prompt: "Fix the TypeScript error in the previous implementation",
  run_in_background: false
})

// Deep reasoning task
task({
  category: "ultrabrain",
  load_skills: [],
  description: "Design plugin system",
  prompt: "Design a new plugin system architecture with extensibility for third-party integrations",
  run_in_background: false
})
```

## Built-in Categories

Categories determine optimal model selection and agent behavior for different task types.

```jsonc
// oh-my-opencode.jsonc - Category configuration
{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-opencode.schema.json",

  "categories": {
    // Frontend/UI work - Gemini excels at visual tasks
    "visual-engineering": {
      "model": "google/gemini-3.1-pro",
      "variant": "high"
    },

    // Deep logical reasoning - GPT-5.4 for complex architecture
    "ultrabrain": {
      "model": "openai/gpt-5.4",
      "variant": "xhigh"
    },

    // Autonomous problem-solving with thorough research
    "deep": {
      "model": "openai/gpt-5.3-codex",
      "variant": "medium"
    },

    // Trivial tasks - fast and cheap
    "quick": {
      "model": "openai/gpt-5.4-mini"
    },

    // Documentation and prose
    "writing": {
      "model": "google/gemini-3-flash"
    },

    // Custom category example
    "korean-writer": {
      "model": "google/gemini-3-flash",
      "temperature": 0.5,
      "prompt_append": "You are a Korean technical writer. Maintain a friendly and clear tone."
    }
  }
}
```

## Agent Configuration

Configure specialized agents with model overrides, fallbacks, and custom prompts.

```jsonc
// oh-my-opencode.jsonc - Agent configuration
{
  "agents": {
    // Main orchestrator - Claude Opus or Kimi K2.5 work best
    "sisyphus": {
      "model": "kimi-for-coding/k2p5",
      "ultrawork": { "model": "anthropic/claude-opus-4-6", "variant": "max" },
      "fallback_models": [
        "openai/gpt-5.4",
        { "model": "google/gemini-3.1-pro", "variant": "high" }
      ]
    },

    // Research agents - cheap fast models
    "librarian": { "model": "google/gemini-3-flash" },
    "explore": { "model": "github-copilot/grok-code-fast-1" },

    // Architecture consultation - GPT-5.4 for deep reasoning
    "oracle": {
      "model": "openai/gpt-5.4",
      "variant": "high",
      "thinking": { "type": "enabled", "budgetTokens": 200000 }
    },

    // Strategic planner with custom prompt
    "prometheus": {
      "prompt_append": "file://./custom-planning-guidelines.md"
    },

    // Disable an agent entirely
    "multimodal-looker": { "disable": true }
  },

  // Disable specific agents
  "disabled_agents": ["momus"]
}
```

## Background Agents

Run multiple agents in parallel for concurrent research and implementation.

```typescript
// Launch exploration in background
task({
  subagent_type: "explore",
  load_skills: [],
  prompt: "Find all database query patterns",
  run_in_background: true
})
// Returns: { task_id: "bg_abc123" }

// Continue working while background agent runs...

// Retrieve results when needed
background_output({ task_id: "bg_abc123" })

// Cancel a running background task
background_cancel({ task_id: "bg_abc123" })
```

```jsonc
// Background task concurrency configuration
{
  "background_task": {
    "defaultConcurrency": 5,
    "staleTimeoutMs": 180000,
    "providerConcurrency": {
      "anthropic": 3,
      "openai": 5,
      "google": 10
    },
    "modelConcurrency": {
      "anthropic/claude-opus-4-6": 2,
      "opencode/gpt-5-nano": 20
    }
  }
}
```

## LSP Tools

IDE-like refactoring and navigation tools for agents.

```typescript
// Rename symbol across entire workspace
lsp_rename({
  file: "src/services/auth.ts",
  line: 45,
  character: 12,
  newName: "authenticateUser"
})

// Get pre-build diagnostics (errors/warnings)
lsp_diagnostics({ file: "src/index.ts" })

// Jump to symbol definition
lsp_goto_definition({
  file: "src/components/Button.tsx",
  line: 23,
  character: 8
})

// Find all usages across workspace
lsp_find_references({
  file: "src/utils/helpers.ts",
  line: 15,
  character: 16
})

// Get file outline or search workspace symbols
lsp_symbols({ file: "src/services/api.ts" })
lsp_symbols({ query: "UserService" })

// Validate rename before executing
lsp_prepare_rename({
  file: "src/models/User.ts",
  line: 5,
  character: 14
})
```

## AST-Grep Tools

AST-aware code pattern search and replacement across 25 languages.

```typescript
// Search for patterns using AST
ast_grep_search({
  pattern: "console.log($$$)",
  lang: "typescript",
  path: "src/"
})

// Find all React useState hooks
ast_grep_search({
  pattern: "const [$STATE, $SETTER] = useState($INIT)",
  lang: "tsx"
})

// Replace patterns across codebase
ast_grep_replace({
  pattern: "console.log($MSG)",
  replacement: "logger.debug($MSG)",
  lang: "typescript",
  path: "src/"
})
```

## Skills

Skills provide domain-specific instructions and embedded MCP servers.

```
# Use git-master skill for atomic commits
/git-master commit these changes

# Browser automation with Playwright
/playwright Navigate to example.com and take a screenshot

# UI/UX design-first approach
task({
  category: "visual-engineering",
  load_skills: ["frontend-ui-ux", "playwright"],
  prompt: "Create a stunning landing page with bold typography"
})
```

```markdown
<!-- Custom skill: .opencode/skills/my-skill/SKILL.md -->
---
name: my-skill
description: My specialized workflow
mcp:
  my-mcp:
    command: npx
    args: ["-y", "my-mcp-server"]
---

# My Skill Instructions

This content is injected into the agent's system prompt when the skill is loaded.
Include domain-specific guidelines, patterns, and constraints here.
```

## Commands

Built-in slash commands for common workflows.

```
# Generate hierarchical AGENTS.md files throughout project
/init-deep

# Self-referential loop until completion
/ralph-loop "Build a REST API with authentication"

# Ultrawork loop - maximum intensity
/ulw-loop "Refactor the entire payment module"

# Start execution from Prometheus plan
/start-work

# Cancel active Ralph Loop
/cancel-ralph

# Intelligent refactoring with LSP and AST
/refactor UserService --scope=module --strategy=safe

# Stop all continuation mechanisms
/stop-continuation

# Create context summary for new session handoff
/handoff
```

## Prometheus Planning

Strategic planning with interview mode for precise execution.

```
# Method 1: Switch to Prometheus agent (Tab → Select Prometheus)
# Then describe your work and answer interview questions

# Method 2: Use @plan command from Sisyphus
@plan "Refactor the authentication system to use JWT"

# Prometheus will:
# 1. Interview you about requirements
# 2. Research codebase patterns via explore/librarian agents
# 3. Consult Metis for gap analysis
# 4. Generate detailed plan in .sisyphus/plans/
# 5. Optionally validate with Momus for high-accuracy mode

# Execute the plan
/start-work
```

## Agent Invocation

Invoke specialized agents directly for specific expertise.

```
# Architecture consultation (read-only)
Ask @oracle to review this design and propose an architecture

# Documentation lookup
Ask @librarian how rate limiting is implemented in Express.js

# Fast codebase exploration
Ask @explore for all API endpoint definitions in this project

# Visual content analysis
look_at({ file: "mockup.png", prompt: "Describe the UI layout and components" })
```

## Built-in MCPs

Always-available MCP servers for web search, documentation, and code search.

```typescript
// Web search via Exa AI
websearch_web_search_exa({ query: "React 19 new features" })

// Official documentation lookup via Context7
context7_resolve_library_id({ libraryName: "express" })
context7_get_library_docs({ context7CompatibleLibraryID: "/npm/express" })

// GitHub code search via grep.app
grep_app_search({ query: "JWT authentication middleware", language: "typescript" })
```

## Session Tools

List, read, and search across OpenCode session history.

```typescript
// List all sessions
session_list()

// Read messages from specific session
session_read({ session_id: "abc123", limit: 50 })

// Full-text search across sessions
session_search({ query: "authentication bug", limit: 10 })

// Get session metadata
session_info({ session_id: "abc123" })
```

## Interactive Terminal

Tmux-based terminal for TUI apps and persistent sessions.

```typescript
// Create new tmux session
interactive_bash({ tmux_command: "new-session -d -s dev-app" })

// Send keystrokes
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" })
```

```jsonc
// Enable tmux visual multi-agent
{
  "tmux": {
    "enabled": true,
    "layout": "main-vertical",
    "main_pane_size": 60
  }
}
```

## Hash-Anchored Edits

Content-hash validated edits that prevent stale-line errors.

```
# When hashline_edit is enabled, Read output includes hash markers:
11#VK| function hello() {
22#XJ|   return "world";
33#MB| }

# Edits reference these markers for validation
# If file changed since read, hash won't match and edit is rejected
```

```jsonc
// Enable hash-anchored edit tool
{
  "hashline_edit": true
}
```

## Runtime Fallback

Automatic model switching on API errors with configurable fallback chains.

```jsonc
{
  "runtime_fallback": {
    "enabled": true,
    "retry_on_errors": [400, 429, 503, 529],
    "max_fallback_attempts": 3,
    "cooldown_seconds": 60,
    "timeout_seconds": 30,
    "notify_on_fallback": true
  },

  "agents": {
    "sisyphus": {
      "model": "anthropic/claude-opus-4-6",
      "fallback_models": [
        "openai/gpt-5.4",
        { "model": "google/gemini-3.1-pro", "variant": "high" },
        { "model": "anthropic/claude-sonnet-4-6", "thinking": { "type": "enabled", "budgetTokens": 64000 } }
      ]
    }
  }
}
```

## Hooks Configuration

Disable or configure built-in hooks for customized behavior.

```jsonc
{
  // Disable specific hooks
  "disabled_hooks": [
    "comment-checker",           // Allow verbose comments
    "auto-update-checker",       // Skip version checks
    "session-notification"       // Disable OS notifications
  ],

  // Comment checker customization
  "comment_checker": {
    "custom_prompt": "Your message. Use {{comments}} placeholder."
  },

  // Force session notifications
  "notification": {
    "force_enable": true
  }
}
```

## Claude Code Hooks Integration

Execute custom scripts via Claude Code's settings.json hook system.

```json
// ~/.claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "eslint --fix $FILE" }]
      }
    ]
  }
}
```

## Full Configuration Example

Complete plugin configuration with all major features.

```jsonc
// ~/.config/opencode/oh-my-opencode.jsonc
{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-opencode.schema.json",

  "agents": {
    "sisyphus": {
      "model": "kimi-for-coding/k2p5",
      "ultrawork": { "model": "anthropic/claude-opus-4-6", "variant": "max" }
    },
    "librarian": { "model": "google/gemini-3-flash" },
    "explore": { "model": "github-copilot/grok-code-fast-1" },
    "oracle": { "model": "openai/gpt-5.4", "variant": "high" },
    "prometheus": {
      "prompt_append": "Leverage deep & quick agents heavily, always in parallel."
    }
  },

  "categories": {
    "quick": { "model": "opencode/gpt-5-nano" },
    "unspecified-low": { "model": "anthropic/claude-sonnet-4-6" },
    "unspecified-high": { "model": "anthropic/claude-opus-4-6", "variant": "max" },
    "writing": { "model": "google/gemini-3-flash" },
    "visual-engineering": { "model": "google/gemini-3.1-pro", "variant": "high" }
  },

  "background_task": {
    "providerConcurrency": { "anthropic": 3, "openai": 3, "opencode": 10 },
    "modelConcurrency": { "anthropic/claude-opus-4-6": 2 }
  },

  "disabled_hooks": [],
  "disabled_skills": [],
  "disabled_mcps": [],

  "experimental": {
    "aggressive_truncation": true,
    "task_system": true
  },

  "tmux": { "enabled": false },
  "hashline_edit": false,
  "runtime_fallback": true
}
```

## Summary

Oh My OpenCode transforms AI coding from single-agent workflows into coordinated multi-model orchestration. The primary use cases include: complex multi-step development tasks where `ultrawork` mode handles everything automatically, precise planned execution using Prometheus planning with `/start-work` for production-critical changes, parallel exploration with background agents for simultaneous research and implementation, and IDE-like refactoring using LSP and AST-grep tools for workspace-wide modifications. The category system routes tasks to optimal models—Gemini for frontend, GPT for deep reasoning, Claude for orchestration—without manual model selection.

Integration follows a simple pattern: install the plugin, configure provider subscriptions, and type `ultrawork` with your task description. For precise control, use Prometheus planning (`@plan`) followed by Atlas execution (`/start-work`). The system handles model fallbacks, context management, session recovery, and todo enforcement automatically. Skills extend capabilities with domain-specific instructions and embedded MCPs that spin up on-demand without bloating context. Whether building features, debugging complex issues, or refactoring large codebases, the orchestrated agent team—Sisyphus, Hephaestus, Prometheus, Atlas, Oracle, Librarian, and Explore—collaborates to ship code that a single agent couldn't.