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
- How they run
- The built-in agents
- Asking for one
- Writing your own
- Background work and the Tasks panel
- Settings
- If something goes wrong
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:
- Stop ends it.
- Move to background (Ctrl+B) lets the agent carry on while a foreground subagent works.
- Open transcript shows everything it did.
- Continue... sends it a follow-up.
- Merge, for a subagent that worked in its own worktree.
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
| 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. |
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 @ 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.
- Run AstraCode: Open Settings, choose Customize, then the Agents chip. Typing
/agentsin the composer opens the same place. - 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.
- 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.
- 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.
| 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 model names are mapped to these. 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. |
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. |
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
| 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, from 1 to 20. |
astracode.agent.maxAgentDepth | 3 | How deep they may nest, from 1 to 5; 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 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
- DENIED: starting agents is not available here: subagents are switched off, or the nesting limit was reached. Check
astracode.agent.subagentsandastracode.agent.maxAgentDepth. - Your agent does not appear: a project's agents load only in a trusted folder; check the file is in one of the folders above and has
nameanddescription. - More on Agent run problems.
← Running several agents at once Remote agents in GitHub Actions →
All documentation
Get started
Using the editor
- Tab completion
- Edit and ask about a selection
- Reviewing the agent's changes
- Git: commit messages, branch review and conflicts
- Dictation
- Layout, themes and the settings page
Agent
- Agent overview
- Agent, Plan, Ask and Debug
- Approvals and permissions
- Plan mode
- Debug mode
- Tools
- Browser tools
- How the agent checks its work
- Checkpoints and undo
- Running several agents at once
- Subagents and background tasks
- Remote agents in GitHub Actions
- Infrastructure as code
Context
Workspaces
Connectors
- Connectors (MCP servers)
- Connector configuration reference
- Use AstraCode from Claude, ChatGPT and other apps
Extending AstraCode
CLI
Account and usage
- Usage and limits
- Bring your own key
- What AstraCode sends and keeps
- Reporting a problem and getting help
Troubleshooting
- Troubleshooting
- Sign-in problems
- Install and update problems
- Chat panel problems
- Agent run problems
- Connector problems
- Dictation problems
- Usage, billing and network errors
- CLI problems