oh-my-openagent/docs/reference/configuration.md

Configuration Reference

Complete reference for Oh My OpenCode plugin configuration. During the rename transition, the runtime recognizes both oh-my-openagent.json[c] and legacy oh-my-opencode.json[c] files.

---

Table of Contents

• Getting Started
  • File Locations
  • Quick Start Example
• Core Concepts
  • Agents
  • Categories
  • Model Resolution
• Task System
  • Background Tasks
  • Sisyphus Agent
  • Sisyphus Tasks
• Features
  • Skills
  • Hooks
  • Commands
  • Browser Automation
  • Tmux Integration
  • Git Master
  • Comment Checker
  • Notification
  • MCPs
  • LSP
• Advanced
  • Runtime Fallback
  • Hashline Edit
  • Experimental
• Reference
  • Environment Variables
  • Provider-Specific

---

Getting Started

File Locations

User config is loaded first, then project config overrides it. In each directory, the compatibility layer recognizes both the renamed and legacy basenames.

1. Project config: .opencode/oh-my-openagent.json[c] or .opencode/oh-my-opencode.json[c]
2. User config (.jsonc preferred over .json):

Platform	Path candidates
macOS/Linux	~/.config/opencode/oh-my-openagent.json[c], ~/.config/opencode/oh-my-opencode.json[c]
Windows	%APPDATA%\opencode\oh-my-openagent.json[c], %APPDATA%\opencode\oh-my-opencode.json[c]

Rename compatibility: OpenCode plugin registration now prefers oh-my-openagent, while legacy oh-my-opencode entries and config basenames still load during the transition. If both plugin config basenames exist in the same directory, the legacy oh-my-opencode.* file currently wins. 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-opencode.schema.json"
}

Run bunx oh-my-opencode 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-opencode.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. Arrays can mix plain strings and per-model objects
temperature	number	Sampling temperature
top_p	number	Top-p sampling
prompt	string	Replace system prompt. Supports file:// URIs
prompt_append	string	Append to system prompt. Supports file:// URIs
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. Normalized to supported values
maxTokens	number	Max response tokens
thinking	object	Anthropic extended thinking
reasoningEffort	string	OpenAI reasoning: low, medium, high, xhigh. Normalized to supported values
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

Fallback Models with Per-Model Settings

fallback_models accepts either a single model string or an array. Array entries can be plain strings or objects with individual model settings:

{
  "agents": {
    "sisyphus": {
      "model": "anthropic/claude-opus-4-6",
      "fallback_models": [
        // Simple string fallback
        "openai/gpt-5.4",
        // Object with per-model settings
        {
          "model": "google/gemini-3.1-pro",
          "variant": "high",
          "temperature": 0.2
        },
        {
          "model": "anthropic/claude-sonnet-4-6",
          "thinking": { "type": "enabled", "budgetTokens": 64000 }
        }
      ]
    }
  }
}

Object entries support: model, variant, reasoningEffort, temperature, top_p, maxTokens, thinking.

File URIs for Prompts

Both prompt and prompt_append support loading content from files via file:// URIs:

{
  "agents": {
    "sisyphus": {
      "prompt_append": "file:///absolute/path/to/prompt.txt"
    },
    "oracle": {
      "prompt": "file://./relative/to/project/prompt.md"
    },
    "explore": {
      "prompt_append": "file://~/home/dir/prompt.txt"
    }
  }
}

Paths can be absolute (file:///abs/path), relative to project root (file://./rel/path), or home-relative (file://~/home/path).

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. Arrays can mix plain strings and per-model objects
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. Unsupported values are normalized
textVerbosity	string	-	Text verbosity
tools	array	-	Allowed tools
prompt_append	string	-	Append to system prompt
variant	string	-	Model variant. Unsupported values are normalized
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. Even on cold cache (first run without model availability data), explicit user configuration takes precedence over hardcoded fallback chains
2. Provider fallback chain - tries each provider in priority order until available
3. System default - falls back to OpenCode's configured default model

Model Settings Compatibility

variant and reasoningEffort values are automatically normalized to what each model supports. If you specify a variant or reasoning effort level that a model does not support, it is adjusted to the closest supported value rather than causing errors.

Examples:

• Claude models do not support reasoningEffort - it is removed automatically
• GPT-4.1 does not support reasoning - reasoningEffort is removed
• o-series models support none through high - xhigh is downgraded to high
• GPT-5 supports none, minimal, low, medium, high, xhigh - all pass through

Agent Provider Chains

Agent	Default Model	Provider Priority
Sisyphus	claude-opus-4-6	claude-opus-4-6 → glm-5 → big-pickle
Hephaestus	gpt-5.4	gpt-5.4
oracle	gpt-5.4	gpt-5.4 → gemini-3.1-pro → claude-opus-4-6
librarian	minimax-m2.7	opencode-go/minimax-m2.7 → opencode/minimax-m2.5 → claude-haiku-4-5 → gpt-5-nano
explore	grok-code-fast-1	grok-code-fast-1 → opencode-go/minimax-m2.7 → opencode/minimax-m2.5 → claude-haiku-4-5 → gpt-5-nano
multimodal-looker	gpt-5.4	gpt-5.4 → k2p5 → 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.7 → gpt-5-nano
unspecified-low	claude-sonnet-4-6	claude-sonnet-4-6 → gpt-5.3-codex → gemini-3-flash → minimax-m2.7
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 → minimax-m2.7

Run bunx oh-my-opencode 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.
• session-recovery - automatically recovers from recoverable session errors (missing tool results, unavailable tools, thinking block violations). Shows toast notifications during recovery. Enable experimental.auto_resume for automatic retry after recovery.

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", "google/gemini-3.1-pro"]
    }
  }
}

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.