Advanced OpenCode Agents and Automation

OpenCode's advanced setup controls who acts, which files and commands they can touch, and which external systems they can reach. Agents, permissions, MCP servers, commands, skills, and formatters all change the same thing: the work an AI session may attempt inside a repository.

Start with the base files, then add one boundary at a time. The often-misread doom_loop permission gets its own section below. Configuration details were checked against OpenCode's official docs on July 28, 2026.

Build the Basic Setup First

Advanced configuration will not rescue a weak base setup. Open the repository, run OpenCode, use /connect for a provider, and choose the model with /models. Run /init only when you want OpenCode to draft an AGENTS.md file for review.

The two main files have different jobs. AGENTS.md tells the agent what the project is, how it builds and tests, and which conventions it must follow. opencode.json sets providers, models, agents, tools, permissions, MCP servers, formatters, and other program behavior.

Try one read-only task before editing either file further. Ask OpenCode to locate a known function, name its callers, and cite every file it reads. Then use Plan for a small failing test. If those steps fail, fix the provider, model, or project context before adding more agents.

Use the Built-In Agents

OpenCode has two built-in primary agents. Build is the default and has all tools enabled. Plan is restricted: file edits and shell commands ask for approval. Switch between primary agents with Tab or the configured agent key.

Three built-in subagents handle narrower work. General can research and carry out multi-step tasks with broad tool access. Explore is a fast read-only code searcher. Scout is read-only and focuses on external docs and dependency source. A primary agent can call them, or you can name one with an @ mention.

Agent	Default Access	Use
Build	All tools	Scoped edits
Plan	Edits ask	Plan and review
Explore	Read-only	Code search
Scout	Read-only	Upstream research

Use the built-ins until a repeated job needs a different authority boundary. A named "senior engineer" agent with the same tools as Build only adds prompt text. A read-only reviewer earns its own definition because it cannot edit the code it judges.

Start from Permissive Defaults

OpenCode starts from permissive defaults when no permission config exists. Most permissions are allow. The doom_loop and external_directory guards default to ask. Reads default to allow, while .env files are denied by default.

Do not assume Plan makes the whole application read-only. Its edits and shell commands ask for approval, and the response still depends on your choice. Auto-approve can also alter the session's behavior. Check the active mode and config rather than relying on the agent name.

Permission actions are allow, ask, and deny. OpenCode applies them to tools such as read, edit, glob, grep, bash, task, external directories, web access, language-server calls, skills, questions, and doom_loop.

Write Ordered Permission Rules

Start from the task. Give a reviewer read and search access. A test writer may edit test paths and run one test command, while production code remains outside its authority. A docs agent can work without deployment or package-manager commands.

Pattern rules are evaluated in order, and the last matching rule wins. Put the broad wildcard first and the narrow exception after it. The order is part of the security boundary, so read the entire object during review.

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "review": {
      "mode": "subagent",
      "permission": {
        "edit": "deny",
        "webfetch": "deny",
        "bash": {
          "*": "ask",
          "git status *": "allow",
          "git diff *": "allow",
          "git log *": "allow"
        }
      }
    }
  }
}

The wildcard makes unknown shell commands ask. The later Git rules allow three read-only command families. Do not write "git *": "allow" for a reviewer, because that also matches commands that change branches, history, remotes, and the working tree.

An approval prompt is useful only when you inspect it. Check the parsed command, arguments, working directory, and affected path. A command named "test" may call a script that resets a database or rewrites snapshots.

Create a Bounded Custom Agent

Define a custom agent in opencode.json or a Markdown file. Project files live under .opencode/agents/; user-wide files live under ~/.config/opencode/agents/. A repository agent can be reviewed, changed, and kept in step with the code it governs.

Give the agent a concrete description so OpenCode knows when to call it. Set its mode to primary, subagent, or all. Add a model only when the job needs a different one. Keep the prompt short and put shared project facts in AGENTS.md.

---
description: Review code without changing files
mode: subagent
permission:
  edit: deny
  webfetch: deny
  bash:
    "*": ask
    "git diff *": allow
    "git log *": allow
---

Report correctness bugs with file and line evidence.
Do not edit files.

Test both allowed and forbidden actions. Ask the review agent to edit a file and confirm that OpenCode denies it. Ask it to run an unlisted command and confirm that the prompt appears. A config that looks right but permits the forbidden action has failed its main job.

Understand the doom_loop Permission

doom_loop is an OpenCode safety guard for recovery prompts when an agent appears stuck in a repeated tool call. It defaults to ask. Approving it lets the product try a recovery prompt; denying it stops that recovery path.

The permission only authorises a recovery prompt after the repeated call. Iteration caps, fresh-context retries, and proof of a different result require separate controls. External scripts that run OpenCode again are a separate automation pattern with their own limits, spend controls, clean state, and validation.

When the guard fires, inspect what repeated. The same failed command may mean the tool is missing. The same edit may mean the test and requirement conflict. Repeated reads can mean the task is too broad or the model has lost the goal.

• Stop after the same failure appears twice without new evidence.
• Read the current diff before approving a recovery attempt.
• Narrow the task or change the model when tool use is the problem.
• Escalate product and security decisions to a person.

Connect One MCP Server

MCP servers add tools from another service. OpenCode supports local servers started by a command and remote servers reached by URL. Remote servers can use headers or OAuth, and OpenCode provides commands to authenticate, list, debug, and log out of them.

Add one server that removes a current manual step. A read-only error tracker can expose open issues. A documentation server can answer API questions. Give it a narrow credential, keep secrets in environment references, and find out whether any tool can write before enabling it.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "docs": {
      "type": "remote",
      "url": "https://docs.example.com/mcp",
      "enabled": true
    }
  },
  "permission": {
    "docs_*": "ask"
  }
}

OpenCode warns that MCP tool definitions use model context. A large catalog can exceed the context limit before the agent reads much code. Disable servers you do not need, or hide their tools globally and allow them only on the agent with that job.

Use opencode mcp list to inspect status. For an OAuth server, use opencode mcp auth SERVER_NAME and opencode mcp logout SERVER_NAME. Do not commit a bearer token into opencode.json.

Add Commands, Skills, and Formatters

Custom commands store a repeated prompt and expose it through a slash command. Use one for a job with a stable input and output, such as reviewing the current diff against repository rules. A command can name an agent, model, file reference, or shell output.

Agent skills are folders with a SKILL.md file. OpenCode discovers project skills under .opencode/skills/ and compatible skill folders under .claude/ and .agents/. Skills load on demand, and their access can be allowed, denied, or set to ask by name pattern.

Formatters are disabled when the formatter setting is omitted. Enable built-ins with "formatter": true, or configure one by file extension and command. A formatter runs after OpenCode writes or edits a matching file, so enabling one can enlarge the diff.

Feature	Stores	Main Risk
Command	Repeated prompt	Stale task steps
Skill	Reusable workflow	Broad tool access
Formatter	Write hook	Large diffs
MCP server	External tools	Data and context

Review Configuration as Code

Review authority changes in every OpenCode config diff. A new wildcard, external directory, MCP server, skill path, formatter, or subagent can alter later sessions even when the current code diff is small. State that authority change in the pull request.

• Read the final merged permission order.
• Test one allowed action and one denied action.
• Check every new credential source and remote URL.
• Run the repository checks after formatters or tools change files.
• Remove agents, commands, and servers that no longer have an owner.

Then inspect the work product as if it came from an unsupervised contributor. Confirm the changed-file list, read the diff, run the checks outside the agent's own summary, and reject unexplained changes even when the final build passes.

The OpenCode local models guide covers Ollama, context sizing, and the network boundary. The OpenCode overview covers the basic fit, provider choice, and first task.

FAQ

What does doom_loop do in OpenCode?

The `doom_loop` permission gates recovery prompts when OpenCode thinks an agent is stuck in a repeated action. It defaults to `ask`. It authorises a recovery attempt after a repeated call; it provides no retry count or autonomous overnight loop. Review the repeated call before approving recovery.

Which OpenCode agent should plan a change?

Use Plan for analysis before edits. OpenCode documents Plan as a restricted primary agent whose edits and shell commands ask for approval. Build is the default primary agent with all tools enabled. Explore and Scout are read-only subagents for codebase and external-source research.

Where do custom OpenCode agents live?

Define agents in `opencode.json` or as Markdown files under `.opencode/agents/` for a project and `~/.config/opencode/agents/` for a user. Give each agent a description, mode, prompt, model only when needed, and explicit permissions. Repository agents can be reviewed with the code.

Do MCP servers use model context?

Yes. OpenCode warns that MCP tool definitions add to the model context and that a large tool catalog can exceed the context limit. Keep only the servers needed for the task enabled. Disable unused tools globally or expose a server only to the agent that needs it.

Boundaries Worth Keeping

OpenCode's advanced features pay off when each one creates a boundary you can name and test. Plan before Build, deny edits for reviewers, order wildcard rules carefully, and connect one MCP server only when its credential, tools, and context cost are understood.

Treat doom_loop as a recovery approval. Keep agents, commands, skills, formatters, and MCP servers in normal code review, and remove any configuration whose owner or purpose is no longer clear.