agentconfig.ing
OPENCODEJSON(5)OPENCODEJSON(5)

NAME

opencode.json — instruction file for OpenCode

SYNOPSIS

~/.config/opencode/

./opencode.json

METADATA

FORMATJson
FILENAMEopencode.json
CASE SENSITIVEYes
TOOLOpenCode
ENCODINGUTF-8
GIT COMMITTEDYes
MAX SIZE10KB
SINCEOpenCode (2025)

DESCRIPTION

opencode.json is the configuration file for OpenCode, an open-source terminal-based AI coding assistant. It uses standard JSON format to define model preferences, scoped instructions, tool permissions, and MCP server integrations.

The file supports a powerful instruction system where each instruction can be globally applied or scoped to specific file patterns using glob arrays. This allows different coding conventions for different parts of the codebase without separate rule files.

Project-level opencode.json overrides the global configuration at ~/.config/opencode/. The file is designed to be committed to version control so teams share consistent AI assistant behavior.

Load Order
1~/.config/opencode/(global)
2./opencode.json(project)

Lower numbers load first. Higher-priority files override lower ones.

STRUCTURE

├──Model Configuration
Specifies the default LLM provider and model to use (e.g., `anthropic/claude-sonnet-4-20250514`). Supports multiple providers including Anthropic, OpenAI, and local models.
├──Instructions
An array of instruction objects with optional `glob` patterns for file-scoped rules. Instructions without globs apply globally; those with globs only activate when matching files are in context.
├──MCP Servers
Configuration for Model Context Protocol servers. Each entry defines a server with command, args, and environment variables for extending OpenCode's capabilities.
└──Permissions & Tools
Controls which tools OpenCode can use and permission levels for shell commands, file writes, and other operations.

ANNOTATED EXAMPLE

opencode.json
json
1{
2  "model": "anthropic/claude-sonnet-4-20250514",
3  "instructions": [
4    {
5      "content": "Use TypeScript strict mode. Prefer functional patterns."
6    },
7    {
8      "glob": ["src/components/**/*.tsx"],
9      "content": "Use functional React components with named exports."
10    },
11    {
12      "glob": ["**/*.test.ts"],
13      "content": "Use Vitest with describe/it blocks. Prefer userEvent over fireEvent."
14    }
15  ],
16  "permissions": {
17    "autoApprove": ["Read", "Glob", "Grep"],
18    "requireApproval": ["Bash", "Write"]
19  },
20  "mcpServers": {
21    "postgres": {
22      "command": "npx",
23      "args": ["-y", "@modelcontextprotocol/server-postgres"],
24      "env": {
25        "DATABASE_URL": "postgresql://localhost:5432/mydb"
26      }
27    }
28  }
29}

COMMON MISTAKES

Gotchas
✗WRONG Using YAML or TOML format
✓RIGHT opencode.json must be valid JSON — no comments, no trailing commas

Unlike many modern config files, OpenCode uses strict JSON. JSONC (JSON with comments) is not supported. Ensure your editor validates the file as standard JSON.

✗WRONG Putting instructions as a plain string
✓RIGHT Instructions are an array of objects with `content` and optional `glob` fields

The instructions field is structured as an array, not a simple string. Each instruction object has a `content` string and an optional `glob` array for file-pattern scoping.

✗WRONG Expecting environment variables to expand in the JSON file
✓RIGHT Use the `env` field within MCP server configs for environment variables

Shell-style $VAR expansion does not work in opencode.json. Environment variables for MCP servers must be specified in the dedicated `env` object within each server configuration.

USED BY

OpenCode

SIMILAR FILES

CLAUDE.md— Claude Memory File
.aider.conf.yml— Aider Configuration

COMPARISONS

OpenCode vs Claude CodeOpenCode vs Aider
agentconfig.ing2026-03-16OPENCODEJSON(5)