OpenCode Config: AGENTS.md, opencode.json Permissions, MCP, Skills

OpenCode reads AGENTS.md by walking up from the current directory, falls back to CLAUDE.md if there is no AGENTS.md, and adds global ~/.config/opencode/AGENTS.md (or ~/.claude/CLAUDE.md). Configuration is opencode.json in the project or ~/.config/opencode/opencode.json: mcp for servers, permission for allow / ask / deny rules (the last matching rule wins), instructions for extra files. Skills load from .opencode/skills, .claude/skills and .agents/skills. ChatGPT Plus and GitHub Copilot subscriptions work out of the box; Claude Pro/Max is not supported because Anthropic prohibits it.

OpenCode at a glance

Global instructions	✓ Yes `~/.config/opencode/AGENTS.md`, else `~/.claude/CLAUDE.md`
Project instructions	✓ Yes `AGENTS.md` (else `CLAUDE.md`) found by traversing up from cwd; `instructions` array in opencode.json
Nested / subfolder	◐ Partial Parent directories by traversing up; first match wins
AGENTS.md	✓ Yes Primary format
Skills (SKILL.md)	✓ Yes `.opencode/skills/`, `.claude/skills/`, `.agents/skills/`; global `~/.config/opencode/skills/`, `~/.claude/skills/`, `~/.agents/skills/`
MCP config	✓ Yes `mcp` key in `opencode.json` / `opencode.jsonc` (project or `~/.config/opencode/`)
Permissions / allowlist	✓ Yes `permission` in opencode.json: allow / ask / deny per tool (bash, edit, webfetch, external_directory…) with wildcards; last matching rule wins
Sandbox	? Not documented Not documented
Hooks	✓ Yes Plugins in `.opencode/plugins/` subscribe to events such as tool execution
Claude Pro/Max login	✕ No Not supported: Anthropic prohibits Claude Pro/Max in third-party tools; OpenCode removed those plugins in v1.3.0
ChatGPT Plus/Pro login	✓ Yes ChatGPT Plus works with zero setup (also GitHub Copilot, GitLab Duo)
API key / own plan	✓ Yes 75+ providers via API keys, local models

Exact file paths

Path	Scope	What it does
`AGENTS.md`	Project	Instructions (CLAUDE.md fallback)
`~/.config/opencode/AGENTS.md`	User	Global instructions
`opencode.json / opencode.jsonc`	Project	permission, mcp, instructions, provider
`~/.config/opencode/opencode.json`	User	Global config
`.opencode/plugins/`	Project	Plugins / hooks
`.opencode/skills/<name>/SKILL.md`	Project	Skills (also .claude/skills, .agents/skills)

Using a shared AGENTS.md with OpenCode

Native. If CLAUDE.md also exists, OpenCode uses only AGENTS.md. See one AGENTS.md for every agent, or generate one with the AGENTS.md generator.

Copy-paste examples

MCP server

File: opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

Turn off Claude Code compatibility

File: shell

export OPENCODE_DISABLE_CLAUDE_CODE=1   # ignore CLAUDE.md and .claude/skills

Safe permissions preset

Safe opencode.json permissions

File: opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "webfetch": "ask",
    "bash": {
      "*": "ask",
      "git status*": "allow",
      "git diff*": "allow",
      "npm test*": "allow",
      "rm -rf *": "deny",
      "sudo *": "deny",
      "git push --force*": "deny",
      "git push -f*": "deny",
      "git reset --hard*": "deny",
      "*DROP TABLE*": "deny",
      "terraform destroy*": "deny"
    }
  }
}

OpenCode applies the LAST matching rule, so keep the catch-all * first and put deny rules at the end. * matches zero or more of any character.

Gotchas

If both AGENTS.md and CLAUDE.md exist, only AGENTS.md is used.
Permission rules are last-match-wins, the opposite of Claude Code's deny-first model.
Older guides mention Claude Pro/Max plugins; OpenCode removed them in v1.3.0 and Anthropic prohibits that use.

FAQ

Can I use Claude Max with OpenCode?

No. OpenCode's provider docs say Anthropic prohibits using Claude Pro/Max through third-party plugins, and OpenCode stopped bundling them in v1.3.0. Use an Anthropic API key, or a ChatGPT Plus or GitHub Copilot subscription, which OpenCode supports.

Does OpenCode read CLAUDE.md?

Yes, as a fallback: CLAUDE.md in the project is used only if there is no AGENTS.md, and ~/.claude/CLAUDE.md only if there is no ~/.config/opencode/AGENTS.md. Set OPENCODE_DISABLE_CLAUDE_CODE=1 to turn this off.

Sources

Checked against these official pages on 2026-10-12. Cells marked "Not documented" mean we could not find the behaviour in these docs; it may still exist.

OpenCode configuration guide: instruction files, MCP, permissions