Overview

Relevant source files

Purpose and Scope

This page introduces oh-my-opencode (also known as oh-my-openagent) as an OpenCode plugin and explains its architecture, initialization flow, and core components. It provides a high-level understanding of how the plugin extends OpenCode with multi-model AI agent orchestration, 54–61 lifecycle hooks, 20–39 tools, and batteries-included tooling for code editing, task delegation, and background execution.

For installation and setup instructions, see Quick Start. For detailed agent behavior and model matching, see Key Concepts and Agents. For tool usage patterns, see Tools and Features.

Sources: README.md103-110 AGENTS.md41-47

What is Oh My OpenCode?

Oh-my-opencode (npm package: oh-my-opencode, dual-published as oh-my-openagent during its rename transition AGENTS.md43) is an OpenCode plugin that transforms the base platform into a multi-agent orchestration system. It provides:

11 specialized agents with role-specific prompts and tool permissions (Sisyphus, Hephaestus, Oracle, Librarian, Explore, Atlas, Prometheus, Metis, Momus, Multimodal-Looker, Sisyphus-Junior) AGENTS.md57
53–60 lifecycle hooks organized into tiers (Session, Tool-Guard, Transform, Continuation, Skill) AGENTS.md58
20–39 built-in tools including native search, task delegation, background execution, and session management AGENTS.md43
Hash-anchored editing via the hashline_edit tool, which validates LINE#ID content hashing to ensure modification integrity AGENTS.md43
3-tier MCP system merging built-in Tier-1 (LSP, AST-grep), Claude Code, and skill-embedded MCP servers AGENTS.md43
Team Mode for parallel multi-agent coordination, enabling complex delegation across member sessions AGENTS.md43

The plugin targets technical users who require reliable multi-model orchestration with automatic fallback chains and zero-configuration agent-to-model matching. It ships in two editions: Ultimate (for OpenCode) and Light (for Codex CLI) docs/guide/installation.md3-8

Sources: README.md41-48 AGENTS.md41-47 docs/guide/installation.md3-8 docs/reference/features.md3-5

System Architecture at a Glance

Plugin initialization and component assembly

This diagram shows how the entry point at packages/omo-opencode/src/index.ts54 serves as a thin wrapper re-exporting createPluginModule. The initialization flow moves from manager creation packages/omo-opencode/src/create-managers.ts56 to tool registration packages/omo-opencode/src/create-tools.ts56 and hook composition packages/omo-opencode/src/create-hooks.ts56 finally assembling the PluginInterface packages/omo-opencode/src/plugin-interface.ts55

Sources: AGENTS.md45 AGENTS.md52-66

Plugin Lifecycle

Plugin initialization sequence from load to runtime

The plugin follows a staged initialization flow where createPluginModule coordinates the setup of 4 managers, the ToolRegistry, and a 5-tier hook composition AGENTS.md45 Configuration loading is a 6-phase pipeline that merges settings before runtime AGENTS.md65

Sources: AGENTS.md45 AGENTS.md52-66

Core Components

Agents (11 total)

The plugin provides 11 specialized agents, each with role-specific prompts and model configurations:

Agent	Purpose	Mode	Recommended Model
Sisyphus	Main lead orchestrator docs/reference/features.md13	primary	Claude Opus / Kimi K2.6
Hephaestus	Autonomous deep worker docs/reference/features.md14	primary	GPT-5.5
Atlas	Todo-list orchestrator docs/reference/features.md31	primary	Claude Sonnet 4.6
Prometheus	Strategic planner (interview mode) docs/reference/features.md23	primary	Claude Opus
Oracle	Read-only architecture consultant docs/reference/features.md15	subagent	GPT-5.5
Librarian	External documentation search docs/reference/features.md16	subagent	GPT-5.4 Mini Fast

For detailed agent behavior, see Agents.

Sources: docs/reference/features.md3-33 docs/guide/agent-model-matching.md11-18

Tools (20–39 total)

Tools are organized into functional categories and gated by configuration:

Core Tools: task (delegate), session_read, skill, background_cancel AGENTS.md43
LSP & AST-grep: Served via built-in MCPs (e.g., lsp_rename, ast_grep_search) AGENTS.md59
Specialized: look_at (vision), interactive_bash (tmux integration), and hashline_edit AGENTS.md43

For detailed tool usage, see Tools and Features.

Sources: AGENTS.md43 docs/reference/features.md44-54

Hooks (53–60 total)

Hooks intercept OpenCode events at multiple tiers AGENTS.md43:

Session Hooks: Lifecycle management like session created/deleted/idle docs/reference/configuration.md28
Tool Guard Hooks: Intercept tool execution for safety or validation (e.g., writeExistingFileGuard) AGENTS.md58
Transform Hooks: Modify chat messages (e.g., IntentGate keyword detector for ultrawork) AGENTS.md43
Continuation Hooks: Manage workflow loops like ulw-loop and boulder AGENTS.md63

For hook internals, see Hook System.

Sources: AGENTS.md43 AGENTS.md58-60

Configuration System

Multi-Level Merging

Configuration is loaded and merged across levels docs/reference/configuration.md44-58:

Defaults: Built-in system defaults.
User config: Global settings (e.g., ~/.config/opencode/oh-my-openagent.jsonc).
Project config: Local workspace settings (e.g., .opencode/oh-my-openagent.jsonc).

Sources: docs/reference/configuration.md44-58

Configuration Schema

The configuration provides extensive customization for agents and features:

Field Category	Purpose
Disabling Features	`disabled_mcps`, `disabled_agents`, `disabled_skills`, `disabled_hooks` assets/oh-my-opencode.schema.json32-71
Agent Overrides	Configure model, temperature, and thinking budget per agent assets/oh-my-opencode.schema.json112-186
Behavior Flags	`hashline_edit`, `model_fallback`, `new_task_system_enabled` assets/oh-my-opencode.schema.json11-111

For configuration reference, see Configuration Reference.

Sources: assets/oh-my-opencode.schema.json1-111 docs/reference/configuration.md71-143

Key Workflows

Ultrawork Mode

The ultrawork (or ulw) command engages the Sisyphus orchestrator to execute tasks autonomously until completion README.md109

Planning Workflow

Using /start-work engages Prometheus for strategic planning and interview-mode requirement gathering docs/guide/overview.md106-116

Hash-Anchored Editing

The hashline_edit system ensures code integrity by verifying content hashes before applying changes AGENTS.md43

Sources: README.md103-110 docs/guide/overview.md134-150