opencode-config

name	opencode-config
description	Complete reference for configuring OpenCode (agents, tools, permissions, models)
license	MIT
compatibility	opencode
metadata	{"category":"reference","scope":"opencode-configuration"}

What I do

I provide comprehensive configuration guidance for OpenCode, covering all aspects of setup and customization.

When you load me, you get instant access to detailed information about:

• Configuration file locations and precedence
• Agent configuration (primary and subagents)
• Tools and permissions management
• Model and provider setup
• Skills, commands, and keybinds
• Advanced features (MCP servers, plugins, formatters)

When to use me

Use this skill when you need to:

• Configure OpenCode agents (create, customize, or troubleshoot)
• Set up permissions for tools and agents
• Understand configuration file structure and precedence
• Configure models and providers
• Set up custom tools, skills, or commands
• Troubleshoot configuration issues

Configuration file basics

Locations and precedence (highest to lowest)

1. Inline config: OPENCODE_CONFIG_CONTENT env var (runtime overrides)
2. .opencode directories: Agents, commands, plugins (project-specific)
3. Project config: opencode.json in project root
4. Custom config: OPENCODE_CONFIG env var path
5. Global config: ~/.config/opencode/opencode.json
6. Remote config: .well-known/opencode (organizational defaults)

Key principle: Configs are MERGED, not replaced

• Later configs override earlier ones for CONFLICTING keys only
• Non-conflicting settings from all levels are preserved
• Example: Global sets theme, project sets model → both are active

Format support

• JSON: opencode.json
• JSONC: opencode.jsonc (supports comments)
• Schema: https://opencode.ai/config.json (enables autocomplete)

Variable substitution

Environment variables:

"model": "{env:OPENCODE_MODEL}"

File contents:

"instructions": "{file:./custom-instructions.md}"

Paths are relative to config file or absolute (/, ~)

Agent configuration

Agent types

Primary agents: Main assistants you interact with directly

• Switch with Tab key or configured keybind
• Examples: build, plan, custom agents

Subagents: Specialized assistants invoked for specific tasks

• Invoked by primary agents via Task tool
• Manually invocable with @mention
• Examples: general, explore, custom subagents

Agent configuration options

Via JSON (opencode.json):

{
  "agent": {
    "my-agent": {
      "description": "Brief description for when to use this agent",
      "mode": "primary",  // or "subagent" or "all"
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "{file:./prompts/my-agent.txt}",
      "temperature": 0.2,
      "hidden": false,  // subagents only
      "maxSteps": 10,   // limit agentic iterations
      "tools": {
        "write": true,
        "edit": true,
        "bash": true,
         
         
      
       
         
           
           
        
         
         
           
           
        
      
    
  

Via Markdown (.opencode/agents/my-agent.md):

---
description: Brief description
mode: primary
model: anthropic/claude-sonnet-4-20250514
temperature: 0.2
color: "#FF6B35"
hidden: false
maxSteps: 10
tools:
  write: true
  edit: true
  bash: true
permission:
  bash:
    "*": "ask"
    "git status*": "allow"
  edit: allow
---

Your system prompt goes here.
Instructions for the agent's behavior.

Agent options reference

Option	Description	Values/Format
description	What the agent does (REQUIRED)	String, brief
mode	Agent type	"primary", "subagent", "all"
model	Override model for this agent	"provider/model-id"
prompt	Custom system prompt	String or {file:path}
temperature	Response randomness	0.0-1.0 (0.0=deterministic)
hidden	Hide from @ autocomplete (subagents)	true/false
maxSteps	Max agentic iterations before text-only	Number
color	Agent color in UI	Hex code "#RRGGBB"
tools	Tool access control	Object (see tools section)
permission	Action permissions	Object (see permissions section)

Default agent

Set which primary agent starts by default:

{
  "default_agent": "plan"  // Must be a primary agent
}

Tools configuration

Built-in tools

Tool	Purpose	Permission Key
bash	Execute shell commands	permission.bash
edit	Modify existing files	permission.edit
write	Create/overwrite files	Controlled by permission.edit
read	Read file contents	permission.read
grep	Search file contents (regex)	permission.grep
glob	Find files by pattern	permission.glob
list	List directory contents	permission.list
patch	Apply patches	Controlled by permission.edit
skill	Load skill definitions	permission.skill
task	Launch subagents	permission.task
todowrite	Manage todo lists	permission.todowrite
todoread	Read todo lists	permission.todoread
webfetch	Fetch web content	permission.webfetch
question	Ask user questions	permission.question
lsp	LSP code intelligence (experimental)	permission.lsp

Enable/disable tools

Global:

{
  "tools": {
    "write": true,
    "bash": true,
    "skill": false
  }
}

Per agent:

{
  "agent": {
    "plan": {
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    }
  }
}

Wildcards (MCP tools):

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

Permissions

Permission actions

• "allow" — Run without approval
• "ask" — Prompt for approval
• "deny" — Block the action

Global permissions

Simple:

{
  "permission": "allow"  // All tools allowed
}

Specific tools:

{
  "permission": {
    "*": "ask",      // Default for all
    "bash": "allow",
    "edit": "deny"
  }
}

Granular permissions (pattern matching)

{
  "permission": {
    "bash": {
      "*": "ask",                  // Default: ask
      "git *": "allow",            // Allow all git commands
      "git push*": "deny",         // Deny git push
      "npm install*": "allow",
      "rm *": "deny"
    },
    "edit": {
      "*": "deny",                           // Default: deny
      "packages/*/src/**/*.ts": "allow",     // Allow specific paths
      "*.md": "allow"                        // Allow markdown
    },
    "read": {
      "*": 
                    
       
            
    
     
                        
         
    
     
       
               
             
    
  

Permission pattern matching

• * matches zero or more of any character
• ? matches exactly one character
• Last matching rule wins
• Put * first, specific rules after

Special permissions

• external_directory — Triggered when accessing files outside project
• doom_loop — Triggered when same tool call repeats 3x identically
• Both default to "ask"

Per-agent permissions

Agent permissions override global config:

{
  "permission": {
    "bash": "ask"
  },
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",
          "git status*": "allow"
        }
      }
    }
  }
}

In markdown agents:

---
permission:
  edit: deny
  bash:
    "*": ask
    "git diff": allow
---

Models and providers

Model configuration

{
  "model": "anthropic/claude-sonnet-4-20250514",
  "small_model": "anthropic/claude-haiku-4-20250514"
}

Format: "provider/model-id"

small_model is used for lightweight tasks (title generation, etc.)

Provider options

{
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,      // 10 min (default: 300000)
        "setCacheKey": true,
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

Common options:

• timeout: Request timeout in ms (or false to disable)
• setCacheKey: Ensure cache key always set
• apiKey: API key (use env vars!)
• baseURL: Custom API endpoint

Provider-specific options

Amazon Bedrock:

{
  "provider": {
    "amazon-bedrock": {
      "options": {
        "region": "us-east-1",
        "profile": "my-aws-profile",
        "endpoint": "https://bedrock-runtime.vpce-xxx.amazonaws.com"
      }
    }
  }
}

Disable/enable providers

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

Note: disabled_providers takes priority over enabled_providers

Model-specific options

Pass provider-specific params directly:

{
  "agent": {
    "deep-thinker": {
      "model": "openai/gpt-5",
      "reasoningEffort": "high",     // OpenAI-specific
      "textVerbosity": "low"
    }
  }
}

Skills

Skill structure

Directory: .opencode/skills/<skill-name>/SKILL.md

SKILL.md format:

---
name: skill-name
description: What this skill does (1-1024 chars)
license: MIT
compatibility: opencode
metadata:
  key1: value1
  key2: value2
---

Skill content goes here.
Instructions, examples, reference material.

Skill name requirements

• 1-64 characters
• Lowercase alphanumeric with single hyphen separators
• No leading/trailing -
• No consecutive --
• Must match directory name
• Regex: ^[a-z0-9]+(-[a-z0-9]+)*$

Discovery locations

• Project: .opencode/skills/<name>/SKILL.md
• Global: ~/.config/opencode/skills/<name>/SKILL.md
• Claude-compatible: .claude/skills/<name>/SKILL.md (both project and global)

Skill permissions

{
  "permission": {
    "skill": {
      "*": "allow",
      "pr-review": "allow",
      "internal-*": "deny",
      "experimental-*": "ask"
    }
  }
}

Per agent:

{
  "agent": {
    "plan": {
      "permission": {
        "skill": {
          "internal-*": "allow"
        }
      }
    }
  }
}

Disable skill tool

{
  "agent": {
    "plan": {
      "tools": {
        "skill": false
      }
    }
  }
}

Commands

Custom commands

JSON:

{
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report.\nFocus on failing tests and suggest fixes.",
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-20250514"
    },
    "component": {
      "template": "Create a new React component named $ARGUMENTS with TypeScript.\nInclude proper typing and basic structure.",
      "description": "Create a new component"
    }
  }
}

Markdown (.opencode/commands/test.md):

---
description: Run tests with coverage
agent: build
model: anthropic/claude-haiku-4-20250514
---

Run the full test suite with coverage report.
Focus on failing tests and suggest fixes.

Use $ARGUMENTS for command arguments.

Advanced configuration

Themes

{
  "theme": "opencode"
}

Place custom themes in .opencode/themes/ or ~/.config/opencode/themes/

Keybinds

{
  "keybinds": {
    "switch_agent": "Tab",
    "session_child_cycle": "<Leader>+Right"
  }
}

TUI settings

{
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": {
      "enabled": true
    },
    "diff_style": "auto"  // or "stacked"
  }
}

Server settings

{
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "cors": ["http://localhost:5173"]
  }
}

Formatters

{
  "formatter": {
    "prettier": {
      "disabled": true
    },
    "custom-prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": {
        "NODE_ENV": "development"
      },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    }
  }
}

Instructions (rules)

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

Supports paths and glob patterns.

MCP servers

{
  "mcp": {
    "server-name": {
      "type": "remote",
      "url": "https://api.example.com/mcp",
      "enabled": true
    }
  }
}

Plugins

{
  "plugin": ["opencode-helicone-session", "@my-org/custom-plugin"]
}

Also place in .opencode/plugins/ or ~/.config/opencode/plugins/

Compaction

{
  "compaction": {
    "auto": true,   // Auto compact when context full
    "prune": true   // Remove old tool outputs
  }
}

Watcher

{
  "watcher": {
    "ignore": ["node_modules/**", "dist/**", ".git/**"]
  }
}

Sharing

{
  "share": "manual"  // "manual", "auto", or "disabled"
}

Autoupdate

{
  "autoupdate": false  // true, false, or "notify"
}

Experimental features

{
  "experimental": {
    // Experimental options here (unstable)
  }
}

Common configuration patterns

Read-only agent (Plan mode)

{
  "agent": {
    "plan": {
      "mode": "primary",
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    }
  }
}

Compilation subagent (noise filter)

{
  "agent": {
    "android-compilation": {
      "mode": "subagent",
      "hidden": false,
      "tools": {
        "write": false,
        "edit": false,
        "bash": true
      },
      "permission": {
        "bash": "allow"
      }
    }
  }
}

Integrator agent (delegates builds)

{
  "agent": {
    "integrator": {
      "mode": "primary",
      "tools": {
        "task": true
      },
      "permission": {
        "task": {
          "*": "deny",
          "android-compilation": "allow"
        }
      }
    }
  }
}

Security-focused permissions

{
  "permission": {
    "bash": {
      "*": "ask",
      "git status": "allow",
      "git diff*": "allow",
      "rm *": "deny",
      "sudo *": "deny"
    },
    "read": {
      "*": "allow",
      "*.env": "deny",
      "*.env.*": "deny",
      "**/secrets/**": "deny"
    },
    "edit": {
      "*": "ask",
      "src/**/*.ts": "allow",
       
    
  

Multi-environment setup

Global (~/.config/opencode/opencode.json):

{
  "theme": "opencode",
  "autoupdate": true,
  "model": "anthropic/claude-sonnet-4-20250514"
}

Project (opencode.json):

{
  "model": "anthropic/claude-haiku-4-20250514",  // Override: use cheaper model
  "instructions": ["CONTRIBUTING.md"],
  "agent": {
    "android-builder": {
      "mode": "primary",
      "prompt": "{file:.opencode/prompts/android-builder.txt}"
    }
  }
}

Result: Merged config uses haiku model, opencode theme, and project-specific agent.

Troubleshooting

Agent not appearing

• Check mode is set correctly (primary or subagent)
• Verify file is in .opencode/agents/ or ~/.config/opencode/agents/
• Check hidden: true (subagents only)
• Ensure description is provided

Skill not loading

• Verify filename is SKILL.md (all caps)
• Check frontmatter has name and description
• Ensure skill name matches directory name
• Check permissions: permission.skill not set to deny

Tool not working

• Check tools.<tool-name> is not false
• Verify permission.<tool-name> is not "deny"
• For subagents, check agent-specific tool config

Config not taking effect

• Check precedence order (project > custom > global > remote)
• Remember configs are merged, not replaced
• Use {env:VAR} for env vars, not direct references
• Validate JSON syntax (use JSONC for comments)

Permission patterns not matching

• Remember: last matching rule wins
• Use * wildcard correctly
• Put catch-all * rule first, specific after
• For commands with args, use "cmd *" not just "cmd"

Quick reference

Essential config locations

• Global: ~/.config/opencode/opencode.json
• Project: <project-root>/opencode.json
• Agents: .opencode/agents/*.md
• Skills: .opencode/skills/<name>/SKILL.md
• Commands: .opencode/commands/*.md

Common permission patterns

{
  "permission": {
    "bash": {
      "*": "ask",
      "git status": "allow",
      "git diff*": "allow"
    },
    "edit": "allow",
    "read": {
      "*": "allow",
      "*.env": "deny"
    },
    "task": {
      "*": "deny",
      "my-subagent": "allow"
    }
  }
}

Temperature guidelines

• 0.0-0.2: Very focused (code analysis, builds, error diagnosis)
• 0.3-0.5: Balanced (general development)
• 0.6-1.0: Creative (brainstorming, exploration)

Model format

provider/model-id

Examples:
- anthropic/claude-sonnet-4-20250514
- openai/gpt-4
- google-vertex-anthropic/claude-sonnet-4-5@20250929
- opencode/claude-haiku-4-5  (via OpenCode Zen)

For detailed documentation on any topic, refer to the accompanying docs in the docs/ folder of this skill.