Edit opencode.json, AGENTS.md, and config files...
Help users configure OpenCode through guided setup of config files and rules.
Batching Rule: Use only for 2+ related questions; single questions use plain text.
Syntax Constraints: header max 12 chars, labels 1-5 words, mark defaults with (Recommended).
Purpose: Clarify config scope (models/permissions/rules), validate approach, and handle multiple valid options.
| Type | Global | Project |
|---|---|---|
| Config | ~/.config/opencode/opencode.json |
./opencode.json |
| Rules | ~/.config/opencode/AGENTS.md |
./AGENTS.md |
Precedence: Project > Global. Configs are merged, not replaced.
Batching: Use the question tool for 2+ related questions. Single questions → plain text.
Syntax: header ≤12 chars, label 1-5 words, add "(Recommended)" to default.
When to ask: Vague request ("configure opencode"), permission/security changes, or multiple valid options exist.
Ask the user what they want to configure:
Then guide them through the relevant section below.
{
"$schema": "https://opencode.ai/config.json",
"model": "anthropic/claude-sonnet-4-20250514",
"theme": "opencode",
"autoupdate": true
}
| Option | Purpose | Example |
|---|---|---|
model |
Default model | "anthropic/claude-sonnet-4-20250514" |
small_model |
Lightweight tasks | "anthropic/claude-3-5-haiku-20241022" |
theme |
UI theme | "opencode", "catppuccin", "dracula" |
autoupdate |
Auto-update OpenCode | true / false |
share |
Session sharing | "manual" / "auto" / "disabled" |
Control what requires approval using the permission field.
{
"permission": {
"edit": "allow", // "allow" | "ask" | "deny"
"bash": {
"npm *": "allow", // pattern matching
"git *": "allow",
"rm *": "ask",
"*": "ask" // default for this tool
},
"webfetch": "allow",
"skill": {
"*": "allow",
"dangerous-*": "deny"
}
}
}
Agents may occasionally work on legacy projects using outdated configuration fields (e.g., tools, maxSteps). You MUST correct these to the modern permission and steps fields when encountered.
Include additional instruction files:
{
"instructions": [
"CONTRIBUTING.md",
"docs/guidelines.md",
".cursor/rules/*.md"
]
}
Full schema reference: See references/config-schema.md
Project instructions for all agents. Similar to CLAUDE.md or Cursor rules.
Run /init in OpenCode to auto-generate based on project analysis.
# Project Name
This is a [framework] project using [language].
## Project Structure
- `src/` - Source code
- `tests/` - Test files
## Code Standards
- Use TypeScript strict mode
- Prefer functional patterns
- Write tests for all features
## Commands
- `npm run build` - Build project
- `npm test` - Run tests
OpenCode supports JSONC (JSON with comments). SHOULD comment out unused configs instead of deleting:
{
"plugin": [
"opencode-openai-codex-auth@latest",
//"@tarquinen/opencode-dcp@latest", // disabled for now
//"@howaboua/pickle-thinker@0.4.0", // only for GLM-4.6
"@ramtinj95/opencode-tokenscope@latest"
]
}
Why: You might want to re-enable later. Keeps a record of what you've tried.
After editing opencode.json, you MUST run this validation (not just suggest it):
opencode run "test"
Execute it yourself using the Bash tool before telling the user the change is complete.
If broken, you'll see a clear error with line number:
Error: Config file at ~/.config/opencode/opencode.json is not valid JSON(C):
--- Errors ---
CommaExpected at line 464, column 5
Line 464: "explore": {
^
--- End ---
Common JSONC mistakes:
}{
"$schema": "https://opencode.ai/config.json",
"model": "anthropic/claude-sonnet-4-20250514",
"permission": {
"edit": "ask",
"bash": "ask"
}
}
{
"$schema": "https://opencode.ai/config.json",
"model": "anthropic/claude-sonnet-4-20250514",
"autoupdate": true,
"permission": {
"edit": "allow",
"bash": {
"*": "allow",
"rm -rf *": "deny",
"sudo *": "ask"
}
},
"instructions": ["CONTRIBUTING.md"]
}
{
"$schema": "https://opencode.ai/config.json",
"model": "anthropic/claude-sonnet-4-20250514",
"share": "auto",
"instructions": [
"docs/development.md",
"docs/api-guidelines.md"
]
}
| Issue | Solution |
|---|---|
| Config not loading | Check JSON syntax, ensure valid path |
| Skill not found | Verify SKILL.md (uppercase), check frontmatter |
| Permission denied unexpectedly | Check global vs project config precedence |
references/config-schema.md - Full config options