Agents & subagents

An agent is a named working style: its own instructions, its own model, and its own permission rules. V3Code Terminal ships with four you can use immediately, and you can add your own as a markdown file.

The built-in agents

Two are primary agents — the one you’re talking to. Two are subagents, which the primary agent delegates to.

buildprimary · default

The default agent. It runs tools according to your configured permissions — reading, editing, running commands, and verifying work.

planprimary

Plan mode. Every edit tool is denied, so it can research and design without touching your files. The one exception is writing the plan itself into .opencode/plans/*.md.

generalsubagent

General-purpose worker for researching complex questions and running multi-step tasks. Use it to run several units of work in parallel.

exploresubagent

A fast, read-only codebase explorer. Its permissions allow only grep, glob, list, bash, read, webfetch, and websearch — everything else is denied, so it can’t change anything. Tell it how thorough to be: quick, medium, or very thorough.

A few more agents exist but stay hidden because the app drives them for you: compaction (condensing a long session), title (naming sessions), and summary.

Switching agents

Input	Result
/agents	Open the agent switcher.
Tab / Shift+Tab	Move to the next or previous agent without leaving the prompt.
@name	Mention a subagent by name in your message.

To change the default for a project, set default_agent in your configuration.

{
  "default_agent": "build",
}

Plan before you build

When a request looks like it needs design work first, the agent can offer to switch you into plan. It asks — it doesn’t move you silently. If you explicitly say you want a plan, it offers the switch first, before doing anything else.

Plan mode is worth reaching for when a task spans multiple files or involves an architectural decision. For a small, obvious fix it just adds a step.

Delegating to subagents

The primary agent delegates with its task tool, choosing which subagent type to use. This is how a big job gets split up.

What’s worth knowing as a user:

• Several subagents can run at once, which is the point — independent questions get answered in parallel.
• Each one starts with a fresh context. It cannot see your conversation, so the instructions it receives have to be self-contained.
• A returned task_id can be reused to continue that same subagent session later, instead of starting over.
• Its output isn’t shown to you directly. The primary agent reads the result and reports back, so you get a summary rather than a transcript.

Note

Subagents run in your working tree, not in a sandbox of their own. When two of them would edit the same files, give them separate areas — or separate worktrees.

Write your own agent

Create a markdown file in an agent/ (or agents/) folder inside your config directory — .v3code/agent/reviewer.md in a project, or under ~/.config/v3code/ for every project. The frontmatter configures it; the body becomes its prompt.

---
description: Reviews changes for correctness and security. Use before a PR.
mode: subagent
model: anthropic/claude-sonnet-4-5
temperature: 0.1
color: warning
permission:
  edit: deny
  bash:
    "*": ask
    "git diff*": allow
---

You review code changes. Focus on real defects, missing error handling,
and anything that touches auth or user input. Be specific and cite files.

The fields you’ll reach for most:

Field	What it does
description	When this agent should be used. Required for subagents to be picked well.
mode	primary, subagent, or all.
model / variant	Pin this agent to a specific model.
temperature, top_p	Sampling controls.
permission	Per-agent permission rules — the safest way to constrain an agent.
steps	Maximum agentic iterations before it must answer in text.
hidden	Keep a subagent out of the @ autocomplete menu.
disable	Turn the agent off without deleting the file.
color	A hex value like #FF5733, or a theme color such as primary or warning.

Note

tools is deprecated in favour of permission. It still works — a tools list is accepted and converted — but new agents should use permission, which is more expressive.

You can also override a built-in agent from configuration, without writing a file:

{
  "agent": {
    "plan": { "model": "anthropic/claude-opus-4-1" },
  },
}

Sharing agents with the editor

Agent files written for the V3Code editor load in the terminal too. The editor declares tools as a list of names; the terminal converts that into its own permission map automatically, so a shared .v3code/ folder works in both products. Editor-only tool names simply won’t match anything here.

A broken or foreign agent file is skipped with a warning — one bad file never stops the app from starting.

Related

Commands & shortcuts covers /agents and the palette, Permissions & privacy covers the rule syntax used above, and Subagents covers the editor’s delegation model.