Skip to main content
Subagents let Embedder hand a focused investigation or task to a separate agent that reports back to your chat. Long shell commands and background subagents keep running while the conversation continues, and you can check on or stop them at any time.

​
Use subagents for isolated work

Ask Embedder to delegate when an investigation would fill the conversation with detail, or when several independent questions can run at once:
Each subagent works in its own session and returns a report to the main chat. Embedder reviews the report and continues the task. To watch a subagent or give it more instructions, open its session:
  • VS Code: select the subagent’s row in the chat, or Open agent session on a background subagent’s card above the chat input. The session opens in its own chat tab.
  • Terminal: select the subagent’s row in the conversation, or run /background, select a background subagent, and press Enter. Press Esc to return to the main chat, or ↑ when the input is empty. With an empty input, use ← and → to move between subagent sessions. Press Ctrl+C to stop the subagent’s current turn.
You can type plain-text messages in a subagent’s session. A message you send while the subagent is working waits for its next turn. The session stays open for follow-ups after the subagent finishes. Up to 10 subagents can run at once, across all chats in the same VS Code window or terminal session. Embedder reports when the limit is reached; wait for one to finish or stop one.

​
Subagent types

Embedder picks the type that fits the task. The subagent’s row shows the type: VS Code shows the name as listed below, and the terminal shows it in title case, such as Codebase Explorer. The four read-only types can read code, documents, and the web. With subagent hardware access on, they can also check hardware status and read serial output that’s already been captured. If the main chat is in Plan mode when a subagent starts, the subagent is read-only, including a general subagent, and stays that way until it finishes. Otherwise, a general subagent works in Act mode, even when the main chat is in Debug mode, so it doesn’t use the debugger. Keep debugger work in the main chat. A general subagent can’t start more subagents, ask you questions, switch modes, add peripherals, upload documents, or stop background tasks. Give a general subagent enough context to resolve ambiguity on its own: the files it owns, the checks to run, and what the main chat has already ruled out.

​
Approvals inside a subagent

A subagent starts with the main chat’s approval mode and follows the same rules. If you change the approval mode, running subagents follow the change right away.
  • Shell commands on your allowlist run without asking. So do directories you allowed outside the project, such as a trusted toolchain folder.
  • Any other shell command, file write, or path outside the project raises the normal request card. The card appears in the main chat, labeled with the subagent’s task title, and the subagent waits until you answer. See Approvals from subagents.
  • Approving lets the action proceed. Rejecting without a reply stops the subagent’s current turn. In VS Code, you can instead reply with what to do, and the subagent continues with your instructions.
  • In Always ask mode, Embedder also asks before it starts each subagent, and the subagent still asks before each of its actions.
A delegated task can run build and test commands, such as west build or ctest. Each command asks exactly as it would in the main chat. Hardware access is controlled separately; see Control subagent hardware access.

​
Runtime limits

A subagent has no fixed time limit. A subagent working in the foreground runs until it finishes, you stop it, or the main chat’s turn is stopped. If it shows no activity for about 15 minutes, Embedder treats it as stalled and stops it.

​
Run subagents in the background

For long work that the main chat doesn’t need right away, ask Embedder to run a subagent in the background:
The subagent keeps working after the current turn ends, and Embedder adds its result to the conversation when it finishes. If the chat is idle at that point, Embedder starts a new turn to review the result. The subagent’s row shows Working in background in VS Code until its first step, or (background) in the terminal. While it runs, you can ask Embedder to check its progress, send it new instructions, or stop it. In Plan mode, Embedder can check progress but can’t send instructions or stop the subagent; use the controls below. You can also stop it yourself:
  • In VS Code, select Stop on its row in the chat, or Stop background agent on its card above the chat input.
  • In the terminal, run /background, select the task, and press x twice.
Stopping a background subagent ends its current turn but keeps its session and transcript. If you stop it yourself, Embedder can’t restart it. To continue the work, open the subagent’s session and send it a message.

​
Control subagent hardware access

General subagents have hardware access by default. They can use hardware tools and run hardware commands through the shell. Embedder lets one agent use a board at a time: the main chat and its subagents take turns, and the others wait until the board is free. To turn hardware access off, or back on, run:
The setting affects subagents started after you change it, in every chat in the same VS Code window or terminal session. Subagents that are already running keep the access they started with. The setting isn’t saved, so each new Embedder session starts with subagent hardware access on. When hardware access is off, a general subagent can’t use hardware tools, and Embedder blocks the shell commands it recognizes as hardware commands, such as flashing. The subagent reports the hardware step back to the main chat.
Read-only subagent types never flash, monitor, send commands, run hardware scripts, or debug. While hardware access is on, they can check hardware status and read serial output that’s already been captured. Turning hardware access off removes that too.
Name one device or port in the delegated task. A subagent that holds a monitor or debugger should release it promptly so the main chat and other subagents can continue. If a request would wait behind a long-running activity held by a related session, such as a debug server or a background hardware task, Embedder refuses it instead of waiting, because the sessions could end up waiting on each other. The message names the session that holds the board and the activity. Stop that activity or let it finish, then retry, or leave the hardware step to the session that holds the board. If a board stays held, see Work with hardware across chats.

​
Long shell commands become background tasks

Embedder watches each shell command for up to one minute:
  1. If the command finishes within a minute, its result appears in the chat.
  2. If it’s still running, it moves to the background without restarting.
  3. When it finishes, Embedder reports the result in the conversation.
A background command keeps running until it completes, you stop it, or you close, clear, or rewind the chat. Its full output is saved to a log, and Embedder reads new output when it checks on the task. Commands Embedder starts in the background on purpose, such as dev servers, watchers, and log followers, go to the background immediately. Up to 16 background commands can run at once. If Embedder restarts while a command or subagent is running, that work isn’t restarted automatically. Ask Embedder to run it again.
A hardware command keeps the board reserved for its session until the command exits, including after it moves to the background. Flash commands and commands that disconnect serial monitors always stay in the foreground. See Hardware scripts.

​
View and manage background tasks

Background shell commands and background subagents appear in one place: You can also ask Embedder in the conversation to:
  • List the running background tasks.
  • Report the status or latest output of a task.
  • Stop a task. Stopping a shell command ends the command and any processes it started. Stopping a subagent ends its turn but keeps its session and transcript.

​
Parallelize with subagents

  • Ask for several read-only subagents in one message when you have independent questions. They run at the same time.
  • Use a general subagent for a self-contained implementation task, in the foreground or the background. Subagents share the project’s files, so give each one files that no other subagent edits.
  • Keep tightly coupled edits in the main chat.
Use a read-only subagent when you need evidence or a plan without file changes. Use a general subagent when the task should write files or run commands on its own.
Last modified on October 13, 2026