This document describes the overall system architecture of oh-my-opencode (dual-published as oh-my-openagent), a multi-agent orchestration harness implemented as an OpenCode plugin. It covers the initialization pipeline, major component subsystems, directory structure, and interaction patterns between agents, hooks, tools, and the OpenCode platform.
For detailed information about specific subsystems, see:
OhMyOpenCodePlugin integrates with OpenCode, the initialization flow, and plugin interface.BackgroundManager, task lifecycle, concurrency control, and parent session notifications.oh-my-opencode is implemented as a single OpenCode plugin that extends the platform through various hook handlers. It follows a factory pattern throughout the codebase, with all major components created through createXXX() functions. Following a major package layering refactor, the plugin adapter logic resides in packages/omo-opencode/, which shims over 19 core packages and 4 MCP packages. AGENTS.md43-46 packages/AGENTS.md7-18
The architecture follows a five-stage initialization pipeline where each stage depends on outputs from previous stages:
Config → Managers → Tools → Hooks → Plugin Interface
Sources: AGENTS.md43-46 packages/AGENTS.md7-18
This diagram shows how pluginModule.server (created via createPluginModule) orchestrates the initialization stages. Each stage is a factory function that returns a typed object, which is passed to subsequent stages. The final stage returns a PluginInterface object that OpenCode uses to invoke the plugin's handlers. AGENTS.md45 packages/omo-opencode/src/hooks/AGENTS.md7
Sources: AGENTS.md41-68 packages/AGENTS.md7-18 packages/omo-opencode/src/hooks/AGENTS.md1-22
The codebase is organized as a monorepo with 38 sibling packages categorized by role. packages/AGENTS.md7-18
| Role | Packages | Purpose |
|---|---|---|
| Adapters | omo-opencode, omo-codex | Platform-specific shims for OpenCode and Codex CLI. packages/AGENTS.md69-70 |
| Core | utils, model-core, prompts-core, rules-engine, etc. | 19 harness-neutral packages providing the engine logic. packages/AGENTS.md37-60 |
| MCP | lsp-tools-mcp, ast-grep-mcp, git-bash-mcp, lsp-daemon | Standalone servers providing specialized tools via JSON-RPC. packages/AGENTS.md28-35 |
| Binaries | oh-my-opencode-darwin-arm64, etc. | 11 platform-specific binary packages for runtime selection. packages/AGENTS.md20-27 |
Sources: package.json8-32 packages/AGENTS.md1-75
The configuration system loads from multiple levels (user, project, and workspace) and merges them into a single state. AGENTS.md43-45 assets/oh-my-opencode.schema.json1-7
oh-my-opencode.jsonc and oh-my-openagent.jsonc and legacy folder migration. AGENTS.md45 packages/omo-opencode/src/hooks/AGENTS.md51~/.config/opencode/ and project-local .opencode/ configurations. AGENTS.md43-45Sources: AGENTS.md43-45 assets/oh-my-opencode.schema.json1-100
The createManagers() function instantiates core operational managers that provide services across the plugin: AGENTS.md45 packages/AGENTS.md15
| Manager | Purpose | Implementation Package |
|---|---|---|
TmuxSessionManager | Tmux pane lifecycle, grid planning, and subagent session orchestration | tmux-core packages/AGENTS.md53 |
BackgroundManager | Task lifecycle, concurrency control, and async delegation polling | omo-opencode/src/features AGENTS.md45 |
SkillMcpManager | Management for Tier-3 skill-embedded MCP clients (stdio/HTTP/OAuth) | mcp-client-core packages/AGENTS.md56 |
ConfigHandler | Orchestrates the 6-phase configuration pipeline and runtime adaptation | omo-opencode/src/plugin AGENTS.md65 |
Sources: AGENTS.md43-68 packages/AGENTS.md37-60
The registry manages 20–39 tools, including native implementations and those served via the 3-tier MCP system. AGENTS.md43 packages/omo-opencode/src/hooks/AGENTS.md16
Sources: AGENTS.md43-68 packages/omo-opencode/src/hooks/AGENTS.md16-24
The system utilizes 53 base hooks (60 with team-mode) organized into five functional tiers. packages/omo-opencode/src/hooks/AGENTS.md1-22
| Tier | Purpose | Examples |
|---|---|---|
| Session (23) | Lifecycle (created/idle/error/params) | preemptiveCompaction, sessionNotification, thinkMode packages/omo-opencode/src/hooks/AGENTS.md26-52 |
| Tool Guard (17) | Pre/Post execution safety and enrichment | commentChecker, writeExistingFileGuard, bashFileReadGuard packages/omo-opencode/src/hooks/AGENTS.md53-74 |
| Transform (4) | Prompt and message manipulation | keywordDetector, rulesInjector, toolPairValidator packages/omo-opencode/src/hooks/AGENTS.md75-82 |
| Continuation (7) | Long-running task loops and background monitoring | todoContinuationEnforcer, ralphLoop, atlasHook packages/omo-opencode/src/hooks/AGENTS.md84-95 |
| Skill (2) | Feature discovery and auto-execution | categorySkillReminder, autoSlashCommand packages/omo-opencode/src/hooks/AGENTS.md96-102 |
Sources: packages/omo-opencode/src/hooks/AGENTS.md1-102
The final PluginInterface maps OpenCode platform hooks to the internal orchestrated handlers. AGENTS.md54-65
| Handler | OpenCode Hook | Purpose |
|---|---|---|
config | config | Triggers the 6-phase config loading pipeline AGENTS.md65 |
tool | tool | Returns the registry of native and MCP tools AGENTS.md59 |
chat.message | chat.message | Session setup, keyword detection, and agent interception AGENTS.md55 |
event | event | Lifecycle events (idle/error), runtime fallback, and team events AGENTS.md65 |
messages.transform | experimental.chat.messages.transform | Context injection (AGENTS.md/README.md) and prompt adaptation AGENTS.md65 |
Sources: AGENTS.md43-68 packages/omo-opencode/src/hooks/AGENTS.md1-22
Agents are defined in packages/omo-opencode/src/agents/ and follow a standard factory pattern. They are categorized by mode (primary, subagent, or all). AGENTS.md57 packages/omo-opencode/src/hooks/AGENTS.md48-49
The system supports 11 agents including Sisyphus (Main Orchestrator), Hephaestus (Deep Worker), Prometheus (Planner), and Atlas (Todo Master). AGENTS.md57 packages/omo-opencode/src/hooks/AGENTS.md41-49
Sources: AGENTS.md57 packages/omo-opencode/src/hooks/AGENTS.md41-49
Model selection balances user preference with agent requirements through a prioritized resolution pipeline. packages/omo-opencode/src/hooks/AGENTS.md46-50
The system implements a 5-tier resolution priority system to ensure reliability across providers, utilizing proactive (modelFallback) and reactive (runtimeFallback) hooks. packages/omo-opencode/src/hooks/AGENTS.md46-50 assets/oh-my-opencode.schema.json109-111
Sources: packages/omo-opencode/src/hooks/AGENTS.md46-50 assets/oh-my-opencode.schema.json109-111
Refresh this wiki