~/.config/opencode/
Global opencode.json, AGENTS.md, commands/, skills/, and plugins/. A crashing desktop app is often a plugin. Empty the plugin key and relaunch. See desktop troubleshooting.
01 / Capabilities
What the agent actually does
Every heading below is a named capability from the homepage, intro, TUI, agents, or permissions docs. To install, skip to the download page.
02 / Surfaces
Three surfaces, one agent
The homepage calls this “any editor”: a terminal interface, a desktop app, and an IDE extension. Desktop is the surface that added tabs for active sessions. The download page still lists Terminal first, then Desktop, then Extensions.
TUI config lives in tui.json (theme, keybinds, cursor, attention sounds). Runtime config lives in opencode.json. They are not the same file.
A blank desktop window on Windows is usually WebView2. That walkthrough is in guides.
03 / Models
Models, logins, and Zen
“Any model” means 75+ LLM providers through Models.dev, including local models. /connect adds a provider. Models are referenced as provider/model, for example openai/gpt-4.1 or opencode/kimi-k2.
| Path | What it is |
|---|---|
| /connect | Add a provider and paste an API key, or sign in to Copilot, ChatGPT, Claude, or Zen. |
| /models | Open the picker. Run opencode models in a shell to list what you can actually call. |
| OpenCode Zen | Handpicked models the project tested for coding agents, so provider quality is less of a lottery. |
| GitHub Copilot | Log in with GitHub. v1.18.31 requests summarized adaptive thinking for Copilot models. |
| ChatGPT Plus/Pro | Log in with OpenAI. v1.18.29 fixed gpt-6-astra visibility for OpenAI subscription users. |
| Local models | The homepage and FAQ both say you can connect local models through the same provider list. |
04 / Loop
The agent loop
- Tab · Plan / Build
- Build is the default primary agent with tools on. Plan is restricted: edit and bash default to ask or deny so the model can propose work without touching the tree.
- /init · AGENTS.md
- Guided setup that writes project rules. Commit the file. Global rules can also live in ~/.config/opencode/AGENTS.md.
- /undo · /redo
- Revert or restore the last user turn and its file changes. Git is required. You can undo more than once.
- /share · /unshare
- Publish a session for review or debugging. Conversations are not shared until you run the command.
05 / Permissions
Permissions are the safety rail
Since v1.1.1 the old tools boolean is folded into permission. Each rule is allow, ask, or deny. opencode --auto approves asks that are not denied.
- read / edit / bash / grep / glob
- File and shell tools. Patterns can allow
git *and denyrm *. - external_directory
- Fires when a tool leaves the working directory. Default is ask. 首页 expansion with ~ does not skip this guard.
- doom_loop
- Fires when the same tool call repeats three times with identical input. Default is ask.
- .env files
- read is allow, but
*.envand*.env.*default to deny.*.env.examplestays allow.
06 / Extend
MCP, agents, and project files
Config lives in well-known folders. These paths are the ones the cheatsheet actually names.
.opencode/ in the repo
Per-project config, commands, skills, and plugins. Agent markdown can set mode: subagent and deny edit so a reviewer cannot write files.
/mcp
Lists configured MCP servers and their connection status. Permission keys can target a server with patterns such as mymcp_*.
Desktop tabs
The download page headline: organize work and active sessions with tabs on macOS, Windows, and Linux.