Opencode Docs

OpenCode + OhMyOpenCode Reference

Quick Reference

Magic Words (OhMyOpenCode)

Config File Locations (Precedence: later overrides earlier)

1. Remote (.well-known/opencode)     - organizational defaults
2. ~/.config/opencode/opencode.json  - global user preferences
3. ./opencode.json                   - project-specific
4. .opencode/                        - agents, commands, plugins

OhMyOpenCode Config Locations

1. ~/.config/opencode/oh-my-opencode.json  - global
2. .opencode/oh-my-opencode.json           - project

Agents

Agents are specialized AI assistants with custom prompts, models, and tool access.

Agent Types

Built-in Primary Agents

Built-in Subagents

OhMyOpenCode Agents

Agent Definition Locations

~/.config/opencode/agent/*.md     - global agents
.opencode/agent/*.md              - project agents
~/.claude/agents/*.md             - Claude Code compat
.claude/agents/*.md               - Claude Code compat (project)

Creating Agents

Interactive CLI:

opencode agent create

This will ask where to save (global/project), description, generate prompt, select tools, and create the markdown file.

Manual - Markdown (recommended): Create ~/.config/opencode/agent/<name>.md:

---
description: Required - what this agent does (shown in @ menu)
mode: subagent           # primary | subagent | all (default: all)
model: anthropic/claude-sonnet-4-20250514
temperature: 0.3         # 0.0-1.0 (default: model-specific)
maxSteps: 10             # Optional: limit agentic iterations
disable: false           # Set true to disable
hidden: false            # Set true to hide from @ autocomplete (subagents only)
tools:
  write: false
  edit: false
  bash: false
  mymcp_*: false         # Wildcards supported
permission:
  edit: deny             # allow | deny | ask
  bash:
    "*": ask             # Default for all commands
    "git status": allow  # Specific command override
    "rm -rf *": deny     # Last matching rule wins
  task:                  # Control which subagents this agent can invoke
    "*": deny
    "code-reviewer": ask
    "my-helper-*": allow
---

System prompt goes here.
You can include:
- Detailed instructions
- Code examples
- Behavioral guidelines

Manual - JSON (opencode.json):

{
  "agent": {
    "my-agent": {
      "description": "Required description",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "temperature": 0.3,
      "maxSteps": 10,
      "tools": { "write": false, "edit": false },
      "permission": { 
        "edit": "deny",
        "bash": { "*": "ask", "git *": "allow" }
      },
      "prompt": "{file:./prompts/my-agent.txt}"
    }
  }
}

Configuration Options Reference

Temperature Guidelines

• 0.0-0.2: Deterministic, ideal for code analysis and planning
• 0.3-0.5: Balanced, good for general development
• 0.6-1.0: Creative, useful for brainstorming

OhMyOpenCode Agent Override (oh-my-opencode.json)

{
  "agents": {
    "oracle": { "model": "openai/gpt-5.2" },
    "explore": { "model": "anthropic/claude-haiku-4-5" },
    "frontend-ui-ux-engineer": { "disable": true }
  },
  "disabled_agents": ["oracle", "frontend-ui-ux-engineer"]
}

Usage

Switch primary agents: Tab key or switch_agent keybind

Invoke subagents: @agent-name your request here

Navigate sessions: When subagents create child sessions:

• <Leader>+Right - cycle forward through parent → children
• <Leader>+Left - cycle backward

Tools

Built-in Tools

OhMyOpenCode Additional Tools

Tool Permissions

{
  "permission": {
    "edit": "allow",        // allow | deny | ask
    "bash": "ask",
    "webfetch": "deny",
    "bash": {               // Per-command
      "*": "ask",
      "git status": "allow",
      "rm -rf": "deny"
    }
  }
}

Disable Tools Globally

{
  "tools": {
    "write": false,
    "mymcp_*": false
  }
}

MCP Servers

Config Location

// opencode.json
{
  "mcp": {
    "server-name": { ... }
  }
}

Local MCP

{
  "mcp": {
    "my-local": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-server"],
      "environment": { "API_KEY": "{env:MY_API_KEY}" },
      "enabled": true,
      "timeout": 5000
    }
  }
}

Remote MCP

{
  "mcp": {
    "my-remote": {
      "type": "remote",
      "url": "https://mcp.example.com",
      "headers": { "Authorization": "Bearer {env:TOKEN}" },
      "oauth": {}
    }
  }
}

OhMyOpenCode Built-in MCPs

Disable via:

// oh-my-opencode.json
{ "disabled_mcps": ["websearch", "context7"] }

Claude Code MCP Compat Locations

~/.claude/.mcp.json
./.mcp.json
./.claude/.mcp.json

Skills

Skill Locations

~/.config/opencode/skill/<name>/SKILL.md  - global
.opencode/skill/<name>/SKILL.md           - project
~/.claude/skills/<name>/SKILL.md          - Claude Code compat
.claude/skills/<name>/SKILL.md            - Claude Code compat (project)

Skill Format

---
name: my-skill
description: What this skill does (1-1024 chars)
license: MIT
compatibility: opencode
mcp:                              # Optional embedded MCP
  playwright:
    command: npx
    args: ["-y", "@anthropic-ai/mcp-playwright"]
---

Instructions for the agent when this skill is loaded.

OhMyOpenCode Built-in Skills

• playwright - Browser automation
• git-master - Git operations expert

Disable via:

// oh-my-opencode.json
{ "disabled_skills": ["playwright"] }

Commands

Command Locations

~/.config/opencode/command/*.md   - global
.opencode/command/*.md            - project
~/.claude/commands/*.md           - Claude Code compat
.claude/commands/*.md             - Claude Code compat (project)

Command Format

---
description: What this command does
agent: build
model: anthropic/claude-sonnet-4
subtask: true
---

Template with $ARGUMENTS or $1, $2, etc.

Include files with @path/to/file.ts
Include shell output with !`command`

Providers

Authentication

opencode auth login       # Interactive provider selection
opencode auth list        # Show configured providers

Provider Config

{
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://api.anthropic.com/v1",
        "timeout": 600000
      }
    }
  },
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

Model Format

provider/model-id - e.g., anthropic/claude-opus-4-5, openai/gpt-5.2

Disable Providers

{
  "disabled_providers": ["openai", "gemini"],
  "enabled_providers": ["anthropic"]  // Allowlist mode
}

OhMyOpenCode Specifics

Sisyphus Agent Config

// oh-my-opencode.json
{
  "sisyphus_agent": {
    "disabled": false,
    "default_builder_enabled": false,
    "planner_enabled": true,
    "replace_plan": true
  }
}

Background Task Concurrency

{
  "background_task": {
    "defaultConcurrency": 5,
    "providerConcurrency": { "anthropic": 3 },
    "modelConcurrency": { "anthropic/claude-opus-4-5": 2 }
  }
}

Categories (sisyphus_task)

{
  "categories": {
    "visual": {
      "model": "google/gemini-3-pro-preview",
      "temperature": 0.7,
      "prompt_append": "Use shadcn/ui and Tailwind"
    },
    "business-logic": {
      "model": "openai/gpt-5.2",
      "temperature": 0.1
    }
  }
}

Hooks

Disable via:

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

Key hooks:

• todo-continuation-enforcer - Forces completion of all TODOs
• comment-checker - Prevents excessive comments
• context-window-monitor - Warns at 70%+ usage
• preemptive-compaction - Compacts at 85% usage
• keyword-detector - Detects ultrawork/search/analyze
• ralph-loop - Continuous execution until done

Ralph Loop

/ralph-loop "Build a REST API"   # Start loop
/cancel-ralph                     # Stop loop

Hooks (Claude Code Compat)

Hook Locations

~/.claude/settings.json
./.claude/settings.json
./.claude/settings.local.json

Hook Events

• PreToolUse - Before tool execution
• PostToolUse - After tool execution
• UserPromptSubmit - On prompt submit
• Stop - When session goes idle

Hook Format

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "eslint --fix $FILE" }]
      }
    ]
  }
}

Rules / Instructions

AGENTS.md Locations

./AGENTS.md                       - project root
~/.config/opencode/AGENTS.md      - global

Both are combined. Project can have nested AGENTS.md per directory.

Instructions Array

{
  "instructions": ["CONTRIBUTING.md", "docs/*.md", ".cursor/rules/*.md"]
}

Conditional Rules (.claude/rules/)

---
globs: ["*.ts", "src/**/*.js"]
alwaysApply: false
---

- Use PascalCase for interfaces
- Use camelCase for functions

Common Tasks

Check Current Config

cat ~/.config/opencode/opencode.json
cat ~/.config/opencode/oh-my-opencode.json
cat ./opencode.json
cat ./.opencode/oh-my-opencode.json

Add Custom Agent

1. Create ~/.config/opencode/agent/my-agent.md or .opencode/agent/my-agent.md
2. Or add to opencode.json under agent key

Disable OhMyOpenCode Feature

// oh-my-opencode.json
{
  "disabled_hooks": ["feature-name"],
  "disabled_agents": ["agent-name"],
  "disabled_mcps": ["mcp-name"],
  "disabled_skills": ["skill-name"]
}

Override Agent Model

// oh-my-opencode.json
{
  "agents": {
    "oracle": { "model": "anthropic/claude-sonnet-4-20250514" }
  }
}

Add Custom MCP

// opencode.json
{
  "mcp": {
    "my-mcp": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-server"]
    }
  }
}

Troubleshooting

Config Not Loading

1. Check JSON syntax: cat ~/.config/opencode/opencode.json | jq .
2. Verify file location (precedence matters)
3. Check OpenCode version: opencode --version (need 1.0.150+)

Agent Not Available

1. Check disabled_agents in oh-my-opencode.json
2. Verify agent file exists and has valid frontmatter
3. Check mode: primary vs subagent

MCP Not Working

1. Check enabled: true in MCP config
2. Verify command exists: which npx
3. Check timeout (default 5000ms)
4. For OAuth: opencode mcp auth <server-name>

Hooks Not Firing

1. Check disabled_hooks in oh-my-opencode.json
2. Verify hook event name matches
3. Check Claude Code settings.json location

Provider Auth Issues

1. Run opencode auth login and re-authenticate
2. Check ~/.local/share/opencode/auth.json exists
3. For Google: Consider opencode-antigravity-auth plugin

Variable Substitution

Environment Variables

{ "apiKey": "{env:MY_API_KEY}" }

File Contents

{ "instructions": ["{file:./prompts/system.txt}"] }

LSP Configuration

Add LSP Server (oh-my-opencode.json)

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

Claude Code Compatibility Toggles

// oh-my-opencode.json
{
  "claude_code": {
    "mcp": false,       // Disable ~/.claude/.mcp.json loading
    "commands": false,  // Disable ~/.claude/commands/
    "skills": false,    // Disable ~/.claude/skills/
    "agents": false,    // Disable ~/.claude/agents/
    "hooks": false,     // Disable settings.json hooks
    "plugins": false    // Disable marketplace plugins
  }
}