Docs › Agent › Subagents and background tasks

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.

On this page

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, and these buttons:

Up to four run at once in one chat; more wait their turn, shown as Waiting for a free slot., rather than being refused. A subagent can start subagents of its own, three levels deep at most. None 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.

The built-in agents

AgentWhat it is for
general-purposeAnything; it has the tools the agent has. Used when no agent is named.
exploreFinding things fast without changing anything: reading, searching and the language server.
planRead-only research that ends in a step-by-step plan. In Plan mode, only read-only agents like this one can be started.
verifyChecking 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 @ in the composer and pick an agent, which inserts @agent-<name>, 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; if both folders define the same name, .astracode wins, and a project's agent wins over yours. A project's own agent folders are read only once you trust the folder.

  1. Run AstraCode: Open Settings, choose Customize, then the Agents chip. Typing /agents in the composer opens the same place.
  2. Choose + Create agent and fill in its name, description, tools, model, colour and where to save it, with Always run in the background and Work in its own git worktree if you want them.
  3. Or choose Generate with AI, describe the agent in a sentence and choose Generate. The agent drafts the file in the chat and you approve it.
  4. Each agent in the list can be opened with Edit or removed with Delete.

.astracode/agents/test-auditor.md

---
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.
FieldWhat it does
name, descriptionRequired. The description is what the agent reads to decide when to use it, so say when, not only what.
tools, disallowedToolsWhat 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.
modelinherit (the default), fast or strong. Claude Code's model names are mapped to these. An exact model id is used only when you bring your own API key.
permissionModeCan only make it stricter than the agent that starts it: plan keeps it read-only, dontAsk refuses anything that would ask you.
maxTurnsSteps before it stops (50 by default; 30 for explore, plan and verify).
backgroundtrue always runs it in the background.
isolationworktree gives it its own git worktree, removed afterwards if it changed nothing; remote runs it in GitHub Actions.
skills, mcpServers, hooks, memory, effort, colorSkills 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.

Subagents never get the tools for asking you questions, writing plans, saving memories or Debug mode; those stay with the agent you are talking to.

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 View 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

SettingDefaultWhat it does
astracode.agent.subagentsonWhether the agent may start subagents at all.
astracode.agent.maxConcurrentAgents4How many run at once in one chat, from 1 to 20.
astracode.agent.maxAgentDepth3How deep they may nest, from 1 to 5; 1 means a subagent starts none of its own.
astracode.agent.backgroundAgentsonOff: every subagent runs in the foreground and the agent waits for it.
astracode.agent.builtinAgentsonOff: explore and plan are not offered.
astracode.agent.taskRetentionDays30How long transcripts, reports and command logs are kept.

Each subagent uses your allowance like any other run. Several at once use it faster than one, so give each a narrow task and ask for a short report.

If something goes wrong

← Running several agents at once Remote agents in GitHub Actions →

All documentation

Get started

Using the editor

Agent

Context

Workspaces

Connectors

Extending AstraCode

CLI

Account and usage

Troubleshooting

Reference