Claude Code parallel agents - auto vs manual triggers
ai/claude-code-parallel-agents-auto-vs-manual · Updated · Tags: ai, claude-code
Claude Code parallel agents: which ones Claude uses on its own, and which you must ask for
TL;DR
- Claude uses these on its own: subagents, forked subagents, background bash, cross-session messages, and threads inside a Project.
- You must start these: agent view,
/batch, routines, and workflows (unless you turn on/effort ultracode). - Agent teams are off by default. Once enabled, Claude can form a team on its own, and it does not ask first.
- To force a feature: @-mention the subagent, type
ultracode, or run its slash command. To stop Claude using one, change a setting or add a deny rule.
Legend
| Mark | Meaning |
|---|---|
| 🤖 Auto | Claude decides to use it without being asked |
| 👤 Manual | Only runs when you run a command, flag, keyword or UI action |
| 🔀 Both | Claude may use it on its own, and you can also ask for it |
| ⚙️ Off by default | Must be enabled in settings before either side can use it |
The five main approaches
| Feature | Trigger | What Claude does on its own | How you trigger it yourself | How to stop or limit it |
|---|---|---|---|---|
| Subagents | 🔀 Both | Picks a subagent from its description. Writing "use proactively" in the description makes it delegate more often | Name it in plain language ("use the code-reviewer subagent"). Claude usually follows, but it's still Claude's call. @-mention (@agent-<name>) always runs it. claude --agent <name> or "agent": "<name>" in settings runs the whole session as that agent | Remove or narrow the subagent's description. Deny the Agent tool |
| Agent view (background sessions) | 👤 Manual | Nothing. Claude never starts a background session. Once you start one, it moves itself into a worktree before it edits files | claude agents (then type a prompt), claude --bg "task", /background (/bg), /fork | "disableAgentView": true or CLAUDE_CODE_DISABLE_AGENT_VIEW=1. Worktree step: "worktree": {"bgIsolation": "none"} |
| Agent teams | ⚙️ then 🔀 | Once enabled, any subagent Claude gives a name becomes a teammate. Teams can form when you never asked for one, and Claude Code doesn't ask first | Enable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, then say "spawn 3 teammates to…". Works only in interactive sessions, not -p or the SDK | Set the variable to 0. Claude then spawns ordinary subagents again |
| Projects (claude.ai/code, desktop) | 👤 create, then 🤖 threads | Starts a cloud thread for each task you post, or passes the task to a thread already working in that area | You create the project (New project). A thread runs on your own computer (via Remote Control) only when you ask | Tell Claude to propose threads before starting them, to limit how many run at once, or to "answer here instead of starting a thread". Claude saves these to project memory |
| Dynamic workflows | 👤 Manual by default, 🤖 with ultracode | Nothing, unless /effort ultracode is on. Then Claude plans a workflow for each substantive task, sometimes several in a row | Type the ultracode keyword or say "use a workflow". Run /deep-research <q> or a saved /<name>. The keyword only works in prompts you type, not in -p, schedules or webhooks | /effort ultracode off. Turn off the "Ultracode keyword trigger" in /config. Turn workflows off with "disableWorkflows": true or CLAUDE_CODE_DISABLE_WORKFLOWS=1 |
Supporting tools
| Feature | Trigger | Automatic part | Manual part |
|---|---|---|---|
| Worktrees | 🔀 Both | Background sessions from agent view or --bg move into a worktree before editing. Subagents with isolation: worktree in their frontmatter always get one. Claude can also give a fork its own worktree | claude -w <name> (or -w "#1234" for a PR). Ask Claude to "work in a worktree", which uses the EnterWorktree tool. Ask it to "use worktrees for your agents". Desktop worktree option. git worktree add |
| Cross-session messaging | 🔀 Both (on by default) | Claude messages your other sessions without being asked, for example to warn them about a breaking change | Ask "tell the session in my other terminal…". @-mention a session (@api-worker). Run /list-agents (/peers) to see which sessions it can reach. To stop it: crossSessionInbound: refuse, or deny SendMessage and ListAgents |
/batch | 👤 Manual | Once you run it: plans 5–30 units, waits for your approval, then spawns one background subagent per unit, each in its own worktree | /batch <instruction>. The docs don't say Claude invokes it on its own, and it isn't in the list of skills Claude can call itself, so treat it as user-only |
Related features that aren't parallel agents
| Feature | Trigger | Detail |
|---|---|---|
| Background bash | 🔀 Both | Claude can run a long command in the background itself. You can ask it to, or press Ctrl+B on a running command (twice in tmux) |
| Forked subagent | 🔀 Both | Fork mode is on by default in interactive sessions, so Claude can spawn forks (subagents that keep the full conversation) itself. You start one with /subtask <task>. Control it with CLAUDE_CODE_FORK_SUBAGENT=0/1 |
/fork | 👤 Manual | Copies the whole session into a new background session. If agent view is off, /fork makes a forked subagent instead |
| Background subagents | 🤖 Auto | Where fork mode is on, every subagent Claude spawns runs in the background. CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 makes them run in the foreground |
| Routines | 👤 set up, then 🤖 runs | You create them with /schedule (/routines), at claude.ai/code/routines, or in the desktop app. After that, they run by themselves on a schedule, an API call or a GitHub event. Claude doesn't create one unless you ask, which you can also do inside a Project |
Watching running work (all manual)
| Command | Shows |
|---|---|
claude agents | Agent view: every background session and its state |
/tasks (/bashes) | Background work in this session: bash commands and subagents, including finished ones |
/workflows | Workflow runs. p pauses, x stops, s saves the run as a command |
@ typeahead | Named background subagents and their status |
/agents | Only prints where subagent files live. It is not the same as claude agents |
/list-agents | Sessions, subagents and teammates that Claude can message |
Watch for these
- Agent teams change ordinary delegation. With the flag on, a subagent Claude names becomes a teammate, which costs more tokens. Turn the flag off if you only want subagents.
- Ultracode applies to every task in the session. Expect more tokens and slower answers. It also skips the "Large workflow" warning and the subagent cap.
- Asking for a subagent by name is a strong hint, not a guarantee. Use
@agent-<name>when it must run. - Fork mode is on by default. Claude may spawn background forks without being asked. Interactive sessions behave differently from
-pand the SDK here.
Sources
- Run agents in parallel
- Subagents · Agent view · Agent teams
- Dynamic workflows · Projects · Routines
- Worktrees · Cross-session messaging
- Commands · Skills · Interactive mode
Checked against the docs on 2026-10-05.
Disclaimer: These documents are personal notes. The information may be incomplete, out of date or wrong, so check it before you rely on it.