Documentation — Spybara

agent-teams.md +7 −0

Details

182 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.182 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.

183</Warning>183</Warning>

184 184

185### Enforce quality gates with hooks

186

187Use [hooks](/en/hooks) to enforce rules when teammates finish work or tasks complete:

188

189* [`TeammateIdle`](/en/hooks#teammateidle): runs when a teammate is about to go idle. Exit with code 2 to send feedback and keep the teammate working.

190* [`TaskCompleted`](/en/hooks#taskcompleted): runs when a task is being marked complete. Exit with code 2 to prevent completion and send feedback.

191

185## How agent teams work192## How agent teams work

186 193

187This section covers the architecture and mechanics behind agent teams. If you want to start using them, see [Control your agent team](#control-your-agent-team) above.194This section covers the architecture and mechanics behind agent teams. If you want to start using them, see [Control your agent team](#control-your-agent-team) above.

checkpointing.md +4 −0

Details

43 43

44This is similar to `/compact`, but targeted: instead of summarizing the entire conversation, you keep early context in full detail and only compress the parts that are using up space. You can type optional instructions to guide what the summary focuses on.44This is similar to `/compact`, but targeted: instead of summarizing the entire conversation, you keep early context in full detail and only compress the parts that are using up space. You can type optional instructions to guide what the summary focuses on.

45 45

46<Note>

47 Summarize keeps you in the same session and compresses context. If you want to branch off and try a different approach while preserving the original session intact, use [fork](/en/how-claude-code-works#resume-or-fork-sessions) instead (`claude --continue --fork-session`).

48</Note>

46## Common use cases50## Common use cases

47 51

48Checkpoints are particularly useful when:52Checkpoints are particularly useful when:

cli-reference.md +7 −3

Details

85The `--agents` flag accepts a JSON object that defines one or more custom subagents. Each subagent requires a unique name (as the key) and a definition object with the following fields:85The `--agents` flag accepts a JSON object that defines one or more custom subagents. Each subagent requires a unique name (as the key) and a definition object with the following fields:

86 86

~~88| :------------ | :------- | :---------------------------------------------------------------------------------------------------------------------------------- |~~88| :---------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

89| `description` | Yes | Natural language description of when the subagent should be invoked |89| `description` | Yes | Natural language description of when the subagent should be invoked |

90| `prompt` | Yes | The system prompt that guides the subagent's behavior |90| `prompt` | Yes | The system prompt that guides the subagent's behavior |

~~91| `tools` | No | Array of specific tools the subagent can use (for example, `["Read", "Edit", "Bash"]`). If omitted, inherits all tools |~~91| `tools` | No | Array of specific tools the subagent can use, for example `["Read", "Edit", "Bash"]`. If omitted, inherits all tools. Supports [`Task(agent_type)`](/en/sub-agents#restrict-which-subagents-can-be-spawned) syntax |

~~92| `model` | No | Model alias to use: `sonnet`, `opus`, `haiku`, or `inherit`. If omitted, defaults to `inherit` (uses the main conversation's model) |~~92| `disallowedTools` | No | Array of tool names to explicitly deny for this subagent |

93| `model` | No | Model alias to use: `sonnet`, `opus`, `haiku`, or `inherit`. If omitted, defaults to `inherit` |

94| `skills` | No | Array of [skill](/en/skills) names to preload into the subagent's context |

95| `mcpServers` | No | Array of [MCP servers](/en/mcp) for this subagent. Each entry is a server name string or a `{name: config}` object |

96| `maxTurns` | No | Maximum number of agentic turns before the subagent stops |

93 97

94Example:98Example:

95 99

fast-mode.md +131 −0 created

Details

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.

5# Speed up responses with fast mode

7> Get faster Opus 4.6 responses in Claude Code by toggling fast mode.

9<Note>

10 Fast mode is in [research preview](#research-preview). The feature, pricing, and availability may change based on feedback.

11</Note>

13Fast mode delivers faster Opus 4.6 responses at a higher cost per token. Toggle it on with `/fast` when you need speed for interactive work like rapid iteration or live debugging, and toggle it off when cost matters more than latency.

15Fast mode is not a different model. It uses the same Opus 4.6 with a different API configuration that prioritizes speed over cost efficiency. You get identical quality and capabilities, just faster responses.

17What to know:

19* Use `/fast` to toggle on fast mode in Claude Code CLI. Also available via `/fast` in Claude Code VS Code Extension.

20* Fast mode for Opus 4.6 pricing starts at \$30/150 MTok. Fast mode is available at a 50% discount for all plans until 11:59pm PT on February 16.

21* Available to all Claude Code users on subscription plans (Pro/Max/Team/Enterprise) and Claude Console.

22* For Claude Code users on subscription plans (Pro/Max/Team/Enterprise), fast mode is available via extra usage only and not included in the subscription rate limits.

24This page covers how to [toggle fast mode](#toggle-fast-mode), its [cost tradeoff](#understand-the-cost-tradeoff), [when to use it](#decide-when-to-use-fast-mode), [requirements](#requirements), and [rate limit behavior](#handle-rate-limits).

26## Toggle fast mode

28Toggle fast mode in either of these ways:

30* Type `/fast` and press Tab to toggle on or off

31* Set `"fastMode": true` in your [user settings file](/en/settings)

33Fast mode persists across sessions. For the best cost efficiency, enable fast mode at the start of a session rather than switching mid-conversation. See [understand the cost tradeoff](#understand-the-cost-tradeoff) for details.

35When you enable fast mode:

37* If you're on a different model, Claude Code automatically switches to Opus 4.6

38* You'll see a confirmation message: "Fast mode ON"

39* A small `↯` icon appears next to the prompt while fast mode is active

40* Run `/fast` again at any time to check whether fast mode is on or off

42When you disable fast mode with `/fast` again, you remain on Opus 4.6. The model does not revert to your previous model. To switch to a different model, use `/model`.

44## Understand the cost tradeoff

46Fast mode has higher per-token pricing than standard Opus 4.6:

48| Mode | Input (MTok) | Output (MTok) |

49| ------------------------------ | ------------ | ------------- |

50| Fast mode on Opus 4.6 (\<200K) | \$30 | \$150 |

51| Fast mode on Opus 4.6 (>200K) | \$60 | \$225 |

53Fast mode is compatible with the 1M token extended context window.

55When you switch into fast mode mid-conversation, you pay the full fast mode uncached input token price for the entire conversation context. This costs more than if you had enabled fast mode from the start.

57## Decide when to use fast mode

59Fast mode is best for interactive work where response latency matters more than cost:

61* Rapid iteration on code changes

62* Live debugging sessions

63* Time-sensitive work with tight deadlines

65Standard mode is better for:

67* Long autonomous tasks where speed matters less

68* Batch processing or CI/CD pipelines

69* Cost-sensitive workloads

71### Fast mode vs effort level

73Fast mode and effort level both affect response speed, but differently:

75| Setting | Effect |

76| ---------------------- | -------------------------------------------------------------------------------- |

77| **Fast mode** | Same model quality, lower latency, higher cost |

78| **Lower effort level** | Less thinking time, faster responses, potentially lower quality on complex tasks |

80You can combine both: use fast mode with a lower [effort level](/en/model-config#adjust-effort-level) for maximum speed on straightforward tasks.

82## Requirements

84Fast mode requires all of the following:

86* **Not available on third-party cloud providers**: fast mode is not available on Amazon Bedrock, Google Vertex AI, or Microsoft Azure Foundry. Fast mode is available through the Anthropic Console API and for Claude subscription plans using extra usage.

87* **Extra usage enabled**: your account must have extra usage enabled, which allows billing beyond your plan's included usage. For individual accounts, enable this in your [Console billing settings](https://platform.claude.com/settings/organization/billing). For Teams and Enterprise, an admin must enable extra usage for the organization.

89<Note>

90 Fast mode usage is billed directly to extra usage, even if you have remaining usage on your plan. This means fast mode tokens do not count against your plan's included usage and are charged at the fast mode rate from the first token.

91</Note>

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

95<Note>

96 If your admin has not enabled fast mode for your organization, the `/fast` command will show "Fast mode has been disabled by your organization."

97</Note>

99### Enable fast mode for your organization

100

101Admins can enable fast mode in:

102

103* **Console** (API customers): [Claude Code preferences](https://platform.claude.com/claude-code/preferences)

104* **Claude AI** (Teams and Enterprise): [Admin Settings > Claude Code](https://claude.ai/admin-settings/claude-code)

105

106## Handle rate limits

107

108Fast mode has separate rate limits from standard Opus 4.6. When you hit the fast mode rate limit or run out of extra usage credits:

109

1101. Fast mode automatically falls back to standard Opus 4.6

1112. The `↯` icon turns gray to indicate cooldown

1123. You continue working at standard speed and pricing

1134. When the cooldown expires, fast mode automatically re-enables

114

115To disable fast mode manually instead of waiting for cooldown, run `/fast` again.

116

117## Research preview

118

119Fast mode is a research preview feature. This means:

120

121* The feature may change based on feedback

122* Availability and pricing are subject to change

123* The underlying API configuration may evolve

124

125Report issues or feedback through your usual Anthropic support channels.

126

127## See also

128

129* [Model configuration](/en/model-config): switch models and adjust effort levels

130* [Manage costs effectively](/en/costs): track token usage and reduce costs

131* [Status line configuration](/en/statusline): display model and context information

hooks.md +104 −6

Details

18 18

19<div style={{maxWidth: "500px", margin: "0 auto"}}>19<div style={{maxWidth: "500px", margin: "0 auto"}}>

20 <Frame>20 <Frame>

21 <img src="https://mintcdn.com/claude-code/z2YM37Ycg6eMbID3/images/hooks-lifecycle.png?fit=max&auto=format&n=z2YM37Ycg6eMbID3&q=85&s=5c25fedbc3db6f8882af50c3cc478c32" alt="Hook lifecycle diagram showing the sequence of hooks from SessionStart through the agentic loop to SessionEnd" data-og-width="8876" width="8876" data-og-height="12492" height="12492" data-path="images/hooks-lifecycle.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/z2YM37Ycg6eMbID3/images/hooks-lifecycle.png?w=280&fit=max&auto=format&n=z2YM37Ycg6eMbID3&q=85&s=62406fcd5d4a189cc8842ee1bd946b84 280w, https://mintcdn.com/claude-code/z2YM37Ycg6eMbID3/images/hooks-lifecycle.png?w=560&fit=max&auto=format&n=z2YM37Ycg6eMbID3&q=85&s=fa3049022a6973c5f974e0f95b28169d 560w, https://mintcdn.com/claude-code/z2YM37Ycg6eMbID3/images/hooks-lifecycle.png?w=840&fit=max&auto=format&n=z2YM37Ycg6eMbID3&q=85&s=bd2890897db61a03160b93d4f972ff8e 840w, https://mintcdn.com/claude-code/z2YM37Ycg6eMbID3/images/hooks-lifecycle.png?w=1100&fit=max&auto=format&n=z2YM37Ycg6eMbID3&q=85&s=7ae8e098340479347135e39df4a13454 1100w, https://mintcdn.com/claude-code/z2YM37Ycg6eMbID3/images/hooks-lifecycle.png?w=1650&fit=max&auto=format&n=z2YM37Ycg6eMbID3&q=85&s=848a8606aab22c2ccaa16b6a18431e32 1650w, https://mintcdn.com/claude-code/z2YM37Ycg6eMbID3/images/hooks-lifecycle.png?w=2500&fit=max&auto=format&n=z2YM37Ycg6eMbID3&q=85&s=f3a9ef7feb61fa8fe362005aa185efbc 2500w" />21 <img src="https://mintcdn.com/claude-code/tpQvD9DKENFo4zX_/images/hooks-lifecycle.svg?fit=max&auto=format&n=tpQvD9DKENFo4zX_&q=85&s=7a351ea1cc3d5da7a2176bf51196bc1a" alt="Hook lifecycle diagram showing the sequence of hooks from SessionStart through the agentic loop to SessionEnd" data-og-width="520" width="520" data-og-height="960" height="960" data-path="images/hooks-lifecycle.svg" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/tpQvD9DKENFo4zX_/images/hooks-lifecycle.svg?w=280&fit=max&auto=format&n=tpQvD9DKENFo4zX_&q=85&s=8f32c67d025f0a318d5ed10a4f8ff2e6 280w, https://mintcdn.com/claude-code/tpQvD9DKENFo4zX_/images/hooks-lifecycle.svg?w=560&fit=max&auto=format&n=tpQvD9DKENFo4zX_&q=85&s=896fc424e39ff8d590720331a77e3d80 560w, https://mintcdn.com/claude-code/tpQvD9DKENFo4zX_/images/hooks-lifecycle.svg?w=840&fit=max&auto=format&n=tpQvD9DKENFo4zX_&q=85&s=a1c1c9739cde965e1eade843cee567c5 840w, https://mintcdn.com/claude-code/tpQvD9DKENFo4zX_/images/hooks-lifecycle.svg?w=1100&fit=max&auto=format&n=tpQvD9DKENFo4zX_&q=85&s=5bb083988de020e7d568e8dd8f1422fc 1100w, https://mintcdn.com/claude-code/tpQvD9DKENFo4zX_/images/hooks-lifecycle.svg?w=1650&fit=max&auto=format&n=tpQvD9DKENFo4zX_&q=85&s=343e9883c1e3172f08096c352aa46f12 1650w, https://mintcdn.com/claude-code/tpQvD9DKENFo4zX_/images/hooks-lifecycle.svg?w=2500&fit=max&auto=format&n=tpQvD9DKENFo4zX_&q=85&s=4de37b29de0f6df8b0c3e937a76c3bc6 2500w" />

22 </Frame>22 </Frame>

23</div>23</div>

24 24

25The table below summarizes when each event fires. The [Hook events](#hook-events) section documents the full input schema and decision control options for each one.25The table below summarizes when each event fires. The [Hook events](#hook-events) section documents the full input schema and decision control options for each one.

26 26

27| Event | When it fires |27| Event | When it fires |

~~28| :------------------- | :--------------------------------------------------- |~~28| :------------------- | :----------------------------------------------------------------- |

29| `SessionStart` | When a session begins or resumes |29| `SessionStart` | When a session begins or resumes |

30| `UserPromptSubmit` | When you submit a prompt, before Claude processes it |30| `UserPromptSubmit` | When you submit a prompt, before Claude processes it |

31| `PreToolUse` | Before a tool call executes. Can block it |31| `PreToolUse` | Before a tool call executes. Can block it |

36| `SubagentStart` | When a subagent is spawned |36| `SubagentStart` | When a subagent is spawned |

37| `SubagentStop` | When a subagent finishes |37| `SubagentStop` | When a subagent finishes |

38| `Stop` | When Claude finishes responding |38| `Stop` | When Claude finishes responding |

39| `TeammateIdle` | When an [agent team](/en/agent-teams) teammate is about to go idle |

40| `TaskCompleted` | When a task is being marked as completed |

39| `PreCompact` | Before context compaction |41| `PreCompact` | Before context compaction |

40| `SessionEnd` | When a session terminates |42| `SessionEnd` | When a session terminates |

41 43

169 171

170The matcher is a regex, so `Edit|Write` matches either tool and `Notebook.*` matches any tool starting with Notebook. The matcher runs against a field from the [JSON input](#hook-input-and-output) that Claude Code sends to your hook on stdin. For tool events, that field is `tool_name`. Each [hook event](#hook-events) section lists the full set of matcher values and the input schema for that event.172The matcher is a regex, so `Edit|Write` matches either tool and `Notebook.*` matches any tool starting with Notebook. The matcher runs against a field from the [JSON input](#hook-input-and-output) that Claude Code sends to your hook on stdin. For tool events, that field is `tool_name`. Each [hook event](#hook-events) section lists the full set of matcher values and the input schema for that event.

171 173

441Exit code 2 is the way a hook signals "stop, don't do this." The effect depends on the event, because some events represent actions that can be blocked (like a tool call that hasn't happened yet) and others represent things that already happened or can't be prevented.443Exit code 2 is the way a hook signals "stop, don't do this." The effect depends on the event, because some events represent actions that can be blocked (like a tool call that hasn't happened yet) and others represent things that already happened or can't be prevented.

442 444

444| :------------------- | :--------- | :-------------------------------------------------------- |446| :------------------- | :--------- | :----------------------------------------------------------------- |

445| `PreToolUse` | Yes | Blocks the tool call |447| `PreToolUse` | Yes | Blocks the tool call |

446| `PermissionRequest` | Yes | Denies the permission |448| `PermissionRequest` | Yes | Denies the permission |

447| `UserPromptSubmit` | Yes | Blocks prompt processing and erases the prompt |449| `UserPromptSubmit` | Yes | Blocks prompt processing and erases the prompt |

448| `Stop` | Yes | Prevents Claude from stopping, continues the conversation |450| `Stop` | Yes | Prevents Claude from stopping, continues the conversation |

449| `SubagentStop` | Yes | Prevents the subagent from stopping |451| `SubagentStop` | Yes | Prevents the subagent from stopping |

452| `TeammateIdle` | Yes | Prevents the teammate from going idle (teammate continues working) |

453| `TaskCompleted` | Yes | Prevents the task from being marked as completed |

450| `PostToolUse` | No | Shows stderr to Claude (tool already ran) |454| `PostToolUse` | No | Shows stderr to Claude (tool already ran) |

451| `PostToolUseFailure` | No | Shows stderr to Claude (tool already failed) |455| `PostToolUseFailure` | No | Shows stderr to Claude (tool already failed) |

452| `Notification` | No | Shows stderr to user only |456| `Notification` | No | Shows stderr to user only |

492| :-------------------------------------------------------------------- | :------------------- | :---------------------------------------------------------------- |496| :-------------------------------------------------------------------- | :------------------- | :---------------------------------------------------------------- |

498| TeammateIdle, TaskCompleted | Exit code only | Exit code 2 blocks the action, stderr is fed back as feedback |

496 501

498 503

499<Tabs>504<Tabs>

500 <Tab title="Top-level decision">505 <Tab title="Top-level decision">

501 Used by `UserPromptSubmit`, `PostToolUse`, `PostToolUseFailure`, `Stop`, and `SubagentStop`. The only value is `"block"` — to allow the action to proceed, omit `decision` from your JSON, or exit 0 without any JSON at all:506 Used by `UserPromptSubmit`, `PostToolUse`, `PostToolUseFailure`, `Stop`, and `SubagentStop`. The only value is `"block"`. To allow the action to proceed, omit `decision` from your JSON, or exit 0 without any JSON at all:

502 507

503 ```json theme={null}508 ```json theme={null}

504 {509 {

1134}1139}

1135```1140```

1136 1141

1142### TeammateIdle

1143

1144Runs when an [agent team](/en/agent-teams) teammate is about to go idle after finishing its turn. Use this to enforce quality gates before a teammate stops working, such as requiring passing lint checks or verifying that output files exist.

1145

1146When a `TeammateIdle` hook exits with code 2, the teammate receives the stderr message as feedback and continues working instead of going idle. TeammateIdle hooks do not support matchers and fire on every occurrence.

1147

1148#### TeammateIdle input

1149

1150In addition to the [common input fields](#common-input-fields), TeammateIdle hooks receive `teammate_name` and `team_name`.

1151

1152```json theme={null}

1153{

1154 "session_id": "abc123",

1155 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",

1156 "cwd": "/Users/...",

1157 "permission_mode": "default",

1158 "hook_event_name": "TeammateIdle",

1159 "teammate_name": "researcher",

1160 "team_name": "my-project"

1161}

1162```

1163

1164| Field | Description |

1165| :-------------- | :-------------------------------------------- |

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

1167| `team_name` | Name of the team |

1168

1169#### TeammateIdle decision control

1170

1171TeammateIdle hooks use exit codes only, not JSON decision control. This example checks that a build artifact exists before allowing a teammate to go idle:

1172

1173```bash theme={null}

1174#!/bin/bash

1175

1176if [ ! -f "./dist/output.js" ]; then

1177 echo "Build artifact missing. Run the build before stopping." >&2

1178 exit 2

1179fi

1180

1181exit 0

1182```

1183

1184### TaskCompleted

1185

1186Runs when a task is being marked as completed. This fires in two situations: when any agent explicitly marks a task as completed through the TaskUpdate tool, or when an [agent team](/en/agent-teams) teammate finishes its turn with in-progress tasks. Use this to enforce completion criteria like passing tests or lint checks before a task can close.

1187

1188When a `TaskCompleted` hook exits with code 2, the task is not marked as completed and the stderr message is fed back to the model as feedback. TaskCompleted hooks do not support matchers and fire on every occurrence.

1189

1190#### TaskCompleted input

1191

1192In addition to the [common input fields](#common-input-fields), TaskCompleted hooks receive `task_id`, `task_subject`, and optionally `task_description`, `teammate_name`, and `team_name`.

1193

1194```json theme={null}

1195{

1196 "session_id": "abc123",

1197 "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",

1198 "cwd": "/Users/...",

1199 "permission_mode": "default",

1200 "hook_event_name": "TaskCompleted",

1201 "task_id": "task-001",

1202 "task_subject": "Implement user authentication",

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

1204 "teammate_name": "implementer",

1205 "team_name": "my-project"

1206}

1207```

1208

1209| Field | Description |

1210| :----------------- | :------------------------------------------------------ |

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

1212| `task_subject` | Title of the task |

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

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

1215| `team_name` | Name of the team. May be absent |

1216

1217#### TaskCompleted decision control

1218

1219TaskCompleted hooks use exit codes only, not JSON decision control. This example runs tests and blocks task completion if they fail:

1220

1221```bash theme={null}

1222#!/bin/bash

1223INPUT=$(cat)

1224TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject')

1225

1226# Run the test suite

1227if ! npm test 2>&1; then

1228 echo "Tests not passing. Fix failing tests before completing: $TASK_SUBJECT" >&2

1229 exit 2

1230fi

1231

1232exit 0

1233```

1234

1137### PreCompact1235### PreCompact

1138 1236

1139Runs before Claude Code is about to run a compact operation.1237Runs before Claude Code is about to run a compact operation.

1195 1293

1196## Prompt-based hooks1294## Prompt-based hooks

1197 1295

1198In addition to Bash command hooks (`type: "command"`), Claude Code supports prompt-based hooks (`type: "prompt"`) that use an LLM to evaluate whether to allow or block an action. Prompt-based hooks work with the following events: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, and `SubagentStop`.1296In addition to Bash command hooks (`type: "command"`), Claude Code supports prompt-based hooks (`type: "prompt"`) that use an LLM to evaluate whether to allow or block an action. Prompt-based hooks work with the following events: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `UserPromptSubmit`, `Stop`, `SubagentStop`, and `TaskCompleted`. `TeammateIdle` does not support prompt-based or agent-based hooks.

1199 1297

1200### How prompt-based hooks work1298### How prompt-based hooks work

1201 1299

hooks-guide.md +6 −4

Details

267Hook events fire at specific lifecycle points in Claude Code. When an event fires, all matching hooks run in parallel, and identical hook commands are automatically deduplicated. The table below shows each event and when it triggers:267Hook events fire at specific lifecycle points in Claude Code. When an event fires, all matching hooks run in parallel, and identical hook commands are automatically deduplicated. The table below shows each event and when it triggers:

268 268

269| Event | When it fires |269| Event | When it fires |

270| :------------------- | :--------------------------------------------------- |270| :------------------- | :----------------------------------------------------------------- |

281| `TeammateIdle` | When an [agent team](/en/agent-teams) teammate is about to go idle |

282| `TaskCompleted` | When a task is being marked as completed |

283 285

382Each event type matches on a specific field. Matchers support exact strings and regex patterns:384Each event type matches on a specific field. Matchers support exact strings and regex patterns:

383 385

385| :--------------------------------------------------------------------- | :------------------------ | :----------------------------------------------------------------------- |387| :--------------------------------------------------------------------- | :------------------------ | :----------------------------------------------------------------------------- |

394 396

395A few more examples showing matchers on different event types:397A few more examples showing matchers on different event types:

how-claude-code-works.md +1 −1

Details

77 77

78Claude Code saves your conversation locally as you work. Each message, tool use, and result is stored, which enables [rewinding](#undo-changes-with-checkpoints), [resuming, and forking](#resume-or-fork-sessions) sessions. Before Claude makes code changes, it also snapshots the affected files so you can revert if needed.78Claude Code saves your conversation locally as you work. Each message, tool use, and result is stored, which enables [rewinding](#undo-changes-with-checkpoints), [resuming, and forking](#resume-or-fork-sessions) sessions. Before Claude makes code changes, it also snapshots the affected files so you can revert if needed.

79 79

80**Sessions are ephemeral.** Unlike claude.ai, Claude Code has no persistent memory between sessions. Each new session starts fresh. Claude doesn't "learn" your preferences over time or remember what you worked on last week. If you want Claude to know something across sessions, put it in your [CLAUDE.md](/en/memory).80**Sessions are independent.** Each new session starts with a fresh context window, without the conversation history from previous sessions. Claude can persist learnings across sessions using [auto memory](/en/memory#auto-memory), and you can add your own persistent instructions in [CLAUDE.md](/en/memory).

81 81

82### Work across branches82### Work across branches

83 83

memory.md +61 −3

Details

6 6

7> Learn how to manage Claude Code's memory across sessions with different memory locations and best practices.7> Learn how to manage Claude Code's memory across sessions with different memory locations and best practices.

8 8

~~9Claude Code can remember your preferences across sessions, like style guidelines and common commands in your workflow.~~9Claude Code has two kinds of memory that persist across sessions:

11* **Auto memory**: Claude automatically saves useful context like project patterns, key commands, and your preferences. This persists across sessions.

12* **CLAUDE.md files**: Markdown files you write and maintain with instructions, rules, and preferences for Claude to follow.

14Both are loaded into Claude's context at the start of every session, though auto memory loads only the first 200 lines of its main file.

10 15

11## Determine memory type16## Determine memory type

12 17

~~13Claude Code offers four memory locations in a hierarchical structure, each serving a different purpose:~~18Claude Code offers several memory locations in a hierarchical structure, each serving a different purpose:

14 19

16| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------- |21| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------- |

19| **Project rules** | `./.claude/rules/*.md` | Modular, topic-specific project instructions | Language-specific guidelines, testing conventions, API standards | Team members via source control |24| **Project rules** | `./.claude/rules/*.md` | Modular, topic-specific project instructions | Language-specific guidelines, testing conventions, API standards | Team members via source control |

22 28

23All memory files are automatically loaded into Claude Code's context when launched. Files higher in the hierarchy take precedence and are loaded first, providing a foundation that more specific memories build upon.29CLAUDE.md files in the directory hierarchy above the working directory are loaded in full at launch. CLAUDE.md files in child directories load on demand when Claude reads files in those directories. Auto memory loads only the first 200 lines of `MEMORY.md`. More specific instructions take precedence over broader ones.

24 30

25<Note>31<Note>

26 CLAUDE.local.md files are automatically added to .gitignore, making them ideal for private project-specific preferences that shouldn't be checked into version control.32 CLAUDE.local.md files are automatically added to .gitignore, making them ideal for private project-specific preferences that shouldn't be checked into version control.

27</Note>33</Note>

28 34

35## Auto memory

37Auto memory is a persistent directory where Claude records learnings, patterns, and insights as it works. Unlike CLAUDE.md files that contain instructions you write for Claude, auto memory contains notes Claude writes for itself based on what it discovers during sessions.

39<Note>

40 Auto memory is being rolled out gradually. If you aren't seeing auto memory, you can opt in by setting `CLAUDE_CODE_DISABLE_AUTO_MEMORY=0` in your environment.

41</Note>

43### What Claude remembers

45As Claude works, it may save things like:

47* Project patterns: build commands, test conventions, code style preferences

48* Debugging insights: solutions to tricky problems, common error causes

49* Architecture notes: key files, module relationships, important abstractions

50* Your preferences: communication style, workflow habits, tool choices

52### Where auto memory is stored

54Each project gets its own memory directory at `~/.claude/projects/<project>/memory/`. The `<project>` path is derived from the git repository root, so all subdirectories within the same repo share one auto memory directory. Git worktrees get separate memory directories. Outside a git repo, the working directory is used instead.

56The directory contains a `MEMORY.md` entrypoint and optional topic files:

58```text theme={null}

59~/.claude/projects/<project>/memory/

60├── MEMORY.md # Concise index, loaded into every session

61├── debugging.md # Detailed notes on debugging patterns

62├── api-conventions.md # API design decisions

63└── ... # Any other topic files Claude creates

64```

66`MEMORY.md` acts as an index of the memory directory. Claude reads and writes files in this directory throughout your session, using `MEMORY.md` to keep track of what's stored where.

68### How it works

70* The first 200 lines of `MEMORY.md` are loaded into Claude's system prompt at the start of every session. Content beyond 200 lines is not loaded automatically, and Claude is instructed to keep it concise by moving detailed notes into separate topic files.

71* Topic files like `debugging.md` or `patterns.md` are not loaded at startup. Claude reads them on demand using its standard file tools when it needs the information.

72* Claude reads and writes memory files during your session, so you'll see memory updates happen as you work.

74### Manage auto memory

76Auto memory files are markdown files you can edit at any time. Use `/memory` to open the file selector, which includes your auto memory entrypoint alongside your CLAUDE.md files.

78To ask Claude to save something specific, tell it directly: "remember that we use pnpm, not npm" or "save to memory that the API tests require a local Redis instance".

80When neither variable is set, auto memory follows the gradual rollout. The variable name uses double-negative logic: `DISABLE=0` means "don't disable" and forces auto memory on.

82```bash theme={null}

83export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 # Force off

84export CLAUDE_CODE_DISABLE_AUTO_MEMORY=0 # Force on

85```

29## CLAUDE.md imports87## CLAUDE.md imports

30 88

31CLAUDE.md files can import additional files using `@path/to/import` syntax. The following example imports 3 files:89CLAUDE.md files can import additional files using `@path/to/import` syntax. The following example imports 3 files:

plugins-reference.md +2 −0

Details

113* `SubagentStop`: When a subagent attempts to stop113* `SubagentStop`: When a subagent attempts to stop

114* `SessionStart`: At the beginning of sessions114* `SessionStart`: At the beginning of sessions

115* `SessionEnd`: At the end of sessions115* `SessionEnd`: At the end of sessions

116* `TeammateIdle`: When an agent team teammate is about to go idle

117* `TaskCompleted`: When a task is being marked as completed

116* `PreCompact`: Before conversation history is compacted118* `PreCompact`: Before conversation history is compacted

117 119

118**Hook types**:120**Hook types**:

settings.md +2 −1

Details

769| `CLAUDE_CODE_EFFORT_LEVEL` | Set the effort level for supported models. Values: `low`, `medium`, `high` (default). Lower effort is faster and cheaper, higher effort provides deeper reasoning. Currently supported with Opus 4.6 only. See [Adjust effort level](/en/model-config#adjust-effort-level) | |769| `CLAUDE_CODE_EFFORT_LEVEL` | Set the effort level for supported models. Values: `low`, `medium`, `high` (default). Lower effort is faster and cheaper, higher effort provides deeper reasoning. Currently supported with Opus 4.6 only. See [Adjust effort level](/en/model-config#adjust-effort-level) | |

770| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Set to `1` to disable Anthropic API-specific `anthropic-beta` headers. Use this if experiencing issues like "Unexpected value(s) for the `anthropic-beta` header" when using an LLM gateway with third-party providers | |770| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Set to `1` to disable Anthropic API-specific `anthropic-beta` headers. Use this if experiencing issues like "Unexpected value(s) for the `anthropic-beta` header" when using an LLM gateway with third-party providers | |

771| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | Set to `1` to disable [auto memory](/en/memory#auto-memory). Set to `0` to force auto memory on during the gradual rollout. When disabled, Claude does not create or load auto memory files | |

771| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | Set to `1` to disable all background task functionality, including the `run_in_background` parameter on Bash and subagent tools, auto-backgrounding, and the Ctrl+B shortcut | |772| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | Set to `1` to disable all background task functionality, including the `run_in_background` parameter on Bash and subagent tools, auto-backgrounding, and the Ctrl+B shortcut | |

772| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | Set to `1` to disable the "How is Claude doing?" session quality surveys. Also disabled when using third-party providers or when telemetry is disabled. See [Session quality surveys](/en/data-usage#session-quality-surveys) | |773| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | Set to `1` to disable the "How is Claude doing?" session quality surveys. Also disabled when using third-party providers or when telemetry is disabled. See [Session quality surveys](/en/data-usage#session-quality-surveys) | |

773| `CLAUDE_CODE_EXIT_AFTER_STOP_DELAY` | Time in milliseconds to wait after the query loop becomes idle before automatically exiting. Useful for automated workflows and scripts using SDK mode | |774| `CLAUDE_CODE_EXIT_AFTER_STOP_DELAY` | Time in milliseconds to wait after the query loop becomes idle before automatically exiting. Useful for automated workflows and scripts using SDK mode | |

822| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | Maximum number of characters for skill metadata shown to the [Skill tool](/en/skills#control-who-invokes-a-skill) (default: 15000). Legacy name kept for backwards compatibility. | |823| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | Override the character budget for skill metadata shown to the [Skill tool](/en/skills#control-who-invokes-a-skill). The budget scales dynamically at 2% of the context window, with a fallback of 16,000 characters. Legacy name kept for backwards compatibility | |

skills.md +10 −2

Details

107 Files in `.claude/commands/` still work and support the same [frontmatter](#frontmatter-reference). Skills are recommended since they support additional features like supporting files.107 Files in `.claude/commands/` still work and support the same [frontmatter](#frontmatter-reference). Skills are recommended since they support additional features like supporting files.

108</Note>108</Note>

109 109

110#### Skills from additional directories

111

112Skills defined in `.claude/skills/` within directories added via `--add-dir` are loaded automatically and picked up by live change detection, so you can edit them during a session without restarting.

113

114<Note>

115 CLAUDE.md files from `--add-dir` directories are not loaded by default. To load them, set `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1`. See [Load memory from additional directories](/en/memory#load-memory-from-additional-directories).

116</Note>

117

110## Configure skills118## Configure skills

111 119

112Skills are configured through YAML frontmatter at the top of `SKILL.md` and the markdown content that follows.120Skills are configured through YAML frontmatter at the top of `SKILL.md` and the markdown content that follows.

656 664

657### Claude doesn't see all my skills665### Claude doesn't see all my skills

658 666

659Skill descriptions are loaded into context so Claude knows what's available. If you have many skills, they may exceed the character budget (default 15,000 characters). Run `/context` to check for a warning about excluded skills.667Skill descriptions are loaded into context so Claude knows what's available. If you have many skills, they may exceed the character budget. The budget scales dynamically at 2% of the context window, with a fallback of 16,000 characters. Run `/context` to check for a warning about excluded skills.

660 668

661To increase the limit, set the `SLASH_COMMAND_TOOL_CHAR_BUDGET` environment variable.669To override the limit, set the `SLASH_COMMAND_TOOL_CHAR_BUDGET` environment variable.

662 670

663## Related resources671## Related resources

664 672

sub-agents.md +31 −6

Details

174}'174}'

175```175```

176 176

177The `--agents` flag accepts JSON with the same fields as [frontmatter](#supported-frontmatter-fields). Use `prompt` for the system prompt (equivalent to the markdown body in file-based subagents). See the [CLI reference](/en/cli-reference#agents-flag-format) for the full JSON format.177The `--agents` flag accepts JSON with the same [frontmatter](#supported-frontmatter-fields) fields as file-based subagents: `description`, `prompt`, `tools`, `disallowedTools`, `model`, `permissionMode`, `mcpServers`, `hooks`, `maxTurns`, `skills`, and `memory`. Use `prompt` for the system prompt, equivalent to the markdown body in file-based subagents. See the [CLI reference](/en/cli-reference#agents-flag-format) for the full JSON format.

178 178

179**Plugin subagents** come from [plugins](/en/plugins) you've installed. They appear in `/agents` alongside your custom subagents. See the [plugin components reference](/en/plugins-reference#agents) for details on creating plugin subagents.179**Plugin subagents** come from [plugins](/en/plugins) you've installed. They appear in `/agents` alongside your custom subagents. See the [plugin components reference](/en/plugins-reference#agents) for details on creating plugin subagents.

180 180

205The following fields can be used in the YAML frontmatter. Only `name` and `description` are required.205The following fields can be used in the YAML frontmatter. Only `name` and `description` are required.

206 206

208| :---------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |208| :---------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

209| `name` | Yes | Unique identifier using lowercase letters and hyphens |209| `name` | Yes | Unique identifier using lowercase letters and hyphens |

210| `description` | Yes | When Claude should delegate to this subagent |210| `description` | Yes | When Claude should delegate to this subagent |

211| `tools` | No | [Tools](#available-tools) the subagent can use. Inherits all tools if omitted |211| `tools` | No | [Tools](#available-tools) the subagent can use. Inherits all tools if omitted |

212| `disallowedTools` | No | Tools to deny, removed from inherited or specified list |212| `disallowedTools` | No | Tools to deny, removed from inherited or specified list |

213| `model` | No | [Model](#choose-a-model) to use: `sonnet`, `opus`, `haiku`, or `inherit`. Defaults to `inherit` |213| `model` | No | [Model](#choose-a-model) to use: `sonnet`, `opus`, `haiku`, or `inherit`. Defaults to `inherit` |

214| `permissionMode` | No | [Permission mode](#permission-modes): `default`, `acceptEdits`, `dontAsk`, `bypassPermissions`, or `plan` |214| `permissionMode` | No | [Permission mode](#permission-modes): `default`, `acceptEdits`, `delegate`, `dontAsk`, `bypassPermissions`, or `plan` |

215| `maxTurns` | No | Maximum number of agentic turns before the subagent stops |

215| `skills` | No | [Skills](/en/skills) to load into the subagent's context at startup. The full skill content is injected, not just made available for invocation. Subagents don't inherit skills from the parent conversation |216| `skills` | No | [Skills](/en/skills) to load into the subagent's context at startup. The full skill content is injected, not just made available for invocation. Subagents don't inherit skills from the parent conversation |

217| `mcpServers` | No | [MCP servers](/en/mcp) available to this subagent. Each entry is either a server name referencing an already-configured server (e.g., `"slack"`) or an inline definition with the server name as key and a full [MCP server config](/en/mcp#configure-mcp-servers) as value |

216| `hooks` | No | [Lifecycle hooks](#define-hooks-for-subagents) scoped to this subagent |218| `hooks` | No | [Lifecycle hooks](#define-hooks-for-subagents) scoped to this subagent |

217| `memory` | No | [Persistent memory scope](#enable-persistent-memory): `user`, `project`, or `local`. Enables cross-session learning |219| `memory` | No | [Persistent memory scope](#enable-persistent-memory): `user`, `project`, or `local`. Enables cross-session learning |

218 220

243---245---

244```246```

245 247

248#### Restrict which subagents can be spawned

249

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

251

252```yaml theme={null}

253---

254name: coordinator

255description: Coordinates work across specialized agents

256tools: Task(worker, researcher), Read, Bash

257---

258```

259

260This is an allowlist: only the `worker` and `researcher` subagents can be spawned. If the agent tries to spawn any other type, the request fails and the agent sees only the allowed types in its prompt. To block specific agents while allowing all others, use [`permissions.deny`](#disable-specific-subagents) instead.

261

262To allow spawning any subagent without restrictions, use `Task` without parentheses:

263

264```yaml theme={null}

265tools: Task, Read, Bash

266```

267

268If `Task` is omitted from the `tools` list entirely, the agent cannot spawn any subagents. This restriction only applies to agents running as the main thread with `claude --agent`. Subagents cannot spawn other subagents, so `Task(agent_type)` has no effect in subagent definitions.

269

246#### Permission modes270#### Permission modes

247 271

248The `permissionMode` field controls how the subagent handles permission prompts. Subagents inherit the permission context from the main conversation but can override the mode.272The `permissionMode` field controls how the subagent handles permission prompts. Subagents inherit the permission context from the main conversation but can override the mode.

249 273

250| Mode | Behavior |274| Mode | Behavior |

251| :------------------ | :----------------------------------------------------------------- |275| :------------------ | :------------------------------------------------------------------------------------------------------------------- |

279| `delegate` | Coordination-only mode for [agent team](/en/agent-teams#use-delegate-mode) leads. Restricts to team management tools |

257 282

435| :-------------- | :-------------- | :------------------------------- |460| :-------------- | :-------------- | :------------------------------- |

438 463

439`SubagentStart` supports matchers to target specific agent types by name. `SubagentStop` fires for all subagent completions regardless of matcher values. This example runs a setup script only when the `db-agent` subagent starts, and a cleanup script when any subagent stops:464Both events support matchers to target specific agent types by name. This example runs a setup script only when the `db-agent` subagent starts, and a cleanup script when any subagent stops:

440 465

441```json theme={null}466```json theme={null}

442{467{

Documentation 2026-02-06 21:06 UTC to 2026-02-07 21:05 UTC