Agent view

Agent view is a single terminal screen for every background session you have running. You type a task, it becomes a row, and the row tells you whether Claude is working, waiting on you, or done. You only open a full conversation when one actually needs you.

Each row is a complete Claude Code session that keeps going with no terminal attached. A separate supervisor process hosts them, so you can close agent view, close the shell, or start something else and the work carries on.

I use it for the jobs that do not need me watching: a dependency bump, a flaky-test hunt, a review of someone else's PR. Three prompts, three rows, and I get on with my own work until one turns yellow.

Note: Agent view is a research preview. Keys and layout may change.

For how it compares with subagents, teams and workflows, see Run agents in parallel. If you want Claude to start and track parallel sessions in the cloud from one conversation instead, look at Projects.

Getting started

1. Open it. Run claude agents from your shell. If the directory is not yet trusted, you get the usual workspace trust dialog first; declining exits.
2. Dispatch. Type a task at the bottom and press Enter. Every prompt you submit here starts a new session; it never sends a follow-up to an existing one.
3. Peek. Highlight a row and press Space. The panel shows the latest output or the question it is stuck on. Type a reply and press Enter to answer without leaving the list.
4. Attach. Press Enter or → to take over the terminal with the full session. Press ← on an empty prompt to go back to the list.
5. Bring in an existing session. In any ordinary claude session, run /bg (or press ← on an empty prompt) to send it to the background and open agent view.

Esc leaves agent view. If you arrived by pressing ← in a session, Esc takes you back to that conversation instead.

In a normal session, the prompt footer's ← hint shows how many background agents are waiting, for example ← 2 agents, and flashes briefly when one finishes (← 2 done). The flashes respect prefersReducedMotion.

Make it the default

Turn on Open agents view by default in /config, or type:

/config defaultToAgentsView=true

From then on, plain claude opens agent view. Pass a prompt (claude "tidy the README") to get an ordinary session. Set it back to false the same way.

Reading the list

By default the list shows background sessions from every project. Narrow it with:

claude agents --cwd ~/clients/acme-portal

That includes sessions that have since moved into a worktree under that folder's .claude/worktrees/. Interactive sessions in other terminals are not listed until you background them, and subagents or teammates a session spawns do not get rows of their own.

Here is roughly what a busy list looks like:

Pinned
  ✽ invoice export          Writing CSV writer for VAT breakdown          6m

Ready for review
  ∙ stripe upgrade          Draft PR open, types fixed                 #318  1h

Needs input
  ✻ email templates         keep the old footer or use the new brand one?  2m

Working
  ✽ flaky checkout test     Re-running suite with retries disabled        4m
  ✢ nightly lint            12 runs, all clean                        in 9m

Completed
  ∙ README refresh          Rewrote setup section                         3h
  … 4 more

State colours

The icon shape adds a second signal: ✻ or an animated ✽ means the process is alive, ∙ means it has exited (replying or attaching restarts it from where it was), and ✢ marks a /loop session sleeping between runs, with its run count and countdown.

While agent view is open, the terminal tab title shows something like 2 awaiting input · claude agents, and Claude Code sends your configured terminal notification when a session needs input, finishes or fails. /loop sessions only notify when they need you. These fire the Notification hook with type agent_needs_input or agent_completed.

Summaries

The one-line text on each row comes from a Haiku-class model. During a turn it refreshes at most every 15 seconds from the session's own output without a model call, gets rewritten every few minutes on long turns, and gets a proper summary when the turn ends. Those summary calls go through your normal provider. On a provider with no Haiku-class model configured, set ANTHROPIC_DEFAULT_HAIKU_MODEL or it falls back to the session's main model.

Pull request labels

When a session opens or works on a PR, a #1234 label (or !1234 for a GitLab merge request) appears on the right and links to it. Its colour tracks status:

Claude Code finds the PR from gh command output, from gh pr checkout, or by looking up the branch after a push. It retries the lookup across the next five git, gh, glab or curl commands, so a PR created just after the push still links. Several PRs show as a count such as 3 PRs. Set FORCE_HYPERLINK=0 if the link escape codes cause trouble.

My habit: when a row goes green with a PR number, that is my cue to review and merge.

Peeking and replying

Space opens the peek panel. For a waiting session it shows the exact question; for a finished one, the result; for a working one, its full status line. Linked PRs are listed, and for a waiting session a line such as waiting 3m tells you how long it has been stuck.

Replies behave differently by situation:

• Session is working: /model, /effort, /rename and /usage apply immediately. Anything else joins the message queue and is picked up when queued input normally is.
• Exactly /stop: stops the session at once.
• Prefix !: sends a Bash command instead.
• A question with numbered choices: press the number to fill it in, then Enter.
• A free-text question: type your answer, or Tab to accept a suggested reply.
• A permission prompt or other dialog: replying does not answer it. Attach with → to deal with the dialog.

If delivery fails because the background service is unreachable, the reply is saved and sent when the session next starts (except ! commands). Hold-to-talk voice dictation works in the reply and dispatch inputs. ↑ and ↓ move the peek to neighbouring rows.

Attaching

Enter or → attaches. Claude gives you a short recap of what happened while you were away, and then it is a normal session. Attached sessions always render in fullscreen mode because there is no scrollback to append to; scroll with PgUp, PgDn or the mouse, and use Ctrl+O for transcript mode.

Commands that need a human at a dialog, such as /install-github-app or the /mcp settings list, put an unattended session into Needs input with a row like open this session to manage MCP servers. Attach and run the command again. /mcp reconnect, /mcp enable and /mcp disable work either way.

To leave:

Detaching never stops the session. A single Ctrl+C still cancels the running response as normal. On Windows, a ← within half a second of attaching asks you to press again.

Switching from a foreground session

In a session you started in the terminal, ← on an empty prompt backgrounds it and opens agent view with that row selected, under the banner Your conversation moved to the background. Enter reopens it, Esc undoes the switch, and Ctrl+C twice exits to the shell. The task list travels with the conversation.

If a tool is running, Claude Code waits for it before switching (press ← again to skip the wait). After about ten seconds it switches anyway, unless foreground subagents are running, a prompt or question is waiting for you, or you have typed into the input. Turn the shortcut off with leftArrowOpensAgents in /config.

Organising the list

Groups run Ready for review and Needs input first, then Working, then Completed. A session lands in Ready for review when its PR needs review or has failing checks; Completed also collects failed and stopped sessions.

• Ctrl+S switches between grouping by state and by directory (remembered between runs).
• Ctrl+T pins a session to the top and keeps its process alive while idle.
• Shift+↑ / Shift+↓ reorders.
• Ctrl+R renames.
• Enter on a group header collapses it.
• Ctrl+X stops a session; a second Ctrl+X within two seconds deletes it. On a group header it deletes the whole group after confirming.

Deleted sessions keep their transcript on disk for claude --resume. To bring one back as a row, type a bare /resume (or /continue) in the dispatch input (v2.1.212+) and pick from the repository's past sessions. The picker does not open when you pass an ID or search term, or when the view was opened with --cwd, --safe-mode, --permission-mode, --settings or similar flags.

Filters

Start the dispatch input with a filter to narrow the list as you type:

Combine with spaces: s:blocked a:reviewer shows reviewer sessions that need you.

Keys

Most of these can be rebound in the Agents context of keybindings.

Dispatching work

From agent view

Type a task and press Enter. A Haiku-class model names the session, and you can rename it with Ctrl+R. Paste screenshots straight in. Pasted text over 800 characters or three lines collapses to [Pasted text #N]; paste it again to expand it for editing. Prompts under four characters are rejected as Too short.

/exit, /quit, /logout, /login, /model and a bare /resume run in agent view itself. Skills, your own commands and prompt-expanding built-ins such as /init become the new session's first prompt; other built-ins tell you to attach first.

If an @name matches both a subagent and a repository, the subagent wins. That first-word rule can surprise you: a prompt that happens to start with an agent's name dispatches that agent.

Choosing a directory

Sessions start where you opened agent view. To target somewhere else, open claude agents there; or open it in a parent folder and use @<repo>, which lists git repositories one level down, worktrees inside the launch repository, and directories that already have sessions (names with spaces are not listed); or cd and run claude --bg. When grouped by directory, dispatching goes to the selected group's folder.

From inside a session

• /background (alias /bg) moves the current conversation to the background and frees the terminal. Add a final instruction: /bg run the integration tests and fix what breaks. Exiting while subagents, workflows or monitors are running also offers Move to background and exit.
• /fork copies the conversation into a new background session while the original carries on (v2.1.212+). The copy keeps model, permission mode, effort, added directories and "don't ask again" grants. With a prompt, it starts immediately; without one it waits for instructions. Sessions launched with flags the copy cannot inherit, such as a replaced system prompt or --tools, cannot be forked.

When you background, in-flight background shell commands, backgrounded subagents, dynamic workflows, /loop tasks and automatic artifact comment replies move with it. Running monitors cannot move and are stopped, so you get a Background this session? dialog first. A workflow with running subagents also triggers the dialog because those subagents restart from scratch. Set CLAUDE_DISABLE_ADOPT=1 to stop in-flight work instead of moving it.

These launch flags carry over: --mcp-config, --strict-mcp-config, --settings, --setting-sources, --add-dir, --plugin-dir, --fallback-model and --allow-dangerously-skip-permissions, plus directories added with /add-dir.

From the shell

claude --bg "find out why the PDF export times out on large invoices"
claude --bg --name pdf-timeout "find out why the PDF export times out"
claude --agent migration-checker --bg "review the migrations on this branch"
claude --resume <session-uuid> --bg "carry on and finish the refactor"

--bg (long form --background) takes the prompt as a positional argument and cannot be combined with -p. Untrusted directories show the trust dialog, or fail with Workspace not trusted in scripts. An unknown --agent name makes the session exit with --agent '<name>' not found.

On v2.1.257+, --resume <id> --bg continues the session in place where possible, or starts a copy and prints a note: explaining why. --continue, a bare --resume or a name always start a copy; --fork-session starts one deliberately.

The command prints the short ID and the management commands:

backgrounded · 3a91f0c2 · pdf-timeout
  claude agents             list sessions
  claude attach 3a91f0c2    open in this terminal
  claude logs 3a91f0c2      show recent output
  claude stop 3a91f0c2      stop this session

Shell jobs

claude --bg --exec 'npm run test:e2e' (or ! in the dispatch input) runs a plain command as a PTY-backed row with no model involved. Its last output line is its status. Output lives in memory only and the row disappears about five minutes after the command exits, so grab the result with claude logs <id> before then. Claude Code never re-runs a shell job on restart.

How file edits are isolated

A dispatched session starts in your working directory, then moves into its own git worktree under .claude/worktrees/ before its first edit, so parallel sessions never collide. Claude Code then enforces that isolation for the session and any subagents.

It skips the worktree when you backgrounded an existing session, when the session or the edited file is already in a linked worktree, when the directory is not a git repository and there is no WorktreeCreate hook, or when the write is outside the working directory.

Turn isolation off for a repository with:

{
  "worktree": {
    "bgIsolation": "none"
  }
}

Outside git, sessions share the directory, so do not dispatch overlapping edits. Other version control systems can use a WorktreeCreate hook.

A session that edited inside its own worktree is told to preserve its work: commit without asking, push if there is a remote, and open a draft PR when it suits the task. It never pushes to main or master, force-pushes or merges, and your own instructions in the task, CLAUDE.md or memory override this. A session editing a checkout it did not isolate asks before committing or switching branches. Every job ends with a report saying where the work is.

What deletion removes

Deleting a session (double Ctrl+X or claude rm) removes the row but keeps the transcript. For a worktree Claude created:

• Agent view removes it, uncommitted changes included. Commit first.
• claude rm keeps the worktree and the row if there are uncommitted changes.
• A worktree in use or locked by another session is never removed; the row shows not deleted.
• If the worktree has commits not found on a remote or on your checked-out default branch, deletion is refused with the branch name and count. Push or merge them, or delete again (or run claude rm <id> --discard-unpushed <value> as printed) to throw them away.
• If git or your WorktreeRemove hook fails, the message says why. Deleting again, or claude rm <id> --force-remove-worktree <worktree-id>, removes the directory when it is safe, leaving the branch.

A worktree you created yourself is always left alone.

Model, permission mode and effort

Model

The header shows the dispatch model, taken from your user model setting. Override it for the whole run with claude agents --model, or type /model sonnet in the dispatch input; the header gains a (session) marker and /model default clears it. Per session, use claude --bg --model, attach and run /model, or dispatch a subagent with its own model.

Settings and provider

A background session reads settings from its own directory, including project env values, and inherits the dispatching shell's PATH, provider selection (CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX and so on), ANTHROPIC_DEFAULT_*_MODEL values and CLAUDE_CODE_EXTRA_BODY.

If you use an LLM gateway, put its variables in a settings file's env block. A shell-only ANTHROPIC_BASE_URL reaches background sessions only in narrow cases (when the supervisor was started from a shell with the same gateway and you are backgrounding, dispatching or waking a session in the current directory).

Permission mode

• Backgrounded with /bg or ←: keeps its current mode.
• Dispatched from an agent view opened with ←: the target directory's permissions.defaultMode first (with auto and bypassPermissions honoured only from managed, --settings or user settings, and project settings never allowed to be more permissive than where you came from), then the mode you came from.
• Dispatched from claude agents in a shell, or claude --bg: starts as a fresh claude in that directory would.

Dispatch defaults

claude agents --permission-mode plan --model opus --effort high --agent reviewer

--effort accepts the same values as the top-level flag, including ultracode. --agent defaults to the agent setting, then the built-in claude agent. --dangerously-skip-permissions is shorthand for bypass mode and --allow-dangerously-skip-permissions adds it to each session's Shift+Tab cycle; both require the one-time disclaimer. --restricted starts every dispatched session in restricted mode (v2.1.248+). Active defaults appear in the footer.

Mode, model, effort, carried flags, /rename names and Ctrl+S stashed prompts all survive supervisor restarts.

Settings, plugins and MCP

claude agents accepts --settings, --setting-sources, --add-dir, --plugin-dir, --mcp-config and --strict-mcp-config, and passes them all to dispatched sessions. Repeat a flag once per value. Put --add-dir and --mcp-config after agents, or claude agents --json fails with unknown option.

Shell commands

Name matching for attach and logs needs v2.1.290+.

Scripting against session state

claude agents --json --all is the supported interface; do not parse ~/.claude/jobs/. Each entry has cwd, kind and startedAt, plus id and state for background sessions, pid and status (busy, waiting, idle) while alive, waitingFor when waiting, and sessionId and name when set.

Each session gets CLAUDE_JOB_DIR pointing at ~/.claude/jobs/<id>; its tmp/ subfolder is a private scratch area where Write and Edit do not prompt, deleted with the session.

How it is hosted

The supervisor starts the first time you background something or open agent view. Each session is its own process under it. Working, waiting-on-a-dialog and attached sessions keep running; idle or finished ones unattached for about an hour are stopped to save resources and restart on demand (pin to prevent this). Crashed sessions are restarted. After an auto-update the supervisor moves itself and idle sessions to the new version.

State lives under your config directory (or CLAUDE_CONFIG_DIR, which gives a separate supervisor):

/status shows Session kind as background job · attached, background job · unattended or interactive.

To switch the whole feature off, set disableAgentView to true or export CLAUDE_CODE_DISABLE_AGENT_VIEW. Admins can enforce this through managed settings.

Troubleshooting

Limitations

• Background sessions use your plan's quota just like interactive ones, so parallelism burns it faster.
• Sessions run locally. They survive sleep but not shutdown.
• Deleting from agent view removes Claude-created worktrees, uncommitted work included.

Related

• Run agents in parallel
• Cross-session messaging
• Worktrees
• Claude Code on the web
• Sessions