# opensoft/oh-my-opencode architecture

> Architecture diagram of the GitHub repository opensoft/oh-my-opencode, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/opensoft/oh-my-opencode
- Repository: https://github.com/opensoft/oh-my-opencode

## Overview

1. **What this repo is**
   - `oh-my-opencode` is a **TypeScript/Bun plugin and CLI distribution layer for OpenCode/Claude Code-style agents**.
   - Architecturally, it is not one app but a **bundle of loaders, hooks, tools, agents, and built-in commands** that extend an existing agent runtime.

2. **Top-level entry points**
   - `src/index.ts` is the main plugin surface.
   - `bin/oh-my-opencode.js` is the executable entry for the CLI.
   - `bin/platform.js` plus `packages/<os>-<arch>/` indicate **platform-specific packaging/distribution** for native-ish binaries or bundled assets.
   - `src/cli/*` contains standalone commands for installation, diagnostics, running flows, version checks, and model fallback handling.

3. **Configuration boundary**
   - `src/config` and `src/plugin-config.ts` define the repo’s **config schema and plugin config loading**.
   - Config is JSONC-capable and lives in **project-level `.opencode/` or user-level `~/.config/opencode/`** locations.
   - This config is the main control plane: it decides which agents, hooks, MCPs, skills, and behaviors are enabled or overridden.

4. **Core plugin orchestration**
   - `src/plugin-handlers` and `src/plugin-state.ts` look like the **bridge between OpenCode’s plugin interface and the internal feature modules**.
   - `src/shared` contains the common primitives used everywhere: config resolution, model resolution/sanitization, file utilities, session utilities, deep merge, logging, and compatibility helpers.
   - This shared layer is the “domain core” that keeps agents/hooks/tools consistent.

5. **Agent subsystem**
   - `src/agents/*` defines the specialized agent roles: **Sisyphus**, **Prometheus**, **Oracle**, **Librarian**, **Explore**, **Metis**, **Atlas**, **Momus**, and multimodal/looker variants.
   - These agents are not just prompts; they are a **role system** with prompt builders, permissions, and model assignments.
   - `dynamic-agent-prompt-builder.ts` suggests prompts are assembled from runtime context, config, and discovered repository state.

6. **Execution model: main agent plus delegation**
   - The readme makes the orchestration model clear: **Sisyphus is the primary agent**, and it delegates to other agents for planning, research, debugging, UI work, and code exploration.
   - `src/features/background-agent` and `src/tools/delegate-task` support **parallel/background execution**, so the main session stays lean while subagents do discovery or side work.
   - This is the central runtime pattern: **one orchestrator, many specialized workers**.

7. **Hook pipeline**
   - `src/hooks/*` is the largest runtime surface and acts like an **event-driven middleware layer** around agent interactions.
   - Hooks cover pre/post tool use, user prompt submission, stop/compact events, context-window recovery, task continuation, comment checking, auto-update checks, session recovery, think-mode switching, directory context injection, and more.
   - These hooks enforce behavior and inject context, so they are effectively the **policy and guardrail layer** of the system.

8. **Tooling layer**
   - `src/tools/*` exposes the operational capabilities agents can call: **grep/glob, AST-grep, LSP, interactive bash, session manager, skill execution, slash commands, background tasks, look-at, delegate-task, and MCP-backed tools**.
   - This is the main “actuation” boundary: agents reason, tools modify/query the environment.
   - The presence of LSP and AST-aware tools means the repo favors **deterministic code changes and codebase search** over pure text-based editing.

9. **Feature modules and local state**
   - `src/features/*` contains the heavier capability implementations and their state managers: **background-agent, boulder-state, tmux-subagent, task-toast-manager, skill loaders, Claude Code compatibility loaders, context injection, session state, and command loaders**.
   - Several of these persist state locally (`storage.ts`, `manager.ts`), which implies the system is **stateful across sessions** rather than stateless command execution.
   - `boulder-state`, `session-recovery`, and `interactive-bash-session` suggest long-running work is resumed and tracked on disk.

10. **Compatibility and interoperability**
   - `src/features/claude-code-*` and `src/hooks/claude-code-hooks` provide a **Claude Code compatibility layer** for agents, commands, MCPs, plugins, and hook events.
   - `src/features/claude-code-mcp-loader` and `src/features/claude-code-plugin-loader` indicate the repo can **ingest external Claude-style configs/plugins** and transform them into its own runtime.
   - This is an important architecture boundary: the project is both a product and an adapter for an existing ecosystem.

11. **External services and integrations**
   - `src/mcp/*` and built-in MCP references in the readme connect agents to **web search, official docs, and GitHub code search**.
   - Readme and tree also point to **tmux** integration, LSP servers, and download/extractor utilities for external tools.
   - These integrations extend the agent’s knowledge and execution surface beyond the local repo, but they are still mediated through explicit loaders/tools.

12. **Build, release, and distribution path**
   - `script/build-binaries.ts`, `script/build-schema.ts`, and `script/publish.ts` drive packaging and release automation.
   - GitHub Actions in `.github/workflows/*` handle CI, linting, CLA checks, and publishing.
   - The repo therefore has a clear split between **runtime code** and **release engineering**: compile/bundle, generate schema/artifacts, publish per platform.

13. **How a request flows through the system**
   - A user prompt enters OpenCode, the plugin loads config and context, hooks inject rules and repository knowledge, and the main agent receives a shaped prompt.
   - The main agent can then call tools, spawn background agents, or delegate to specialized agents/MCPs.
   - Results come back through the hook/tool pipeline, where they may be truncated, validated, commented on, or forced to continue until completion.

14. **Diagramming advice**
   - The clearest diagram would show three layers: **control plane** (config, plugin loading, CLI, schema), **runtime plane** (agents, hooks, tools, features), and **integration plane** (MCPs, LSP, tmux, external search/docs services, platform packages).
   - Emphasize that the repo is a **plugin harness and orchestration framework**, not a single-purpose application.

Main entry points: [`src/plugin-handlers/index.ts`](https://github.com/opensoft/oh-my-opencode/blob/dev/src/plugin-handlers/index.ts) (Plugin bridge), [`src/index.ts`](https://github.com/opensoft/oh-my-opencode/blob/dev/src/index.ts) (Plugin entry), [`src/tools/index.ts`](https://github.com/opensoft/oh-my-opencode/blob/dev/src/tools/index.ts) (Tool layer), [`src/hooks/index.ts`](https://github.com/opensoft/oh-my-opencode/blob/dev/src/hooks/index.ts) (Hook layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control plane"]
  node_bin_oh_my_opencode["CLI entry<br/>executable<br/>[oh-my-opencode.js]"]
  node_src_index["Plugin entry<br/>plugin-surface<br/>[index.ts]"]
  node_src_config["Config schema<br/>config-core<br/>[index.ts]"]
  node_src_plugin_config["Plugin config<br/>config-loader<br/>[plugin-config.ts]"]
  node_src_plugin_handlers["Plugin bridge<br/>orchestration<br/>[index.ts]"]
  node_src_plugin_state[("Plugin state<br/>[plugin-state.ts]")]
  node_src_shared["Shared core<br/>common-runtime<br/>[index.ts]"]
end

subgraph group_runtime["Runtime plane"]
  node_src_hooks["Hook layer<br/>middleware<br/>[index.ts]"]
  node_src_tools["Tool layer<br/>actuation<br/>[index.ts]"]
  node_src_agents["Agent roles<br/>role-system<br/>[index.ts]"]
  node_src_features_bg["Background work<br/>feature-module<br/>[index.ts]"]
  node_src_features_skill["Skill loading<br/>feature-module<br/>[index.ts]"]
  node_src_features_claude["Claude adapters<br/>compatibility<br/>[index.ts]"]
  node_src_builtin_commands["Built-in commands<br/>command-pack<br/>[index.ts]"]
  node_src_builtin_skills["Built-in skills<br/>skill-pack<br/>[index.ts]"]
end

subgraph group_integration["Integration plane"]
  node_src_mcp["MCP adapters<br/>integration<br/>[index.ts]"]
  node_bin_platform["Platform router<br/>distribution<br/>[platform.js]"]
  node_script_release["Release scripts<br/>release-engineering<br/>[publish.ts]"]
end

node_bin_oh_my_opencode -->|"starts"| node_src_index
node_src_index -->|"loads"| node_src_config
node_src_index -->|"applies"| node_src_plugin_config
node_src_index -->|"wires"| node_src_plugin_handlers
node_src_plugin_handlers -->|"routes"| node_src_hooks
node_src_plugin_handlers -->|"exposes"| node_src_tools
node_src_plugin_handlers -->|"configures"| node_src_agents
node_src_plugin_handlers -->|"shares state"| node_src_plugin_state
node_src_hooks -->|"uses"| node_src_shared
node_src_tools -->|"uses"| node_src_shared
node_src_agents -->|"uses"| node_src_shared
node_src_agents -->|"delegates"| node_src_features_bg
node_src_tools -->|"launches"| node_src_features_bg
node_src_tools -->|"calls"| node_src_mcp
node_src_features_skill -->|"loads"| node_src_builtin_skills
node_src_features_claude -->|"adapts"| node_src_mcp
node_src_features_claude -->|"extends"| node_src_hooks
node_src_builtin_commands -->|"invoked by"| node_src_hooks
node_bin_platform -->|"feeds"| node_script_release
node_script_release -->|"packages"| node_bin_platform
node_script_release -->|"generates schema"| node_src_config

click node_bin_oh_my_opencode "https://github.com/opensoft/oh-my-opencode/blob/dev/bin/oh-my-opencode.js"
click node_src_index "https://github.com/opensoft/oh-my-opencode/blob/dev/src/index.ts"
click node_src_config "https://github.com/opensoft/oh-my-opencode/blob/dev/src/config/index.ts"
click node_src_plugin_config "https://github.com/opensoft/oh-my-opencode/blob/dev/src/plugin-config.ts"
click node_src_plugin_handlers "https://github.com/opensoft/oh-my-opencode/blob/dev/src/plugin-handlers/index.ts"
click node_src_plugin_state "https://github.com/opensoft/oh-my-opencode/blob/dev/src/plugin-state.ts"
click node_src_shared "https://github.com/opensoft/oh-my-opencode/blob/dev/src/shared/index.ts"
click node_src_hooks "https://github.com/opensoft/oh-my-opencode/blob/dev/src/hooks/index.ts"
click node_src_tools "https://github.com/opensoft/oh-my-opencode/blob/dev/src/tools/index.ts"
click node_src_agents "https://github.com/opensoft/oh-my-opencode/blob/dev/src/agents/index.ts"
click node_src_features_bg "https://github.com/opensoft/oh-my-opencode/blob/dev/src/features/background-agent/index.ts"
click node_src_features_skill "https://github.com/opensoft/oh-my-opencode/blob/dev/src/features/opencode-skill-loader/index.ts"
click node_src_features_claude "https://github.com/opensoft/oh-my-opencode/blob/dev/src/features/claude-code-plugin-loader/index.ts"
click node_src_builtin_commands "https://github.com/opensoft/oh-my-opencode/blob/dev/src/features/builtin-commands/index.ts"
click node_src_builtin_skills "https://github.com/opensoft/oh-my-opencode/blob/dev/src/features/builtin-skills/index.ts"
click node_src_mcp "https://github.com/opensoft/oh-my-opencode/blob/dev/src/mcp/index.ts"
click node_bin_platform "https://github.com/opensoft/oh-my-opencode/blob/dev/bin/platform.js"
click node_script_release "https://github.com/opensoft/oh-my-opencode/blob/dev/script/publish.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_bin_oh_my_opencode,node_src_index,node_src_config,node_src_plugin_config,node_src_plugin_handlers,node_src_plugin_state,node_src_shared toneBlue
class node_src_hooks,node_src_tools,node_src_agents,node_src_features_bg,node_src_features_skill,node_src_features_claude,node_src_builtin_commands,node_src_builtin_skills toneAmber
class node_src_mcp,node_bin_platform,node_script_release toneMint
```

## Components

### Control plane

Entry points, configuration, and plugin wiring.

- [CLI entry](https://github.com/opensoft/oh-my-opencode/blob/dev/bin/oh-my-opencode.js): executable · Main Bun/Node executable for the distribution layer. · `bin/oh-my-opencode.js`
- [Plugin entry](https://github.com/opensoft/oh-my-opencode/blob/dev/src/index.ts): plugin-surface · Top-level plugin surface loaded by OpenCode/Claude-style runtimes. · `src/index.ts`
- [Config schema](https://github.com/opensoft/oh-my-opencode/blob/dev/src/config/index.ts): config-core · Repository and user config schema plus loading/validation boundary. · `src/config/index.ts`
- [Plugin config](https://github.com/opensoft/oh-my-opencode/blob/dev/src/plugin-config.ts): config-loader · Resolves plugin-specific configuration and overrides. · `src/plugin-config.ts`
- [Plugin bridge](https://github.com/opensoft/oh-my-opencode/blob/dev/src/plugin-handlers/index.ts): orchestration · Connects host plugin events to internal feature modules. · `src/plugin-handlers/index.ts`
- [Plugin state](https://github.com/opensoft/oh-my-opencode/blob/dev/src/plugin-state.ts): state · Shared runtime state for plugin coordination. · `src/plugin-state.ts`
- [Shared core](https://github.com/opensoft/oh-my-opencode/blob/dev/src/shared/index.ts): common-runtime · Core utilities for config, models, files, sessions, logging, and compatibility. · `src/shared/index.ts`

### Runtime plane

Agents, hooks, tools, and feature modules that run inside the agent session.

- [Hook layer](https://github.com/opensoft/oh-my-opencode/blob/dev/src/hooks/index.ts): middleware · Event-driven middleware that injects policy, context, and recovery behavior. · `src/hooks/index.ts`
- [Tool layer](https://github.com/opensoft/oh-my-opencode/blob/dev/src/tools/index.ts): actuation · Operational tools agents call for search, edits, sessions, delegation, and external actions. · `src/tools/index.ts`
- [Agent roles](https://github.com/opensoft/oh-my-opencode/blob/dev/src/agents/index.ts): role-system · Specialized agent definitions, prompts, permissions, and model assignments. · `src/agents/index.ts`
- [Background work](https://github.com/opensoft/oh-my-opencode/blob/dev/src/features/background-agent/index.ts): feature-module · Background-agent execution and local state management for parallel work. · `src/features/background-agent/index.ts`
- [Skill loading](https://github.com/opensoft/oh-my-opencode/blob/dev/src/features/opencode-skill-loader/index.ts): feature-module · Loads built-in and external skills and coordinates skill MCP state. · `src/features/opencode-skill-loader/index.ts`
- [Claude adapters](https://github.com/opensoft/oh-my-opencode/blob/dev/src/features/claude-code-plugin-loader/index.ts): compatibility · Loads Claude Code-style agents, commands, MCPs, plugins, and session state. · `src/features/claude-code-plugin-loader/index.ts`
- [Built-in commands](https://github.com/opensoft/oh-my-opencode/blob/dev/src/features/builtin-commands/index.ts): command-pack · Packaged command templates and command registration data. · `src/features/builtin-commands/index.ts`
- [Built-in skills](https://github.com/opensoft/oh-my-opencode/blob/dev/src/features/builtin-skills/index.ts): skill-pack · Bundled skills that extend agent behavior with reusable workflows. · `src/features/builtin-skills/index.ts`

### Integration plane

External adapters, MCPs, platform packaging, and release plumbing.

- [MCP adapters](https://github.com/opensoft/oh-my-opencode/blob/dev/src/mcp/index.ts): integration · Built-in MCP integrations for search and documentation backends. · `src/mcp/index.ts`
- [Platform router](https://github.com/opensoft/oh-my-opencode/blob/dev/bin/platform.js): distribution · Selects platform-specific packaging and assets for release distribution. · `bin/platform.js`
- [Release scripts](https://github.com/opensoft/oh-my-opencode/blob/dev/script/publish.ts): release-engineering · Builds binaries, schema artifacts, changelogs, and publish packages. · `script/publish.ts`

## Connections

- CLI entry → Plugin entry: starts · CLI bootstraps the plugin/runtime surface.
- Plugin entry → Config schema: loads · Plugin entry resolves repository and user configuration.
- Plugin entry → Plugin config: applies · Plugin entry merges plugin-specific overrides and defaults.
- Plugin entry → Plugin bridge: wires · Top-level entry dispatches host events into internal handlers.
- Plugin bridge → Hook layer: routes · Host events flow into hook-based policy and context middleware.
- Plugin bridge → Tool layer: exposes · Handlers publish tool surfaces to the agent runtime.
- Plugin bridge → Agent roles: configures · Handlers attach agent roles and prompt behavior.
- Plugin bridge → Plugin state: shares state · Runtime coordination uses plugin-wide shared state.
- Hook layer → Shared core: uses · Hooks rely on shared utilities for config, files, models, and sessions.
- Tool layer → Shared core: uses · Tools reuse common utilities and compatibility helpers.
- Agent roles → Shared core: uses · Agent role construction depends on shared model and prompt helpers.
- Agent roles → Background work: delegates · Primary orchestration can spawn background work for subtasks.
- Tool layer → Background work: launches · Background-task and delegate tools connect to the background runtime.
- Tool layer → MCP adapters: calls · Tooling wraps MCP-backed integrations for external knowledge sources.
- Skill loading → Built-in skills: loads · Skill loader discovers and merges bundled skills.
- Claude adapters → MCP adapters: adapts · Claude-style MCP definitions are transformed into native integrations.
- Claude adapters → Hook layer: extends · Compatibility layer contributes additional hook behavior and state.
- Built-in commands → Hook layer: invoked by · Built-in commands are executed through hook and command plumbing.
- Platform router → Release scripts: feeds · Platform selection supports the release/build pipeline.
- Release scripts → Platform router: packages · Release automation produces per-platform distributions.
- Release scripts → Config schema: generates schema · Build scripts emit schema and release artifacts from config definitions.
