luna/oh-my-opencode
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
241224f7ab892e35ea19806c526fc5bd87e536bb
oh-my-opencode/docs/reference/configuration.md
T
Ravi Tharuma 241224f7ab docs(config): document object-style fallback_models
2026-03-26 18:55:22 +01:00

34 KiB
Raw Blame History

Configuration Reference

Complete reference for oh-my-openagent.jsonc configuration. This document covers every available option with examples.

Table of Contents

Getting Started

File Locations

Priority order (project overrides user):

  1. .opencode/oh-my-openagent.jsonc / .opencode/oh-my-openagent.json
  2. User config (.jsonc preferred over .json):
Platform Path
macOS/Linux ~/.config/opencode/oh-my-openagent.jsonc
Windows %APPDATA%\opencode\oh-my-openagent.jsonc

JSONC supports // line comments, /* block comments */, and trailing commas.

Enable schema autocomplete:

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

Run bunx oh-my-openagent install for guided setup. Run opencode models to list available models.

Quick Start Example

Here's a practical starting configuration:

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

  "agents": {
    // Main orchestrator: Claude Opus or Kimi K2.5 work best
    "sisyphus": {
      "model": "kimi-for-coding/k2p5",
      "ultrawork": { "model": "anthropic/claude-opus-4-6", "variant": "max" },
    },

    // Research agents: cheap fast models are fine
    "librarian": { "model": "google/gemini-3-flash" },
    "explore": { "model": "github-copilot/grok-code-fast-1" },

    // Architecture consultation: GPT-5.4 or Claude Opus
    "oracle": { "model": "openai/gpt-5.4", "variant": "high" },

    // Prometheus inherits sisyphus model; just add prompt guidance
    "prometheus": {
      "prompt_append": "Leverage deep & quick agents heavily, always in parallel.",
    },
  },

  "categories": {
    // quick — trivial tasks
    "quick": { "model": "opencode/gpt-5-nano" },

    // unspecified-low — moderate tasks
    "unspecified-low": { "model": "anthropic/claude-sonnet-4-6" },

    // unspecified-high — complex work
    "unspecified-high": { "model": "anthropic/claude-opus-4-6", "variant": "max" },

    // writing — docs/prose
    "writing": { "model": "google/gemini-3-flash" },

    // visual-engineering — Gemini dominates visual tasks
    "visual-engineering": {
      "model": "google/gemini-3.1-pro",
      "variant": "high",
    },

    // Custom category for git operations
    "git": {
      "model": "opencode/gpt-5-nano",
      "description": "All git operations",
      "prompt_append": "Focus on atomic commits, clear messages, and safe operations.",
    },
  },

  // Limit expensive providers; let cheap ones run freely
  "background_task": {
    "providerConcurrency": {
      "anthropic": 3,
      "openai": 3,
      "opencode": 10,
      "zai-coding-plan": 10,
    },
    "modelConcurrency": {
      "anthropic/claude-opus-4-6": 2,
      "opencode/gpt-5-nano": 20,
    },
  },

  "experimental": { "aggressive_truncation": true, "task_system": true },
  "tmux": { "enabled": false },
}

Core Concepts

Agents

Override built-in agent settings. Available agents: sisyphus, hephaestus, prometheus, oracle, librarian, explore, multimodal-looker, metis, momus, atlas.

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

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

Agent Options

Option Type Description
model string Model override (provider/model)
fallback_models string|array Fallback models on API errors. Supports strings or mixed arrays of strings and object entries with per-model settings.
temperature number Sampling temperature
top_p number Top-p sampling
prompt string Replace system prompt
prompt_append string Append to system prompt
tools array Allowed tools list
disable boolean Disable this agent
mode string Agent mode
color string UI color
permission object Per-tool permissions (see below)
category string Inherit model from category
variant string Model variant: max, high, medium, low, xhigh
maxTokens number Max response tokens
thinking object Anthropic extended thinking
reasoningEffort string OpenAI reasoning: low, medium, high, xhigh
textVerbosity string Text verbosity: low, medium, high
providerOptions object Provider-specific options

Anthropic Extended Thinking

{
  "agents": {
    "oracle": { "thinking": { "type": "enabled", "budgetTokens": 200000 } }
  }
}

Agent Permissions

Control what tools an agent can use:

{
  "agents": {
    "explore": {
      "permission": {
        "edit": "deny",
        "bash": "ask",
        "webfetch": "allow"
      }
    }
  }
}
Permission Values
edit ask / allow / deny
bash ask / allow / deny or per-command: { "git": "allow", "rm": "deny" }
webfetch ask / allow / deny
doom_loop ask / allow / deny
external_directory ask / allow / deny

Categories

Domain-specific model delegation used by the task() tool. When Sisyphus delegates work, it picks a category, not a model name.

Built-in Categories

Category Default Model Description
visual-engineering google/gemini-3.1-pro (high) Frontend, UI/UX, design, animation
ultrabrain openai/gpt-5.4 (xhigh) Deep logical reasoning, complex architecture
deep openai/gpt-5.3-codex (medium) Autonomous problem-solving, thorough research
artistry google/gemini-3.1-pro (high) Creative/unconventional approaches
quick openai/gpt-5.4-mini Trivial tasks, typo fixes, single-file changes
unspecified-low anthropic/claude-sonnet-4-6 General tasks, low effort
unspecified-high anthropic/claude-opus-4-6 (max) General tasks, high effort
writing google/gemini-3-flash Documentation, prose, technical writing

Note

: Built-in defaults only apply if the category is present in your config. Otherwise the system default model is used.

Category Options

Option Type Default Description
model string - Model override
fallback_models string|array - Fallback models on API errors. Supports strings or mixed arrays of strings and object entries with per-model settings.
temperature number - Sampling temperature
top_p number - Top-p sampling
maxTokens number - Max response tokens
thinking object - Anthropic extended thinking
reasoningEffort string - OpenAI reasoning effort
textVerbosity string - Text verbosity
tools array - Allowed tools
prompt_append string - Append to system prompt
variant string - Model variant
description string - Shown in task() tool prompt
is_unstable_agent boolean false Force background mode + monitoring. Auto-enabled for Gemini models.

Disable categories: { "disabled_categories": ["ultrabrain"] }

Model Resolution

3-step priority at runtime:

  1. User override — model set in config → used exactly as-is
  2. Provider fallback chain — tries each provider in priority order until available
  3. System default — falls back to OpenCode's configured default model

Agent Provider Chains

Agent Default Model Provider Priority
Sisyphus claude-opus-4-6 claude-opus-4-6 → glm-5 → big-pickle
Hephaestus gpt-5.3-codex gpt-5.3-codex → gpt-5.4 (GitHub Copilot fallback)
oracle gpt-5.4 gpt-5.4 → gemini-3.1-pro → claude-opus-4-6
librarian gemini-3-flash gemini-3-flash → minimax-m2.5-free → big-pickle
explore grok-code-fast-1 grok-code-fast-1 → minimax-m2.5-free → claude-haiku-4-5 → gpt-5-nano
multimodal-looker gpt-5.3-codex gpt-5.3-codex → k2p5 → gemini-3-flash → glm-4.6v → gpt-5-nano
Prometheus claude-opus-4-6 claude-opus-4-6 → gpt-5.4 → gemini-3.1-pro
Metis claude-opus-4-6 claude-opus-4-6 → gpt-5.4 → gemini-3.1-pro
Momus gpt-5.4 gpt-5.4 → claude-opus-4-6 → gemini-3.1-pro
Atlas claude-sonnet-4-6 claude-sonnet-4-6 → gpt-5.4

Category Provider Chains

Category Default Model Provider Priority
visual-engineering gemini-3.1-pro gemini-3.1-pro → glm-5 → claude-opus-4-6
ultrabrain gpt-5.4 gpt-5.4 → gemini-3.1-pro → claude-opus-4-6
deep gpt-5.3-codex gpt-5.3-codex → claude-opus-4-6 → gemini-3.1-pro
artistry gemini-3.1-pro gemini-3.1-pro → claude-opus-4-6 → gpt-5.4
quick gpt-5.4-mini gpt-5.4-mini → claude-haiku-4-5 → gemini-3-flash → minimax-m2.5 → gpt-5-nano
unspecified-low claude-sonnet-4-6 claude-sonnet-4-6 → gpt-5.3-codex → gemini-3-flash
unspecified-high claude-opus-4-6 claude-opus-4-6 → gpt-5.4 (high) → glm-5 → k2p5 → kimi-k2.5
writing gemini-3-flash gemini-3-flash → claude-sonnet-4-6

Run bunx oh-my-openagent doctor --verbose to see effective model resolution for your config.

Task System

Background Tasks

Control parallel agent execution and concurrency limits.

{
  "background_task": {
    "defaultConcurrency": 5,
    "staleTimeoutMs": 180000,
    "providerConcurrency": { "anthropic": 3, "openai": 5, "google": 10 },
    "modelConcurrency": { "anthropic/claude-opus-4-6": 2 }
  }
}
Option Default Description
defaultConcurrency - Max concurrent tasks (all providers)
staleTimeoutMs 180000 Interrupt tasks with no activity (min: 60000)
providerConcurrency - Per-provider limits (key = provider name)
modelConcurrency - Per-model limits (key = provider/model). Overrides provider limits.

Priority: modelConcurrency > providerConcurrency > defaultConcurrency

Sisyphus Agent

Configure the main orchestration system.

{
  "sisyphus_agent": {
    "disabled": false,
    "default_builder_enabled": false,
    "planner_enabled": true,
    "replace_plan": true
  }
}
Option Default Description
disabled false Disable all Sisyphus orchestration, restore original build/plan
default_builder_enabled false Enable OpenCode-Builder agent (off by default)
planner_enabled true Enable Prometheus (Planner) agent
replace_plan true Demote default plan agent to subagent mode

Sisyphus agents can also be customized under agents using their names: Sisyphus, OpenCode-Builder, Prometheus (Planner), Metis (Plan Consultant).

Sisyphus Tasks

Enable the Sisyphus Tasks system for cross-session task tracking.

{
  "sisyphus": {
    "tasks": {
      "enabled": false,
      "storage_path": ".sisyphus/tasks",
      "claude_code_compat": false
    }
  }
}
Option Default Description
enabled false Enable Sisyphus Tasks system
storage_path .sisyphus/tasks Storage path (relative to project root)
claude_code_compat false Enable Claude Code path compatibility mode

Features

Skills

Skills bring domain-specific expertise and embedded MCPs.

Built-in skills: playwright, playwright-cli, agent-browser, dev-browser, git-master, frontend-ui-ux

Disable built-in skills: { "disabled_skills": ["playwright"] }

Skills Configuration

{
  "skills": {
    "sources": [
      { "path": "./my-skills", "recursive": true },
      "https://example.com/skill.yaml"
    ],
    "enable": ["my-skill"],
    "disable": ["other-skill"],
    "my-skill": {
      "description": "What it does",
      "template": "Custom prompt template",
      "from": "source-file.ts",
      "model": "custom/model",
      "agent": "custom-agent",
      "subtask": true,
      "argument-hint": "usage hint",
      "license": "MIT",
      "compatibility": ">= 3.0.0",
      "metadata": { "author": "Your Name" },
      "allowed-tools": ["read", "bash"]
    }
  }
}
sources option Default Description
path - Local path or remote URL
recursive false Recurse into subdirectories
glob - Glob pattern for file selection

Hooks

Disable built-in hooks via disabled_hooks:

{ "disabled_hooks": ["comment-checker"] }

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, auto-slash-command, sisyphus-junior-notepad, no-sisyphus-gpt, start-work, runtime-fallback

Notes:

  • directory-agents-injector — auto-disabled on OpenCode 1.1.37+ (native AGENTS.md support)
  • no-sisyphus-gpt — do not disable. It blocks incompatible GPT models for Sisyphus while allowing the dedicated GPT-5.4 prompt path.
  • startup-toast is a sub-feature of auto-update-checker. Disable just the toast by adding startup-toast to disabled_hooks.

Commands

Disable built-in commands via disabled_commands:

{ "disabled_commands": ["init-deep", "start-work"] }

Available commands: init-deep, ralph-loop, ulw-loop, cancel-ralph, refactor, start-work, stop-continuation, handoff

Browser Automation

Provider Interface Installation
playwright (default) MCP tools Auto-installed via npx
agent-browser Bash CLI bun add -g agent-browser && agent-browser install

Switch provider:

{ "browser_automation_engine": { "provider": "agent-browser" } }

Tmux Integration

Run background subagents in separate tmux panes. Requires running inside tmux with opencode --port <port>.

{
  "tmux": {
    "enabled": true,
    "layout": "main-vertical",
    "main_pane_size": 60,
    "main_pane_min_width": 120,
    "agent_pane_min_width": 40
  }
}
Option Default Description
enabled false Enable tmux pane spawning
layout main-vertical main-vertical / main-horizontal / tiled / even-horizontal / even-vertical
main_pane_size 60 Main pane % (20–80)
main_pane_min_width 120 Min main pane columns
agent_pane_min_width 40 Min agent pane columns

Git Master

Configure git commit behavior:

{ "git_master": { "commit_footer": true, "include_co_authored_by": true } }

Comment Checker

Customize the comment quality checker:

{
  "comment_checker": {
    "custom_prompt": "Your message. Use {{comments}} placeholder."
  }
}

Notification

Force-enable session notifications:

{ "notification": { "force_enable": true } }

force_enable (false) — force session-notification even if external notification plugins are detected.

MCPs

Built-in MCPs (enabled by default): websearch (Exa AI), context7 (library docs), grep_app (GitHub code search).

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

LSP

Configure Language Server Protocol integration:

{
  "lsp": {
    "typescript-language-server": {
      "command": ["typescript-language-server", "--stdio"],
      "extensions": [".ts", ".tsx"],
      "priority": 10,
      "env": { "NODE_OPTIONS": "--max-old-space-size=4096" },
      "initialization": {
        "preferences": { "includeInlayParameterNameHints": "all" }
      }
    },
    "pylsp": { "disabled": true }
  }
}
Option Type Description
command array Command to start LSP server
extensions array File extensions (e.g. [".ts"])
priority number Priority when multiple servers match
env object Environment variables
initialization object Init options passed to server
disabled boolean Disable this server

Advanced

Runtime Fallback

Auto-switches to backup models on API errors.

Simple configuration (enable/disable with defaults):

{ "runtime_fallback": true }
{ "runtime_fallback": false }

Advanced configuration (full control):

{
  "runtime_fallback": {
    "enabled": true,
    "retry_on_errors": [400, 429, 503, 529],
    "max_fallback_attempts": 3,
    "cooldown_seconds": 60,
    "timeout_seconds": 30,
    "notify_on_fallback": true
  }
}
Option Default Description
enabled false Enable runtime fallback
retry_on_errors [400,429,503,529] HTTP codes that trigger fallback. Also handles classified provider key errors.
max_fallback_attempts 3 Max fallback attempts per session (1–20)
cooldown_seconds 60 Seconds before retrying a failed model
timeout_seconds 30 Seconds before forcing next fallback. Set to 0 to disable timeout-based escalation and provider retry message detection.
notify_on_fallback true Toast notification on model switch

Define fallback_models per agent or category:

{
  "agents": {
    "sisyphus": {
      "model": "anthropic/claude-opus-4-6",
      "fallback_models": [
        "openai/gpt-5.4",
        {
          "model": "google/gemini-3.1-pro",
          "variant": "high"
        }
      ]
    }
  }
}

fallback_models also supports object-style entries so you can attach settings to a specific fallback model:

{
  "agents": {
    "sisyphus": {
      "model": "anthropic/claude-opus-4-6",
      "fallback_models": [
        "openai/gpt-5.4",
        {
          "model": "anthropic/claude-sonnet-4-6",
          "variant": "high",
          "thinking": { "type": "enabled", "budgetTokens": 12000 }
        },
        {
          "model": "openai/gpt-5.3-codex",
          "reasoningEffort": "high",
          "temperature": 0.2,
          "top_p": 0.95,
          "maxTokens": 8192
        }
      ]
    }
  }
}

Mixed arrays are allowed, so string entries and object entries can appear together in the same fallback chain.

Object-style fallback_models

Object entries use the following shape:

Field Type Description
model string Fallback model ID. Provider prefix is optional when OmO can inherit the current/default provider.
variant string Explicit variant override for this fallback entry.
reasoningEffort string OpenAI reasoning effort override for this fallback entry.
temperature number Temperature applied if this fallback model becomes active.
top_p number Top-p applied if this fallback model becomes active.
maxTokens number Max response tokens applied if this fallback model becomes active.
thinking object Anthropic thinking config applied if this fallback model becomes active.

Per-model settings are fallback-only. They are promoted only when that specific fallback model is actually selected, so they do not override your primary model settings when the primary model resolves successfully.

thinking uses the same shape as the normal agent/category option:

Field Type Description
type string enabled or disabled
budgetTokens number Optional Anthropic thinking budget

Object entries can also omit the provider prefix when OmO can infer it from the current/default provider. If you provide both inline variant syntax in model and an explicit variant field, the explicit variant field wins.

Full examples

1. Simple string chain

Use strings when you only need an ordered fallback chain:

{
  "agents": {
    "atlas": {
      "model": "anthropic/claude-sonnet-4-6",
      "fallback_models": [
        "anthropic/claude-haiku-4-5",
        "openai/gpt-5.4",
        "google/gemini-3.1-pro"
      ]
    }
  }
}

2. Same-provider shorthand

If the primary model already establishes the provider, fallback entries can omit the prefix:

{
  "agents": {
    "atlas": {
      "model": "openai/gpt-5.4",
      "fallback_models": [
        "gpt-5.4-mini",
        {
          "model": "gpt-5.3-codex",
          "reasoningEffort": "medium",
          "maxTokens": 4096
        }
      ]
    }
  }
}

In this example OmO treats gpt-5.4-mini and gpt-5.3-codex as OpenAI fallback entries because the current/default provider is already openai.

3. Mixed cross-provider chain

Mix string entries and object entries when only some fallback models need special settings:

{
  "agents": {
    "sisyphus": {
      "model": "anthropic/claude-opus-4-6",
      "fallback_models": [
        "openai/gpt-5.4",
        {
          "model": "anthropic/claude-sonnet-4-6",
          "variant": "high",
          "thinking": { "type": "enabled", "budgetTokens": 12000 }
        },
        {
          "model": "google/gemini-3.1-pro",
          "variant": "high"
        }
      ]
    }
  }
}

4. Category-level fallback chain

fallback_models works the same way under categories:

{
  "categories": {
    "deep": {
      "model": "openai/gpt-5.3-codex",
      "fallback_models": [
        {
          "model": "openai/gpt-5.4",
          "reasoningEffort": "xhigh",
          "maxTokens": 12000
        },
        {
          "model": "anthropic/claude-opus-4-6",
          "variant": "max",
          "temperature": 0.2
        },
        "google/gemini-3.1-pro(high)"
      ]
    }
  }
}

5. Full object entry with every supported field

This shows every supported object-style parameter in one place:

{
  "agents": {
    "oracle": {
      "model": "openai/gpt-5.4",
      "fallback_models": [
        {
          "model": "openai/gpt-5.3-codex(low)",
          "variant": "xhigh",
          "reasoningEffort": "high",
          "temperature": 0.3,
          "top_p": 0.9,
          "maxTokens": 8192,
          "thinking": {
            "type": "disabled"
          }
        }
      ]
    }
  }
}

In this example the explicit "variant": "xhigh" overrides the inline (low) suffix in "model".

This final example is a complete shape reference. In real configs, prefer provider-appropriate settings:

  • use reasoningEffort for OpenAI reasoning models
  • use thinking for Anthropic thinking-capable models
  • use variant, temperature, top_p, and maxTokens only when that fallback model supports them

Hashline Edit

Replaces the built-in Edit tool with a hash-anchored version using LINE#ID references to prevent stale-line edits. Disabled by default.

{ "hashline_edit": true }

When enabled, two companion hooks are active: hashline-read-enhancer (annotates Read output) and hashline-edit-diff-enhancer (shows diffs). Opt-in by setting hashline_edit: true. Disable the companion hooks individually via disabled_hooks if needed.

Experimental

{
  "experimental": {
    "truncate_all_tool_outputs": false,
    "aggressive_truncation": false,
    "auto_resume": false,
    "disable_omo_env": false,
    "task_system": false,
    "dynamic_context_pruning": {
      "enabled": false,
      "notification": "detailed",
      "turn_protection": { "enabled": true, "turns": 3 },
      "protected_tools": [
        "task",
        "todowrite",
        "todoread",
        "lsp_rename",
        "session_read",
        "session_write",
        "session_search"
      ],
      "strategies": {
        "deduplication": { "enabled": true },
        "supersede_writes": { "enabled": true, "aggressive": false },
        "purge_errors": { "enabled": true, "turns": 5 }
      }
    }
  }
}
Option Default Description
truncate_all_tool_outputs false Truncate all tool outputs (not just whitelisted)
aggressive_truncation false Aggressively truncate when token limit exceeded
auto_resume false Auto-resume after thinking block recovery
disable_omo_env false Disable auto-injected <omo-env> block (date/time/locale). Improves cache hit rate.
task_system false Enable Sisyphus task system
dynamic_context_pruning.enabled false Auto-prune old tool outputs to manage context window
dynamic_context_pruning.notification detailed Pruning notifications: off / minimal / detailed
turn_protection.turns 3 Recent turns protected from pruning (1–10)
strategies.deduplication true Remove duplicate tool calls
strategies.supersede_writes true Prune write inputs when file later read
strategies.supersede_writes.aggressive false Prune any write if ANY subsequent read exists
strategies.purge_errors.turns 5 Turns before pruning errored tool inputs

Reference

Environment Variables

Variable Description
OPENCODE_CONFIG_DIR Override OpenCode config directory (useful for profile isolation)

Provider-Specific

Google Auth

Install opencode-antigravity-auth for Google Gemini. Provides multi-account load balancing, dual quota, and variant-based thinking.

Ollama

Must disable streaming to avoid JSON parse errors:

{
  "agents": {
    "explore": { "model": "ollama/qwen3-coder", "stream": false }
  }
}

Common models: ollama/qwen3-coder, ollama/ministral-3:14b, ollama/lfm2.5-thinking

See Ollama Troubleshooting for JSON Parse error: Unexpected EOF issues.

Reference in New Issue View Git Blame Copy Permalink