Library
Claude Code Documentation (June 2026) · 5 of 15
Claude Code Documentation (June 2026)
ai HIGH

Background Sessions & Agent View (claude agents)

Claude Code Documentation (June 2026) Anthropic
background-sessions agent-view supervisor-daemon worktrees parallelism

Key Principle

claude agents opens agent view — one full-terminal screen to dispatch and monitor every background Claude Code session, grouped by state, so you watch progress at a glance and step in only when a row blocks or finishes. Each background session is a full conversation that keeps running with no terminal attached, hosted by a per-user supervisor process (Section: Agent view; Section: The supervisor). Research preview; requires v2.1.139+ (p. agent-view).

Why This Matters

Background sessions are the scale-out tier above agent teams: looser coupling, longer-lived, no single lead. Each session has its own context budget and consumes subscription quota independently — 10 in parallel ≈ 10× quota (Section: Background sessions). They survive machine sleep (supervisor reconnects on wake), but a shutdown stops them (rows show failed; attach/peek/reply restarts). Because sessions are unwatched, edits are git-worktree-isolated by default and bypassPermissions/auto require prior interactive acceptance.

Good Examples

Dispatch from the shell, with name and agent:

claude --bg "investigate the flaky SettingsChangeDetector test"
claude --agent code-reviewer --bg "address review comments on PR 1234"
claude --bg --name "flaky-test-fix" "investigate the flaky SettingsChangeDetector test"

After backgrounding Claude prints the short ID + management 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

Set defaults for every dispatched session (Section: Permission mode, model, and effort):

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

Run a shell command as a background job (no model invoked) via ! prefix or --exec:

! pytest -x                    # in agent view; Enter to start
claude --bg --exec 'pytest -x' # from shell

Turn off worktree edit-isolation (v2.1.143+, in project .claude/settings.json):

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

Counterpoints

  • Every Enter starts its OWN new session — typing another prompt launches a second session, not a follow-up. To follow up, attach to the row (→/Enter) and work inside that conversation (Section: Quick start loop).
  • Deleting a Claude-created worktree destroys uncommitted changes — agent-view delete (Ctrl+X twice) removes the worktree including uncommitted work; commit/push first. Shell claude rm <id> keeps a worktree with uncommitted changes and prints its path. A worktree you created yourself is left in place (Section: Worktrees with sessions).
  • Shell-job output is in memory, not on disk — row + output auto-clean ~5 minutes after exit; read it before then (Section: Shell jobs).
  • @name precedence: when @name matches both a subagent and a sibling repo, the subagent wins; bare first-word match also fires (Section: prompt prefixes).
  • Idle finished sessions are reaped after ~1 hour (state stays on disk, restarts on attach); empty ← rows removed after ~5 min. Pin with Ctrl+T to keep an idle process alive (Section: reaping).
  • On non-Anthropic providers (Bedrock/Vertex/Foundry) without a Haiku model, row summaries fall back to the main model — set ANTHROPIC_DEFAULT_HAIKU_MODEL (Section: Row summaries).
  • Admins can disable the whole feature via disableAgentView / CLAUDE_CODE_DISABLE_AGENT_VIEW (managed settings).

Key Commands & Config

claude agents                  Open agent view
claude agents --cwd <path>     Scope list to sessions under <path> (v2.1.141+)
claude agents --json [--all]   Print sessions as JSON array and exit
claude attach <id>             Attach in this terminal
claude logs <id>               Print recent output
claude stop <id>               Stop a session (also: claude kill)
claude respawn <id> | --all    Restart with conversation intact (pick up updated binary)
claude rm <id>                 Remove from list (keeps worktree w/ uncommitted changes)
claude daemon status           Supervisor state, version, socket dir, worker count
claude daemon stop --any [--keep-workers]   Stop supervisor; --keep-workers leaves sessions running

Slash / dispatch: /bg (/background), /stop, /exit, /tasks; prefixes @agent @repo !cmd /command #<number>; Shift+Enter (dispatch + attach). Per-session flags: --permission-mode --model --effort --dangerously-skip-permissions (v2.1.142); --allow-dangerously-skip-permissions (v2.1.143); --agent (v2.1.157); --settings --add-dir --plugin-dir --mcp-config --strict-mcp-config (v2.1.142, repeat per value — no space-separated). Paths: ~/.claude/daemon.log, ~/.claude/daemon/roster.json, ~/.claude/jobs/<id>/state.json, ~/.claude/jobs/<id>/tmp/. Env / settings: CLAUDE_CONFIG_DIR (separate supervisor instance), CLAUDE_JOB_DIR (= ~/.claude/jobs/<id>), CLAUDE_CODE_DISABLE_AGENT_VIEW, disableAgentView: true, leftArrowOpensAgents. Keys: Space peek/reply, ←/→ detach/attach, Ctrl+T pin, Ctrl+S group by dir, Ctrl+X stop (2× delete), Ctrl+R rename, ? all shortcuts. Recover stalled supervisor: claude daemon stop --any --keep-workers, then next claude agents reconnects.

Rules of Thumb

  • Dispatch independent, unattended-friendly tasks (bug fix, PR review, flaky-test hunt) as separate rows; check back when one needs you or shows a green PR #N.
  • Commit or push before deleting a Claude-created worktree.
  • Pin (Ctrl+T) any idle session you want to stay instantly responsive.
  • For follow-ups, attach — don't re-dispatch.
  • Filter the list with a:<name>, s:<state> (s:blocked = waiting on you), #<number>, or a URL.

Related References