#Architecture & Runtime

This chapter explains how OpenCode completes a task: config merge, agent tool selection, and how Plan/Build split work via permissions.

#1. Agent Execution Loop

The TUI session is a typical tool-augmented agent loop:

flowchart LR
  A[User input] --> B[Load config + AGENTS.md]
  B --> C[Primary agent reasoning]
  C --> D{Call tool?}
  D -->|Yes| E[Permission check ask/allow/deny]
  E --> F[Run read/edit/bash/MCP/LSP...]
  F --> G[Return result to model]
  G --> C
  D -->|No| H[Reply to user]
  C --> I{Delegate subagent?}
  I -->|task tool| J[Child session Explore/General...]
  J --> G

Unlike pure chat, state lives in tool output and LSP diagnostics, and every tool call passes through permission gates.

#2. Primary vs Subagent

#Primary agents

• Switch with Tab (Build / Plan)
• Own the main conversation thread
• Configured under agent.build, agent.plan, etc. in opencode.json

#Subagents

• Delegated via the task tool or manually with @explore
• Can spawn child sessions; navigate with arrow keys:
  • Enter child: default Leader+Down
  • Between children: Right / Left
  • Back to parent: Up

Intent: Explore/Scout stay read-only so the main thread is not flooded with glob/grep output; General handles parallel subtasks.

#3. Configuration Merge Order

OpenCode loads config from several sources and shallow-merges (later keys win):

1. Remote config (.well-known/opencode, org defaults)
2. Global ~/.config/opencode/opencode.json
3. File pointed to by OPENCODE_CONFIG
4. Project root opencode.json (walk up to Git root)
5. .opencode/ directory (agents, commands, plugins, skills…)
6. Inline JSON from OPENCODE_CONFIG_CONTENT
7. Managed config (enterprise, macOS, etc.)
8. MDM .mobileconfig (highest priority, user cannot override)

In practice:

• Personal prefs → global
• Team rules → project opencode.json + AGENTS.md
• Enterprise policy → remote / managed

TUI appearance and keybindings live in tui.json, separate from opencode.json.

#4. Permission System

Permissions are central—they replace older simple tools: true/false flags.

Each permission key gates a tool group:

Values:

• allow — run silently
• ask — prompt for approval
• deny — disabled

Plan agent defaults use ask or deny for edit, bash, etc.—“talk, don’t touch.”

Bash command rules are supported:

"bash": {
  "*": "ask",
  "git status*": "allow",
  "git diff*": "allow"
}

More specific rules override earlier * matches.

#5. Multi-session

OpenCode can run multiple sessions in one project, e.g.:

• Session A: Plan a feature
• Session B: Build a bugfix
• Session C: Explore-only code search

Useful when long tasks should not interfere. Parallel Build sessions may cause Git conflicts—use branches or serialize merges.

#6. Headless Mode

Good for a shared agent gateway or CI integration.

#7. Privacy Model

OpenCode states it does not store your code or context (see official FAQ). Data still flows through:

• Your chosen LLM provider (cloud API)
• Local LSP / MCP processes

For compliance:

• Use offline local models where required
• Disable unnecessary websearch
• Audit MCP server permissions

#8. Mental Model

#Next Steps

• Agents & Permissions
• AGENTS.md & Project Init
• Config & CLI Reference