Configuration

Configuration

Opinionated defaults, adjustable if you insist.

Config File Locations

Level	Path	Priority
Project	.opencode/oh-my-openagent.json[c]	Highest
User	~/.config/opencode/oh-my-openagent.json[c]	Lower

The compatibility layer recognizes both oh-my-openagent.json[c] and legacy oh-my-opencode.json[c] filenames. Existing installs still commonly use the legacy basename.

JSONC is supported — comments and trailing commas work.

Agent Configuration

Override models, temperatures, prompts, and permissions for any agent:

{
  "agents": {
    "sisyphus": {
      "model": "claude-opus-4-6",
      "temperature": 0.7
    },
    "hephaestus": {
      "model": "gpt-5.4"
    },
    "prometheus": {
      "model": "claude-opus-4-6",
      "temperature": 0.6
    }
  }
}

Per-agent options:

• model — Which LLM to use
• temperature — Sampling temperature
• prompt_append — Additional instructions appended to agent’s system prompt
• system_prompt_override — Replace the entire system prompt
• max_tokens — Maximum response length
• file:// prompts — Load prompt text from files

Category Mapping

Sisyphus delegates by category. You can define custom categories that map to specific models:

{
  "categories": {
    "visual-engineering": { "model": "claude-opus-4-6" },
    "deep": { "model": "gpt-5.4" },
    "quick": { "model": "kimi-k2.5" },
    "ultrabrain": { "model": "gpt-5.4", "reasoning_effort": "xhigh" },
    "business-logic": { "model": "claude-opus-4-6" },
    "custom": { "model": "glm-5" }
  }
}

Built-in categories: visual-engineering, deep, quick, ultrabrain. Add any custom categories you need.

Model Fallbacks

Configure fallback models for reliability:

{
  "fallback_models": {
    "default": ["claude-opus-4-6", "kimi-k2.5"],
    "hephaestus": [
      "gpt-5.4",
      { "model": "claude-opus-4-6", "reasoning_effort": "high" }
    ]
  }
}

Mix plain model strings and per-fallback objects in the same array. The system tries each fallback in order until one succeeds.

Built-in Skills

Configure built-in skills:

Skill	Description	Default
playwright	Browser automation	Enabled
git-master	Atomic commits, rebase surgery	Enabled
frontend-ui-ux	Design-first UI	Enabled

Disable a skill:

{
  "skills": {
    "playwright": { "enabled": false }
  }
}

Add custom skills:

• Project-level: .opencode/skills/*/SKILL.md
• User-level: ~/.config/opencode/skills/*/SKILL.md

Hooks

25+ built-in hooks, all configurable. Disable specific hooks:

{
  "disabled_hooks": [
    "comment-checker",
    "auto-format"
  ]
}

Hooks run at various lifecycle points:

• Pre-task: Before agent execution
• Post-task: After agent completes
• On-error: When an error occurs
• On-agent-switch: When switching between agents

Built-in MCP Configuration

Three MCPs are always on by default:

MCP	Purpose	Configurable
websearch (Exa)	Web search	API key, search depth
context7	Official docs lookup	Enabled/disabled
grep_app (Grep.app)	GitHub code search	Enabled/disabled

Custom MCP servers can be added in the standard OpenCode MCP configuration format.

Background Task Concurrency

Control how many agents run in parallel:

{
  "background_tasks": {
    "max_concurrent": 5,
    "per_provider": {
      "anthropic": 3,
      "openai": 5,
      "google": 2
    }
  }
}

Adjust based on your API rate limits and subscription tier.

LSP Configuration

{
  "lsp": {
    "enabled": true,
    "servers": {
      "typescript": {
        "command": "typescript-language-server",
        "args": ["--stdio"]
      }
    }
  }
}

Experimental Features

{
  "experimental": {
    "aggressive_truncation": true,
    "auto_resume": true
  }
}

• aggressive_truncation — Truncate context more aggressively to stay within limits
• auto_resume — Automatically resume from errors and context window limits

Complete Configuration Example

{
  // Agent models
  "agents": {
    "sisyphus": {
      "model": "claude-opus-4-6",
      "temperature": 0.7
    },
    "hephaestus": {
      "model": "gpt-5.4"
    }
  },

  // Category routing
  "categories": {
    "visual-engineering": { "model": "claude-opus-4-6" },
    "deep": { "model": "gpt-5.4" },
    "quick": { "model": "kimi-k2.5" },
    "ultrabrain": { "model": "gpt-5.4", "reasoning_effort": "xhigh" }
  },

  // Fallback models
  "fallback_models": {
    "default": ["claude-opus-4-6", "kimi-k2.5"]
  },

  // Skills
  "skills": {
    "playwright": { "enabled": true },
    "git-master": { "enabled": true },
    "frontend-ui-ux": { "enabled": true }
  },

  // Hooks
  "disabled_hooks": [],

  // Background tasks
  "background_tasks": {
    "max_concurrent": 5,
    "per_provider": {
      "anthropic": 3,
      "openai": 5
    }
  },

  // LSP
  "lsp": {
    "enabled": true
  },

  // Experimental
  "experimental": {
    "aggressive_truncation": true,
    "auto_resume": true
  }
}

Validation

Run doctor to validate your configuration:

bunx oh-my-opencode doctor

This checks plugin registration, config syntax, model availability, and environment setup.

Next Steps

• Best Practices — Usage patterns and troubleshooting
• Features — All features reference