Agent view: run many Claude Code sessions with claude agents

Agent view is the claude agents dashboard in Claude Code: one screen that lists every background session on a machine, with its state and any pull request it opened. It dispatches new sessions, answers blocked ones without attaching, and moves each session’s edits into its own git worktree. It is a research preview, added in v2.1.139.

You have three unrelated jobs before lunch: a flaky checkout test, a pull request with twelve unresolved review comments, and a dependency bump. Run them one after another and you wait on each; open three terminals and you lose track of which one is sitting on a permission prompt. Agent view gives each job its own session and shows you which one needs you. This page is for developers who run several Claude Code sessions at once, and for tech leads who set the rules those sessions run under.

Research preview v2.1.139+

Checked against Claude Code 2.1.283

The interface and shortcuts still change between releases. Everything here was checked on 2026-09-26 against Claude Code v2.1.283 (the latest channel) and the vendor’s agent view reference. It also holds on the stable channel (v2.1.274), except where a later version is named. Run claude --version before you rely on a detail.

What agent view gives you

• A dispatch loop for several independent tasks, each in its own background session and its own worktree.
• Three dispatch prompts that end in evidence (a test run, a pull request, a report) instead of “done”.
• A way to check every session’s result from its row and its pull request, without reading transcripts.
• A shell interface (claude --bg, claude agents --json) for scripts, status bars and notifications.
• A symptom-to-recovery table for the failures that actually happen: lost worktrees, stalled supervisors, sessions that die on shutdown.

When is agent view the right tool?

Agent view is for work you split into independent tasks and supervise yourself, on your own machine. When the split, the schedule or the scale belongs to someone else, another feature fits better:

You need…	Use
Several unrelated tasks you dispatch and check one by one	Agent view (this page)
One task split into parallel parts inside a single conversation	Custom subagents
One mechanical change spread across many files	/batch, covered in multi-file workflows
Tens to hundreds of agents driven by a rerunnable script	Dynamic workflows
One objective that runs until a checkable condition holds	/goal, often inside an agent view row
Work that starts on a schedule or trigger with your laptop off	Routines

Codex has its own codex agents command center, covered in parallel development with Codex. The cross-tool comparison of background and cloud agents lives in background agents.

Run your first three agents from agent view

Before you start, work in a git repository with a remote, and authenticate the gh CLI so pull request labels can link. Worktree isolation needs git; outside a repository, sessions edit your files directly.

1. Open agent view. In your terminal, from the repository root:

   claude agents

   In a directory you have not trusted yet, the workspace trust dialog appears first (v2.1.225+); declining exits. Esc returns to your shell, and your sessions keep running.

2. Set dispatch defaults once. Flags passed to claude agents apply to every session you dispatch from that view, and the footer shows them:

   claude agents --permission-mode auto --effort high

   Use auto only with a model that supports auto mode (on the stable channel, also check your plan); see permissions and sandboxing. Without --permission-mode, a dispatched session starts in the mode a new claude session in that directory would use.

3. Dispatch three tasks. Type a prompt in the input at the bottom and press Enter. Every Enter starts a new session; it never sends a follow-up to an existing one. Use the prompts in the next section. Shift+Enter inserts a newline (v2.1.248+); Ctrl+Enter dispatches and attaches where the ? overlay lists it.

4. Peek and reply. Select a row with the arrow keys and press Space. The peek panel shows the question the session is waiting on, its result, or its current status. Type a reply and press Enter, or press a number key for a multiple-choice question.

5. Attach only when the peek is not enough. Press Enter or → to open the full conversation; Claude posts a recap of what happened while you were away. Press ← on an empty prompt or run /exit to detach. Detaching never stops the session; /stop does.

6. Pull in a session you already have open. In any regular claude session, run /bg (alias of /background) or press ← on an empty prompt. The conversation moves to the background and appears as a row.

Write dispatch prompts that end in evidence

An unattended session reports “done” when it believes it is done. Make the prompt define what done looks like and what proof to leave behind, so you check the proof rather than the transcript. Each prompt below names its acceptance check, its limits and its deliverable. See acceptance criteria for writing checks that an agent cannot argue its way around.

Copy-paste prompt: fix a flaky test, with proof

The test "checkout applies the discount once" in tests/checkout.spec.ts fails
intermittently in CI. Reproduce it locally by running it 50 times in a loop and
record the failure rate. Find the root cause, fix it with the smallest change
that works, and do not edit any other test or loosen any assertion. Run the
loop again and record the new failure rate, then run the full test suite.
Open a draft pull request whose description contains: the root cause in two
sentences, the before and after failure rates with the exact command you ran,
and the full-suite result. If you cannot reproduce the failure, stop and say so
instead of changing code.

Copy-paste prompt: an independent review session

Review pull request #1234 without editing any code. Read the linked issue and
list its acceptance criteria. Check out the branch, run the test suite and the
type checker yourself, and do not trust results quoted in the PR description.
For each criterion, mark it met, not met, or untested, and cite the command and
output that shows it. Flag any test that was deleted, skipped, or had an
assertion weakened. Post the result as one review comment on the pull request.

A review session is a second, independent check: it did not write the code, so it has no stake in the result. To run a review subagent you have defined, mention it: start the prompt with @code-reviewer, and that subagent runs as the session’s main agent. The custom subagents page shows how to write one.

Copy-paste command: a named background job from the shell

claude --bg --name "dep-bump" "Upgrade all dependencies to their latest minor \
versions. Run the full test suite and the type checker. Open a draft pull \
request only if both pass, listing every upgraded package with its old and \
new version. If anything fails, do not open a pull request: end with a summary of what \
broke as your final reply, and keep scratch files in \$CLAUDE_JOB_DIR/tmp."

claude --bg returns at once and prints a short ID plus the attach, logs and stop commands for it. Use that ID with claude logs and claude attach; --name only sets the display name in agent view. Read the failure summary in the peek panel or with claude logs <id>. CLAUDE_JOB_DIR points at the session’s own ~/.claude/jobs/<id> directory, so parallel sessions never write their scratch files over each other; the backslash stops your shell from expanding it before the session sees it. The prompt must be a positional argument: Claude Code rejects --bg combined with -p.

Read a session’s state from its row

Each row shows a name, a one-line summary and an age. The icon’s color and animation show the state; its shape shows the process:

Icon shows as	State	What to do
Animated	Working	Nothing
Yellow	Needs input	Peek and answer: a question, a permission, a sandbox request
Dimmed	Idle	Give it the next prompt, or delete it
Green	Completed	Check the result and its pull request
Red	Failed	Peek for the error; attach or reply to restart it
Gray	Stopped	Stopped with Ctrl+X or claude stop, or ended while the service was off

A ✻ or animated ✽ means the process is alive; ∙ means it has exited but restarts from where it left off when you reply or attach; ✢ marks a /loop session sleeping between runs.

When a session opens or pushes to a pull request, a #1234 label appears at the right of the row (!1234 for a GitLab merge request). Yellow means waiting on checks or review, or checks failed; green means checks passed and no review is blocking; purple means merged; gray means draft or closed. Groups sort the work for you: below any Pinned rows, Ready for review (sessions with an open pull request) and Needs input sit above Working and Completed.

The row summary comes from a Haiku-class model: one short request at the end of each turn and every few minutes during long turns, billed like the session itself. On a gateway or third-party provider with no Haiku-class model configured, that request uses the session’s main model; set ANTHROPIC_DEFAULT_HAIKU_MODEL to keep it cheap.

Verify the output without reading every transcript

Agent view makes sessions cheap to start. What limits you is how much finished work you can check. Treat each row’s output as a change that must pass the same gates as a human’s, in this order:

1. Machine gates. CI on the pull request (tests, type check, lint) decides the label color. A yellow label is not a result, and it is never mergeable.
2. The evidence the prompt demanded. Read the pull request description: root cause, before/after numbers, the commands run. If the evidence is missing, reply in the peek panel asking for it; do not open the transcript to reconstruct it. The evidence bundle page defines a standard format.
3. An independent review. Dispatch the review prompt above as its own session. It checks each acceptance criterion against output it produced itself.
4. A human decision at merge. You, or the code owner, read the spec delta, the evidence and the review, then sample the riskiest hunks. Reviewing an agent’s pull request gives the full triage protocol, and evidence, not diffs explains why this replaces line-by-line reading.

Agent view never merges. A session that moved its changes into a worktree Claude created commits without asking, pushes its branch when there is a remote, and opens a draft pull request when the task calls for one. It never pushes main or master, never force-pushes, and never merges. If your task, CLAUDE.md or memory says you handle git yourself, Claude leaves git to you.

For tech leads: parallel sessions raise the arrival rate of pull requests, not your team’s review capacity. Cap the number of open agent pull requests per person at what the team reviews in a day, and see the review queue for work-in-progress limits and size budgets.

Get told when a session needs you

Agent view already notifies through your preferredNotifChannel when a session needs input, finishes or fails; add a Notification hook only to route the alerts elsewhere, such as a desktop notifier. Two notification types fire while agent view is open in a terminal: agent_needs_input and agent_completed (v2.1.198+). Route them to a desktop notifier with a Notification hook in ~/.claude/settings.json:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "agent_needs_input|agent_completed",
        "hooks": [
          { "type": "command", "command": "notify-send 'Claude Code' 'A background agent needs you or has finished'" }
        ]
      }
    ]
  }
}

notify-send is the Linux notifier; use osascript -e 'display notification ...' on macOS. See hooks automation for handler types.

Read state from a script

claude agents --json prints sessions as a JSON array and exits; it needs no TTY. It is the supported interface. The files under ~/.claude/jobs/ are not stable, so do not parse them. This one-liner lists every background session waiting on you:

claude agents --json --all | jq -r '.[]
  | select(.kind == "background" and .state == "blocked")
  | [.id, (.name // "-"), (.waitingFor // "-")] | @tsv'

state is one of working, blocked, done, failed or stopped. blocked always means the session needs you; a session that finished its turn reads done. Add --cwd <path> to limit the list to one project.

Script background sessions from the shell

Command	Purpose
claude --bg "<prompt>"	Start a background session in the current directory; prints its short ID
claude --agent code-reviewer --bg "<prompt>"	Run a named subagent as the session’s main agent
claude --bg --permission-mode plan "<prompt>"	Override the permission mode for one session
claude --resume <session-id> --bg "<prompt>"	Continue an existing conversation in the background (same ID from v2.1.257)
claude attach <id>	Open the session in this terminal
claude logs <id>	Print its recent output
claude stop <id> (or claude kill <id>)	Stop it; the conversation is kept
claude respawn <id> / claude respawn --all	Restart one session, or every running one, onto the current Claude Code binary
claude rm <id>	Delete the session, and its worktree when that is safe
claude daemon status	Show the supervisor’s process ID, version and uptime

A background session reads settings from the directory it runs in, and inherits the PATH and cloud-provider variables of the shell you dispatched from. claude --bg --permission-mode bypassPermissions is refused until you have accepted the bypass disclaimer once interactively with claude --dangerously-skip-permissions. Use either only inside a disposable, network-restricted sandbox (a throwaway container or VM with no production credentials): a bypassed background session runs every tool call unattended, with nobody watching to stop it. From v2.1.281 (latest channel), claude --bg in a script exits with Workspace not trusted if the directory was never trusted: run claude there once interactively first.

How agent view keeps parallel edits apart

Every background session starts in your working directory. Before it edits a file, Claude moves the session into its own git worktree under .claude/worktrees/, so sessions share reads but never share writes. Subagents the session spawns edit inside that same worktree; give a subagent its own with isolation: worktree in its frontmatter.

For a repository where worktrees are impractical, such as heavy native build output or many submodules, turn isolation off in the project’s .claude/settings.json:

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

Sessions then edit your checkout directly and ask before committing or switching branches, so never run two against the same files.

Deleting a session is where work gets lost. Pressing Ctrl+X twice in agent view removes the worktree Claude created, uncommitted changes included. claude rm <id> keeps a worktree that has uncommitted changes. Both refuse when the worktree has commits that Claude Code cannot confirm are saved elsewhere, and print the branch and the number of unpushed commits. Commits already on a remote do not block the delete, and neither do commits on your local copy of the remote’s default branch while that branch is checked out in your main checkout. After that refusal, deleting again — Ctrl+X twice on the row, or claude rm <id> --discard-unpushed <commit>@<worktree-id> with the value the refusal printed (v2.1.260+) — removes the worktree, its branch, the unpushed commits and any uncommitted changes. To keep them, push first. The transcript always survives: claude --resume reopens it, and a bare /resume in the dispatch input (v2.1.212+) brings a deleted session back as a row.

Keyboard shortcuts you use every day

Press ? in agent view for the full list in context.

Shortcut	Action
Enter	Dispatch the typed prompt, or attach to the selected row
Space	Open or close the peek panel
→ / ←	Attach / detach (on an empty prompt)
Tab	On an empty input, browse subagents; otherwise apply a suggestion
Ctrl+T	Pin or unpin a session; pinned rows sort to the top
Ctrl+R	Rename a session
Ctrl+S	Group by state or by directory (persists)
Ctrl+G	Write the dispatch prompt in $VISUAL or $EDITOR
Ctrl+X, twice	Stop, then delete within two seconds

Type a filter into the dispatch input instead of a prompt: s:blocked shows everything waiting on you, a:<name> shows sessions running one agent, and #1234 or a pull request URL selects the session working on it. Prefix ! to run a shell command as a background job instead of a Claude session.

What breaks when you run agents in the background?

Symptom	Cause	Recovery
Work vanished after deleting a row	Agent view deleted a Claude-created worktree with uncommitted changes	Ask sessions to commit and push in the prompt; use claude rm rather than Ctrl+X when unsure; recover the conversation with /resume
Row stays in Needs input with “open this session to…”	A command such as /mcp or /install-github-app needs an attached terminal	Attach and run the command again
Rows show failed after a reboot	Shutdown stops sessions; sleep does not	Attach to or reply to each row to restart it from where it left off. After 48 hours it shows stopped (ended while the background service was off); press Enter twice on the row, or run claude attach <id>
Attach, peek or claude logs says the service did not respond	The supervisor stalled	claude daemon stop --any --keep-workers, then claude agents
Dispatch fails with Could not resolve authentication method	The supervisor started without stored credentials	Run /login, then claude daemon stop --any --keep-workers
A --agent session exits at once	The name matches no subagent: --agent '<name>' not found	Check the name in .claude/agents/
Two sessions overwrote each other	Isolation is off (bgIsolation: "none") or the directory is not a git repository	Turn isolation back on, or dispatch one session per set of files
Quota runs out mid-afternoon	Each session uses your subscription quota independently	Cap concurrent sessions; see cost control
claude agents prints your subagents and exits	Agent view is unavailable or turned off (disableAgentView, CLAUDE_CODE_DISABLE_AGENT_VIEW)	Run claude update, then check both settings
A green label on a change that is still wrong	The label reports CI and review status, not correctness	Strengthen the tests the prompt must pass, and keep the review session in the loop

Two limits apply as of v2.1.283: Sessions run on your machine, so they stop when it shuts down. Each session consumes quota like an interactive one, so ten parallel sessions use it roughly ten times as fast as one. Leftover directories in .claude/worktrees/ can be listed with git worktree list and removed with git worktree remove <path>.

Where to go next with agent view

Reviewing an agent's pull request The triage protocol for the pull requests your background sessions open.

Goal workflows with /goal Give a dispatched session a checkable completion condition so it finishes on its own.

Custom subagents Build the reviewer and specialist agents you mention with @name when dispatching.

Running the review queue Work-in-progress limits and size budgets once agents open most of the pull requests.