OpenWriterControle/dev/ai-tools/opencode/how-context-works.md

OpenCode File Structure & Reference Guide

Directory Structure

Global Config (~/.config/opencode/)

~/.config/opencode/
├── opencode.json          # Global config
├── AGENTS.md              # Auto-loaded instructions
├── CLAUDE.md              # Auto-loaded instructions
├── agent/                 # Custom agents
│   ├── my-agent.md
│   └── category/
│       └── nested-agent.md
├── command/               # Custom commands
│   └── my-command.md
└── plugin/                # Custom plugins
    └── my-plugin.ts

Local Repo (.opencode/)

your-repo/
├── opencode.json          # Repo config
├── .opencode/
│   ├── AGENTS.md          # Auto-loaded instructions
│   ├── agent/             # Project-specific agents
│   │   └── my-agent.md
│   ├── command/           # Project-specific commands
│   │   └── my-command.md
│   └── plugin/            # Project-specific plugins
│       └── my-plugin.ts
└── src/

Auto-Loaded Files

Instruction files (loaded automatically as system prompts):

• AGENTS.md - Custom instructions (global or local)
• CLAUDE.md - Legacy Claude instructions
• CONTEXT.md - Deprecated, but still works

Config files (merged in order):

1. ~/.config/opencode/opencode.json (global)
2. opencode.json files from repo root up to current directory
3. Files from .opencode/ folders in hierarchy

Supported Subfolders

Folder	Files	Purpose
agent/	*.md	Custom agents with system prompts
command/	*.md	Custom slash commands
plugin/	*.ts, *.js	Custom tools and extensions

⚠️ Use singular names only: agent/, NOT agents/

File References with @ Symbol

In commands and templates:

# Relative to repo root
@README.md
@src/main.ts

# Home directory
@~/my-file.txt

# Absolute path
@/absolute/path/file.txt

# If file doesn't exist, looks for agent
@my-agent

Resolution order:

1. Check if starts with ~/ → resolve to home directory
2. Check if absolute path → use as-is
3. Otherwise → resolve relative to repo root (Instance.worktree)
4. If not found → look for agent with that name

Custom Instruction Files

For arbitrary paths, use instructions field:

{
  "instructions": [
    "~/opencode/context/my-context.md",
    "docs/**/*.md",
    ".opencode/context/**/*.md"
  ]
}

Paths can be:

• Absolute: /path/to/file.md
• Home relative: ~/path/to/file.md
• Repo relative: docs/instructions.md
• Glob patterns: **/*.md

Config Merging

Configs merge with priority (later overrides earlier):

1. Global config (~/.config/opencode/)
2. Repo root configs (from root up)
3. Custom config directories (.opencode/ folders)
4. Environment variables (OPENCODE_CONFIG)

Agents, commands, and plugins from all locations are merged together.

Quick Reference

What	Where	How
Global agent	~/.config/opencode/agent/name.md	Auto-loaded
Local agent	.opencode/agent/name.md	Auto-loaded
Global command	~/.config/opencode/command/name.md	Auto-loaded
Local command	.opencode/command/name.md	Auto-loaded
Global instructions	~/.config/opencode/AGENTS.md	Auto-loaded
Local instructions	.opencode/AGENTS.md or AGENTS.md	Auto-loaded
Custom files	Anywhere	Use instructions config or @ symbol