Configuring OpenCode with opencode.json

Both opencode.json and opencode.jsonc (JSON with comments) work. Add the $schema key so your editor can validate and autocomplete. Sources load in this order, with later ones overriding earlier ones for conflicting keys:

• Remote config from your organization's .well-known/opencode endpoint.
• Global config at ~/.config/opencode/opencode.json.
• Custom config from the OPENCODE_CONFIG environment variable.
• Project config: opencode.json in the project. OpenCode looks in the current directory, then up to the nearest Git directory.
• .opencode directories for agents, commands, and plugins.
• Inline config from the OPENCODE_CONFIG_CONTENT environment variable.
• Managed config files set by admins (for example /etc/opencode/ on Linux), then macOS managed preferences, which cannot be overridden.

TUI-specific settings now belong in a separate tui.json file. Run opencode debug config to see the resolved config.

Set model and small_model using the provider/model format. small_model handles lightweight tasks like title generation. Use {env:VARIABLE_NAME} to pull secrets from environment variables, and enabled_providers or disabled_providers to limit which providers load. If a provider is in both lists, disabled_providers wins.

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}",
        "timeout": 600000
      }
    }
  },
  // Only load these providers
  "enabled_providers": ["anthropic", "openai"]
}

Each permission resolves to allow, ask, or deny. Most default to allow, while doom_loop and external_directory default to ask. Object rules match on tool input and the last matching rule wins, so put the catch-all * first. The older tools boolean config is deprecated in favor of permission.

MCP servers go under mcp with a unique name. Local servers use type local with a command array. Remote servers use type remote with a url and optional headers. Set enabled to false to turn one off without deleting it. OpenCode handles OAuth for remote servers automatically, and opencode mcp auth YOUR_SERVER_NAME triggers it manually.

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": {
      "*": "ask",
      "git *": "allow",
      "rm *": "deny"
    }
  },
  "mcp": {
    "my-local-mcp-server": {
      "type": "local",
      "command": ["npx", "-y", "YOUR_MCP_PACKAGE"],
      "enabled": true,
      "environment": { "MY_ENV_VAR": "YOUR_VALUE" }
    },
    "my-remote-mcp": {
      "type": "remote",
      "url": "https://YOUR_MCP_SERVER_URL",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Put project rules in AGENTS.md at your project root and personal rules in ~/.config/opencode/AGENTS.md. If no AGENTS.md exists, OpenCode falls back to CLAUDE.md files. Use the instructions array to pull in extra files or globs such as CONTRIBUTING.md.

Custom agents and commands can live in the agent and command keys of your config, or as markdown files in .opencode/agents/ and .opencode/commands/ (or the same folders under ~/.config/opencode/). The file name becomes the agent or command name, and $ARGUMENTS in a command template is replaced with what you type after it.

---
description: Run tests with coverage
agent: build
---
Run the full test suite with coverage report and show any failures.
Focus on the failing tests and suggest fixes.