Installation and Setup
Relevant source files
The following files were used as context for generating this wiki page:
OhMyOpenCode is a high-performance orchestration layer designed to enhance the OpenCode agent environment. The installation process facilitates the integration of advanced multi-model agents, curated MCPs (Model Context Protocol), and specialized tools for deep codebase exploration and autonomous task execution.
The setup enables a "Battery Included" experience, allowing agents to operate with parallel background tasks, structured planning phases, and automated verification loops. Users can initiate the environment via a simple installation command or by delegating the setup to an existing LLM agent to ensure proper configuration of the project-specific or user-wide environment.
Sources: README.md:1-25, README.md:145-165
Core Installation Methods
OhMyOpenCode can be installed manually by developers or delegated to an AI agent to minimize configuration errors.
Human-Led Installation
Developers can follow the official guide to integrate the plugin into their local environment. The primary method involves updating the OpenCode configuration file to include the oh-my-opencode plugin.
Agent-Led Installation
For automated setup, users can provide the installation URL to an existing agent (e.g., Claude Code, Cursor). The agent then fetches the guide and executes the necessary bash commands to configure the environment.
# Command used by agents to fetch installation instructions
curl -s https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/refs/heads/master/docs/guide/installation.md
Sources: README.md:188-202
Configuration Management
The system utilizes a hierarchical configuration structure, allowing for global user settings or granular project-specific overrides.
| Config Type | File Path | Scope |
|---|---|---|
| Project Config | .opencode/oh-my-opencode.json | Specific repository settings |
| User Config | ~/.config/opencode/oh-my-opencode.json | Global agent preferences |
| OpenCode Plugin | ~/.config/opencode/opencode.json | Core plugin registration |
Sources: README.md:218-225, README.md:209-215
Directory Initialization (/init-deep)
For complex codebases, the /init-deep command is used to generate hierarchical knowledge base files (AGENTS.md). This process involves discovery, complexity scoring, and parallel generation of documentation.
The discovery phase concurrently fires background explore agents to analyze project scale, finding entry points and anti-patterns.
Sources: src/features/builtin-commands/templates/init-deep.ts:25-50, src/features/builtin-commands/templates/init-deep.ts:110-125
Initializing the Planning Environment
Once installed, the primary interaction model begins with a planning phase managed by the Prometheus agent. Prometheus serves as a strategic consultant that creates work plans before execution begins.
The .sisyphus Directory
The system relies on a dedicated hidden directory for storing planning artifacts and drafts:
- Plans:
.sisyphus/plans/*.md - Drafts:
.sisyphus/drafts/*.md - Evidence:
.sisyphus/evidence/(for QA screenshots and logs)
Sources: src/agents/prometheus/identity-constraints.ts:100-115, src/agents/prometheus/plan-template.ts:50-65
Plan Generation Workflow
Prometheus follows a strict protocol to transition from interview to plan generation, ensuring all requirements are captured in a single atomic file.
Prometheus is constrained to only create or edit Markdown files within the .sisyphus/ directory to prevent unauthorized source code modifications during the planning phase.
Sources: src/agents/prometheus/identity-constraints.ts:80-95, src/agents/prometheus/plan-generation.ts:45-70
Setup Verification and Performance
Verification is an integral part of the setup to ensure the "autonomous deep worker" (Hephaestus) and other agents have the necessary environment context.
The Execution Loop
After setup, the agent follows an Explore → Plan → Decide → Execute → Verify loop. The verification step is mandatory and requires:
lsp_diagnosticsreturning zero errors on modified files.- Build commands exiting with code 0.
- Passing automated tests or documented QA scenarios.
Sources: src/agents/hephaestus.ts:250-270, src/agents/hephaestus.ts:330-345
Build and Distribution
For developers contributing to or building the project, a multi-package distribution system is used, targeting various platforms (Darwin, Linux, Windows).
| Platform | Architecture | Package Name |
|---|---|---|
| Darwin | arm64 / x64 | oh-my-opencode-darwin-[arch] |
| Linux | arm64 / x64 (glibc/musl) | oh-my-opencode-linux-[arch]-[libc] |
| Windows | x64 | oh-my-opencode-windows-x64 |
Sources: script/publish.ts:10-20
Summary
Installation and Setup for OhMyOpenCode transforms a standard OpenCode environment into a specialized multi-agent forge. By configuring the .opencode/ and .sisyphus/ directories and registering the core plugin, users enable structured planning via Prometheus and high-intensity execution via Sisyphus and Hephaestus. The system emphasizes verification-led progress, where every architectural decision and code change is mapped, planned, and validated autonomously.