|
| 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