Claude Code Agent View: Complete Guide to Background Sessions (2026)

Agent view, opened with claude agents, is Claude Code’s answer to a real problem: once you start running parallel tasks, you have no way to see them all at once. Agent view gives you one screen for every background session — what’s running, what needs your input, what’s done.

This guide covers everything: how to dispatch tasks, read session state, use the full CLI command set, and understand the worktree isolation that prevents parallel sessions from trampling each other’s files.

This feature requires Claude Code v2.1.139 or later. Check your version with claude --version.

What agent view is (and what it isn’t)

Agent view is not a task runner or workflow engine. It’s a session dashboard. Each row is a full Claude Code conversation running in the background. You dispatch a task, it runs without a terminal attached, you check back when it needs you or finishes.

The key distinction from subagents: background sessions in agent view are independent top-level sessions that you manage manually. Subagents are spawned by a parent session to delegate subtasks. Both run Claude in parallel, but the control flow is different.

Use background sessions when the tasks are genuinely independent — a refactor in one module while a test run finishes in another. Use subagents when one session needs to coordinate the results.

Quick start: dispatch, watch, reply

claude agents

Agent view opens with a dispatch input at the bottom. Type a task and press Enter to start a background session. The session appears as a row and starts working immediately.

To dispatch and attach right away, press Shift+Enter instead.

From inside any session, press ← on an empty prompt to background it and open agent view with that session already listed. Or run /bg to background the current conversation:

/bg run the full test suite and fix any failures

From your shell, skip agent view entirely and go straight to background:

claude --bg "investigate the flaky AuthMiddlewareTest"

Reading session state

Each row shows the session’s name, current activity, and a state icon:

A separate icon shape shows whether the process is alive:

The one-line summary per row is generated by a Haiku-class model, refreshed every 15 seconds while working. It tells you what the session is doing without opening the transcript.

Peek and reply without attaching

Select a row and press Space to open the peek panel. It shows the session’s most recent output — usually enough context to decide whether to let it keep running or step in.

To reply without leaving agent view, type in the peek panel and press Enter. For multiple-choice prompts, press the number key to pick an option. Press Tab to fill the input with a suggested reply you can edit first.

Peek without attaching is the main advantage of agent view over running sessions in separate terminals — you handle a blocked session in seconds, then return to your work.

The full keyboard shortcut map

Press ? inside agent view to see all shortcuts. The complete list:

CLI commands for managing sessions from the shell

Agent view is the interactive dashboard, but the shell commands let you automate and script session management:

# Open agent view
claude agents
claude agents --cwd ~/projects/my-app   # filter to one directory (v2.1.141+)

# Start background sessions
claude --bg "task description"
claude --bg --name "my-task" "task description"   # custom display name
claude --bg --agent code-reviewer "address PR 1234 review comments"
claude --bg --exec 'pytest -x'   # background shell command, not a Claude session

# Manage specific sessions
claude attach <session-id>    # open in current terminal
claude logs <session-id>      # show recent output
claude stop <session-id>      # stop the session
claude rm <session-id>        # remove from list (preserves worktree if uncommitted)

After starting a background session, the output includes the short session ID and these commands:

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

Worktree isolation: how parallel file edits don’t conflict

This is the part most guides skip. When a background session edits files, Claude automatically moves it into an isolated git worktree under .claude/worktrees/. Parallel sessions can read the same checkout but each writes to its own branch.

This means you can safely dispatch two sessions that work on the same repository:

claude --bg "refactor the auth module to use the new token format"
claude --bg "update the API client to handle the new response schema"

Both will edit files, but into separate worktrees. Neither will see the other’s uncommitted changes.

Worktree isolation is skipped when:

• The session is already inside a linked git worktree
• The directory isn’t a git repository (and no WorktreeCreate hook is configured)
• The write target is outside the working directory

To disable isolation for a project where git worktrees are impractical, add this to .claude/settings.json:

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

With "none", background sessions write directly to your working copy. Avoid parallel sessions that touch the same files in this mode.

To find a session’s worktree path, peek the session or attach and check its working directory. When you delete a session with Ctrl+X twice, Claude removes the worktree — including uncommitted changes. Commit or push first if you want to keep the work.

Session persistence across restarts

Background sessions don’t need a terminal open to keep running. A supervisor process runs them independently. You can close agent view, close your shell, or start other sessions and the background work continues.

State persists on disk across:

• Claude Code auto-updates
• Supervisor restarts
• Machine sleep and wake

Shutdown stops running sessions. If sessions show as failed after shutdown, reopen agent view, select the failed session, and press Enter to resume from the saved conversation.

Sessions clean up automatically after 30 days of inactivity. Completed sessions with open pull requests stay visible until you explicitly remove them.

Filtering the session list

Type in the dispatch input to filter instead of dispatch:

Practical workflow patterns

Feature work + tests running in parallel

# Start refactor
claude --bg --name "auth-refactor" "refactor src/auth/ to use the new JWT library"

# Start test run while refactor is underway
claude --bg --exec 'npm test -- --watch'

# Check on both from agent view
claude agents

PR review loop

claude --bg "review PR 2048 and post a summary comment"

When the session opens a pull request, a PR #N label appears in the row. The color tells you the status: yellow (waiting on checks), green (ready to merge), purple (merged).

Send a long-running task to the background mid-conversation

You’re in the middle of a session and realize the task will take a while:

/bg continue running and fix all the linting errors you find

The session moves to the background and keeps working. Press ← on an empty prompt in any session to background it and open agent view.

Run a background shell command alongside Claude sessions

# From agent view dispatch input:
! pytest -x --tb=short

# Or from the shell:
claude --bg --exec 'pytest -x --tb=short'

Shell jobs appear as rows in agent view. They show the most recent output line as the row summary. Attach to see full output. The captured output cleans up about 5 minutes after the command exits.

Common mistakes

Dispatching too many sessions at once

Each background session uses your subscription quota independently. Ten sessions running simultaneously use ten times your normal rate. Agent view doesn’t cap the count. Check Limitations in the official docs before running large fleets.

Expecting subagent coordination from background sessions

Background sessions are independent. They don’t communicate with each other. If session A’s output needs to feed into session B, you need to do that manually: attach to session B, paste the relevant output, and continue.

Deleting sessions with uncommitted work in worktrees

Ctrl+X twice removes the session and its worktree — including uncommitted changes. If a session wrote useful code, commit or merge it before deleting.

Closing agent view and assuming sessions stopped

Background sessions keep running after you close agent view. Esc or closing the terminal returns you to your shell; it doesn’t stop anything. Use claude stop <id> or Ctrl+X to actually stop a session.

See also

• Manage multiple agents with agent view — official docs
• Sub-agents — for delegating subtasks within a session
• Git worktrees — parallel sessions with isolated file edits
• Our gallery of Claude Code rules and settings — curated CLAUDE.md patterns for agent view workflows