> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/opencode-ai/opencode/llms.txt
> Use this file to discover all available pages before exploring further.

# 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)

<Note>
  Local configuration files are merged with global configuration. Local settings take precedence over global settings.
</Note>

## Root properties

<ParamField path="data" type="object">
  Storage configuration for OpenCode's database and files.

  <Expandable title="properties">
    <ParamField path="directory" type="string" default=".opencode">
      Directory where application data is stored (database, session history, etc.)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="wd" type="string">
  Working directory for the application. If not specified, uses the current directory.
</ParamField>

<ParamField path="debug" type="boolean" default="false">
  Enable debug mode with verbose logging. When `true`, log level is set to debug automatically.
</ParamField>

<ParamField path="debugLSP" type="boolean" default="false">
  Enable Language Server Protocol debug mode for troubleshooting LSP integration issues.
</ParamField>

<ParamField path="autoCompact" type="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.
</ParamField>

<ParamField path="contextPaths" type="array" default="['.github/copilot-instructions.md', '.cursorrules', ...]">
  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`
</ParamField>

## Agents configuration

<ParamField path="agents" type="object">
  Configuration for different AI agents used by OpenCode. Each agent can use a different model and token limit.

  <Expandable title="properties">
    <ParamField path="coder" type="object">
      Main coding agent for interactive sessions. Handles code editing, file operations, and complex tasks.

      <Expandable title="properties">
        <ParamField path="model" type="string" required>
          Model ID to use for the coder agent. See [provider configuration](/reference/provider-config) for available models.
        </ParamField>

        <ParamField path="maxTokens" type="integer" default="5000">
          Maximum tokens for agent responses (minimum: 1).
        </ParamField>

        <ParamField path="reasoningEffort" type="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`.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="task" type="object">
      Task agent for executing background operations like file search, grep, and analysis.

      <Expandable title="properties">
        <ParamField path="model" type="string" required>
          Model ID to use for the task agent.
        </ParamField>

        <ParamField path="maxTokens" type="integer" default="5000">
          Maximum tokens for task agent responses.
        </ParamField>

        <ParamField path="reasoningEffort" type="string">
          Reasoning effort level (`low`, `medium`, `high`).
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="title" type="object">
      Title agent for generating session titles from first messages.

      <Expandable title="properties">
        <ParamField path="model" type="string" required>
          Model ID to use for the title agent.
        </ParamField>

        <ParamField path="maxTokens" type="integer" default="80">
          Maximum tokens for title generation (automatically set to 80).
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Providers configuration

<ParamField path="providers" type="object">
  LLM provider configurations. Each provider can be enabled/disabled and configured with API keys.

  <Expandable title="properties">
    <ParamField path="anthropic" type="object">
      Anthropic (Claude) provider configuration.

      <Expandable title="properties">
        <ParamField path="apiKey" type="string">
          Anthropic API key. Can also be set via `ANTHROPIC_API_KEY` environment variable.
        </ParamField>

        <ParamField path="disabled" type="boolean" default="false">
          Disable this provider.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="openai" type="object">
      OpenAI provider configuration.

      <Expandable title="properties">
        <ParamField path="apiKey" type="string">
          OpenAI API key. Can also be set via `OPENAI_API_KEY` environment variable.
        </ParamField>

        <ParamField path="disabled" type="boolean" default="false">
          Disable this provider.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="gemini" type="object">
      Google Gemini provider configuration.

      <Expandable title="properties">
        <ParamField path="apiKey" type="string">
          Gemini API key. Can also be set via `GEMINI_API_KEY` environment variable.
        </ParamField>

        <ParamField path="disabled" type="boolean" default="false">
          Disable this provider.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="groq" type="object">
      Groq provider configuration.

      <Expandable title="properties">
        <ParamField path="apiKey" type="string">
          Groq API key. Can also be set via `GROQ_API_KEY` environment variable.
        </ParamField>

        <ParamField path="disabled" type="boolean" default="false">
          Disable this provider.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="openrouter" type="object">
      OpenRouter provider configuration.

      <Expandable title="properties">
        <ParamField path="apiKey" type="string">
          OpenRouter API key. Can also be set via `OPENROUTER_API_KEY` environment variable.
        </ParamField>

        <ParamField path="disabled" type="boolean" default="false">
          Disable this provider.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="bedrock" type="object">
      AWS Bedrock provider configuration. Uses AWS credentials from environment.

      <Expandable title="properties">
        <ParamField path="disabled" type="boolean" default="false">
          Disable this provider.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="azure" type="object">
      Azure OpenAI provider configuration.

      <Expandable title="properties">
        <ParamField path="apiKey" type="string">
          Azure OpenAI API key. Optional when using Entra ID authentication.
        </ParamField>

        <ParamField path="disabled" type="boolean" default="false">
          Disable this provider.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="vertexai" type="object">
      Google Cloud VertexAI provider configuration.

      <Expandable title="properties">
        <ParamField path="disabled" type="boolean" default="false">
          Disable this provider.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="copilot" type="object">
      GitHub Copilot provider configuration.

      <Expandable title="properties">
        <ParamField path="apiKey" type="string">
          GitHub token. Auto-detected from GitHub Copilot configuration or `GITHUB_TOKEN` environment variable.
        </ParamField>

        <ParamField path="disabled" type="boolean" default="false">
          Disable this provider.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## MCP servers configuration

<ParamField path="mcpServers" type="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.

  <Expandable title="Server properties">
    <ParamField path="command" type="string" required>
      Command to execute for the MCP server.
    </ParamField>

    <ParamField path="type" type="string" default="stdio">
      Type of MCP server.

      **Options:** `stdio`, `sse`
    </ParamField>

    <ParamField path="args" type="array">
      Command arguments for the MCP server.
    </ParamField>

    <ParamField path="env" type="array">
      Environment variables for the MCP server (array of strings).
    </ParamField>

    <ParamField path="url" type="string">
      URL for SSE type MCP servers (required when `type: "sse"`).
    </ParamField>

    <ParamField path="headers" type="object">
      HTTP headers for SSE type MCP servers (key-value pairs).
    </ParamField>
  </Expandable>
</ParamField>

## LSP configuration

<ParamField path="lsp" type="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.

  <Expandable title="LSP properties">
    <ParamField path="command" type="string" required>
      Command to execute for the LSP server (e.g., `gopls`, `typescript-language-server`).
    </ParamField>

    <ParamField path="args" type="array">
      Command arguments for the LSP server.
    </ParamField>

    <ParamField path="disabled" type="boolean" default="false">
      Whether the LSP is disabled.
    </ParamField>

    <ParamField path="options" type="object">
      Additional options for the LSP server (provider-specific).
    </ParamField>
  </Expandable>
</ParamField>

## Shell configuration

<ParamField path="shell" type="object">
  Shell configuration for the bash tool.

  <Expandable title="properties">
    <ParamField path="path" type="string" default="$SHELL or /bin/bash">
      Path to the shell executable.
    </ParamField>

    <ParamField path="args" type="array" default="[&#x22;-l&#x22;]">
      Arguments to pass to the shell.
    </ParamField>
  </Expandable>
</ParamField>

## TUI configuration

<ParamField path="tui" type="object">
  Terminal User Interface configuration.

  <Expandable title="properties">
    <ParamField path="theme" type="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
    </ParamField>
  </Expandable>
</ParamField>

## Example configuration

```json theme={null}
{
  "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:

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