Manage Multiple Agents with Agent View

1. What Is Agent View?

Agent view is a control screen for background Claude Code sessions. Each row represents a separate Claude Code conversation that can continue working without a terminal attached.

It is especially useful when you have several independent tasks, such as fixing a bug, reviewing a pull request, and investigating a flaky test at the same time. citeturn0view0

2. When Should You Use Agent View?

• You have several independent tasks.
• You want Claude to work while you do something else.
• You want one place to see which sessions need your attention.
• You want to attach to a session only when deeper interaction is necessary.
• You want background sessions to keep running without a terminal attached.

3. Requirements and Current Status

The official documentation describes agent view as a research preview. The interface and keyboard shortcuts can change as the feature evolves. Current documentation requires Claude Code v2.1.139 or later.

claude --version

Organizations can disable agent view with the managed disableAgentView setting. citeturn0search0

4. Quick Start

Step 1 — Open Agent View

claude agents

Agent view takes over the terminal. An input appears at the bottom where you can dispatch new tasks. If workspace trust has not yet been accepted, Claude Code shows the normal trust dialog first. citeturn0view0

Step 2 — Dispatch a Session

Type a task and press Enter:

Fix the failing login test and report what caused it.

A new background session appears as a row. You can dispatch another task immediately:

Review the latest pull request for security issues.

Each prompt starts a separate background session. Multiple sessions can run in parallel. citeturn0view0

Step 3 — Peek

Select a row with the arrow keys and press Space. The peek panel shows the latest output or the question the session is waiting on.

Step 4 — Reply

If Claude needs an answer, type it and press Enter. You can respond without attaching to the full conversation.

Step 5 — Attach

Press Enter or → on a selected row to enter the full Claude Code conversation.

Step 6 — Detach

When the prompt is empty, press ← to return to agent view. Detaching does not stop the background session. citeturn0view0

5. The Basic Agent View Loop

claude agents
      ↓
Dispatch task
      ↓
Claude works in background
      ↓
Watch status
      ↓
Needs input?
   ↙       ↘
 Yes       No
 ↓          ↓
Peek/Reply  Keep working
      ↓
Attach when needed
      ↓
Review result

6. Understand Session States

The icon's shape also indicates whether the underlying process is still alive. A dot can represent a process that has exited but whose session can still be resumed by replying or attaching. citeturn0view0

7. What Each Row Shows

A row can show:

• Session name
• Current activity
• Age / how long ago it changed
• State
• Pull request or merge request reference when available
• Whether the process is still alive

Needs input
  ✻ power-up design       double jump or wall climb?       1m

Working
  ✽ collision detection   Adding collision checks           2m

Completed
  ✻ title screen          result: menu finished             9m

8. Background Sessions Keep Running

Background sessions are not tied to an open terminal. You can close agent view and return later. Sessions are persisted on disk and can reappear when you open agent view again.

However, the machine itself still matters: background sessions stop when the machine sleeps or shuts down. They can be restarted afterward. citeturn0search0

9. Open Agent View for One Directory

By default, agent view can show background sessions across your projects. Use --cwd to narrow the list to a directory:

claude agents --cwd ~/projects/my-app

This is useful when you have many sessions and want to focus on one project. citeturn0view0

10. Organize Sessions

Agent view groups sessions by state by default. You can switch to directory-based grouping.

11. Filter Sessions

You can type filters into the dispatch input instead of launching a new task.

12. Important Keyboard Shortcuts

13. Dispatch a Specific Subagent

If you have custom subagents, agent view can start a session using one of them.

@code-reviewer Review the authentication changes.

You can also put the subagent name first:

code-reviewer Review the authentication changes.

If the first word matches a custom subagent name, that agent can become the session's main agent. You can press Tab on an empty input to browse dispatchable subagents. citeturn0view0

14. Dispatch to a Specific Repository

You can mention a repository when you opened agent view from a parent directory containing several repositories:

@my-app Fix the failing checkout test.

Alternatively, open agent view directly inside the target directory. From the shell, you can also change directory and use the background command. citeturn0view0

15. Dispatch a Skill

If you package a recurring workflow as a Skill, agent view can dispatch it from the input:

/my-skill

Type / to browse available dispatchable Skills. This avoids rewriting the same large prompt every time. citeturn0view0

16. Start a Background Session from the Shell

You do not have to open agent view first. You can launch a background session directly:

claude --bg "Investigate the flaky checkout tests and report the root cause."

The session then appears in agent view. citeturn0search0

17. Background an Existing Session

If you are already inside a normal Claude Code session, you can send it to the background:

/bg

You can also press ← on an empty prompt. The session keeps running and appears as a row in agent view. citeturn0view0

18. Fork a Session

Agent view also supports copying a session with /fork. This is useful when you want a new session based on an existing conversation without continuing in the same session.

19. Run Shell Commands in the Background

Agent view is primarily for Claude Code sessions, but background shell commands can also be launched from the workflow. This is useful for long-running commands that do not require Claude reasoning.

20. File Isolation

Background sessions can work in their own worktrees when isolation is configured or when the session is moved into a worktree. This helps prevent parallel coding sessions from editing the same checkout.

Session A → worktree A
Session B → worktree B
Session C → worktree C

Worktrees are the file-isolation mechanism; agent view is the session-management interface. citeturn0search1

21. What Happens When You Delete a Session?

If a session has its own worktree, deleting the session can remove that worktree. Therefore, merge, push, or otherwise preserve important changes before deleting the session.

22. Manage Sessions from the Shell

23. Supervisor Process

Background sessions are hosted by a per-user supervisor process. It is separate from your terminal and from agent view. It starts automatically when you first background a session or open agent view.

The supervisor allows sessions to continue even after agent view closes. When a finished session remains unattached for about an hour, the supervisor can stop its process to free resources; the transcript and state remain on disk so the session can be restarted when you attach, peek, or reply.

24. Where Session State Is Stored

The documentation describes local state under the Claude Code configuration directory. With the default configuration this includes:

If CLAUDE_CONFIG_DIR is set, the supervisor uses that directory instead of the default ~/.claude. citeturn0search0

25. Notifications

While agent view is open, Claude Code can notify you when a local background session needs input, finishes, or fails. The notification behavior uses the configured notification channel and can interact with the Notification hook.

26. Rate Limits and Cost

Every background session consumes subscription usage independently. Running ten agents in parallel can therefore consume quota much faster than running one session.

27. Machine Sleep and Shutdown

Background sessions run locally. If the machine sleeps or shuts down, active sessions stop. After the machine is available again, stopped sessions can be restarted from their saved state.

claude respawn --all

28. Troubleshooting

Agent view is empty

That is normal when no background sessions exist. Dispatch your first task from the input at the bottom.

Sessions stopped after the computer slept

Background sessions do not survive sleep/shutdown. Attach, peek, or reply to restart one, or run:

claude respawn --all

Session is slow after attaching

A finished session that has remained unattached for roughly an hour may have had its process stopped. Attaching starts a fresh process from saved state, so there can be a short startup delay.

Worktrees are filling up

List them:

git worktree list

Then remove unwanted worktrees:

git worktree remove <path>

29. Limitations

• Agent view is a research preview.
• Background sessions consume the same subscription usage as interactive sessions.
• Background sessions are local to your machine.
• They stop when the machine sleeps or shuts down.
• Deleting a session can delete its associated worktree.
• The interface and shortcuts may change as the feature evolves.

30. Agent View vs. Subagents vs. Agent Teams

31. Practical Example

Suppose you have three independent tasks:

Task 1: Fix checkout bug
Task 2: Review authentication PR
Task 3: Investigate flaky tests

Open:

claude agents

Dispatch each task:

Fix the checkout bug and run the relevant tests.

Review the authentication PR for security issues.

Investigate the flaky tests and identify the root cause.

Peek at the session needing input, reply without leaving agent view, and attach to a session when you need the full conversation.

32. Common Beginner Mistakes

1. Thinking agent view itself is an agent.
2. Confusing agent view with subagents.
3. Opening a new terminal for every background task unnecessarily.
4. Forgetting that every background session consumes quota.
5. Deleting a completed session before preserving its code changes.
6. Assuming sessions survive machine sleep or shutdown.
7. Not using --cwd when many projects make the session list noisy.
8. Ignoring “Needs input” sessions.
9. Using parallel agents for tasks that depend heavily on one another.
10. Expecting worktree isolation just because a session appears in agent view.

33. Best-Practice Checklist

34. Interview / Revision Questions

1. What is Claude Code Agent View?
2. Which command opens agent view?
3. What is the difference between agent view and a subagent?
4. How do you dispatch a new background session?
5. How do you peek at a session?
6. How do you attach to a session?
7. How do you detach without stopping it?
8. What do the Working, Needs input, Completed, Failed, and Stopped states mean?
9. How do you restrict agent view to a directory?
10. What does Ctrl+T do?
11. What does Ctrl+X do?
12. How can you start a background session directly from the shell?
13. What is the supervisor process?
14. Why can background sessions consume quota quickly?
15. What happens to sessions when the computer sleeps?

35. Practice — Use Agent View

1. Check your Claude Code version with claude --version.
2. Open a Git project.
3. Run claude agents.
4. Dispatch one small independent task.
5. Dispatch a second independent task.
6. Use arrow keys to select a session.
7. Press Space to peek.
8. Reply if the session needs input.
9. Press Enter to attach to a session.
10. Press ← on an empty prompt to return to the agent list.
11. Rename a useful session with Ctrl+R.
12. Pin an important session with Ctrl+T.
13. Stop and remove a test session with Ctrl+X.

36. Quick Memory Map

37. Final Takeaway

claude agents
     ↓
Dispatch many tasks
     ↓
Claude sessions run independently
     ↓
Monitor status
     ↓
Peek / Reply
     ↓
Attach when needed
     ↓
Detach and keep working