16 ファイル変更+161-74
この更新の概要
Agent View機能がリサーチプレビューとして大幅に拡張され、バックグラウンドセッションの管理、状態表示の詳細化、モデル設定の個別指定などが可能になりました。プロジェクト設定やスキルの検索パスが変更され、親ディレクトリを遡って.claudeディレクトリやCLAUDE.mdファイルを探索する仕様に統一されています。また、GitHub連携における権限モデルが整理され、アプリのインストール状況に関わらず接続アカウントがアクセス可能なリポジトリを操作できることが明記されました。
CLAUDE.mdやルールの読み込みパスが変更され、現在のディレクトリからリポジトリのルートまで親ディレクトリを遡って探索する仕様が詳しく定義されました。
@@ -68,13 +68,13 @@ Each source loads settings from a specific location, where `<cwd>` is the workin
| Source | What it loads | Location |
| :- | :- | :- |
| `"project"` | Project CLAUDE.md, `.claude/rules/*.md`, project skills, project hooks, project `settings.json` | `<cwd>/.claude/` and each parent directory up to the filesystem root (stopping when a `.claude/` is found or no more parents exist) |
| `"project"` | Project CLAUDE.md, `.claude/rules/*.md`, project skills, project hooks, project `settings.json` | `<cwd>/.claude/` for `settings.json` and hooks; `<cwd>` and every parent directory for CLAUDE.md and rules; `<cwd>` and every parent directory up to the repository root for skills |
| `"user"` | User CLAUDE.md, `~/.claude/rules/*.md`, user skills, user settings | `~/.claude/` |
| `"local"` | CLAUDE.local.md (gitignored), `.claude/settings.local.json` | `<cwd>/` |
| `"local"` | CLAUDE.local.md, `.claude/settings.local.json` | `<cwd>/.claude/` for `settings.local.json`; `<cwd>` and every parent directory for CLAUDE.local.md |
Omitting `settingSources` is equivalent to `["user", "project", "local"]`.
The `cwd` option determines where the SDK looks for project settings. If neither `cwd` nor any of its parent directories contains a `.claude/` folder, project-level features won't load.
The `cwd` option determines where the SDK looks for project-level inputs. CLAUDE.md and rules load from `<cwd>` and from every parent directory. Skills load from `<cwd>` and from every parent directory up to the repository root. Project `settings.json` and hooks load only from `<cwd>/.claude/` with no parent-directory fallback.
### What settingSources does not control
@@ -97,10 +97,10 @@ Do not rely on default `query()` options for multi-tenant isolation. Because the
| Level | Location | When loaded |
| :- | :- | :- |
| Project (root) | `<cwd>/CLAUDE.md` or `<cwd>/.claude/CLAUDE.md` | `settingSources` includes `"project"` |
| Project rules | `<cwd>/.claude/rules/*.md` | `settingSources` includes `"project"` |
| Project rules | `<cwd>/.claude/rules/*.md` and `.claude/rules/*.md` in every parent directory | `settingSources` includes `"project"` |
| Project (parent dirs) | `CLAUDE.md` files in directories above `cwd` | `settingSources` includes `"project"`, loaded at session start |
| Project (child dirs) | `CLAUDE.md` files in subdirectories of `cwd` | `settingSources` includes `"project"`, loaded on demand when the agent reads a file in that subtree |
| Local (gitignored) | `<cwd>/CLAUDE.local.md` | `settingSources` includes `"local"` |
| Local | `<cwd>/CLAUDE.local.md` and `CLAUDE.local.md` in every parent directory | `settingSources` includes `"local"` |
| User | `~/.claude/CLAUDE.md` | `settingSources` includes `"user"` |
| User rules | `~/.claude/rules/*.md` | `settingSources` includes `"user"` |
@@ -25,7 +25,7 @@ When using the Claude Agent SDK, Skills are:
Unlike subagents (which can be defined programmatically), Skills must be created as filesystem artifacts. The SDK does not provide a programmatic API for registering Skills.
Skills are discovered through the filesystem setting sources. With default `query()` options, the SDK loads user and project sources, so skills in `~/.claude/skills/` and `<cwd>/.claude/skills/` are available. If you set `settingSources` explicitly, include `'user'` or `'project'` to keep skill discovery, or use the [`plugins` option](/en/agent-sdk/plugins) to load skills from a specific path.
Skills are discovered through the filesystem setting sources. With default `query()` options, the SDK loads user and project sources, so skills in `~/.claude/skills/`, `<cwd>/.claude/skills/`, and `.claude/skills/` in any parent directory of `<cwd>` up to the repository root are available. If you set `settingSources` explicitly, include `'user'` or `'project'` to keep skill discovery, or use the [`plugins` option](/en/agent-sdk/plugins) to load skills from a specific path.
## Using Skills with the SDK
@@ -233,12 +233,12 @@ const options = {
For more details on `settingSources`/`setting_sources`, see the [TypeScript SDK reference](/en/agent-sdk/typescript#settingsource) or [Python SDK reference](/en/agent-sdk/python#settingsource).
**Check working directory**: The SDK loads Skills relative to the `cwd` option. Ensure it points to a directory containing `.claude/skills/`:
**Check working directory**: The SDK loads Skills from `.claude/skills/` in the `cwd` option and in every parent directory up to the repository root. Ensure `cwd` points at or below the directory containing `.claude/skills/`, within the same repository:
```python Python theme={null}
# Ensure your cwd points to the directory containing .claude/skills/
options = ClaudeAgentOptions(
cwd="/path/to/project", # Must contain .claude/skills/
cwd="/path/to/project", # .claude/skills/ here or in a parent directory
setting_sources=["user", "project"], # Loads skills from these sources
skills="all",
)
@@ -247,7 +247,7 @@ options = ClaudeAgentOptions(
```typescript TypeScript theme={null}
// Ensure your cwd points to the directory containing .claude/skills/
const options = {
cwd: "/path/to/project", // Must contain .claude/skills/
cwd: "/path/to/project", // .claude/skills/ here or in a parent directory
settingSources: ["user", "project"], // Loads skills from these sources
skills: "all"
};
@@ -325,7 +325,7 @@ function resolveSettings(
| :- | :- | :- | :- |
| `options.cwd` | `string` | `process.cwd()` | Directory to resolve project and local settings relative to |
| `options.settingSources` | [`SettingSource`](#settingsource)`[]` | All sources | Which filesystem sources to load. Pass `[]` to skip user, project, and local settings. Managed policy settings load in all cases |
| `options.managedSettings` | `Settings` | `undefined` | Restrictive policy-tier settings merged at the managed-policy precedence level. Non-restrictive keys such as `model` are silently dropped |
| `options.managedSettings` | `Settings` | `undefined` | Restrictive policy-tier settings supplied by the embedding host. Dropped by default when an admin-deployed managed tier is present; merged under that tier when [`parentSettingsBehavior`](/en/settings#available-settings) is `"merge"`. Non-restrictive keys such as `model` are silently dropped so this option can tighten managed policy but not loosen it |
| `options.serverManagedSettings` | `Settings` | `undefined` | Server-managed settings payload from `/api/claude_code/settings`. Non-restrictive keys pass through unfiltered |
#### Return type: `ResolvedSettings`
バックグラウンドセッションを管理するAgent Viewの全般的な説明が刷新され、アイコンの形状によるプロセス状態の識別やセッションごとのモデル変更、トラブルシューティング情報が大幅に追加されました。
@@ -7,25 +7,27 @@ source: https://code.claude.com/docs/en/agent-view.md
> Dispatch and manage many Claude Code sessions from one screen. Agent view shows what every session is doing and which ones need your input.
Agent view, opened with `claude agents`, is one screen for all your background sessions: what's running, what needs your input, and what's done. Dispatch new sessions, watch their state at a glance instead of scrolling through transcripts, and step in only when one needs you. Sessions keep running in the background without a terminal attached.
Agent view, opened with `claude agents`, is one screen for all your background sessions: what's running, what needs your input, and what's done. Dispatch new sessions, watch their state at a glance instead of scrolling through transcripts, and step in only when one needs you. Each background session is a full Claude Code conversation that keeps running without a terminal attached, so you can open it, reply, and leave whenever you want.
Use agent view when you have several independent tasks Claude can work on at once, such as fixing a bug, reviewing a pull request, or investigating a log. When you want to work through a problem together, attach to a session and use Claude Code interactively as usual.
Use agent view when you have several independent tasks Claude can work on without you watching every step. Dispatch a bug fix, a pull request review, and a flaky-test investigation as three rows, keep working in another window, and check back when a row shows it needs you or has a result.
Sessions in agent view run independently and report only to you. To compare with subagents, agent teams, and worktrees, see [Run agents in parallel](/en/agents).
When you want to work more directly in any agent's session, attach to the row to enter the full conversation.
Agent view is a research preview and requires Claude Code v2.1.139 or later. Check your version with `claude --version`. The interface and keyboard shortcuts may change as the feature evolves, and administrators can disable agent view for an organization with the [`disableAgentView`](#how-background-sessions-are-hosted) managed setting.
To compare agent view with subagents, agent teams, and worktrees, see [Run agents in parallel](/en/agents).
Agent view is in research preview and requires Claude Code v2.1.139 or later. Check your version with `claude --version`. The interface and keyboard shortcuts may change as the feature evolves.
This page covers:
- [Quick start](#quick-start)
- [Quick start](#quick-start): give Claude a task to work on in the background, check on it, and step in when needed
- [Monitor sessions with agent view](#monitor-sessions-with-agent-view), including state icons, peeking and replying, attaching, organizing, and keyboard shortcuts
- [Dispatch new agents](#dispatch-new-agents) from agent view, from inside a session, or from the shell
- [Dispatch new agents](#dispatch-new-agents) from agent view, from inside a session, or from your shell
- [Manage sessions from the shell](#manage-sessions-from-the-shell)
- [How background sessions are hosted](#how-background-sessions-are-hosted) by the supervisor process
## Quick start
This walkthrough opens agent view, dispatches a session, replies from the peek panel, and attaches for the full conversation.
This walkthrough covers the core agent view loop: dispatch a task, watch its row update as Claude works, peek to check on it and reply, and attach for the full conversation. The session you dispatch keeps running after you close agent view, so you can leave and come back to it.
From your shell, run:
@@ -33,15 +35,19 @@ From your shell, run:
claude agents
```
Agent view opens with 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.
Agent view opens with an input at the bottom and a table that fills in as sessions start. Press `Esc` at any time to return to your shell. Your sessions keep running while you're away and reappear the next time you open agent view.
Type a prompt describing a task and press `Enter`. A new background session starts on that task and appears as a row showing whether it's working, waiting on you, or done. The new session uses the model shown in the agent view header and the same [permission mode](#permission-mode-and-settings) you'd get running `claude` in that directory.
Every prompt you enter here starts its own new session. Typing another prompt and pressing `Enter` launches a second session alongside the first rather than sending a follow-up to it. You can run several in parallel this way.
Type a prompt in the input and press `Enter`. A new session starts and appears as a row showing whether it's working, waiting on you, or done. Repeat to run several sessions in parallel. Each one uses your subscription quota independently, so see [Limitations](#limitations) before dispatching many at once.
Each session uses your subscription quota independently, so see [Limitations](#limitations) before dispatching many at once.
Select a row with the arrow keys and press `Space` to see what the session is doing or what it needs from you. Type a reply and press `Enter` to send it without leaving agent view.
Select a row with the arrow keys and press `Space` to open the peek panel. It shows the session's most recent output, or the question it's waiting on, rather than the full transcript. Type a reply and press `Enter` to send it without leaving agent view.
Press `Enter` or `→` on a row to attach when you want the full conversation. The session takes over the terminal exactly as if you had run `claude`. Press `←` on an empty prompt to detach and return to the table.
To bring an existing interactive session into agent view, run `/bg` inside it, or press `←` on an empty prompt to background the session and open agent view in one step. The session keeps running in the background and appears as a row. To start a new background session directly from the shell, run `claude --bg "<prompt>"`.
To move a session you already have open into agent view, run `/bg` inside it, or press `←` on an empty prompt to background it and open agent view in one step. The session keeps running and appears as a row alongside the ones you dispatched.
You can use `claude agents` as your primary entry point instead of `claude`: dispatch every task from agent view, attach when you want the full conversation, and press `←` to return to the table.
@@ -49,14 +55,14 @@ You can use `claude agents` as your primary entry point instead of `claude`: dis
Run `claude agents` to open agent view. It takes over the full terminal and lists every session grouped by state, with pinned sessions and the ones that need you at the top. Each row shows the session's name, current activity, and how long ago it last changed.
The list covers every background session under your [config directory](#how-background-sessions-are-hosted), regardless of which project or worktree it's working in, so a session started in one repository and another started in a different worktree both appear together. Interactive sessions you have open in other terminals don't appear until you [background them](#from-inside-a-session), and [subagents](/en/sub-agents) running inside a session aren't listed as separate rows.
The list shows every background session you've started, across all your projects. A session working in one repository and another in a different worktree both appear here, regardless of which directory you opened agent view from. Interactive sessions you have open in other terminals don't appear until you [background them](#from-inside-a-session). [Subagents](/en/sub-agents) and [teammates](/en/agent-teams) a session spawns aren't listed as separate rows.
```text
Pinned
✽ clawd walk cycle Write assets/sprites/clawd-walk.png 3m
Ready for review
∙ jump physics github.com/anthropics/example/pull/2048 ● 2h
∙ jump physics github.com/example/game/pull/2048 ● 2h
Needs input
✻ power-up design needs input: double jump or wall climb? 1m
@@ -71,24 +77,38 @@ Completed
… 6 more
```
Each row's icon carries two signals. The indicator tells you the session's state, and the icon's shape tells you whether the underlying process is still running. The states are:
### Read session state
| Indicator | State | What it means |
Each row starts with an icon whose color and animation show the session's state:
| State | Icon shows as | What it means |
| :- | :- | :- |
| Animated | Working | Claude is actively running tools or generating a response |
| Yellow | Needs input | Claude is waiting for your input, usually a permission decision or an answer |
| Dimmed | Idle | The session is waiting for input but isn't blocked on a specific question |
| Green | Completed | The task finished successfully |
| Red | Failed | The task ended with an error |
| Grey | Stopped | The session was stopped with `Ctrl+X` or `claude stop` |
| Working | Animated | Claude is actively running tools or generating a response |
| Needs input | Yellow | Claude is waiting on a specific question or permission decision from you |
| Idle | Dimmed | The session has nothing to do and is ready for your next prompt |
| Completed | Green | The task finished successfully |
| Failed | Red | The task ended with an error |
| Stopped | Grey | The session was stopped with `Ctrl+X` or `claude stop` |
Separately, the icon's shape shows whether the underlying process is running:
| Shape | What it means |
| :- | :- |
| `✻` or animated `✽` | The session process is alive and replies immediately |
| `∙` | The process has exited. You can still peek, reply, or attach, and Claude restarts from where it left off |
| `✢` | A [`/loop`](/en/scheduled-tasks) session sleeping between iterations. The row shows its run count and a countdown |
Background sessions don't need any terminal open to keep working. A separate [supervisor process](#the-supervisor-process) runs them, so you can close agent view, close your shell, or start a new interactive session and your dispatched work keeps going.
Session state persists on disk through auto-updates and supervisor restarts. If your machine sleeps or shuts down, running sessions stop; restart them with `claude respawn --all`.
The icon's shape tells you whether the underlying process is still running. A `✻`, or an animated `✽` while Claude is working, means the session is alive and you can reply to it immediately. A `∙` means the process has exited, but you can still peek, reply, or attach: Claude restarts the session from where it left off. A `✢` is a [`/loop`](/en/commands) session sleeping between iterations, with the row showing its run count and a countdown to the next iteration.
### Row summaries
Background sessions don't need any terminal open to keep working. A separate [supervisor process](#how-background-sessions-are-hosted) runs them, so you can close agent view, close your shell, or start a new interactive session and your dispatched work keeps going.
The one-line summary in each row is generated by a [Haiku-class model](/en/model-config) so the row can tell you what the session is doing, what it needs, or what it produced without opening the transcript. While a session is actively working, the summary refreshes at most once every 15 seconds, plus once when each turn ends.
Sessions persist on disk: closing your terminal or an auto-update doesn't lose them, and reopening `claude agents` shows them all. If your machine sleeps or shuts down, running sessions stop; restart them with `claude respawn --all`.
Each refresh is one short Haiku-class request through your normal provider, billed and handled under the same [data usage terms](/en/data-usage) as the session itself.
The one-line summary in each row is generated by your configured [Haiku-class model](/en/model-config) so the row can tell you what the session is doing, what it needs, or what it produced without opening the transcript. While a session is actively working, the summary refreshes at most once every 15 seconds, plus once when each turn ends. Each refresh is one short Haiku-class request through your normal provider, billed and handled under the same [data usage terms](/en/data-usage) as the session itself.
### Pull request status
When a session opens a pull request, a status dot appears at the right edge of the row, linked to the pull request in terminals that support hyperlinks. When the session has opened more than one pull request, the count appears before the dot and the color reflects whichever one most needs attention.
@@ -111,7 +131,7 @@ Use `↑` and `↓` to peek at adjacent sessions without closing the panel, or `
### Attach to a session
Press `Enter` or `→` on a selected row to attach, or press `Alt+1` through `Alt+9` to attach directly to the Nth session in the focused group. Agent view is replaced by the full interactive session, exactly as if you had run `claude` in that directory. When you attach, Claude posts a short recap of what happened while you were away.
Press `Enter` or `→` on a selected row to attach. Agent view is replaced by the full interactive session, exactly as if you had run `claude` in that directory. When you attach, Claude posts a short recap of what happened while you were away.
While attached, the session behaves like any other Claude Code session: every [command](/en/commands), keyboard shortcut, and feature works.
@@ -123,23 +143,34 @@ After you've dispatched or backgrounded a session, pressing `←` on an empty pr
### Organize the list
Agent view groups sessions by state, with sessions that need input above sessions that are working or done. Press `Ctrl+S` to switch to grouping by directory instead. Your choice is saved across runs. Within a group, pin a session to the top with `Ctrl+T`, reorder with `Shift+↑` and `Shift+↓`, or press `Enter` on a group header to collapse it. To remove a session, press `Ctrl+X` to stop it and `Ctrl+X` again within two seconds to delete it. Pressing `Ctrl+X` on a group header deletes every session in that group after confirmation.
Agent view groups sessions so the ones that need input are at the top, with `Ready for review` and `Needs input` above `Working` and `Completed`. These group names don't map one-to-one to the [states](#read-session-state) above: a session moves to `Ready for review` when it has an open pull request, and `Completed` collects finished, failed, and stopped sessions together. Press `Ctrl+S` to group by directory instead. Your choice persists across runs.
Older completed sessions fold into a "… N more" row to keep the list short. Failures and sessions with an open pull request always stay visible.
Within a group:
### Filter the list
- Press `Ctrl+T` to pin a session to the top
- Press `Shift+↑` or `Shift+↓` to reorder sessions
- Press `Ctrl+R` to rename a session
- Press `Enter` on a group header to collapse it
To remove a session from the list, press `Ctrl+X` to stop it and `Ctrl+X` again within two seconds to delete it. Pressing `Ctrl+X` on a group header deletes every session in that group after confirmation.
Deleting removes the session from agent view and cleans up its [worktree](#how-file-edits-are-isolated), including any uncommitted changes in it, so push or commit work you want to keep before deleting. The conversation transcript stays on disk and remains available through `claude --resume`.
Older completed sessions fold into a `… N more` row to keep the list short. Failures and sessions with an open pull request always stay visible.
### Filter sessions
Type in the dispatch input to filter instead of dispatching:
| Filter | Shows |
| :- | :- |
| `a:<name>` | Sessions running the named agent |
| `s:<state>` | Sessions in the given state, such as `s:blocked` for sessions that need you |
| `s:<state>` | Sessions in the given state, such as `s:working`. Also accepts `s:blocked` for everything waiting on you |
| `#<number>` or a PR URL | The session working on that pull request |
### Keyboard shortcuts
Press `?` in agent view to see every shortcut. The most common ones:
Press `?` in agent view to see every shortcut in context. The table below summarizes them.
| Shortcut | Action |
| :- | :- |
@@ -148,8 +179,8 @@ Press `?` in agent view to see every shortcut. The most common ones:
| `Space` | Open or close the peek panel for the selected session |
| `Shift+Enter` | Dispatch and attach immediately |
| `→` | Attach to the selected session |
| `Alt+1`..`Alt+9` | Attach to the Nth session in the focused group |
| `Tab` | Browse all subagents, or apply the highlighted suggestion |
| `Alt+1`..`Alt+9` | Attach to session 1–9 in the current group |
| `Tab` | On an empty input, browse all subagents. Otherwise apply the highlighted suggestion |
| `Ctrl+S` | Switch grouping between state and directory |
| `Ctrl+T` | Pin or unpin the selected session |
| `Ctrl+R` | Rename the selected session |
@@ -166,7 +197,9 @@ You can dispatch new background sessions from agent view, send an existing inter
### From agent view
Type a prompt in the input at the bottom of agent view and press `Enter` to start a new background session. The session is named automatically from the prompt. You can rename it later with `Ctrl+R`. Paste an image into the prompt to include a screenshot or diagram with the task.
Type a prompt in the input at the bottom of agent view and press `Enter` to start a new background session. The session is named automatically from the prompt; rename it later with `Ctrl+R`.
Paste an image into the prompt to include a screenshot or diagram with the task.
Prefix or mention parts of the prompt to control how the session starts:
@@ -179,9 +212,9 @@ Prefix or mention parts of the prompt to control how the session starts:
| `#<number>` or a pull request URL | If a session is already working on that PR, select it instead of dispatching |
| `Shift+Enter` | Dispatch and immediately attach to the new session |
Type `/` to dispatch a [skill](/en/skills). Packaging a recurring task as a skill lets you start the same workflow many times from agent view without retyping the prompt. Press `Tab` on an empty input to browse every dispatchable subagent, or to apply the highlighted suggestion when suggestions are showing.
Packaging a recurring task as a [skill](/en/skills) lets you start the same workflow from agent view repeatedly without retyping the prompt.
When the same `@name` matches both a subagent and a sibling repository, the subagent takes precedence. The first-word form without `@` also applies to any subagent name, so a prompt that begins with a word matching one of your subagent names dispatches that subagent. Use the `@` form when you want to be explicit.
When the same `@name` matches both a subagent and a sibling repository, the subagent takes precedence. The bare first-word match also applies, so a prompt that happens to begin with one of your subagent names dispatches that subagent rather than treating the word as plain text. Use the `@` form when you want to be explicit, or start the prompt with a different word to avoid the match.
#### Dispatch to a specific directory
@@ -195,9 +228,11 @@ When agent view is grouped by directory, the highlighted row's directory becomes
### From inside a session
Run `/background` or its alias `/bg` to detach the current conversation and keep it running. Pass a prompt such as `/bg run the test suite and fix any failures` to send one more instruction before detaching.
Run `/background` or its alias `/bg` to move the current conversation into a background session. Pass a prompt such as `/bg run the test suite and fix any failures` to give one more instruction first.
Backgrounding from an interactive session starts a fresh process that resumes from the saved conversation, so running subagents and background commands do not transfer to it. Claude asks you to confirm before backgrounding when any are running. Once in the background, the session can start new subagents and background commands, and those keep running across later detach and reattach.
### From the shell
### From your shell
Pass `--bg` to start a session that goes straight to the background:
@@ -223,12 +258,24 @@ backgrounded · 7c5dcf5d
### How file edits are isolated
Every background session, whether started from agent view, `/bg`, or `claude --bg`, starts in your working directory but is blocked from writing files there. When the session needs to edit files, Claude moves it into an isolated [git worktree](/en/worktrees) under `.claude/worktrees/` automatically, so parallel sessions can read the same checkout but each writes to its own. The block doesn't apply when the session is already inside a worktree, when the working directory isn't a git repository, or to writes outside the working directory.
Every background session, whether started from agent view, `/bg`, or `claude --bg`, starts in your working directory. Before editing files, Claude moves the session into an isolated [git worktree](/en/worktrees) under `.claude/worktrees/`, so parallel sessions can read the same checkout but each writes to its own. Claude skips this when the session is already under `.claude/worktrees/`, when the working directory isn't a git repository, or for writes outside the working directory.
Outside a git repository, sessions write to the working directory directly and aren't isolated from each other, so avoid dispatching parallel sessions that edit the same files.
The worktree is removed when you delete the session, so merge or push the changes you want to keep before you delete. To find a session's worktree path, peek the session or attach and check its working directory.
To make a subagent always run in its own worktree regardless of how it was started, set [`isolation: worktree`](/en/sub-agents#supported-frontmatter-fields) in its frontmatter.
### Set the model
The model name shown in the agent view header is the dispatch default. New sessions you start from the input use this model, which is the same setting [`/model`](/en/model-config) controls in any session.
Each background session can run on a different model. To override it for one session:
- From the shell, pass `--model` with `claude --bg`.
- Attach to a running session and run `/model` there. The change persists if the session is respawned.
- Dispatch a [subagent](/en/sub-agents) whose frontmatter sets a `model` field.
### Permission mode and settings
A dispatched session reads its [settings](/en/settings) and [permission mode](/en/permissions) from the directory it runs in, the same as if you had started `claude` there. Dispatching from the agent view input doesn't pass a permission mode, so the session uses the `defaultMode` from that directory's settings or the `permissionMode` from the dispatched [subagent's frontmatter](/en/sub-agents#supported-frontmatter-fields).
@@ -237,7 +284,7 @@ To set the mode from the shell, pass `--permission-mode` with `claude --bg`. Usi
## Manage sessions from the shell
Every background session has a short ID you can use from the shell. These commands are useful for scripting or when you don't want to open agent view.
Every background session has a short ID you can use from the shell. The ID is printed when you start a session with `claude --bg`, and each session's ID is its directory name under `~/.claude/jobs/`. These commands are useful for scripting or when you don't want to open agent view.
| Command | Purpose |
| :- | :- |
@@ -247,16 +294,26 @@ Every background session has a short ID you can use from the shell. These comman
| `claude stop <id>` | Stop a session. Also accepts `claude kill` |
| `claude respawn <id>` | Restart a stopped session with its conversation intact |
| `claude respawn --all` | Restart every stopped session |
| `claude rm <id>` | Remove a session from the list |
| `claude rm <id>` | Remove a session from the list. Cleans up its worktree if there are no uncommitted changes |
## How background sessions are hosted
Background sessions are hosted by a per-user supervisor process, separate from your terminal and from agent view. It starts automatically the first time you background a session or open agent view, and you don't manage it directly. The supervisor and its sessions authenticate with the same credentials as your interactive sessions and make no additional network connections beyond the model API.
Every session listed in agent view is considered a background session, whether or not you're currently attached to it. By contrast, a session started by running `claude` directly is tied to that terminal and ends when it closes, unless you [send it to the background](#from-inside-a-session).
### The supervisor process
Each background session is its own Claude Code process, parented to the supervisor rather than to your terminal. A session that's actively working, waiting for your input, or has a terminal attached keeps its process running. Once a session finishes and sits unattached for about an hour, the supervisor stops its process to free resources. The transcript and state stay on disk, and the next time you attach, peek, or reply, the supervisor starts a fresh process from where it left off. When every session has finished and no terminal is connected, the supervisor itself exits and starts again the next time you background a session or open agent view.
Background sessions are hosted by a per-user supervisor process, separate from your terminal and from agent view. The supervisor starts automatically the first time you background a session or open agent view, and you don't manage it directly.
The supervisor and its sessions authenticate with the same credentials as your interactive sessions and make no additional network connections beyond the model API.
Each background session is its own Claude Code process, managed by the supervisor rather than tied to your terminal. A session that's actively working, waiting for your input, or has a terminal attached keeps its process running.
Once a session finishes and sits unattached for about an hour, the supervisor stops its process to free resources. The transcript and state stay on disk, and the next time you attach, peek, or reply, the supervisor starts a fresh process from where it left off. When every session has finished and no terminal is connected, the supervisor itself exits and starts again the next time you need it.
The supervisor watches the installed Claude Code binary on disk and restarts into the new version after the regular [auto-updater](/en/setup#auto-updates) replaces it. This is a local file watch, not a network check. Background sessions are detached processes, so they keep running through the restart and the new supervisor reconnects to them.
### Where state is stored
Session state is stored under your Claude Code config directory. If you set [`CLAUDE_CONFIG_DIR`](/en/env-vars), the supervisor uses that directory instead of `~/.claude` and runs as a separate instance with its own sessions.
| Path | Contents |
@@ -265,17 +322,33 @@ Session state is stored under your Claude Code config directory. If you set [`CL
| `~/.claude/daemon/roster.json` | List of running background sessions, used to reconnect after a restart |
| `~/.claude/jobs/<id>/state.json` | Per-session state shown in agent view |
### Turn off agent view
To turn off background agents and agent view entirely, set the `disableAgentView` [setting](/en/settings) to `true` or set the `CLAUDE_CODE_DISABLE_AGENT_VIEW` environment variable. Administrators can enforce this through [managed settings](/en/permissions#managed-settings).
## Troubleshooting
### `claude agents` lists subagents instead of opening agent view
If `claude agents` prints a count followed by your configured subagents and then exits, agent view is unavailable in your environment. Earlier versions didn't open agent view in every environment, including when connected through Bedrock, Vertex AI, or Foundry. Run `claude update` to install the latest version.
If agent view still does not open after updating, check whether it has been [turned off](#turn-off-agent-view) by a setting or environment variable.
### Agent view opens with no sessions
Agent view is empty until you dispatch your first session. Type a prompt in the input at the bottom and press `Enter`.
### Sessions show as stopped after waking your machine
### Cannot open agents because background tasks are running
If pressing `←` to background the current session shows `Cannot open agents — N background task(s) running`, the session has in-flight work such as a subagent, a workflow, or a background shell command, and the shortcut won't silently abandon it. Run `/tasks` to see what's running, then `/bg` to confirm abandoning them. See [From inside a session](#from-inside-a-session) for what does and doesn't transfer when you background.
### Prompt rejected as too short
The dispatch input expects a task description, not a conversational opener. A prompt shorter than four characters is rejected with a `Too short` hint so a stray keystroke doesn't start a session. Describe what you want the session to do, such as `investigate the flaky checkout test`.
### Sessions show as failed after waking your machine
Background sessions don't survive sleep or shutdown. Attach, peek, or reply to any stopped session and it restarts from where it left off. To restart all of them at once, run `claude respawn --all`.
Background sessions don't survive sleep or shutdown, so sessions that were running show as failed after you wake. Attach, peek, or reply to any of them and the session restarts from where it left off. To restart all of them at once, run `claude respawn --all`.
### A session is slow to respond after attaching
@@ -287,17 +360,16 @@ Worktrees are removed when you delete the session that created them. If a sessio
## Limitations
Agent view is a research preview. Current limitations to be aware of:
Agent view is in research preview with the following limitations:
- **Rate limits apply**: background sessions consume your subscription usage the same as interactive sessions, so running ten agents in parallel uses quota roughly ten times as fast as running one.
- **Sessions are local**: background sessions run on your machine and stop if it sleeps or shuts down.
- **Worktrees are deleted with the session**: merge or push changes before deleting a session that edited files in its own worktree.
## Next steps
## Related resources
Now that you understand agent view, explore these related features:
For other ways to run Claude in parallel, see:
- [Run agents in parallel](/en/agents): compare agent view with subagents, agent teams, and worktrees
- [Subagents](/en/sub-agents): define reusable agent configurations with custom prompts, tools, and isolation
- [Agent teams](/en/agent-teams): coordinate multiple sessions that message each other
- [Claude Code on the web](/en/claude-code-on-the-web): run sessions in a managed cloud environment instead of locally
GitHub Appのインストールと権限の関係が整理され、セッションのアクセス範囲はインストール先ではなく接続アカウントの権限に依存することが明記されました。
@@ -31,8 +31,10 @@ Cloud sessions need access to your GitHub repositories to clone code and push br
| Method | How it works | Best for |
| :- | :- | :- |
| **GitHub App** | Install the Claude GitHub App on specific repositories during [web onboarding](/en/web-quickstart). Access is scoped per repository. | Teams that want explicit per-repo authorization |
| **`/web-setup`** | Run `/web-setup` in your terminal to sync your local `gh` CLI token to your Claude account. Access matches whatever your `gh` token can see. | Individual developers who already use `gh` |
| **GitHub App** | Authorize the Claude GitHub App during [web onboarding](/en/web-quickstart). | Browser onboarding; teams that want [Auto-fix](#auto-fix-pull-requests) |
| **`/web-setup`** | Run `/web-setup` in your terminal to sync your local `gh` CLI token to your Claude account. | Individual developers who already use `gh` |
With either method, a cloud session can access any repository the connecting GitHub account can see, not just the repositories the Claude GitHub App is installed on. App installation enables PR webhooks for [Auto-fix](#auto-fix-pull-requests); it is not a session-level access control. To restrict which repositories your team can reach from cloud sessions, restrict access on GitHub itself, for example by limiting team or repository membership for the connected GitHub accounts.
Either method works. [`/schedule`](/en/routines) checks for either form of access and prompts you to run `/web-setup` if neither is configured. See [Connect from your terminal](/en/web-quickstart#connect-from-your-terminal) for the `/web-setup` walkthrough.
@@ -713,7 +715,7 @@ If a new session fails to start with `Session creation failed` or stalls at prov
- Check [status.claude.com](https://status.claude.com) for cloud session incidents
- Retry after a minute, as capacity is provisioned on demand
- Confirm your repository is reachable. Private repositories require either the GitHub App installed with access to that repository, or a `gh` token synced via `/web-setup`. See [GitHub authentication options](#github-authentication-options).
- Confirm your repository is reachable. The connecting GitHub account must have access to the repository on GitHub, either through the Claude GitHub App authorization or a `gh` token synced via `/web-setup` — installing the App on the repository is not required. See [GitHub authentication options](#github-authentication-options).
### Remote Control session expired or access denied
@@ -60,7 +60,7 @@ Not every command appears for every user. Availability depends on your platform,
| `/diff` | Open an interactive diff viewer showing uncommitted changes and per-turn diffs. Use left/right arrows to switch between the current git diff and individual Claude turns, and up/down to browse files |
| `/doctor` | Diagnose and verify your Claude Code installation and settings. Results show with status icons. Press `f` to have Claude fix any reported issues |
| `/effort [level\|auto]` | Set the model [effort level](/en/model-config#adjust-effort-level). Accepts `low`, `medium`, `high`, `xhigh`, or `max`; available levels depend on the model and `max` is session-only. `auto` resets to the model default. Without an argument, opens an interactive slider; use left and right arrows to pick a level and `Enter` to apply. Takes effect immediately without waiting for the current response to finish |
| `/exit` | Exit the CLI. Alias: `/quit` |
| `/exit` | Exit the CLI. In an attached [background session](/en/agent-view#attach-to-a-session), this detaches and the session keeps running. Alias: `/quit` |
| `/export [filename]` | Export the current conversation as plain text. With a filename, writes directly to that file. Without, opens a dialog to copy to clipboard or save to a file |
| `/extra-usage` | Configure extra usage to keep working when rate limits are hit |
| `/fast [on\|off]` | Toggle [fast mode](/en/fast-mode) on or off |
@@ -337,6 +337,8 @@ Toggle auto-update for individual marketplaces through the UI:
Official Anthropic marketplaces have auto-update enabled by default. Third-party and local development marketplaces have auto-update disabled by default.
Administrators can also set `"autoUpdate": true` on each [`extraKnownMarketplaces`](/en/settings#extraknownmarketplaces) entry in managed settings to enable auto-update for an organization marketplace without requiring each user to toggle it.
To disable all automatic updates entirely for both Claude Code and all plugins, set the `DISABLE_AUTOUPDATER` environment variable. See [Auto updates](/en/setup#auto-updates) for details.
To keep plugin auto-updates enabled while disabling Claude Code auto-updates, set `FORCE_AUTOUPDATE_PLUGINS=1` along with `DISABLE_AUTOUPDATER`:
@@ -130,6 +130,7 @@ Claude Code supports the following environment variables to control its behavior
| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | OAuth refresh token for Claude.ai authentication. When set, `claude auth login` exchanges this token directly instead of opening a browser. Requires `CLAUDE_CODE_OAUTH_SCOPES`. Useful for provisioning authentication in automated environments |
| `CLAUDE_CODE_OAUTH_SCOPES` | Space-separated OAuth scopes the refresh token was issued with, such as `"user:profile user:inference user:sessions:claude_code"`. Required when `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` is set |
| `CLAUDE_CODE_OAUTH_TOKEN` | OAuth access token for Claude.ai authentication. Alternative to `/login` for SDK and automated environments. Takes precedence over keychain-stored credentials. Generate one with [`claude setup-token`](/en/authentication#generate-a-long-lived-token) |
| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | Set to `1` to keep [fast mode](/en/fast-mode) on Claude Opus 4.6. Takes precedence over `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE`, so set this if you need to pin Opus 4.6 regardless of how the default changes |
| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | Timeout in milliseconds for flushing pending OpenTelemetry spans (default: 5000). See [Monitoring](/en/monitoring-usage) |
| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | Interval for refreshing dynamic OpenTelemetry headers in milliseconds (default: 1740000 / 29 minutes). See [Dynamic headers](/en/monitoring-usage#dynamic-headers) |
| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | Timeout in milliseconds for the OpenTelemetry exporter to finish on shutdown (default: 2000). Increase if metrics are dropped at exit. See [Monitoring](/en/monitoring-usage) |
@@ -144,6 +145,7 @@ Claude Code supports the following environment variables to control its behavior
| `CLAUDE_CODE_REMOTE` | Set automatically to `true` when Claude Code is running as a [cloud session](/en/claude-code-on-the-web). Read this from a hook or setup script to detect whether you are in a cloud environment |
| `CLAUDE_CODE_REMOTE_SESSION_ID` | Set automatically in [cloud sessions](/en/claude-code-on-the-web) to the current session's ID. Read this to construct a link back to the session transcript. See [Link artifacts back to the session](/en/claude-code-on-the-web#link-artifacts-back-to-the-session) |
| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | Set to `1` to automatically resume if the previous session ended mid-turn. Used in SDK mode so the model continues without requiring the SDK to re-send the prompt |
| `CLAUDE_CODE_RESUME_PROMPT` | Override the continuation message injected when resuming a session that ended mid-turn. Defaults to `Continue from where you left off.`. Spawn scripts for long-running agents can set this to a more directive boot message. An empty string uses the default |
| `CLAUDE_CODE_SCRIPT_CAPS` | JSON object limiting how many times specific scripts may be invoked per session when `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` is set. Keys are substrings matched against the command text; values are integer call limits. For example, `{"deploy.sh": 2}` allows `deploy.sh` to be called at most twice. Matching is substring-based so shell-expansion tricks like `./scripts/deploy.sh $(evil)` still count against the cap. Runtime fan-out via `xargs` or `find -exec` is not detected; this is a defense-in-depth control |
| `CLAUDE_CODE_SCROLL_SPEED` | Set the mouse wheel scroll multiplier in [fullscreen rendering](/en/fullscreen#mouse-wheel-scrolling). Accepts values from 1 to 20. Set to `3` to match `vim` if your terminal sends one wheel event per notch without amplification. Ignored in the JetBrains IDE terminal, where Claude Code uses its own scroll handling |
| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | Override the time budget in milliseconds for [SessionEnd](/en/hooks#sessionend) hooks. Applies to session exit, `/clear`, and switching sessions via interactive `/resume`. By default the budget is 1.5 seconds, automatically raised to the highest per-hook `timeout` configured in settings files, up to 60 seconds. Timeouts on plugin-provided hooks do not raise the budget |
@@ -199,7 +201,7 @@ Claude Code supports the following environment variables to control its behavior
| `DISABLE_PROMPT_CACHING_HAIKU` | Set to `1` to disable prompt caching for Haiku models |
| `DISABLE_PROMPT_CACHING_OPUS` | Set to `1` to disable prompt caching for Opus models |
| `DISABLE_PROMPT_CACHING_SONNET` | Set to `1` to disable prompt caching for Sonnet models |
| `DISABLE_TELEMETRY` | Set to `1` to opt out of telemetry. Telemetry events do not include user data like code, file paths, or bash commands |
| `DISABLE_TELEMETRY` | Set to `1` to opt out of telemetry. Telemetry events do not include user data like code, file paths, or bash commands. Also disables feature flags, so some features that are still rolling out may not be available |
| `DISABLE_UPDATES` | Set to `1` to block all updates including manual `claude update` and `claude install`. Stricter than `DISABLE_AUTOUPDATER`. Use when distributing Claude Code through your own channels and users should not self-update |
| `DISABLE_UPGRADE_COMMAND` | Set to `1` to hide the `/upgrade` command |
| `DO_NOT_TRACK` | Set to `1` to opt out of telemetry. Equivalent to setting `DISABLE_TELEMETRY`. Honored as the [standard cross-tool convention](https://consoledonottrack.com/) |
@@ -73,6 +73,8 @@ Or in any Claude Code [settings file](/en/settings#settings-files), including us
Fast mode for Opus 4.6 remains available alongside Opus 4.7. The two share the same fast mode rate limit pool: usage on either model draws from the same limits.
To pin fast mode to Opus 4.6 explicitly, set `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1`. This variable takes precedence, so fast mode runs on Opus 4.6 regardless of whether `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE` is set.
## Understand the cost tradeoff
Fast mode has higher per-token pricing than standard Opus:
@@ -123,7 +123,7 @@ Evaluation tokens are billed on the small fast model configured for your provide
## Requirements
`/goal` runs only in workspaces where you have accepted the trust dialog, because the evaluator is part of the hooks system. If [`disableAllHooks`](/en/hooks#disable-or-remove-hooks) is set in managed policy settings, `/goal` is unavailable. In both cases, the command tells you why instead of silently doing nothing.
`/goal` runs only in workspaces where you have accepted the trust dialog, because the evaluator is part of the hooks system. `/goal` is also unavailable when [`disableAllHooks`](/en/hooks#disable-or-remove-hooks) is set at any settings level or when [`allowManagedHooksOnly`](/en/settings#hook-configuration) is set in managed settings. In each case, the command tells you why instead of silently doing nothing.
## See also
@@ -277,7 +277,7 @@ The following configuration types are loaded from `--add-dir` directories:
| Plugin settings in `.claude/settings.json` | `enabledPlugins` and `extraKnownMarketplaces` only |
| [CLAUDE.md](/en/memory) files, `.claude/rules/`, and `CLAUDE.local.md` | Only when `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1` is set. `CLAUDE.local.md` additionally requires the `local` setting source, which is enabled by default |
Everything else, including subagents, commands, output styles, hooks, and other settings, is discovered only from the current working directory and its parents, your user directory at `~/.claude/`, and managed settings. To share that configuration across projects, use one of these approaches:
Subagents, commands, and output styles are discovered from the current working directory and its parents, your user directory at `~/.claude/`, and managed settings. Hooks and other `settings.json` keys load from the current working directory's `.claude/` folder with no parent-directory fallback, alongside your user `~/.claude/settings.json` and managed settings. To share that configuration across projects, use one of these approaches:
- **User-level configuration**: place files in `~/.claude/agents/`, `~/.claude/output-styles/`, or `~/.claude/settings.json` to make them available in every project
- **Plugins**: package and distribute configuration as a [plugin](/en/plugins) that teams can install
@@ -338,6 +338,8 @@ Permission rules follow the same [settings precedence](/en/settings#settings-pre
If a tool is denied at any level, no other level can allow it. For example, a managed settings deny cannot be overridden by `--allowedTools`, and `--disallowedTools` can add restrictions beyond what managed settings define.
Embedding hosts can supply additional managed policy via the SDK `managedSettings` option when [`parentSettingsBehavior`](/en/settings#settings-precedence) is set to `"merge"`; embedder values can tighten policy but not loosen it.
If a permission is allowed in user settings but denied in project settings, the project setting takes precedence and the permission is blocked.
## Example configurations
@@ -511,6 +511,8 @@ Whether a custom path replaces or extends the plugin's default directory depends
- **Adds to the default**: `skills`. The default `skills/` directory is always scanned, and directories listed in `skills` are loaded alongside it
- **Own merge rules**: [hooks](#hooks), [MCP servers](#mcp-servers), and [LSP servers](#lsp-servers). See each section for how multiple sources combine
When a plugin has both a default folder and the matching manifest key, Claude Code v2.1.140 and later flags the ignored folder in `/doctor`, `claude plugin list`, and the `/plugin` detail view. The plugin still loads using the manifest paths. No warning is shown when the manifest key points into the default folder, for example `"commands": ["./commands/deploy.md"]`, because the folder is addressed explicitly in that case.
For all path fields:
- All paths must be relative to the plugin root and start with `./`
@@ -771,7 +773,7 @@ claude plugin uninstall <plugin> [options]
| `-s, --scope <scope>` | Uninstall from scope: `user`, `project`, or `local` | `user` |
| `--keep-data` | Preserve the plugin's [persistent data directory](#persistent-data-directory) | |
| `--prune` | Also remove auto-installed dependencies that no other plugin requires. See [plugin prune](#plugin-prune) | |
| `-y, --yes` | Skip the `--prune` confirmation prompt. Required when stdin is not a TTY | |
| `-y, --yes` | Skip the `--prune` confirmation prompt. Required when stdin or stdout is not a TTY | |
| `-h, --help` | Display help for command | |
**Aliases:** `remove`, `rm`
@@ -792,7 +794,7 @@ claude plugin prune [options]
| :- | :- | :- |
| `-s, --scope <scope>` | Prune at scope: `user`, `project`, or `local` | `user` |
| `--dry-run` | List what would be removed without removing anything | |
| `-y, --yes` | Skip the confirmation prompt. Required when stdin is not a TTY | |
| `-y, --yes` | Skip the confirmation prompt. Required when stdin or stdout is not a TTY | |
| `-h, --help` | Display help for command | |
**Aliases:** `autoremove`
@@ -264,7 +264,7 @@ Configure how `--worktree` creates and manages git worktrees.
| :- | :- | :- |
| `worktree.baseRef` | Which ref new worktrees branch from. `"fresh"` (default) branches from `origin/<default-branch>` for a clean tree matching the remote. `"head"` branches from your current local `HEAD`, so unpushed commits and feature-branch state are present in the worktree. Applies to `--worktree`, the `EnterWorktree` tool, and subagent isolation | `"head"` |
| `worktree.symlinkDirectories` | Directories to symlink from the main repository into each worktree to avoid duplicating large directories on disk. No directories are symlinked by default | `["node_modules", ".cache"]` |
| `worktree.sparsePaths` | Directories to check out in each worktree via git sparse-checkout (cone mode). Only the listed paths are written to disk, which is faster in large monorepos | `["packages/my-app", "shared/utils"]` |
| `worktree.sparsePaths` | Directories to check out in each worktree via git sparse-checkout. Only the listed directories plus root-level files are written to disk, which is faster in large monorepos | `["packages/my-app", "shared/utils"]` |
To copy gitignored files like `.env` into new worktrees, use a [`.worktreeinclude` file](/en/worktrees#copy-gitignored-files-into-worktrees) in your project root instead of a setting.
@@ -504,6 +504,7 @@ Settings apply in order of precedence. From highest to lowest:
- Policies deployed by IT through server delivery, MDM configuration profiles, registry policies, or managed settings files
- Cannot be overridden by any other level, including command line arguments
- Within the managed tier, precedence is: server-managed > MDM/OS-level policies > file-based (`managed-settings.d/*.json` + `managed-settings.json`) > HKCU registry (Windows only). Only one managed source is used; sources do not merge across tiers. Within the file-based tier, drop-in files and the base file are merged together.
- Embedding hosts such as Claude Desktop can supply policy via the SDK `managedSettings` option. By default this is ignored when any managed-settings tier is present. Administrators can opt in by setting [`parentSettingsBehavior`](#available-settings) to `"merge"`. The embedder's values are filtered so they can tighten managed policy but not loosen it.
2. **Command line arguments**
- Temporary overrides for a specific session. JSON passed via `--settings <file-or-json>` merges with file-based settings using the same rules as the other layers: a key set here overrides the same key in local, project, or user settings, and omitting a key leaves the lower-layer value in place
@@ -662,6 +663,8 @@ Defines additional marketplaces that should be made available for the repository
- `hostPattern`: regex pattern to match marketplace hosts (uses `hostPattern`)
- `settings`: inline marketplace declared directly in settings.json without a separate hosted repository (uses `name` and `plugins`)
Each marketplace entry also accepts an optional `autoUpdate` Boolean. Set `"autoUpdate": true` alongside `source` to make Claude Code refresh that marketplace and update its installed plugins at startup. When omitted, official Anthropic marketplaces default to `true` and all other marketplaces default to `false`. See [Configure auto-updates](/en/discover-plugins#configure-auto-updates).
Use `source: 'settings'` to declare a small set of plugins inline without setting up a hosted marketplace repository. Plugins listed here must reference external sources such as GitHub or npm. You still need to enable each plugin separately in `enabledPlugins`.
```json
@@ -88,9 +88,9 @@ When skills share the same name across levels, enterprise overrides personal, an
Claude Code watches skill directories for file changes. Adding, editing, or removing a skill under `~/.claude/skills/`, the project `.claude/skills/`, or a `.claude/skills/` inside an `--add-dir` directory takes effect within the current session without restarting. Creating a top-level skills directory that did not exist when the session started requires restarting Claude Code so the new directory can be watched.
#### Automatic discovery from nested directories
#### Automatic discovery from parent and nested directories
When you work with files in subdirectories, Claude Code automatically discovers skills from nested `.claude/skills/` directories. For example, if you're editing a file in `packages/frontend/`, Claude Code also looks for skills in `packages/frontend/.claude/skills/`. This supports monorepo setups where packages have their own skills.
Project skills load from `.claude/skills/` in your starting directory and in every parent directory up to the repository root, so starting Claude in a subdirectory still picks up skills defined at the root. When you work with files in subdirectories below your starting directory, Claude Code also discovers skills from nested `.claude/skills/` directories on demand. For example, if you're editing a file in `packages/frontend/`, Claude Code also looks for skills in `packages/frontend/.claude/skills/`. This supports monorepo setups where packages have their own skills.
Each skill is a directory with `SKILL.md` as the entrypoint:
@@ -139,7 +139,7 @@ The session stays live after the PR is created. Paste CI failure output or revie
### No repositories appear after connecting GitHub
The Claude GitHub App needs explicit access to each repository you want to use. On github.com, open **Settings → Applications → Claude → Configure** and verify your repo is listed under **Repository access**. Private repositories need the same authorization as public ones.
A cloud session can use any repository the connected GitHub account can see, regardless of which repositories the Claude GitHub App is installed on. If a repository is missing, verify the connected GitHub account has access to it on GitHub. If you also want [Auto-fix](/en/claude-code-on-the-web#auto-fix-pull-requests) for a repository, install the App on it: on github.com, open **Settings → Applications → Claude → Configure** and verify the repository is listed under **Repository access**. Private repositories need the same authorization as public ones.
### The page only shows a GitHub login button
@@ -83,8 +83,8 @@ Subagents can run in their own worktrees so parallel edits don't conflict. Ask C
When you exit a worktree session, cleanup depends on whether you made changes:
- **No changes**: the worktree and its branch are removed automatically
- **Changes or commits exist**: Claude prompts you to keep or remove the worktree. Keeping preserves the directory and branch so you can return later. Removing deletes the worktree directory and its branch, discarding all uncommitted changes and commits
- **No uncommitted changes, no untracked files, and no new commits**: the worktree and its branch are removed automatically. If the session has a [name](/en/sessions#name-your-sessions), Claude prompts instead so you can keep the worktree for later
- **Uncommitted changes, untracked files, or new commits exist**: Claude prompts you to keep or remove the worktree. Keeping preserves the directory and branch so you can return later. Removing deletes the worktree directory and its branch, discarding any uncommitted changes, untracked files, and commits
- **Non-interactive runs**: worktrees created with `--worktree` alongside `-p` are not cleaned up automatically since there is no exit prompt. Remove them with `git worktree remove`
Subagent worktrees orphaned by a crash or interrupted run are removed at startup once they are older than your [`cleanupPeriodDays`](/en/settings#available-settings) setting, provided they have no uncommitted changes, no untracked files, and no unpushed commits. Worktrees you create with `--worktree` are never removed by this sweep.