OpenCode

OpenCode is a terminal-native coding-agent harness. This entry covers its instruction loading, agent modes, and permission boundaries, not the behavior of the model selected for a session.

• Put repository-wide conventions in a root AGENTS.md, and add narrower AGENTS.md files closer to code that needs scoped guidance.
• Keep personal preferences in the global instruction location and project requirements in the repository so their scopes remain legible.
• Use the read-only plan agent for exploration and planning; use build when the task is authorized to edit files, and verify the active agent and permissions before execution.
• Define reusable project agents in .opencode/agent/ or .opencode/agents/ with an explicit purpose, mode, and permission policy.
• Set per-agent permissions deliberately with allow, ask, or deny, especially for edit, bash, task, and external_directory operations. Review broad wildcard rules and their ordering before running an agent.

• Assuming CLAUDE.md is an OpenCode V2 instruction-file fallback; use the documented AGENTS.md mechanism for OpenCode guidance.
• Treating global and project instructions as a conflict-resolution system. OpenCode combines applicable files, so resolve contradictions in the files themselves.
• Giving an agent broad shell, edit, subagent, or external-directory access when a narrower permission policy is sufficient.
• Attributing agent mode, instruction discovery, or permission behavior to the model.

OpenCode's built-in plan and build agents represent harness modes. Custom agents can be primary or subagents, and their permissions should describe the smallest set of operations required by their role. Keep prompts and permissions aligned: a read-only reviewer should not receive edit or shell access merely because the selected model can use those tools.

OpenCode instruction discovery is scope-sensitive and does not provide a general precedence rule for resolving contradictory instructions. Confirm the current agent configuration and permissions before relying on behavior in a long-running or automated session.