Agent View For Managing Multiple Claude Code Sessions

TL;DR

Agent view (claude agents) is one screen for many background Claude Code sessions. Dispatch tasks as rows, watch state icons and PR labels, peek to reply without opening full transcripts, attach when you need the full session, and use shell commands such as claude attach, claude logs, and claude stop for scripting.

Prerequisites & Requirements

• {"task": "Version check", "description": "Claude Code is v2.1.139+ for agent view research preview"}
• {"task": "Task queue ready", "description": "Independent tasks are written with clear done criteria"}
• {"task": "Directory plan", "description": "Each session knows its cwd, worktree, or @repo target"}
• {"task": "Quota awareness", "description": "Team understands parallel sessions bill independently"}
• {"task": "Merge owner", "description": "A human reviews PR labels before merging green rows"}

Core Concepts Explained

Background sessions vs interactive terminals

Official docs describe agent view sessions as full Claude Code conversations hosted by a supervisor process, not tied to an open terminal. Interactive claude sessions end when the terminal closes unless you background them with /bg or ← on an empty prompt.

Dispatch creates rows, not follow-ups

Each prompt entered in the agent view dispatch input starts a new background session. Follow-ups belong in peek, attach, or shell attach—not a second dispatch with the same intent.

State icons and PR labels are different signals

Row icons show working, needs input, idle, completed, failed, or stopped states. A PR #N label at the row edge tracks pull requests the session opened and is colored by CI/review status—not by session animation alone.

Peek vs attach

Peek (Space) shows recent output or blocking questions with quick replies. Attach (Enter or →) replaces agent view with the full interactive session; ← on an empty prompt detaches without stopping work.

Step-by-Step Implementation Guide

1. Open agent view. Run claude agents from the directory that should own most dispatches, or pass --cwd to filter to one project tree.

2. Dispatch parallel tasks. Enter one prompt per row (bug fix, review, test hunt). Use @subagent or a leading subagent name when a custom agent should run the session.

3. Triage blocked rows first. Sort groups put Needs input and Ready for review above Working. Answer permission or design questions via peek.

4. Review PR labels. When a row shows green PR status, human-review the diff before merge; yellow means checks or review still pending.

5. Attach for deep work. Enter full-screen session mode for complex edits, then detach back to the fleet table.

6. Organize the fleet. Pin long-running monitors with Ctrl+T, rename rows with Ctrl+R, and stop or delete finished sessions with Ctrl+X.

7. Script status when needed. Run claude agents --json --cwd ./my-app for automation that lists working, blocked, or done states without the TUI.

8. Recover after shutdown. Failed rows after host shutdown may need claude respawn or manual resume via claude --resume per official docs.

Daily Workflow Example

# Morning: open fleet view scoped to one repo
claude agents --cwd ~/projects/my-app

# Dispatch three independent tasks (each Enter = new row)
# 1) Fix flaky test in pkg/auth
# 2) Review open dependency PR
# 3) Draft release notes from CHANGELOG

# Midday: peek blocked rows, answer permission prompts
# Space → reply → Enter

# Afternoon: attach to the auth fix for final edits
# Enter on row → work → ← to detach

# Script check before standup
claude agents --json --cwd ~/projects/my-app

Keyboard and Shell Reference

Press ? inside agent view for the full shortcut list documented on code.claude.com.

Troubleshooting

Too many rows across unrelated repos

Use claude agents --cwd ~/projects/my-app (v2.1.141+) to filter sessions to one project tree.

Accidentally dispatched a follow-up as a new session

Use peek or attach on the original row; dispatch input always creates a new background session.

Row shows failed after laptop sleep or shutdown

Official docs note sessions persist through sleep but shutdown stops processes. Use claude respawn ID or resume transcripts with claude --resume.

Deleted row removed uncommitted work

Deleting can remove Claude-created worktrees. Commit, push, or copy changes before Ctrl+X delete confirmation.

Summaries look stale while working

Row summaries refresh at most every 15 seconds during active work plus once per turn—attach if you need live tool output.

Source Verification Notes

Verified against official Claude Code agent view documentation on 2026-06-16:

• Agent view opens with claude agents, requires v2.1.139+, and lists background sessions with state icons, peek/attach flows, and keyboard shortcuts.
• Each dispatch prompt starts a new session; sessions continue under a supervisor process without an attached terminal.
• claude agents --cwd, --json, claude attach, claude logs, claude stop, and claude respawn are documented shell companions to the TUI.
• PR #N labels and color states reflect GitHub pull request status separate from session working/needs-input icons.

Duplicate Check

This guide complements claude-code-desktop-parallel-sessions-workflow (Desktop app windows and tabs) and using-worktrees-for-parallel-claude-code-sessions (worktree isolation mechanics). The agent-view-fleet-operator-agent entry is a reusable agent prompt, not a step-by-step guide. No existing guides entry walks through the CLI agent view dispatch, peek, attach, and shell fleet workflow end to end.

References

• Claude Code agent view - https://code.claude.com/docs/en/agent-view
• Claude Code sub-agents - https://code.claude.com/docs/en/sub-agents