# Agent view: run many Claude Code sessions with claude agents

URL: https://developertoolkit.ai/en/claude-code/automate/agent-view/
Description: Dispatch, watch and verify parallel Claude Code background sessions from the claude agents dashboard, with worktree isolation and evidence-first review.

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](https://code.claude.com/docs/en/agent-view). It also holds on the `stable` channel (v2.1.292 on 2026-10-17), 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](/en/claude-code/automate/custom-subagents/)                       |
| One mechanical change spread across many files                  | `/batch`, covered in [multi-file workflows](/en/claude-code/build/multi-file-workflows/) |
| Tens to hundreds of agents driven by a rerunnable script        | [Dynamic workflows](/en/claude-code/automate/dynamic-workflows/)                     |
| One objective that runs until a checkable condition holds       | [`/goal`](/en/claude-code/automate/goal-workflows/), often inside an agent view row   |
| Work that starts on a schedule or trigger with your laptop off  | [Routines](/en/claude-code/automate/routines/)                                       |

Codex has its own `codex agents` command center, covered in [parallel development with Codex](/en/codex/automate/multi-agent-workflows/). The cross-tool comparison of background and cloud agents lives in [background agents](/en/workflows/automate/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:

   ```bash
   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:

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

   Use `auto` only with a model that supports auto mode (on a build older than v2.1.283, also check your plan); see [permissions and sandboxing](/en/workflows/harness/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](/en/workflows/plan/acceptance-criteria/) for writing checks that an agent cannot argue its way around.

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

```text
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**

```text
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](/en/claude-code/automate/custom-subagents/) page shows how to write one.

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

```bash
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](/en/workflows/ship/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](/en/workflows/ship/agent-pr-review/) gives the full triage protocol, and [evidence, not diffs](/en/ladder/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](/en/teams/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`:

```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](/en/claude-code/automate/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:

```bash
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                              |

From v2.1.290 (both release channels on 2026-10-17), `claude attach` and `claude logs` take either the ID or part of the session's name; put a name with spaces in quotes.

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, `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`:

```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](/en/claude-code/operate/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](/en/workflows/ship/agent-pr-review/) — The triage protocol for the pull requests your background sessions open.
- [Goal workflows with /goal](/en/claude-code/automate/goal-workflows/) — Give a dispatched session a checkable completion condition so it finishes on its own.
- [Custom subagents](/en/claude-code/automate/custom-subagents/) — Build the reviewer and specialist agents you mention with @name when dispatching.
- [Running the review queue](/en/teams/review-queue/) — Work-in-progress limits and size budgets once agents open most of the pull requests.