Config

Create opencode.jsonc in your project to configure OpenCode. Add the schema for editor validation, then set only the options you need.

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

You can also ask OpenCode to update this file for you.

Format

OpenCode supports JSON and JSONC. Use JSONC when you want comments or trailing commas.

{
  "$schema": "https://opencode.ai/config.json",
  // Use this model by default.
  "model": "anthropic/claude-sonnet-4-5",
}

Locations

Put settings for every project in the global configuration:

~/.config/opencode/opencode.json(c)

Put project settings in either of these files:

/home/user/projects/my-app/opencode.json(c)
/home/user/projects/my-app/.opencode/opencode.json(c)

OpenCode searches from the current directory to the filesystem root. It first merges direct opencode.json(c) files from the farthest directory to the closest, then merges files inside .opencode directories in the same order. This means every discovered .opencode config overrides every direct config. Use one form throughout a directory tree unless you need that behavior.

For example, start OpenCode from /home/user/projects/acme/packages/web:

~/.config/opencode/opencode.json

/home/user/projects/acme/
├── opencode.json
└── packages/
    └── web/
        ├── opencode.json
        └── src/

OpenCode applies these files from lowest to highest precedence:

1. ~/.config/opencode/opencode.json
2. /home/user/projects/acme/opencode.json
3. /home/user/projects/acme/packages/web/opencode.json

The package config overrides matching settings from the repository config, which overrides the global config. Settings that do not conflict are preserved.

Schema

The complete OpenCode configuration schema is available at opencode.ai/config.json.

Add the $schema field to your configuration file to enable validation and autocomplete in editors that support JSON Schema:

{
  "$schema": "https://opencode.ai/config.json"
}

Use the schema as the source of truth for available fields, accepted values, and nested configuration shapes.

Shell

Set the shell used by the terminal and shell tools.

{
  "shell": "/bin/zsh",
}

Model

Set the default model in provider/model format. The root default currently does not retain a #variant; agent and command model references can select one.

{
  "model": "anthropic/claude-sonnet-4-5",
}

See the models guide for model selection and local models.

Agent

Choose the primary agent used when a session does not select one explicitly.

{
  "default_agent": "build",
}

See the agents guide for built-in and custom agents.

Updates

Control update checks from the global config. Set update to "disable" to skip them, "notify" to show available updates before installing them, or "auto" to install updates automatically. When omitted, update defaults to "notify".

Automatic installation does not restart a running server. Restart it manually to activate the installed update. Project-level values are ignored.

{
  "update": "notify",
}

Sharing

Set the session sharing policy. OpenCode accepts this field, but session sharing is not supported yet.

{
  "share": "manual",
}

See the sharing guide for more details.

Username

Set a username. OpenCode accepts this field but does not display it in conversations.

{
  "username": "alice",
}

Permissions

Define ordered rules that allow, deny, or ask before an agent uses a tool on a matching resource.

{
  "permissions": [
    {
      "action": "shell",
      "resource": "git push *",
      "effect": "ask",
    },
  ],
}

See the permissions guide for rule matching and available actions.

Agents

Override built-in agents or define specialized agents with their own model, instructions, mode, and permissions.

{
  "agents": {
    "reviewer": {
      "description": "Review changes without editing files",
      "mode": "subagent",
      "system": "Focus on correctness, security, and missing tests.",
      "permissions": [{ "action": "edit", "resource": "*", "effect": "deny" }],
    },
  },
}

See the agents guide for all agent options and file-based agents.

Snapshots

Enable or disable filesystem snapshots used by undo and revert behavior.

{
  "snapshots": false,
}

See the snapshots guide for undo and redo behavior.

Watcher

Ignore files and directories that should not trigger filesystem updates.

{
  "watcher": {
    "ignore": ["dist/**", "coverage/**"],
  },
}

Formatter

Format files after the write, edit, or patch tools change them. Set formatter to true to enable available built-in formatters.

{
  "formatter": true,
}

See the formatters guide for built-ins and custom formatters.

Media

Control how oversized images loaded by the read tool are resized or rejected before they are sent to a model.

{
  "media": {
    "image": {
      "auto_resize": true,
      "max_width": 2000,
      "max_height": 2000,
      "max_base64_bytes": 5242880,
    },
  },
}

See the attachments guide for image processing and limits.

Output

Set the maximum number of lines and bytes retained from a tool result.

{
  "tool_output": {
    "max_lines": 2000,
    "max_bytes": 51200,
  },
}

Search

Choose how OpenCode searches the web. Use "random" to select an available provider automatically.

{
  "websearch": {
    "provider": "random",
  },
}

See the websearch guide for providers, credentials, selection, rate limits, and disabling search.

MCP

Configure local and remote Model Context Protocol servers. Global timeouts can be overridden by an individual server.

{
  "mcp": {
    "servers": {
      "playwright": {
        "type": "local",
        "command": ["bunx", "@playwright/mcp"],
      },
    },
  },
}

See the MCP guide for remote servers, OAuth, environment variables, and timeouts.

Compaction

Control automatic context compaction and how much recent context it preserves.

{
  "compaction": {
    "auto": true,
    "keep": {
      "tokens": 15000,
    },
    "buffer": 20000,
  },
}

Local summaries remain the default. Opt into native provider compaction for both automatic and manual requests with a provider or model policy:

{
  "providers": {
    "openai": {
      "settings": { "compaction": { "type": "native" } },
      "models": {
        "gpt-4.1": { "settings": { "compaction": { "type": "summary" } } },
      },
    },
  },
}

A model setting overrides the provider setting. Automatic compaction uses the selected model’s usable input budget. Provider checkpoints keep recent user messages within the same compaction.tokens budget that local summaries use for their retained tail. Top-level compaction.auto: false disables new automatic compaction without discarding installed checkpoints. See the compaction guide for budgeting and overflow recovery.

Warming

Keep recently active model sessions warm with periodic transient requests. Warming is disabled by default; set it to true to use the four-minute idle interval and 30-minute active window.

{
  "warming": {
    "prompt": "Do not perform any work. Reply with exactly: OK",
    "interval": "4 minutes",
    "duration": "30 minutes",
  },
}

See the warming guide for request behavior, customization, and cost considerations.

Skills

Add directories or URLs that OpenCode should search for agent skills.

{
  "skills": ["./team-skills", "https://example.com/.well-known/skills/"],
}

See the skills guide for skill structure and automatic discovery under .opencode/skills/.

Commands

Define reusable slash commands as named prompt templates.

{
  "commands": {
    "review": {
      "description": "Review the current changes",
      "template": "Review the current diff for correctness and missing tests.",
    },
  },
}

See the commands guide for arguments, models, agents, and file-based commands.

Instructions

Declare additional instruction files, globs, or URLs. OpenCode accepts this field but does not load its entries; use AGENTS.md for instructions.

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

See the instructions guide for project instructions and AGENTS.md.

References

Make local directories or Git repositories available as named supporting context.

{
  "references": {
    "docs": {
      "path": "../product-docs",
      "description": "Product behavior and terminology",
    },
    "effect": {
      "repository": "Effect-TS/effect",
      "branch": "main",
    },
  },
}

See the references guide for shorthand, visibility, and path resolution.

Worktrees

Set the parent directory for new local worktrees. OpenCode appends the requested or generated worktree name.

{
  "worktree": {
    "directory": "../worktrees",
  },
}

Relative paths resolve against the project’s saved canonical checkout. This applies to global and project configuration alike; absolute paths are used as-is, and ~/ resolves against the user’s home directory.

For example, this global configuration places new worktrees under each project’s own .lane/trees/ directory:

{
  "worktree": {
    "directory": ".lane/trees",
  },
}

Without this setting, creation uses the server’s data directory under worktree/<first-six-project-ID-characters>. Worktree creation and refresh load configuration from the project’s saved canonical checkout, including when other clones share its project ID. Changing it does not move existing worktrees.

Git is the built-in default. A plugin that registers a strategy automatically becomes the default in that plugin runtime. Project operations use the canonical checkout’s runtime. Strategy-specific options belong to that plugin, not the worktree config object.

Plugins

Load plugins from packages or local plugin directories. Use the object form when a plugin accepts options.

{
  "plugins": [
    "opencode-example-plugin",
    {
      "package": "./plugins/local",
      "options": {
        "enabled": true,
      },
    },
  ],
}

See the plugins guide for plugin loading and configuration.

Providers

Configure providers and add or override their models, request settings, headers, and model variants.

{
  "providers": {
    "openai": {
      "models": {
        "gpt-5.2-custom": {
          "modelID": "gpt-5.2",
          "name": "GPT-5.2 Custom",
          "limit": {
            "context": 200000,
            "output": 32000,
          },
        },
      },
    },
  },
}

Provider settings.transport: "websocket" selects its session WebSocket.

See the providers guide for credentials, custom endpoints, provider packages, the WebSocket transport, and model configuration.