# 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.

### build

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

### plan

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`.

### general

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

### explore

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.

```jsonc
{
  "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.

```markdown
---
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:

```jsonc
{
  "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](/terminal/commands) covers `/agents` and the palette, [Permissions & privacy](/terminal/permissions-and-privacy) covers the rule syntax used above, and [Subagents](/editor/subagents) covers the editor's delegation model.