How opensoft/oh-my-opencode works
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: plugin-handlers/index.ts Plugin bridge · src/index.ts Plugin entry · tools/index.ts Tool layer · hooks/index.ts Hook layer
Components 18
Control plane
Entry points, configuration, and plugin wiring.
- CLI entry · Main Bun/Node executable for the distribution layer.
bin/oh-my-opencode.js - Plugin entry · Top-level plugin surface loaded by OpenCode/Claude-style runtimes.
src/index.ts - Config schema · Repository and user config schema plus loading/validation boundary.
src/config/index.ts - Plugin config · Resolves plugin-specific configuration and overrides.
src/plugin-config.ts - Plugin bridge · Connects host plugin events to internal feature modules.
src/plugin-handlers/index.ts - Plugin state · Shared runtime state for plugin coordination.
src/plugin-state.ts - Shared core · 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 · Event-driven middleware that injects policy, context, and recovery behavior.
src/hooks/index.ts - Tool layer · Operational tools agents call for search, edits, sessions, delegation, and external actions.
src/tools/index.ts - Agent roles · Specialized agent definitions, prompts, permissions, and model assignments.
src/agents/index.ts - Background work · Background-agent execution and local state management for parallel work.
src/features/background-agent/index.ts - Skill loading · Loads built-in and external skills and coordinates skill MCP state.
src/features/opencode-skill-loader/index.ts - Claude adapters · Loads Claude Code-style agents, commands, MCPs, plugins, and session state.
src/features/claude-code-plugin-loader/index.ts - Built-in commands · Packaged command templates and command registration data.
src/features/builtin-commands/index.ts - Built-in skills · 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 · Built-in MCP integrations for search and documentation backends.
src/mcp/index.ts - Platform router · Selects platform-specific packaging and assets for release distribution.
bin/platform.js - Release scripts · Builds binaries, schema artifacts, changelogs, and publish packages.
script/publish.ts
Connections 21
- 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.