Skip to content

Commit d0b50b6

Browse files
committed
docs: Add configuration directory locations documentation (Fixes anomalyco#4170)
1 parent 2a20822 commit d0b50b6

1 file changed

Lines changed: 248 additions & 0 deletions

File tree

Lines changed: 248 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,248 @@
1+
# Configuration Directory Locations
2+
3+
OpenCode stores its files in different directories depending on your operating system. Understanding where these files are located is important for configuration, backup, and troubleshooting.
4+
5+
## Overview
6+
7+
OpenCode follows the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) for Unix-like systems, and uses platform-specific conventions for Windows.
8+
9+
### Quick Reference
10+
11+
| Directory Type | Linux | macOS | Windows |
12+
|----------------|-------|-------|---------|
13+
| **Configuration** | `~/.config/opencode/` | `~/Library/Application Support/opencode/` | `%APPDATA%/opencode/` |
14+
| **Data/Credentials** | `~/.local/share/opencode/` | `~/Library/Application Support/opencode/` | `%LOCALAPPDATA%/opencode/` |
15+
| **Cache** | `~/.cache/opencode/` | `~/Library/Caches/opencode/` | `%LOCALAPPDATA%/Temp/opencode/` |
16+
| **State** | `~/.local/state/opencode/` | `~/Library/State/opencode/` | `%LOCALAPPDATA%/opencode/` |
17+
18+
## Configuration Directory (`~/.config/opencode/`)
19+
20+
**Purpose**: User preferences, settings, and customization files.
21+
22+
### What's stored here:
23+
24+
- **`opencode.json`** - Main configuration file
25+
- **`opencode.jsonc`** - Configuration with comments support (preferred)
26+
- **`config.json`** - Legacy configuration file (auto-migrated)
27+
- **`themes/`** - Custom theme files (`*.json`)
28+
- **`agents/`** - Custom agent definitions (`*.md`)
29+
- **`commands/`** - Custom commands (`*.md`)
30+
- **`plugins/`** - Local plugin files (`*.ts`, `*.js`)
31+
- **`tools/`** - Custom tool definitions
32+
- **`skills/`** - Custom skills (`<name>/SKILL.md`)
33+
34+
### Files you should preserve:
35+
36+
- `opencode.json` or `opencode.jsonc` - Your settings
37+
- `themes/` - Custom themes
38+
- `agents/` - Custom agent configurations
39+
- `commands/` - Custom command templates
40+
41+
### Environment Variables:
42+
43+
- `$XDG_CONFIG_HOME/opencode/` - If `XDG_CONFIG_HOME` is set
44+
- Otherwise: `$HOME/.config/opencode/`
45+
46+
### Windows:
47+
48+
- `%APPDATA%\opencode\` (usually `C:\Users\<user>\AppData\Roaming\opencode\`)
49+
50+
### macOS:
51+
52+
- `~/Library/Application Support/opencode/`
53+
54+
## Data Directory (`~/.local/share/opencode/`)
55+
56+
**Purpose**: Persistent data, authentication credentials, and session information.
57+
58+
### What's stored here:
59+
60+
- **`auth.json`** - API keys and authentication tokens
61+
- **`mcp-auth.json`** - MCP server authentication
62+
- **`opencode.db`** - SQLite database for sessions and messages
63+
- **`log/`** - Application logs
64+
- **`sessions/`** - Session history and state
65+
66+
### ⚠️ Important:
67+
68+
- Contains **sensitive authentication data**
69+
- **Do not share** this directory
70+
- Backup this directory to preserve sessions and credentials
71+
- On reinstall, restore this directory to keep your data
72+
73+
### Environment Variables:
74+
75+
- `$XDG_DATA_HOME/opencode/` - If `XDG_DATA_HOME` is set
76+
- Otherwise: `$HOME/.local/share/opencode/`
77+
78+
### Windows:
79+
80+
- `%LOCALAPPDATA%\opencode\` (usually `C:\Users\<user>\AppData\Local\opencode\`)
81+
82+
### macOS:
83+
84+
- `~/Library/Application Support/opencode/` (same as config on macOS)
85+
86+
## Cache Directory (`~/.cache/opencode/`)
87+
88+
**Purpose**: Temporary files and cached data that can be regenerated.
89+
90+
### What's stored here:
91+
92+
- Downloaded model files
93+
- Compiled assets
94+
- Temporary processing files
95+
- `version` - Cache version marker
96+
97+
### Notes:
98+
99+
- **Safe to delete** - OpenCode will regenerate as needed
100+
- Clears automatically on version updates
101+
- Can be cleared to free up disk space
102+
103+
### Environment Variables:
104+
105+
- `$XDG_CACHE_HOME/opencode/` - If `XDG_CACHE_HOME` is set
106+
- Otherwise: `$HOME/.cache/opencode/`
107+
108+
### Windows:
109+
110+
- `%LOCALAPPDATA%\Temp\opencode\`
111+
112+
### macOS:
113+
114+
- `~/Library/Caches/opencode/`
115+
116+
## State Directory (`~/.local/state/opencode/`)
117+
118+
**Purpose**: Application state that persists across sessions.
119+
120+
### What's stored here:
121+
122+
- Application state files
123+
- UI preferences
124+
- Window positions and sizes
125+
126+
### Notes:
127+
128+
- Can be cleared if UI state issues occur
129+
- Generally safe to delete, settings will reset to defaults
130+
131+
### Environment Variables:
132+
133+
- `$XDG_STATE_HOME/opencode/` - If `XDG_STATE_HOME` is set
134+
- Otherwise: `$HOME/.local/state/opencode/`
135+
136+
### Windows:
137+
138+
- Stored in `%LOCALAPPDATA%\opencode\`
139+
140+
### macOS:
141+
142+
- `~/Library/State/opencode/`
143+
144+
## Installation Directory
145+
146+
**Purpose**: OpenCode executable and bundled files.
147+
148+
### Locations:
149+
150+
| Installation Method | Default Location |
151+
|---------------------|------------------|
152+
| **npm/bun/pnpm** | `~/.npm-global/lib/node_modules/opencode-ai/` |
153+
| **Homebrew** | `/usr/local/opt/opencode/` (Intel) <br> `/opt/homebrew/opt/opencode/` (Apple Silicon) |
154+
| **install script** | `$OPENCODE_INSTALL_DIR` (if set) <br> `$XDG_BIN_DIR` (if set) <br> `~/.local/bin` <br> `~/.opencode/bin` (default fallback) |
155+
| **System-wide** | `/usr/local/bin/opencode` |
156+
157+
### Environment Variables:
158+
159+
- `$OPENCODE_INSTALL_DIR` - Override installation directory
160+
- `$XDG_BIN_DIR` - XDG-compliant binary directory
161+
162+
## Project Configuration
163+
164+
OpenCode also reads project-specific configuration from your working directory:
165+
166+
### In your project folder:
167+
168+
- **`.opencode/opencode.json`** - Project-level configuration
169+
- **`.opencode/agents/`** - Project-specific agents
170+
- **`.opencode/commands/`** - Project-specific commands
171+
- **`.opencode/plugins/`** - Project plugins
172+
173+
### Configuration Precedence (lowest to highest):
174+
175+
1. Remote `.well-known/opencode` (organization defaults)
176+
2. Global config (`~/.config/opencode/opencode.json`)
177+
3. Custom config (`$OPENCODE_CONFIG`)
178+
4. Project config (`opencode.json` in workspace)
179+
5. `.opencode` directories (project and global)
180+
6. Inline config (`$OPENCODE_CONFIG_CONTENT`)
181+
7. **Managed config** (enterprise admin-controlled, always overrides)
182+
183+
## Backup Recommendations
184+
185+
### What to backup:
186+
187+
```bash
188+
# Configuration
189+
~/.config/opencode/opencode.json
190+
~/.config/opencode/themes/
191+
~/.config/opencode/agents/
192+
~/.config/opencode/commands/
193+
194+
# Data (if you want to preserve sessions/credentials)
195+
~/.local/share/opencode/
196+
```
197+
198+
### What NOT to backup (regeneratable):
199+
200+
```bash
201+
# Safe to skip - these regenerate
202+
~/.cache/opencode/
203+
~/.local/state/opencode/
204+
```
205+
206+
## Troubleshooting
207+
208+
### Find where OpenCode stores files:
209+
210+
```bash
211+
# Check environment variables
212+
echo "Config: $XDG_CONFIG_HOME/opencode/"
213+
echo "Data: $XDG_DATA_HOME/opencode/"
214+
echo "Cache: $XDG_CACHE_HOME/opencode/"
215+
216+
# Or use OpenCode commands
217+
opencode --version
218+
opencode debug paths # If available
219+
```
220+
221+
### Common issues:
222+
223+
**"Config file not found"**
224+
- Check if `~/.config/opencode/opencode.json` exists
225+
- Create it manually if needed
226+
227+
**"Permission denied" errors**
228+
- Check directory permissions
229+
- Ensure you own the config/data directories
230+
231+
**Lost settings after reinstall**
232+
- Backup `~/.config/opencode/` before uninstalling
233+
- Restore after reinstall
234+
235+
## Migration from Legacy Locations
236+
237+
If you installed OpenCode before version 1.0, your configuration might be in legacy locations:
238+
239+
| Old Location | New Location |
240+
|--------------|--------------|
241+
| `~/.opencode/opencode.json` | `~/.config/opencode/opencode.json` |
242+
| `~/.opencode/config.toml` | `~/.config/opencode/config.json` |
243+
244+
OpenCode will automatically migrate these files on first run.
245+
246+
## Contributing
247+
248+
Found incorrect information? Want to add more details? Please contribute to [anomalyco/opencode](https://github.com/anomalyco/opencode) by opening a PR to update this documentation.

0 commit comments

Comments
 (0)