Configuration
Relevant source files
The following files were used as context for generating this wiki page:
The configuration system in Oh-My-OpenCode is designed to provide a highly customizable and multi-layered orchestration environment for AI agents. It leverages Zod for schema validation and supports JSONC (JSON with Comments) to allow for a more developer-friendly configuration experience, including trailing commas and inline comments. Sources: AGENTS.md, README.md
The system follows a hierarchical structure, merging configurations from the project level (.opencode/) and the user level (~/.config/opencode/). This allows developers to define project-specific rules and agent behaviors while maintaining global user preferences across different repositories. Sources: AGENTS.md, README.md
Configuration Hierarchy and Resolution
The project employs a multi-level configuration strategy. When the plugin initializes, it resolves settings by looking at multiple locations and merging them according to specific priorities. Sources: AGENTS.md, src/cli/config-manager.ts
Config Locations
- Project Level: Located at
.opencode/oh-my-opencode.json. This is used for repository-specific settings such as custom agents, specialized hooks, or project-specific skills. - User Level: Located at
~/.config/opencode/oh-my-opencode.json. This contains global preferences like API keys or default model selections.
The following diagram illustrates the data flow for configuration resolution:
The configuration is merged and then validated against a Zod schema to ensure type safety before the orchestrator starts. Sources: AGENTS.md, src/cli/config-manager.ts
Core Configuration Components
Agent Definitions
Users can override model selections, temperatures, system prompts, and tool permissions for any agent. The configuration allows for specialized agents such as Sisyphus, Prometheus, and Oracle. Sources: README.md, sisyphus-prompt.md
| Configuration Option | Description | Relevant Agents |
|---|---|---|
model | The specific LLM model ID (e.g., claude-opus-4-5) | All Agents |
temperature | Controls randomness (Default 0.1 for code agents) | All Agents |
permission | Tool execution restrictions | Oracle, Momus |
thinking | Thinking budget and token allocation | Sisyphus, Prometheus |
Sources: src/config/schema.ts, AGENTS.md, sisyphus-prompt.md
Task Delegation Categories
The system uses categories to route tasks to the most appropriate models based on the domain of the work. Sources: src/tools/delegate-task/constants.ts, sisyphus-prompt.md
Sources: src/tools/delegate-task/constants.ts
Category Mapping Table
Default categories are mapped to specific models optimized for their respective tasks:
| Category | Optimized Domain | Default Model |
|---|---|---|
visual-engineering | Frontend, UI/UX, styling | google/gemini-3-pro |
ultrabrain | Architecture, deep logic | openai/gpt-5.2-codex |
quick | Trivial tasks, typos | anthropic/claude-haiku-4-5 |
writing | Documentation, technical prose | google/gemini-3-flash |
deep | Autonomous problem-solving | openai/gpt-5.2-codex |
Sources: src/tools/delegate-task/constants.ts:101-110
Implementation Details
Zod Schema Validation
The configuration is strictly validated using Zod. This prevents runtime errors caused by malformed JSON or invalid model IDs. The schema defines the structure for hooks, agents, and tool permissions. Sources: src/config/schema.ts, AGENTS.md
// Example representation of the configuration schema structure
const configSchema = z.object({
agents: z.record(z.string(), agentConfigSchema).optional(),
disabled_hooks: z.array(z.string()).optional(),
categories: z.record(z.string(), categoryConfigSchema).optional(),
experimental: z.object({
aggressive_truncation: z.boolean().optional(),
auto_resume: z.boolean().optional(),
}).optional(),
});
Sources: src/config/schema.ts, AGENTS.md
JSONC Support
The config-manager.ts handles the parsing of JSONC, allowing users to document their configuration files directly. This is particularly useful for explaining why specific model overrides or hook disablements were chosen. Sources: src/cli/config-manager.ts:667, README.md
Specialized System Prompts
The configuration extends to the prompt level, where files like sisyphus-prompt.md define the operational behavior of the primary agent. This include identity constraints, behavior instructions for intent gating, and parallel execution logic. Sources: sisyphus-prompt.md:31-100
Key behavioral flags defined in prompts include:
- Intent Gate: Checks every message for skill triggers before classification. Sources: sisyphus-prompt.md:46-50
- Skill Triggers: Mandatory use of specific skills for certain domains (e.g.,
git-masterfor any git operation). Sources: sisyphus-prompt.md:55-60 - Verification Rules: Mandatory use of
lsp_diagnosticsand build commands before task completion. Sources: sisyphus-prompt.md:330-340
Summary
The configuration system in Oh-My-OpenCode provides the backbone for multi-agent orchestration. By combining hierarchical JSONC files with strict Zod validation and domain-specific categories, it allows for granular control over how AI agents interact with the codebase, which models are utilized for specific tasks, and how execution is verified. Sources: AGENTS.md, README.md, src/config/schema.ts