Documentation 2026-06-15 23:02 UTC to 2026-06-16 21:57 UTC

35If any of these sets an advisor model, the advisor is enabled for sessions whose main model [supports it](#choose-an-advisor-model). To stop using it, see [Turn the advisor off](#turn-the-advisor-off).35If any of these sets an advisor model, the advisor is enabled for sessions whose main model [supports it](#choose-an-advisor-model). To stop using it, see [Turn the advisor off](#turn-the-advisor-off).

36 36 

37<Note>37<Note>

38 To use Fable 5 as the advisor, you need Claude Code v2.1.170 or later and [Fable 5 access](/en/model-config#work-with-fable-5) for your organization. Fable does not appear in the picker that `/advisor` opens, so pass it directly as `/advisor fable`, `--advisor fable`, or `"advisorModel": "fable"`.38 To use Fable 5 as the advisor, you need Claude Code v2.1.170 or later and [Fable 5 access](/en/model-config#work-with-fable-5) for your organization.

39</Note>39</Note>

40 40 

41### Use the `/advisor` command41### Use the `/advisor` command

79| Opus 4.6 or later | Fable, Opus at or above the main model's version | An Opus 4.7 main with an Opus 4.6 advisor is rejected |79| Opus 4.6 or later | Fable, Opus at or above the main model's version | An Opus 4.7 main with an Opus 4.6 advisor is rejected |

80| Fable 5 ({/* min-version: 2.1.170 */}v2.1.170+) | Fable | An Opus or Sonnet advisor is rejected |80| Fable 5 ({/* min-version: 2.1.170 */}v2.1.170+) | Fable | An Opus or Sonnet advisor is rejected |

81 81 

82Fable 5 requires Claude Code v2.1.170 or later and Fable 5 access, whether it acts as the main model or the advisor. The `fable` option does not appear in the `/advisor` picker.82Fable 5 requires Claude Code v2.1.170 or later and Fable 5 access, whether it acts as the main model or the advisor.

83 83 

84Set the advisor as `opus`, `sonnet`, or `fable`. These aliases resolve to the latest version of each model. You can also pass a full model ID such as `claude-opus-4-8`.84Set the advisor as `opus`, `sonnet`, or `fable`. These aliases resolve to the latest version of each model. You can also pass a full model ID such as `claude-opus-4-8`.

85 85 

86The API enforces the pairing, not Claude Code. Setting a rejected pairing succeeds, then surfaces as a `cannot be used as an advisor when the request model is` error on the next request.86Subagents inherit the configured advisor and apply the same pairing check against their own model.

87 

88Claude Code validates the pairing before sending a request:

89 

90* If the advisor is less capable than the main model, the advisor is not attached to the main model's requests. The `/advisor` command output and a notification show this. Subagents whose own model satisfies the pairing may still use the advisor.

91* If the main model or the advisor is a model Claude Code does not recognize, the advisor is not attached.

87 92 

88### Common model pairings93### Common model pairings

89 94 

47 47 

48As the loop runs, the SDK yields a stream of messages. Each message carries a type that tells you what stage of the loop it came from. The five core types are:48As the loop runs, the SDK yields a stream of messages. Each message carries a type that tells you what stage of the loop it came from. The five core types are:

49 49 

50* **`SystemMessage`:** session lifecycle events. The `subtype` field distinguishes them: `"init"` is the first message (session metadata), and `"compact_boundary"` fires after [compaction](#automatic-compaction). In TypeScript, the compact boundary is its own [`SDKCompactBoundaryMessage`](/en/agent-sdk/typescript#sdkcompactboundarymessage) type rather than a subtype of `SDKSystemMessage`.50* **`SystemMessage`:** session lifecycle events. The `subtype` field distinguishes them:

51 

52 * `"init"`: the first message with session metadata

53 * `"compact_boundary"`: fires after [compaction](#automatic-compaction)

54 * `"informational"`: plain-text status banners from the loop

55 * `"worker_shutting_down"`: the loop will end after the current turn because the host is exiting or Remote Control disconnected

56 

57 In TypeScript, each subtype other than `"init"` is its own type in the [`SDKMessage` union](/en/agent-sdk/typescript#sdkmessage) rather than a subtype of `SDKSystemMessage`.

51* **`AssistantMessage`:** emitted after each Claude response, including the final text-only one. Contains text content blocks and tool call blocks from that turn.58* **`AssistantMessage`:** emitted after each Claude response, including the final text-only one. Contains text content blocks and tool call blocks from that turn.

52* **`UserMessage`:** emitted after each tool execution with the tool result content sent back to Claude. Also emitted for any user inputs you stream mid-loop.59* **`UserMessage`:** emitted after each tool execution with the tool result content sent back to Claude. Also emitted for any user inputs you stream mid-loop.

53* **`StreamEvent`:** only emitted when partial messages are enabled. Contains raw API streaming events (text deltas, tool input chunks). See [Stream responses](/en/agent-sdk/streaming-output).60* **`StreamEvent`:** only emitted when partial messages are enabled. Contains raw API streaming events (text deltas, tool input chunks). See [Stream responses](/en/agent-sdk/streaming-output).

1044```1044```

1045 1045 

1046| Field | Required | Description |1046| Field | Required | Description |

1047| :---------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |1047| :---------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1048| `description` | Yes | Natural language description of when to use this agent |1048| `description` | Yes | Natural language description of when to use this agent |

1049| `prompt` | Yes | The agent's system prompt |1049| `prompt` | Yes | The agent's system prompt |

1050| `tools` | No | Array of allowed tool names. If omitted, inherits all tools |1050| `tools` | No | Array of allowed tool names. If omitted, inherits all tools |

1051| `disallowedTools` | No | Array of tool names to remove from the agent's tool set |1051| `disallowedTools` | No | Array of tool names to remove from the agent's tool set. MCP server-level patterns are also accepted: `mcp__server` or `mcp__server__*` removes every tool from that server, and `mcp__*` removes every MCP tool from any server |

1052| `model` | No | Model override for this agent. Accepts an alias such as `"sonnet"`, `"opus"`, `"haiku"`, or `"inherit"`, or a full model ID. If omitted, uses the main model |1052| `model` | No | Model override for this agent. Accepts an alias such as `"sonnet"`, `"opus"`, `"haiku"`, or `"inherit"`, or a full model ID. If omitted, uses the main model |

1053| `skills` | No | List of skill names to preload into the agent's context at startup. Unlisted skills remain invocable through the Skill tool |1053| `skills` | No | List of skill names to preload into the agent's context at startup. Unlisted skills remain invocable through the Skill tool |

1054| `memory` | No | Memory source for this agent: `"user"`, `"project"`, or `"local"` |1054| `memory` | No | Memory source for this agent: `"user"`, `"project"`, or `"local"` |

346 346 

347## Error handling347## Error handling

348 348 

349Structured output generation can fail when the agent cannot produce valid JSON matching your schema. This typically happens when the schema is too complex for the task, the task itself is ambiguous, or the agent hits its retry limit trying to fix validation errors. It can also happen without any validation failure: a [model fallback](/en/model-config#automatic-model-fallback) can retract an already-completed output mid-stream, and if no retry replaces it the run ends with the same error. Check the result's `errors` text to tell the two causes apart before debugging your schema.349Structured output generation can fail when the agent cannot produce valid JSON matching your schema. This typically happens when the schema is too complex for the task, the task itself is ambiguous, or the agent hits its retry limit trying to fix validation errors. It can also happen without any validation failure: a [model fallback](/en/model-config#automatic-model-fallback) can retract an already-completed output mid-stream, and if no retry replaces it the run ends with the same error. Check the `errors` field on the result message to tell the two causes apart before debugging your schema.

350 350 

351When an error occurs, the result message has a `subtype` indicating what went wrong:351When an error occurs, the result message has a `subtype` indicating what went wrong:

352 352 

353| Subtype | Meaning |353| Subtype | Meaning |

354| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |354| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |

355| `success` | Output was generated and validated successfully |355| `success` | Output was generated and validated successfully |

356| `error_max_structured_output_retries` | No valid output survived after multiple attempts (validation failures, or a model-fallback retraction with no successful retry) |356| `error_max_structured_output_retries` | No valid output remained after multiple attempts (validation failures, or a model-fallback retraction with no successful retry) |

357 357 

358The example below checks the `subtype` field to determine whether the output was generated successfully or if you need to handle a failure:358The example below checks the `subtype` field to determine whether the output was generated successfully or if you need to handle a failure:

359 359 

160### AgentDefinition configuration160### AgentDefinition configuration

161 161 

162| Field | Type | Required | Description |162| Field | Type | Required | Description |

163| :---------------- | :---------------------------------------------------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |163| :---------------- | :---------------------------------------------------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

164| `description` | `string` | Yes | Natural language description of when to use this agent |164| `description` | `string` | Yes | Natural language description of when to use this agent |

165| `prompt` | `string` | Yes | The agent's system prompt defining its role and behavior |165| `prompt` | `string` | Yes | The agent's system prompt defining its role and behavior |

166| `tools` | `string[]` | No | Array of allowed tool names. If omitted, inherits all tools |166| `tools` | `string[]` | No | Array of allowed tool names. If omitted, inherits all tools |

167| `disallowedTools` | `string[]` | No | Array of tool names to remove from the agent's tool set |167| `disallowedTools` | `string[]` | No | Array of tool names to remove from the agent's tool set. MCP server-level patterns are also accepted: `mcp__server` or `mcp__server__*` removes every tool from that server, and `mcp__*` removes every MCP tool from any server |

168| `model` | `string` | No | Model override for this agent. Accepts an alias such as `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'`, or a full model ID. Defaults to main model if omitted |168| `model` | `string` | No | Model override for this agent. Accepts an alias such as `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'`, or a full model ID. Defaults to main model if omitted |

169| `skills` | `string[]` | No | List of skill names to preload into the agent's context at startup. Unlisted skills remain invocable through the Skill tool |169| `skills` | `string[]` | No | List of skill names to preload into the agent's context at startup. Unlisted skills remain invocable through the Skill tool |

170| `memory` | `'user' \| 'project' \| 'local'` | No | Memory source for this agent |170| `memory` | `'user' \| 'project' \| 'local'` | No | Memory source for this agent |

205| Item shape: `{ content, status, activeForm }` | `TaskCreate` input: `{ subject, description, activeForm?, metadata? }`. `TaskUpdate` input: `{ taskId, status?, subject?, description?, activeForm?, addBlocks?, addBlockedBy?, owner?, metadata? }`. `status` is `"pending"`, `"in_progress"`, or `"completed"`; set `status: "deleted"` to delete |205| Item shape: `{ content, status, activeForm }` | `TaskCreate` input: `{ subject, description, activeForm?, metadata? }`. `TaskUpdate` input: `{ taskId, status?, subject?, description?, activeForm?, addBlocks?, addBlockedBy?, owner?, metadata? }`. `status` is `"pending"`, `"in_progress"`, or `"completed"`; set `status: "deleted"` to delete |

206| Render `block.input.todos` directly | Accumulate items across calls, or read a snapshot from a `TaskList` tool result |206| Render `block.input.todos` directly | Accumulate items across calls, or read a snapshot from a `TaskList` tool result |

207 207 

208The assigned task ID is not in the `TaskCreate` input. It comes back in the matching `tool_result` as `{ task: { id, subject } }`, so capture it from the result block to key your map. The following example shows the minimal change to the [Monitoring Todo Changes](#monitoring-todo-changes) loop. To render a complete list, watch for a `TaskList` tool result in the stream or accumulate `TaskCreate` results and `TaskUpdate` inputs into a map:208The assigned task ID is not in the `TaskCreate` input. It comes back in the matching `tool_result` as `{ task: { id, subject } }`, so capture it from the result block to key your map. The following example shows the minimal change to the [Monitoring Todo Changes](#monitoring-todo-changes) loop. To render a complete list, watch for a `TaskList` tool result in the stream or accumulate `TaskCreate` results and `TaskUpdate` inputs into a map.

209 

210The streamed `tool_use` input is the raw shape the model emitted. Claude Code repairs some close-but-incorrect key names before execution, mapping `id` or `task_id` to `taskId` and `active_form` to `activeForm`, but that repair is not reflected in the stream. Read `TaskUpdate` input fields defensively, as the samples below do, rather than assuming the canonical name is always present.

209 211 

210<CodeGroup>212<CodeGroup>

211 ```typescript TypeScript theme={null}213 ```typescript TypeScript theme={null}

221 const input = block.input as { subject: string };223 const input = block.input as { subject: string };

222 console.log(`+ ${input.subject}`);224 console.log(`+ ${input.subject}`);

223 } else if (block.name === "TaskUpdate") {225 } else if (block.name === "TaskUpdate") {

224 const input = block.input as { taskId: string; status?: string };226 const input = block.input as {

225 if (input.status) console.log(` ${input.taskId} -> ${input.status}`);227 taskId?: string;

228 id?: string;

229 task_id?: string;

230 status?: string;

231 };

232 const taskId = input.taskId ?? input.id ?? input.task_id;

233 if (taskId && input.status) console.log(` ${taskId} -> ${input.status}`);

226 }234 }

227 }235 }

228 }236 }

242 if block.name == "TaskCreate":250 if block.name == "TaskCreate":

243 print(f"+ {block.input['subject']}")251 print(f"+ {block.input['subject']}")

244 elif block.name == "TaskUpdate" and block.input.get("status"):252 elif block.name == "TaskUpdate" and block.input.get("status"):

245 print(f" {block.input['taskId']} -> {block.input['status']}")253 task_id = (

254 block.input.get("taskId")

255 or block.input.get("id")

256 or block.input.get("task_id")

257 )

258 if task_id:

259 print(f" {task_id} -> {block.input['status']}")

246 ```260 ```

247</CodeGroup>261</CodeGroup>

248 262 

631```631```

632 632 

633| Field | Required | Description |633| Field | Required | Description |

634| :------------------------------------ | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |634| :------------------------------------ | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

635| `description` | Yes | Natural language description of when to use this agent |635| `description` | Yes | Natural language description of when to use this agent |

636| `tools` | No | Array of allowed tool names. If omitted, inherits all tools from parent. To preload Skills into the agent's context, use the `skills` field rather than listing `'Skill'` here |636| `tools` | No | Array of allowed tool names. If omitted, inherits all tools from parent. To preload Skills into the agent's context, use the `skills` field rather than listing `'Skill'` here |

637| `disallowedTools` | No | Array of tool names to explicitly disallow for this agent |637| `disallowedTools` | No | Array of tool names to explicitly disallow for this agent. MCP server-level patterns are also accepted: `mcp__server` or `mcp__server__*` removes every tool from that server, and `mcp__*` removes every MCP tool from any server |

638| `prompt` | Yes | The agent's system prompt |638| `prompt` | Yes | The agent's system prompt |

639| `model` | No | Model override for this agent. Accepts an alias such as `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'`, or a full model ID. If omitted or `'inherit'`, uses the main model |639| `model` | No | Model override for this agent. Accepts an alias such as `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'`, or a full model ID. If omitted or `'inherit'`, uses the main model |

640| `mcpServers` | No | MCP server specifications for this agent |640| `mcpServers` | No | MCP server specifications for this agent |

966 | SDKTaskProgressMessage966 | SDKTaskProgressMessage

967 | SDKTaskUpdatedMessage967 | SDKTaskUpdatedMessage

968 | SDKSessionStateChangedMessage968 | SDKSessionStateChangedMessage

969 | SDKWorkerShuttingDownMessage

969 | SDKCommandsChangedMessage970 | SDKCommandsChangedMessage

970 | SDKNotificationMessage971 | SDKNotificationMessage

971 | SDKFilesPersistedEvent972 | SDKFilesPersistedEvent

976 | SDKPermissionDeniedMessage977 | SDKPermissionDeniedMessage

977 | SDKPromptSuggestionMessage978 | SDKPromptSuggestionMessage

978 | SDKAPIRetryMessage979 | SDKAPIRetryMessage

979 | SDKMirrorErrorMessage;980 | SDKMirrorErrorMessage

981 | SDKInformationalMessage;

980```982```

981 983 

982### `SDKAssistantMessage`984### `SDKAssistantMessage`

1164};1166};

1165```1167```

1166 1168 

1169### `SDKInformationalMessage`

1170 

1171Generic text banner emitted by the loop. Carries non-error status lines, hook feedback such as a `UserPromptSubmit` hook's block reason, and command output. Render `content` as plaintext at the given `level`.

1172 

1173```typescript theme={null}

1174type SDKInformationalMessage = {

1175 type: "system";

1176 subtype: "informational";

1177 content: string;

1178 level: "info" | "notice" | "suggestion" | "warning";

1179 tool_use_id?: string;

1180 prevent_continuation?: boolean;

1181 uuid: UUID;

1182 session_id: string;

1183};

1184```

1185 

1186### `SDKWorkerShuttingDownMessage`

1187 

1188Emitted on graceful worker teardown so remote clients can show why the worker went away instead of waiting for heartbeat timeout. The `reason` is a short snake\_case string set by the host CLI, such as `"host_exit"` or `"remote_control_disabled"`. Act on this only when streaming live. A resumed session replays past instances of this message, so ignore them in that case.

1189 

1190```typescript theme={null}

1191type SDKWorkerShuttingDownMessage = {

1192 type: "system";

1193 subtype: "worker_shutting_down";

1194 reason: string;

1195 uuid: UUID;

1196 session_id: string;

1197};

1198```

1199 

1167### `SDKPluginInstallMessage`1200### `SDKPluginInstallMessage`

1168 1201 

1169Plugin installation progress event. Emitted when [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/en/env-vars) is set, so your Agent SDK application can track marketplace plugin installation before the first turn. The `started` and `completed` statuses bracket the overall install. The `installed` and `failed` statuses report individual marketplaces and include `name`.1202Plugin installation progress event. Emitted when [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/en/env-vars) is set, so your Agent SDK application can track marketplace plugin installation before the first turn. The `started` and `completed` statuses bracket the overall install. The `installed` and `failed` statuses report individual marketplaces and include `name`.

1230type SDKMessageOrigin =1263type SDKMessageOrigin =

1231 | { kind: "human" }1264 | { kind: "human" }

1232 | { kind: "channel"; server: string }1265 | { kind: "channel"; server: string }

1233 | { kind: "peer"; from: string; name?: string }1266 | { kind: "peer"; from: string; name?: string; senderTaskId?: string }

1234 | { kind: "task-notification" }1267 | { kind: "task-notification" }

1235 | { kind: "coordinator" }1268 | { kind: "coordinator" }

1236 | { kind: "auto-continuation" };1269 | { kind: "auto-continuation" };

1237```1270```

1238 1271 

1239| `kind` | Meaning |1272| `kind` | Meaning |

1240| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1273| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1241| `human` | Direct input from the end user. On user messages, an absent `origin` also means human input. |1274| `human` | Direct input from the end user. On user messages, an absent `origin` also means human input. |

1242| `channel` | Message arriving on a [channel](/en/channels). `server` is the source MCP server name. |1275| `channel` | Message arriving on a [channel](/en/channels). `server` is the source MCP server name. |

1243| `peer` | Reserved for messages from another agent session. `from` is the sender address and `name` is the sender's display name when available. The Agent SDK does not emit this origin; treat as an unknown origin. |1276| `peer` | Reserved for messages from another agent session. `from` is the sender address and `name` is the sender's display name when available. `senderTaskId` is the task ID of the in-process background subagent that sent the message; absent for cross-session peers. The Agent SDK does not emit this origin; treat as an unknown origin. |

1244| `task-notification` | Synthetic turn injected after a background task finished. See [`SDKTaskNotificationMessage`](#sdktasknotificationmessage). |1277| `task-notification` | Synthetic turn injected after a background task finished. See [`SDKTaskNotificationMessage`](#sdktasknotificationmessage). |

1245| `coordinator` | Message from a team coordinator in an [agent team](/en/agent-teams). |1278| `coordinator` | Message from a team coordinator in an [agent team](/en/agent-teams). |

1246| `auto-continuation` | Synthetic turn injected when the session continues without fresh user input, such as a command result that triggers a follow-up prompt. |1279| `auto-continuation` | Synthetic turn injected when the session continues without fresh user input, such as a command result that triggers a follow-up prompt. |

1533type TeammateIdleHookInput = BaseHookInput & {1566type TeammateIdleHookInput = BaseHookInput & {

1534 hook_event_name: "TeammateIdle";1567 hook_event_name: "TeammateIdle";

1535 teammate_name: string;1568 teammate_name: string;

1569 /** @deprecated since v2.1.178. Carries the session-derived team name; will be removed. */

1536 team_name: string;1570 team_name: string;

1537};1571};

1538```1572```

1546 task_subject: string;1580 task_subject: string;

1547 task_description?: string;1581 task_description?: string;

1548 teammate_name?: string;1582 teammate_name?: string;

1583 /** @deprecated since v2.1.178. Carries the session-derived team name; will be removed. */

1549 team_name?: string;1584 team_name?: string;

1550};1585};

1551```1586```

1738 run_in_background?: boolean;1773 run_in_background?: boolean;

1739 max_turns?: number;1774 max_turns?: number;

1740 name?: string;1775 name?: string;

1741 team_name?: string;

1742 mode?: "acceptEdits" | "bypassPermissions" | "default" | "dontAsk" | "plan";1776 mode?: "acceptEdits" | "bypassPermissions" | "default" | "dontAsk" | "plan";

1743 isolation?: "worktree";1777 isolation?: "worktree";

1744};1778};

7> Coordinate multiple Claude Code instances working together as a team, with shared tasks, inter-agent messaging, and centralized management.7> Coordinate multiple Claude Code instances working together as a team, with shared tasks, inter-agent messaging, and centralized management.

8 8 

9<Warning>9<Warning>

10 Agent teams are experimental and disabled by default. Enable them by adding `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` to your [settings.json](/en/settings) or environment. Agent teams have [known limitations](#limitations) around session resumption, task coordination, and shutdown behavior.10 Agent teams are experimental and disabled by default. Enable them by adding `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` to your [settings.json](/en/settings) or environment. Without that variable, no team is set up at session start, no team directories are written, and Claude does not spawn or propose teammates. Agent teams have [known limitations](#limitations) around session resumption, task coordination, and shutdown behavior.

11</Warning>11</Warning>

12 12 

13Agent teams let you coordinate multiple Claude Code instances working together. One session acts as the team lead, coordinating work, assigning tasks, and synthesizing results. Teammates work independently, each in its own context window, and communicate directly with each other.13Agent teams let you coordinate multiple Claude Code instances working together. One session acts as the team lead, coordinating work, assigning tasks, and synthesizing results. Teammates work independently, each in its own context window, and communicate directly with each other.

15Unlike [subagents](/en/sub-agents), which run within a single session and can only report back to the main agent, you can also interact with individual teammates directly without going through the lead.15Unlike [subagents](/en/sub-agents), which run within a single session and can only report back to the main agent, you can also interact with individual teammates directly without going through the lead.

16 16 

17<Note>17<Note>

18 Agent teams require Claude Code v2.1.32 or later. Check your version with `claude --version`.18 This page describes agent teams as of v2.1.178. With `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` set, spawning a teammate no longer needs a setup step, and cleanup happens automatically when the session exits. Before v2.1.178, you asked Claude to create and name a team first, and Claude used the `TeamCreate` and `TeamDelete` tools to set it up and remove it. Both tools no longer exist. The `team_name` input on the Agent tool is accepted but ignored, and the `team_name` field in `TaskCreated`, `TaskCompleted`, and `TeammateIdle` [hook payloads](/en/hooks#taskcreated) carries the session-derived name and is deprecated.

19</Note>19</Note>

20 20 

21This page covers:21This page covers:

70 70 

71## Start your first agent team71## Start your first agent team

72 72 

73After enabling agent teams, tell Claude to create an agent team and describe the task and the team structure you want in natural language. Claude creates the team, spawns teammates, and coordinates work based on your prompt.73After enabling agent teams, describe the task and the teammates you want in natural language. Claude spawns them and coordinates work based on your prompt.

74 74 

75This example works well because the three roles are independent and can explore the problem without waiting on each other:75This example works well because the three roles are independent and can explore the problem without waiting on each other:

76 76 

77```text theme={null}77```text theme={null}

78I'm designing a CLI tool that helps developers track TODO comments across78I'm designing a CLI tool that helps developers track TODO comments across

79their codebase. Create an agent team to explore this from different angles: one79their codebase. Spawn three teammates to explore this from different angles:

80teammate on UX, one on technical architecture, one playing devil's advocate.80one on UX, one on technical architecture, one playing devil's advocate.

81```81```

82 82 

83From there, Claude creates a team with a [shared task list](/en/interactive-mode#task-list), spawns teammates for each perspective, has them explore the problem, synthesizes findings, and attempts to [clean up the team](#clean-up-the-team) when finished.83From there, Claude populates a [shared task list](/en/interactive-mode#task-list), spawns teammates for each perspective, has them explore the problem, and synthesizes findings when finished.

84 84 

85The lead's terminal lists all teammates and what they're working on. Use Shift+Down to cycle through teammates and message them directly. After the last teammate, Shift+Down wraps back to the lead.85The lead's terminal lists all teammates and what they're working on. Use Shift+Down to cycle through teammates and message them directly. After the last teammate, Shift+Down wraps back to the lead.

86 86 

125Claude decides the number of teammates to spawn based on your task, or you can specify exactly what you want:125Claude decides the number of teammates to spawn based on your task, or you can specify exactly what you want:

126 126 

127```text theme={null}127```text theme={null}

128Create a team with 4 teammates to refactor these modules in parallel.128Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for

129Use Sonnet for each teammate.129each teammate.

130```130```

131 131 

132Teammates don't inherit the lead's `/model` selection by default. To change the model used when the prompt doesn't specify one, set **Default teammate model** in `/config`. Pick **Default (leader's model)** to have teammates follow the lead's current model.132Teammates don't inherit the lead's `/model` selection by default. To change the model used when the prompt doesn't specify one, set **Default teammate model** in `/config`. Pick **Default (leader's model)** to have teammates follow the lead's current model.

172 172 

173The lead sends a shutdown request. The teammate can approve, exiting gracefully, or reject with an explanation.173The lead sends a shutdown request. The teammate can approve, exiting gracefully, or reject with an explanation.

174 174 

175### Clean up the team175The team's shared directories are cleaned up automatically when the session ends, so there's no separate cleanup step. See [Architecture](#architecture) for which directories are removed and which persist for resumed sessions.

176 

177When you're done, ask the lead to clean up:

178 

179```text theme={null}

180Clean up the team

181```

182 

183This removes the shared team resources. When the lead runs cleanup, it checks for active teammates and fails if any are still running, so shut them down first. Claude often cleans up on its own when the team's work is done, so a later cleanup request may report that there is nothing to clean up.

184 

185<Warning>

186 Always use the lead to clean up. Teammates should not run cleanup because their team context may not resolve correctly, potentially leaving resources in an inconsistent state.

187</Warning>

188 176 

189### Enforce quality gates with hooks177### Enforce quality gates with hooks

190 178 

200 188 

201### How Claude starts agent teams189### How Claude starts agent teams

202 190 

203There are two ways agent teams get started:191An agent team forms when the first teammate is spawned, with the main session acting as the lead. There are two ways teammates get spawned:

204 192 

205* **You request a team**: give Claude a task that benefits from parallel work and explicitly ask for an agent team. Claude creates one based on your instructions.193* **You request teammates**: give Claude a task that benefits from parallel work and explicitly ask for teammates. Claude spawns them based on your instructions.

206* **Claude proposes a team**: if Claude determines your task would benefit from parallel work, it may suggest creating a team. You confirm before it proceeds.194* **Claude proposes teammates**: if Claude determines your task would benefit from parallel work, it may suggest spawning teammates. You confirm before it proceeds.

207 195 

208In both cases, you stay in control. Claude won't create a team without your approval.196In both cases, you stay in control. Claude won't spawn teammates without your approval.

209 197 

210### Architecture198### Architecture

211 199 

212An agent team consists of:200An agent team consists of:

213 201 

214| Component | Role |202| Component | Role |

215| :------------ | :----------------------------------------------------------------------------------------- |203| :------------ | :---------------------------------------------------------------------- |

216| **Team lead** | The main Claude Code session that creates the team, spawns teammates, and coordinates work |204| **Team lead** | The main Claude Code session that spawns teammates and coordinates work |

217| **Teammates** | Separate Claude Code instances that each work on assigned tasks |205| **Teammates** | Separate Claude Code instances that each work on assigned tasks |

218| **Task list** | Shared list of work items that teammates claim and complete |206| **Task list** | Shared list of work items that teammates claim and complete |

219| **Mailbox** | Messaging system for communication between agents |207| **Mailbox** | Messaging system for communication between agents |

222 210 

223The system manages task dependencies automatically. When a teammate completes a task that other tasks depend on, blocked tasks unblock without manual intervention.211The system manages task dependencies automatically. When a teammate completes a task that other tasks depend on, blocked tasks unblock without manual intervention.

224 212 

225Teams and tasks are stored locally:213Teams and tasks are stored locally under a session-derived name. The name is `session-` followed by the first eight characters of the session ID:

226 214 

227* **Team config**: `~/.claude/teams/{team-name}/config.json`215* **Team config**: `~/.claude/teams/{team-name}/config.json`

228* **Task list**: `~/.claude/tasks/{team-name}/`216* **Task list**: `~/.claude/tasks/{team-name}/`

229 217 

230Claude Code generates both of these automatically when you create a team and updates them as teammates join, go idle, or leave. Both directories exist only while the team is active: they are removed when the team is cleaned up or when the session ends. The team config holds runtime state such as session IDs and tmux pane IDs, so don't edit it by hand or pre-author it: your changes are overwritten on the next state update.218Claude Code generates both of these automatically at session startup and updates them as teammates join, go idle, or leave. The team config directory is removed when the session ends. The task list directory persists locally and is never uploaded, so resumed sessions keep their tasks. Retention is governed by the same [`cleanupPeriodDays`](/en/settings#available-settings) you already control for session transcripts.

219 

220The team config holds runtime state such as session IDs and tmux pane IDs, so don't edit it by hand or pre-author it: your changes are overwritten on the next state update.

231 221 

232To define reusable teammate roles, use [subagent definitions](#use-subagent-definitions-for-teammates) instead.222To define reusable teammate roles, use [subagent definitions](#use-subagent-definitions-for-teammates) instead.

233 223 

281A single reviewer tends to gravitate toward one type of issue at a time. Splitting review criteria into independent domains means security, performance, and test coverage all get thorough attention simultaneously. The prompt assigns each teammate a distinct lens so they don't overlap:271A single reviewer tends to gravitate toward one type of issue at a time. Splitting review criteria into independent domains means security, performance, and test coverage all get thorough attention simultaneously. The prompt assigns each teammate a distinct lens so they don't overlap:

282 272 

283```text theme={null}273```text theme={null}

284Create an agent team to review PR #142. Spawn three reviewers:274Spawn three teammates to review PR #142:

285- One focused on security implications275- One focused on security implications

286- One checking performance impact276- One checking performance impact

287- One validating test coverage277- One validating test coverage

366 356 

367### Teammates not appearing357### Teammates not appearing

368 358 

369If teammates aren't appearing after you ask Claude to create a team:359If teammates aren't appearing after you ask Claude to spawn them:

370 360 

371* In in-process mode, teammates may already be running but not visible. Press Shift+Down to cycle through active teammates.361* In in-process mode, teammates may already be running but not visible. Press Shift+Down to cycle through active teammates.

372* Check that the task you gave Claude was complex enough to warrant a team. Claude decides whether to spawn teammates based on the task.362* Check that the task you gave Claude was complex enough to warrant teammates. Claude decides whether to spawn them based on the task.

373* If you explicitly requested split panes, ensure tmux is installed and available in your PATH:363* If you explicitly requested split panes, ensure tmux is installed and available in your PATH:

374 ```bash theme={null}364 ```bash theme={null}

375 which tmux365 which tmux

393 383 

394### Orphaned tmux sessions384### Orphaned tmux sessions

395 385 

396If a tmux session persists after the team ends, it may not have been fully cleaned up. List sessions and end the one created by the team:386If a tmux session persists after the Claude Code session ends, it may not have been fully cleaned up. List sessions and end the one created by the team:

397 387 

398```bash theme={null}388```bash theme={null}

399tmux ls389tmux ls

407* **No session resumption with in-process teammates**: `/resume` and `/rewind` do not restore in-process teammates. After resuming a session, the lead may attempt to message teammates that no longer exist. If this happens, tell the lead to spawn new teammates.397* **No session resumption with in-process teammates**: `/resume` and `/rewind` do not restore in-process teammates. After resuming a session, the lead may attempt to message teammates that no longer exist. If this happens, tell the lead to spawn new teammates.

408* **Task status can lag**: teammates sometimes fail to mark tasks as completed, which blocks dependent tasks. If a task appears stuck, check whether the work is actually done and update the task status manually or tell the lead to nudge the teammate.398* **Task status can lag**: teammates sometimes fail to mark tasks as completed, which blocks dependent tasks. If a task appears stuck, check whether the work is actually done and update the task status manually or tell the lead to nudge the teammate.

409* **Shutdown can be slow**: teammates finish their current request or tool call before shutting down, which can take time.399* **Shutdown can be slow**: teammates finish their current request or tool call before shutting down, which can take time.

410* **One team at a time**: a lead can only manage one team. Clean up the current team before creating a new one.400* **One team per session**: a session has exactly one team, scoped to that session. You can't create additional named teams or share a team across sessions.

411* **No nested teams**: teammates cannot spawn their own teams or teammates. Only the lead can manage the team.401* **No nested teams**: teammates cannot spawn their own teammates. Only the lead can manage the team.

412* **Lead is fixed**: the session that creates the team is the lead for its lifetime. You can't promote a teammate to lead or transfer leadership.402* **Lead is fixed**: the main session is the lead for its lifetime. You can't promote a teammate to lead or transfer leadership.

413* **Permissions set at spawn**: all teammates start with the lead's permission mode. You can change individual teammate modes after spawning, but you can't set per-teammate modes at spawn time.403* **Permissions set at spawn**: all teammates start with the lead's permission mode. You can change individual teammate modes after spawning, but you can't set per-teammate modes at spawn time.

414* **Split panes require tmux or iTerm2**: the default in-process mode works in any terminal. Split-pane mode isn't supported in VS Code's integrated terminal, Windows Terminal, or Ghostty.404* **Split panes require tmux or iTerm2**: the default in-process mode works in any terminal. Split-pane mode isn't supported in VS Code's integrated terminal, Windows Terminal, or Ghostty.

415 405 

487 487 

488Each background session has the `CLAUDE_JOB_DIR` environment variable set to its `~/.claude/jobs/<id>` directory, so shell commands the session runs can write temporary files to `$CLAUDE_JOB_DIR/tmp` without colliding with parallel sessions.488Each background session has the `CLAUDE_JOB_DIR` environment variable set to its `~/.claude/jobs/<id>` directory, so shell commands the session runs can write temporary files to `$CLAUDE_JOB_DIR/tmp` without colliding with parallel sessions.

489 489 

490To inspect this state without reading the files directly, run `claude daemon status`. It reports whether the supervisor is reachable, its process ID and version, the socket directory, and how many background sessions are live. `/doctor` includes a summary of the same check. On Windows, `claude daemon status` surfaces the underlying file error when the daemon's pipe-key file is locked or unreadable instead of reporting a generic connection failure.490To inspect this state without reading the files directly, run `claude daemon status`. It reports whether the supervisor is reachable, its process ID and version, the socket directory, and how many background sessions are live. `/doctor` includes a summary of the same check.

491 

492The command also warns when the running supervisor is on a different version than the `claude` you invoked, which happens after an update the supervisor hasn't restarted into yet. The warning shows both versions and tells you to run `claude daemon stop --any` to pick up the new version. When Claude Code is installed as an OS service, the suggested command is `claude daemon stop` without the flag.

493 

494On Windows, `claude daemon status` surfaces the underlying file error when the daemon's pipe-key file is locked or unreadable instead of reporting a generic connection failure.

491 495 

492### Turn off agent view496### Turn off agent view

493 497 

197 "Credentials": {197 "Credentials": {

198 "AccessKeyId": "value",198 "AccessKeyId": "value",

199 "SecretAccessKey": "value",199 "SecretAccessKey": "value",

200 "SessionToken": "value"200 "SessionToken": "value",

201 "Expiration": "2026-01-01T00:00:00Z"

201 }202 }

202}203}

203```204```

204 205 

206`Expiration` is optional. {/* min-version: 2.1.176 */}As of Claude Code v2.1.176, when the command returns a valid ISO 8601 `Expiration`, Claude Code caches the credentials until five minutes before that time. Without it, or on earlier versions, credentials are cached for one hour.

207 

205### 3. Configure Claude Code208### 3. Configure Claude Code

206 209 

207Set the following environment variables to enable Bedrock:210Set the following environment variables to enable Bedrock:

77* Use Sonnet for teammates. It balances capability and cost for coordination tasks.77* Use Sonnet for teammates. It balances capability and cost for coordination tasks.

78* Keep teams small. Each teammate runs its own context window, so token usage is roughly proportional to team size.78* Keep teams small. Each teammate runs its own context window, so token usage is roughly proportional to team size.

79* Keep spawn prompts focused. Teammates load CLAUDE.md, MCP servers, and skills automatically, but everything in the spawn prompt adds to their context from the start.79* Keep spawn prompts focused. Teammates load CLAUDE.md, MCP servers, and skills automatically, but everything in the spawn prompt adds to their context from the start.

80* Clean up teams when work is done. Active teammates continue consuming tokens even if idle.80* Shut down teammates when their work is done. Each active teammate continues consuming tokens until it exits or the session ends.

81* Agent teams are disabled by default. Set `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in your [settings.json](/en/settings) or environment to enable them. See [enable agent teams](/en/agent-teams#enable-agent-teams).81* Agent teams are disabled by default. Set `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in your [settings.json](/en/settings) or environment to enable them. See [enable agent teams](/en/agent-teams#enable-agent-teams).

82 82 

83## Reduce token usage83## Reduce token usage

86## Variables86## Variables

87 87 

88| Variable | Purpose |88| Variable | Purpose |

89| :------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |89| :------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

90| `ANTHROPIC_API_KEY` | API key sent as `X-Api-Key` header. When set, this key is used instead of your Claude Pro, Max, Team, or Enterprise subscription even if you are logged in. In non-interactive mode (`-p`), the key is always used when present. In interactive mode, you are prompted to approve the key once before it overrides your subscription. To use your subscription instead, run `unset ANTHROPIC_API_KEY` |90| `ANTHROPIC_API_KEY` | API key sent as `X-Api-Key` header. When set, this key is used instead of your Claude Pro, Max, Team, or Enterprise subscription even if you are logged in. In non-interactive mode (`-p`), the key is always used when present. In interactive mode, you are prompted to approve the key once before it overrides your subscription. To use your subscription instead, run `unset ANTHROPIC_API_KEY` |

91| `ANTHROPIC_AUTH_TOKEN` | Custom value for the `Authorization` header (the value you set here will be prefixed with `Bearer `) |91| `ANTHROPIC_AUTH_TOKEN` | Custom value for the `Authorization` header (the value you set here will be prefixed with `Bearer `) |

92| `ANTHROPIC_AWS_API_KEY` | Workspace API key for [Claude Platform on AWS](/en/claude-platform-on-aws), generated in the AWS Console. Sent as `x-api-key` and takes precedence over AWS SigV4 |92| `ANTHROPIC_AWS_API_KEY` | Workspace API key for [Claude Platform on AWS](/en/claude-platform-on-aws), generated in the AWS Console. Sent as `x-api-key` and takes precedence over AWS SigV4 |

138| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | Set to `1` to disable all built-in [subagent](/en/sub-agents) types such as Explore and Plan. Only applies in non-interactive mode (the `-p` flag). Useful for SDK users who want a blank slate |138| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | Set to `1` to disable all built-in [subagent](/en/sub-agents) types such as Explore and Plan. Only applies in non-interactive mode (the `-p` flag). Useful for SDK users who want a blank slate |

139| `CLAUDE_AGENT_SDK_MCP_NO_PREFIX` | Set to `1` to skip the `mcp__<server>__` prefix on tool names from SDK-created MCP servers. Tools use their original names. SDK usage only |139| `CLAUDE_AGENT_SDK_MCP_NO_PREFIX` | Set to `1` to skip the `mcp__<server>__` prefix on tool names from SDK-created MCP servers. Tools use their original names. SDK usage only |

140| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | Stall timeout in milliseconds for background subagents. Default `600000` (10 minutes). The timer resets on each streaming progress event; if no progress arrives within the window, the subagent is aborted and the task is marked failed, surfacing any partial result to the parent |140| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | Stall timeout in milliseconds for background subagents. Default `600000` (10 minutes). The timer resets on each streaming progress event; if no progress arrives within the window, the subagent is aborted and the task is marked failed, surfacing any partial result to the parent |

141| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | Set the percentage (1-100) of the auto-compaction window at which auto-compaction triggers. Use lower values like `50` to compact earlier. This variable only causes earlier compaction when Claude Code compacts proactively: when `CLAUDE_CODE_AUTO_COMPACT_WINDOW` is set, in [cloud sessions](/en/claude-code-on-the-web), in [Remote Control](/en/remote-control) sessions, and on Sonnet 4.6 and Opus 4.6 without [extended context](/en/model-config#extended-context), which compact at the 200K boundary by default. In other cases, such as a default local session, auto-compaction triggers when the conversation reaches the model's context limit. The override can only lower the threshold, so values above the default have no effect. Applies to both main conversations and subagents |141| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | Set the percentage (1-100) of the auto-compaction window at which auto-compaction triggers. Use lower values like `50` to compact earlier. This variable only causes earlier compaction when Claude Code compacts proactively: when `CLAUDE_CODE_AUTO_COMPACT_WINDOW` is set, in [cloud sessions](/en/claude-code-on-the-web), in [Remote Control](/en/remote-control) sessions, and on Sonnet 4.6 and Opus 4.6 without [extended context](/en/model-config#extended-context), which compact at the 200K boundary by default. In other cases, such as a local session on Opus 4.8 or any model with extended context, auto-compaction triggers when the conversation reaches the model's context limit. The override can only lower the threshold, so values above the default have no effect. Applies to both main conversations and subagents |

142| `CLAUDE_AUTO_BACKGROUND_TASKS` | Set to `1` to force-enable automatic backgrounding of long-running agent tasks. When enabled, subagents are moved to the background after running for approximately two minutes |142| `CLAUDE_AUTO_BACKGROUND_TASKS` | Set to `1` to force-enable automatic backgrounding of long-running agent tasks. When enabled, subagents are moved to the background after running for approximately two minutes |

143| `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR` | Return to the original working directory after each Bash or PowerShell command in the main session |143| `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR` | Return to the original working directory after each Bash or PowerShell command in the main session |

144| `CLAUDE_CODE_ACCESSIBILITY` | Set to `1` to keep the native terminal cursor visible and disable the inverted-text cursor indicator. Allows screen magnifiers like macOS Zoom to track cursor position |144| `CLAUDE_CODE_ACCESSIBILITY` | Set to `1` to keep the native terminal cursor visible and disable the inverted-text cursor indicator. Allows screen magnifiers like macOS Zoom to track cursor position |

150| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for [extended context](/en/model-config#extended-context) models. Use a lower value like `500000` on a 1M model to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window |150| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | Set the context capacity in tokens used for auto-compaction calculations. Defaults to the model's context window: 200K for standard models or 1M for [extended context](/en/model-config#extended-context) models. Use a lower value like `500000` on a 1M model to treat the window as 500K for compaction purposes. The value is capped at the model's actual context window. `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` is applied as a percentage of this value. Setting this variable decouples the compaction threshold from the status line's `used_percentage`, which always uses the model's full context window |

151| `CLAUDE_CODE_AUTO_CONNECT_IDE` | Override automatic [IDE connection](/en/vs-code). By default, Claude Code connects automatically when launched inside a supported IDE's integrated terminal. Set to `false` to prevent this. Set to `true` to force a connection attempt when auto-detection fails, such as when tmux obscures the parent terminal. Takes precedence over the [`autoConnectIde`](/en/settings#global-config-settings) global config setting |151| `CLAUDE_CODE_AUTO_CONNECT_IDE` | Override automatic [IDE connection](/en/vs-code). By default, Claude Code connects automatically when launched inside a supported IDE's integrated terminal. Set to `false` to prevent this. Set to `true` to force a connection attempt when auto-detection fails, such as when tmux obscures the parent terminal. Takes precedence over the [`autoConnectIde`](/en/settings#global-config-settings) global config setting |

152| `CLAUDE_CODE_CERT_STORE` | Comma-separated list of CA certificate sources for TLS connections. `bundled` is the Mozilla CA set shipped with Claude Code. `system` is the operating system trust store. Default is `bundled,system` |152| `CLAUDE_CODE_CERT_STORE` | Comma-separated list of CA certificate sources for TLS connections. `bundled` is the Mozilla CA set shipped with Claude Code. `system` is the operating system trust store. Default is `bundled,system` |

153| `CLAUDE_CODE_CHILD_SESSION` | {/* min-version: 2.1.172 */}Set to `1` in subprocesses Claude Code spawns via the Bash, PowerShell, and Monitor tools, [hook](/en/hooks) commands, and [status line](/en/statusline) commands. Not set for stdio [MCP server](/en/mcp) subprocesses, which are long-lived and outlive the session that spawned them. Unlike `CLAUDECODE`, this is only set by Claude Code's own spawn path and not by IDE extensions, so it reliably distinguishes a nested session from a top-level `claude` launched in an IDE-integrated terminal. A nested interactive `claude` TUI started this way is automatically excluded from `--resume`, `--continue`, up-arrow history, and the `claude agents` list. Non-interactive `claude -p` sessions still persist. Set `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1` to override this exclusion. Requires Claude Code v2.1.172 or later |153| `CLAUDE_CODE_CHILD_SESSION` | {/* min-version: 2.1.172 */}Set to `1` in subprocesses Claude Code spawns via the Bash, PowerShell, and Monitor tools, [hook](/en/hooks) commands, and [status line](/en/statusline) commands. Not set for stdio [MCP server](/en/mcp) subprocesses, which are long-lived and outlive the session that spawned them. Unlike `CLAUDECODE`, this is only set by Claude Code itself when it launches a subprocess and not by IDE extensions, so it reliably distinguishes a nested session from a top-level `claude` launched in an IDE-integrated terminal. A nested interactive `claude` TUI started this way is automatically excluded from `--resume`, `--continue`, up-arrow history, and the `claude agents` list. Non-interactive `claude -p` sessions still persist. Set `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1` to override this exclusion. Requires Claude Code v2.1.172 or later |

154| `CLAUDE_CODE_CLIENT_CERT` | Path to client certificate file for mTLS authentication |154| `CLAUDE_CODE_CLIENT_CERT` | Path to client certificate file for mTLS authentication |

155| `CLAUDE_CODE_CLIENT_KEY` | Path to client private key file for mTLS authentication |155| `CLAUDE_CODE_CLIENT_KEY` | Path to client private key file for mTLS authentication |

156| `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE` | Passphrase for encrypted CLAUDE\_CODE\_CLIENT\_KEY (optional) |156| `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE` | Passphrase for encrypted CLAUDE\_CODE\_CLIENT\_KEY (optional) |

199| `CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS` | Override the default token limit for file reads. Useful when you need to read larger files in full |199| `CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS` | Override the default token limit for file reads. Useful when you need to read larger files in full |

200| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | {/* min-version: 2.1.172 */}Set to `1` to force transcript persistence, prompt history, and `claude agents` registration even when this `claude` was launched from inside another Claude Code session. Use when an inherited `CLAUDE_CODE_CHILD_SESSION` value, for example from a tmux server first started by Claude Code's Bash tool, causes a genuine top-level session to be misclassified as nested. Also honored on v2.1.169 and earlier; has no effect on v2.1.170 and v2.1.171, where the nested-session detection it overrides was removed |200| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | {/* min-version: 2.1.172 */}Set to `1` to force transcript persistence, prompt history, and `claude agents` registration even when this `claude` was launched from inside another Claude Code session. Use when an inherited `CLAUDE_CODE_CHILD_SESSION` value, for example from a tmux server first started by Claude Code's Bash tool, causes a genuine top-level session to be misclassified as nested. Also honored on v2.1.169 and earlier; has no effect on v2.1.170 and v2.1.171, where the nested-session detection it overrides was removed |

201| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | Set to `1` to force-enable DEC private mode 2026 [synchronized output](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036) when your terminal supports it but is not auto-detected. Useful for emulators such as Emacs `eat` that implement BSU/ESU but do not reply to the capability probe. Has no effect under tmux |201| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | Set to `1` to force-enable DEC private mode 2026 [synchronized output](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036) when your terminal supports it but is not auto-detected. Useful for emulators such as Emacs `eat` that implement BSU/ESU but do not reply to the capability probe. Has no effect under tmux |

202| `CLAUDE_CODE_FORK_SUBAGENT` | Set to `1` to make [forked subagents](/en/sub-agents#fork-the-current-conversation) the model's default, or `0` to disable them, overriding any server-side rollout. When enabled, Claude spawns a fork, a subagent that inherits the full conversation context instead of starting fresh, whenever it would otherwise use the general-purpose subagent, and all subagent spawns run in the background. The explicit [`/fork`](/en/commands) command works without this variable. Works in interactive mode and via the SDK or `claude -p` |202| `CLAUDE_CODE_FORK_SUBAGENT` | Set to `1` to let Claude spawn [forked subagents](/en/sub-agents#fork-the-current-conversation), or `0` to disable them, overriding any server-side rollout. When enabled, Claude can request the `fork` subagent type to spawn a fork, a subagent that inherits the full conversation context instead of starting fresh. Spawns without a subagent type still use the general-purpose subagent, and all subagent spawns run in the background. The explicit [`/fork`](/en/commands) command works without this variable. Works in interactive mode and via the SDK or `claude -p` |

203| `CLAUDE_CODE_GIT_BASH_PATH` | Windows only: path to the Git Bash executable (`bash.exe`). Use when Git Bash is installed but not in your PATH. See [Windows setup](/en/setup#set-up-on-windows) |203| `CLAUDE_CODE_GIT_BASH_PATH` | Windows only: path to the Git Bash executable (`bash.exe`). Use when Git Bash is installed but not in your PATH. See [Windows setup](/en/setup#set-up-on-windows) |

204| `CLAUDE_CODE_GLOB_HIDDEN` | Set to `false` to exclude dotfiles from results when Claude invokes the [Glob tool](/en/tools-reference#glob-tool-behavior). Included by default. Does not affect `@` file autocomplete, `ls`, Grep, or Read |204| `CLAUDE_CODE_GLOB_HIDDEN` | Set to `false` to exclude dotfiles from results when Claude invokes the [Glob tool](/en/tools-reference#glob-tool-behavior). Included by default. Does not affect `@` file autocomplete, `ls`, Grep, or Read |

205| `CLAUDE_CODE_GLOB_NO_IGNORE` | Set to `false` to make the [Glob tool](/en/tools-reference#glob-tool-behavior) respect `.gitignore` patterns. By default, Glob returns all matching files including gitignored ones. Does not affect `@` file autocomplete, which has its own [`respectGitignore` setting](/en/settings#available-settings) |205| `CLAUDE_CODE_GLOB_NO_IGNORE` | Set to `false` to make the [Glob tool](/en/tools-reference#glob-tool-behavior) respect `.gitignore` patterns. By default, Glob returns all matching files including gitignored ones. Does not affect `@` file autocomplete, which has its own [`respectGitignore` setting](/en/settings#available-settings) |

241| `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 |241| `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 |

242| `CLAUDE_CODE_SAFE_MODE` | Set to `1` to start in safe mode: CLAUDE.md, skills, plugins, hooks, MCP servers, custom commands and agents, output styles, workflows, custom themes, custom keybindings, status line and file-suggestion commands, LSP servers, and auto-memory do not load, for troubleshooting a broken configuration. Managed settings policy still applies, including policy-configured hooks, status line, and file-suggestion commands; managed plugins, managed skills, managed CLAUDE.md, and policy-configured MCP servers do not. Equivalent to passing [`--safe-mode`](/en/cli-reference#cli-flags). Directly spawned child processes inherit the variable |242| `CLAUDE_CODE_SAFE_MODE` | Set to `1` to start in safe mode: CLAUDE.md, skills, plugins, hooks, MCP servers, custom commands and agents, output styles, workflows, custom themes, custom keybindings, status line and file-suggestion commands, LSP servers, and auto-memory do not load, for troubleshooting a broken configuration. Managed settings policy still applies, including policy-configured hooks, status line, and file-suggestion commands; managed plugins, managed skills, managed CLAUDE.md, and policy-configured MCP servers do not. Equivalent to passing [`--safe-mode`](/en/cli-reference#cli-flags). Directly spawned child processes inherit the variable |

243| `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 |243| `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 |

244| `CLAUDE_CODE_SCROLL_SPEED` | Set the mouse wheel scroll multiplier in [fullscreen rendering](/en/fullscreen#mouse-wheel-scrolling). Accepts values from 1 to 20, and fractional values below 1 such as `0.5` to slow accelerated trackpad and wheel scrolling in terminals on the native scroll path. 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 |244| `CLAUDE_CODE_SCROLL_SPEED` | Set the mouse wheel scroll multiplier in [fullscreen rendering](/en/fullscreen#mouse-wheel-scrolling). Accepts values from 1 to 20, and fractional values below 1 such as `0.5` to slow accelerated trackpad and wheel scrolling in terminals that already amplify wheel events. 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 |

245| `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 |245| `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 |

246| `CLAUDE_CODE_SESSION_ID` | Set automatically to the current session ID in Bash and PowerShell tool subprocesses, [hook command](/en/hooks) subprocesses, and stdio [MCP server](/en/mcp) subprocesses. For Bash, PowerShell, and hooks this matches the `session_id` field in the hook JSON input and is updated on `/clear`. An MCP server subprocess retains the ID it was spawned with. On `--resume <session-id>` it receives the resumed ID, matching hooks and Bash. On `--continue` or `--resume` without an explicit ID it may receive the initial startup ID instead. Use to correlate scripts and external tools with the Claude Code session that launched them |246| `CLAUDE_CODE_SESSION_ID` | Set automatically to the current session ID in Bash and PowerShell tool subprocesses, [hook command](/en/hooks) subprocesses, and stdio [MCP server](/en/mcp) subprocesses. For Bash, PowerShell, and hooks this matches the `session_id` field in the hook JSON input and is updated on `/clear`. An MCP server subprocess retains the ID it was spawned with. On `--resume <session-id>` it receives the resumed ID, matching hooks and Bash. On `--continue` or `--resume` without an explicit ID it may receive the initial startup ID instead. Use to correlate scripts and external tools with the Claude Code session that launched them |

247| `CLAUDE_CODE_SHELL` | Override automatic shell detection. Useful when your login shell differs from your preferred working shell (for example, `bash` vs `zsh`) |247| `CLAUDE_CODE_SHELL` | Override automatic shell detection. Useful when your login shell differs from your preferred working shell (for example, `bash` vs `zsh`) |

105* **Admin enablement for Team and Enterprise**: fast mode is disabled by default for Team and Enterprise organizations. An admin must explicitly [enable fast mode](#enable-fast-mode-for-your-organization) before users can access it.105* **Admin enablement for Team and Enterprise**: fast mode is disabled by default for Team and Enterprise organizations. An admin must explicitly [enable fast mode](#enable-fast-mode-for-your-organization) before users can access it.

106 106 

107<Note>107<Note>

108 If your admin has not enabled fast mode for your organization, the `/fast` command will show "Fast mode has been disabled by your organization."108 If your admin has not enabled fast mode for your organization, the `/fast` command will show "Fast mode has been disabled by your organization." If your organization's [`availableModels`](/en/model-config#restrict-model-selection) allowlist excludes the fast-mode Opus model, `/fast` is refused with "is not in your organization's allowed models".

109</Note>109</Note>

110 110 

111### Enable fast mode for your organization111### Enable fast mode for your organization

92export CLAUDE_CODE_SCROLL_SPEED=392export CLAUDE_CODE_SCROLL_SPEED=3

93```93```

94 94 

95A value of `3` matches the default in `vim` and similar applications. The setting accepts values from 1 to 20, and fractional values below 1 such as `0.5` to slow accelerated trackpad and wheel scrolling in terminals on the native scroll path.95A value of `3` matches the default in `vim` and similar applications. The setting accepts values from 1 to 20, and fractional values below 1 such as `0.5` to slow accelerated trackpad and wheel scrolling in terminals that already amplify wheel events.

96 96 

97To adjust scroll speed interactively, run `/scroll-speed`. The dialog shows a ruler you can scroll while it is open so you can feel the change immediately. Press `←` and `→` to adjust, `r` to reset to the auto-detected default, and `Enter` to save. The command writes the same value the `CLAUDE_CODE_SCROLL_SPEED` environment variable sets, persisted to `~/.claude/settings.json`. The command is not available in the JetBrains IDE terminal.97To adjust scroll speed interactively, run `/scroll-speed`. The dialog shows a ruler you can scroll while it is open so you can feel the change immediately. Press `←` and `→` to adjust, `r` to reset to the auto-detected default, and `Enter` to save. The command writes the same value the `CLAUDE_CODE_SCROLL_SPEED` environment variable sets, persisted to `~/.claude/settings.json`. The command is not available in the JetBrains IDE terminal.

98 98 

1425 1425 

1426For `run_in_background: true` calls, the tool returns immediately after launching the subagent, so `tool_response` carries no usage fields. It has `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile`, and `resolvedModel`.1426For `run_in_background: true` calls, the tool returns immediately after launching the subagent, so `tool_response` carries no usage fields. It has `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile`, and `resolvedModel`.

1427 1427 

1428The `resolvedModel` field names the model the subagent actually runs on, which can differ from the `model` value in `tool_input`. It requires Claude Code v2.1.174 or later.1428The `resolvedModel` field names the model the subagent actually runs on, which can differ from the `model` value in `tool_input`, such as when `availableModels` or another override applies. It requires Claude Code v2.1.174 or later.

1429 1429 

1430<a id="askuserquestion" />1430<a id="askuserquestion" />

1431 1431 

1975 "task_subject": "Implement user authentication",1975 "task_subject": "Implement user authentication",

1976 "task_description": "Add login and signup endpoints",1976 "task_description": "Add login and signup endpoints",

1977 "teammate_name": "implementer",1977 "teammate_name": "implementer",

1978 "team_name": "my-project"1978 "team_name": "session-a1b2c3d4"

1979}1979}

1980```1980```

1981 1981 

1982| Field | Description |1982| Field | Description |

1983| :----------------- | :---------------------------------------------------- |1983| :----------------- | :------------------------------------------------------------------------- |

1984| `task_id` | Identifier of the task being created |1984| `task_id` | Identifier of the task being created |

1985| `task_subject` | Title of the task |1985| `task_subject` | Title of the task |

1986| `task_description` | Detailed description of the task. May be absent |1986| `task_description` | Detailed description of the task. May be absent |

1987| `teammate_name` | Name of the teammate creating the task. May be absent |1987| `teammate_name` | Name of the teammate creating the task. May be absent |

1988| `team_name` | Name of the team. May be absent |1988| `team_name` | Deprecated. Session-derived team name; will be removed in a future release |

1989 1989 

1990#### TaskCreated decision control1990#### TaskCreated decision control

1991 1991 

2030 "task_subject": "Implement user authentication",2030 "task_subject": "Implement user authentication",

2031 "task_description": "Add login and signup endpoints",2031 "task_description": "Add login and signup endpoints",

2032 "teammate_name": "implementer",2032 "teammate_name": "implementer",

2033 "team_name": "my-project"2033 "team_name": "session-a1b2c3d4"

2034}2034}

2035```2035```

2036 2036 

2037| Field | Description |2037| Field | Description |

2038| :----------------- | :------------------------------------------------------ |2038| :----------------- | :------------------------------------------------------------------------- |

2039| `task_id` | Identifier of the task being completed |2039| `task_id` | Identifier of the task being completed |

2040| `task_subject` | Title of the task |2040| `task_subject` | Title of the task |

2041| `task_description` | Detailed description of the task. May be absent |2041| `task_description` | Detailed description of the task. May be absent |

2042| `teammate_name` | Name of the teammate completing the task. May be absent |2042| `teammate_name` | Name of the teammate completing the task. May be absent |

2043| `team_name` | Name of the team. May be absent |2043| `team_name` | Deprecated. Session-derived team name; will be removed in a future release |

2044 2044 

2045#### TaskCompleted decision control2045#### TaskCompleted decision control

2046 2046 

2211 "permission_mode": "default",2211 "permission_mode": "default",

2212 "hook_event_name": "TeammateIdle",2212 "hook_event_name": "TeammateIdle",

2213 "teammate_name": "researcher",2213 "teammate_name": "researcher",

2214 "team_name": "my-project"2214 "team_name": "session-a1b2c3d4"

2215}2215}

2216```2216```

2217 2217 

2218| Field | Description |2218| Field | Description |

2219| :-------------- | :-------------------------------------------- |2219| :-------------- | :------------------------------------------------------------------------- |

2220| `teammate_name` | Name of the teammate that is about to go idle |2220| `teammate_name` | Name of the teammate that is about to go idle |

2221| `team_name` | Name of the team |2221| `team_name` | Deprecated. Session-derived team name; will be removed in a future release |

2222 2222 

2223#### TeammateIdle decision control2223#### TeammateIdle decision control

2224 2224 

113 113 

114Enterprise administrators can use `availableModels` in [managed or policy settings](/en/settings#settings-files) to restrict which models users can select.114Enterprise administrators can use `availableModels` in [managed or policy settings](/en/settings#settings-files) to restrict which models users can select.

115 115 

116When `availableModels` is set, the allowlist applies to every surface where a user can name a model:116When `availableModels` is set, the allowlist applies everywhere a user can specify a model:

117 117 

118* **Main session model**: `/model`, the `--model` flag, and the `ANTHROPIC_MODEL` environment variable118* **Main session model**: `/model`, the `--model` flag, and the `ANTHROPIC_MODEL` environment variable

119* **Alias resolution**: {/* min-version: 2.1.176 */}the `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_HAIKU_MODEL`, and `ANTHROPIC_DEFAULT_FABLE_MODEL` environment variables cannot redirect an allowed alias to a model outside the list

120* **Fast mode**: {/* min-version: 2.1.176 */}`/fast` refuses to toggle when it would implicitly switch to an Opus model outside the list, with the message "is not in your organization's allowed models"

119* **Subagent models**: the `model` field in [subagent](/en/sub-agents#choose-a-model) frontmatter, the Agent tool's `model` parameter, the model picker in `/agents`, and `CLAUDE_CODE_SUBAGENT_MODEL`121* **Subagent models**: the `model` field in [subagent](/en/sub-agents#choose-a-model) frontmatter, the Agent tool's `model` parameter, the model picker in `/agents`, and `CLAUDE_CODE_SUBAGENT_MODEL`

120* **Advisor model**: the configured [`advisorModel`](/en/advisor) setting122* **Advisor model**: the configured [`advisorModel`](/en/advisor) setting

121* **Fallback chains**: elements of a [fallback model chain](#fallback-model-chains) outside the list are dropped123* **Fallback chains**: elements of a [fallback model chain](#fallback-model-chains) outside the list are dropped

201 203 

202The plan-mode Opus phase uses the same context window as the `opus` model setting. On subscription tiers where Opus is [automatically upgraded to 1M context](#extended-context), `opusplan` receives the upgrade in plan mode as well. To force 1M context for both phases when you are not on an auto-upgrade tier, set the model to `opusplan[1m]`.204The plan-mode Opus phase uses the same context window as the `opus` model setting. On subscription tiers where Opus is [automatically upgraded to 1M context](#extended-context), `opusplan` receives the upgrade in plan mode as well. To force 1M context for both phases when you are not on an auto-upgrade tier, set the model to `opusplan[1m]`.

203 205 

204When [`availableModels`](#restrict-model-selection) excludes Opus, `opusplan` stays on Sonnet in plan mode instead of switching. The same applies to the implicit Haiku-to-Sonnet plan-mode upgrade when Sonnet is excluded.206When [`availableModels`](#restrict-model-selection) excludes Opus, `opusplan` stays on Sonnet in plan mode instead of switching. Similarly, a Haiku session that would normally upgrade to Sonnet in plan mode stays on Haiku when Sonnet is excluded.

205 207 

206For a hybrid approach where Claude decides mid-task when to consult a second model rather than switching at the plan boundary, see the [advisor tool](/en/advisor).208For a hybrid approach where Claude decides mid-task when to consult a second model rather than switching at the plan boundary, see the [advisor tool](/en/advisor).

207 209 

51 * User: `~/.claude/output-styles`51 * User: `~/.claude/output-styles`

52 * Project: `.claude/output-styles`52 * Project: `.claude/output-styles`

53 * Managed policy: `.claude/output-styles` inside the [managed settings directory](/en/settings#settings-files)53 * Managed policy: `.claude/output-styles` inside the [managed settings directory](/en/settings#settings-files)

54 

55 Project output styles load from every `.claude/output-styles/` between the working directory and the repository root. {/* min-version: 2.1.178 */}As of v2.1.178, when more than one of these nested directories defines a style with the same name, Claude Code uses the one closest to the working directory.

54 </Step>56 </Step>

55 57 

56 <Step title="Add frontmatter and instructions">58 <Step title="Add frontmatter and instructions">

271 1. Before a subagent starts, the delegated task description is evaluated, so a dangerous-looking task is blocked at spawn time.271 1. Before a subagent starts, the delegated task description is evaluated, so a dangerous-looking task is blocked at spawn time.

272 2. While the subagent runs, each of its actions goes through the classifier with the same rules as the parent session, and any `permissionMode` in the subagent's frontmatter is ignored.272 2. While the subagent runs, each of its actions goes through the classifier with the same rules as the parent session, and any `permissionMode` in the subagent's frontmatter is ignored.

273 3. When the subagent finishes, the classifier reviews its full action history; if that return check flags a concern, a security warning is prepended to the subagent's results.273 3. When the subagent finishes, the classifier reviews its full action history; if that return check flags a concern, a security warning is prepended to the subagent's results.

274 

275 Step 1 requires Claude Code v2.1.178 or later. Earlier versions applied the classifier at steps 2 and 3, but did not evaluate the task description before the subagent started.

274 </Accordion>276 </Accordion>

275 277 

276 <Accordion title="Cost and latency">278 <Accordion title="Cost and latency">

26* **Ask** rules prompt for confirmation whenever Claude Code tries to use the specified tool.26* **Ask** rules prompt for confirmation whenever Claude Code tries to use the specified tool.

27* **Deny** rules prevent Claude Code from using the specified tool.27* **Deny** rules prevent Claude Code from using the specified tool.

28 28 

29Rules are evaluated in order: deny, then ask, then allow. The first match in that order determines the outcome, and rule specificity does not change the order. A matching ask rule prompts even when a more specific allow rule also matches the same call.29Rules are evaluated in order: deny, then ask, then allow. The first match in that order determines the outcome, and rule specificity does not change the order. A broad deny rule like `Bash(aws *)` blocks every matching call, including calls that also match a narrower allow rule like `Bash(aws s3 ls)`, so a deny rule cannot carry allowlist exceptions. The same precedence applies between ask and allow: a matching ask rule prompts even when a more specific allow rule also matches the same call.

30 30 

31Deny rules behave differently depending on whether they name a tool or scope a pattern within one. A bare tool name like `Bash` removes the tool from Claude's context entirely, so Claude never sees it. A scoped rule like `Bash(rm *)` leaves the tool available and blocks matching calls when Claude attempts them.31Deny rules behave differently depending on whether they name a tool or scope a pattern within one. A bare tool name like `Bash` removes the tool from Claude's context entirely, so Claude never sees it. A scoped rule like `Bash(rm *)` leaves the tool available and blocks matching calls when Claude attempts them.

32 32 

79| `Read(./.env)` | Matches reading the `.env` file in the current directory |79| `Read(./.env)` | Matches reading the `.env` file in the current directory |

80| `WebFetch(domain:example.com)` | Matches fetch requests to example.com |80| `WebFetch(domain:example.com)` | Matches fetch requests to example.com |

81 81 

82### Match by input parameter

83 

84Deny and ask rules can match a top-level input parameter on any tool with `Tool(param:value)`. The rule matches when Claude calls the tool with that parameter set to that exact value. This syntax is for deny and ask rules; an allow rule for one parameter value would not establish that the call is safe overall, so allow rules continue to use each tool's own specifier syntax. This works for any scalar parameter the tool accepts:

85 

86| Rule | Matches |

87| :----------------------------- | :------------------------------------------- |

88| `Agent(model:opus)` | Agent calls that request the Opus model tier |

89| `Agent(isolation:worktree)` | Agent calls that request a git worktree |

90| `Bash(run_in_background:true)` | Bash calls that run in the background |

91 

92Parameter matching follows these rules:

93 

94* The parameter name must be a direct field of the tool's input, such as `model` on the Agent tool. Fields nested inside an object or array are not matchable

95* Each rule names one parameter. To gate on both `model` and `isolation`, write two rules, `Agent(model:opus)` and `Agent(isolation:worktree)`, rather than combining them in one rule

96* The value supports `*` as a wildcard that matches any sequence of characters, so `Agent(isolation:*)` matches any explicit isolation value. Without `*` the match is exact

97* A parameter the model omits is never matched, so `Agent(model:*)` does not match a call that leaves `model` unset

98* The value is compared against the literal input Claude sends, before any normalization. `Agent(model:opus)` matches the alias `opus` but not a full model ID. Run with [`--verbose`](/en/cli-reference) to see the exact parameter names and values in each tool call

99* Whitespace around the colon is ignored

100 

101Fields that a tool already matches with its own canonicalizing rules are not matchable this way: `command` for Bash and PowerShell, `file_path` for Read, Edit, and Write, `path` for Grep and Glob, `notebook_path` for NotebookEdit, and `url` for WebFetch. A rule like `Bash(command:rm *)` would be bypassable by a compound command, so Claude Code ignores it and emits a startup warning. Use `Bash(rm *)`, `Read(./path)`, or `WebFetch(domain:host)` instead.

102 

82### Wildcard patterns103### Wildcard patterns

83 104 

84Bash rules support glob patterns with `*`. Wildcards can appear at any position in the command. This configuration allows npm and git commit commands while blocking git push:105Bash rules support glob patterns with `*`. Wildcards can appear at any position in the command. This configuration allows npm and git commit commands while blocking git push:

262* `WebFetch(domain:*.example.com)` matches any subdomain at any depth, such as `api.example.com` or `a.b.example.com`, but not `example.com` itself283* `WebFetch(domain:*.example.com)` matches any subdomain at any depth, such as `api.example.com` or `a.b.example.com`, but not `example.com` itself

263* `WebFetch(domain:*)` matches every domain and is equivalent to a bare `WebFetch` rule284* `WebFetch(domain:*)` matches every domain and is equivalent to a bare `WebFetch` rule

264 285 

265A `*` matches across a `.` only as a leading `*.` or as the entire pattern. Elsewhere it stays within one label, so `WebFetch(domain:github.*)` matches `github.io` but not `github.evil.com`, a domain an attacker could register. When an exact rule and a wildcard rule in the same allow, ask, or deny list both match a hostname, the exact rule is the one matched. Evaluation order is unchanged: deny rules still run before ask and allow rules regardless of specificity.286In any position other than a leading `*.` or a bare `*`, the wildcard matches only the text between two dots. `WebFetch(domain:example.*)` matches `example.org`, where `*` becomes `org`, but not `example.evil.com`, where `*` would have to become `evil.com` and cross a dot. This keeps a trailing wildcard from matching domains an attacker could register.

266 287 

267### MCP288### MCP

268 289 

335| Configuration | Loaded from `--add-dir` |356| Configuration | Loaded from `--add-dir` |

336| :--------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- |357| :--------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- |

337| [Skills](/en/skills) in `.claude/skills/` | Yes, with live reload |358| [Skills](/en/skills) in `.claude/skills/` | Yes, with live reload |

359| [Subagents](/en/sub-agents) in `.claude/agents/` | Yes |

338| Plugin settings in `.claude/settings.json` | `enabledPlugins` and `extraKnownMarketplaces` only |360| Plugin settings in `.claude/settings.json` | `enabledPlugins` and `extraKnownMarketplaces` only |

339| [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 |361| [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 |

340 362 

341Subagents, 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:363Commands 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:

342 364 

343* **User-level configuration**: place files in `~/.claude/agents/`, `~/.claude/output-styles/`, or `~/.claude/settings.json` to make them available in every project365* **User-level configuration**: place files in `~/.claude/agents/`, `~/.claude/output-styles/`, or `~/.claude/settings.json` to make them available in every project

344* **Plugins**: package and distribute configuration as a [plugin](/en/plugins) that teams can install366* **Plugins**: package and distribute configuration as a [plugin](/en/plugins) that teams can install

29 29 

30Gate emission on an environment variable so the marker is unlikely to appear when a human runs your CLI directly, then write the tag to stderr on its own line. Choose which variable to check:30Gate emission on an environment variable so the marker is unlikely to appear when a human runs your CLI directly, then write the tag to stderr on its own line. Choose which variable to check:

31 31 

32* `CLAUDECODE`: set on every Claude Code version, so it reaches the most sessions. It is also set in tmux sessions and stdio MCP server subprocesses that Claude Code starts, and IDE extensions set it in their integrated terminals, where a human may be running your CLI directly.32* `CLAUDECODE`: set on every Claude Code version, so it reaches the most sessions. It is also set in tmux sessions and stdio MCP server subprocesses that Claude Code starts. IDE extensions also set it in their integrated terminals, where a human may be running your CLI directly.

33* {/* min-version: 2.1.172 */}`CLAUDE_CODE_CHILD_SESSION`: set only in subprocesses Claude Code itself spawns, such as tool calls, hook commands, and [status line](/en/statusline) commands, so the tag does not normally reach a human terminal. A long-lived process that was started inside a session, such as a tmux server, captures the variable, so shells later launched from that process still show the raw tag. Requires Claude Code v2.1.172 or later, so sessions on older versions miss the hint.33* {/* min-version: 2.1.172 */}`CLAUDE_CODE_CHILD_SESSION`: set only in subprocesses Claude Code itself spawns, such as tool calls, hook commands, and [status line](/en/statusline) commands, so the tag does not normally reach a human terminal. A long-lived process that was started inside a session, such as a tmux server, captures the variable, so shells later launched from that process still show the raw tag. Requires Claude Code v2.1.172 or later, so sessions on older versions miss the hint.

34 34 

35The following examples gate on `CLAUDECODE` for maximum reach and emit a hint for a plugin named `example-cli` in the official marketplace:35The following examples gate on `CLAUDECODE` for maximum reach and emit a hint for a plugin named `example-cli` in the official marketplace:

473* **`${CLAUDE_PLUGIN_ROOT}`**: use this variable in hooks and MCP server configs to reference files within the plugin's installation directory. This is necessary because plugins are copied to a cache location when installed. For dependencies or state that should survive plugin updates, use [`${CLAUDE_PLUGIN_DATA}`](/en/plugins-reference#persistent-data-directory) instead.473* **`${CLAUDE_PLUGIN_ROOT}`**: use this variable in hooks and MCP server configs to reference files within the plugin's installation directory. This is necessary because plugins are copied to a cache location when installed. For dependencies or state that should survive plugin updates, use [`${CLAUDE_PLUGIN_DATA}`](/en/plugins-reference#persistent-data-directory) instead.

474* **`strict: false`**: Since this is set to false, the plugin doesn't need its own `plugin.json`. The marketplace entry defines everything. See [Strict mode](#strict-mode) below.474* **`strict: false`**: Since this is set to false, the plugin doesn't need its own `plugin.json`. The marketplace entry defines everything. See [Strict mode](#strict-mode) below.

475 475 

476By default, a plugin's skills load from the `skills/` directory under its `source`, and any paths listed under `skills` add to that scan. The exception is a marketplace-root source such as `source: "./"`, where several plugin entries share one `skills/` folder. In that case, listing specific subdirectories under `skills` makes that list the complete set for the entry, and other directories under `skills/` do not load. Listing the `skills/` directory itself or the plugin root keeps the full scan. If none of the listed paths exist, the default scan runs instead.

477 

476### Strict mode478### Strict mode

477 479 

478The `strict` field controls whether `plugin.json` is the authority for component definitions (skills, agents, hooks, MCP servers, output styles).480The `strict` field controls whether `plugin.json` is the authority for component definitions (skills, agents, hooks, MCP servers, output styles).

508### Component path fields508### Component path fields

509 509 

510| Field | Type | Description | Example |510| Field | Type | Description | Example |

511| :---------------------- | :-------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |511| :---------------------- | :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |

512| `skills` | string\|array | Custom skill directories containing `<name>/SKILL.md` (in addition to default `skills/`) | `"./custom/skills/"` |512| `skills` | string\|array | Custom skill directories containing `<name>/SKILL.md`. Adds to the default `skills/` scan. See [Path behavior rules](#path-behavior-rules) for the marketplace-root exception | `"./custom/skills/"` |

513| `commands` | string\|array | Custom flat `.md` skill files or directories (replaces default `commands/`) | `"./custom/cmd.md"` or `["./cmd1.md"]` |513| `commands` | string\|array | Custom flat `.md` skill files or directories (replaces default `commands/`) | `"./custom/cmd.md"` or `["./cmd1.md"]` |

514| `agents` | string\|array | Custom agent files (replaces default `agents/`) | `"./custom/agents/reviewer.md"` |514| `agents` | string\|array | Custom agent files (replaces default `agents/`) | `"./custom/agents/reviewer.md"` |

515| `hooks` | string\|array\|object | Hook config paths or inline config | `"./my-extra-hooks.json"` |515| `hooks` | string\|array\|object | Hook config paths or inline config | `"./my-extra-hooks.json"` |

599Whether a custom path replaces or extends the plugin's default directory depends on the field:599Whether a custom path replaces or extends the plugin's default directory depends on the field:

600 600 

601* **Replaces the default**: `commands`, `agents`, `outputStyles`, `experimental.themes`, `experimental.monitors`. For example, when the manifest specifies `commands`, the default `commands/` directory is not scanned. To keep the default and add more, list it explicitly: `"commands": ["./commands/", "./extras/"]`601* **Replaces the default**: `commands`, `agents`, `outputStyles`, `experimental.themes`, `experimental.monitors`. For example, when the manifest specifies `commands`, the default `commands/` directory is not scanned. To keep the default and add more, list it explicitly: `"commands": ["./commands/", "./extras/"]`

602* **Adds to the default**: `skills`. The default `skills/` directory is always scanned, and directories listed in `skills` are loaded alongside it602* **Adds to the default**: `skills`. The default `skills/` directory is always scanned, and directories listed in `skills` are loaded alongside it. Exception: for a [marketplace entry whose `source` resolves to the marketplace root](/en/plugin-marketplaces#advanced-plugin-entries), declaring specific subdirectories replaces the scan

603* **Own merge rules**: [hooks](#hooks), [MCP servers](#mcp-servers), and [LSP servers](#lsp-servers). See each section for how multiple sources combine603* **Own merge rules**: [hooks](#hooks), [MCP servers](#mcp-servers), and [LSP servers](#lsp-servers). See each section for how multiple sources combine

604 604 

605When 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.605When 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.

74 ```74 ```

75 75 

76 This gives you a full interactive session in your terminal that you can also control from claude.ai or the Claude app. Unlike `claude remote-control` (server mode), you can type messages locally while the session is also available remotely.76 This gives you a full interactive session in your terminal that you can also control from claude.ai or the Claude app. Unlike `claude remote-control` (server mode), you can type messages locally while the session is also available remotely.

77 

78 As of v2.1.162, a Remote Control indicator stays in the footer below the input box while the connection is up. {/* min-version: 2.1.172 */}From v2.1.172, the indicator reads `/rc active` and is hidden when the terminal is too narrow to fit it; earlier versions always show `Remote Control active`. The indicator text is a link to the session on claude.ai, so you can reopen it from the terminal at any time. Select the indicator with the down arrow key and press Enter to open a status panel with the session URL and a QR code.

79 </Tab>77 </Tab>

80 78 

81 <Tab title="From an existing session">79 <Tab title="From an existing session">

93 91 

94 This starts a Remote Control session that carries over your current conversation history.92 This starts a Remote Control session that carries over your current conversation history.

95 93 

96 As of v2.1.162, a Remote Control indicator appears in the footer below the input box and stays visible while the connection is up. {/* min-version: 2.1.172 */}From v2.1.172, the indicator reads `/rc active` and is hidden when the terminal is too narrow to fit it; earlier versions always show `Remote Control active`. The indicator text is a link to the session on claude.ai. Select it with the down arrow key and press Enter, or run `/remote-control` again, to open a status panel with the session URL and a QR code you can use to [connect from another device](#connect-from-another-device).

97 

98 The `--verbose`, `--sandbox`, and `--no-sandbox` flags are not available with this command.94 The `--verbose`, `--sandbox`, and `--no-sandbox` flags are not available with this command.

99 </Tab>95 </Tab>

100 96 

113 </Tab>109 </Tab>

114</Tabs>110</Tabs>

115 111 

112### Check connection status

113 

114In an interactive terminal session, a `/rc active` indicator sits in the footer below the input box while the connection is up, and is hidden if the terminal is too narrow to fit it. The indicator text is a link to the session on claude.ai. Select it with the down arrow key and press Enter, or run `/remote-control` again, to open a status panel with the session URL and a QR code you can use to [connect from another device](#connect-from-another-device).

115 

116If the connection fails, the indicator turns red and reads `/rc failed`. Select it with the down arrow key and press Enter to see the failure reason and a dismiss option, or run `/remote-control` again to retry.

117 

116### Connect from another device118### Connect from another device

117 119 

118Once a Remote Control session is active, you have a few ways to connect from another device:120Once a Remote Control session is active, you have a few ways to connect from another device:

1283. The last meaningful message in existing conversation history1303. The last meaningful message in existing conversation history

1294. An auto-generated name like `myhost-graceful-unicorn`, where `myhost` is your machine's hostname or the prefix you set with `--remote-control-session-name-prefix`1314. An auto-generated name like `myhost-graceful-unicorn`, where `myhost` is your machine's hostname or the prefix you set with `--remote-control-session-name-prefix`

130 132 

131If you didn't set an explicit name, the title updates to reflect your prompt once you send one. Renaming a session from claude.ai or the Claude app also updates the local title shown in `claude --resume`.133If you didn't set an explicit name, the title updates to reflect your prompt once you send one. {/* min-version: 2.1.176 */}As of Claude Code v2.1.176, auto-generated titles match the language of your conversation, or the [`language`](/en/settings#available-settings) setting if one is configured. Renaming a session from claude.ai or the Claude app also updates the local title shown in `claude --resume`.

132 134 

133If the environment already has an active session, you'll be asked whether to continue it or start a new one.135If the environment already has an active session, you'll be asked whether to continue it or start a new one.

134 136 

156 158 

157When Remote Control is active, Claude can send push notifications to your phone.159When Remote Control is active, Claude can send push notifications to your phone.

158 160 

159Claude decides when to push. It typically sends one when a long-running task finishes or when it needs a decision from you to continue. You can also request a push in your prompt, for example `notify me when the tests finish`. Beyond the on/off toggle below, there is no per-event configuration.161Claude decides when to push. It typically sends one when a long-running task finishes or when it needs a decision from you to continue. You can also request a push in your prompt, for example `notify me when the tests finish`. Beyond the two on/off toggles below, there is no per-event configuration.

160 162 

161<Note>163<Note>

162 Mobile push notifications require Claude Code v2.1.110 or later.164 Mobile push notifications require Claude Code v2.1.110 or later.

178 </Step>180 </Step>

179 181 

180 <Step title="Enable push in Claude Code">182 <Step title="Enable push in Claude Code">

181 In your terminal, run `/config` and enable **Push when Claude decides**.183 In your terminal, run `/config` and enable **Push when Claude decides** for proactive notifications, **Push when actions required** for permission prompts and questions, or both.

182 </Step>184 </Step>

183</Steps>185</Steps>

184 186 

212 214 

213### "Remote Control is not yet enabled for your account"215### "Remote Control is not yet enabled for your account"

214 216 

215The eligibility check can fail with certain environment variables present:217The Remote Control rollout has not reached your account, or your cached entitlements are out of date. If you recently changed plans, run `claude auth logout` then `claude auth login` to refresh them. Run `claude doctor` to see which individual eligibility check failed. Environment-variable conflicts, unreachable checks, and organization policy each produce their own message, so this error means the rollout gate itself.

216 218 

217* `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` or `DISABLE_TELEMETRY`: unset them and try again.219### "Couldn't verify Remote Control eligibility"

218* `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, or `CLAUDE_CODE_USE_FOUNDRY`: Remote Control requires claude.ai authentication and does not work with third-party providers.

219 220 

220If none of these are set, run `/logout` then `/login` to refresh.221Claude Code could not reach the feature-flag service to check whether Remote Control is enabled for your account, typically because you are offline or a proxy is blocking the request. Retry once you have network access, or run `claude doctor` for details. The related message "Couldn't verify your organization's Remote Control policy" has the same cause and the same fix. Both messages were added in v2.1.178.

221 222 

222### "Remote Control is disabled by your organization's policy"223### "Remote Control is disabled by your organization's policy"

223 224 

195`settings.json` supports a number of options:195`settings.json` supports a number of options:

196 196 

197| Key | Description | Example |197| Key | Description | Example |

198| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------- |198| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------ |

199| `advisorModel` | {/* min-version: 2.1.98 */}Model for the server-side [advisor tool](/en/advisor). Accepts a model alias such as `"opus"`, `"sonnet"`, or `"fable"` ({/* min-version: 2.1.170 */}v2.1.170+), or a full model ID. Written automatically when you run `/advisor`. Unset to disable the advisor. Requires Claude Code v2.1.98 or later | `"opus"` |199| `advisorModel` | {/* min-version: 2.1.98 */}Model for the server-side [advisor tool](/en/advisor). Accepts a model alias such as `"opus"`, `"sonnet"`, or `"fable"` ({/* min-version: 2.1.170 */}v2.1.170+), or a full model ID. Written automatically when you run `/advisor`. Unset to disable the advisor. Requires Claude Code v2.1.98 or later | `"opus"` |

200| `agent` | Run the main thread as a named subagent, and set the default agent for sessions dispatched from `claude agents`. Applies that subagent's system prompt, tool restrictions, and model. See [Invoke subagents explicitly](/en/sub-agents#invoke-subagents-explicitly) | `"code-reviewer"` |200| `agent` | Run the main thread as a named subagent, and set the default agent for sessions dispatched from `claude agents`. Applies that subagent's system prompt, tool restrictions, and model. See [Invoke subagents explicitly](/en/sub-agents#invoke-subagents-explicitly) | `"code-reviewer"` |

201| `agentPushNotifEnabled` | {/* min-version: 2.1.119 */}When [Remote Control](/en/remote-control) is connected, allow Claude to send proactive push notifications to your phone, for example when a long task finishes. Default: `false`. Appears in `/config` as **Push when Claude decides**. See [Mobile push notifications](/en/remote-control#mobile-push-notifications). Requires Claude Code v2.1.119 or later | `true` |

201| `allowAllClaudeAiMcps` | (Managed settings only) Load claude.ai connectors alongside a deployed `managed-mcp.json`, which otherwise takes exclusive control and suppresses them. See [Managed MCP configuration](/en/managed-mcp) | `true` |202| `allowAllClaudeAiMcps` | (Managed settings only) Load claude.ai connectors alongside a deployed `managed-mcp.json`, which otherwise takes exclusive control and suppresses them. See [Managed MCP configuration](/en/managed-mcp) | `true` |

202| `allowedChannelPlugins` | (Managed settings only) Allowlist of channel plugins that may push messages. Replaces the default Anthropic allowlist when set. Undefined = fall back to the default, empty array = block all channel plugins. Requires `channelsEnabled: true`. See [Restrict which channel plugins can run](/en/channels#restrict-which-channel-plugins-can-run) | `[{ "marketplace": "claude-plugins-official", "plugin": "telegram" }]` |203| `allowedChannelPlugins` | (Managed settings only) Allowlist of channel plugins that may push messages. Replaces the default Anthropic allowlist when set. Undefined = fall back to the default, empty array = block all channel plugins. Requires `channelsEnabled: true`. See [Restrict which channel plugins can run](/en/channels#restrict-which-channel-plugins-can-run) | `[{ "marketplace": "claude-plugins-official", "plugin": "telegram" }]` |

203| `allowedHttpHookUrls` | Allowlist of URL patterns that HTTP hooks may target. Supports `*` as a wildcard. When set, hooks with non-matching URLs are blocked. Undefined = no restriction, empty array = block all HTTP hooks. Arrays merge across settings sources. See [Hook configuration](#hook-configuration) | `["https://hooks.example.com/*"]` |204| `allowedHttpHookUrls` | Allowlist of URL patterns that HTTP hooks may target. Supports `*` as a wildcard. When set, hooks with non-matching URLs are blocked. Undefined = no restriction, empty array = block all HTTP hooks. Arrays merge across settings sources. See [Hook configuration](#hook-configuration) | `["https://hooks.example.com/*"]` |

208| `alwaysThinkingEnabled` | Enable [extended thinking](/en/model-config#extended-thinking) by default for all sessions. Typically configured via the `/config` command rather than editing directly. To force thinking off regardless of this setting, set [`MAX_THINKING_TOKENS=0`](/en/env-vars) in `env`, which disables thinking on the Anthropic API except on Fable 5, which cannot have thinking turned off. On [third-party providers](/en/third-party-integrations) this omits the `thinking` parameter instead, and adaptive-reasoning models may still think | `true` |209| `alwaysThinkingEnabled` | Enable [extended thinking](/en/model-config#extended-thinking) by default for all sessions. Typically configured via the `/config` command rather than editing directly. To force thinking off regardless of this setting, set [`MAX_THINKING_TOKENS=0`](/en/env-vars) in `env`, which disables thinking on the Anthropic API except on Fable 5, which cannot have thinking turned off. On [third-party providers](/en/third-party-integrations) this omits the `thinking` parameter instead, and adaptive-reasoning models may still think | `true` |

209| `apiKeyHelper` | Custom script, to be executed in `/bin/sh`, to generate an auth value. This value will be sent as `X-Api-Key` and `Authorization: Bearer` headers for model requests. Set the refresh interval with [`CLAUDE_CODE_API_KEY_HELPER_TTL_MS`](/en/env-vars) | `/bin/generate_temp_api_key.sh` |210| `apiKeyHelper` | Custom script, to be executed in `/bin/sh`, to generate an auth value. This value will be sent as `X-Api-Key` and `Authorization: Bearer` headers for model requests. Set the refresh interval with [`CLAUDE_CODE_API_KEY_HELPER_TTL_MS`](/en/env-vars) | `/bin/generate_temp_api_key.sh` |

210| `attribution` | Customize attribution for git commits and pull requests. See [Attribution settings](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |211| `attribution` | Customize attribution for git commits and pull requests. See [Attribution settings](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |

212| `autoCompactEnabled` | {/* min-version: 2.1.119 */}Automatically compact the conversation when context approaches the limit. Default: `true`. Appears in `/config` as **Auto-compact**. To disable via environment variable, set [`DISABLE_AUTO_COMPACT`](/en/env-vars) in `env` | `false` |

211| `autoMemoryDirectory` | Custom directory for [auto memory](/en/memory#storage-location) storage. Accepts an absolute path or a `~/`-prefixed path. From project or local settings, this is honored only after you accept the workspace trust dialog, since a cloned repository can supply this file | `"~/my-memory-dir"` |213| `autoMemoryDirectory` | Custom directory for [auto memory](/en/memory#storage-location) storage. Accepts an absolute path or a `~/`-prefixed path. From project or local settings, this is honored only after you accept the workspace trust dialog, since a cloned repository can supply this file | `"~/my-memory-dir"` |

212| `autoMemoryEnabled` | Enable [auto memory](/en/memory#enable-or-disable-auto-memory). When `false`, Claude does not read from or write to the auto memory directory. Default: `true`. You can also toggle this with `/memory` during a session. To disable via environment variable, set [`CLAUDE_CODE_DISABLE_AUTO_MEMORY`](/en/env-vars) in `env` | `false` |214| `autoMemoryEnabled` | Enable [auto memory](/en/memory#enable-or-disable-auto-memory). When `false`, Claude does not read from or write to the auto memory directory. Default: `true`. You can also toggle this with `/memory` during a session. To disable via environment variable, set [`CLAUDE_CODE_DISABLE_AUTO_MEMORY`](/en/env-vars) in `env` | `false` |

213| `autoMode` | Customize what the [auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) classifier blocks and allows. Contains `environment`, `allow`, `soft_deny`, and `hard_deny` arrays of prose rules. Include the literal string `"$defaults"` in an array to inherit the built-in rules at that position. See [Configure auto mode](/en/auto-mode-config). Not read from shared project settings | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |215| `autoMode` | Customize what the [auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) classifier blocks and allows. Contains `environment`, `allow`, `soft_deny`, and `hard_deny` arrays of prose rules. Include the literal string `"$defaults"` in an array to inherit the built-in rules at that position. See [Configure auto mode](/en/auto-mode-config). Not read from shared project settings | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |

214| `autoScrollEnabled` | In [fullscreen rendering](/en/fullscreen), follow new output to the bottom of the conversation. Default: `true`. Appears in `/config` as **Auto-scroll**. Permission prompts still scroll into view when this is off | `false` |216| `autoScrollEnabled` | In [fullscreen rendering](/en/fullscreen), follow new output to the bottom of the conversation. Default: `true`. Appears in `/config` as **Auto-scroll**. Permission prompts still scroll into view when this is off | `false` |

215| `autoUpdatesChannel` | Release channel to follow for updates. Use `"stable"` for a version that is typically about one week old and skips versions with major regressions, or `"latest"` (default) for the most recent release. To disable auto-updates entirely, set [`DISABLE_AUTOUPDATER`](/en/setup#disable-auto-updates) in `env` | `"stable"` |217| `autoUpdatesChannel` | Release channel to follow for updates. Use `"stable"` for a version that is typically about one week old and skips versions with major regressions, or `"latest"` (default) for the most recent release. To disable auto-updates entirely, set [`DISABLE_AUTOUPDATER`](/en/setup#disable-auto-updates) in `env` | `"stable"` |

216| `availableModels` | Restrict which models users can select for the main session, [subagents](/en/sub-agents), and the [advisor](/en/advisor). See [Restrict model selection](/en/model-config#restrict-model-selection) | `["sonnet", "haiku"]` |218| `availableModels` | Restrict which models users can select for the main session, [subagents](/en/sub-agents), and the [advisor](/en/advisor). See [Restrict model selection](/en/model-config#restrict-model-selection). See `enforceAvailableModels` to also constrain Default | `["sonnet", "haiku"]` |

217| `awaySummaryEnabled` | Show a one-line session recap when you return to the terminal after a few minutes away. Set to `false` or turn off Session recap in `/config` to disable. Same as [`CLAUDE_CODE_ENABLE_AWAY_SUMMARY`](/en/env-vars) | `true` |219| `awaySummaryEnabled` | Show a one-line session recap when you return to the terminal after a few minutes away. Set to `false` or turn off Session recap in `/config` to disable. Same as [`CLAUDE_CODE_ENABLE_AWAY_SUMMARY`](/en/env-vars) | `true` |

218| `awsAuthRefresh` | Custom script that modifies the `.aws` directory (see [advanced credential configuration](/en/amazon-bedrock#advanced-credential-configuration)) | `aws sso login --profile myprofile` |220| `awsAuthRefresh` | Custom script that modifies the `.aws` directory (see [advanced credential configuration](/en/amazon-bedrock#advanced-credential-configuration)) | `aws sso login --profile myprofile` |

219| `awsCredentialExport` | Custom script that outputs JSON with AWS credentials (see [advanced credential configuration](/en/amazon-bedrock#advanced-credential-configuration)) | `/bin/generate_aws_grant.sh` |221| `awsCredentialExport` | Custom script that outputs JSON with AWS credentials (see [advanced credential configuration](/en/amazon-bedrock#advanced-credential-configuration)) | `/bin/generate_aws_grant.sh` |

243| `fallbackModel` | Fallback model(s) to try in order when the primary model is overloaded or unavailable. Claude Code switches to the next available model in the chain for the rest of the turn and shows a notice. `"default"` expands to the default model. Chains are capped at three models; extra entries are ignored. Unlike most array settings, this key does not merge across settings files: the highest-precedence file that defines it supplies the entire chain. The [`--fallback-model`](/en/cli-reference#cli-flags) flag overrides this for one session. See [Fallback model chains](/en/model-config#fallback-model-chains) | `["claude-sonnet-4-6", "claude-haiku-4-5"]` |245| `fallbackModel` | Fallback model(s) to try in order when the primary model is overloaded or unavailable. Claude Code switches to the next available model in the chain for the rest of the turn and shows a notice. `"default"` expands to the default model. Chains are capped at three models; extra entries are ignored. Unlike most array settings, this key does not merge across settings files: the highest-precedence file that defines it supplies the entire chain. The [`--fallback-model`](/en/cli-reference#cli-flags) flag overrides this for one session. See [Fallback model chains](/en/model-config#fallback-model-chains) | `["claude-sonnet-4-6", "claude-haiku-4-5"]` |

244| `fastModePerSessionOptIn` | When `true`, fast mode does not persist across sessions. Each session starts with fast mode off, requiring users to enable it with `/fast`. The user's fast mode preference is still saved. See [Require per-session opt-in](/en/fast-mode#require-per-session-opt-in) | `true` |246| `fastModePerSessionOptIn` | When `true`, fast mode does not persist across sessions. Each session starts with fast mode off, requiring users to enable it with `/fast`. The user's fast mode preference is still saved. See [Require per-session opt-in](/en/fast-mode#require-per-session-opt-in) | `true` |

245| `feedbackSurveyRate` | Probability (0–1) that the [session quality survey](/en/data-usage#session-quality-surveys) appears when eligible. Set to `0` to suppress entirely, or set [`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY`](/en/env-vars) in `env`. Useful when using Bedrock, Vertex, or Foundry where the default sample rate does not apply | `0.05` |247| `feedbackSurveyRate` | Probability (0–1) that the [session quality survey](/en/data-usage#session-quality-surveys) appears when eligible. Set to `0` to suppress entirely, or set [`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY`](/en/env-vars) in `env`. Useful when using Bedrock, Vertex, or Foundry where the default sample rate does not apply | `0.05` |

248| `fileCheckpointingEnabled` | {/* min-version: 2.1.119 */}Snapshot files before each edit so [`/rewind`](/en/checkpointing) can restore them. Default: `true`. Appears in `/config` as **Rewind code (checkpoints)**. To disable via environment variable, set [`CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING`](/en/env-vars) in `env` | `false` |

246| `fileSuggestion` | Configure a custom script for `@` file autocomplete. See [File suggestion settings](#file-suggestion-settings) | `{"type": "command", "command": "~/.claude/file-suggestion.sh"}` |249| `fileSuggestion` | Configure a custom script for `@` file autocomplete. See [File suggestion settings](#file-suggestion-settings) | `{"type": "command", "command": "~/.claude/file-suggestion.sh"}` |

250| `footerLinksRegexes` | {/* min-version: 2.1.176 */}Render extra clickable badges in the footer when a regex matches turn output. Each entry has a `pattern`, a `url` template with `{name}` placeholders filled from named capture groups, and an optional `label`. Read from user, `--settings` flag, and managed settings only. See [Footer link badges](#footer-link-badges) for URL constraints, scheme allowlist, and limits. Requires Claude Code v2.1.176 or later | `[{"type": "regex", "pattern": "\\b(?<key>PROJ-\\d+)\\b", "url": "https://issues.example.com/browse/{key}", "label": "{key}"}]` |

247| `forceLoginMethod` | Use `claudeai` to restrict login to Claude.ai accounts, `console` to restrict login to Claude Console accounts. When set in managed settings, sessions authenticated by `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, or `apiKeyHelper` are blocked at startup, since neither value can be satisfied without first-party OAuth. Third-party provider sessions such as Bedrock, Vertex, and Foundry are not blocked: they authenticate against your cloud provider rather than Anthropic | `claudeai` |251| `forceLoginMethod` | Use `claudeai` to restrict login to Claude.ai accounts, `console` to restrict login to Claude Console accounts. When set in managed settings, sessions authenticated by `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, or `apiKeyHelper` are blocked at startup, since neither value can be satisfied without first-party OAuth. Third-party provider sessions such as Bedrock, Vertex, and Foundry are not blocked: they authenticate against your cloud provider rather than Anthropic | `claudeai` |

248| `forceLoginOrgUUID` | Require login to belong to a specific Anthropic organization. Accepts a single UUID string, which also pre-selects that organization during login, or an array of UUIDs where any listed organization is accepted without pre-selection. When set in managed settings, login fails if the authenticated account does not belong to a listed organization, and sessions authenticated by `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, or `apiKeyHelper` are blocked at startup since organization membership cannot be verified for them. Third-party provider sessions such as Bedrock, Vertex, and Foundry are not blocked: use your cloud IAM to restrict which cloud accounts can be used. An empty array fails closed and blocks login with a misconfiguration message | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` or `["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"]` |252| `forceLoginOrgUUID` | Require login to belong to a specific Anthropic organization. Accepts a single UUID string, which also pre-selects that organization during login, or an array of UUIDs where any listed organization is accepted without pre-selection. When set in managed settings, login fails if the authenticated account does not belong to a listed organization, and sessions authenticated by `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, or `apiKeyHelper` are blocked at startup since organization membership cannot be verified for them. Third-party provider sessions such as Bedrock, Vertex, and Foundry are not blocked: use your cloud IAM to restrict which cloud accounts can be used. An empty array fails closed and blocks login with a misconfiguration message | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` or `["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"]` |

249| `forceRemoteSettingsRefresh` | (Managed settings only) Block CLI startup until remote managed settings are freshly fetched from the server. If the fetch fails, the CLI exits rather than continuing with cached or no settings. When not set, startup continues without waiting for remote settings. See [fail-closed enforcement](/en/server-managed-settings#enforce-fail-closed-startup) | `true` |253| `forceRemoteSettingsRefresh` | (Managed settings only) Block CLI startup until remote managed settings are freshly fetched from the server. If the fetch fails, the CLI exits rather than continuing with cached or no settings. When not set, startup continues without waiting for remote settings. See [fail-closed enforcement](/en/server-managed-settings#enforce-fail-closed-startup) | `true` |

252| `httpHookAllowedEnvVars` | Allowlist of environment variable names HTTP hooks may interpolate into headers. When set, each hook's effective `allowedEnvVars` is the intersection with this list. Undefined = no restriction. Arrays merge across settings sources. See [Hook configuration](#hook-configuration) | `["MY_TOKEN", "HOOK_SECRET"]` |256| `httpHookAllowedEnvVars` | Allowlist of environment variable names HTTP hooks may interpolate into headers. When set, each hook's effective `allowedEnvVars` is the intersection with this list. Undefined = no restriction. Arrays merge across settings sources. See [Hook configuration](#hook-configuration) | `["MY_TOKEN", "HOOK_SECRET"]` |

253| `includeCoAuthoredBy` | **Deprecated**: Use `attribution` instead. Whether to include the `co-authored-by Claude` byline in git commits and pull requests (default: `true`) | `false` |257| `includeCoAuthoredBy` | **Deprecated**: Use `attribution` instead. Whether to include the `co-authored-by Claude` byline in git commits and pull requests (default: `true`) | `false` |

254| `includeGitInstructions` | Include built-in commit and PR workflow instructions and the git status snapshot in Claude's system prompt (default: `true`). Set to `false` to remove both, for example when using your own git workflow skills. The `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` environment variable takes precedence over this setting when set | `false` |258| `includeGitInstructions` | Include built-in commit and PR workflow instructions and the git status snapshot in Claude's system prompt (default: `true`). Set to `false` to remove both, for example when using your own git workflow skills. The `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` environment variable takes precedence over this setting when set | `false` |

255| `language` | Configure Claude's preferred response language (e.g., `"japanese"`, `"spanish"`, `"french"`). Claude will respond in this language by default. Also sets the [voice dictation](/en/voice-dictation#change-the-dictation-language) language | `"japanese"` |259| `inputNeededNotifEnabled` | {/* min-version: 2.1.119 */}When [Remote Control](/en/remote-control) is connected, send a push notification to your phone when a permission prompt or question is waiting for your input. Default: `false`. Appears in `/config` as **Push when actions required**. See [Mobile push notifications](/en/remote-control#mobile-push-notifications). Requires Claude Code v2.1.119 or later | `true` |

260| `language` | Configure Claude's preferred response language (e.g., `"japanese"`, `"spanish"`, `"french"`). Claude will respond in this language by default. Also sets the language for [voice dictation](/en/voice-dictation#change-the-dictation-language) and auto-generated session titles. {/* min-version: 2.1.176 */}As of v2.1.176, when not set, session titles match the language of your conversation | `"japanese"` |

256| `maxSkillDescriptionChars` | {/* min-version: 2.1.105 */}Per-skill character cap on the combined `description` and `when_to_use` text in the [skill listing](/en/skills#skill-descriptions-are-cut-short) Claude sees each turn (default: `1536`). Text longer than this is truncated. Raise to keep long descriptions intact at the cost of more context per turn; lower to fit more skills under [`skillListingBudgetFraction`](#available-settings). Requires Claude Code v2.1.105 or later | `2048` |261| `maxSkillDescriptionChars` | {/* min-version: 2.1.105 */}Per-skill character cap on the combined `description` and `when_to_use` text in the [skill listing](/en/skills#skill-descriptions-are-cut-short) Claude sees each turn (default: `1536`). Text longer than this is truncated. Raise to keep long descriptions intact at the cost of more context per turn; lower to fit more skills under [`skillListingBudgetFraction`](#available-settings). Requires Claude Code v2.1.105 or later | `2048` |

257| `minimumVersion` | Floor that prevents background auto-updates and `claude update` from installing a version below this one. Switching from the `"latest"` channel to `"stable"` via `/config` prompts you to stay on the current version or allow the downgrade. Choosing to stay sets this value. Also useful in [managed settings](/en/permissions#managed-settings) to pin an organization-wide minimum. For a hard floor that blocks startup entirely, see `requiredMinimumVersion` | `"2.1.100"` |262| `minimumVersion` | Floor that prevents background auto-updates and `claude update` from installing a version below this one. Switching from the `"latest"` channel to `"stable"` via `/config` prompts you to stay on the current version or allow the downgrade. Choosing to stay sets this value. Also useful in [managed settings](/en/permissions#managed-settings) to pin an organization-wide minimum. For a hard floor that blocks startup entirely, see `requiredMinimumVersion` | `"2.1.100"` |

258| `model` | Override the default model to use for Claude Code. `--model` and [`ANTHROPIC_MODEL`](/en/model-config#environment-variables) override this for one session | `"claude-sonnet-4-6"` |263| `model` | Override the default model to use for Claude Code. `--model` and [`ANTHROPIC_MODEL`](/en/model-config#environment-variables) override this for one session | `"claude-sonnet-4-6"` |

287| `syntaxHighlightingDisabled` | Disable syntax highlighting in diffs, code blocks, and file previews | `true` |292| `syntaxHighlightingDisabled` | Disable syntax highlighting in diffs, code blocks, and file previews | `true` |

288| `teammateMode` | How [agent team](/en/agent-teams) teammates display: `auto` (split panes when running inside tmux or iTerm2, in-process otherwise), `in-process`, or `tmux` (split panes using tmux or iTerm2, detected from your terminal). `--teammate-mode` overrides this for one session. See [choose a display mode](/en/agent-teams#choose-a-display-mode) | `"in-process"` |293| `teammateMode` | How [agent team](/en/agent-teams) teammates display: `auto` (split panes when running inside tmux or iTerm2, in-process otherwise), `in-process`, or `tmux` (split panes using tmux or iTerm2, detected from your terminal). `--teammate-mode` overrides this for one session. See [choose a display mode](/en/agent-teams#choose-a-display-mode) | `"in-process"` |

289| `terminalProgressBarEnabled` | Show the terminal progress bar in supported terminals: ConEmu, Ghostty 1.2.0+, and iTerm2 3.6.6+. Default: `true`. Appears in `/config` as **Terminal progress bar** | `false` |294| `terminalProgressBarEnabled` | Show the terminal progress bar in supported terminals: ConEmu, Ghostty 1.2.0+, and iTerm2 3.6.6+. Default: `true`. Appears in `/config` as **Terminal progress bar** | `false` |

295| `theme` | {/* min-version: 2.1.119 */}Color theme for the interface: `"auto"`, `"dark"`, `"light"`, `"dark-daltonized"`, `"light-daltonized"`, `"dark-ansi"`, `"light-ansi"`, or a custom theme reference such as `"custom:<slug>"` or `"custom:<plugin-name>:<slug>"`. Default: `"dark"`. See [Create a custom theme](/en/terminal-config#create-a-custom-theme). Appears in `/config` as **Theme** | `"dark"` |

290| `tui` | Terminal UI renderer. Use `"fullscreen"` for the flicker-free [alt-screen renderer](/en/fullscreen) with virtualized scrollback. Use `"default"` for the classic main-screen renderer. Set via `/tui`. You can also set the [`CLAUDE_CODE_NO_FLICKER`](/en/env-vars) environment variable. Background sessions opened from [agent view](/en/agent-view) always use the fullscreen renderer regardless of this setting | `"fullscreen"` |296| `tui` | Terminal UI renderer. Use `"fullscreen"` for the flicker-free [alt-screen renderer](/en/fullscreen) with virtualized scrollback. Use `"default"` for the classic main-screen renderer. Set via `/tui`. You can also set the [`CLAUDE_CODE_NO_FLICKER`](/en/env-vars) environment variable. Background sessions opened from [agent view](/en/agent-view) always use the fullscreen renderer regardless of this setting | `"fullscreen"` |

291| `ultracode` | Turn on [ultracode](/en/workflows#let-claude-decide-with-ultracode) for the session. Session-only and not read from `settings.json`. Set through `/effort ultracode`, `--settings`, or an Agent SDK control request | `true` |297| `ultracode` | Turn on [ultracode](/en/workflows#let-claude-decide-with-ultracode) for the session. Session-only and not read from `settings.json`. Set through `/effort ultracode`, `--settings`, or an Agent SDK control request | `true` |

292| `useAutoModeDuringPlan` | Whether plan mode uses auto mode semantics when auto mode is available. Default: `true`. Not read from shared project settings. Appears in `/config` as "Use auto mode during plan" | `false` |298| `useAutoModeDuringPlan` | Whether plan mode uses auto mode semantics when auto mode is available. Default: `true`. Not read from shared project settings. Appears in `/config` as "Use auto mode during plan" | `false` |

299| `verbose` | {/* min-version: 2.1.119 */}Show full tool output instead of truncated summaries. Default: `false`. Appears in `/config` as **Verbose output**. The `--verbose` flag overrides this for one session | `true` |

293| `viewMode` | Default transcript view mode on startup: `"default"`, `"verbose"`, or `"focus"`. Overrides the sticky `/focus` selection when set. The `--verbose` flag overrides this for one session | `"verbose"` |300| `viewMode` | Default transcript view mode on startup: `"default"`, `"verbose"`, or `"focus"`. Overrides the sticky `/focus` selection when set. The `--verbose` flag overrides this for one session | `"verbose"` |

294| `voice` | [Voice dictation](/en/voice-dictation) settings: `enabled` turns dictation on, `mode` selects `"hold"` or `"tap"`, and `autoSubmit` sends the prompt on key release in hold mode. Written automatically when you run `/voice`. Requires a Claude.ai account | `{ "enabled": true, "mode": "tap" }` |301| `voice` | [Voice dictation](/en/voice-dictation) settings: `enabled` turns dictation on, `mode` selects `"hold"` or `"tap"`, and `autoSubmit` sends the prompt on key release in hold mode. Written automatically when you run `/voice`. Requires a Claude.ai account | `{ "enabled": true, "mode": "tap" }` |

295| `voiceEnabled` | Legacy alias for `voice.enabled`. Prefer the `voice` object | `true` |302| `voiceEnabled` | Legacy alias for `voice.enabled`. Prefer the `voice` object | `true` |

302These settings are stored in `~/.claude.json` rather than `settings.json`. Adding them to `settings.json` will trigger a schema validation error.309These settings are stored in `~/.claude.json` rather than `settings.json`. Adding them to `settings.json` will trigger a schema validation error.

303 310 

304<Note>311<Note>

305 Versions before v2.1.119 also store `autoScrollEnabled`, `editorMode`, `showTurnDuration`, `teammateMode`, and `terminalProgressBarEnabled` here instead of in `settings.json`.312 Versions before v2.1.119 also store a number of `/config` preference keys here instead of in `settings.json`, including `theme`, `verbose`, `editorMode`, `autoCompactEnabled`, and `preferredNotifChannel`.

306</Note>313</Note>

307 314 

308| Key | Description | Example |315| Key | Description | Example |

500your-repo-file-index --query "$query" | head -20507your-repo-file-index --query "$query" | head -20

501```508```

502 509 

510### Footer link badges

511 

512The `footerLinksRegexes` setting renders extra clickable badges in the footer below the input box. Use it to turn IDs printed by project CLIs, such as review tools and issue trackers, into session links.

513 

514Each entry's `pattern` regex is matched against turn output: tool results, including file contents and fetched pages, and Claude's own responses. `{name}` placeholders in `url` and `label` are filled from named capture groups in the pattern.

515 

516The following example renders a badge whenever an issue key like `PROJ-1234` appears in turn output. The `(?<key>...)` named group captures the key, and `{key}` substitutes it into the URL and label:

517 

518```json ~/.claude/settings.json theme={null}

519{

520 "footerLinksRegexes": [

521 {

522 "type": "regex",

523 "pattern": "\\b(?<key>PROJ-\\d+)\\b",

524 "url": "https://issues.example.com/browse/{key}",

525 "label": "{key}"

526 }

527 ]

528}

529```

530 

531With this configured, when `PROJ-1234` appears in a tool result or in Claude's reply, a `PROJ-1234` chip appears in the footer linking to `https://issues.example.com/browse/PROJ-1234`.

532 

533The following constraints apply to each entry:

534 

535| Constraint | Behavior |

536| :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

537| URL origin | Captured values are URL-encoded and the constructed URL must share the template's literal origin. A capture can fill a path segment or query value but cannot change where the link points |

538| URL length | Constructed URLs longer than 2048 characters are dropped |

539| URL scheme | Must be `https`, `http`, or a recognized editor or workspace deep-link scheme: `vscode`, `vscode-insiders`, `cursor`, `windsurf`, `zed`, `jetbrains`, `idea`, `slack`, `linear`, `notion`, `figma` |

540| Label | Defaults to the matched text and is truncated to 28 display columns |

541| Badge count | At most 5 badges render. The oldest is displaced by newer matches and `/clear` removes them |

542| Settings scope | Read from user settings, the `--settings` flag, and managed settings only. Ignored in project `.claude/settings.json` and local `.claude/settings.local.json` |

543 

544When a turn completes, Claude Code matches each entry's `pattern` regex against the turn output on the main thread, so a slow regex blocks the UI until it finishes. Nested quantifiers such as `(a+)+$` can take exponentially long against certain inputs and freeze the session, so keep each `pattern` linear and avoid nesting `+` or `*`.

545 

546Footer badges render alongside a [custom status line](/en/statusline) when one is configured; neither replaces the other. Use a status line for a script-driven row that computes its own content from session data, and footer badges to turn IDs from the conversation into links without a script.

547 

503### Hook configuration548### Hook configuration

504 549 

505These settings control which hooks are allowed to run and what HTTP hooks can access. The `allowManagedHooksOnly` setting can only be configured in [managed settings](#settings-files). The URL and env var allowlists can be set at any settings level and merge across sources.550These settings control which hooks are allowed to run and what HTTP hooks can access. The `allowManagedHooksOnly` setting can only be configured in [managed settings](#settings-files). The URL and env var allowlists can be set at any settings level and merge across sources.

583For example, if your user settings set `permissions.defaultMode` to `acceptEdits` and a project's shared settings set it to `default`, the project value applies. The example below covers how array-valued settings such as permission rules combine instead.628For example, if your user settings set `permissions.defaultMode` to `acceptEdits` and a project's shared settings set it to `default`, the project value applies. The example below covers how array-valued settings such as permission rules combine instead.

584 629 

585<Note>630<Note>

586 **Array settings merge across scopes.** When the same array-valued setting (such as `sandbox.filesystem.allowWrite` or `permissions.allow`) appears in multiple scopes, the arrays are **concatenated and deduplicated**, not replaced. This means lower-priority scopes can add entries without overriding those set by higher-priority scopes, and vice versa. For example, if managed settings set `allowWrite` to `["/opt/company-tools"]` and a user adds `["~/.kube"]`, both paths are included in the final configuration. Two exceptions: [`fallbackModel`](#available-settings), an ordered chain where position carries meaning so the highest-precedence file that defines it supplies the entire value, and {/* min-version: 2.1.175 */}as of v2.1.175, [`availableModels`](#available-settings), where a managed or policy value replaces lower-precedence entries entirely. See [Merge behavior](/en/model-config#merge-behavior).631 **Array settings merge across scopes.** When the same array-valued setting (such as `sandbox.filesystem.allowWrite` or `permissions.allow`) appears in multiple scopes, the arrays are **concatenated and deduplicated**, not replaced. This means lower-priority scopes can add entries without overriding those set by higher-priority scopes, and vice versa. For example, if managed settings set `allowWrite` to `["/opt/company-tools"]` and a user adds `["~/.kube"]`, both paths are included in the final configuration. Two exceptions: [`fallbackModel`](#available-settings) is an ordered chain where position carries meaning, so the highest-precedence file that defines it supplies the entire value. {/* min-version: 2.1.175 */}As of v2.1.175, a managed or policy [`availableModels`](#available-settings) value replaces lower-precedence entries entirely. See [Merge behavior](/en/model-config#merge-behavior).

587</Note>632</Note>

588 633 

589### Verify active settings634### Verify active settings

590 635 

591Run `/status` and check the `Setting sources` line on the **Status** tab. It lists every settings layer Claude Code loaded for this session:636Run `/status` inside Claude Code to see which settings sources are active. Inside the menu, the **Status** tab includes a `Setting sources` line that lists each layer Claude Code loaded for the current session, such as `User settings` or `Project local settings`. When [managed settings](/en/admin-setup#decide-how-settings-reach-devices) are in effect, the entry shows the delivery channel in parentheses, for example `Enterprise managed settings (remote)`, `(plist)`, `(HKLM)`, `(HKCU)`, or `(file)`. A layer appears in the list only when that source is loaded with at least one key, so an empty list means no settings sources were found.

592 

593* If a layer such as `User settings` or `Project local settings` appears, that file is being read.

594* If a layer is missing, that file was not found or contains no keys.

595 

596When [managed settings](/en/admin-setup#decide-how-settings-reach-devices) are in effect, the entry shows the delivery channel in parentheses, for example `Enterprise managed settings (remote)`, `(plist)`, `(HKLM)`, `(HKCU)`, or `(file)`.

597 637 

598If a settings file has invalid JSON or a value that fails validation, Claude Code shows a setup issues notice at startup and the **Status** tab lists the affected files. Run `/doctor` for the details of each error.638The `Setting sources` line confirms which sources are being read. It does not show which layer supplied each individual key. The **Config** tab in the same dialog is an editor for a fixed set of toggles such as theme and verbose output, not a view of your `settings.json` contents.

599 639 

600The line confirms which files are being read, not which layer supplied each individual key. The **Config** tab in the same dialog edits built-in toggles such as theme and verbose output, not your `settings.json` contents.640If a settings file contains errors, such as invalid JSON or a value that fails validation, Claude Code shows a setup issues notice at startup and `/status` lists the affected files. Run `/doctor` to see the details for each error.

601 641 

602### Key points about the configuration system642### Key points about the configuration system

603 643 

107| Project | `.claude/skills/<skill-name>/SKILL.md` | This project only |107| Project | `.claude/skills/<skill-name>/SKILL.md` | This project only |

108| Plugin | `<plugin>/skills/<skill-name>/SKILL.md` | Where plugin is enabled |108| Plugin | `<plugin>/skills/<skill-name>/SKILL.md` | Where plugin is enabled |

109 109 

110When skills share the same name across levels, enterprise overrides personal, and personal overrides project. Plugin skills use a `plugin-name:skill-name` namespace, so they cannot conflict with other levels. If you have files in `.claude/commands/`, those work the same way, but if a skill and a command share the same name, the skill takes precedence.110When skills share the same name across levels, enterprise overrides personal, and personal overrides project. A skill at any of these levels also overrides a bundled skill with the same name. For example, a `code-review` skill in your project's `.claude/skills/` replaces the bundled `/code-review`. Plugin skills use a `plugin-name:skill-name` namespace, so they cannot conflict with other levels. If you have files in `.claude/commands/`, those work the same way, but if a skill and a command share the same name, the skill takes precedence.

111 

112Skills also load from nested `.claude/skills/` directories below your working directory. When Claude reads or edits a file in a subdirectory, skills from that subdirectory's `.claude/skills/` become available. This lets a monorepo package provide its own skills that apply when working on that package, even if the session started at the repo root.

113 

114If a nested skill shares a name with another skill, both stay available. For example, with a `deploy` skill at the project root and another in `apps/web/.claude/skills/`:

115 

116* The nested one appears under a directory-qualified name, `apps/web:deploy`.

117* Its description says which directory it applies to.

118* Claude picks the variant that matches the files it is working on.

119 

120Typing `/deploy` runs the project-root skill. Type the qualified name `/apps/web:deploy` to run the nested variant explicitly.

111 121 

112<Note>122<Note>

113 Add a `.claude-plugin/plugin.json` to a skill folder and it loads as a [plugin](/en/plugins-reference#skills-directory-plugins) named `<name>@skills-dir`, so it can bundle agents, hooks, and MCP servers. In a project's `.claude/skills/`, this requires accepting the workspace trust dialog first.123 Add a `.claude-plugin/plugin.json` to a skill folder and it loads as a [plugin](/en/plugins-reference#skills-directory-plugins) named `<name>@skills-dir`, so it can bundle agents, hooks, and MCP servers. In a project's `.claude/skills/`, this requires accepting the workspace trust dialog first.

15* Work across multiple sessions and need to distinguish them15* Work across multiple sessions and need to distinguish them

16* Want git branch and status always visible16* Want git branch and status always visible

17 17 

18Claude Code can also render [footer link badges](/en/settings#footer-link-badges): clickable chips that appear in the footer when a configured regex matches text in the conversation. These are independent of the status line and do not interact with your script; configure them with the [`footerLinksRegexes`](/en/settings#footer-link-badges) setting instead.

19 

18Here's an example of a [multi-line status line](#display-multiple-lines) that displays git info on the first line and a color-coded context bar on the second.20Here's an example of a [multi-line status line](#display-multiple-lines) that displays git info on the first line and a color-coded context bar on the second.

19 21 

20<Frame>22<Frame>

176 176 

177**Project subagents** (`.claude/agents/`) are ideal for subagents specific to a codebase. Check them into version control so your team can use and improve them collaboratively.177**Project subagents** (`.claude/agents/`) are ideal for subagents specific to a codebase. Check them into version control so your team can use and improve them collaboratively.

178 178 

179Project subagents are discovered by walking up from the current working directory. Directories added with `--add-dir` [grant file access only](/en/permissions#additional-directories-grant-file-access-not-configuration) and are not scanned for subagents. To share subagents across projects, use `~/.claude/agents/` or a [plugin](/en/plugins).179Project subagents are discovered by walking up from the current working directory, so every `.claude/agents/` between there and the repository root is scanned. {/* min-version: 2.1.178 */}As of v2.1.178, when more than one of these nested directories defines the same `name`, Claude Code uses the definition closest to the working directory.

180 

181Directories added with `--add-dir` are also scanned: a `.claude/agents/` folder inside an added directory loads alongside project subagents. See [Additional directories](/en/permissions#additional-directories-grant-file-access-not-configuration) for which other configuration types load from `--add-dir`. To share subagents across projects without `--add-dir`, use `~/.claude/agents/` or a [plugin](/en/plugins).

180 182 

181**User subagents** (`~/.claude/agents/`) are personal subagents available in all your projects.183**User subagents** (`~/.claude/agents/`) are personal subagents available in all your projects.

182 184 

335 337 

336If both are set, `disallowedTools` is applied first, then `tools` is resolved against the remaining pool. A tool listed in both is removed.338If both are set, `disallowedTools` is applied first, then `tools` is resolved against the remaining pool. A tool listed in both is removed.

337 339 

340Both fields accept MCP server-level patterns in addition to exact tool names: `mcp__<server>` or `mcp__<server>__*` grants or removes every tool from the named server. In `disallowedTools`, `mcp__*` also removes every MCP tool from any server.

341 

338#### Restrict which subagents can be spawned342#### Restrict which subagents can be spawned

339 343 

340When an agent runs as the main thread with `claude --agent`, it can spawn subagents using the Agent tool. To restrict which subagent types it can spawn, use `Agent(agent_type)` syntax in the `tools` field.344When an agent runs as the main thread with `claude --agent`, it can spawn subagents using the Agent tool. To restrict which subagent types it can spawn, use `Agent(agent_type)` syntax in the `tools` field.

852## Fork the current conversation856## Fork the current conversation

853 857 

854<Note>858<Note>

855 Forked subagents require Claude Code v2.1.117 or later. {/* min-version: 2.1.161 */}From v2.1.161 the `/fork` command is enabled by default; on earlier versions it requires setting the [`CLAUDE_CODE_FORK_SUBAGENT`](/en/env-vars) environment variable to `1`. Making forks the model's *default* spawn behavior is experimental and may change in future releases. This default may also be enabled in interactive sessions as part of a staged rollout.859 Forked subagents require Claude Code v2.1.117 or later. {/* min-version: 2.1.161 */}From v2.1.161 the `/fork` command is enabled by default; on earlier versions it requires setting the [`CLAUDE_CODE_FORK_SUBAGENT`](/en/env-vars) environment variable to `1`. Letting Claude itself spawn forks is experimental and may change in future releases. This capability may also be enabled in interactive sessions as part of a staged rollout.

856</Note>860</Note>

857 861 

858A fork is a subagent that inherits the entire conversation so far instead of starting fresh. This drops the input isolation that subagents otherwise provide: a fork sees the same system prompt, tools, model, and message history as the main session, so you can hand it a side task without re-explaining the situation. The fork's own tool calls still stay out of your conversation and only its final result comes back, so your main context window stays clean. Use a fork when a named subagent would need too much background to be useful, or when you want to try several approaches in parallel from the same starting point.862A fork is a subagent that inherits the entire conversation so far instead of starting fresh. This drops the input isolation that subagents otherwise provide: a fork sees the same system prompt, tools, model, and message history as the main session, so you can hand it a side task without re-explaining the situation. The fork's own tool calls still stay out of your conversation and only its final result comes back, so your main context window stays clean. Use a fork when a named subagent would need too much background to be useful, or when you want to try several approaches in parallel from the same starting point.

861 865 

862Enabling fork mode changes Claude Code in two ways:866Enabling fork mode changes Claude Code in two ways:

863 867 

864* Claude spawns a fork whenever it would otherwise use the [general-purpose](#built-in-subagents) subagent. Named subagents such as Explore still spawn as before.868* Claude can spawn a fork by requesting the `fork` subagent type explicitly. Spawns without a subagent type still use the [general-purpose](#built-in-subagents) subagent, and named subagents such as Explore still spawn as before.

865* Every subagent spawn runs in the [background](#run-subagents-in-foreground-or-background), whether it is a fork or a named subagent. Set `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` to `1` to keep spawns synchronous.869* Every subagent spawn runs in the [background](#run-subagents-in-foreground-or-background), whether it is a fork or a named subagent. Set `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` to `1` to keep spawns synchronous.

866 870 

867You can start a fork yourself with `/fork` followed by a directive, with or without the variable set. Claude Code names the fork from the first words of the directive. The following example forks the conversation to draft test cases while you continue with the implementation in the main session:871You can start a fork yourself with `/fork` followed by a directive, with or without the variable set. Claude Code names the fork from the first words of the directive. The following example forks the conversation to draft test cases while you continue with the implementation in the main session:

44| `TaskOutput` | (Deprecated) Retrieves output from a background task. Prefer `Read` on the task's output file path | No |44| `TaskOutput` | (Deprecated) Retrieves output from a background task. Prefer `Read` on the task's output file path | No |

45| `TaskStop` | Kills a running background task by ID | No |45| `TaskStop` | Kills a running background task by ID | No |

46| `TaskUpdate` | Updates task status, dependencies, details, or deletes tasks | No |46| `TaskUpdate` | Updates task status, dependencies, details, or deletes tasks | No |

47| `TeamCreate` | Creates an [agent team](/en/agent-teams) with multiple teammates. Only available when `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` is set | No |

48| `TeamDelete` | Disbands an agent team and cleans up teammate processes. Only available when `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` is set | No |

49| `TodoWrite` | {/* min-version: 2.1.142 */}Manages the session task checklist. Disabled by default as of v2.1.142 in favor of `TaskCreate`, `TaskGet`, `TaskList`, and `TaskUpdate`. Set `CLAUDE_CODE_ENABLE_TASKS=0` to re-enable | No |47| `TodoWrite` | {/* min-version: 2.1.142 */}Manages the session task checklist. Disabled by default as of v2.1.142 in favor of `TaskCreate`, `TaskGet`, `TaskList`, and `TaskUpdate`. Set `CLAUDE_CODE_ENABLE_TASKS=0` to re-enable | No |

50| `ToolSearch` | Searches for and loads deferred tools when [tool search](/en/mcp#scale-with-mcp-tool-search) is enabled | No |48| `ToolSearch` | Searches for and loads deferred tools when [tool search](/en/mcp#scale-with-mcp-tool-search) is enabled | No |

51| `WaitForMcpServers` | {/* min-version: 2.1.142 */}Waits for one or more [MCP servers](/en/mcp) that are still connecting in the background, so a request can use their tools without restarting the session. Claude calls it when a needed server is not connected yet. Only appears when [tool search](/en/mcp#scale-with-mcp-tool-search) is disabled, since `ToolSearch` handles the wait when it's enabled | No |49| `WaitForMcpServers` | {/* min-version: 2.1.142 */}Waits for one or more [MCP servers](/en/mcp) that are still connecting in the background, so a request can use their tools without restarting the session. Claude calls it when a needed server is not connected yet. Only appears when [tool search](/en/mcp#scale-with-mcp-tool-search) is disabled, since `ToolSearch` handles the wait when it's enabled | No |

8 8 

9The weekly dev digest highlights the features most likely to change how you work. Each entry includes runnable code, a short demo, and a link to the full docs. For every bug fix and minor improvement, see the [changelog](/en/changelog).9The weekly dev digest highlights the features most likely to change how you work. Each entry includes runnable code, a short demo, and a link to the full docs. For every bug fix and minor improvement, see the [changelog](/en/changelog).

10 10 

11<Update label="Week 24" description="June 8–12, 2026" tags={["v2.1.166–v2.1.176"]}>

12 **`/cd`**: move the current session to a new working directory mid-conversation without rebuilding the prompt cache.

13 

14 Also this week: **sub-agents can spawn their own sub-agents** (background chains are capped at five levels deep); **`--safe-mode`** starts Claude Code with all customizations disabled for troubleshooting; and **`fallbackModel`** configures up to three fallback models tried in order.

15 

16 [Read the Week 24 digest →](/en/whats-new/2026-w24)

17</Update>

18 

19<Update label="Week 23" description="June 1–5, 2026" tags={["v2.1.158–v2.1.165"]}>

20 **Auto mode on Bedrock, Vertex, and Foundry**: auto mode is now available on third-party providers for Opus 4.7 and Opus 4.8, replacing permission prompts with background safety checks.

21 

22 Also this week: **safer automatic edits** prompt before writing files that can run code in `acceptEdits` mode; **`/plugin list`** prints your installed plugins inline; and **version requirements** let managed deployments require an approved Claude Code version range.

23 

24 [Read the Week 23 digest →](/en/whats-new/2026-w23)

25</Update>

26 

11<Update label="Week 22" description="May 25–29, 2026" tags={["v2.1.150–v2.1.157"]}>27<Update label="Week 22" description="May 25–29, 2026" tags={["v2.1.150–v2.1.157"]}>

12 **Claude Opus 4.8**: the new default model for Max, Team Premium, Enterprise pay-as-you-go, and Anthropic API accounts, with high effort by default and `/effort xhigh` for the hardest tasks.28 **Claude Opus 4.8**: the new default model for Max, Team Premium, Enterprise pay-as-you-go, and Anthropic API accounts, with high effort by default and `/effort xhigh` for the hardest tasks.

13 29 

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

4 

5# Week 23 · June 1–5, 2026

6 

7> Run auto mode on Bedrock, Vertex, and Foundry, prompt before writing files that can run code in acceptEdits mode, list installed plugins with /plugin list, and require an approved version range for managed deployments.

8 

9<div className="digest-meta">

10 <span>Releases <a href="/docs/en/changelog#2-1-158">v2.1.158 → v2.1.165</a></span>

11 <span>4 features · June 1–5</span>

12</div>

13 

14<div className="digest-feature">

15 <div className="digest-feature-header">

16 <span className="digest-feature-title">Auto mode on Bedrock, Vertex, and Foundry</span>

17 <span className="digest-feature-pill">v2.1.158</span>

18 </div>

19 

20 <p className="digest-feature-lede">Auto mode is now available on Bedrock, Vertex, and Foundry for Opus 4.7 and Opus 4.8, replacing permission prompts with background safety checks on third-party providers. Opt in by setting <code>CLAUDE\_CODE\_ENABLE\_AUTO\_MODE=1</code>.</p>

21 

22 <p className="digest-feature-try">Opt in on a third-party provider, then cycle to auto mode with Shift+Tab:</p>

23 

24 ```bash terminal theme={null}

25 export CLAUDE_CODE_ENABLE_AUTO_MODE=1

26 ```

27 

28 <a className="digest-feature-link" href="/docs/en/permission-modes#enable-auto-mode-on-bedrock-vertex-ai-or-foundry">Enable auto mode on third-party providers</a>

29</div>

30 

31<div className="digest-feature">

32 <div className="digest-feature-header">

33 <span className="digest-feature-title">Safer automatic edits</span>

34 <span className="digest-feature-pill">v2.1.160</span>

35 </div>

36 

37 <p className="digest-feature-lede">Claude Code now prompts before writing files that can run code, even in <code>acceptEdits</code> mode. The protected set covers shell startup files such as <code>.zshenv</code> and <code>.bash\_login</code>, git config under <code>\~/.config/git/</code>, and build-tool configs such as <code>.npmrc</code>, <code>.bazelrc</code>, and <code>.pre-commit-config.yaml</code>. These writes are never auto-approved in any mode except <code>bypassPermissions</code>.</p>

38 

39 <p className="digest-feature-try">Work in acceptEdits mode; Claude now pauses before writing these files:</p>

40 

41 ```bash terminal theme={null}

42 claude --permission-mode acceptEdits

43 ```

44 

45 <a className="digest-feature-link" href="/docs/en/permission-modes#protected-paths">Protected paths</a>

46</div>

47 

48<div className="digest-feature">

49 <div className="digest-feature-header">

50 <span className="digest-feature-title">List installed plugins with /plugin list</span>

51 <span className="digest-feature-pill">v2.1.163</span>

52 </div>

53 

54 <p className="digest-feature-lede">The new <code>/plugin list</code> command prints your installed plugins inline, without opening the <code>/plugin</code> menu, and is also available as <code>claude plugin list</code> from the shell. In the interactive form, add `--enabled` or `--disabled` to show only plugins in that state.</p>

55 

56 <p className="digest-feature-try">List the plugins that are currently turned on:</p>

57 

58 ```text Claude Code theme={null}

59 > /plugin list --enabled

60 ```

61 

62 <a className="digest-feature-link" href="/docs/en/plugins-reference#plugin-list">Plugin commands</a>

63</div>

64 

65<div className="digest-feature">

66 <div className="digest-feature-header">

67 <span className="digest-feature-title">Version requirements for managed deployments</span>

68 <span className="digest-feature-pill">v2.1.163</span>

69 </div>

70 

71 <p className="digest-feature-lede">Two managed settings, <code>requiredMinimumVersion</code> and <code>requiredMaximumVersion</code>, let your organization require an approved Claude Code version range. A client outside the range exits at startup and tells the user to update through the organization's method. <code>claude update</code>, <code>claude install</code>, and <code>claude doctor</code> keep working so users can still recover.</p>

72 

73 <p className="digest-feature-try">Add a floor to your managed settings so older clients refuse to start:</p>

74 

75 ```json managed-settings.json theme={null}

76 "requiredMinimumVersion": "2.1.163"

77 ```

78 

79 <a className="digest-feature-link" href="/docs/en/admin-setup#decide-what-to-enforce">Decide what to enforce</a>

80</div>

81 

82<div className="digest-wins">

83 <p className="digest-wins-title">Other wins</p>

84 

85 <div className="digest-wins-grid">

86 <div>The trigger keyword for <a href="/docs/en/workflows">dynamic workflows</a> changed from <code>workflow</code> to <code>ultracode</code>; asking for a workflow in your own words still works, and the keyword is highlighted in violet in the prompt</div>

87 <div><a href="/docs/en/hooks">Stop and SubagentStop hooks</a> can return <code>hookSpecificOutput.additionalContext</code> to give Claude feedback and keep the turn going instead of being treated as an error</div>

88 <div><code>claude mcp</code> list, get, and add no longer print secrets: environment-variable references are not expanded, and credential headers and URL secrets are redacted</div>

89 <div>A failed Bash command in a parallel tool batch no longer cancels the others; each tool returns its own result independently</div>

90 <div>Editing a file no longer needs a separate Read first when you viewed it with a single-file <code>grep</code>, <code>egrep</code>, or <code>fgrep</code></div>

91 <div>Clicking a command in the autocomplete menu now fills it into your prompt instead of running it immediately; press Enter to run</div>

92 <div>Listing <code>Grep</code> or <code>Glob</code> in `--tools` now provides the dedicated search tools on native builds with embedded search, instead of silently ignoring those names</div>

93 <div><code>/effort</code> now confirms when your chosen level will persist as the default for new sessions</div>

94 <div><code>OTEL\_RESOURCE\_ATTRIBUTES</code> values are now attached as labels on metric datapoints, so you can slice usage metrics by custom dimensions like team or repo</div>

95 <div>Windsurf is renamed to Devin Desktop in <code>/ide</code>, <code>/terminal-setup</code>, and <code>/scroll-speed</code>, following the editor's rebrand</div>

96 <div><code>/btw</code> gains a <code>c to copy</code> shortcut that copies the raw markdown answer to the clipboard</div>

97 </div>

98</div>

99 

100[Full changelog for v2.1.158–v2.1.165 →](/en/changelog#2-1-158)

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

4 

5# Week 24 · June 8–12, 2026

6 

7> Move a session to a new directory with /cd, let sub-agents spawn their own sub-agents, and troubleshoot a broken configuration with safe mode.

8 

9<div className="digest-meta">

10 <span>Releases <a href="/docs/en/changelog#2-1-166">v2.1.166 → v2.1.176</a></span>

11 <span>3 features · June 8–12</span>

12</div>

13 

14<div className="digest-feature">

15 <div className="digest-feature-header">

16 <span className="digest-feature-title">Move a session with /cd</span>

17 <span className="digest-feature-pill">v2.1.169</span>

18 </div>

19 

20 <p className="digest-feature-lede">The new <code>/cd</code> command moves the current session to a different working directory without rebuilding the prompt cache: the new directory's <code>CLAUDE.md</code> is appended as a message instead of replacing the system prompt. The session relocates to the new directory's project storage, so `--resume` and `--continue` find it there. Claude prompts you to trust the directory if you haven't worked in it before.</p>

21 

22 <p className="digest-feature-try">Move the session into another project without restarting:</p>

23 

24 ```text Claude Code theme={null}

25 > /cd ../other-project

26 ```

27 

28 <a className="digest-feature-link" href="/docs/en/commands#all-commands">Commands reference</a>

29</div>

30 

31<div className="digest-feature">

32 <div className="digest-feature-header">

33 <span className="digest-feature-title">Sub-agents can spawn sub-agents</span>

34 <span className="digest-feature-pill">v2.1.172</span>

35 </div>

36 

37 <p className="digest-feature-lede">Sub-agents can now spawn their own sub-agents. The subagent panel below the prompt shows the full tree: each row carries a count of its descendants and a path back to <code>main</code>. Background sub-agents are capped at five levels deep to prevent runaway concurrent trees; foreground chains can spawn at any depth and are self-limiting.</p>

38 

39 <p className="digest-feature-try">Open the agents view to watch the nested tree as work fans out:</p>

40 

41 ```text Claude Code theme={null}

42 > /agents

43 ```

44 

45 <a className="digest-feature-link" href="/docs/en/sub-agents#spawn-nested-subagents">Spawn nested subagents</a>

46</div>

47 

48<div className="digest-feature">

49 <div className="digest-feature-header">

50 <span className="digest-feature-title">Troubleshoot with safe mode</span>

51 <span className="digest-feature-pill">v2.1.169</span>

52 </div>

53 

54 <p className="digest-feature-lede">Start Claude Code with `--safe-mode`, or set <code>CLAUDE\_CODE\_SAFE\_MODE</code>, to launch with all customizations disabled: <code>CLAUDE.md</code>, skills, plugins, hooks, MCP servers, and custom commands and agents do not load. Authentication, model selection, built-in tools, and permissions still work. If a problem disappears in safe mode, one of those surfaces is the cause.</p>

55 

56 <p className="digest-feature-try">Launch a clean session to isolate a broken configuration:</p>

57 

58 ```bash terminal theme={null}

59 claude --safe-mode

60 ```

61 

62 <a className="digest-feature-link" href="/docs/en/debug-your-config#test-against-a-clean-configuration">Test against a clean configuration</a>

63</div>

64 

65<div className="digest-wins">

66 <p className="digest-wins-title">Other wins</p>

67 

68 <div className="digest-wins-grid">

69 <div><a href="/docs/en/model-config#fallback-model-chains"><code>fallbackModel</code></a> configures up to three fallback models tried in order when the primary is overloaded or unavailable, and `--fallback-model` now applies to interactive sessions too</div>

70 <div>Session titles are now generated in the language of your conversation; pin a specific one with the <code>language</code> setting</div>

71 <div>`claude agents --json` adds `--all` to include completed sessions plus new <code>id</code> and <code>state</code> fields, and no longer omits blocked or newly dispatched sessions</div>

72 <div>Browsing a marketplace's plugins in <code>/plugin</code> now has a search bar</div>

73 <div>New <code>disableBundledSkills</code> setting and <code>CLAUDE\_CODE\_DISABLE\_BUNDLED\_SKILLS</code> hide bundled skills, workflows, and built-in commands from the model</div>

74 <div>Deny rules accept a glob in the tool-name position, so <code>"\*"</code> denies all tools, and unknown tool names in deny rules now warn at startup</div>

75 <div>Cross-session messaging is hardened: messages relayed via <code>SendMessage</code> from other sessions no longer carry user authority, and auto mode blocks them</div>

76 <div>Amazon Bedrock reads the AWS region from <code>\~/.aws</code> config files when <code>AWS\_REGION</code> is unset, and <code>/status</code> shows where the region came from</div>

77 <div>New <code>enforceAvailableModels</code> managed setting makes the <code>availableModels</code> allowlist also constrain the Default model</div>

78 <div>Claude in Chrome browser tools now load in a single batched call instead of one per tool</div>

79 <div><code>claude update</code> announces the target version before downloading instead of going silent</div>

80 <div>New <code>footerLinksRegexes</code> setting adds regex-matched link badges to the footer row</div>

81 </div>

82</div>

83 

84[Full changelog for v2.1.166–v2.1.176 →](/en/changelog#2-1-166)

180 180 

181Press Enter to save. The workflow runs as `/<name>` in future sessions from either location.181Press Enter to save. The workflow runs as `/<name>` in future sessions from either location.

182 182 

183{/* min-version: 2.1.178 */}As of v2.1.178, saving to the project location writes to the closest `.claude/workflows/` directory that already exists between your working directory and the repository root, or to the repository root if none exists yet. Project workflows also load from every `.claude/workflows/` along that path, and when more than one defines the same name Claude Code runs the one closest to the working directory.

184 

183If a project workflow and a personal workflow share a name, the project one runs.185If a project workflow and a personal workflow share a name, the project one runs.

184 186 

185### Pass input to a saved workflow187### Pass input to a saved workflow