Docs › Agent
Subagents and background tasks
Let the agent hand work to subagents that run at the same time, each with its own context, and write your own as Markdown files.
A subagent is a separate agent with its own context. The agent gives it one task, it works on that alone, and its report comes back to the agent that started it. Several can run at the same time, so three questions about a codebase are answered together instead of one after another, and the main conversation receives conclusions rather than every file each one read.
How they run
Subagents run in the background by default: the agent carries on, and is told when each one finishes. If the chat is idle by then, it is woken with the report. Each subagent is one card in the chat, with its own reads, commands and edits inside it, its step count, model and cost, and buttons to Stop it, open its transcript, send it a follow-up with Continue, or move a foreground one to the background (Ctrl+B, Cmd+B on a Mac).
Up to four run at once in one chat; more wait their turn rather than being refused. A subagent can start subagents of its own, three levels deep at most. Neither can be given more than the agent that started it: the tools a subagent is offered and the approvals it needs are at most its parent's, never more.
The built-in agents
| Agent | What it is for |
|---|---|
| `general-purpose` | Anything; it has the tools the agent has. Used when no agent is named. |
| `explore` | Finding things fast without changing anything: reading, searching and the language server, on the fast model tier. |
| `plan` | Read-only research that ends in a step-by-step plan. In plan mode, only read-only agents like this one can be started. |
| `verify` | Checking work: reading, plus running commands such as the tests. |
Asking for one
The agent decides when to delegate. You can ask in words ("use three agents to check each package"), or type @ and an agent's name in the composer to have that agent do the work.
Writing your own
An agent is a Markdown file: frontmatter that says what it is and may use, and a body that is its role. Put it in .astracode/agents/ in the project, or in ~/.astracode/agents/ for every project. Files you already have in .claude/agents/ are read as they are. A project's own agent folders are read only once you trust the folder. Customize, Agents in AstraCode Settings lists every agent with the file it came from, creates one from a form, and can draft one from a sentence; /agents in the composer opens it.
---
name: test-auditor
description: Finds code paths with no test that would fail if they broke. Use after a change, before review.
tools: Read, Grep, Glob, Bash
model: fast
color: green
---
You audit tests. For each function changed on this branch, say which test
would fail if it broke, or that none would. Report a list, nothing else.| Field | What it does |
|---|---|
| `name`, `description` | Required. The description is what the agent reads to decide when to use it, so say when, not only what. |
| `tools`, `disallowedTools` | What it may use, by AstraCode's tool names or Claude Code's (`Read`, `Grep`, `Glob`, `Edit`, `Write`, `Bash`, `WebFetch`, `WebSearch` and the rest are mapped). `Agent(a, b)` limits which agents it may start. Leave `tools` out to give it everything it is allowed. |
| `model` | `inherit` (the default), `fast` or `strong`. Claude Code's `haiku` is fast, `sonnet` inherits, `opus` is strong. An exact model id is used only when you bring your own API key. |
| `permissionMode` | Can only make it stricter than the agent that starts it: `plan` keeps it read-only, `dontAsk` refuses anything that would ask you. |
| `maxTurns` | Steps before it stops (50 by default; 30 for explore, plan and verify). |
| `background` | `true` always runs it in the background. |
| `isolation` | `worktree` gives it its own git worktree, removed afterwards if it changed nothing; `remote` runs it in [GitHub Actions](/docs/agent/remote-agents/). |
| `skills`, `mcpServers`, `hooks`, `memory`, `effort`, `color` | Skills to load into its role, the connectors it may use (or its own, started with it), hooks for its tool calls only, a memory folder of its own, the reasoning effort, and its card's colour. |
Background work and the Tasks panel
Subagents, commands left running (a dev server, a watcher) and monitors are tasks. The Tasks count above the composer, or /tasks, opens a panel listing this chat's tasks, with their output, a Stop for each, and Stop all. The chat's own Stop ends the reply and any subagent it is waiting on, and leaves background tasks running: stop those from the panel or their card. When a background task ends, the agent that started it is told, with the report or the last lines of output.
Settings
| Setting | Default | What it does |
|---|---|---|
| `astracode.agent.subagents` | on | Whether the agent may start subagents at all. |
| `astracode.agent.maxConcurrentAgents` | 4 | How many run at once in one chat, up to 20. |
| `astracode.agent.maxAgentDepth` | 3 | How deep they may nest; 1 means a subagent starts none of its own. |
| `astracode.agent.backgroundAgents` | on | Off: every subagent runs in the foreground and the agent waits for it. |
| `astracode.agent.builtinAgents` | on | Off: `explore` and `plan` are not offered. |
| `astracode.agent.taskRetentionDays` | 30 | How long transcripts, reports and command logs are kept. |
Each subagent is billed like any other request. Several at once spend faster than one, so give each a narrow task and ask for a short report.
All documentation
Get started
Agent
- Agent overview
- Approvals and permissions
- Plan mode
- What the agent can do
- Running commands
- Browser tools
- Checkpoints and undo
- Infrastructure as code
- Running several agents at once
- Subagents and background tasks
- Remote agents in GitHub Actions