Configuration schema

Complete JSON schema reference for .opencode.json configuration file

OpenCode uses a JSON configuration file (.opencode.json) to customize its behavior. This page documents the complete schema and all available configuration options.

Configuration file locations

OpenCode searches for configuration files in the following order:

1. $HOME/.opencode.json - Global configuration
2. $XDG_CONFIG_HOME/opencode/.opencode.json - XDG-compliant location
3. ./.opencode.json - Local directory (merged with global config)

Local configuration files are merged with global configuration. Local settings take precedence over global settings.

Root properties

data · object

Storage configuration for OpenCode’s database and files.

Show properties

directory · string · default: ".opencode"

Directory where application data is stored (database, session history, etc.)

wd · string

Working directory for the application. If not specified, uses the current directory.

debug · boolean · default: "false"

Enable debug mode with verbose logging. When true, log level is set to debug automatically.

debugLSP · boolean · default: "false"

Enable Language Server Protocol debug mode for troubleshooting LSP integration issues.

autoCompact · boolean · default: "true"

Automatically summarize conversations when approaching the model’s context window limit. When enabled, OpenCode monitors token usage and creates a new session with a summary at 95% context usage.

contextPaths · array

List of file paths to automatically include in the AI context. These files are added to every conversation.

Default paths:

• .github/copilot-instructions.md
• .cursorrules
• .cursor/rules/
• CLAUDE.md, CLAUDE.local.md
• opencode.md, opencode.local.md
• OpenCode.md, OpenCode.local.md
• OPENCODE.md, OPENCODE.local.md

Agents configuration

agents · object

Configuration for different AI agents used by OpenCode. Each agent can use a different model and token limit.

Show properties

coder · object

Main coding agent for interactive sessions. Handles code editing, file operations, and complex tasks.

Show properties

model · string · required

Model ID to use for the coder agent. See provider configuration for available models.

maxTokens · integer · default: "5000"

Maximum tokens for agent responses (minimum: 1).

reasoningEffort · string

Reasoning effort level for models that support extended thinking (OpenAI o-series, Anthropic extended thinking).

Options: low, medium, high

Only applicable to models with CanReason: true.

task · object

Task agent for executing background operations like file search, grep, and analysis.

Show properties

model · string · required

Model ID to use for the task agent.

maxTokens · integer · default: "5000"

Maximum tokens for task agent responses.

reasoningEffort · string

Reasoning effort level (low, medium, high).

title · object

Title agent for generating session titles from first messages.

Show properties

model · string · required

Model ID to use for the title agent.

maxTokens · integer · default: "80"

Maximum tokens for title generation (automatically set to 80).

Providers configuration

providers · object

LLM provider configurations. Each provider can be enabled/disabled and configured with API keys.

Show properties

anthropic · object

Anthropic (Claude) provider configuration.

Show properties

apiKey · string

Anthropic API key. Can also be set via ANTHROPIC_API_KEY environment variable.

disabled · boolean · default: "false"

Disable this provider.

openai · object

OpenAI provider configuration.

Show properties

apiKey · string

OpenAI API key. Can also be set via OPENAI_API_KEY environment variable.

disabled · boolean · default: "false"

Disable this provider.

gemini · object

Google Gemini provider configuration.

Show properties

apiKey · string

Gemini API key. Can also be set via GEMINI_API_KEY environment variable.

disabled · boolean · default: "false"

Disable this provider.

groq · object

Groq provider configuration.

Show properties

apiKey · string

Groq API key. Can also be set via GROQ_API_KEY environment variable.

disabled · boolean · default: "false"

Disable this provider.

openrouter · object

OpenRouter provider configuration.

Show properties

apiKey · string

OpenRouter API key. Can also be set via OPENROUTER_API_KEY environment variable.

disabled · boolean · default: "false"

Disable this provider.

bedrock · object

AWS Bedrock provider configuration. Uses AWS credentials from environment.

Show properties

disabled · boolean · default: "false"

Disable this provider.

azure · object

Azure OpenAI provider configuration.

Show properties

apiKey · string

Azure OpenAI API key. Optional when using Entra ID authentication.

disabled · boolean · default: "false"

Disable this provider.

vertexai · object

Google Cloud VertexAI provider configuration.

Show properties

disabled · boolean · default: "false"

Disable this provider.

copilot · object

GitHub Copilot provider configuration.

Show properties

apiKey · string

GitHub token. Auto-detected from GitHub Copilot configuration or GITHUB_TOKEN environment variable.

disabled · boolean · default: "false"

Disable this provider.

MCP servers configuration

mcpServers · object

Model Control Protocol server configurations. Define custom MCP servers to extend OpenCode’s capabilities.

Each key is the server name, and the value is a server configuration object.

Show Server properties

command · string · required

Command to execute for the MCP server.

type · string · default: "stdio"

Type of MCP server.

Options: stdio, sse

args · array

Command arguments for the MCP server.

env · array

Environment variables for the MCP server (array of strings).

url · string

URL for SSE type MCP servers (required when type: "sse").

headers · object

HTTP headers for SSE type MCP servers (key-value pairs).

LSP configuration

lsp · object

Language Server Protocol configurations. Define LSP servers for different programming languages.

Each key is a language identifier, and the value is an LSP configuration object.

Show LSP properties

command · string · required

Command to execute for the LSP server (e.g., gopls, typescript-language-server).

args · array

Command arguments for the LSP server.

disabled · boolean · default: "false"

Whether the LSP is disabled.

options · object

Additional options for the LSP server (provider-specific).

Shell configuration

shell · object

Shell configuration for the bash tool.

Show properties

path · string · default: "$SHELL or /bin/bash"

Path to the shell executable.

args · array · default: "[\"-l\"]"

Arguments to pass to the shell.

TUI configuration

tui · object

Terminal User Interface configuration.

Show properties

theme · string · default: "opencode"

TUI theme name.

Available themes:

• opencode - Default OpenCode theme
• catppuccin - Catppuccin color scheme
• dracula - Dracula theme
• flexoki - Flexoki theme
• gruvbox - Gruvbox theme
• monokai - Monokai theme
• onedark - One Dark theme
• tokyonight - Tokyo Night theme
• tron - Tron theme

Example configuration

{
  "data": {
    "directory": ".opencode"
  },
  "debug": false,
  "autoCompact": true,
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-..."
    },
    "openai": {
      "apiKey": "sk-..."
    }
  },
  "agents": {
    "coder": {
      "model": "claude-3.7-sonnet",
      "maxTokens": 5000,
      "reasoningEffort": "medium"
    },
    "task": {
      "model": "gpt-4.1-mini",
      "maxTokens": 5000
    },
    "title": {
      "model": "gpt-4.1-mini"
    }
  },
  "shell": {
    "path": "/bin/zsh",
    "args": ["-l"]
  },
  "lsp": {
    "go": {
      "command": "gopls",
      "disabled": false
    },
    "typescript": {
      "command": "typescript-language-server",
      "args": ["--stdio"]
    }
  },
  "mcpServers": {
    "example": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-git"]
    }
  },
  "tui": {
    "theme": "tokyonight"
  }
}

JSON schema

The complete JSON schema is available in the OpenCode repository at opencode-schema.json. You can use it for validation and autocompletion in your editor:

{
  "$schema": "https://raw.githubusercontent.com/opencode-ai/opencode/main/opencode-schema.json"
}