Skip to main content

​
Overview

OpenCode uses JSON and JSONC (JSON with Comments) configuration files. Settings are merged from multiple locations, with local configuration taking precedence.

​
File Format

{
  "$schema": "https://opencode.ai/config.json",
  // Theme configuration
  "theme": "opencode",
  "model": "anthropic/claude-sonnet-4-5",
  "auto_update": true
}

​
Configuration Locations (Merged)

PriorityLocationDescription
1~/.config/opencode/opencode.jsoncGlobal settings
2opencode.jsonc (project root)Project settings
3OPENCODE_CONFIG env varCustom file path
4OPENCODE_CONFIG_DIR env varCustom directory

​
Core Options

OptionTypeDescription
$schemastringSchema URL for validation
themestringUI theme name
modelstringDefault model (provider/model-id)
small_modelstringModel for lightweight tasks
auto_updateboolean / "notify"Auto-update behavior
default_agentstringDefault primary agent
share"manual" / "auto" / "disabled"Session sharing mode

​
Tools Configuration

Globally enable or disable tools: 
{
  "tools": {
    "write": false,
    "bash": false,
    "mymcp_*": false
  }
}

​
Provider Configuration

{
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "setCacheKey": true
      }
    }
  },
  "disabled_providers": ["openai"],
  "enabled_providers": ["anthropic"]
}

​
TUI Configuration

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

​
Server Configuration

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

​
Compaction Configuration

{
  "compaction": {
    "auto": true,
    "prune": true
  }
}

​
File Watcher Configuration

{
  "watcher": {
    "include": ["src/**/*.ts", "*.json"],
    "exclude": ["node_modules/**", "dist/**", ".git/**"]
  }
}

​
Formatter Configuration

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

​
Commands Configuration

​
JSONC Format

{
  "command": {
    "test": {
      "run": "Run the full test suite with coverage.",
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "anthropic/claude-sonnet-4-5"
    }
  }
}

​
Markdown Format

.opencode/command/test.md
---
description: Run tests with coverage
agent: build
model: anthropic/claude-sonnet-4-5
---

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

​
Command Placeholders

PlaceholderDescription
$ARGUMENTSAll arguments
$1, $2, …Positional arguments
!`command`Shell output injection
@filepathFile content inclusion

​
Variable Substitution

​
Environment Variables

{
  "model": "{env:OPENCODE_MODEL}",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

​
File Contents

{
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

​
Built-in Tools

ToolDescription
bashExecute shell commands
editModify files via string replacement
writeCreate/overwrite files
readRead file contents
grepSearch file contents (regex)
globFind files by pattern
listList directory contents
patchApply patches
skillLoad skill definitions
todowriteManage todo lists
todoreadRead todo lists
webfetchFetch web content
lsp(Experimental) LSP integration

​
OpenCode CLI

CommandDescription
opencodeStart TUI
opencode run [message]Non-interactive mode
opencode serveStart headless server
opencode webStart server with web interface
opencode agent createCreate new agent
opencode agent listList agents
opencode auth loginConfigure API keys
opencode auth listList authenticated providers
opencode auth logoutRemove credentials
opencode mcp addAdd MCP server
opencode mcp listList MCP servers
opencode session listList sessions
opencode modelsList available models
opencode statsShow usage statistics
opencode upgradeUpdate OpenCode

​
Global Flags

FlagDescription
--help, -hDisplay help
--version, -vPrint version
--print-logsPrint logs to stderr
--log-levelDEBUG, INFO, WARN, ERROR

​
Environment Variables

VariableDescription
OPENCODE_CONFIGCustom config file path
OPENCODE_CONFIG_DIRCustom config directory
OPENCODE_PERMISSIONInline JSON permissions
OPENCODE_DISABLE_AUTOUPDATEDisable updates
OPENCODE_EXPERIMENTALEnable experimental features

​
SDK Reference

​
Installation

npm install @opencode-ai/sdk

​
Create Instance

import { createOpencode } from "@opencode-ai/sdk"

const { client } = await createOpencode({
  host: "127.0.0.1",
  port: 4096,
  config: {
    model: "anthropic/claude-sonnet-4-5"
  }
})

​
Client Only

import { createOpencodeClient } from "@opencode-ai/sdk"

const client = createOpencodeClient({
  baseUrl: "http://localhost:4096"
})

​
Key APIs

// Health check
const health = await client.global.health()

// Sessions
const session = await client.session.create({ body: { title: "My session" } })
const sessions = await client.session.list()

// Send prompt
const result = await client.session.prompt({
  path: { id: session.id },
  body: {
    model: { providerID: "anthropic", modelID: "claude-sonnet-4-5" },
    parts: [{ type: "text", text: "Hello!" }]
  }
})

// Event stream
const events = await client.event.subscribe()
for await (const event of events.stream) {
  console.log("Event:", event.type)
}

​
See Also