Background Agents and Agent View: Running Many Sessions at Once#

Executive Summary#

A background session is a full Claude Code conversation that keeps running without a terminal attached. Agent view, opened with claude agents, is one screen that lists every background session, shows what each is doing, and flags the ones that need your input. You dispatch independent tasks – a bug fix, a PR review, a flaky-test investigation – as separate rows, work elsewhere, and step in only when a row needs you. A per-user supervisor process hosts the sessions, so they keep running after you close the view or the shell.

Agent view is a research preview and requires Claude Code v2.1.139 or later. Check with claude --version.

Table of Contents#

• Background Agents and Agent View: Running Many Sessions at Once
  • Executive Summary
  • Table of Contents
  • Opening Agent View
  • Creating Background Sessions
    • From Agent View
    • From Inside a Session
    • From the Shell
    • Running a Shell Command
  • Reading the Agent View
    • Session State
    • Pull Request Status
    • Row Summaries
  • Working with Sessions
    • Peek and Reply
    • Attach and Detach
    • Organize and Filter
    • Keyboard Shortcuts
  • Managing Sessions from the Shell
  • How File Edits Are Isolated
  • Model, Effort, and Permissions
  • How Sessions Are Hosted
  • Turning Agent View Off
  • Limitations
  • Best Practices
  • Anti-Patterns
  • References

Opening Agent View#

Run claude agents to open agent view. It takes over the terminal and lists every background session you have started, across all projects, grouped by state with pinned sessions and the ones that need input at the top.

claude agents

Press Esc to return to your shell; sessions keep running while you are away. You can use claude agents as your primary entry point instead of claude: dispatch every task from the view, attach when you want the full conversation, and press ← to return to the table.

To narrow the list to one project, pass --cwd (v2.1.141 or later):

claude agents --cwd ~/projects/my-app

Subagents and teammates a session spawns are not listed as separate rows. Interactive sessions open in other terminals do not appear until you background them.

Creating Background Sessions#

From Agent View#

Type a prompt in the input at the bottom of agent view and press Enter. Each prompt starts its own new session, so entering a second prompt launches a second session rather than following up on the first. The session is named automatically from the prompt; rename it later with Ctrl+R.

Prefixes and mentions control how the session starts:

/exit and /quit close agent view and /logout signs you out; every other command or skill is sent to a new session as its first prompt.

From Inside a Session#

Run /background or its alias /bg to move the current conversation into a background session. Pass a prompt to give one more instruction first:

/bg run the test suite and fix any failures

If Claude is responding when you run /bg, the response continues in the background. Backgrounding starts a fresh process that resumes from the saved conversation, so running subagents, monitors, and background commands do not transfer; Claude asks you to confirm before backgrounding when any are running. Configuration flags from the original launch carry through: --mcp-config, --strict-mcp-config, --settings, --add-dir, --plugin-dir, --fallback-model, and --allow-dangerously-skip-permissions, along with directories added with /add-dir.

Pressing ← on an empty prompt backgrounds the current session and opens agent view with that row selected, in one step. This works from any session, even a fresh one with no history. Turn the shortcut off with the leftArrowOpensAgents setting in /config.

From the Shell#

Pass --bg to start a session that goes straight to the background:

claude --bg "investigate the flaky SettingsChangeDetector test"

Combine with --agent to run a specific subagent as the main agent, and --name to set the display name:

claude --agent code-reviewer --bg --name "pr-1234" "address review comments on PR 1234"

Claude prints the session’s short ID and the commands to manage it:

backgrounded · 7c5dcf5d · pr-1234
  claude agents             list sessions
  claude attach 7c5dcf5d    open in this terminal
  claude logs 7c5dcf5d      show recent output
  claude stop 7c5dcf5d      stop this session

Running a Shell Command#

To run a shell command as a background job instead of a Claude session, type ! as the first character of the dispatch input, or use --exec from the shell:

claude --bg --exec 'pytest -x'

The command runs as a PTY-backed job and appears as a row with its most recent output line as the status. No model is invoked. Attach, peek with Space, or run claude logs <id> to see output. The captured output stays in memory, is not written to disk, and the row cleans up about five minutes after the command exits.

Reading the Agent View#

Agent view groups sessions so the ones that need you are at the top: Ready for review (an open pull request) and Needs input sit above Working and Completed. Completed collects finished, failed, and stopped sessions together. Press Ctrl+S to group by directory instead; the choice persists.

Needs input
  ✻ power-up design           needs input: double jump or wall climb?       1m

Working
  ✽ collision detection       Edit src/physics/CollisionSystem.ts           2m

Ready for review
  ∙ jump physics              Opened PR with collision fix              PR #2048  2h

Completed
  ✻ title screen              result: menu, options, and credits done       9m

Session State#

Each row starts with an icon whose color shows the session’s state:

The icon’s shape shows whether the underlying process is running:

The terminal tab title shows the awaiting-input count while agent view is open, such as 2 awaiting input · claude agents.

Pull Request Status#

When a session opens a pull request, a PR #1234 label appears at the right edge of the row, linked in terminals that support hyperlinks. Multiple pull requests show as a count, such as 3 PRs. The number is colored by status:

For most tasks this column is where you pick up the result: review and merge the pull request when its number turns green.

Row Summaries#

The one-line summary in each row is generated by a Haiku-class model so you can see what a session is doing without opening the transcript. While a session works, the summary refreshes at most once every 15 seconds plus once per turn end. Each refresh is one short request billed under the session’s normal provider. On third-party providers without a Haiku model configured, set ANTHROPIC_DEFAULT_HAIKU_MODEL to choose the summary model. From v2.1.161, a done/total count such as 2/5 appears before the summary when the session is running parallel work items.

Working with Sessions#

Peek and Reply#

Press Space on a selected row to open the peek panel. It shows what the session needs, its most recent output, and any pull requests it opened – usually enough that you never open the full transcript. Type a reply and press Enter to send it without leaving agent view. For a multiple-choice question, press a number key to pick an option; for other blocked sessions, press Tab to fill the input with a suggested reply. Prefix a reply with ! to send a Bash command. Use ↑ and ↓ to peek at adjacent sessions, or → to attach.

Attach and Detach#

Press Enter or → on a row to attach. Agent view is replaced by the full interactive session, and Claude posts a short recap of what happened while you were away. Attached sessions render in fullscreen (a background session has no scrollback to append to); scroll with PgUp/PgDn and press Ctrl+O for transcript mode.

Press ← on an empty prompt to detach and return to agent view (or Ctrl+Z if a dialog has focus). Detaching never stops a session: ←, Ctrl+Z, /exit, and double Ctrl+C all leave it running. To end a session from inside it, run /stop.

Organize and Filter#

Within a group:

• Ctrl+T – pin a session to the top and keep its process running while idle
• Shift+↑ / Shift+↓ – reorder sessions
• Ctrl+R – rename a session
• Enter on a group header – collapse it
• Ctrl+X, then Ctrl+X again within two seconds – stop, then delete the session

Type in the dispatch input to filter instead of dispatching:

Keyboard Shortcuts#

Press ? in agent view to see every shortcut in context.

Managing Sessions from the Shell#

Every background session has a short ID, printed when you start it with claude --bg and used as its directory name under ~/.claude/jobs/. These commands work without opening agent view, which is useful for scripting:

The conversation transcript stays on your machine after a session is removed and remains available through claude --resume.

How File Edits Are Isolated#

Every background session starts in your working directory. Before editing files, Claude moves the session into an isolated git worktree under .claude/worktrees/, so parallel sessions read the same checkout but each writes to its own. Claude skips the worktree when the session is already inside a linked worktree, the directory is not a git repository (and no WorktreeCreate hook is configured), or the write is outside the working directory.

To turn worktree isolation off for a repository where worktrees are impractical, set worktree.bgIsolation to "none" (v2.1.143 or later). Background sessions then edit the working copy directly:

{
  "worktree": {
    "bgIsolation": "none"
  }
}

Deleting a session in agent view (Ctrl+X twice) removes a worktree Claude created for it, including uncommitted changes, so push or commit work you want to keep first. claude rm keeps a worktree that has uncommitted changes and prints its path. A worktree you created yourself is left in place either way. A subagent the session spawns inherits the session’s worktree unless its frontmatter sets isolation: worktree.

Model, Effort, and Permissions#

A background session reads its settings from the directory it runs in. The model shown in the agent view header is the dispatch default, taken from your model setting. Override defaults for everything dispatched from a view by passing flags when you open it:

claude agents --permission-mode plan --model opus --effort high

Each session can run a different model: pass --model with claude --bg, or attach and press s on a model in the /model picker to switch that session only. The permission mode depends on how the session started – backgrounding with /bg or ← keeps the current mode, while dispatching from the input or claude --bg uses the directory’s defaultMode. The permission mode, model, and effort persist when the supervisor restarts the process.

bypassPermissions and auto are refused until you have accepted that mode by running claude with it once interactively, since those modes let an unwatched session act without approval. Flags were added across releases:

Repeat --add-dir, --plugin-dir, or --mcp-config once per value; the space-separated form is not supported with claude agents.

How Sessions Are Hosted#

A per-user supervisor process, separate from your terminal and agent view, hosts background sessions. It starts automatically the first time you background a session or open agent view, and authenticates with the same credentials as your interactive sessions. Each session is its own Claude Code process.

Lifecycle:

• A session that is working, waiting on input, has a terminal attached, or is running a background command, subagent, dynamic workflow, or monitor keeps its process alive.
• Once a session finishes and sits unattached for about an hour, the supervisor stops its process to free resources. The transcript and state stay on disk, and the next attach, peek, or reply starts a fresh process from where it left off. Pin a session with Ctrl+T to keep it responsive.
• An empty row left from pressing ← and never given a prompt is removed after about five minutes.
• Under memory pressure, the supervisor stops idle non-pinned sessions first.
• When the auto-updater replaces the binary on disk, the supervisor restarts into the new version; detached sessions keep running and the new supervisor reconnects.

State lives under your config directory (or CLAUDE_CONFIG_DIR if set):

Each session has CLAUDE_JOB_DIR set to its ~/.claude/jobs/<id> directory, so shell commands can write temp files to $CLAUDE_JOB_DIR/tmp without colliding with parallel sessions. Run claude daemon status (or /doctor) to check the supervisor without reading these files.

Turning Agent View Off#

Set the disableAgentView setting to true, or set the CLAUDE_CODE_DISABLE_AGENT_VIEW environment variable. Administrators can enforce this through managed settings.

If claude agents prints a count followed by your subagents and exits instead of opening the view, agent view is unavailable in that environment (older versions did not open it on Bedrock, Vertex AI, or Foundry). Run claude update.

Limitations#

Best Practices#

1. Dispatch independent tasks. Agent view shines when sessions do not share files: a bug fix in one module, a PR review, a flaky-test investigation. Worktree isolation handles parallel writes, but tasks that edit the same files still conflict at merge time.

2. Watch the PR column. For most dispatched work, the result is a pull request. Let the PR #N color tell you when to look: green means checks passed and nothing is blocking.

3. Peek before attaching. Space shows the latest output or the pending question. Reply from the panel and move on; reserve attaching for when you want the full conversation.

4. Pin long-lived sessions. A session you will return to repeatedly stays responsive when pinned with Ctrl+T, instead of being stopped after an idle hour.

5. Pre-accept the permission mode you need. auto and bypassPermissions require one interactive acceptance before a background session can use them. Accept once, then dispatch.

6. Keep parallelism modest. Two to four parallel sessions is manageable for most work. Beyond that, quota burn and the effort of tracking results tend to outweigh the time saved.

7. Commit or push before deleting. Deleting a session in agent view removes its worktree and any uncommitted changes. Use claude rm if you want the worktree preserved.

Anti-Patterns#

1. Parallel sessions editing the same files outside a worktree. With worktree.bgIsolation: "none" or in a non-git directory, concurrent sessions write to the same working copy and overwrite each other. Keep isolation on, or partition the files.

2. Dispatching ten agents without watching quota. Background sessions consume usage the same as interactive ones. Ten in parallel exhaust rate limits roughly ten times as fast.

3. Deleting a session before saving its work. Ctrl+X twice discards the session’s worktree, including uncommitted changes. Merge, push, or claude rm first.

4. Treating background sessions as durable across reboots. They survive sleep but stop on shutdown. Don’t rely on one to finish overnight through a restart.

5. Backgrounding a session mid-task expecting subagents to follow. Running subagents, monitors, and background commands do not transfer when you /bg. Let them finish, or restart them in the backgrounded session.

References#

• Manage Multiple Agents with Agent View (Claude Code Docs) – agent view, dispatching, the supervisor, and session management
• Agent View in Claude Code – announcement and motivation
• Run Agents in Parallel (Claude Code Docs) – compares agent view with subagents, agent teams, and worktrees
• Git Worktrees (Claude Code Docs) – worktree isolation and cleanup
• Agent Teams Article – the mesh-coordination model for multi-agent work
• Dynamic Workflows Article – script-driven subagent orchestration, another way to run agents in parallel
• Large Codebase Strategies Article – parallel work with worktrees on big repositories