oh-my-opencode is a plugin for OpenCode that implements multi-model AI agent orchestration, enhanced code intelligence tools, and a comprehensive hook system. Think of it as "oh-my-zsh for OpenCode"—transforming a powerful foundation into a batteries-included development environment where AI agents work as a coordinated team, each using the best model for their specialized domain.
| Feature | Description | Key Benefit |
|---|---|---|
| Multi-Agent Orchestration | 7+ specialized agents (Sisyphus, oracle, librarian, explore, frontend, document-writer, multimodal-looker) across 5 AI providers | Cost-efficient parallel execution with domain-optimized models |
| Advanced Tooling | 30+ tools: LSP (11 operations), AST-Grep (25 languages), session management, background tasks | IDE-grade code intelligence for agents |
| Lifecycle Hooks | 22+ hooks intercepting 6 event types (PreToolUse, PostToolUse, UserPromptSubmit, Stop, SessionIdle, onSummarize) | Modifies agent behavior without forking OpenCode |
| Background Execution | Async task management with concurrency control | True parallel agent workflows |
| Claude Code Compatibility | Full compatibility layer for commands, skills, agents, MCPs, hooks | Zero-friction migration from Claude Code |
Sources: README.md1-230 AGENTS.md1-30
To install and configure oh-my-opencode, see:
For architectural deep-dives, see:
Sources: Table of contents from wiki structure
oh-my-opencode integrates into OpenCode as a plugin via the OhMyOpenCodePlugin class src/index.ts1-563 The plugin's main entry point registers hooks, tools, agents, and MCPs through OpenCode's plugin API.
Plugin Initialization Flow
Sources: src/index.ts1-563 src/cli/config-manager.ts1-725 src/agents/utils.ts1-180 src/agents/sisyphus-prompt-builder.ts1-300
Five Major Subsystems
The plugin architecture is organized into five major subsystems, each serving a distinct purpose:
| Subsystem | Entry Point | Core Components | Wiki Page |
|---|---|---|---|
| Agent Orchestration | createBuiltinAgents() src/agents/utils.ts1-180 | Sisyphus, oracle, librarian, explore, frontend-ui-ux-engineer, document-writer, multimodal-looker | Agent System (4) |
| Tool Ecosystem | builtinTools src/tools/index.ts1-82 | LSPClient src/tools/lsp/client.ts1-632 ast_grep_search, background_task, session_list | Tool System (5) |
| Hook System | Hook factories in src/hooks/ | directory-agents-injector, todo-continuation-enforcer, anthropic-context-window-limit-recovery | Hook System (7) |
| Background Execution | BackgroundManager src/features/background-agent/manager.ts1-825 | ConcurrencyManager, task lifecycle, notification queue | Background Execution System (6) |
| Compatibility Layer | Claude Code loaders src/features/claude-code-*-loader/ | command-loader, skill-loader, agent-loader, mcp-loader, plugin-loader src/features/claude-code-plugin-loader/index.ts1-484 | Claude Code Compatibility (9) |
Sources: src/index.ts1-563 src/agents/utils.ts1-180 src/tools/index.ts1-82 src/features/background-agent/manager.ts1-825 src/features/claude-code-plugin-loader/index.ts1-484 AGENTS.md14-53
The agent system implements a hub-and-spoke architecture where Sisyphus orchestrates task delegation to 6+ specialist agents, each optimized for a specific domain and cost tier. This enables parallel execution at scale—background agents run concurrently while the orchestrator continues planning.
Agent Delegation Flow with Code Entities
Sources: src/agents/sisyphus-prompt-builder.ts1-300 src/tools/sisyphus-task/tools.ts1-583 src/tools/sisyphus-task/constants.ts1-100 src/features/background-agent/manager.ts1-825 src/agents/prometheus-prompt.ts1-988
Agent Roster by Cost Tier
| Agent | Model | Config Key | Cost | Mode | Purpose | Implementation |
|---|---|---|---|---|---|---|
| Sisyphus | claude-opus-4-5 | anthropic/claude-opus-4-5 | High | Sync | Primary orchestrator, extended thinking (32k) | src/agents/sisyphus.ts1-643 |
| Prometheus | claude-opus-4-5 | anthropic/claude-opus-4-5 | High | Sync | Strategic planner, interview mode | src/agents/prometheus-prompt.ts1-988 |
| oracle | gpt-5.2 | openai/gpt-5.2 | Very High | Sync | Architecture advice, debugging | src/agents/oracle.ts1-200 |
| librarian | claude-sonnet-4-5 | anthropic/claude-sonnet-4-5 | Low | Async | Multi-repo research, GitHub search | src/agents/librarian.ts1-450 |
| explore | grok-code | opencode/grok-code | Free | Async | Fast codebase grep | src/agents/explore.ts1-300 |
| frontend-ui-ux-engineer | gemini-3-pro-high | google/gemini-3-pro-high | Low | Sync | UI/UX generation | src/agents/frontend-ui-ux-engineer.ts1-200 |
| document-writer | gemini-3-flash | google/gemini-3-flash | Very Low | Sync | Technical writing | src/agents/document-writer.ts1-150 |
| multimodal-looker | gemini-3-flash | google/gemini-3-flash | Very Low | Sync | PDF, image analysis | src/agents/multimodal-looker.ts1-150 |
Cost-Based Routing Strategy: EXPENSIVE agents (oracle, Prometheus) require explicit justification. CHEAP agents (librarian, explore) default to run_in_background: true for parallel execution. The BackgroundManager enforces per-provider concurrency limits (anthropic: 3, openai: 5, google: 10).
For detailed agent delegation strategies, see Sisyphus Orchestrator (4.1). For the Planning Triad (Prometheus/Metis/Momus), see Planning Triad (4.2).
Sources: src/agents/AGENTS.md28-40 src/agents/utils.ts1-180 src/features/background-agent/manager.ts1-825 README.md493-520
oh-my-opencode provides 30+ custom tools organized into 7 categories. Each tool replaces OpenCode's basic operations with production-grade implementations featuring timeouts (60s default), error recovery, and advanced code intelligence.
Tool Registry and Categories
The builtinTools array src/tools/index.ts1-82 registers all tools. Each tool follows the factory pattern (createXXXTools()) and exports a tools array.
| Category | Tool Count | Key Tools | Implementation | Purpose |
|---|---|---|---|---|
| LSP | 11 | lsp_hover, lsp_goto_definition, lsp_find_references, lsp_rename, lsp_diagnostics | LSPClient src/tools/lsp/client.ts1-632 | IDE-grade code intelligence via JSON-RPC |
| AST | 2 | ast_grep_search, ast_grep_replace | @ast-grep/napi src/tools/ast-grep/napi.ts1-200 | Structural pattern matching, 25 languages |
| File Ops | 2 | grep, glob | src/tools/grep/ src/tools/glob/ | Timeout-safe search (60s cap) |
| Session | 4 | session_list, session_read, session_search, session_info | src/tools/session-manager/ | OpenCode session history |
| Background | 3 | background_task, background_output, background_cancel | src/tools/background-task/ | Async task management |
| Specialized | 3 | look_at, interactive_bash, call_omo_agent | src/tools/look-at/ src/tools/interactive-bash/ src/tools/call-omo-agent/ | Multimodal (27 types), tmux, agent spawning |
| Skill System | 3 | skill, skill_mcp, slashcommand | src/tools/skill/ src/tools/skill-mcp/ src/tools/slashcommand/ | Reusable prompt content, embedded MCPs |
For complete tool documentation, see Tool System (5). For LSP implementation details, see LSP Tools (5.1). For AST-Grep, see AST-Grep Tools (5.2).
Sources: src/tools/index.ts1-82 src/tools/AGENTS.md1-61 src/tools/lsp/client.ts1-632 src/tools/ast-grep/napi.ts1-200
LSP Client Architecture
The LSPClient class src/tools/lsp/client.ts1-632 implements JSON-RPC over stdio with 4 language servers:
typescript-language-server (TypeScript, JavaScript)vscode-json-languageserver (JSON, JSONC)bash-language-server (Bash, Shell)Key implementation details:
initialize handshakeSources: src/tools/lsp/client.ts1-632 src/tools/lsp/tools.ts1-400 README.md542-562
AST-Grep Implementation
The AST-Grep subsystem supports 25 programming languages via tree-sitter parsers. Implementation prefers NAPI binding for performance:
Meta-variable syntax:
$VAR - Single AST node capture$$$ - Multiple node capture (zero or more)Sources: src/tools/ast-grep/napi.ts1-200 src/tools/ast-grep/cli.ts1-150 README.md554-564
The hook system provides 22+ lifecycle hooks that intercept 6 OpenCode event types to modify agent behavior without forking the platform. All hooks are registered via factories (createXXXHook()) in src/index.ts200-350
Hook Event Types and Registration
Sources: src/index.ts200-350 src/hooks/AGENTS.md30-37
Hook Categories by Function
| Category | Key Hooks | Event Type | Purpose | Implementation |
|---|---|---|---|---|
| Context Injection | directory-agents-injector, directory-readme-injector, rules-injector | chat.message | Walks directory tree to inject AGENTS.md, README.md, and conditional rules | src/hooks/directory-agents-injector/ src/hooks/rules-injector/ |
| Workflow Control | todo-continuation-enforcer, keyword-detector, ralph-loop | session.idle, chat.message | Forces task completion (2s countdown), detects ultrawork keyword, iterates until <promise>DONE</promise> | src/hooks/todo-continuation-enforcer.ts1-200 src/hooks/ralph-loop/index.ts1-364 |
| Recovery & Protection | anthropic-context-window-limit-recovery, preemptive-compaction, tool-output-truncator | session.error, experimental.chat.messages.transform, tool.execute.after | 3-stage recovery (70% warn, 85% compact, limit emergency), 50k token cap | src/hooks/anthropic-context-window-limit-recovery/executor.ts1-555 src/hooks/tool-output-truncator.ts1-150 |
| Integration | claude-code-hooks, background-notification, session-notification | tool.execute.before, tool.execute.after, session.idle | Claude Code settings.json compatibility, task completion notifications | src/hooks/claude-code-hooks/ src/hooks/background-notification/ |
For detailed hook documentation, see Hook System (7). For context injection strategies, see Context Injection System (7.2). For recovery mechanisms, see Session Recovery (7.7).
Sources: src/hooks/AGENTS.md1-54 src/hooks/anthropic-context-window-limit-recovery/executor.ts1-555 src/hooks/todo-continuation-enforcer.ts1-200 README.md744-768
The background execution system src/features/background-agent/ enables true parallel agent orchestration. While Sisyphus orchestrates, librarian and explore can execute simultaneously in background sessions, reporting results asynchronously.
Background Task Architecture with Code Entities
Sources: src/features/background-agent/manager.ts1-825 src/features/background-agent/concurrency-manager.ts1-200 src/tools/sisyphus-task/tools.ts1-583 src/hooks/background-notification/index.ts1-150
Concurrency Control via ConcurrencyManager
The ConcurrencyManager src/features/background-agent/concurrency-manager.ts1-200 enforces three-tier limits:
| Limit Type | Default | Configuration | Example |
|---|---|---|---|
| Global | 5 | defaultConcurrency | Max 5 background tasks total |
| Per-provider | Varies | providerConcurrency.anthropic: 3 | Max 3 Anthropic tasks |
| Per-model | Varies | modelConcurrency["claude-opus-4-5"]: 1 | Max 1 Opus 4.5 task |
Slot Management Methods:
acquireSlot(providerId, modelId) - Blocks until slot availablereleaseSlot(providerId, modelId) - Frees slot, processes queuegetAvailableSlots() - Returns current capacityTask State Transitions:
pending - Created, awaiting concurrency slotrunning - Executing in background OpenCode sessioncompleted - Finished, result stored in tasks Mapfailed - Error occurred, error message storedFor complete background execution documentation, see Background Execution System (6). For task execution modes, see Task Execution Modes (6.3).
Sources: src/features/background-agent/manager.ts1-825 src/features/background-agent/concurrency-manager.ts1-200 README.md514-536
The compatibility layer src/features/claude-code-*-loader/ enables zero-friction migration from Claude Code. Six loaders translate Claude Code configuration formats:
Loader Priority and File Paths
| Loader | Implementation | Priority Order (Highest → Lowest) | Wiki Page |
|---|---|---|---|
| command-loader | src/features/claude-code-command-loader/index.ts1-300 | .opencode/command/ > ~/.config/opencode/command/ > .claude/commands/ > ~/.claude/commands/ | Claude Code Compatibility (9) |
| skill-loader | src/features/opencode-skill-loader/index.ts1-400 | .opencode/skill/ > ~/.config/opencode/skill/ > .claude/skills/ > ~/.claude/skills/ | Loaders and Compatibility Toggles (9.3) |
| agent-loader | src/features/claude-code-agent-loader/index.ts1-250 | .claude/agents/*.md > ~/.claude/agents/*.md | Configuration Migration (9.1) |
| mcp-loader | src/features/claude-code-mcp-loader/index.ts1-350 | .claude/.mcp.json > .mcp.json > ~/.claude/.mcp.json (with ${VAR} expansion) | MCP Integration (8) |
| plugin-loader | src/features/claude-code-plugin-loader/index.ts1-484 | ~/.claude/plugins/installed_plugins.json (marketplace plugins) | Loaders and Compatibility Toggles (9.3) |
| hooks | src/hooks/claude-code-hooks/index.ts1-350 | .claude/settings.json, .claude/settings.local.json, ~/.claude/settings.json | Hooks Integration (9.2) |
Configuration Toggles
Each loader can be disabled via claude_code configuration object in oh-my-opencode.json:
For detailed Claude Code compatibility documentation, see Claude Code Compatibility (9). For hook system integration, see Hooks Integration (9.2).
Sources: src/features/AGENTS.md26-49 src/features/claude-code-plugin-loader/index.ts1-484 src/features/claude-code-command-loader/index.ts1-300 README.md634-726
Configuration follows a three-tier hierarchy (project > user > defaults) with JSONC support (comments + trailing commas). The ConfigManager src/cli/config-manager.ts1-725 handles parsing, Zod validation src/config/schema.ts1-12000 and deep merging src/shared/deep-merge.ts1-100
Configuration Resolution Flow
Sources: src/cli/config-manager.ts1-725 src/config/schema.ts1-12000 src/shared/jsonc-parser.ts1-100 src/shared/deep-merge.ts1-100
JSONC Support Details
The parseJsonc() function src/shared/jsonc-parser.ts1-100 enables:
// comment/* comment */{ "key": "value", }File Priority: If both .jsonc and .json exist, .jsonc takes precedence.
For complete configuration documentation, see Configuration System (3.2). For schema reference, see Configuration Schema Reference (13.1).
Sources: src/cli/config-manager.ts1-725 src/config/schema.ts1-12000 src/shared/jsonc-parser.ts1-100 README.md717-786
The build system uses Bun for fast compilation and GitHub Actions for CI/CD with strict TDD enforcement.
Build Commands
| Command | Script | Purpose |
|---|---|---|
bun run typecheck | tsc --noEmit | Type checking only, no build |
bun run build | bun build src/index.ts + tsc --emitDeclarationOnly | ESM bundle + .d.ts files |
bun run build:schema | bun run script/build-schema.ts | Generate assets/oh-my-opencode.schema.json from Zod schema |
bun test | Bun native test runner | Run 82 test files with 2559+ assertions |
Sources: package.json1-100 AGENTS.md138-144
CI/CD Pipeline
The CI/CD pipeline enforces TDD (RED-GREEN-REFACTOR) and blocks local publishing:
| Workflow | Trigger | Actions | Implementation |
|---|---|---|---|
| ci.yml | Push to master/dev, PR | Parallel test + typecheck → Build → Auto-commit schema on master → Draft release on dev | .github/workflows/ci.yml1-200 |
| publish.yml | Manual workflow_dispatch only | Version calculation → Changelog generation → npm publish (OIDC) → GitHub release → Master sync | .github/workflows/publish.yml1-300 |
| sisyphus-agent.yml | @sisyphus-dev-ai mention in issues/PRs | Environment setup → Execute oh-my-opencode → Post comment/PR | .github/workflows/sisyphus-agent.yml1-150 |
Anti-Patterns (Forbidden):
bun publish (use GitHub Actions workflow_dispatch)package.json (CI manages versions)For complete development guidelines, see Development Guide (12). For TDD methodology, see Testing Methodology (12.2). For release process, see Release Process (12.4).
Sources: .github/workflows/ci.yml1-200 .github/workflows/publish.yml1-300 script/publish.ts1-400 AGENTS.md88-108 Diagram 6 from high-level system architecture
The codebase follows strict TDD (Test-Driven Development) with RED-GREEN-REFACTOR methodology:
Testing conventions:
*.test.ts alongside source#given, #when, #then (equivalent to AAA pattern)bun test (380+ tests)Anti-patterns (forbidden):
as any, @ts-ignore, @ts-expect-errorbun publish (use GitHub Actions workflow)Sources: AGENTS.md42-86 README.md1-100
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.