Claude Code Agent View: The Complete Hands-On Guide

If you've been running Claude Code seriously, you've already hit the wall: five tmux panes, seven named sessions, a mental ledger of which one is waiting for permission, which one finished, which one needs a follow-up. The constraint stopped being the model an hour ago. The constraint is you, switching contexts.

Anthropic shipped the fix on May 11, 2026. It's called agent view, and it's exactly what it sounds like: one screen for every Claude Code session you have running, grouped by state, with peek-and-reply built into the same view. From the official launch post: "With agent view in Claude Code, you can kick off new agents, send them to the background, and jump in only when Claude needs you."

Agent view is a Research Preview, requires Claude Code v2.1.139 or later (claude --version), and ships today on Pro, Max, Team, Enterprise, and Claude API plans. This guide is the long-form version of the official docs: every shortcut, every shell command, every state icon, three real-world workflows, and an honest comparison with subagents and agent teams so you know which one to reach for.

Agent view is a full-terminal dashboard that lists every background Claude Code session running under your config directory, regardless of which project, worktree, or repository each one is in. Each row shows the session's name, what it's currently doing, how long ago it last changed state, and a PR link if the session opened one.

You enter it two ways:

• From the shell: claude agents
• From inside any Claude Code session: press ← on an empty prompt

That second entry point is what makes the feature work as an actual workflow. You're mid-implementation on Feature A, you want to investigate something unrelated, press the left arrow, dispatch the new task, peek at it as it runs, arrow back to Feature A. No tab switching. No tmux pane shuffling. One terminal.

The list is grouped by state. Needs input sits at the top, then Working, then Ready for review (sessions with open PRs awaiting your review), then Completed. Pinned sessions float to the very top, and old completed sessions fold into a "… N more" row to keep the screen calm.

Two things agent view explicitly does not show: subagents running inside a session (those are workers in the parent's context window, not separate sessions) and interactive sessions you have open in other terminals (those haven't been backgrounded yet). The view is for parented background sessions only.

The whole feature collapses to four interactions. Walk through these in order on a real project.

1. Open agent view.

claude agents

Agent view takes over the terminal. There's an input at the bottom and a table that fills in as sessions start. Press Esc at any time to exit — your sessions keep running.

2. Dispatch a session.

Type a prompt in the input and press Enter. A new background session starts and shows up as a row. Repeat. Each one runs independently and burns its own slice of your quota, so plan accordingly. After a few sessions are running, the screen looks like the launch example:

Pinned
  ✽ clawd walk cycle          Write assets/sprites/clawd-walk.png           3m
Ready for review
  ∙ jump physics              github.com/anthropics/example/pull/2048       2h
Needs input
  ✻ power-up design           needs input: double jump or wall climb?       1m
Working
  ✽ collision detection       Edit src/physics/CollisionSystem.ts           2m
  ✢ playtest level 3          run 12 · all checkpoints cleared           in 4m
Completed
  ✻ title screen              result: menu, options, and credits done       9m
  ∙ sound effects             result: 14 SFX exported to assets/audio       4h

3. Peek and reply.

Arrow to the row you care about, press Space. The peek panel opens with the session's most recent output and any blocking question. Type a reply, press Enter — it goes to that session without ever leaving the view. Multiple-choice questions get number-key shortcuts. Press Tab to fill a suggested reply you can edit before sending. Prefix with ! to send a Bash command instead of a message.

4. Attach.

Press Enter or → on a row to take the terminal over with the full session, exactly as if you'd run claude in that directory. When you attach, Claude posts a one-paragraph recap of what happened while you were away. Press ← on an empty prompt to detach.

Every row's icon carries two independent signals. The indicator tells you what state Claude is in. The icon shape tells you whether the underlying process is alive.

Then the icon shape, which is independent of the indicator:

• ✻ (or animated ✽) → process is alive, you can reply instantly
• ∙ → process has exited, but Claude restarts it from where it left off the moment you peek, reply, or attach
• ✢ → a /loop session sleeping between iterations; the row shows the iteration count and a countdown to the next run

The one-line summary in each row ("Edit src/physics/CollisionSystem.ts", "result: 14 SFX exported") isn't hand-written. It's generated by your configured Haiku-class model and refreshes at most once every 15 seconds while a session is active, plus once at the end of every turn. Each refresh is a short request billed through your normal provider under the same data-usage terms as the session itself.

You can start a background session from three places, and the choice matters.

From inside agent view

Type a prompt and press Enter. The session is named automatically from the prompt — rename it later with Ctrl+R. Paste an image (screenshot, diagram) directly into the input and it goes along with the task. The prompt can use these prefixes:

When the same @name matches both a subagent and a sibling repo, the subagent wins. Use @ to be explicit.

From inside a session

Run /background (or its alias /bg). The current conversation detaches and keeps running. Pass a trailing prompt to send one more instruction before detaching:

/bg run the test suite and fix any failures

From the shell

--bg starts a new session that goes straight to the background:

claude --bg "investigate the flaky SettingsChangeDetector test"

Combine --bg with --agent to run as a specific subagent:

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

After backgrounding, Claude prints the new session's short ID and the four commands you'll use to manage it:

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

Press ? inside agent view to see all of these in-app. Memorize the top half.

Filter syntax — type these in the dispatch input to filter the list instead of dispatching:

Three useful behaviors that aren't obvious: pressing Enter on a group header collapses it; Ctrl+X on a group header deletes every session in that group after confirmation; your Ctrl+S grouping choice persists across runs.

Every background session has a short ID (eight hex characters) you can use from any shell. These are the script-friendly version of agent view.

A note on the last row: bypassPermissions and auto are refused when passed to --bg unless you've already accepted that mode interactively at least once. The reasoning is straightforward — a background session you aren't watching shouldn't be allowed to act without approval the first time.

The architecture is a per-user supervisor process, separate from your terminal and from agent view itself.

The supervisor starts automatically the first time you background a session or run claude agents — you never manage it directly. Each background session is its own Claude Code process, parented to the supervisor rather than your shell. That's the whole reason sessions survive when you close the terminal, exit the shell, or even auto-update Claude Code mid-session.

Process lifecycle is conservative. A session that's actively working, waiting on you, or has a terminal attached keeps its process running. Once a session finishes and sits unattached for about an hour, the supervisor stops the process to free RAM. The transcript and state stay on disk, and the next time you peek, reply, or attach, the supervisor starts a fresh process from the saved state. When every session is finished and no terminal is connected, the supervisor itself exits and starts again the next time you need it.

State persists on disk under your Claude Code config directory:

Set CLAUDE_CONFIG_DIR to point the supervisor at a different directory; it runs as a separate instance with its own sessions. The supervisor also watches the installed Claude Code binary on disk (a local file watch, not a network check) and restarts into the new version after the auto-updater replaces it. Because background sessions are detached processes, they survive that restart, and the new supervisor reconnects to them on startup.

The interesting half is file isolation. Every background session starts in your working directory but is blocked from writing to it. The moment a session needs to edit files, Claude moves it into an isolated git worktree under .claude/worktrees/ automatically. Parallel sessions can read the same checkout simultaneously, but each writes to its own. The block doesn't apply when the session is already inside a worktree, when the directory isn't a git repo, or to writes outside the working directory. To make a specific subagent always run in its own worktree regardless of how it's started, set isolation: worktree in its frontmatter. The worktree is removed when you delete the session, so merge or push the changes you want to keep first. This is the same daemon architecture surfaced in the leaked Claude Code source, now visible at the product layer.

Three Anthropic-blessed patterns, three different problems. They are not interchangeable.

• Subagents are workers inside one Claude Code session. The parent agent delegates a side task — research, code review, file scan — to a subagent that runs in its own context window and returns only the summary. The conversation stays clean. Subagents never talk to each other. They report to the parent.
• Agent teams are multiple Claude Code sessions that coordinate on a shared task list and message each other directly. One session is the lead. Teammates challenge each other, share findings, and claim work via file locking. Experimental, off by default, requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.
• Agent view is the dashboard for many fully independent sessions you supervise yourself. No shared task list, no inter-agent messages. Each session runs alone and reports only to you. PRs are the deliverable.

The rule of thumb: choose by who needs to talk to whom. If only you need to see the output, agent view. If the parent agent needs the output, subagents. If the workers need to argue with each other, agent teams. The three layer cleanly — a session you launch in agent view can itself use subagents internally, and an agent team's lead session can show up as a single row in agent view.

These are the three patterns that justify the feature.

1. The PR shotgun

You have five small bugs filed. Each one is a 20-minute fix you don't want to context-switch through serially. Dispatch them in parallel and come back to five PRs:

cd ~/code/your-repo

claude --bg "fix #481: timezone bug in invoice export — see the issue for repro"
claude --bg "fix #492: pagination breaks on empty result set"
claude --bg "fix #498: email validation rejects + sign"
claude --bg "fix #501: dark mode contrast on settings page"
claude --bg "fix #504: typo in onboarding copy"

claude agents

Wait 20 minutes, open agent view, review the Ready for review group. Each session works inside its own .claude/worktrees/<id>/, runs CI on its branch, and the row shows the check status next to the PR link. Merge the green ones. Reply in the peek panel to fix the rest.

2. The long-running watcher

A /loop session that re-runs an evaluation against the latest commit on a schedule. You don't want a tmux pane for it. You also don't want to forget it exists.

claude --bg "/loop 1h regenerate the dashboard from latest metrics and post a Slack summary if anything drifts >5%"

In agent view, this shows up as the distinctive ✢ icon with a run count and a countdown to the next iteration. Peek with Space every few hours, attach with Enter only if something looks wrong.

3. The investigation plus context switch

You're attached to a session implementing Feature A. CI fires off an alert about a flaky test in a different repo. You need to investigate without losing your place.

(inside Feature A)  ←  (on empty prompt)
(agent view opens, Feature A is now a row)
@other-repo investigate the flaky SettingsChangeDetector test   Enter
(new session dispatched, you stay in agent view)
↑↑↑   (back to the Feature A row)
Enter   (attach back into Feature A)

Total context-switch overhead: maybe four seconds. Without agent view this is a new tmux pane, a cd, a claude invocation, a mental tag for "remember to come back," and three context-switch taxes. With agent view it's one arrow press. This is the workflow that actually changes how you work, not the dashboard itself.

Some of these you'll hit on day one.

• Rate limits apply per session. Each parallel agent burns your quota independently. Ten agents equals ten times the burn. On Pro this is enough rope to throttle yourself in under an hour.
• Sessions are local. Sleep your laptop and every running session stops. Wake it, run claude respawn --all, and they pick up from disk.
• Worktrees are deleted with the session. Merge or push before you delete. If you forget, recover with git worktree list and git worktree remove <path> from the project directory.
• Research Preview = unstable surface. The interface, shortcuts, and supervisor implementation may shift between Claude Code releases.
• Admin lockout. Organizations can disable agent view entirely with the disableAgentView managed setting or the CLAUDE_CODE_DISABLE_AGENT_VIEW environment variable.
• Subagents inside a session aren't separate rows. They're workers inside the parent's context window, not parented to the supervisor.
• Interactive sessions in other terminals don't appear until you background them with /bg or ← on an empty prompt.
• Reliability isn't fixed by infrastructure. Agent view multiplies your parallelism, not the underlying model's quality. The 67% Claude Code degradation we documented earlier this year hits ten parallel agents just as hard as it hit one.

Anthropic ran Code with Claude 2026 two weeks ago and shipped zero new models. They shipped Dreaming (long-horizon background reasoning), Outcomes (multi-attempt-with-judge), multi-agent orchestration improvements, Add-ins, and now Agent View. Every announcement was infrastructure.

That isn't a slowdown. It's a strategy. The model capability curve for coding agents is now well past the threshold where one agent can solve a typical PR-sized task end-to-end. Claude Opus 4.7 clears 80% on SWE-Bench. GPT-5.4 clears similar marks on computer-use tasks. The bottleneck for production agent systems isn't can one agent do the task. It's can one human supervise twelve agents doing twelve tasks at once.

That's the bet Agent View is built on. The harness — the dashboard, the supervisor process, the worktree isolation, the peek-and-reply loop — is the thing that lets human oversight scale to match model throughput. Anthropic is racing the rest of the field on harness rather than on raw benchmark numbers, and on the early reaction from developers (the launch tweet from the team lead became one of the most-shared AI dev posts of the week) the bet looks like the right one.