Installation & Setup
Relevant source files
The following files were used as context for generating this wiki page:
Oh-My-OpenCode is a modular plugin for OpenCode designed to enhance AI-assisted development through multi-model orchestration, specialized agents, and advanced toolsets. The installation process is designed to be automated via AI agents or handled manually by developers through standard configuration paths.
The setup environment relies on Bun as the exclusive package manager and runtime, ensuring high-performance execution of background agents and tools. It integrates directly into the OpenCode configuration system, supporting both project-level and user-level settings.
Sources: README.md:155-165, CONTRIBUTING.md:43-50, AGENTS.md:145-155
Prerequisites & Environment Setup
Before installation, the host system must meet specific software version requirements to ensure compatibility with OpenCode's plugin API and the plugin's internal logic.
| Requirement | Version | Description |
|---|---|---|
| Bun | Latest | The only supported package manager and runtime. |
| OpenCode | 1.0.150+ | Required for plugin API and hook compatibility. |
| TypeScript | 5.7.3+ | Required for type checking and local builds. |
Sources: CONTRIBUTING.md:43-47, AGENTS.md:162-164
Development Environment Setup
For developers contributing to the project, the setup involves cloning the repository and utilizing Bun for dependency management. Manual use of npm or yarn is strictly forbidden to prevent lockfile conflicts.
# Clone and install
git clone https://github.com/code-yeongyu/oh-my-opencode.git
cd oh-my-opencode
bun install
# Build the project
bun run build
Sources: CONTRIBUTING.md:52-60, AGENTS.md:112-115
Installation Workflows
The project supports two primary installation paths: an automated "Agent-Led" installation and a manual developer workflow.
Automated Installation (Recommended)
Users can delegate the installation to an existing LLM agent (such as Claude Code or Cursor) by providing the raw installation guide URL. This method reduces human error in configuration.
Install and configure oh-my-opencode by following the instructions here:
https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/refs/heads/master/docs/guide/installation.md
Sources: README.md:175-180
Manual Plugin Registration
To manually install the plugin, the absolute path to the built index.js must be added to the OpenCode configuration file (opencode.json or opencode.jsonc).
The diagram shows the logic for registering the local build as an OpenCode plugin.
Sources: CONTRIBUTING.md:65-80, AGENTS.md:158-160
Configuration System
Oh-My-OpenCode utilizes a multi-level configuration system that supports JSON with Comments (JSONC). Configuration is resolved in a hierarchy: Project-level settings override User-level settings.
Configuration Locations
- Project-level:
.opencode/oh-my-opencode.json - User-level:
~/.config/opencode/oh-my-opencode.json
Sources: README.md:215-225, AGENTS.md:155-160
Plugin Initialization Flow
When OpenCode loads, the plugin initializes its lifecycle hooks and registers built-in agents and tools.
The sequence diagram illustrates the internal registration process during plugin startup.
Sources: AGENTS.md:105-115, CONTRIBUTING.md:85-95
Build & Publishing Architecture
The project employs a complex multi-platform binary build system to support various operating systems and architectures (Linux, macOS, Windows).
Platform Support
Platform-specific binaries are maintained in the packages/ directory, including:
darwin-arm64/darwin-x64linux-x64/linux-arm64(including musl variants)windows-x64
Sources: script/publish.ts:13-21, AGENTS.md:105-110
Automated Release Workflow
Publishing is strictly handled via GitHub Actions to maintain OIDC provenance and ensure version consistency across all platform packages.
This flowchart details the CI/CD pipeline used to sync versions and publish the multi-package ecosystem.
Sources: script/publish.ts:25-50, script/publish.ts:180-200, CONTRIBUTING.md:155-165
Verification & Troubleshooting
After setup, users should verify the installation by checking for OmO agent availability or inspecting the startup logs.
Key Build Commands
| Command | Action |
|---|---|
bun run build | Compiles ESM, generates .d.ts and JSON schema. |
bun run build:schema | Updates the Zod-based configuration schema. |
bun run typecheck | Validates TypeScript integrity. |
bun test | Executes the suite of 100 test files. |
Sources: CONTRIBUTING.md:105-115, AGENTS.md:135-140
Failure Recovery Protocol
If the setup fails during runtime (particularly for agents), the system follows a specific recovery logic:
- Revert to last known working state.
- Document failure context.
- Consult the Oracle agent for high-IQ reasoning.
- Escalate to the user if unresolved after 3 attempts.
Sources: src/agents/prometheus/identity-constraints.ts:150-165, src/agents/prometheus/plan-generation.ts:110-125
Successful installation of Oh-My-OpenCode establishes a robust orchestration layer within OpenCode, enabling developers to leverage specialized subagents like Prometheus for planning and Sisyphus for execution. The transition from a manual setup to an agent-driven environment is the primary objective of the configuration process.