Claude Code Agent View: Run, Monitor, and Recover Background Sessions

Claude Code Agent View is a terminal dashboard for independent background sessions running on your computer. Open it with claude agents, enter a task, and press Enter to create a session. Select its row and press Space to check progress or answer a question; press Enter or → to enter the full conversation. You can leave the dashboard while work continues.

The useful operating loop is dispatch → check → intervene → review → preserve → clean up. Agent View helps you manage the conversations; you still decide which tasks belong together and which changes to keep. It remains a Research Preview, so use the current official Agent View guide for controls that differ from your installed version. The steps here describe documented behavior, rather than a hands-on performance test.

Choose Agent View when you can assign independent tasks

Use Agent View when you want to steer several conversations yourself: investigate two causes of a bug, review separate changes, or keep a long local check visible while another session works. Each task gets its own conversation and a row you can return to.

Keep a tightly coupled edit in one session. If a helper just needs to search files and return findings to that conversation, a subagent is often enough. Splitting the work becomes useful when you can name each session's responsibility and decide how to combine its result.

There are several ways to run Claude in parallel, with different people or programs coordinating the work:

These distinctions come from Anthropic's parallel-agent comparison. Agent View sessions can also exchange findings when cross-session messaging is enabled; they are not inherently unable to communicate. However, opening the dashboard does not automatically turn your independently dispatched tasks into a coordinated team.

For the longer-lived coordinator, see Claude Code Projects: access, first setup, and usage limits. Cloud threads can keep working when your computer is off; Projects can also use local threads through Remote Control when requested. That is a different choice from operating local sessions in Agent View.

If you are building an application, the Agent SDK embeds the Claude Code agent in a Python or TypeScript process you operate. Managed Agents supplies a managed agent harness with cloud or self-hosted sandbox environments. Neither is required to use this terminal dashboard.

Open the dashboard and verify the starting conditions

Start in the repository where the tasks belong. You need an installed, authenticated Claude Code environment and permission to work in that directory. The setup guide covers supported accounts and providers; a free claude.ai chat account alone does not include Claude Code access.

From your shell:

claude --version
claude doctor
claude agents

The first command prints your installed version. claude doctor provides read-only installation and settings diagnostics. claude agents opens the dashboard; a previously untrusted workspace first presents its trust dialog. An empty dashboard is expected before you dispatch or background a session.

Update through the installation method you already use. Native installations normally auto-update, and claude update requests an immediate update. Homebrew, WinGet, and Linux package manager installations use their corresponding upgrade paths by default. For an existing npm installation, the documented upgrade is npm install -g @anthropic-ai/claude-code@latest; npm installation requires Node.js 22 or later and optional dependencies. See the installation-specific update instructions, rather than mixing installers to fix a dashboard problem.

If claude agents prints your configured subagents and exits, the dashboard is unavailable in that environment. Update through your installation method, then check whether Agent View has been disabled by configuration or an administrator. The official troubleshooting entry describes this specific symptom.

The dashboard normally lists background sessions across your projects. To focus on one launch directory, use an actual project path:

claude agents --cwd /path/to/your/project

This scopes the list to sessions started under that directory, including ones that subsequently move into its worktrees. A regular interactive session in another terminal does not appear until you background it. Subagents and team workers inside a session do not each receive their own dashboard row. These visibility rules are documented under monitoring sessions.

Make Agent View the default entry point

In a regular Claude Code conversation, run:

/config defaultToAgentsView=true

Exit that conversation, then run claude with no arguments. It opens Agent View. Passing a task, such as claude "explain the search index builder", still starts a regular conversation. To undo the setting, run /config defaultToAgentsView=false inside a regular or attached conversation.

If the dashboard says /config isn't available in agent view — attach to a session to run it, select a session and attach first. The setting is changed inside a conversation, not through the dashboard's task-dispatch box. See opening Agent View by default.

Dispatch a useful first pair of tasks

Every ordinary prompt submitted in the dashboard's bottom input starts a new session. To send a follow-up to an existing one, use its Space peek panel or attach to its row. This distinction prevents an accidental duplicate investigation.

A good first split produces two pieces of evidence you can compare before editing. Suppose a documentation site's search sometimes shows results for an earlier query. You could ask one session to inspect the browser-side request handling and another to inspect how the search index is generated.

An illustrative brief for the first session:

Investigate whether older search responses can overwrite newer results.
Read only: inspect the search UI and its request-handling code. Do not edit files.
Identify where responses become visible and whether stale responses are discarded.
Return file locations, the relevant control flow, and a reproduction plan.
Stop if the answer requires changing the search index format.

The second brief can ask for a read-only index investigation: identify the index generation command, when generated data is refreshed, and what evidence would distinguish an old index from a browser response-order problem. It should return findings without changing the index or UI. These are example tasks, not reported test results.

Submit each brief separately. The success signal is two rows representing the two responsibilities. Rename them with Ctrl+R if their automatic names are hard to distinguish. Check their findings, then choose one implementation task based on the evidence; there is little benefit in asking both sessions to implement competing fixes to the same search component.

You can also dispatch from the shell:

claude --bg --name "search-response-review" "Read only: inspect whether stale search responses can overwrite newer results. Return file locations and a reproduction plan; do not edit files."
claude agents

The launch prints a short session ID and commands for attaching, reading logs, and stopping it. Save that ID if you will manage the session from the shell. The task is a positional prompt: --bg cannot be combined with -p or --print, because those do not start the interactive session that Agent View can attach to. See shell dispatch.

Move an existing conversation or copy its context

Use /bg inside an existing conversation to move that conversation to the background. You can add one last instruction, such as /bg finish the read-only index investigation. Pressing ← on an empty prompt also backgrounds a foreground conversation and opens the dashboard. /bg requires a first message in a fresh conversation; the empty-prompt arrow shortcut can create the row immediately.

Use /fork when you want a second conversation with the context accumulated so far while you continue in the original. On Claude Code v2.1.212 or later, it creates an independent background session with that context. On older v2.1.161–2.1.211 versions it instead starts a forked subagent, now called /subtask; disabling Agent View also changes this behavior. See the fork documentation.

A fork can start back in the origin checkout when the original is in a linked worktree. Read the confirmation and verify the copy's working directory before giving it an editing task. Context inheritance does not establish separate ownership of files.

Read the row, then intervene in the right place

Agent View groups urgent sessions near the top, but the group heading alone does not prove a successful result. In particular, Completed includes finished, failed, and stopped sessions. Check the individual state and output.

The state and peek documentation explains these controls. Typing into peek does not approve a permission dialog; that message waits in the queue. A normal follow-up to a working session also queues rather than interrupting its current response.

For the search example, if the UI investigator asks which client component serves the page, answer in peek. If it needs permission to run the agreed reproduction command, attach and examine that request. After the two investigations finish, ask for the missing evidence or begin a scoped fix in the appropriate conversation. Keep the review decision tied to files and reproducible checks, rather than the row's short summary.

Enter or → opens the full conversation and a recap. While attached, ← on an empty prompt or /exit returns to the dashboard without stopping the session. Ctrl+C cancels a running response or shell command; double Ctrl+C on an empty prompt detaches. Esc in the dashboard closes its current panel or clears input before eventually leaving the view. If you entered by backgrounding a foreground conversation, the final Esc returns to that conversation. See attach and detach behavior.

Use s:blocked in the dispatch input to find sessions waiting on you. A filter is handled differently from a task: Enter opens a matching session. Name filtering with n:search requires v2.1.287 or later. Press ? for the shortcuts supported in your current view.

For shell inspection, replace SESSION_ID below with the short ID printed at launch:

claude logs SESSION_ID
claude attach SESSION_ID

Attach and logs also accept a partial session name on v2.1.290 or later. Attaching by name requires a running process; use the ID to wake a stopped session. The supported shell commands are a better interface than private session files.

Review and preserve changes before deleting a session

After an investigation, preserve useful findings in your issue or working notes. After an editing task, attach and locate its working directory, branch, changed files, and check results. Review the diff and decide which changes belong in your project before treating the work as complete.

Newly dispatched background sessions in a normal Git checkout move into their own worktrees before editing, with isolation enforced for their file-editing tools and subagents. However, a conversation moved to the background keeps its existing location. A session already inside a linked worktree uses that checkout; non-Git directories without a suitable worktree hook, writes outside the working directory, and disabled background isolation also change the behavior. See file-edit isolation.

So check the location instead of assuming every row created a fresh checkout. Separate worktrees let sessions edit separate copies; they do not decide whether two changes are compatible or merge them for you.

Claude is instructed to preserve changes it made in a worktree it entered: commit, push when a remote exists, and open a draft pull request when the task calls for it. Your task's Git instructions take precedence. If you want to review locally and handle commits or pushes yourself, state that in the task brief before dispatch. A PR label in the dashboard helps find the result, but your review still needs the actual diff and checks.

Stopping and deleting are different actions:

• A single Ctrl+X stops the selected session. claude stop SESSION_ID does the same from the shell.
• A second Ctrl+X within two seconds requests deletion. For a Claude-created worktree, this can remove uncommitted changes. Preserve wanted work before that second press.
• claude rm SESSION_ID keeps a Claude-created worktree and its row when there are uncommitted changes. A worktree you created yourself is left in place by either deletion method.

Deletion can also be refused because another session uses or locks the worktree, or because commits have not been confirmed saved elsewhere. Resolve the named reason and preserve the work before trying again. Commands offered to discard unpushed commits are destructive options for that exact refusal, not routine cleanup commands.

The deletion rules retain the conversation transcript for claude --resume, subject to later transcript cleanup. A saved conversation is not a backup of deleted uncommitted files. For the search example, keep the findings or reviewed fix first; only then remove the investigative rows you no longer need.

Recover an interrupted session without duplicating the task

Closing Agent View or its terminal leaves supervised background sessions running. Sleep preserves the sessions and their processes resume on wake; shutting down or restarting the computer stops running work. Start recovery from the existing row and its ID, rather than dispatching the original task again.

After shutdown, attach to the failed or stopped row and ask it to continue. A stopped row whose last progress was more than 48 hours ago asks for a second Enter to resume; a reply or claude attach SESSION_ID resumes without that extra footer confirmation. The shutdown recovery guide documents these distinctions.

claude respawn can rerun the original prompt when no saved conversation remains. That is fresh execution, so check what the previous attempt already changed before using it. A shell-job row is different: Claude Code does not automatically rerun its command when you attach, because that would execute it again. See recovery and shell management.

For an unresponsive supervisor, the documented recovery sequence is:

claude daemon status
claude daemon stop --any --keep-workers
claude agents

The first command shows the supervisor state and version. --keep-workers leaves workers running while you replace the supervisor. On macOS and Linux, start the new supervisor within about a minute so it can reconnect; otherwise workers stop and need to resume from saved conversations. Without --keep-workers, stopping the supervisor also stops its sessions. Use this sequence for the background-service failure, rather than restarting all healthy workers to fix one failed task.

A slow attachment to a finished, unattended session can simply mean its process was stopped after roughly an hour of inactivity to free resources. Its conversation remains available. Pinning with Ctrl+T keeps an idle process running, but does not keep a local session running through shutdown or guarantee it survives low-memory pressure.

Keep usage and configuration visible as you add sessions

Each background session consumes normal subscription usage or provider capacity. Add concurrency when it saves useful waiting time and you can still review the results. Several simultaneous conversations can exhaust the same account limits sooner; a dashboard row is not a separate allowance.

Row names and summaries also involve model use. End-of-turn summaries and occasional mid-turn rewrites make short Haiku-class requests through your normal provider; the frequent updates between rewrites reuse existing output. A provider without a configured Haiku-class model uses the session's main model for those requests. The row-summary documentation explains the distinction, so do not estimate cost from the main task alone.

Check the dispatch model in the header and any active defaults in the footer. /model in the dispatch input changes the default for later sessions during that dashboard run; it does not retroactively change every existing session. Backgrounding an existing conversation keeps its permission mode. New dispatches depend on the target directory's configuration and how you opened the view. See permission mode, model, and effort.

If interactive work succeeds but a background task fails before starting, inspect the reported error and its configuration source. Provider settings depend on the target directory and supervisor context; shell-only gateway configuration is forwarded only under the documented conditions. Consult settings and provider behavior instead of assuming every worker inherited the current shell's configuration.

For an external status display, use the supported command:

claude agents --json --all

--all includes completed background sessions. Read state for work status: working, blocked, done, failed, or stopped. pid and status are present while the process is alive; waitingFor identifies a live waiting prompt when applicable. A finished turn awaiting a new task is done, not blocked. The JSON interface is supported; private job files are not a stable scripting API.

FAQ

How do I get out of Claude Code Agent View?

Press Esc to close a panel or clear input, then leave the dashboard. When you opened it by backgrounding a conversation with ←, the final Esc returns to that conversation. While attached to a background session, ← on an empty prompt or /exit detaches. These actions keep background work running; use Ctrl+X on the row or claude stop SESSION_ID to stop it. See the navigation controls.

Why doesn't Agent View show my subagents?

Subagents and team workers are not separate Agent View rows. The dashboard lists independent background sessions. Use /tasks inside the parent conversation to inspect its background work. /agents concerns custom subagent definitions and is separate from the shell command claude agents. See checking running work.

Can I bring a deleted session back into Agent View?

On v2.1.212 or later, a bare /resume in the dashboard dispatch input opens the repository's past-session picker, including conversations removed from the list. This picker is unavailable in a --cwd-scoped view or some restricted/custom launch configurations; targeted resume commands require an attached conversation. A remaining transcript can restore the conversation, but not deleted uncommitted files. See organizing and resuming sessions.

Can Agent View run a test command without starting a model session?

Yes. claude --bg --exec 'npm test' runs that command as a shell job, assuming it is the correct test command for your repository. You can also enter ! followed by the command in the dashboard. No model is invoked for that job, and its output is not sent to a Claude session. Captured output is kept in memory; the row and output are removed roughly five minutes after the job exits, so read or capture the result while available. See background shell jobs.