Guides for OpenCode: instructions, sessions and permissions

OpenCode is an open-source coding agent that runs as a terminal interface, a desktop app, a web app, and IDE integrations. It is also two products at once. V1 still gets releases and its documentation is at opencode.ai/docs. V2 is the current line, installed as @opencode/cli, with its own documentation at opencode.ai/v2/docs. Both use the opencode command, and they cannot be installed side by side under that command.

That split is behind a lot of the confusion these guides cover. The same problem has a different answer depending on which line you are on, and sometimes the field name alone is the answer.

Run opencode --version before you use a page here. A 1.x version is V1. A 2.x version is V2. Most pages lead with V2 and keep the V1 answer for people who still need it.

Checked against OpenCode's documentation on 27 October 2026.

Which line are you on?#

V2 is the current answer, but V1 is not abandoned: it was still getting releases in October 2026. The fastest way to tell them apart is the config shape.

If you paste a V1 block into V2, or the other way round, the setting can sit in the file without ever being read. That is not a bug in the rule; it is a rule in a language the other line does not speak. MCP here means the Model Context Protocol, the standard way OpenCode connects external tools and data sources.

Each guide says which line a fact applies to. Where the lines differ, the V2 answer comes first.

Start with the problem#

Why OpenCode ignores your AGENTS.md — Which files each line loads, what changed in V2, why a nested file or a configured instructions entry can be missing, and how to prove what reached the model instead of asking the model whether it read the file.

Where did my OpenCode session go? — Sessions are rows in a local SQLite database, grouped by project, and the picker is narrower than the database. This guide covers the V2 commands, the V1-to-V2 global project trap, renamed directories, and how to export or back up a session before you move it.

Why OpenCode permission rules don't fire — When a deny does not block, the usual cause is that the rule never matched, a later rule won, or the action is being checked against a different path form. This guide covers V1 object order, the V2 array, the external_directory default change, and the checks that show the effective rules.

Also in this set#

• What /undo really reverts in OpenCode — conversation rollback and the snapshot store are two different things, and neither is a backup.
• Why your OpenCode plugin or hook isn't running — where plugins load, which surface they load on, and how to prove a hook fired. A hook is a function that runs at a set point in a session.
• Context compaction: what your coding agent drops — what a long session loses when older turns are replaced by a summary, and how to re-anchor after it. The page covers OpenCode alongside the other major agents.

Memory, handoff and the other agents#

OpenCode does not document a built-in memory store that learns across sessions. Durable rules belong in AGENTS.md or the instructions array; task state belongs in a handoff file. Persistent memory for Claude Code and Codex compares the mechanisms, including what OpenCode does and does not have.

Hand off work between Claude Code and Codex is the written baton for work that moves between tools, sessions, or machines. It is also the right page when you are bringing a Claude Code setup across to OpenCode.

If you are coming from the other tools, the Claude Code guides cover nested CLAUDE.md files, auto memory, sessions, permissions, and hooks; the Codex guides cover AGENTS.md loading, config, approvals, sessions, hooks, and undo; the GitHub Copilot CLI guides cover instruction loading, sessions, custom agents, permissions, and hooks; the Gemini CLI guides cover GEMINI.md and AGENTS.md loading, sessions, permissions, models, skills, and hooks; the Qwen Code guides cover the same ground for the Gemini CLI fork; the Cursor guides cover Cursor's rules, skills, chat history, permissions, hooks and MCP. The OpenCode pages here are the counterparts, not copies: the mechanisms and the failure modes are different.

Where to start#

If OpenCode is ignoring a rule, start with AGENTS.md. If the work disappeared, start with session resume. If a command ran when it should have been blocked, start with permissions. The order is deliberate: instructions, then the session that carries them, then the rules that are supposed to stop them.