Plugin & Loader System
Relevant source files
The following files were used as context for generating this wiki page:
The Plugin & Loader system in Oh-My-OpenCode serves as a comprehensive orchestration layer designed to extend the capabilities of the OpenCode base platform. It functions as a "multi-model agent orchestration" system, providing a structured environment for integrating specialized AI agents, lifecycle hooks, and advanced developer tools. By acting as a compatibility layer for Claude Code, it allows developers to utilize various LLM providers (Anthropic, OpenAI, Google) within a single unified terminal interface.
The system is architected around a core plugin entry point that manages the registration and execution of 34 lifecycle hooks, 20+ specialized tools (including LSP and AST-Grep), and 11 distinct AI agents. This modular design enables the platform to perform complex tasks such as background task execution, parallel agent dispatching, and automated code refactoring while maintaining a strict adherence to project-specific conventions and safety guardrails.
Sources: README.md, AGENTS.md:OVERVIEW
Core Orchestration Architecture
The system utilizes a hierarchical orchestration model where a primary agent (typically Sisyphus or Atlas) manages subagents to execute specialized tasks. This architecture minimizes context load on the primary model by delegating heavy lifting to domain-specific agents.
Agent Tier System
The orchestration is organized into specialized roles, each mapped to specific models optimized for their respective domains:
| Tier | Agent Name | Primary Model | Purpose |
|---|---|---|---|
| Orchestrator | Sisyphus | Claude Opus 4.5 | Primary driver and task manager. |
| Planner | Prometheus | Claude Opus 4.5 | Strategic planning and interview conductor. |
| Consultant | Oracle | GPT 5.2 | High-IQ debugging and architecture design. |
| Researcher | Librarian | GLM 4.7 | Multi-repository analysis and documentation search. |
| Deep Worker | Hephaestus | GPT 5.2 Codex | Autonomous execution and "Legitimate Craftsmanship." |
Sources: AGENTS.md:AGENT_MODELS, sisyphus-prompt.md:Available_Agents
Delegation Workflow
Orchestrators use the delegate_task() API to spawn subagents. This process involves a "6-Section Prompt Structure" that ensures subagents receive explicit instructions, context, and "Inherited Wisdom" from a project-level notepad.
The diagram above illustrates the parallel execution wave system used to maximize throughput during task implementation.
Sources: src/agents/atlas/gpt.ts:workflow, src/tools/delegate-task/constants.ts:SECTION_2
Plugin Lifecycle & Hooks
The system manages 34 lifecycle hooks that allow for intercepting and augmenting the behavior of the OpenCode environment. These hooks are categorized into pre-tool, post-tool, session, and prompt submission events.
Hook Implementation Pattern
Hooks are created using factory functions (e.g., createXXXHook) and registered in the main plugin entry. This allows the system to enforce "Guardrails" and "Anti-patterns" dynamically. For example, the Comment Checker hook prevents AI from adding excessive comments to codebases.
Major Lifecycle Events
- onSessionStart: Initializes the environment and loads project-specific AGENTS.md context.
- PreToolUse: Intercepts tool calls to validate permissions or add context (e.g., ensuring
playwrightis used for browser tasks). - PostToolUse: Verifies the output of a tool (e.g., running
lsp_diagnosticsafter a file edit). - UserPromptSubmit: Augments user input with "ultrawork" instructions or relevant codebase snippets.
Sources: AGENTS.md:STRUCTURE, README.md:Features, CONTRIBUTING.md:Adding_a_New_Hook
Task & Skill Loading System
The system uses a sophisticated category and skill matching protocol to determine which model and specialized instructions should be used for a given task.
Category Configuration
Categories map tasks to specific models and system prompts:
| Category | Recommended Model | Use Case |
|---|---|---|
visual-engineering | Gemini 3 Pro | Frontend, styling, and animations. |
ultrabrain | GPT 5.2 Codex | Complex logic and deep architectural decisions. |
quick | Claude Haiku 4.5 | Trivial changes and typo fixes. |
artistry | Gemini 3 Pro | Unconventional, creative problem-solving. |
Sources: src/tools/delegate-task/constants.ts:DEFAULT_CATEGORIES
Skill Injection
Skills are specialized instruction sets injected into subagents. The system mandates a "Skill Evaluation" protocol where the orchestrator must justify the inclusion or omission of every available skill (e.g., git-master, playwright, frontend-ui-ux).
This sequence shows how the Loader System augments the subagent's identity with specialized skills before execution.
Sources: sisyphus-prompt.md:Pre-Delegation_Planning, src/tools/delegate-task/constants.ts:SECTION_3
Technical Implementation Details
The system is built exclusively using the Bun runtime, leveraging its high-performance build tools and type safety.
Project Structure and Exports
The project follows a "Barrel" export pattern via src/index.ts. Each tool and feature is isolated into its own directory containing implementation, types, and constants.
// Example of Tool directory structure required by the system
oh-my-opencode/
└── src/tools/my-tool/
├── index.ts // Main exports
├── types.ts // Interfaces
├── constants.ts // Tool descriptions
├── tools.ts // Implementations
└── utils.ts // Helpers
Sources: CONTRIBUTING.md:Project_Structure, CONTRIBUTING.md:Code_Style_&_Conventions
Development and Build Pipeline
The system enforces strict development standards to ensure stability:
- Package Manager: Bun only (npm/yarn are forbidden).
- Types:
bun-typesinstead of@types/node. - Validation: Zod-based schema validation for configuration (
src/config/schema.ts). - Build:
bun run buildgenerates ESM output, TypeScript declarations, and JSON schemas.
Sources: AGENTS.md:CONVENTIONS, CONTRIBUTING.md:Build_Commands
Summary
The Plugin & Loader system of Oh-My-OpenCode transforms a standard AI coding assistant into a multi-agent development team. By integrating specialized agents like Prometheus for planning and Momus for review, the system ensures that work is planned meticulously and executed with high precision. The reliance on parallel execution waves and automated verification via LSP and Bash tools makes it a highly efficient environment for large-scale codebase refactoring and autonomous task completion.