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
  • Model Capabilities
  • 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):

Rename compatibility: The published package and CLI binary remain oh-my-opencode. OpenCode plugin registration prefers oh-my-openagent, while legacy oh-my-opencode entries and config basenames still load during the transition. Config detection checks oh-my-opencode before oh-my-openagent, so 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-7", "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-7", "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-7": 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, sisyphus-junior.

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

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

Core agents receive an injected runtime order field for deterministic Tab cycling in the UI: Sisyphus = 1, Hephaestus = 2, Prometheus = 3, Atlas = 4. This is not a user-configurable config key.

Agent 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"
      }
    }
  }
}

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-7",
      "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. Category-level prompt_append supports the same URI forms.

{
  "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"
    }
  },
  "categories": {
    "custom": {
      "model": "anthropic/claude-sonnet-4-6",
      "prompt_append": "file://./category-context.md"
    }
  }
}

Paths can be absolute (file:///abs/path), relative to project root (file://./rel/path), or home-relative (file://~/home/path). If a file URI cannot be decoded, resolved, or read, OmO inserts a warning placeholder into the prompt instead of failing hard.

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

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

Category Options

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

Model Resolution

Runtime priority:

1. UI-selected model - model chosen in the OpenCode UI, for primary agents
2. User override - model set in config → used exactly as-is. Even on cold cache, explicit user configuration takes precedence over hardcoded fallback chains
3. Category default - model inherited from the assigned category config
4. User fallback_models - user-configured fallback list is tried before built-in fallback chains
5. Provider fallback chain - built-in provider/model chain from OmO source
6. System default - OpenCode's configured default model

Model Settings Compatibility

Model settings are compatibility-normalized against model capabilities instead of failing hard.

Normalized fields:

• variant - downgraded to the closest supported value
• reasoningEffort - downgraded to the closest supported value, or removed if unsupported
• temperature - removed if unsupported by the model metadata
• top_p - removed if unsupported by the model metadata
• maxTokens - capped to the model's reported max output limit
• thinking - removed if the target model does not support thinking

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

Capability data comes from provider runtime metadata first. OmO also ships bundled models.dev-backed capability data, supports a refreshable local models.dev cache, and falls back to heuristic family detection plus alias rules when exact metadata is unavailable. bunx oh-my-opencode doctor surfaces capability diagnostics and warns when a configured model relies on compatibility fallback.

Agent Provider Chains

Category Provider Chains

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-7": 2 }
  }
}

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
  }
}

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
    }
  }
}

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"]
    }
  }
}

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

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
  }
}

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 }
  }
}

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
  }
}

Define fallback_models per agent or category:

{
  "agents": {
    "sisyphus": {
      "model": "anthropic/claude-opus-4-7",
      "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-7",
      "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:

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:

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-7",
      "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-7",
          "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

Model Capabilities

OmO can refresh a local models.dev capability snapshot on startup. This cache is controlled by model_capabilities.

{
  "model_capabilities": {
    "enabled": true,
    "auto_refresh_on_start": true,
    "refresh_timeout_ms": 5000,
    "source_url": "https://models.dev/api.json"
  }
}

Notes:

• Startup refresh runs through the auto-update checker hook.
• Manual refresh is available via bunx oh-my-opencode refresh-model-capabilities.
• Provider runtime metadata still takes priority when OmO resolves capabilities for compatibility checks.

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": true,
    "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 }
      }
    }
  }
}

Reference

Environment Variables

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.