Skip to content

configurations.md

Latest commit

 

History

History
654 lines (523 loc) · 28.3 KB

configurations.md

File metadata and controls

654 lines (523 loc) · 28.3 KB

Oh-My-OpenCode Configuration

Highly opinionated, but adjustable to taste.

Config File Locations

Config file locations (priority order):

  1. .opencode/oh-my-opencode.json (project)
  2. User config (platform-specific):
Platform User Config Path
Windows ~/.config/opencode/oh-my-opencode.json (preferred) or %APPDATA%\opencode\oh-my-opencode.json (fallback)
macOS/Linux ~/.config/opencode/oh-my-opencode.json

Schema autocomplete supported:

{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json"
}

JSONC Support

The oh-my-opencode configuration file supports JSONC (JSON with Comments):

  • Line comments: // comment
  • Block comments: /* comment */
  • Trailing commas: { "key": "value", }

When both oh-my-opencode.jsonc and oh-my-opencode.json files exist, .jsonc takes priority.

Example with comments:

{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",

  /* Agent overrides - customize models for specific tasks */
  "agents": {
    "oracle": {
      "model": "openai/gpt-5.2"  // GPT for strategic reasoning
    },
    "explore": {
      "model": "opencode/grok-code"  // Free & fast for exploration
    },
  },
}

Google Auth

Recommended: For Google Gemini authentication, install the opencode-antigravity-auth plugin. It provides multi-account load balancing, more models (including Claude via Antigravity), and active maintenance. See Installation > Google Gemini.

Agents

Override built-in agent settings:

{
  "agents": {
    "explore": {
      "model": "anthropic/claude-haiku-4-5",
      "temperature": 0.5
    },
    "multimodal-looker": {
      "disable": true
    }
  }
}

Each agent supports: model, temperature, top_p, prompt, prompt_append, tools, disable, description, mode, color, permission.

Use prompt_append to add extra instructions without replacing the default system prompt:

{
  "agents": {
    "librarian": {
      "prompt_append": "Always use the elisp-dev-mcp for Emacs Lisp documentation lookups."
    }
  }
}

You can also override settings for Sisyphus (the main orchestrator) and build (the default agent) using the same options.

Permission Options

Fine-grained control over what agents can do:

{
  "agents": {
    "explore": {
      "permission": {
        "edit": "deny",
        "bash": "ask",
        "webfetch": "allow"
      }
    }
  }
}
Permission Description Values
edit File editing permission ask / allow / deny
bash Bash command execution ask / allow / deny or per-command: { "git": "allow", "rm": "deny" }
webfetch Web request permission ask / allow / deny
doom_loop Allow infinite loop detection override ask / allow / deny
external_directory Access files outside project root ask / allow / deny

Or disable via disabled_agents in ~/.config/opencode/oh-my-opencode.json or .opencode/oh-my-opencode.json:

{
  "disabled_agents": ["oracle", "multimodal-looker"]
}

Available agents: oracle, librarian, explore, multimodal-looker

Built-in Skills

Oh My OpenCode includes built-in skills that provide additional capabilities:

  • playwright: Browser automation with Playwright MCP. Use for web scraping, testing, screenshots, and browser interactions.
  • git-master: Git expert for atomic commits, rebase/squash, and history search (blame, bisect, log -S). STRONGLY RECOMMENDED: Use with delegate_task(category='quick', skills=['git-master'], ...) to save context.

Disable built-in skills via disabled_skills in ~/.config/opencode/oh-my-opencode.json or .opencode/oh-my-opencode.json:

{
  "disabled_skills": ["playwright"]
}

Available built-in skills: playwright, git-master

Git Master

Configure git-master skill behavior:

{
  "git_master": {
    "commit_footer": true,
    "include_co_authored_by": true
  }
}
Option Default Description
commit_footer true Adds "Ultraworked with Sisyphus" footer to commit messages.
include_co_authored_by true Adds Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai> trailer to commits.

Sisyphus Agent

When enabled (default), Sisyphus provides a powerful orchestrator with optional specialized agents:

  • Sisyphus: Primary orchestrator agent (Claude Opus 4.5)
  • OpenCode-Builder: OpenCode's default build agent, renamed due to SDK limitations (disabled by default)
  • Prometheus (Planner): OpenCode's default plan agent with work-planner methodology (enabled by default)
  • Metis (Plan Consultant): Pre-planning analysis agent that identifies hidden requirements and AI failure points

Configuration Options:

{
  "sisyphus_agent": {
    "disabled": false,
    "default_builder_enabled": false,
    "planner_enabled": true,
    "replace_plan": true
  }
}

Example: Enable OpenCode-Builder:

{
  "sisyphus_agent": {
    "default_builder_enabled": true
  }
}

This enables OpenCode-Builder agent alongside Sisyphus. The default build agent is always demoted to subagent mode when Sisyphus is enabled.

Example: Disable all Sisyphus orchestration:

{
  "sisyphus_agent": {
    "disabled": true
  }
}

You can also customize Sisyphus agents like other agents:

{
  "agents": {
    "Sisyphus": {
      "model": "anthropic/claude-sonnet-4",
      "temperature": 0.3
    },
    "OpenCode-Builder": {
      "model": "anthropic/claude-opus-4"
    },
    "Prometheus (Planner)": {
      "model": "openai/gpt-5.2"
    },
    "Metis (Plan Consultant)": {
      "model": "anthropic/claude-sonnet-4-5"
    }
  }
}
Option Default Description
disabled false When true, disables all Sisyphus orchestration and restores original build/plan as primary.
default_builder_enabled false When true, enables OpenCode-Builder agent (same as OpenCode build, renamed due to SDK limitations). Disabled by default.
planner_enabled true When true, enables Prometheus (Planner) agent with work-planner methodology. Enabled by default.
replace_plan true When true, demotes default plan agent to subagent mode. Set to false to keep both Prometheus (Planner) and default plan available.

Background Tasks

Configure concurrency limits for background agent tasks. This controls how many parallel background agents can run simultaneously.

{
  "background_task": {
    "defaultConcurrency": 5,
    "providerConcurrency": {
      "anthropic": 3,
      "openai": 5,
      "google": 10
    },
    "modelConcurrency": {
      "anthropic/claude-opus-4-5": 2,
      "google/gemini-3-flash": 10
    }
  }
}
Option Default Description
defaultConcurrency - Default maximum concurrent background tasks for all providers/models
providerConcurrency - Per-provider concurrency limits. Keys are provider names (e.g., anthropic, openai, google)
modelConcurrency - Per-model concurrency limits. Keys are full model names (e.g., anthropic/claude-opus-4-5). Overrides provider limits.

Priority Order: modelConcurrency > providerConcurrency > defaultConcurrency

Use Cases:

  • Limit expensive models (e.g., Opus) to prevent cost spikes
  • Allow more concurrent tasks for fast/cheap models (e.g., Gemini Flash)
  • Respect provider rate limits by setting provider-level caps

Categories

Categories enable domain-specific task delegation via the delegate_task tool. Each category applies runtime presets (model, temperature, prompt additions) when calling the Sisyphus-Junior agent.

Default Categories:

Category Model Description
visual google/gemini-3-pro-preview Frontend, UI/UX, design-focused tasks. High creativity (temp 0.7).
business-logic openai/gpt-5.2 Backend logic, architecture, strategic reasoning. Low creativity (temp 0.1).

Usage:

// Via delegate_task tool
delegate_task(category="visual", prompt="Create a responsive dashboard component")
delegate_task(category="business-logic", prompt="Design the payment processing flow")

// Or target a specific agent directly
delegate_task(agent="oracle", prompt="Review this architecture")

Custom Categories:

Add custom categories in oh-my-opencode.json:

{
  "categories": {
    "data-science": {
      "model": "anthropic/claude-sonnet-4-5",
      "temperature": 0.2,
      "prompt_append": "Focus on data analysis, ML pipelines, and statistical methods."
    },
    "visual": {
      "model": "google/gemini-3-pro-preview",
      "prompt_append": "Use shadcn/ui components and Tailwind CSS."
    }
  }
}

Each category supports: model, temperature, top_p, maxTokens, thinking, reasoningEffort, textVerbosity, tools, prompt_append.

Model Selection System

The installer automatically configures optimal models based on your subscriptions. This section explains how models are selected for each agent and category.

Overview

Problem: Users have different subscription combinations (Claude, OpenAI, Gemini, etc.). The system needs to automatically select the best available model for each task.

Solution: A tiered fallback system that:

  1. Prioritizes native provider subscriptions (Claude, OpenAI, Gemini)
  2. Falls back through alternative providers in priority order
  3. Applies capability-specific logic (e.g., Oracle prefers GPT, visual tasks prefer Gemini)

Provider Priority

┌─────────────────────────────────────────────────────────────────┐
│                     MODEL SELECTION FLOW                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   ┌─────────────────────────────────────────────────────────┐   │
│   │              TIER 1: NATIVE PROVIDERS                   │   │
│   │         (Your direct subscriptions)                     │   │
│   │                                                         │   │
│   │   Claude (anthropic/) ──► OpenAI (openai/) ──► Gemini   │   │
│   │         │                      │              (google/) │   │
│   │         ▼                      ▼                   │    │   │
│   │   Opus/Sonnet/Haiku    GPT-5.2/Codex      Gemini 3 Pro │   │
│   └─────────────────────────────────────────────────────────┘   │
│                              │                                  │
│                              ▼ (if no native available)         │
│   ┌─────────────────────────────────────────────────────────┐   │
│   │              TIER 2: OPENCODE ZEN                       │   │
│   │         (opencode/ prefix models)                       │   │
│   │                                                         │   │
│   │   opencode/claude-opus-4-5, opencode/gpt-5.2, etc.      │   │
│   └─────────────────────────────────────────────────────────┘   │
│                              │                                  │
│                              ▼ (if no OpenCode Zen)             │
│   ┌─────────────────────────────────────────────────────────┐   │
│   │              TIER 3: GITHUB COPILOT                     │   │
│   │         (github-copilot/ prefix models)                 │   │
│   │                                                         │   │
│   │   github-copilot/claude-opus-4.5, etc.                  │   │
│   └─────────────────────────────────────────────────────────┘   │
│                              │                                  │
│                              ▼ (if no Copilot)                  │
│   ┌─────────────────────────────────────────────────────────┐   │
│   │              TIER 4: Z.AI CODING PLAN                   │   │
│   │         (zai-coding-plan/ prefix models)                │   │
│   │                                                         │   │
│   │   zai-coding-plan/glm-4.7 (GLM models only)             │   │
│   └─────────────────────────────────────────────────────────┘   │
│                              │                                  │
│                              ▼ (ultimate fallback)              │
│   ┌─────────────────────────────────────────────────────────┐   │
│   │              FALLBACK: FREE TIER                        │   │
│   │                                                         │   │
│   │   opencode/glm-4.7-free                                 │   │
│   └─────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Native Tier Cross-Fallback

Within the Native tier, models fall back based on capability requirements:

Capability 1st Choice 2nd Choice 3rd Choice
High-tier tasks (Sisyphus, Atlas) Claude Opus OpenAI GPT-5.2 Gemini 3 Pro
Standard tasks Claude Sonnet OpenAI GPT-5.2 Gemini 3 Flash
Quick tasks Claude Haiku OpenAI GPT-5.1-mini Gemini 3 Flash
Deep reasoning (Oracle) OpenAI GPT-5.2-Codex Claude Opus Gemini 3 Pro
Visual/UI tasks Gemini 3 Pro OpenAI GPT-5.2 Claude Sonnet
Writing tasks Gemini 3 Flash OpenAI GPT-5.2 Claude Sonnet

Agent-Specific Rules

Standard Agents

Agent Capability Example (Claude + OpenAI + Gemini)
Sisyphus High-tier (isMax20) or Standard anthropic/claude-opus-4-5 or anthropic/claude-sonnet-4-5
Oracle Deep reasoning openai/gpt-5.2-codex
Prometheus High-tier/Standard Same as Sisyphus
Metis High-tier/Standard Same as Sisyphus
Momus Deep reasoning openai/gpt-5.2-codex
Atlas High-tier/Standard Same as Sisyphus
multimodal-looker Visual google/gemini-3-pro-preview

Special Case: explore Agent

The explore agent has unique logic for cost optimization:

┌────────────────────────────────────────┐
│           EXPLORE AGENT LOGIC          │
├────────────────────────────────────────┤
│                                        │
│   Has Claude + isMax20?                │
│         │                              │
│    YES  │  NO                          │
│    ▼    │  ▼                           │
│ ┌──────┐│┌────────────────────┐        │
│ │Haiku ││ │ opencode/grok-code │        │
│ │4.5   │││ (free & fast)       │        │
│ └──────┘│└────────────────────┘        │
│                                        │
│ Rationale:                             │
│ • max20 users want to use Claude quota │
│ • Others save quota with free grok     │
└────────────────────────────────────────┘

Special Case: librarian Agent

The librarian agent prioritizes Z.ai when available:

┌────────────────────────────────────────┐
│          LIBRARIAN AGENT LOGIC         │
├────────────────────────────────────────┤
│                                        │
│   Has Z.ai Coding Plan?                │
│         │                              │
│    YES  │  NO                          │
│    ▼    │  ▼                           │
│ ┌──────────────┐ ┌──────────────────┐  │
│ │zai-coding-   │ │ Normal fallback  │  │
│ │plan/glm-4.7  │ │ chain applies    │  │
│ └──────────────┘ └──────────────────┘  │
│                                        │
│ Rationale:                             │
│ • GLM excels at documentation tasks    │
│ • Z.ai provides dedicated GLM access   │
└────────────────────────────────────────┘

Category-Specific Rules

Categories follow the same fallback logic as agents:

Category Primary Capability Fallback Chain
visual-engineering Visual Gemini → OpenAI → Claude
ultrabrain Deep reasoning OpenAI → Claude → Gemini
artistry Visual/Creative Gemini → OpenAI → Claude
quick Quick tasks Claude Haiku → OpenAI mini → Gemini Flash
unspecified-low Standard Claude Sonnet → OpenAI → Gemini Flash
unspecified-high High-tier Claude Opus → OpenAI → Gemini Pro
writing Writing Gemini Flash → OpenAI → Claude

Subscription Scenarios

Scenario 1: Claude Only (Standard Plan)

// User has: Claude Pro (not max20)
{
  "agents": {
    "Sisyphus": { "model": "anthropic/claude-sonnet-4-5" },
    "oracle": { "model": "anthropic/claude-opus-4-5" },
    "explore": { "model": "opencode/grok-code" },
    "librarian": { "model": "opencode/glm-4.7-free" }
  }
}

Scenario 2: Claude Only (Max20 Plan)

// User has: Claude Max (max20 mode)
{
  "agents": {
    "Sisyphus": { "model": "anthropic/claude-opus-4-5" },
    "oracle": { "model": "anthropic/claude-opus-4-5" },
    "explore": { "model": "anthropic/claude-haiku-4-5" },
    "librarian": { "model": "opencode/glm-4.7-free" }
  }
}

Scenario 3: ChatGPT Only

// User has: OpenAI/ChatGPT Plus only
{
  "agents": {
    "Sisyphus": { "model": "openai/gpt-5.2" },
    "oracle": { "model": "openai/gpt-5.2-codex" },
    "explore": { "model": "opencode/grok-code" },
    "multimodal-looker": { "model": "openai/gpt-5.2" },
    "librarian": { "model": "opencode/glm-4.7-free" }
  }
}

Scenario 4: Full Stack (Claude + OpenAI + Gemini)

// User has: All native providers
{
  "agents": {
    "Sisyphus": { "model": "anthropic/claude-opus-4-5" },
    "oracle": { "model": "openai/gpt-5.2-codex" },
    "explore": { "model": "anthropic/claude-haiku-4-5" },
    "multimodal-looker": { "model": "google/gemini-3-pro-preview" },
    "librarian": { "model": "opencode/glm-4.7-free" }
  }
}

Scenario 5: GitHub Copilot Only

// User has: GitHub Copilot only (no native providers)
{
  "agents": {
    "Sisyphus": { "model": "github-copilot/claude-sonnet-4.5" },
    "oracle": { "model": "github-copilot/gpt-5.2-codex" },
    "explore": { "model": "opencode/grok-code" },
    "librarian": { "model": "github-copilot/gpt-5.2" }
  }
}

isMax20 Flag Impact

The isMax20 flag (Claude Max 20x mode) affects high-tier task model selection:

isMax20 High-tier Capability Result
true Uses unspecified-high Opus-class models
false Uses unspecified-low Sonnet-class models

Affected agents: Sisyphus, Prometheus, Metis, Atlas

Why?: Max20 users have 20x more Claude usage, so they can afford Opus for orchestration. Standard users should conserve quota with Sonnet.

Manual Override

You can always override automatic selection in oh-my-opencode.json:

{
  "agents": {
    "Sisyphus": {
      "model": "anthropic/claude-sonnet-4-5"  // Force specific model
    },
    "oracle": {
      "model": "openai/o3"  // Use different model
    }
  },
  "categories": {
    "visual-engineering": {
      "model": "anthropic/claude-opus-4-5"  // Override category default
    }
  }
}

Hooks

Disable specific built-in hooks via disabled_hooks in ~/.config/opencode/oh-my-opencode.json or .opencode/oh-my-opencode.json:

{
  "disabled_hooks": ["comment-checker", "agent-usage-reminder"]
}

Available hooks: todo-continuation-enforcer, context-window-monitor, session-recovery, session-notification, comment-checker, grep-output-truncator, tool-output-truncator, directory-agents-injector, directory-readme-injector, empty-task-response-detector, think-mode, anthropic-context-window-limit-recovery, rules-injector, background-notification, auto-update-checker, startup-toast, keyword-detector, agent-usage-reminder, non-interactive-env, interactive-bash-session, compaction-context-injector, thinking-block-validator, claude-code-hooks, ralph-loop, preemptive-compaction

Note on auto-update-checker and startup-toast: The startup-toast hook is a sub-feature of auto-update-checker. To disable only the startup toast notification while keeping update checking enabled, add "startup-toast" to disabled_hooks. To disable all update checking features (including the toast), add "auto-update-checker" to disabled_hooks.

MCPs

Exa, Context7 and grep.app MCP enabled by default.

  • websearch: Real-time web search powered by Exa AI - searches the web and returns relevant content
  • context7: Fetches up-to-date official documentation for libraries
  • grep_app: Ultra-fast code search across millions of public GitHub repositories via grep.app

Don't want them? Disable via disabled_mcps in ~/.config/opencode/oh-my-opencode.json or .opencode/oh-my-opencode.json:

{
  "disabled_mcps": ["websearch", "context7", "grep_app"]
}

LSP

OpenCode provides LSP tools for analysis. Oh My OpenCode adds refactoring tools (rename, code actions). All OpenCode LSP configs and custom settings (from opencode.json) are supported, plus additional Oh My OpenCode-specific settings.

Add LSP servers via the lsp option in ~/.config/opencode/oh-my-opencode.json or .opencode/oh-my-opencode.json:

{
  "lsp": {
    "typescript-language-server": {
      "command": ["typescript-language-server", "--stdio"],
      "extensions": [".ts", ".tsx"],
      "priority": 10
    },
    "pylsp": {
      "disabled": true
    }
  }
}

Each server supports: command, extensions, priority, env, initialization, disabled.

Experimental

Opt-in experimental features that may change or be removed in future versions. Use with caution.

{
  "experimental": {
    "truncate_all_tool_outputs": true,
    "aggressive_truncation": true,
    "auto_resume": true
  }
}
Option Default Description
truncate_all_tool_outputs false Truncates ALL tool outputs instead of just whitelisted tools (Grep, Glob, LSP, AST-grep). Tool output truncator is enabled by default - disable via disabled_hooks.
aggressive_truncation false When token limit is exceeded, aggressively truncates tool outputs to fit within limits. More aggressive than the default truncation behavior. Falls back to summarize/revert if insufficient.
auto_resume false Automatically resumes session after successful recovery from thinking block errors or thinking disabled violations. Extracts the last user message and continues.

Warning: These features are experimental and may cause unexpected behavior. Enable only if you understand the implications.

Environment Variables

Variable Description
OPENCODE_CONFIG_DIR Override the OpenCode configuration directory. Useful for profile isolation with tools like OCX ghost mode.