Sessions and Agents

Sessions

A session is a conversation between you and an AI agent. Sessions are owned by the background service and persisted in SQLite via Drizzle ORM.

Key session properties:

Each session has a unique ID, a location (working directory), an agent, and a model
Sessions persist across service restarts through durable history
The SessionRunner coordinates execution, message generation, and tool dispatch
Sessions support undo/redo via filesystem snapshots and conversation reversion
Subagents create child sessions, navigable with session_child_first and session_parent keybinds

// Session creation via the client
const session = await client.session.create({
  location: { directory: "/workspace" },
})

Agents

Agents are specialized AI assistants with their own model, system prompt, permissions, and mode. OpenCode ships with built-in agents and supports custom agents via config or markdown files.

Agent Types

Type	Description
`primary`	Main assistants you interact with directly. Cycle with Tab.
`subagent`	Invoked by primary agents for specialized tasks. Also @mentionable.

Built-in Agents

Agent	Mode	Role
build	primary	Default agent with all tools enabled
plan	primary	Restricted: edits and bash set to `ask` by default
general	subagent	Full tool access for multi-step research tasks
explore	subagent	Read-only codebase exploration
scout	subagent	Read-only external docs and dependency research
compaction	primary (hidden)	Compacts long context automatically
title	primary (hidden)	Generates session titles
summary	primary (hidden)	Creates session summaries

Tip: If you don’t specify a model for a subagent, it inherits the model from the primary agent that invoked it.

Custom Agents

Define agents in opencode.json(c) or as markdown files in .opencode/agents/:

{
  "agents": {
    "reviewer": {
      "description": "Review changes without editing files",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-5#high",
      "system": "Focus on correctness, security, and missing tests.",
      "permissions": [
        { "action": "edit", "resource": "*", "effect": "deny" }
      ]
    }
  }
}

Or as markdown:

---
description: Reviews code for quality
mode: subagent
model: anthropic/claude-sonnet-4-5
permission:
  edit: deny
  bash:
    "git diff *": allow
    "git status *": allow
---

Focus on correctness, security, and missing tests.

Agent Options

Option	Description
`description`	Required. What the agent does.
`mode`	`primary`, `subagent`, or `all` (default)
`model`	`provider/model-id` with optional `#variant`
`system`	System prompt (V2 name; V1 used `prompt`)
`permissions`	Ordered permission rules (V2 array format)
`temperature`	0.0-1.0 randomness control
`top_p`	Alternative to temperature for diversity
`steps`	Max agentic iterations before forced text-only response
`disabled`	Disable the agent (V2 name; V1 used `disable`)
`hidden`	Hide from @ autocomplete (subagents only)
`color`	Hex color or theme color for UI

Gotcha: V2 renames several agent fields: prompt becomes system, disable becomes disabled, and a separate variant joins the model reference after # (e.g. anthropic/claude-sonnet-4-5#high).