This document provides a high-level introduction to oh-my-opencode, a plugin that transforms OpenCode (Claude Code) into a multi-model agent orchestration platform. It covers the system's architecture, initialization flow, core subsystems, and operational philosophy.
For specific topics, see:
Sources: README.md1-376 src/index.ts1-114 AGENTS.md1-158
oh-my-opencode is an npm package (oh-my-opencode) that extends OpenCode through its plugin API. The plugin registers as OhMyOpenCodePlugin and provides:
The codebase consists of 1,268 TypeScript files totaling approximately 160,000 lines of code, built with Bun and deployed as a monorepo with platform-specific binaries.
Sources: README.md74-81 AGENTS.md1-158 src/index.ts17-98
Architecture Principles:
No Single-Model Lock-in: Models become cheaper and more capable monthly. No provider will dominate long-term. The system orchestrates across Claude, GPT, Gemini, Kimi, and others based on task requirements.
Semantic Task Delegation: Agents select work by category (visual-engineering, ultrabrain, deep, quick) rather than explicit model names. The system maps categories to optimal models automatically.
Provider Fallback Cascade: Each agent has a 6-level fallback chain across providers. If claude-opus-4-6 is unavailable, the system cascades through alternative models without user intervention.
Parallel Execution: Background task system enables concurrent specialist execution (5 tasks per model/provider) while maintaining lean context windows.
Sources: README.md25-29 src/agents/builtin-agents.ts1-100 src/shared/model-requirements.ts1-200
Initialization Phases:
| Phase | Entry Point | Output | Purpose |
|---|---|---|---|
| 0 | initConfigContext() | Config context | Prevents hook warnings during init |
| 1 | loadPluginConfig() | OhMyOpenCodeConfig | JSONC parse, merge, validate, migrate |
| 2 | createManagers() | 4 manager instances | Infrastructure services |
| 3 | createTools() | ToolRegistry | 26 tools with permissions |
| 4 | createHooks() | 46 hook functions | Lifecycle interception |
| 5 | createPluginInterface() | PluginInterface | OpenCode event bindings |
Each phase depends on the previous phase's output, ensuring proper dependency initialization order.
Sources: src/index.ts17-98 AGENTS.md30-39 src/plugin-config.ts1-100 src/create-managers.ts1-50 src/create-tools.ts1-60 src/create-hooks.ts1-70 src/plugin-interface.ts1-80
| Subsystem | Primary Location | Key Types/Functions | Purpose |
|---|---|---|---|
| Agent System | src/agents/ | AgentFactory, buildAgent(), createBuiltinAgents() | 11 specialized agents with fallback chains |
| Hook System | src/hooks/ | createXXXHook() factories, HookName | 46 lifecycle interception points |
| Tool System | src/tools/ | createToolRegistry(), ToolDefinition | 26 tools for delegation, LSP, search, etc. |
| Background Execution | src/features/background-agent/ | BackgroundManager, ConcurrencyManager | Parallel task orchestration |
| Skill System | src/features/opencode-skill-loader/ | SkillContext, SKILL.md parser | Composable domain expertise |
| MCP Integration | src/mcp/, src/features/skill-mcp-manager/ | createBuiltinMcps(), SkillMcpManager | Three-tier MCP system |
| Configuration | src/config/, src/plugin-config.ts | OhMyOpenCodeConfigSchema, loadPluginConfig() | Multi-level config with validation |
| Model Resolution | src/shared/model-resolution-pipeline.ts | resolveModel(), AGENT_MODEL_REQUIREMENTS | 4-tier priority, 6-level cascade |
| Tmux Integration | src/features/tmux-subagent/ | TmuxSessionManager, pane lifecycle | Interactive terminal sessions |
| CLI | src/cli/ | install, run, doctor, mcp-oauth | Command-line interface |
Sources: AGENTS.md9-70 src/agents/AGENTS.md1-80 src/hooks/AGENTS.md1-166 src/tools/AGENTS.md1-109 src/features/AGENTS.md1-71
The configuration system follows a three-level hierarchy with deep merging for structured fields and set union for array fields.
| Field Type | Merge Strategy | Example |
|---|---|---|
agents.* | Deep recursive merge | User agents.sisyphus.temperature overrides default |
categories.* | Deep recursive merge | Project category configs override user |
disabled_* arrays | Set union (concatenate + deduplicate) | disabled_hooks from all levels combined |
| Primitive fields | Override (last wins) | Project value replaces user/default |
| Omitted fields | Zod defaults | safeParse() fills missing values |
The root schema OhMyOpenCodeConfigSchema at src/config/schema/oh-my-opencode-config.ts composes 24 sub-schemas:
experimental, hashline_edit, model_fallback, new_task_system_enableddisabled_mcps, disabled_agents, disabled_skills, disabled_hooks, disabled_commands, disabled_toolstmux, background_task, ralph_loop, sisyphus, notification, git_master, websearch, etc.Sources: src/plugin-config.ts1-100 src/config/AGENTS.md1-55 src/config/schema/oh-my-opencode-config.ts1-100
Sisyphus (Main Orchestrator):
claude-opus-4-6 (max)glm-5kimi-k2p5Hephaestus (Autonomous Worker):
gpt-5.3-codex (medium)gpt-5.4 (medium, copilot)Oracle (Architecture Consultant):
gpt-5.4 (high)gemini-3.1-pro (high)claude-opus-4-6 (max)Independent of the static fallback chain, the runtime-fallback hook at src/hooks/runtime-fallback/ monitors API errors and auto-switches to fallback_models on retryable errors (400, 429, 503, 529) with per-model cooldown tracking (default 60s).
Sources: src/shared/model-resolution-pipeline.ts1-150 src/shared/model-requirements.ts1-200 src/agents/AGENTS.md10-74 src/hooks/runtime-fallback/
All agents, tools, and hooks follow the factory pattern:
Sources: src/agents/types.ts1-50 src/tools/delegate-task/index.ts1-100 src/hooks/todo-continuation-enforcer/index.ts1-50
The codebase uses 98 barrel export files (index.ts) to establish module boundaries:
Sources: AGENTS.md156 src/agents/index.ts1-20
Empty catch blocks are prohibited. All errors must be handled:
Sources: AGENTS.md120
Tests use Bun's test runner with given/when/then structure:
CI Test Split:
bun test invocations)Sources: AGENTS.md98 src/config/schema.test.ts1-600
The plugin distributes as:
oh-my-opencode (npm)optionalDependencies:
oh-my-opencode-darwin-arm64oh-my-opencode-darwin-x64oh-my-opencode-linux-arm64oh-my-opencode-linux-x64oh-my-opencode-win32-arm64oh-my-opencode-win32-x64Binary resolution at packages/cli-runner/bin/platform.js selects the correct binary for the current platform.
Sources: AGENTS.md26-27 src/cli/AGENTS.md1-72
All logs write to /tmp/oh-my-opencode.log via the log() function at src/shared/logger.ts:
Sources: AGENTS.md149 src/shared/AGENTS.md7
For detailed information on specific subsystems:
Refresh this wiki
This wiki was recently refreshed. Please wait 5 days to refresh again.