AI
Claude Code Background Agents: The Supervisor Model
August 202613 min read
Three ways: claude agents opens the management UI and dispatches from there, claude --bg with a prompt dispatches from any shell, and /bg or /fork moves or copies a live conversation into the background. Sessions persist even after you close agent view or your terminal, because a supervisor process hosts them rather than your shell.
A per-user process that hosts every background session. It starts automatically on your first background dispatch, keeps a pre-warmed worker for fast dispatch, persists across auto-updates by restarting into the new version, stops idle unpinned sessions after about an hour, and respawns stopped processes when you attach or reply.
Not on files. Before editing, each background session moves into its own git worktree under .claude/worktrees/ so parallel sessions do not collide. Isolation is skipped when you are already in a linked worktree, outside a git repository, or writing outside the working directory, and it can be turned off with the worktree bgIsolation setting.
The supervisor inherits its environment from whichever shell first started it, and an OS-installed supervisor gets no shell environment at all. A variable exported only in your shell reaches background agents when that shell happened to cold-start the supervisor and silently does not otherwise. Put them in the env block of a settings file instead.
Rate limits apply per account, so ten parallel sessions consume roughly ten times the quota — there is no separate budget for background work. The parallelism is also local: sessions run on your machine and stop when it shuts down. For work that must outlive the machine, use a cloud session or a routine.
Key Takeaway
Claude Code background sessions run without a terminal attached, hosted by a per-user supervisor process that persists across auto-updates and outlives the shell that started it. Before editing files, each session moves into its own git worktree so parallel sessions do not collide. Ten parallel sessions consume roughly ten times the quota.
I dispatched four background sessions, closed the terminal, and came back to find all four still working. That was the point, and it was still slightly startling. What made it possible is a process I had not known existed: a supervisor that started on my first background dispatch, took ownership of every session, and has no relationship to the terminal I happened to launch it from.
Almost every non-obvious behaviour here follows from that architecture, including one I had already been bitten by in a completely different context. This post covers the ways to dispatch, the supervisor and what it inherits, the worktree isolation that makes parallelism safe, what survives when you move a session to the background, and the honest cost of running ten agents at once.
There is a management UI and there is the shell, and both reach the same thing. The distinction worth internalising early is between the two ways of pushing a live conversation into the background, because one of them leaves you with nothing in front of you.
# Three ways to start work that outlives your terminal.
claude agents # the full-terminal management UI
claude --bg "investigate the flaky test"
claude --bg --name "test-fix" --model opus "..."
claude --bg --exec 'pytest -x' # a SHELL job, not a Claude session
# From inside an interactive session:
/bg <prompt> # MOVE this conversation to the background
/fork <prompt> # COPY it to the background and keep working here
← # background and return to agent view
# Inside agent view, the dispatch line understands:
# <agent-name> <prompt> run a custom subagent
# @<agent-name> mention a subagent anywhere
# @<repo> dispatch to a specific directory
# ! <command> run a shell job
# #<number> or a PR URL attach to the session on that PR
# Shift+Enter dispatch AND attach immediatelyBackgrounding moves the conversation — your terminal is free and the work continues elsewhere. Forking copies it, so the background session carries the context and you keep the conversation you were in. Fork is almost always what you want when you are mid-investigation and want a side quest run without losing your place.
One supervisor process per user hosts every background session, and it behaves more like a service than a shell job:
The supervisor inherits its environment from whichever shell first started it, which is the same structural fact that makes shell-exported proxy and certificate variables unreliable for background agents. It also means a gateway endpoint only reaches a background session under specific conditions — the supervisor must have been started from a gateway shell, and the session dispatched to that directory or backgrounded from it. Put anything that must apply universally in a settings file, not a shell profile.
This is the design decision that makes running four agents at once reasonable rather than reckless. Before touching files, a background session moves into its own git worktree, so two sessions working the same repository are not writing over each other. It is on by default and there is a setting to turn it off, which you should think about carefully before using.
# Before editing files, a background session moves into a git
# worktree under .claude/worktrees/ so parallel sessions do not
# collide. Skipped when: already in a linked worktree, not a git
# repository, or the write is outside the working directory.
{
"worktree": { "bgIsolation": "none" } // turn it off
}
# What CARRIES OVER when you background a session:
# running background shell commands
# backgrounded subagents
# dynamic workflows
# scheduled tasks from /loop
# directories added with /add-dir
# flags: --mcp-config --settings --add-dir --plugin-dir
# --fallback-model
#
# What STOPS:
# running monitors
# MCP servers awaiting input — anything needing an attached
# terminal, such as the settings list in /mcpDeleting a session in agent view removes its worktree. If that session produced work you have not committed, it goes with it. The stop-and-delete key is two presses of the same chord, which is deliberate, but the habit worth building is committing from a background session's worktree before removing it — or using the remove command instead, which drops it from the list and keeps the transcript.
The UI is a list of rows grouped by state, and the two keys worth learning first are peek and attach — peek shows the latest output or the question blocking a session without committing you to it, which is exactly what you want when scanning four rows to find the one that needs you.
# Agent view keys
↑ ↓ navigate rows
Space peek — latest output, or the blocking question
Enter / → attach to the full session
← background it again and come back here
Ctrl+T PIN — keep the process running while idle
Ctrl+R rename
Ctrl+X ×2 stop and delete
Ctrl+S toggle grouping: by state, or by directory
# From any shell, without the UI:
claude agents --json # list sessions as JSON
claude attach <id>
claude logs <id>
claude stop <id>
claude rm <id> # remove from the list, KEEPS the transcript
claude respawn <id> # restart with the conversation intact
claude daemon status
claude daemon stop --any # add --keep-workers to preserve sessionsThe states, and what each is telling you:
| State | What it means |
|---|---|
| Needs input | Waiting on an approval, an answer or a permission — the only state that needs you now |
| Working | Actively processing; peek to see how far it has got |
| Idle | Ready for the next prompt. Unpinned, it will be stopped after about an hour |
| Completed or Failed | Finished. Failed means it ended with an error rather than being stopped |
The carry-over list is more generous than you would guess: running shell commands, backgrounded subagents, dynamic workflows, scheduled loop tasks, added directories and most launch flags all come along. That means a session mid-workflow can be pushed to the background without losing the workflow.
Two things stop, and both for the same reason: they need a terminal. Running monitors stop, and any MCP server waiting on input stops — which includes commands that open a settings list or an install flow. If your session is doing something that needs you to answer in a picker, finish that first and background it afterwards.
Pinning is the answer to the one-hour idle stop. A pinned session keeps its process running even while idle, which matters when the session holds expensive state you do not want rebuilt — a warmed cache, a long conversation, a loaded environment. Everything else is better left unpinned so the supervisor can reclaim it.
Three limitations decide whether this fits your workflow, and the first one is arithmetic rather than opinion:
The pattern that has worked best for me is one investigation per independent question, dispatched and left alone. A flaky test, a documentation pass and a refactor are three things that do not need to talk to each other, and running them in parallel costs three times the tokens and roughly one third of the wall-clock time. That is a good trade when the tokens are cheaper than your attention.
It is a bad trade when the tasks are actually one task. Three sessions on the same subsystem will produce three overlapping and mutually inconsistent sets of edits in three worktrees, and merging them is worse than having done the work once. The worktrees stop them corrupting each other; they do not stop them disagreeing.
Hold the supervisor in mind and the rest of this feature stops surprising you: it is why sessions outlive your terminal, why environment variables have to live in settings rather than a shell, why a crashed session comes back, and why stopping the daemon is a real operation rather than closing a window. Dispatch things that are genuinely independent, pin only what holds expensive state, and commit before you delete — that is most of what you need.
Sources & further reading