Anthropic - Claude Code Docs Changes

agent-teams.md +404 −0 added

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# Orchestrate teams of Claude Code sessions

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

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.

11</Warning>

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.

17<Note>

18 Agent teams require Claude Code v2.1.32 or later. Check your version with `claude --version`.

19</Note>

21This page covers:

23* [When to use agent teams](#when-to-use-agent-teams), including best use cases and how they compare with subagents

24* [Starting a team](#start-your-first-agent-team)

25* [Controlling teammates](#control-your-agent-team), including display modes, task assignment, and delegation

26* [Best practices for parallel work](#best-practices)

28## When to use agent teams

30Agent teams are most effective for tasks where parallel exploration adds real value. See [use case examples](#use-case-examples) for full scenarios. The strongest use cases are:

32* **Research and review**: multiple teammates can investigate different aspects of a problem simultaneously, then share and challenge each other's findings

33* **New modules or features**: teammates can each own a separate piece without stepping on each other

34* **Debugging with competing hypotheses**: teammates test different theories in parallel and converge on the answer faster

35* **Cross-layer coordination**: changes that span frontend, backend, and tests, each owned by a different teammate

37Agent teams add coordination overhead and use significantly more tokens than a single session. They work best when teammates can operate independently. For sequential tasks, same-file edits, or work with many dependencies, a single session or [subagents](/en/sub-agents) are more effective.

39### Compare with subagents

41Both agent teams and [subagents](/en/sub-agents) let you parallelize work, but they operate differently. Choose based on whether your workers need to communicate with each other:

43<Frame caption="Subagents only report results back to the main agent and never talk to each other. In agent teams, teammates share a task list, claim work, and communicate directly with each other.">

44 <img src="https://mintcdn.com/claude-code/nsvRFSDNfpSU5nT7/images/subagents-vs-agent-teams-light.png?fit=max&auto=format&n=nsvRFSDNfpSU5nT7&q=85&s=2f8db9b4f3705dd3ab931fbe2d96e42a" className="dark:hidden" alt="Diagram comparing subagent and agent team architectures. Subagents are spawned by the main agent, do work, and report results back. Agent teams coordinate through a shared task list, with teammates communicating directly with each other." width="4245" height="1615" data-path="images/subagents-vs-agent-teams-light.png" />

46 <img src="https://mintcdn.com/claude-code/nsvRFSDNfpSU5nT7/images/subagents-vs-agent-teams-dark.png?fit=max&auto=format&n=nsvRFSDNfpSU5nT7&q=85&s=d573a037540f2ada6a9ae7d8285b46fd" className="hidden dark:block" alt="Diagram comparing subagent and agent team architectures. Subagents are spawned by the main agent, do work, and report results back. Agent teams coordinate through a shared task list, with teammates communicating directly with each other." width="4245" height="1615" data-path="images/subagents-vs-agent-teams-dark.png" />

47</Frame>

49| | Subagents | Agent teams |

50| :---------------- | :----------------------------------------------- | :-------------------------------------------------- |

51| **Context** | Own context window; results return to the caller | Own context window; fully independent |

52| **Communication** | Report results back to the main agent only | Teammates message each other directly |

53| **Coordination** | Main agent manages all work | Shared task list with self-coordination |

54| **Best for** | Focused tasks where only the result matters | Complex work requiring discussion and collaboration |

55| **Token cost** | Lower: results summarized back to main context | Higher: each teammate is a separate Claude instance |

57Use subagents when you need quick, focused workers that report back. Use agent teams when teammates need to share findings, challenge each other, and coordinate on their own.

59## Enable agent teams

61Agent teams are disabled by default. Enable them by setting the `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` environment variable to `1`, either in your shell environment or through [settings.json](/en/settings):

63```json settings.json theme={null}

64{

65 "env": {

66 "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"

67 }

68}

69```

71## Start your first agent team

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.

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

77```text theme={null}

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

79their codebase. Create an agent team to explore this from different angles: one

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

81```

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.

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.

87If you want each teammate in its own split pane, see [Choose a display mode](#choose-a-display-mode).

89## Control your agent team

91Tell the lead what you want in natural language. It handles team coordination, task assignment, and delegation based on your instructions.

93### Choose a display mode

95Agent teams support two display modes:

97* **In-process**: all teammates run inside your main terminal. Use Shift+Down to cycle through teammates and type to message them directly. Works in any terminal, no extra setup required.

98* **Split panes**: each teammate gets its own pane. You can see everyone's output at once and click into a pane to interact directly. Requires tmux, or iTerm2.

100<Note>

101 `tmux` has known limitations on certain operating systems and traditionally works best on macOS. Using `tmux -CC` in iTerm2 is the suggested entrypoint into `tmux`.

102</Note>

103

104The default is `"auto"`, which uses split panes if you're already running inside a tmux session, and in-process otherwise. The `"tmux"` setting enables split-pane mode and auto-detects whether to use tmux or iTerm2 based on your terminal. To override, set `teammateMode` in your [global config](/en/settings#global-config-settings) at `~/.claude.json`:

105

106```json theme={null}

107{

108 "teammateMode": "in-process"

109}

110```

111

112To force in-process mode for a single session, pass it as a flag:

113

114```bash theme={null}

115claude --teammate-mode in-process

116```

117

118Split-pane mode requires either [tmux](https://github.com/tmux/tmux/wiki) or iTerm2 with the [`it2` CLI](https://github.com/mkusaka/it2). To install manually:

119

120* **tmux**: install through your system's package manager. See the [tmux wiki](https://github.com/tmux/tmux/wiki/Installing) for platform-specific instructions.

121* **iTerm2**: install the [`it2` CLI](https://github.com/mkusaka/it2), then enable the Python API in **iTerm2 → Settings → General → Magic → Enable Python API**.

122

123### Specify teammates and models

124

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

126

127```text theme={null}

128Create a team with 4 teammates to refactor these modules in parallel.

129Use Sonnet for each teammate.

130```

131

132### Require plan approval for teammates

133

134For complex or risky tasks, you can require teammates to plan before implementing. The teammate works in read-only plan mode until the lead approves their approach:

135

136```text theme={null}

137Spawn an architect teammate to refactor the authentication module.

138Require plan approval before they make any changes.

139```

140

141When a teammate finishes planning, it sends a plan approval request to the lead. The lead reviews the plan and either approves it or rejects it with feedback. If rejected, the teammate stays in plan mode, revises based on the feedback, and resubmits. Once approved, the teammate exits plan mode and begins implementation.

142

143The lead makes approval decisions autonomously. To influence the lead's judgment, give it criteria in your prompt, such as "only approve plans that include test coverage" or "reject plans that modify the database schema."

144

145### Talk to teammates directly

146

147Each teammate is a full, independent Claude Code session. You can message any teammate directly to give additional instructions, ask follow-up questions, or redirect their approach.

148

149* **In-process mode**: use Shift+Down to cycle through teammates, then type to send them a message. Press Enter to view a teammate's session, then Escape to interrupt their current turn. Press Ctrl+T to toggle the task list.

150* **Split-pane mode**: click into a teammate's pane to interact with their session directly. Each teammate has a full view of their own terminal.

151

152### Assign and claim tasks

153

154The shared task list coordinates work across the team. The lead creates tasks and teammates work through them. Tasks have three states: pending, in progress, and completed. Tasks can also depend on other tasks: a pending task with unresolved dependencies cannot be claimed until those dependencies are completed.

155

156The lead can assign tasks explicitly, or teammates can self-claim:

157

158* **Lead assigns**: tell the lead which task to give to which teammate

159* **Self-claim**: after finishing a task, a teammate picks up the next unassigned, unblocked task on its own

160

161Task claiming uses file locking to prevent race conditions when multiple teammates try to claim the same task simultaneously.

162

163### Shut down teammates

164

165To gracefully end a teammate's session:

166

167```text theme={null}

168Ask the researcher teammate to shut down

169```

170

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

172

173### Clean up the team

174

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

176

177```text theme={null}

178Clean up the team

179```

180

181This 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.

182

183<Warning>

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

185</Warning>

186

187### Enforce quality gates with hooks

188

189Use [hooks](/en/hooks) to enforce rules when teammates finish work or tasks are created or completed:

190

191* [`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.

192* [`TaskCreated`](/en/hooks#taskcreated): runs when a task is being created. Exit with code 2 to prevent creation and send feedback.

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

194

195## How agent teams work

196

197This 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.

198

199### How Claude starts agent teams

200

201There are two ways agent teams get started:

202

203* **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.

204* **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.

205

206In both cases, you stay in control. Claude won't create a team without your approval.

207

208### Architecture

209

210An agent team consists of:

211

212| Component | Role |

213| :------------ | :----------------------------------------------------------------------------------------- |

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

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

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

217| **Mailbox** | Messaging system for communication between agents |

218

219See [Choose a display mode](#choose-a-display-mode) for display configuration options. Teammate messages arrive at the lead automatically.

220

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

222

223Teams and tasks are stored locally:

224

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

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

227

228The team config contains a `members` array with each teammate's name, agent ID, and agent type. Teammates can read this file to discover other team members.

229

230### Permissions

231

232Teammates start with the lead's permission settings. If the lead runs with `--dangerously-skip-permissions`, all teammates do too. After spawning, you can change individual teammate modes, but you can't set per-teammate modes at spawn time.

233

234### Context and communication

235

236Each teammate has its own context window. When spawned, a teammate loads the same project context as a regular session: CLAUDE.md, MCP servers, and skills. It also receives the spawn prompt from the lead. The lead's conversation history does not carry over.

237

238**How teammates share information:**

239

240* **Automatic message delivery**: when teammates send messages, they're delivered automatically to recipients. The lead doesn't need to poll for updates.

241* **Idle notifications**: when a teammate finishes and stops, they automatically notify the lead.

242* **Shared task list**: all agents can see task status and claim available work.

243

244**Teammate messaging:**

245

246* **message**: send a message to one specific teammate

247* **broadcast**: send to all teammates simultaneously. Use sparingly, as costs scale with team size.

248

249### Token usage

250

251Agent teams use significantly more tokens than a single session. Each teammate has its own context window, and token usage scales with the number of active teammates. For research, review, and new feature work, the extra tokens are usually worthwhile. For routine tasks, a single session is more cost-effective. See [agent team token costs](/en/costs#agent-team-token-costs) for usage guidance.

252

253## Use case examples

254

255These examples show how agent teams handle tasks where parallel exploration adds value.

256

257### Run a parallel code review

258

259A 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:

260

261```text theme={null}

262Create an agent team to review PR #142. Spawn three reviewers:

263- One focused on security implications

264- One checking performance impact

265- One validating test coverage

266Have them each review and report findings.

267```

268

269Each reviewer works from the same PR but applies a different filter. The lead synthesizes findings across all three after they finish.

270

271### Investigate with competing hypotheses

272

273When the root cause is unclear, a single agent tends to find one plausible explanation and stop looking. The prompt fights this by making teammates explicitly adversarial: each one's job is not only to investigate its own theory but to challenge the others'.

274

275```text theme={null}

276Users report the app exits after one message instead of staying connected.

277Spawn 5 agent teammates to investigate different hypotheses. Have them talk to

278each other to try to disprove each other's theories, like a scientific

279debate. Update the findings doc with whatever consensus emerges.

280```

281

282The debate structure is the key mechanism here. Sequential investigation suffers from anchoring: once one theory is explored, subsequent investigation is biased toward it.

283

284With multiple independent investigators actively trying to disprove each other, the theory that survives is much more likely to be the actual root cause.

285

286## Best practices

287

288### Give teammates enough context

289

290Teammates load project context automatically, including CLAUDE.md, MCP servers, and skills, but they don't inherit the lead's conversation history. See [Context and communication](#context-and-communication) for details. Include task-specific details in the spawn prompt:

291

292```text theme={null}

293Spawn a security reviewer teammate with the prompt: "Review the authentication module

294at src/auth/ for security vulnerabilities. Focus on token handling, session

295management, and input validation. The app uses JWT tokens stored in

296httpOnly cookies. Report any issues with severity ratings."

297```

298

299### Choose an appropriate team size

300

301There's no hard limit on the number of teammates, but practical constraints apply:

302

303* **Token costs scale linearly**: each teammate has its own context window and consumes tokens independently. See [agent team token costs](/en/costs#agent-team-token-costs) for details.

304* **Coordination overhead increases**: more teammates means more communication, task coordination, and potential for conflicts

305* **Diminishing returns**: beyond a certain point, additional teammates don't speed up work proportionally

306

307Start with 3-5 teammates for most workflows. This balances parallel work with manageable coordination. The examples in this guide use 3-5 teammates because that range works well across different task types.

308

309Having 5-6 [tasks](/en/agent-teams#architecture) per teammate keeps everyone productive without excessive context switching. If you have 15 independent tasks, 3 teammates is a good starting point.

310

311Scale up only when the work genuinely benefits from having teammates work simultaneously. Three focused teammates often outperform five scattered ones.

312

313### Size tasks appropriately

314

315* **Too small**: coordination overhead exceeds the benefit

316* **Too large**: teammates work too long without check-ins, increasing risk of wasted effort

317* **Just right**: self-contained units that produce a clear deliverable, such as a function, a test file, or a review

318

319<Tip>

320 The lead breaks work into tasks and assigns them to teammates automatically. If it isn't creating enough tasks, ask it to split the work into smaller pieces. Having 5-6 tasks per teammate keeps everyone productive and lets the lead reassign work if someone gets stuck.

321</Tip>

322

323### Wait for teammates to finish

324

325Sometimes the lead starts implementing tasks itself instead of waiting for teammates. If you notice this:

326

327```text theme={null}

328Wait for your teammates to complete their tasks before proceeding

329```

330

331### Start with research and review

332

333If you're new to agent teams, start with tasks that have clear boundaries and don't require writing code: reviewing a PR, researching a library, or investigating a bug. These tasks show the value of parallel exploration without the coordination challenges that come with parallel implementation.

334

335### Avoid file conflicts

336

337Two teammates editing the same file leads to overwrites. Break the work so each teammate owns a different set of files.

338

339### Monitor and steer

340

341Check in on teammates' progress, redirect approaches that aren't working, and synthesize findings as they come in. Letting a team run unattended for too long increases the risk of wasted effort.

342

343## Troubleshooting

344

345### Teammates not appearing

346

347If teammates aren't appearing after you ask Claude to create a team:

348

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

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

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

352 ```bash theme={null}

353 which tmux

354 ```

355* For iTerm2, verify the `it2` CLI is installed and the Python API is enabled in iTerm2 preferences.

356

357### Too many permission prompts

358

359Teammate permission requests bubble up to the lead, which can create friction. Pre-approve common operations in your [permission settings](/en/permissions) before spawning teammates to reduce interruptions.

360

361### Teammates stopping on errors

362

363Teammates may stop after encountering errors instead of recovering. Check their output using Shift+Down in in-process mode or by clicking the pane in split mode, then either:

364

365* Give them additional instructions directly

366* Spawn a replacement teammate to continue the work

367

368### Lead shuts down before work is done

369

370The lead may decide the team is finished before all tasks are actually complete. If this happens, tell it to keep going. You can also tell the lead to wait for teammates to finish before proceeding if it starts doing work instead of delegating.

371

372### Orphaned tmux sessions

373

374If a tmux session persists after the team ends, it may not have been fully cleaned up. List sessions and kill the one created by the team:

375

376```bash theme={null}

377tmux ls

378tmux kill-session -t <session-name>

379```

380

381## Limitations

382

383Agent teams are experimental. Current limitations to be aware of:

384

385* **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.

386* **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.

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

388* **One team per session**: a lead can only manage one team at a time. Clean up the current team before starting a new one.

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

390* **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.

391* **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.

392* **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.

393

394<Tip>

395 **`CLAUDE.md` works normally**: teammates read `CLAUDE.md` files from their working directory. Use this to provide project-specific guidance to all teammates.

396</Tip>

397

398## Next steps

399

400Explore related approaches for parallel work and delegation:

401

402* **Lightweight delegation**: [subagents](/en/sub-agents) spawn helper agents for research or verification within your session, better for tasks that don't need inter-agent coordination

403* **Manual parallel sessions**: [Git worktrees](/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees) let you run multiple Claude Code sessions yourself without automated team coordination

404* **Compare approaches**: see the [subagent vs agent team](/en/features-overview#compare-similar-features) comparison for a side-by-side breakdown

amazon-bedrock.md +41 −25

Details

11Before configuring Claude Code with Bedrock, ensure you have:11Before configuring Claude Code with Bedrock, ensure you have:

12 12

13* An AWS account with Bedrock access enabled13* An AWS account with Bedrock access enabled

~~14* Access to desired Claude models (for example, Claude Sonnet 4.5) in Bedrock~~14* Access to desired Claude models (for example, Claude Sonnet 4.6) in Bedrock

15* AWS CLI installed and configured (optional - only needed if you don't have another mechanism for getting credentials)15* AWS CLI installed and configured (optional - only needed if you don't have another mechanism for getting credentials)

16* Appropriate IAM permissions16* Appropriate IAM permissions

17 17

18<Note>

19 If you are deploying Claude Code to multiple users, [pin your model versions](#4-pin-model-versions) to prevent breakage when Anthropic releases new models.

20</Note>

18## Setup22## Setup

19 23

20### 1. Submit use case details24### 1. Submit use case details

120* When using Bedrock, the `/login` and `/logout` commands are disabled since authentication is handled through AWS credentials.124* When using Bedrock, the `/login` and `/logout` commands are disabled since authentication is handled through AWS credentials.

121* You can use settings files for environment variables like `AWS_PROFILE` that you don't want to leak to other processes. See [Settings](/en/settings) for more information.125* You can use settings files for environment variables like `AWS_PROFILE` that you don't want to leak to other processes. See [Settings](/en/settings) for more information.

122 126

123### 4. Model configuration127### 4. Pin model versions

128

129<Warning>

130 Pin specific model versions for every deployment. If you use model aliases (`sonnet`, `opus`, `haiku`) without pinning, Claude Code may attempt to use a newer model version that isn't available in your Bedrock account, breaking existing users when Anthropic releases updates.

131</Warning>

132

133Set these environment variables to specific Bedrock model IDs:

124 134

125Claude Code uses these default models for Bedrock:135```bash theme={null}

136export ANTHROPIC_DEFAULT_OPUS_MODEL='us.anthropic.claude-opus-4-6-v1'

137export ANTHROPIC_DEFAULT_SONNET_MODEL='us.anthropic.claude-sonnet-4-6'

138export ANTHROPIC_DEFAULT_HAIKU_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'

139```

140

141These variables use cross-region inference profile IDs (with the `us.` prefix). If you use a different region prefix or application inference profiles, adjust accordingly. For current and legacy model IDs, see [Models overview](https://platform.claude.com/docs/en/about-claude/models/overview). See [Model configuration](/en/model-config#pin-models-for-third-party-deployments) for the full list of environment variables.

142

143Claude Code uses these default models when no pinning variables are set:

126 144

127| Model type | Default value |145| Model type | Default value |

128| :--------------- | :------------------------------------------------- |146| :--------------- | :-------------------------------------------- |

131 149

132<Note>150To customize models further, use one of these methods:

133 For Bedrock users, Claude Code won't automatically upgrade from Haiku 3.5 to Haiku 4.5. To manually switch to a newer Haiku model, set the `ANTHROPIC_DEFAULT_HAIKU_MODEL` environment variable to the full model name (for example, `us.anthropic.claude-haiku-4-5-20251001-v1:0`).

134</Note>

~~135~~

136To customize models, use one of these methods:

137 151

138```bash theme={null}152```bash theme={null}

139# Using inference profile ID153# Using inference profile ID

140export ANTHROPIC_MODEL='global.anthropic.claude-sonnet-4-5-20250929-v1:0'154export ANTHROPIC_MODEL='global.anthropic.claude-sonnet-4-6'

141export ANTHROPIC_SMALL_FAST_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'155export ANTHROPIC_DEFAULT_HAIKU_MODEL='us.anthropic.claude-haiku-4-5-20251001-v1:0'

142 156

143# Using application inference profile ARN157# Using application inference profile ARN

144export ANTHROPIC_MODEL='arn:aws:bedrock:us-east-2:your-account-id:application-inference-profile/your-model-id'158export ANTHROPIC_MODEL='arn:aws:bedrock:us-east-2:your-account-id:application-inference-profile/your-model-id'

147export DISABLE_PROMPT_CACHING=1161export DISABLE_PROMPT_CACHING=1

148```162```

149 163

150<Note>[Prompt caching](https://docs.claude.com/en/docs/build-with-claude/prompt-caching) may not be available in all regions.</Note>164<Note>[Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) may not be available in all regions.</Note>

~~151~~

152### 5. Output token configuration

153 165

154These are the recommended token settings for Claude Code with Amazon Bedrock:166#### Map each model version to an inference profile

155 167

156```bash theme={null}168The `ANTHROPIC_DEFAULT_*_MODEL` environment variables configure one inference profile per model family. If your organization needs to expose several versions of the same family in the `/model` picker, each routed to its own application inference profile ARN, use the `modelOverrides` setting in your [settings file](/en/settings#settings-files) instead.

157# Recommended output token settings for Bedrock

158export CLAUDE_CODE_MAX_OUTPUT_TOKENS=4096

159export MAX_THINKING_TOKENS=1024

160```

161 169

162**Why these values:**170This example maps three Opus versions to distinct ARNs so users can switch between them without bypassing your organization's inference profiles:

163 171

164* **`CLAUDE_CODE_MAX_OUTPUT_TOKENS=4096`**: Bedrock's burndown throttling logic sets a minimum of 4096 tokens as the `max_token` penalty. Setting this lower won't reduce costs but may cut off long tool uses, causing the Claude Code agent loop to fail persistently. Claude Code typically uses less than 4096 output tokens without extended thinking, but may need this headroom for tasks involving significant file creation or Write tool usage.172```json theme={null}

173{

174 "modelOverrides": {

175 "claude-opus-4-6": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-46-prod",

176 "claude-opus-4-5-20251101": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-45-prod",

177 "claude-opus-4-1-20250805": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-41-prod"

178 }

179}

180```

165 181

166* **`MAX_THINKING_TOKENS=1024`**: This provides space for extended thinking without cutting off tool use responses, while still maintaining focused reasoning chains. This balance helps prevent trajectory changes that aren't always helpful for coding tasks specifically.182When a user selects one of these versions in `/model`, Claude Code calls Bedrock with the mapped ARN. Versions without an override fall back to the built-in Bedrock model ID or any matching inference profile discovered at startup. See [Override model IDs per version](/en/model-config#override-model-ids-per-version) for details on how overrides interact with `availableModels` and other model settings.

167 183

168## IAM configuration184## IAM configuration

169 185

210For details, see [Bedrock IAM documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/security-iam.html).226For details, see [Bedrock IAM documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/security-iam.html).

211 227

212<Note>228<Note>

213 We recommend creating a dedicated AWS account for Claude Code to simplify cost tracking and access control.229 Create a dedicated AWS account for Claude Code to simplify cost tracking and access control.

214</Note>230</Note>

215 231

216## AWS Guardrails232## AWS Guardrails

analytics.md +5 −1

Details

34 34

35You need the Owner role to configure analytics settings. A GitHub admin must install the GitHub app.35You need the Owner role to configure analytics settings. A GitHub admin must install the GitHub app.

36 36

37<Warning>

38 Contribution metrics are not available for organizations with [Zero Data Retention](/en/zero-data-retention) enabled. The analytics dashboard will show usage metrics only.

39</Warning>

37<Steps>41<Steps>

38 <Step title="Install the GitHub app">42 <Step title="Install the GitHub app">

39 A GitHub admin installs the Claude GitHub app on your organization's GitHub account at [github.com/apps/claude](https://github.com/apps/claude).43 A GitHub admin installs the Claude GitHub app on your organization's GitHub account at [github.com/apps/claude](https://github.com/apps/claude).

217 221

218* [Monitoring with OpenTelemetry](/en/monitoring-usage): export real-time metrics and events to your observability stack222* [Monitoring with OpenTelemetry](/en/monitoring-usage): export real-time metrics and events to your observability stack

219* [Manage costs effectively](/en/costs): set spend limits and optimize token usage223* [Manage costs effectively](/en/costs): set spend limits and optimize token usage

220* [Identity and access management](/en/iam): configure roles and permissions224* [Permissions](/en/permissions): configure roles and permissions

authentication.md +134 −0 added

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# Authentication

7> Log in to Claude Code and configure authentication for individuals, teams, and organizations.

9Claude Code supports multiple authentication methods depending on your setup. Individual users can log in with a Claude.ai account, while teams can use Claude for Teams or Enterprise, the Claude Console, or a cloud provider like Amazon Bedrock, Google Vertex AI, or Microsoft Foundry.

11## Log in to Claude Code

13After [installing Claude Code](/en/setup#install-claude-code), run `claude` in your terminal. On first launch, Claude Code opens a browser window for you to log in.

15If the browser doesn't open automatically, press `c` to copy the login URL to your clipboard, then paste it into your browser.

17You can authenticate with any of these account types:

19* **Claude Pro or Max subscription**: log in with your Claude.ai account. Subscribe at [claude.com/pricing](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_pro_max).

20* **Claude for Teams or Enterprise**: log in with the Claude.ai account your team admin invited you to.

21* **Claude Console**: log in with your Console credentials. Your admin must have [invited you](#claude-console-authentication) first.

22* **Cloud providers**: if your organization uses [Amazon Bedrock](/en/amazon-bedrock), [Google Vertex AI](/en/google-vertex-ai), or [Microsoft Foundry](/en/microsoft-foundry), set the required environment variables before running `claude`. No browser login is needed.

24To log out and re-authenticate, type `/logout` at the Claude Code prompt.

26If you're having trouble logging in, see [authentication troubleshooting](/en/troubleshooting#authentication-issues).

28## Set up team authentication

30For teams and organizations, you can configure Claude Code access in one of these ways:

32* [Claude for Teams or Enterprise](#claude-for-teams-or-enterprise), recommended for most teams

33* [Claude Console](#claude-console-authentication)

34* [Amazon Bedrock](/en/amazon-bedrock)

35* [Google Vertex AI](/en/google-vertex-ai)

36* [Microsoft Foundry](/en/microsoft-foundry)

38### Claude for Teams or Enterprise

40[Claude for Teams](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_teams#team-&-enterprise) and [Claude for Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_enterprise) provide the best experience for organizations using Claude Code. Team members get access to both Claude Code and Claude on the web with centralized billing and team management.

42* **Claude for Teams**: self-service plan with collaboration features, admin tools, and billing management. Best for smaller teams.

43* **Claude for Enterprise**: adds SSO, domain capture, role-based permissions, compliance API, and managed policy settings for organization-wide Claude Code configurations. Best for larger organizations with security and compliance requirements.

45<Steps>

46 <Step title="Subscribe">

47 Subscribe to [Claude for Teams](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_teams_step#team-&-enterprise) or contact sales for [Claude for Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_enterprise_step).

48 </Step>

50 <Step title="Invite team members">

51 Invite team members from the admin dashboard.

52 </Step>

54 <Step title="Install and log in">

55 Team members install Claude Code and log in with their Claude.ai accounts.

56 </Step>

57</Steps>

59### Claude Console authentication

61For organizations that prefer API-based billing, you can set up access through the Claude Console.

63<Steps>

64 <Step title="Create or use a Console account">

65 Use your existing Claude Console account or create a new one.

66 </Step>

68 <Step title="Add users">

69 You can add users through either method:

71 * Bulk invite users from within the Console: Settings -> Members -> Invite

72 * [Set up SSO](https://support.claude.com/en/articles/13132885-setting-up-single-sign-on-sso)

73 </Step>

75 <Step title="Assign roles">

76 When inviting users, assign one of:

78 * **Claude Code** role: users can only create Claude Code API keys

79 * **Developer** role: users can create any kind of API key

80 </Step>

82 <Step title="Users complete setup">

83 Each invited user needs to:

85 * Accept the Console invite

86 * [Check system requirements](/en/setup#system-requirements)

87 * [Install Claude Code](/en/setup#install-claude-code)

88 * Log in with Console account credentials

89 </Step>

90</Steps>

92### Cloud provider authentication

94For teams using Amazon Bedrock, Google Vertex AI, or Microsoft Foundry:

96<Steps>

97 <Step title="Follow provider setup">

98 Follow the [Bedrock docs](/en/amazon-bedrock), [Vertex docs](/en/google-vertex-ai), or [Microsoft Foundry docs](/en/microsoft-foundry).

99 </Step>

100

101 <Step title="Distribute configuration">

102 Distribute the environment variables and instructions for generating cloud credentials to your users. Read more about how to [manage configuration here](/en/settings).

103 </Step>

104

105 <Step title="Install Claude Code">

106 Users can [install Claude Code](/en/setup#install-claude-code).

107 </Step>

108</Steps>

109

110## Credential management

111

112Claude Code securely manages your authentication credentials:

113

114* **Storage location**: on macOS, credentials are stored in the encrypted macOS Keychain. On Linux and Windows, credentials are stored in `~/.claude/.credentials.json`, or under `$CLAUDE_CONFIG_DIR` if that variable is set. On Linux, the file is written with mode `0600`; on Windows, it inherits the access controls of your user profile directory.

115* **Supported authentication types**: Claude.ai credentials, Claude API credentials, Azure Auth, Bedrock Auth, and Vertex Auth.

116* **Custom credential scripts**: the [`apiKeyHelper`](/en/settings#available-settings) setting can be configured to run a shell script that returns an API key.

117* **Refresh intervals**: by default, `apiKeyHelper` is called after 5 minutes or on HTTP 401 response. Set `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` environment variable for custom refresh intervals.

118* **Slow helper notice**: if `apiKeyHelper` takes longer than 10 seconds to return a key, Claude Code displays a warning notice in the prompt bar showing the elapsed time. If you see this notice regularly, check whether your credential script can be optimized.

119

120`apiKeyHelper`, `ANTHROPIC_API_KEY`, and `ANTHROPIC_AUTH_TOKEN` apply to terminal CLI sessions only. Claude Desktop and remote sessions use OAuth exclusively and do not call `apiKeyHelper` or read API key environment variables.

121

122### Authentication precedence

123

124When multiple credentials are present, Claude Code chooses one in this order:

125

1261. Cloud provider credentials, when `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, or `CLAUDE_CODE_USE_FOUNDRY` is set. See [third-party integrations](/en/third-party-integrations) for setup.

1272. `ANTHROPIC_AUTH_TOKEN` environment variable. Sent as the `Authorization: Bearer` header. Use this when routing through an [LLM gateway or proxy](/en/llm-gateway) that authenticates with bearer tokens rather than Anthropic API keys.

1283. `ANTHROPIC_API_KEY` environment variable. Sent as the `X-Api-Key` header. Use this for direct Anthropic API access with a key from the [Claude Console](https://platform.claude.com). In interactive mode, you are prompted once to approve or decline the key, and your choice is remembered. To change it later, use the "Use custom API key" toggle in `/config`. In non-interactive mode (`-p`), the key is always used when present.

1294. [`apiKeyHelper`](/en/settings#available-settings) script output. Use this for dynamic or rotating credentials, such as short-lived tokens fetched from a vault.

1305. Subscription OAuth credentials from `/login`. This is the default for Claude Pro, Max, Team, and Enterprise users.

131

132If you have an active Claude subscription but also have `ANTHROPIC_API_KEY` set in your environment, the API key takes precedence once approved. This can cause authentication failures if the key belongs to a disabled or expired organization. Run `unset ANTHROPIC_API_KEY` to fall back to your subscription, and check `/status` to confirm which method is active.

133

134[Claude Code on the Web](/en/claude-code-on-the-web) always uses your subscription credentials. `ANTHROPIC_API_KEY` and `ANTHROPIC_AUTH_TOKEN` in the sandbox environment do not override them.

best-practices.md +41 −56

Details

20 20

21Claude's context window holds your entire conversation, including every message, every file Claude reads, and every command output. However, this can fill up fast. A single debugging session or codebase exploration might generate and consume tens of thousands of tokens.21Claude's context window holds your entire conversation, including every message, every file Claude reads, and every command output. However, this can fill up fast. A single debugging session or codebase exploration might generate and consume tens of thousands of tokens.

22 22

23This matters since LLM performance degrades as context fills. When the context window is getting full, Claude may start "forgetting" earlier instructions or making more mistakes. The context window is the most important resource to manage. For detailed strategies on reducing token usage, see [Reduce token usage](/en/costs#reduce-token-usage).23This matters since LLM performance degrades as context fills. When the context window is getting full, Claude may start "forgetting" earlier instructions or making more mistakes. The context window is the most important resource to manage. To see how a session fills up in practice, [watch an interactive walkthrough](/en/context-window) of what loads at startup and what each file read costs. Track context usage continuously with a [custom status line](/en/statusline), and see [Reduce token usage](/en/costs#reduce-token-usage) for strategies on reducing token usage.

24 24

25***25***

26 26

40| **Verify UI changes visually** | *"make the dashboard look better"* | *"\[paste screenshot] implement this design. take a screenshot of the result and compare it to the original. list differences and fix them"* |40| **Verify UI changes visually** | *"make the dashboard look better"* | *"\[paste screenshot] implement this design. take a screenshot of the result and compare it to the original. list differences and fix them"* |

41| **Address root causes, not symptoms** | *"the build is failing"* | *"the build fails with this error: \[paste error]. fix it and verify the build succeeds. address the root cause, don't suppress the error"* |41| **Address root causes, not symptoms** | *"the build is failing"* | *"the build fails with this error: \[paste error]. fix it and verify the build succeeds. address the root cause, don't suppress the error"* |

42 42

~~43UI changes can be verified using the [Claude in Chrome extension](/en/chrome). It opens a browser, tests the UI, and iterates until the code works.~~43UI changes can be verified using the [Claude in Chrome extension](/en/chrome). It opens new tabs in your browser, tests the UI, and iterates until the code works.

44 44

45Your verification can also be a test suite, a linter, or a Bash command that checks output. Invest in making your verification rock-solid.45Your verification can also be a test suite, a linter, or a Bash command that checks output. Invest in making your verification rock-solid.

46 46

148 Run `/init` to generate a starter CLAUDE.md file based on your current project structure, then refine over time.148 Run `/init` to generate a starter CLAUDE.md file based on your current project structure, then refine over time.

149</Tip>149</Tip>

150 150

151CLAUDE.md is a special file that Claude reads at the start of every conversation. Include Bash commands, code style, and workflow rules. This gives Claude persistent context **it can't infer from code alone**.151CLAUDE.md is a special file that Claude reads at the start of every conversation. Include Bash commands, code style, and workflow rules. This gives Claude persistent context it can't infer from code alone.

152 152

153The `/init` command analyzes your codebase to detect build systems, test frameworks, and code patterns, giving you a solid foundation to refine.153The `/init` command analyzes your codebase to detect build systems, test frameworks, and code patterns, giving you a solid foundation to refine.

154 154

194 194

195You can place CLAUDE.md files in several locations:195You can place CLAUDE.md files in several locations:

196 196

197* **Home folder (`~/.claude/CLAUDE.md`)**: Applies to all Claude sessions197* **Home folder (`~/.claude/CLAUDE.md`)**: applies to all Claude sessions

198* **Project root (`./CLAUDE.md`)**: Check into git to share with your team, or name it `CLAUDE.local.md` and `.gitignore` it198* **Project root (`./CLAUDE.md`)**: check into git to share with your team

199* **Parent directories**: Useful for monorepos where both `root/CLAUDE.md` and `root/foo/CLAUDE.md` are pulled in automatically199* **Parent directories**: useful for monorepos where both `root/CLAUDE.md` and `root/foo/CLAUDE.md` are pulled in automatically

200* **Child directories**: Claude pulls in child CLAUDE.md files on demand when working with files in those directories200* **Child directories**: Claude pulls in child CLAUDE.md files on demand when working with files in those directories

201 201

202### Configure permissions202### Configure permissions

203 203

204<Tip>204<Tip>

205 Use `/permissions` to allowlist safe commands or `/sandbox` for OS-level isolation. This reduces interruptions while keeping you in control.205 Use [auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) to let a classifier handle approvals, `/permissions` to allowlist specific commands, or `/sandbox` for OS-level isolation. Each reduces interruptions while keeping you in control.

206</Tip>206</Tip>

207 207

208By default, Claude Code requests permission for actions that might modify your system: file writes, Bash commands, MCP tools, etc. This is safe but tedious. After the tenth approval you're not really reviewing anymore, you're just clicking through. There are two ways to reduce these interruptions:208By default, Claude Code requests permission for actions that might modify your system: file writes, Bash commands, MCP tools, etc. This is safe but tedious. After the tenth approval you're not really reviewing anymore, you're just clicking through. There are three ways to reduce these interruptions:

209 209

210* **Permission allowlists**: Permit specific tools you know are safe (like `npm run lint` or `git commit`)210* **Auto mode**: a separate classifier model reviews commands and blocks only what looks risky: scope escalation, unknown infrastructure, or hostile-content-driven actions. Best when you trust the general direction of a task but don't want to click through every step

211* **Sandboxing**: Enable OS-level isolation that restricts filesystem and network access, allowing Claude to work more freely within defined boundaries211* **Permission allowlists**: permit specific tools you know are safe, like `npm run lint` or `git commit`

212* **Sandboxing**: enable OS-level isolation that restricts filesystem and network access, allowing Claude to work more freely within defined boundaries

212 213

213Alternatively, use `--dangerously-skip-permissions` to bypass all permission checks for contained workflows like fixing lint errors or generating boilerplate.214Read more about [permission modes](/en/permission-modes), [permission rules](/en/permissions), and [sandboxing](/en/sandboxing).

~~214~~

215<Warning>

216 Letting Claude run arbitrary commands can result in data loss, system corruption, or data exfiltration via prompt injection. Only use `--dangerously-skip-permissions` in a sandbox without internet access.

217</Warning>

~~218~~

219Read more about [configuring permissions](/en/settings) and [enabling sandboxing](/en/sandboxing#sandboxing).

220 215

221### Use CLI tools216### Use CLI tools

222 217

244 239

245[Hooks](/en/hooks-guide) run scripts automatically at specific points in Claude's workflow. Unlike CLAUDE.md instructions which are advisory, hooks are deterministic and guarantee the action happens.240[Hooks](/en/hooks-guide) run scripts automatically at specific points in Claude's workflow. Unlike CLAUDE.md instructions which are advisory, hooks are deterministic and guarantee the action happens.

246 241

247Claude can write hooks for you. Try prompts like *"Write a hook that runs eslint after every file edit"* or *"Write a hook that blocks writes to the migrations folder."* Run `/hooks` for interactive configuration, or edit `.claude/settings.json` directly.242Claude can write hooks for you. Try prompts like *"Write a hook that runs eslint after every file edit"* or *"Write a hook that blocks writes to the migrations folder."* Edit `.claude/settings.json` directly to configure hooks by hand, and run `/hooks` to browse what's configured.

248 243

249### Create skills244### Create skills

250 245

356 351

357Claude asks about things you might not have considered yet, including technical implementation, UI/UX, edge cases, and tradeoffs.352Claude asks about things you might not have considered yet, including technical implementation, UI/UX, edge cases, and tradeoffs.

358 353

359```354```text theme={null}

360I want to build [brief description]. Interview me in detail using the AskUserQuestion tool.355I want to build [brief description]. Interview me in detail using the AskUserQuestion tool.

361 356

362Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs. Don't ask obvious questions, dig into the hard parts I might not have considered.357Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs. Don't ask obvious questions, dig into the hard parts I might not have considered.

380 375

381The best results come from tight feedback loops. Though Claude occasionally solves problems perfectly on the first attempt, correcting it quickly generally produces better solutions faster.376The best results come from tight feedback loops. Though Claude occasionally solves problems perfectly on the first attempt, correcting it quickly generally produces better solutions faster.

382 377

383* **`Esc`**: Stop Claude mid-action with the `Esc` key. Context is preserved, so you can redirect.378* **`Esc`**: stop Claude mid-action with the `Esc` key. Context is preserved, so you can redirect.

384* **`Esc + Esc` or `/rewind`**: Press `Esc` twice or run `/rewind` to open the rewind menu and restore previous conversation and code state.379* **`Esc + Esc` or `/rewind`**: press `Esc` twice or run `/rewind` to open the rewind menu and restore previous conversation and code state, or summarize from a selected message.

385* **`"Undo that"`**: Have Claude revert its changes.380* **`"Undo that"`**: have Claude revert its changes.

386* **`/clear`**: Reset context between unrelated tasks. Long sessions with irrelevant context can reduce performance.381* **`/clear`**: reset context between unrelated tasks. Long sessions with irrelevant context can reduce performance.

387 382

388If you've corrected Claude more than twice on the same issue in one session, the context is cluttered with failed approaches. Run `/clear` and start fresh with a more specific prompt that incorporates what you learned. A clean session with a better prompt almost always outperforms a long session with accumulated corrections.383If you've corrected Claude more than twice on the same issue in one session, the context is cluttered with failed approaches. Run `/clear` and start fresh with a more specific prompt that incorporates what you learned. A clean session with a better prompt almost always outperforms a long session with accumulated corrections.

389 384

400* Use `/clear` frequently between tasks to reset the context window entirely395* Use `/clear` frequently between tasks to reset the context window entirely

401* When auto compaction triggers, Claude summarizes what matters most, including code patterns, file states, and key decisions396* When auto compaction triggers, Claude summarizes what matters most, including code patterns, file states, and key decisions

402* For more control, run `/compact <instructions>`, like `/compact Focus on the API changes`397* For more control, run `/compact <instructions>`, like `/compact Focus on the API changes`

398* To compact only part of the conversation, use `Esc + Esc` or `/rewind`, select a message checkpoint, and choose **Summarize from here**. This condenses messages from that point forward while keeping earlier context intact.

403* Customize compaction behavior in CLAUDE.md with instructions like `"When compacting, always preserve the full list of modified files and any test commands"` to ensure critical context survives summarization399* Customize compaction behavior in CLAUDE.md with instructions like `"When compacting, always preserve the full list of modified files and any test commands"` to ensure critical context survives summarization

400* For quick questions that don't need to stay in context, use [`/btw`](/en/interactive-mode#side-questions-with-btw). The answer appears in a dismissible overlay and never enters conversation history, so you can check a detail without growing context.

404 401

405### Use subagents for investigation402### Use subagents for investigation

406 403

410 407

411Since context is your fundamental constraint, subagents are one of the most powerful tools available. When Claude researches a codebase it reads lots of files, all of which consume your context. Subagents run in separate context windows and report back summaries:408Since context is your fundamental constraint, subagents are one of the most powerful tools available. When Claude researches a codebase it reads lots of files, all of which consume your context. Subagents run in separate context windows and report back summaries:

412 409

413```410```text theme={null}

414Use subagents to investigate how our authentication system handles token411Use subagents to investigate how our authentication system handles token

415refresh, and whether we have any existing OAuth utilities I should reuse.412refresh, and whether we have any existing OAuth utilities I should reuse.

416```413```

419 416

420You can also use subagents for verification after Claude implements something:417You can also use subagents for verification after Claude implements something:

421 418

422```419```text theme={null}

423use a subagent to review this code for edge cases420use a subagent to review this code for edge cases

424```421```

425 422

429 Every action Claude makes creates a checkpoint. You can restore conversation, code, or both to any previous checkpoint.426 Every action Claude makes creates a checkpoint. You can restore conversation, code, or both to any previous checkpoint.

430</Tip>427</Tip>

431 428

432Claude automatically checkpoints before changes. Double-tap `Escape` or run `/rewind` to open the checkpoint menu. You can restore conversation only (keep code changes), restore code only (keep conversation), or restore both.429Claude automatically checkpoints before changes. Double-tap `Escape` or run `/rewind` to open the rewind menu. You can restore conversation only, restore code only, restore both, or summarize from a selected message. See [Checkpointing](/en/checkpointing) for details.

433 430

434Instead of carefully planning every move, you can tell Claude to try something risky. If it doesn't work, rewind and try a different approach. Checkpoints persist across sessions, so you can close your terminal and still rewind later.431Instead of carefully planning every move, you can tell Claude to try something risky. If it doesn't work, rewind and try a different approach. Checkpoints persist across sessions, so you can close your terminal and still rewind later.

435 432

443 Run `claude --continue` to pick up where you left off, or `--resume` to choose from recent sessions.440 Run `claude --continue` to pick up where you left off, or `--resume` to choose from recent sessions.

444</Tip>441</Tip>

445 442

446Claude Code saves conversations locally. When a task spans multiple sessions (you start a feature, get interrupted, come back the next day) you don't have to re-explain the context:443Claude Code saves conversations locally. When a task spans multiple sessions, you don't have to re-explain the context:

447 444

448```bash theme={null}445```bash theme={null}

449claude --continue # Resume the most recent conversation446claude --continue # Resume the most recent conversation

450claude --resume # Select from recent conversations447claude --resume # Select from recent conversations

451```448```

452 449

453Use `/rename` to give sessions descriptive names (`"oauth-migration"`, `"debugging-memory-leak"`) so you can find them later. Treat sessions like branches. Different workstreams can have separate, persistent contexts.450Use `/rename` to give sessions descriptive names like `"oauth-migration"` or `"debugging-memory-leak"` so you can find them later. Treat sessions like branches: different workstreams can have separate, persistent contexts.

454 451

455***452***

456 453

457## Automate and scale454## Automate and scale

458 455

459Once you're effective with one Claude, multiply your output with parallel sessions, headless mode, and fan-out patterns.456Once you're effective with one Claude, multiply your output with parallel sessions, non-interactive mode, and fan-out patterns.

460 457

461Everything so far assumes one human, one Claude, and one conversation. But Claude Code scales horizontally. The techniques in this section show how you can get more done.458Everything so far assumes one human, one Claude, and one conversation. But Claude Code scales horizontally. The techniques in this section show how you can get more done.

462 459

463### Run headless mode460### Run non-interactive mode

464 461

465<Tip>462<Tip>

466 Use `claude -p "prompt"` in CI, pre-commit hooks, or scripts. Add `--output-format stream-json` for streaming JSON output.463 Use `claude -p "prompt"` in CI, pre-commit hooks, or scripts. Add `--output-format stream-json` for streaming JSON output.

467</Tip>464</Tip>

468 465

469With `claude -p "your prompt"`, you can run Claude headlessly, without an interactive session. Headless mode is how you integrate Claude into CI pipelines, pre-commit hooks, or any automated workflow. The output formats (plain text, JSON, streaming JSON) let you parse results programmatically.466With `claude -p "your prompt"`, you can run Claude non-interactively, without a session. Non-interactive mode is how you integrate Claude into CI pipelines, pre-commit hooks, or any automated workflow. The output formats let you parse results programmatically: plain text, JSON, or streaming JSON.

470 467

471```bash theme={null}468```bash theme={null}

472# One-off queries469# One-off queries

485 Run multiple Claude sessions in parallel to speed up development, run isolated experiments, or start complex workflows.482 Run multiple Claude sessions in parallel to speed up development, run isolated experiments, or start complex workflows.

486</Tip>483</Tip>

487 484

488There are two main ways to run parallel sessions:485There are three main ways to run parallel sessions:

489 486

490* [Claude Desktop](/en/desktop): Manage multiple local sessions visually. Each session gets its own isolated worktree.487* [Claude Code desktop app](/en/desktop#work-in-parallel-with-sessions): Manage multiple local sessions visually. Each session gets its own isolated worktree.

491* [Claude Code on the web](/en/claude-code-on-the-web): Run on Anthropic's secure cloud infrastructure in isolated VMs.488* [Claude Code on the web](/en/claude-code-on-the-web): Run on Anthropic's secure cloud infrastructure in isolated VMs.

489* [Agent teams](/en/agent-teams): Automated coordination of multiple sessions with shared tasks, messaging, and a team lead.

492 490

493Beyond parallelizing work, multiple sessions enable quality-focused workflows. A fresh context improves code review since Claude won't be biased toward code it just wrote.491Beyond parallelizing work, multiple sessions enable quality-focused workflows. A fresh context improves code review since Claude won't be biased toward code it just wrote.

494 492

537 535

538Use `--verbose` for debugging during development, and turn it off in production.536Use `--verbose` for debugging during development, and turn it off in production.

539 537

540### Safe Autonomous Mode538### Run autonomously with auto mode

541 539

542Use `claude --dangerously-skip-permissions` to bypass all permission checks and let Claude work uninterrupted. This works well for workflows like fixing lint errors or generating boilerplate code.540For uninterrupted execution with background safety checks, use [auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode). A classifier model reviews commands before they run, blocking scope escalation, unknown infrastructure, and hostile-content-driven actions while letting routine work proceed without prompts.

543 541

544<Warning>542```bash theme={null}

545 Letting Claude run arbitrary commands is risky and can result in data loss, system corruption, or data exfiltration (e.g., via prompt injection attacks). To minimize these risks, use `--dangerously-skip-permissions` in a container without internet access.543claude --permission-mode auto -p "fix all lint errors"

544```

546 545

547 With sandboxing enabled (`/sandbox`), you get similar autonomy with better security. Sandbox defines upfront boundaries rather than bypassing all checks.546For non-interactive runs with the `-p` flag, auto mode aborts if the classifier repeatedly blocks actions, since there is no user to fall back to. See [when auto mode falls back](/en/permission-modes#when-auto-mode-falls-back) for thresholds.

548</Warning>

549 547

550***548***

551 549

578 576

579## Related resources577## Related resources

580 578

581<CardGroup cols={2}>579* [How Claude Code works](/en/how-claude-code-works): the agentic loop, tools, and context management

582 <Card title="How Claude Code works" icon="gear" href="/en/how-claude-code-works">580* [Extend Claude Code](/en/features-overview): skills, hooks, MCP, subagents, and plugins

583 Understand the agentic loop, tools, and context management581* [Common workflows](/en/common-workflows): step-by-step recipes for debugging, testing, PRs, and more

584 </Card>582* [CLAUDE.md](/en/memory): store project conventions and persistent context

~~585~~

586 <Card title="Extend Claude Code" icon="puzzle-piece" href="/en/features-overview">

587 Choose between skills, hooks, MCP, subagents, and plugins

588 </Card>

~~589~~

590 <Card title="Common workflows" icon="list-check" href="/en/common-workflows">

591 Step-by-step recipes for debugging, testing, PRs, and more

592 </Card>

~~593~~

594 <Card title="CLAUDE.md" icon="file-lines" href="/en/memory">

595 Store project conventions and persistent context

596 </Card>

597</CardGroup>

channels.md +357 −0 added

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# Push events into a running session with channels

7> Use channels to push messages, alerts, and webhooks into your Claude Code session from an MCP server. Forward CI results, chat messages, and monitoring events so Claude can react while you're away.

9<Note>

10 Channels are in [research preview](#research-preview) and require Claude Code v2.1.80 or later. They require claude.ai login. Console and API key authentication is not supported. Team and Enterprise organizations must [explicitly enable them](#enterprise-controls).

11</Note>

13A channel is an MCP server that pushes events into your running Claude Code session, so Claude can react to things that happen while you're not at the terminal. Channels can be two-way: Claude reads the event and replies back through the same channel, like a chat bridge. Events only arrive while the session is open, so for an always-on setup you run Claude in a background process or persistent terminal.

15Unlike integrations that spawn a fresh cloud session or wait to be polled, the event arrives in the session you already have open: see [how channels compare](#how-channels-compare).

17You install a channel as a plugin and configure it with your own credentials. Telegram, Discord, and iMessage are included in the research preview.

19When Claude replies through a channel, you see the inbound message in your terminal but not the reply text. The terminal shows the tool call and a confirmation (like "sent"), and the actual reply appears on the other platform.

21This page covers:

23* [Supported channels](#supported-channels): Telegram, Discord, and iMessage setup

24* [Install and run a channel](#quickstart) with fakechat, a localhost demo

25* [Who can push messages](#security): sender allowlists and how you pair

26* [Enable channels for your organization](#enterprise-controls) on Team and Enterprise

27* [How channels compare](#how-channels-compare) to web sessions, Slack, MCP, and Remote Control

29To build your own channel, see the [Channels reference](/en/channels-reference).

31## Supported channels

33Each supported channel is a plugin that requires [Bun](https://bun.sh). For a hands-on demo of the plugin flow before connecting a real platform, try the [fakechat quickstart](#quickstart).

35<Tabs>

36 <Tab title="Telegram">

37 View the full [Telegram plugin source](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/telegram).

39 <Steps>

40 <Step title="Create a Telegram bot">

41 Open [BotFather](https://t.me/BotFather) in Telegram and send `/newbot`. Give it a display name and a unique username ending in `bot`. Copy the token BotFather returns.

42 </Step>

44 <Step title="Install the plugin">

45 In Claude Code, run:

47 ```

48 /plugin install telegram@claude-plugins-official

49 ```

51 If Claude Code reports that the plugin is not found in any marketplace, your marketplace is either missing or outdated. Run `/plugin marketplace update claude-plugins-official` to refresh it, or `/plugin marketplace add anthropics/claude-plugins-official` if you haven't added it before. Then retry the install.

53 After installing, run `/reload-plugins` to activate the plugin's configure command.

54 </Step>

56 <Step title="Configure your token">

57 Run the configure command with the token from BotFather:

59 ```

60 /telegram:configure <token>

61 ```

63 This saves it to `~/.claude/channels/telegram/.env`. You can also set `TELEGRAM_BOT_TOKEN` in your shell environment before launching Claude Code.

64 </Step>

66 <Step title="Restart with channels enabled">

67 Exit Claude Code and restart with the channel flag. This starts the Telegram plugin, which begins polling for messages from your bot:

69 ```bash theme={null}

70 claude --channels plugin:telegram@claude-plugins-official

71 ```

72 </Step>

74 <Step title="Pair your account">

75 Open Telegram and send any message to your bot. The bot replies with a pairing code.

77 <Note>If your bot doesn't respond, make sure Claude Code is running with `--channels` from the previous step. The bot can only reply while the channel is active.</Note>

79 Back in Claude Code, run:

81 ```

82 /telegram:access pair <code>

83 ```

85 Then lock down access so only your account can send messages:

87 ```

88 /telegram:access policy allowlist

89 ```

90 </Step>

91 </Steps>

92 </Tab>

94 <Tab title="Discord">

95 View the full [Discord plugin source](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/discord).

97 <Steps>

98 <Step title="Create a Discord bot">

99 Go to the [Discord Developer Portal](https://discord.com/developers/applications), click **New Application**, and name it. In the **Bot** section, create a username, then click **Reset Token** and copy the token.

100 </Step>

101

102 <Step title="Enable Message Content Intent">

103 In your bot's settings, scroll to **Privileged Gateway Intents** and enable **Message Content Intent**.

104 </Step>

105

106 <Step title="Invite the bot to your server">

107 Go to **OAuth2 > URL Generator**. Select the `bot` scope and enable these permissions:

108

109 * View Channels

110 * Send Messages

111 * Send Messages in Threads

112 * Read Message History

113 * Attach Files

114 * Add Reactions

115

116 Open the generated URL to add the bot to your server.

117 </Step>

118

119 <Step title="Install the plugin">

120 In Claude Code, run:

121

122 ```

123 /plugin install discord@claude-plugins-official

124 ```

125

126 If Claude Code reports that the plugin is not found in any marketplace, your marketplace is either missing or outdated. Run `/plugin marketplace update claude-plugins-official` to refresh it, or `/plugin marketplace add anthropics/claude-plugins-official` if you haven't added it before. Then retry the install.

127

128 After installing, run `/reload-plugins` to activate the plugin's configure command.

129 </Step>

130

131 <Step title="Configure your token">

132 Run the configure command with the bot token you copied:

133

134 ```

135 /discord:configure <token>

136 ```

137

138 This saves it to `~/.claude/channels/discord/.env`. You can also set `DISCORD_BOT_TOKEN` in your shell environment before launching Claude Code.

139 </Step>

140

141 <Step title="Restart with channels enabled">

142 Exit Claude Code and restart with the channel flag. This connects the Discord plugin so your bot can receive and respond to messages:

143

144 ```bash theme={null}

145 claude --channels plugin:discord@claude-plugins-official

146 ```

147 </Step>

148

149 <Step title="Pair your account">

150 DM your bot on Discord. The bot replies with a pairing code.

151

152 <Note>If your bot doesn't respond, make sure Claude Code is running with `--channels` from the previous step. The bot can only reply while the channel is active.</Note>

153

154 Back in Claude Code, run:

155

156 ```

157 /discord:access pair <code>

158 ```

159

160 Then lock down access so only your account can send messages:

161

162 ```

163 /discord:access policy allowlist

164 ```

165 </Step>

166 </Steps>

167 </Tab>

168

169 <Tab title="iMessage">

170 View the full [iMessage plugin source](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/imessage).

171

172 The iMessage channel reads your Messages database directly and sends replies through AppleScript. It requires macOS and needs no bot token or external service.

173

174 <Steps>

175 <Step title="Grant Full Disk Access">

176 The Messages database at `~/Library/Messages/chat.db` is protected by macOS. The first time the server reads it, macOS prompts for access: click **Allow**. The prompt names whichever app launched Bun, such as Terminal, iTerm, or your IDE.

177

178 If the prompt doesn't appear or you clicked Don't Allow, grant access manually under **System Settings > Privacy & Security > Full Disk Access** and add your terminal. Without this, the server exits immediately with `authorization denied`.

179 </Step>

180

181 <Step title="Install the plugin">

182 In Claude Code, run:

183

184 ```

185 /plugin install imessage@claude-plugins-official

186 ```

187

188 If Claude Code reports that the plugin is not found in any marketplace, your marketplace is either missing or outdated. Run `/plugin marketplace update claude-plugins-official` to refresh it, or `/plugin marketplace add anthropics/claude-plugins-official` if you haven't added it before. Then retry the install.

189 </Step>

190

191 <Step title="Restart with channels enabled">

192 Exit Claude Code and restart with the channel flag:

193

194 ```bash theme={null}

195 claude --channels plugin:imessage@claude-plugins-official

196 ```

197 </Step>

198

199 <Step title="Text yourself">

200 Open Messages on any device signed into your Apple ID and send a message to yourself. It reaches Claude immediately: self-chat bypasses access control with no setup.

201

202 <Note>The first reply Claude sends triggers a macOS Automation prompt asking if your terminal can control Messages. Click **OK**.</Note>

203 </Step>

204

205 <Step title="Allow other senders">

206 By default, only your own messages pass through. To let another contact reach Claude, add their handle:

207

208 ```

209 /imessage:access allow +15551234567

210 ```

211

212 Handles are phone numbers in `+country` format or Apple ID emails like `user@example.com`.

213 </Step>

214 </Steps>

215 </Tab>

216</Tabs>

217

218You can also [build your own channel](/en/channels-reference) for systems that don't have a plugin yet.

219

220## Quickstart

221

222Fakechat is an officially supported demo channel that runs a chat UI on localhost, with nothing to authenticate and no external service to configure.

223

224Once you install and enable fakechat, you can type in the browser and the message arrives in your Claude Code session. Claude replies, and the reply shows up back in the browser. After you've tested the fakechat interface, try out [Telegram](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/telegram), [Discord](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/discord), or [iMessage](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/imessage).

225

226To try the fakechat demo, you'll need:

227

228* Claude Code [installed and authenticated](/en/quickstart#step-1-install-claude-code) with a claude.ai account

229* [Bun](https://bun.sh) installed. The pre-built channel plugins are Bun scripts. Check with `bun --version`; if that fails, [install Bun](https://bun.sh/docs/installation).

230* **Team/Enterprise users**: your organization admin must [enable channels](#enterprise-controls) in managed settings

231

232<Steps>

233 <Step title="Install the fakechat channel plugin">

234 Start a Claude Code session and run the install command:

235

236 ```text theme={null}

237 /plugin install fakechat@claude-plugins-official

238 ```

239

240 If Claude Code reports that the plugin is not found in any marketplace, your marketplace is either missing or outdated. Run `/plugin marketplace update claude-plugins-official` to refresh it, or `/plugin marketplace add anthropics/claude-plugins-official` if you haven't added it before. Then retry the install.

241 </Step>

242

243 <Step title="Restart with the channel enabled">

244 Exit Claude Code, then restart with `--channels` and pass the fakechat plugin you installed:

245

246 ```bash theme={null}

247 claude --channels plugin:fakechat@claude-plugins-official

248 ```

249

250 The fakechat server starts automatically.

251

252 <Tip>

253 You can pass several plugins to `--channels`, space-separated.

254 </Tip>

255 </Step>

256

257 <Step title="Push a message in">

258 Open the fakechat UI at [http://localhost:8787](http://localhost:8787) and type a message:

259

260 ```text theme={null}

261 hey, what's in my working directory?

262 ```

263

264 The message arrives in your Claude Code session as a `<channel source="fakechat">` event. Claude reads it, does the work, and calls fakechat's `reply` tool. The answer shows up in the chat UI.

265 </Step>

266</Steps>

267

268If Claude hits a permission prompt while you're away from the terminal, the session pauses until you respond. Channel servers that declare the [permission relay capability](/en/channels-reference#relay-permission-prompts) can forward these prompts to you so you can approve or deny remotely. For unattended use, [`--dangerously-skip-permissions`](/en/permission-modes#skip-all-checks-with-bypasspermissions-mode) bypasses prompts entirely, but only use it in environments you trust.

269

270## Security

271

272Every approved channel plugin maintains a sender allowlist: only IDs you've added can push messages, and everyone else is silently dropped.

273

274Telegram and Discord bootstrap the list by pairing:

275

2761. Find your bot in Telegram or Discord and send it any message

2772. The bot replies with a pairing code

2783. In your Claude Code session, approve the code when prompted

2794. Your sender ID is added to the allowlist

280

281iMessage works differently: texting yourself bypasses the gate automatically, and you add other contacts by handle with `/imessage:access allow`.

282

283On top of that, you control which servers are enabled each session with `--channels`, and on Team and Enterprise plans your organization controls availability with [`channelsEnabled`](#enterprise-controls).

284

285Being in `.mcp.json` isn't enough to push messages: a server also has to be named in `--channels`.

286

287The allowlist also gates [permission relay](/en/channels-reference#relay-permission-prompts) if the channel declares it. Anyone who can reply through the channel can approve or deny tool use in your session, so only allowlist senders you trust with that authority.

288

289## Enterprise controls

290

291On Team and Enterprise plans, channels are off by default. Admins control availability through two [managed settings](/en/settings) that users cannot override:

292

293| Setting | Purpose | When not configured |

294| :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------- |

295| `channelsEnabled` | Master switch. Must be `true` for any channel to deliver messages. Set via the [claude.ai Admin console](https://claude.ai/admin-settings/claude-code) toggle or directly in managed settings. Blocks all channels including the development flag when off. | Channels blocked |

296| `allowedChannelPlugins` | Which plugins can register once channels are enabled. Replaces the Anthropic-maintained list when set. Only applies when `channelsEnabled` is `true`. | Anthropic default list applies |

297

298Pro and Max users without an organization skip these checks entirely: channels are available and users opt in per session with `--channels`.

299

300### Enable channels for your organization

301

302Admins can enable channels from [**claude.ai → Admin settings → Claude Code → Channels**](https://claude.ai/admin-settings/claude-code), or by setting `channelsEnabled` to `true` in managed settings.

303

304Once enabled, users in your organization can use `--channels` to opt channel servers into individual sessions. If the setting is disabled or unset, the MCP server still connects and its tools work, but channel messages won't arrive. A startup warning tells the user to have an admin enable the setting.

305

306### Restrict which channel plugins can run

307

308By default, any plugin on the Anthropic-maintained allowlist can register as a channel. Admins on Team and Enterprise plans can replace that allowlist with their own by setting `allowedChannelPlugins` in managed settings. Use this to restrict which official plugins are allowed, approve channels from your own internal marketplace, or both. Each entry names a plugin and the marketplace it comes from:

309

310```json theme={null}

311{

312 "channelsEnabled": true,

313 "allowedChannelPlugins": [

314 { "marketplace": "claude-plugins-official", "plugin": "telegram" },

315 { "marketplace": "claude-plugins-official", "plugin": "discord" },

316 { "marketplace": "acme-corp-plugins", "plugin": "internal-alerts" }

317 ]

318}

319```

320

321When `allowedChannelPlugins` is set, it replaces the Anthropic allowlist entirely: only the listed plugins can register. Leave it unset to fall back to the default Anthropic allowlist. An empty array blocks all channel plugins from the allowlist, but `--dangerously-load-development-channels` can still bypass it for local testing. To block channels entirely including the development flag, leave `channelsEnabled` unset instead.

322

323This setting requires `channelsEnabled: true`. If a user passes a plugin to `--channels` that isn't on your list, Claude Code starts normally but the channel doesn't register, and the startup notice explains that the plugin isn't on the organization's approved list.

324

325## Research preview

326

327Channels are a research preview feature. Availability is rolling out gradually, and the `--channels` flag syntax and protocol contract may change based on feedback.

328

329During the preview, `--channels` only accepts plugins from an Anthropic-maintained allowlist, or from your organization's allowlist if an admin has set [`allowedChannelPlugins`](#restrict-which-channel-plugins-can-run). The channel plugins in [claude-plugins-official](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins) are the default approved set. If you pass something that isn't on the effective allowlist, Claude Code starts normally but the channel doesn't register, and the startup notice tells you why.

330

331To test a channel you're building, use `--dangerously-load-development-channels`. See [Test during the research preview](/en/channels-reference#test-during-the-research-preview) for information about testing custom channels that you build.

332

333Report issues or feedback on the [Claude Code GitHub repository](https://github.com/anthropics/claude-code/issues).

334

335## How channels compare

336

337Several Claude Code features connect to systems outside the terminal, each suited to a different kind of work:

338

339| Feature | What it does | Good for |

340| ---------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------- |

341| [Claude Code on the web](/en/claude-code-on-the-web) | Runs tasks in a fresh cloud sandbox, cloned from GitHub | Delegating self-contained async work you check on later |

342| [Claude in Slack](/en/slack) | Spawns a web session from an `@Claude` mention in a channel or thread | Starting tasks directly from team conversation context |

343| Standard [MCP server](/en/mcp) | Claude queries it during a task; nothing is pushed to the session | Giving Claude on-demand access to read or query a system |

344| [Remote Control](/en/remote-control) | You drive your local session from claude.ai or the Claude mobile app | Steering an in-progress session while away from your desk |

345

346Channels fill the gap in that list by pushing events from non-Claude sources into your already-running local session.

347

348* **Chat bridge**: ask Claude something from your phone via Telegram, Discord, or iMessage, and the answer comes back in the same chat while the work runs on your machine against your real files.

349* **[Webhook receiver](/en/channels-reference#example-build-a-webhook-receiver)**: a webhook from CI, your error tracker, a deploy pipeline, or other external service arrives where Claude already has your files open and remembers what you were debugging.

350

351## Next steps

352

353Once you have a channel running, explore these related features:

354

355* [Build your own channel](/en/channels-reference) for systems that don't have plugins yet

356* [Remote Control](/en/remote-control) to drive a local session from your phone instead of forwarding events into it

357* [Scheduled tasks](/en/scheduled-tasks) to poll on a timer instead of reacting to pushed events

channels-reference.md +749 −0 added

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# Channels reference

7> Build an MCP server that pushes webhooks, alerts, and chat messages into a Claude Code session. Reference for the channel contract: capability declaration, notification events, reply tools, sender gating, and permission relay.

9<Note>

10 Channels are in [research preview](/en/channels#research-preview) and require Claude Code v2.1.80 or later. They require claude.ai login. Console and API key authentication is not supported. Team and Enterprise organizations must [explicitly enable them](/en/channels#enterprise-controls).

11</Note>

13A channel is an MCP server that pushes events into a Claude Code session so Claude can react to things happening outside the terminal.

15You can build a one-way or two-way channel. One-way channels forward alerts, webhooks, or monitoring events for Claude to act on. Two-way channels like chat bridges also [expose a reply tool](#expose-a-reply-tool) so Claude can send messages back. A channel with a trusted sender path can also opt in to [relay permission prompts](#relay-permission-prompts) so you can approve or deny tool use remotely.

17This page covers:

19* [Overview](#overview): how channels work

20* [What you need](#what-you-need): requirements and general steps

21* [Example: build a webhook receiver](#example-build-a-webhook-receiver): a minimal one-way walkthrough

22* [Server options](#server-options): the constructor fields

23* [Notification format](#notification-format): the event payload

24* [Expose a reply tool](#expose-a-reply-tool): let Claude send messages back

25* [Gate inbound messages](#gate-inbound-messages): sender checks to prevent prompt injection

26* [Relay permission prompts](#relay-permission-prompts): forward tool approval prompts to remote channels

28To use an existing channel instead of building one, see [Channels](/en/channels). Telegram, Discord, iMessage, and fakechat are included in the research preview.

30## Overview

32A channel is an [MCP](https://modelcontextprotocol.io) server that runs on the same machine as Claude Code. Claude Code spawns it as a subprocess and communicates over stdio. Your channel server is the bridge between external systems and the Claude Code session:

34* **Chat platforms** (Telegram, Discord): your plugin runs locally and polls the platform's API for new messages. When someone DMs your bot, the plugin receives the message and forwards it to Claude. No URL to expose.

35* **Webhooks** (CI, monitoring): your server listens on a local HTTP port. External systems POST to that port, and your server pushes the payload to Claude.

37<img src="https://mintcdn.com/claude-code/zbUxPYi8065L3Y_P/en/images/channel-architecture.svg?fit=max&auto=format&n=zbUxPYi8065L3Y_P&q=85&s=fd6b6b949eab38264043d2a96285a57c" alt="Architecture diagram showing external systems connecting to your local channel server, which communicates with Claude Code over stdio" width="600" height="220" data-path="en/images/channel-architecture.svg" />

39## What you need

41The only hard requirement is the [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk) package and a Node.js-compatible runtime. [Bun](https://bun.sh), [Node](https://nodejs.org), and [Deno](https://deno.com) all work. The pre-built plugins in the research preview use Bun, but your channel doesn't have to.

43Your server needs to:

451. Declare the `claude/channel` capability so Claude Code registers a notification listener

462. Emit `notifications/claude/channel` events when something happens

473. Connect over [stdio transport](https://modelcontextprotocol.io/docs/concepts/transports#standard-io) (Claude Code spawns your server as a subprocess)

49The [Server options](#server-options) and [Notification format](#notification-format) sections cover each of these in detail. See [Example: build a webhook receiver](#example-build-a-webhook-receiver) for a full walkthrough.

51During the research preview, custom channels aren't on the [approved allowlist](/en/channels#supported-channels). Use `--dangerously-load-development-channels` to test locally. See [Test during the research preview](#test-during-the-research-preview) for details.

53## Example: build a webhook receiver

55This walkthrough builds a single-file server that listens for HTTP requests and forwards them into your Claude Code session. By the end, anything that can send an HTTP POST, like a CI pipeline, a monitoring alert, or a `curl` command, can push events to Claude.

57This example uses [Bun](https://bun.sh) as the runtime for its built-in HTTP server and TypeScript support. You can use [Node](https://nodejs.org) or [Deno](https://deno.com) instead; the only requirement is the [MCP SDK](https://www.npmjs.com/package/@modelcontextprotocol/sdk).

59<Steps>

60 <Step title="Create the project">

61 Create a new directory and install the MCP SDK:

63 ```bash theme={null}

64 mkdir webhook-channel && cd webhook-channel

65 bun add @modelcontextprotocol/sdk

66 ```

67 </Step>

69 <Step title="Write the channel server">

70 Create a file called `webhook.ts`. This is your entire channel server: it connects to Claude Code over stdio, and it listens for HTTP POSTs on port 8788. When a request arrives, it pushes the body to Claude as a channel event.

72 ```ts title="webhook.ts" theme={null}

73 #!/usr/bin/env bun

74 import { Server } from '@modelcontextprotocol/sdk/server/index.js'

75 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'

77 // Create the MCP server and declare it as a channel

78 const mcp = new Server(

79 { name: 'webhook', version: '0.0.1' },

80 {

81 // this key is what makes it a channel — Claude Code registers a listener for it

82 capabilities: { experimental: { 'claude/channel': {} } },

83 // added to Claude's system prompt so it knows how to handle these events

84 instructions: 'Events from the webhook channel arrive as <channel source="webhook" ...>. They are one-way: read them and act, no reply expected.',

85 },

86 )

88 // Connect to Claude Code over stdio (Claude Code spawns this process)

89 await mcp.connect(new StdioServerTransport())

91 // Start an HTTP server that forwards every POST to Claude

92 Bun.serve({

93 port: 8788, // any open port works

94 // localhost-only: nothing outside this machine can POST

95 hostname: '127.0.0.1',

96 async fetch(req) {

97 const body = await req.text()

98 await mcp.notification({

99 method: 'notifications/claude/channel',

100 params: {

101 content: body, // becomes the body of the <channel> tag

102 // each key becomes a tag attribute, e.g. <channel path="/" method="POST">

103 meta: { path: new URL(req.url).pathname, method: req.method },

104 },

105 })

106 return new Response('ok')

107 },

108 })

109 ```

110

111 The file does three things in order:

112

113 * **Server configuration**: creates the MCP server with `claude/channel` in its capabilities, which is what tells Claude Code this is a channel. The [`instructions`](#server-options) string goes into Claude's system prompt: tell Claude what events to expect, whether to reply, and how to route replies if it should.

114 * **Stdio connection**: connects to Claude Code over stdin/stdout. This is standard for any [MCP server](https://modelcontextprotocol.io/docs/concepts/transports#standard-io): Claude Code spawns it as a subprocess.

115 * **HTTP listener**: starts a local web server on port 8788. Every POST body gets forwarded to Claude as a channel event via `mcp.notification()`. The `content` becomes the event body, and each `meta` entry becomes an attribute on the `<channel>` tag. The listener needs access to the `mcp` instance, so it runs in the same process. You could split it into separate modules for a larger project.

116 </Step>

117

118 <Step title="Register your server with Claude Code">

119 Add the server to your MCP config so Claude Code knows how to start it. For a project-level `.mcp.json` in the same directory, use a relative path. For user-level config in `~/.claude.json`, use the full absolute path so the server can be found from any project:

120

121 ```json title=".mcp.json" theme={null}

122 {

123 "mcpServers": {

124 "webhook": { "command": "bun", "args": ["./webhook.ts"] }

125 }

126 }

127 ```

128

129 Claude Code reads your MCP config at startup and spawns each server as a subprocess.

130 </Step>

131

132 <Step title="Test it">

133 During the research preview, custom channels aren't on the allowlist, so start Claude Code with the development flag:

134

135 ```bash theme={null}

136 claude --dangerously-load-development-channels server:webhook

137 ```

138

139 When Claude Code starts, it reads your MCP config, spawns your `webhook.ts` as a subprocess, and the HTTP listener starts automatically on the port you configured (8788 in this example). You don't need to run the server yourself.

140

141 If you see "blocked by org policy," your Team or Enterprise admin needs to [enable channels](/en/channels#enterprise-controls) first.

142

143 In a separate terminal, simulate a webhook by sending an HTTP POST with a message to your server. This example sends a CI failure alert to port 8788 (or whichever port you configured):

144

145 ```bash theme={null}

146 curl -X POST localhost:8788 -d "build failed on main: https://ci.example.com/run/1234"

147 ```

148

149 The payload arrives in your Claude Code session as a `<channel>` tag:

150

151 ```text theme={null}

152 <channel source="webhook" path="/" method="POST">build failed on main: https://ci.example.com/run/1234</channel>

153 ```

154

155 In your Claude Code terminal, you'll see Claude receive the message and start responding: reading files, running commands, or whatever the message calls for. This is a one-way channel, so Claude acts in your session but doesn't send anything back through the webhook. To add replies, see [Expose a reply tool](#expose-a-reply-tool).

156

157 If the event doesn't arrive, the diagnosis depends on what `curl` returned:

158

159 * **`curl` succeeds but nothing reaches Claude**: run `/mcp` in your session to check the server's status. "Failed to connect" usually means a dependency or import error in your server file; check the debug log at `~/.claude/debug/<session-id>.txt` for the stderr trace.

160 * **`curl` fails with "connection refused"**: the port is either not bound yet or a stale process from an earlier run is holding it. `lsof -i :<port>` shows what's listening; `kill` the stale process before restarting your session.

161 </Step>

162</Steps>

163

164The [fakechat server](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/fakechat) extends this pattern with a web UI, file attachments, and a reply tool for two-way chat.

165

166## Test during the research preview

167

168During the research preview, every channel must be on the [approved allowlist](/en/channels#research-preview) to register. The development flag bypasses the allowlist for specific entries after a confirmation prompt. This example shows both entry types:

169

170```bash theme={null}

171# Testing a plugin you're developing

172claude --dangerously-load-development-channels plugin:yourplugin@yourmarketplace

173

174# Testing a bare .mcp.json server (no plugin wrapper yet)

175claude --dangerously-load-development-channels server:webhook

176```

177

178The bypass is per-entry. Combining this flag with `--channels` doesn't extend the bypass to the `--channels` entries. During the research preview, the approved allowlist is Anthropic-curated, so your channel stays on the development flag while you build and test.

179

180<Note>

181 This flag skips the allowlist only. The `channelsEnabled` organization policy still applies. Don't use it to run channels from untrusted sources.

182</Note>

183

184## Server options

185

186A channel sets these options in the [`Server`](https://modelcontextprotocol.io/docs/concepts/servers) constructor. The `instructions` and `capabilities.tools` fields are [standard MCP](https://modelcontextprotocol.io/docs/concepts/servers); `capabilities.experimental['claude/channel']` and `capabilities.experimental['claude/channel/permission']` are the channel-specific additions:

187

188| Field | Type | Description |

189| :------------------------------------------------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

190| `capabilities.experimental['claude/channel']` | `object` | Required. Always `{}`. Presence registers the notification listener. |

191| `capabilities.experimental['claude/channel/permission']` | `object` | Optional. Always `{}`. Declares that this channel can receive permission relay requests. When declared, Claude Code forwards tool approval prompts to your channel so you can approve or deny them remotely. See [Relay permission prompts](#relay-permission-prompts). |

192| `capabilities.tools` | `object` | Two-way only. Always `{}`. Standard MCP tool capability. See [Expose a reply tool](#expose-a-reply-tool). |

193| `instructions` | `string` | Recommended. Added to Claude's system prompt. Tell Claude what events to expect, what the `<channel>` tag attributes mean, whether to reply, and if so which tool to use and which attribute to pass back (like `chat_id`). |

194

195To create a one-way channel, omit `capabilities.tools`. This example shows a two-way setup with the channel capability, tools, and instructions set:

196

197```ts theme={null}

198import { Server } from '@modelcontextprotocol/sdk/server/index.js'

199

200const mcp = new Server(

201 { name: 'your-channel', version: '0.0.1' },

202 {

203 capabilities: {

204 experimental: { 'claude/channel': {} }, // registers the channel listener

205 tools: {}, // omit for one-way channels

206 },

207 // added to Claude's system prompt so it knows how to handle your events

208 instructions: 'Messages arrive as <channel source="your-channel" ...>. Reply with the reply tool.',

209 },

210)

211```

212

213To push an event, call `mcp.notification()` with method `notifications/claude/channel`. The params are in the next section.

214

215## Notification format

216

217Your server emits `notifications/claude/channel` with two params:

218

219| Field | Type | Description |

220| :-------- | :----------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

221| `content` | `string` | The event body. Delivered as the body of the `<channel>` tag. |

222| `meta` | `Record<string, string>` | Optional. Each entry becomes an attribute on the `<channel>` tag for routing context like chat ID, sender name, or alert severity. Keys must be identifiers: letters, digits, and underscores only. Keys containing hyphens or other characters are silently dropped. |

223

224Your server pushes events by calling `mcp.notification()` on the `Server` instance. This example pushes a CI failure alert with two meta keys:

225

226```ts theme={null}

227await mcp.notification({

228 method: 'notifications/claude/channel',

229 params: {

230 content: 'build failed on main: https://ci.example.com/run/1234',

231 meta: { severity: 'high', run_id: '1234' },

232 },

233})

234```

235

236The event arrives in Claude's context wrapped in a `<channel>` tag. The `source` attribute is set automatically from your server's configured name:

237

238```text theme={null}

239<channel source="your-channel" severity="high" run_id="1234">

240build failed on main: https://ci.example.com/run/1234

241</channel>

242```

243

244## Expose a reply tool

245

246If your channel is two-way, like a chat bridge rather than an alert forwarder, expose a standard [MCP tool](https://modelcontextprotocol.io/docs/concepts/tools) that Claude can call to send messages back. Nothing about the tool registration is channel-specific. A reply tool has three components:

247

2481. A `tools: {}` entry in your `Server` constructor capabilities so Claude Code discovers the tool

2492. Tool handlers that define the tool's schema and implement the send logic

2503. An `instructions` string in your `Server` constructor that tells Claude when and how to call the tool

251

252To add these to the [webhook receiver above](#example-build-a-webhook-receiver):

253

254<Steps>

255 <Step title="Enable tool discovery">

256 In your `Server` constructor in `webhook.ts`, add `tools: {}` to the capabilities so Claude Code knows your server offers tools:

257

258 ```ts theme={null}

259 capabilities: {

260 experimental: { 'claude/channel': {} },

261 tools: {}, // enables tool discovery

262 },

263 ```

264 </Step>

265

266 <Step title="Register the reply tool">

267 Add the following to `webhook.ts`. The `import` goes at the top of the file with your other imports; the two handlers go between the `Server` constructor and `mcp.connect()`. This registers a `reply` tool that Claude can call with a `chat_id` and `text`:

268

269 ```ts theme={null}

270 // Add this import at the top of webhook.ts

271 import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js'

272

273 // Claude queries this at startup to discover what tools your server offers

274 mcp.setRequestHandler(ListToolsRequestSchema, async () => ({

275 tools: [{

276 name: 'reply',

277 description: 'Send a message back over this channel',

278 // inputSchema tells Claude what arguments to pass

279 inputSchema: {

280 type: 'object',

281 properties: {

282 chat_id: { type: 'string', description: 'The conversation to reply in' },

283 text: { type: 'string', description: 'The message to send' },

284 },

285 required: ['chat_id', 'text'],

286 },

287 }],

288 }))

289

290 // Claude calls this when it wants to invoke a tool

291 mcp.setRequestHandler(CallToolRequestSchema, async req => {

292 if (req.params.name === 'reply') {

293 const { chat_id, text } = req.params.arguments as { chat_id: string; text: string }

294 // send() is your outbound: POST to your chat platform, or for local

295 // testing the SSE broadcast shown in the full example below.

296 send(`Reply to ${chat_id}: ${text}`)

297 return { content: [{ type: 'text', text: 'sent' }] }

298 }

299 throw new Error(`unknown tool: ${req.params.name}`)

300 })

301 ```

302 </Step>

303

304 <Step title="Update the instructions">

305 Update the `instructions` string in your `Server` constructor so Claude knows to route replies back through the tool. This example tells Claude to pass `chat_id` from the inbound tag:

306

307 ```ts theme={null}

308 instructions: 'Messages arrive as <channel source="webhook" chat_id="...">. Reply with the reply tool, passing the chat_id from the tag.'

309 ```

310 </Step>

311</Steps>

312

313Here's the complete `webhook.ts` with two-way support. Outbound replies stream over `GET /events` using [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) (SSE), so `curl -N localhost:8788/events` can watch them live; inbound chat arrives on `POST /`:

314

315```ts title="Full webhook.ts with reply tool" expandable theme={null}

316#!/usr/bin/env bun

317import { Server } from '@modelcontextprotocol/sdk/server/index.js'

318import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'

319import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js'

320

321// --- Outbound: write to any curl -N listeners on /events --------------------

322// A real bridge would POST to your chat platform instead.

323const listeners = new Set<(chunk: string) => void>()

324function send(text: string) {

325 const chunk = text.split('\n').map(l => `data: ${l}\n`).join('') + '\n'

326 for (const emit of listeners) emit(chunk)

327}

328

329const mcp = new Server(

330 { name: 'webhook', version: '0.0.1' },

331 {

332 capabilities: {

333 experimental: { 'claude/channel': {} },

334 tools: {},

335 },

336 instructions: 'Messages arrive as <channel source="webhook" chat_id="...">. Reply with the reply tool, passing the chat_id from the tag.',

337 },

338)

339

340mcp.setRequestHandler(ListToolsRequestSchema, async () => ({

341 tools: [{

342 name: 'reply',

343 description: 'Send a message back over this channel',

344 inputSchema: {

345 type: 'object',

346 properties: {

347 chat_id: { type: 'string', description: 'The conversation to reply in' },

348 text: { type: 'string', description: 'The message to send' },

349 },

350 required: ['chat_id', 'text'],

351 },

352 }],

353}))

354

355mcp.setRequestHandler(CallToolRequestSchema, async req => {

356 if (req.params.name === 'reply') {

357 const { chat_id, text } = req.params.arguments as { chat_id: string; text: string }

358 send(`Reply to ${chat_id}: ${text}`)

359 return { content: [{ type: 'text', text: 'sent' }] }

360 }

361 throw new Error(`unknown tool: ${req.params.name}`)

362})

363

364await mcp.connect(new StdioServerTransport())

365

366let nextId = 1

367Bun.serve({

368 port: 8788,

369 hostname: '127.0.0.1',

370 idleTimeout: 0, // don't close idle SSE streams

371 async fetch(req) {

372 const url = new URL(req.url)

373

374 // GET /events: SSE stream so curl -N can watch Claude's replies live

375 if (req.method === 'GET' && url.pathname === '/events') {

376 const stream = new ReadableStream({

377 start(ctrl) {

378 ctrl.enqueue(': connected\n\n') // so curl shows something immediately

379 const emit = (chunk: string) => ctrl.enqueue(chunk)

380 listeners.add(emit)

381 req.signal.addEventListener('abort', () => listeners.delete(emit))

382 },

383 })

384 return new Response(stream, {

385 headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache' },

386 })

387 }

388

389 // POST: forward to Claude as a channel event

390 const body = await req.text()

391 const chat_id = String(nextId++)

392 await mcp.notification({

393 method: 'notifications/claude/channel',

394 params: {

395 content: body,

396 meta: { chat_id, path: url.pathname, method: req.method },

397 },

398 })

399 return new Response('ok')

400 },

401})

402```

403

404The [fakechat server](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/fakechat) shows a more complete example with file attachments and message editing.

405

406## Gate inbound messages

407

408An ungated channel is a prompt injection vector. Anyone who can reach your endpoint can put text in front of Claude. A channel listening to a chat platform or a public endpoint needs a real sender check before it emits anything.

409

410Check the sender against an allowlist before calling `mcp.notification()`. This example drops any message from a sender not in the set:

411

412```ts theme={null}

413const allowed = new Set(loadAllowlist()) // from your access.json or equivalent

414

415// inside your message handler, before emitting:

416if (!allowed.has(message.from.id)) { // sender, not room

417 return // drop silently

418}

419await mcp.notification({ ... })

420```

421

422Gate on the sender's identity, not the chat or room identity: `message.from.id` in the example, not `message.chat.id`. In group chats, these differ, and gating on the room would let anyone in an allowlisted group inject messages into the session.

423

424The [Telegram](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/telegram) and [Discord](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/discord) channels gate on a sender allowlist the same way. They bootstrap the list by pairing: the user DMs the bot, the bot replies with a pairing code, the user approves it in their Claude Code session, and their platform ID is added. See either implementation for the full pairing flow. The [iMessage](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/imessage) channel takes a different approach: it detects the user's own addresses from the Messages database at startup and lets them through automatically, with other senders added by handle.

425

426## Relay permission prompts

427

428<Note>

429 Permission relay requires Claude Code v2.1.81 or later. Earlier versions ignore the `claude/channel/permission` capability.

430</Note>

431

432When Claude calls a tool that needs approval, the local terminal dialog opens and the session waits. A two-way channel can opt in to receive the same prompt in parallel and relay it to you on another device. Both stay live: you can answer in the terminal or on your phone, and Claude Code applies whichever answer arrives first and closes the other.

433

434Relay covers tool-use approvals like `Bash`, `Write`, and `Edit`. Project trust and MCP server consent dialogs don't relay; those only appear in the local terminal.

435

436### How relay works

437

438When a permission prompt opens, the relay loop has four steps:

439

4401. Claude Code generates a short request ID and notifies your server

4412. Your server forwards the prompt and ID to your chat app

4423. The remote user replies with a yes or no and that ID

4434. Your inbound handler parses the reply into a verdict, and Claude Code applies it only if the ID matches an open request

444

445The local terminal dialog stays open through all of this. If someone at the terminal answers before the remote verdict arrives, that answer is applied instead and the pending remote request is dropped.

446

447<img src="https://mintcdn.com/claude-code/DsZvsJII1OmzIjIs/en/images/channel-permission-relay.svg?fit=max&auto=format&n=DsZvsJII1OmzIjIs&q=85&s=c1d75f6ee34c2757983e2cca899b90d1" alt="Sequence diagram: Claude Code sends a permission_request notification to the channel server, the server formats and sends the prompt to the chat app, the human replies with a verdict, and the server parses that reply into a permission notification back to Claude Code" width="600" height="230" data-path="en/images/channel-permission-relay.svg" />

448

449### Permission request fields

450

451The outbound notification from Claude Code is `notifications/claude/channel/permission_request`. Like the [channel notification](#notification-format), the transport is standard MCP but the method and schema are Claude Code extensions. The `params` object has four string fields your server formats into the outgoing prompt:

452

453| Field | Description |

454| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

455| `request_id` | Five lowercase letters drawn from `a`-`z` without `l`, so it never reads as a `1` or `I` when typed on a phone. Include it in your outgoing prompt so it can be echoed in the reply. Claude Code only accepts a verdict that carries an ID it issued. The local terminal dialog doesn't display this ID, so your outbound handler is the only way to learn it. |

456| `tool_name` | Name of the tool Claude wants to use, for example `Bash` or `Write`. |

457| `description` | Human-readable summary of what this specific tool call does, the same text the local terminal dialog shows. For a Bash call this is Claude's description of the command, or the command itself if none was given. |

458| `input_preview` | The tool's arguments as a JSON string, truncated to 200 characters. For Bash this is the command; for Write it's the file path and a prefix of the content. Omit it from your prompt if you only have room for a one-line message. Your server decides what to show. |

459

460The verdict your server sends back is `notifications/claude/channel/permission` with two fields: `request_id` echoing the ID above, and `behavior` set to `'allow'` or `'deny'`. Allow lets the tool call proceed; deny rejects it, the same as answering No in the local dialog. Neither verdict affects future calls.

461

462### Add relay to a chat bridge

463

464Adding permission relay to a two-way channel takes three components:

465

4661. A `claude/channel/permission: {}` entry under `experimental` capabilities in your `Server` constructor so Claude Code knows to forward prompts

4672. A notification handler for `notifications/claude/channel/permission_request` that formats the prompt and sends it out through your platform API

4683. A check in your inbound message handler that recognizes `yes <id>` or `no <id>` and emits a `notifications/claude/channel/permission` verdict instead of forwarding the text to Claude

469

470Only declare the capability if your channel [authenticates the sender](#gate-inbound-messages), because anyone who can reply through your channel can approve or deny tool use in your session.

471

472To add these to a two-way chat bridge like the one assembled in [Expose a reply tool](#expose-a-reply-tool):

473

474<Steps>

475 <Step title="Declare the permission capability">

476 In your `Server` constructor, add `claude/channel/permission: {}` alongside `claude/channel` under `experimental`:

477

478 ```ts theme={null}

479 capabilities: {

480 experimental: {

481 'claude/channel': {},

482 'claude/channel/permission': {}, // opt in to permission relay

483 },

484 tools: {},

485 },

486 ```

487 </Step>

488

489 <Step title="Handle the incoming request">

490 Register a notification handler between your `Server` constructor and `mcp.connect()`. Claude Code calls it with the [four request fields](#permission-request-fields) when a permission dialog opens. Your handler formats the prompt for your platform and includes instructions for replying with the ID:

491

492 ```ts theme={null}

493 import { z } from 'zod'

494

495 // setNotificationHandler routes by z.literal on the method field,

496 // so this schema is both the validator and the dispatch key

497 const PermissionRequestSchema = z.object({

498 method: z.literal('notifications/claude/channel/permission_request'),

499 params: z.object({

500 request_id: z.string(), // five lowercase letters, include verbatim in your prompt

501 tool_name: z.string(), // e.g. "Bash", "Write"

502 description: z.string(), // human-readable summary of this call

503 input_preview: z.string(), // tool args as JSON, truncated to ~200 chars

504 }),

505 })

506

507 mcp.setNotificationHandler(PermissionRequestSchema, async ({ params }) => {

508 // send() is your outbound: POST to your chat platform, or for local

509 // testing the SSE broadcast shown in the full example below.

510 send(

511 `Claude wants to run ${params.tool_name}: ${params.description}\n\n` +

512 // the ID in the instruction is what your inbound handler parses in Step 3

513 `Reply "yes ${params.request_id}" or "no ${params.request_id}"`,

514 )

515 })

516 ```

517 </Step>

518

519 <Step title="Intercept the verdict in your inbound handler">

520 Your inbound handler is the loop or callback that receives messages from your platform: the same place you [gate on sender](#gate-inbound-messages) and emit `notifications/claude/channel` to forward chat to Claude. Add a check before the chat-forwarding call that recognizes the verdict format and emits the permission notification instead.

521

522 The regex matches the ID format Claude Code generates: five letters, never `l`. The `/i` flag tolerates phone autocorrect capitalizing the reply; lowercase the captured ID before sending it back.

523

524 ```ts theme={null}

525 // matches "y abcde", "yes abcde", "n abcde", "no abcde"

526 // [a-km-z] is the ID alphabet Claude Code uses (lowercase, skips 'l')

527 // /i tolerates phone autocorrect; lowercase the capture before sending

528 const PERMISSION_REPLY_RE = /^\s*(y|yes|n|no)\s+([a-km-z]{5})\s*$/i

529

530 async function onInbound(message: PlatformMessage) {

531 if (!allowed.has(message.from.id)) return // gate on sender first

532

533 const m = PERMISSION_REPLY_RE.exec(message.text)

534 if (m) {

535 // m[1] is the verdict word, m[2] is the request ID

536 // emit the verdict notification back to Claude Code instead of chat

537 await mcp.notification({

538 method: 'notifications/claude/channel/permission',

539 params: {

540 request_id: m[2].toLowerCase(), // normalize in case of autocorrect caps

541 behavior: m[1].toLowerCase().startsWith('y') ? 'allow' : 'deny',

542 },

543 })

544 return // handled as verdict, don't also forward as chat

545 }

546

547 // didn't match verdict format: fall through to the normal chat path

548 await mcp.notification({

549 method: 'notifications/claude/channel',

550 params: { content: message.text, meta: { chat_id: String(message.chat.id) } },

551 })

552 }

553 ```

554 </Step>

555</Steps>

556

557Claude Code also keeps the local terminal dialog open, so you can answer in either place, and the first answer to arrive is applied. A remote reply that doesn't exactly match the expected format fails in one of two ways, and in both cases the dialog stays open:

558

559* **Different format**: your inbound handler's regex fails to match, so text like `approve it` or `yes` without an ID falls through as a normal message to Claude.

560* **Right format, wrong ID**: your server emits a verdict, but Claude Code finds no open request with that ID and drops it silently.

561

562### Full example

563

564The assembled `webhook.ts` below combines all three extensions from this page: the reply tool, sender gating, and permission relay. If you're starting here, you'll also need the [project setup and `.mcp.json` entry](#example-build-a-webhook-receiver) from the initial walkthrough.

565

566To make both directions testable from curl, the HTTP listener serves two paths:

567

568* **`GET /events`**: holds an SSE stream open and pushes each outbound message as a `data:` line, so `curl -N` can watch Claude's replies and permission prompts arrive live.

569* **`POST /`**: the inbound side, the same handler as earlier, now with the verdict-format check inserted before the chat-forward branch.

570

571```ts title="Full webhook.ts with permission relay" expandable theme={null}

572#!/usr/bin/env bun

573import { Server } from '@modelcontextprotocol/sdk/server/index.js'

574import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'

575import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js'

576import { z } from 'zod'

577

578// --- Outbound: write to any curl -N listeners on /events --------------------

579// A real bridge would POST to your chat platform instead.

580const listeners = new Set<(chunk: string) => void>()

581function send(text: string) {

582 const chunk = text.split('\n').map(l => `data: ${l}\n`).join('') + '\n'

583 for (const emit of listeners) emit(chunk)

584}

585

586// Sender allowlist. For the local walkthrough we trust the single X-Sender

587// header value "dev"; a real bridge would check the platform's user ID.

588const allowed = new Set(['dev'])

589

590const mcp = new Server(

591 { name: 'webhook', version: '0.0.1' },

592 {

593 capabilities: {

594 experimental: {

595 'claude/channel': {},

596 'claude/channel/permission': {}, // opt in to permission relay

597 },

598 tools: {},

599 },

600 instructions:

601 'Messages arrive as <channel source="webhook" chat_id="...">. ' +

602 'Reply with the reply tool, passing the chat_id from the tag.',

603 },

604)

605

606// --- reply tool: Claude calls this to send a message back -------------------

607mcp.setRequestHandler(ListToolsRequestSchema, async () => ({

608 tools: [{

609 name: 'reply',

610 description: 'Send a message back over this channel',

611 inputSchema: {

612 type: 'object',

613 properties: {

614 chat_id: { type: 'string', description: 'The conversation to reply in' },

615 text: { type: 'string', description: 'The message to send' },

616 },

617 required: ['chat_id', 'text'],

618 },

619 }],

620}))

621

622mcp.setRequestHandler(CallToolRequestSchema, async req => {

623 if (req.params.name === 'reply') {

624 const { chat_id, text } = req.params.arguments as { chat_id: string; text: string }

625 send(`Reply to ${chat_id}: ${text}`)

626 return { content: [{ type: 'text', text: 'sent' }] }

627 }

628 throw new Error(`unknown tool: ${req.params.name}`)

629})

630

631// --- permission relay: Claude Code (not Claude) calls this when a dialog opens

632const PermissionRequestSchema = z.object({

633 method: z.literal('notifications/claude/channel/permission_request'),

634 params: z.object({

635 request_id: z.string(),

636 tool_name: z.string(),

637 description: z.string(),

638 input_preview: z.string(),

639 }),

640})

641

642mcp.setNotificationHandler(PermissionRequestSchema, async ({ params }) => {

643 send(

644 `Claude wants to run ${params.tool_name}: ${params.description}\n\n` +

645 `Reply "yes ${params.request_id}" or "no ${params.request_id}"`,

646 )

647})

648

649await mcp.connect(new StdioServerTransport())

650

651// --- HTTP on :8788: GET /events streams outbound, POST routes inbound -------

652const PERMISSION_REPLY_RE = /^\s*(y|yes|n|no)\s+([a-km-z]{5})\s*$/i

653let nextId = 1

654

655Bun.serve({

656 port: 8788,

657 hostname: '127.0.0.1',

658 idleTimeout: 0, // don't close idle SSE streams

659 async fetch(req) {

660 const url = new URL(req.url)

661

662 // GET /events: SSE stream so curl -N can watch replies and prompts live

663 if (req.method === 'GET' && url.pathname === '/events') {

664 const stream = new ReadableStream({

665 start(ctrl) {

666 ctrl.enqueue(': connected\n\n') // so curl shows something immediately

667 const emit = (chunk: string) => ctrl.enqueue(chunk)

668 listeners.add(emit)

669 req.signal.addEventListener('abort', () => listeners.delete(emit))

670 },

671 })

672 return new Response(stream, {

673 headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache' },

674 })

675 }

676

677 // everything else is inbound: gate on sender first

678 const body = await req.text()

679 const sender = req.headers.get('X-Sender') ?? ''

680 if (!allowed.has(sender)) return new Response('forbidden', { status: 403 })

681

682 // check for verdict format before treating as chat

683 const m = PERMISSION_REPLY_RE.exec(body)

684 if (m) {

685 await mcp.notification({

686 method: 'notifications/claude/channel/permission',

687 params: {

688 request_id: m[2].toLowerCase(),

689 behavior: m[1].toLowerCase().startsWith('y') ? 'allow' : 'deny',

690 },

691 })

692 return new Response('verdict recorded')

693 }

694

695 // normal chat: forward to Claude as a channel event

696 const chat_id = String(nextId++)

697 await mcp.notification({

698 method: 'notifications/claude/channel',

699 params: { content: body, meta: { chat_id, path: url.pathname } },

700 })

701 return new Response('ok')

702 },

703})

704```

705

706Test the verdict path in three terminals. The first is your Claude Code session, started with the [development flag](#test-during-the-research-preview) so it spawns `webhook.ts`:

707

708```bash theme={null}

709claude --dangerously-load-development-channels server:webhook

710```

711

712In the second, stream the outbound side so you can see Claude's replies and any permission prompts as they fire:

713

714```bash theme={null}

715curl -N localhost:8788/events

716```

717

718In the third, send a message that will make Claude try to run a command:

719

720```bash theme={null}

721curl -d "list the files in this directory" -H "X-Sender: dev" localhost:8788

722```

723

724The local permission dialog opens in your Claude Code terminal. A moment later the prompt appears in the `/events` stream, including the five-letter ID. Approve it from the remote side:

725

726```bash theme={null}

727curl -d "yes <id>" -H "X-Sender: dev" localhost:8788

728```

729

730The local dialog closes and the tool runs. Claude's reply comes back through the `reply` tool and lands in the stream too.

731

732The three channel-specific pieces in this file:

733

734* **Capabilities** in the `Server` constructor: `claude/channel` registers the notification listener, `claude/channel/permission` opts in to permission relay, `tools` lets Claude discover the reply tool.

735* **Outbound paths**: the `reply` tool handler is what Claude calls for conversational responses; the `PermissionRequestSchema` notification handler is what Claude Code calls when a permission dialog opens. Both call `send()` to broadcast over `/events`, but they're triggered by different parts of the system.

736* **HTTP handler**: `GET /events` holds an SSE stream open so curl can watch outbound live; `POST` is inbound, gated on the `X-Sender` header. A `yes <id>` or `no <id>` body goes to Claude Code as a verdict notification and never reaches Claude; anything else is forwarded to Claude as a channel event.

737

738## Package as a plugin

739

740To make your channel installable and shareable, wrap it in a [plugin](/en/plugins) and publish it to a [marketplace](/en/plugin-marketplaces). Users install it with `/plugin install`, then enable it per session with `--channels plugin:<name>@<marketplace>`.

741

742A channel published to your own marketplace still needs `--dangerously-load-development-channels` to run, since it isn't on the [approved allowlist](/en/channels#supported-channels). To get it added, [submit it to the official marketplace](/en/plugins#submit-your-plugin-to-the-official-marketplace). Channel plugins go through security review before being approved. On Team and Enterprise plans, an admin can instead include your plugin in the organization's own [`allowedChannelPlugins`](/en/channels#restrict-which-channel-plugins-can-run) list, which replaces the default Anthropic allowlist.

743

744## See also

745

746* [Channels](/en/channels) to install and use Telegram, Discord, iMessage, or the fakechat demo, and to enable channels for a Team or Enterprise org

747* [Working channel implementations](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins) for complete server code with pairing flows, reply tools, and file attachments

748* [MCP](/en/mcp) for the underlying protocol that channel servers implement

749* [Plugins](/en/plugins) to package your channel so users can install it with `/plugin install`

checkpointing.md +30 −10

Details

4 4

5# Checkpointing5# Checkpointing

6 6

~~7> Automatically track and rewind Claude's edits to quickly recover from unwanted changes.~~7> Track, rewind, and summarize Claude's edits and conversation to manage session state.

8 8

9Claude Code automatically tracks Claude's file edits as you work, allowing you to quickly undo changes and rewind to previous states if anything gets off track.9Claude Code automatically tracks Claude's file edits as you work, allowing you to quickly undo changes and rewind to previous states if anything gets off track.

10 10

20* Checkpoints persist across sessions, so you can access them in resumed conversations20* Checkpoints persist across sessions, so you can access them in resumed conversations

21* Automatically cleaned up along with sessions after 30 days (configurable)21* Automatically cleaned up along with sessions after 30 days (configurable)

22 22

~~23### Rewinding changes~~23### Rewind and summarize

24 24

~~25Press `Esc` twice (`Esc` + `Esc`) or use the `/rewind` command to open up the rewind menu. You can choose to restore:~~25Press `Esc` twice (`Esc` + `Esc`) or use the `/rewind` command to open the rewind menu. A scrollable list shows each of your prompts from the session. Select the point you want to act on, then choose an action:

26 26

~~27* **Conversation only**: Rewind to a user message while keeping code changes~~27* **Restore code and conversation**: revert both code and conversation to that point

~~28* **Code only**: Revert file changes while keeping the conversation~~28* **Restore conversation**: rewind to that message while keeping current code

~~29* **Both code and conversation**: Restore both to a prior point in the session~~29* **Restore code**: revert file changes while keeping the conversation

30* **Summarize from here**: compress the conversation from this point forward into a summary, freeing context window space

31* **Never mind**: return to the message list without making changes

33After restoring the conversation or summarizing, the original prompt from the selected message is restored into the input field so you can re-send or edit it.

35#### Restore vs. summarize

37The three restore options revert state: they undo code changes, conversation history, or both. "Summarize from here" works differently:

39* Messages before the selected message stay intact

40* The selected message and all subsequent messages get replaced with a compact AI-generated summary

41* No files on disk are changed

42* The original messages are preserved in the session transcript, so Claude can reference the details if needed

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.

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>

30 49

31## Common use cases50## Common use cases

32 51

33Checkpoints are particularly useful when:52Checkpoints are particularly useful when:

34 53

~~35* **Exploring alternatives**: Try different implementation approaches without losing your starting point~~54* **Exploring alternatives**: try different implementation approaches without losing your starting point

~~36* **Recovering from mistakes**: Quickly undo changes that introduced bugs or broke functionality~~55* **Recovering from mistakes**: quickly undo changes that introduced bugs or broke functionality

~~37* **Iterating on features**: Experiment with variations knowing you can revert to working states~~56* **Iterating on features**: experiment with variations knowing you can revert to working states

57* **Freeing context space**: summarize a verbose debugging session from the midpoint forward, keeping your initial instructions intact

38 58

39## Limitations59## Limitations

40 60

65## See also85## See also

66 86

67* [Interactive mode](/en/interactive-mode) - Keyboard shortcuts and session controls87* [Interactive mode](/en/interactive-mode) - Keyboard shortcuts and session controls

~~68* [Built-in commands](/en/interactive-mode#built-in-commands) - Accessing checkpoints using `/rewind`~~88* [Built-in commands](/en/commands) - Accessing checkpoints using `/rewind`

69* [CLI reference](/en/cli-reference) - Command-line options89* [CLI reference](/en/cli-reference) - Command-line options

chrome.md +98 −86

Details

4 4

5# Use Claude Code with Chrome (beta)5# Use Claude Code with Chrome (beta)

6 6

~~7> Connect Claude Code to your browser to test web apps, debug with console logs, and automate browser tasks.~~7> Connect Claude Code to your Chrome browser to test web apps, debug with console logs, automate form filling, and extract data from web pages.

8 8

~~9<Note>~~9Claude Code integrates with the Claude in Chrome browser extension to give you browser automation capabilities from the CLI or the [VS Code extension](/en/vs-code#automate-browser-tasks-with-chrome). Build your code, then test and debug in the browser without switching contexts.

10 Chrome integration is in beta and currently works with Google Chrome only. It is not yet supported on Brave, Arc, or other Chromium-based browsers. WSL (Windows Subsystem for Linux) is also not supported.

~~11</Note>~~

12 10

13Claude Code integrates with the Claude in Chrome browser extension to give you browser automation capabilities directly from your terminal. Build in your terminal, then test and debug in your browser without switching contexts.11Claude opens new tabs for browser tasks and shares your browser's login state, so it can access any site you're already signed into. Browser actions run in a visible Chrome window in real time. When Claude encounters a login page or CAPTCHA, it pauses and asks you to handle it manually.

14 12

~~15## What the integration enables~~13<Note>

14 Chrome integration is in beta and currently works with Google Chrome and Microsoft Edge. It is not yet supported on Brave, Arc, or other Chromium-based browsers. WSL (Windows Subsystem for Linux) is also not supported.

15</Note>

16 16

17With Chrome connected, you can chain browser actions with terminal commands in a single workflow. For example: scrape documentation from a website, analyze it, generate code based on what you learned, and commit the result.17## Capabilities

18 18

~~19Key capabilities include:~~19With Chrome connected, you can chain browser actions with coding tasks in a single workflow:

20 20

~~21* **Live debugging**: Claude reads console errors and DOM state directly, then fixes the code that caused them~~21* **Live debugging**: read console errors and DOM state directly, then fix the code that caused them

~~22* **Design verification**: Build a UI from a Figma mock, then have Claude open it in the browser and verify it matches~~22* **Design verification**: build a UI from a Figma mock, then open it in the browser to verify it matches

~~23* **Web app testing**: Test form validation, check for visual regressions, or verify user flows work correctly~~23* **Web app testing**: test form validation, check for visual regressions, or verify user flows

~~24* **Authenticated web apps**: Interact with Google Docs, Gmail, Notion, or any app you're logged into without needing API connectors~~24* **Authenticated web apps**: interact with Google Docs, Gmail, Notion, or any app you're logged into without API connectors

~~25* **Data extraction**: Pull structured information from web pages and save it locally~~25* **Data extraction**: pull structured information from web pages and save it locally

~~26* **Task automation**: Automate repetitive browser tasks like data entry, form filling, or multi-site workflows~~26* **Task automation**: automate repetitive browser tasks like data entry, form filling, or multi-site workflows

~~27* **Session recording**: Record browser interactions as GIFs to document or share what happened~~27* **Session recording**: record browser interactions as GIFs to document or share what happened

28 28

29## Prerequisites29## Prerequisites

30 30

31Before using Claude Code with Chrome, you need:31Before using Claude Code with Chrome, you need:

32 32

~~33* [Google Chrome](https://www.google.com/chrome/) browser~~33* [Google Chrome](https://www.google.com/chrome/) or [Microsoft Edge](https://www.microsoft.com/edge) browser

~~34* [Claude in Chrome extension](https://chromewebstore.google.com/detail/claude/fcoeoabgfenejglbffodgkkbkcdhcgfn) version 1.0.36 or higher~~34* [Claude in Chrome extension](https://chromewebstore.google.com/detail/claude/fcoeoabgfenejglbffodgkkbkcdhcgfn) version 1.0.36 or higher, available in the Chrome Web Store for both browsers

~~35* [Claude Code CLI](/en/quickstart#step-1-install-claude-code) version 2.0.73 or higher~~35* [Claude Code](/en/quickstart#step-1-install-claude-code) version 2.0.73 or higher

~~36* A paid Claude plan (Pro, Team, or Enterprise)~~36* A direct Anthropic plan (Pro, Max, Teams, or Enterprise)

~~38## How the integration works~~

40Claude Code communicates with Chrome through the Claude in Chrome browser extension. The extension uses Chrome's [Native Messaging API](https://developer.chrome.com/docs/extensions/develop/concepts/native-messaging) to receive commands from Claude Code and execute them in your browser. This architecture lets Claude Code control browser tabs, read page content, and perform actions while you continue working in your terminal.

42When Claude encounters a login page, CAPTCHA, or other blocker, it pauses and asks you to handle it. You can provide credentials for Claude to enter, or log in manually in the browser. Once you're past the blocker, tell Claude to continue and it picks up where it left off.

44Claude opens new tabs for browser tasks rather than taking over existing ones. However, it shares your browser's login state, so if you're already signed into a site in Chrome, Claude can access it without re-authenticating.

45 37

46<Note>38<Note>

47 The Chrome integration requires a visible browser window. When Claude performs browser actions, you'll see Chrome open and navigate in real time. There's no headless mode since the integration relies on your actual browser session with its login state.39 Chrome integration is not available through third-party providers like Amazon Bedrock, Google Cloud Vertex AI, or Microsoft Foundry. If you access Claude exclusively through a third-party provider, you need a separate claude.ai account to use this feature.

48</Note>40</Note>

49 41

~~50## Set up the integration~~42## Get started in the CLI

51 43

52<Steps>44<Steps>

~~53 <Step title="Update Claude Code">~~45 <Step title="Launch Claude Code with Chrome">

54 Chrome integration requires a recent version of Claude Code. If you installed using the [native installer](/en/quickstart#step-1-install-claude-code), updates happen automatically. Otherwise, run:46 Start Claude Code with the `--chrome` flag:

55 47

56 ```bash theme={null}48 ```bash theme={null}

~~57 claude update~~49 claude --chrome

58 ```50 ```

52 You can also enable Chrome from within an existing session by running `/chrome`.

59 </Step>53 </Step>

60 54

~~61 <Step title="Start Claude Code with Chrome enabled">~~55 <Step title="Ask Claude to use the browser">

~~62 Launch Claude Code with the `--chrome` flag:~~56 This example navigates to a page, interacts with it, and reports what it finds, all from your terminal or editor:

63 57

~~64 ```bash theme={null}~~58 ```text theme={null}

~~65 claude --chrome~~59 Go to code.claude.com/docs, click on the search box,

60 type "hooks", and tell me what results appear

66 ```61 ```

67 </Step>62 </Step>

~~69 <Step title="Verify the connection">~~

~~70 Run `/chrome` to check the connection status and manage settings. If the extension isn't detected, you'll see a warning with a link to install it.~~

~~71 </Step>~~

72</Steps>63</Steps>

73 64

~~74You can also enable Chrome integration from within an existing session using the `/chrome` command.~~65Run `/chrome` at any time to check the connection status, manage permissions, or reconnect the extension.

75 66

~~76## Try it out~~67For VS Code, see [browser automation in VS Code](/en/vs-code#automate-browser-tasks-with-chrome).

77 68

~~78Once connected, type this into Claude to see the integration in action:~~69### Enable Chrome by default

79 70

~~80```~~71To avoid passing `--chrome` each session, run `/chrome` and select "Enabled by default".

~~81Go to code.claude.com/docs, click on the search box,~~

~~82type "hooks", and tell me what results appear~~

~~83```~~

84 72

~~85Claude opens the page, clicks into the search field, types the query, and reports the autocomplete results. This shows navigation, clicking, and typing in a single workflow.~~73In the [VS Code extension](/en/vs-code#automate-browser-tasks-with-chrome), Chrome is available whenever the Chrome extension is installed. No additional flag is needed.

86 74

~~87## Example workflows~~75<Note>

76 Enabling Chrome by default in the CLI increases context usage since browser tools are always loaded. If you notice increased context consumption, disable this setting and use `--chrome` only when needed.

77</Note>

79### Manage site permissions

81Site-level permissions are inherited from the Chrome extension. Manage permissions in the Chrome extension settings to control which sites Claude can browse, click, and type on.

88 82

89Claude can navigate pages, click and type, fill forms, scroll, read console logs and network requests, manage tabs, resize windows, and record GIFs. Run `/mcp` and click into `claude-in-chrome` to see the full list of available tools.83## Example workflows

90 84

~~91The following examples show common patterns for browser automation.~~85These examples show common ways to combine browser actions with coding tasks. Run `/mcp` and select `claude-in-chrome` to see the full list of available browser tools.

92 86

93### Test a local web application87### Test a local web application

94 88

95When developing a web app, ask Claude to verify your changes work correctly:89When developing a web app, ask Claude to verify your changes work correctly:

96 90

~~97```~~91```text theme={null}

98I just updated the login form validation. Can you open localhost:3000,92I just updated the login form validation. Can you open localhost:3000,

99try submitting the form with invalid data, and check if the error93try submitting the form with invalid data, and check if the error

100messages appear correctly?94messages appear correctly?

104 98

105### Debug with console logs99### Debug with console logs

106 100

107If your app has issues, Claude can read console output to help diagnose problems:101Claude can read console output to help diagnose problems. Tell Claude what patterns to look for rather than asking for all console output, since logs can be verbose:

108 102

109```103```text theme={null}

110Open the dashboard page and check the console for any errors when104Open the dashboard page and check the console for any errors when

111the page loads.105the page loads.

112```106```

117 111

118Speed up repetitive data entry tasks:112Speed up repetitive data entry tasks:

119 113

120```114```text theme={null}

121I have a spreadsheet of customer contacts in contacts.csv. For each row,115I have a spreadsheet of customer contacts in contacts.csv. For each row,

122go to our CRM at crm.example.com, click "Add Contact", and fill in the116go to the CRM at crm.example.com, click "Add Contact", and fill in the

123name, email, and phone fields.117name, email, and phone fields.

124```118```

125 119

129 123

130Use Claude to write directly in your documents without API setup:124Use Claude to write directly in your documents without API setup:

131 125

132```126```text theme={null}

133Draft a project update based on our recent commits and add it to my127Draft a project update based on the recent commits and add it to my

134Google Doc at docs.google.com/document/d/abc123128Google Doc at docs.google.com/document/d/abc123

135```129```

136 130

140 134

141Pull structured information from websites:135Pull structured information from websites:

142 136

143```137```text theme={null}

144Go to the product listings page and extract the name, price, and138Go to the product listings page and extract the name, price, and

145availability for each item. Save the results as a CSV file.139availability for each item. Save the results as a CSV file.

146```140```

151 145

152Coordinate tasks across multiple websites:146Coordinate tasks across multiple websites:

153 147

154```148```text theme={null}

155Check my calendar for meetings tomorrow, then for each meeting with149Check my calendar for meetings tomorrow, then for each meeting with

156an external attendee, look up their company on LinkedIn and add a150an external attendee, look up their company website and add a note

157note about what they do.151about what they do.

158```152```

159 153

160Claude works across tabs to gather information and complete the workflow.154Claude works across tabs to gather information and complete the workflow.

163 157

164Create shareable recordings of browser interactions:158Create shareable recordings of browser interactions:

165 159

166```160```text theme={null}

167Record a GIF showing how to complete the checkout flow, from adding161Record a GIF showing how to complete the checkout flow, from adding

168an item to the cart through to the confirmation page.162an item to the cart through to the confirmation page.

169```163```

170 164

171Claude records the interaction sequence and saves it as a GIF file.165Claude records the interaction sequence and saves it as a GIF file.

172 166

173## Best practices

~~174~~

175When using browser automation, keep these guidelines in mind:

~~176~~

177* **Modal dialogs can interrupt the flow**: JavaScript alerts, confirms, and prompts block browser events and prevent Claude from receiving commands. If a dialog appears, dismiss it manually and tell Claude to continue.

178* **Use fresh tabs**: Claude creates new tabs for each session. If a tab becomes unresponsive, ask Claude to create a new one.

179* **Filter console output**: Console logs can be verbose. When debugging, tell Claude what patterns to look for rather than asking for all console output.

~~180~~

181## Troubleshooting167## Troubleshooting

182 168

183### Extension not detected169### Extension not detected

184 170

185If Claude Code shows "Chrome extension not detected":171If Claude Code shows "Chrome extension not detected":

186 172

1871. Verify the Chrome extension (version 1.0.36 or higher) is installed1731. Verify the Chrome extension is installed and enabled in `chrome://extensions`

1882. Verify Claude Code is version 2.0.73 or higher by running `claude --version`1742. Verify Claude Code is up to date by running `claude --version`

1893. Check that Chrome is running1753. Check that Chrome is running

1904. Run `/chrome` and select "Reconnect extension" to re-establish the connection1764. Run `/chrome` and select "Reconnect extension" to re-establish the connection

1915. If the issue persists, restart both Claude Code and Chrome1775. If the issue persists, restart both Claude Code and Chrome

192 178

179The first time you enable Chrome integration, Claude Code installs a native messaging host configuration file. Chrome reads this file on startup, so if the extension isn't detected on your first attempt, restart Chrome to pick up the new configuration.

180

181If the connection still fails, verify the host configuration file exists at:

182

183For Chrome:

184

185* **macOS**: `~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json`

186* **Linux**: `~/.config/google-chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json`

187* **Windows**: check `HKCU\Software\Google\Chrome\NativeMessagingHosts\` in the Windows Registry

188

189For Edge:

190

191* **macOS**: `~/Library/Application Support/Microsoft Edge/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json`

192* **Linux**: `~/.config/microsoft-edge/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json`

193* **Windows**: check `HKCU\Software\Microsoft\Edge\NativeMessagingHosts\` in the Windows Registry

194

193### Browser not responding195### Browser not responding

194 196

195If Claude's browser commands stop working:197If Claude's browser commands stop working:

196 198

1971. Check if a modal dialog (alert, confirm, prompt) is blocking the page1991. Check if a modal dialog (alert, confirm, prompt) is blocking the page. JavaScript dialogs block browser events and prevent Claude from receiving commands. Dismiss the dialog manually, then tell Claude to continue.

1982. Ask Claude to create a new tab and try again2002. Ask Claude to create a new tab and try again

1993. Restart the Chrome extension by disabling and re-enabling it2013. Restart the Chrome extension by disabling and re-enabling it in `chrome://extensions`

200 202

201### First-time setup203### Connection drops during long sessions

202 204

203The first time you use the integration, Claude Code installs a native messaging host that allows communication between the CLI and Chrome. If you encounter permission errors, you may need to restart Chrome for the installation to take effect.205The Chrome extension's service worker can go idle during extended sessions, which breaks the connection. If browser tools stop working after a period of inactivity, run `/chrome` and select "Reconnect extension".

204 206

205## Enable by default207### Windows-specific issues

206 208

207Chrome integration requires the `--chrome` flag each time you start Claude Code. To enable it by default, run `/chrome` and select "Enabled by default".209On Windows, you may encounter:

208 210

209<Note>211* **Named pipe conflicts (EADDRINUSE)**: if another process is using the same named pipe, restart Claude Code. Close any other Claude Code sessions that might be using Chrome.

210 Enabling Chrome by default increases context usage since browser tools are always loaded. If you notice increased context consumption, disable this setting and use `--chrome` only when needed.212* **Native messaging host errors**: if the native messaging host crashes on startup, try reinstalling Claude Code to regenerate the host configuration.

211</Note>213

214### Common error messages

215

216These are the most frequently encountered errors and how to resolve them:

212 217

213Site-level permissions are inherited from the Chrome extension. Manage permissions in the Chrome extension settings to control which sites Claude can browse, click, and type on. Run `/chrome` to see current permission settings.218| Error | Cause | Fix |

219| ------------------------------------ | ------------------------------------------------ | --------------------------------------------------------------- |

220| "Browser extension is not connected" | Native messaging host cannot reach the extension | Restart Chrome and Claude Code, then run `/chrome` to reconnect |

221| "Extension not detected" | Chrome extension is not installed or is disabled | Install or enable the extension in `chrome://extensions` |

222| "No tab available" | Claude tried to act before a tab was ready | Ask Claude to create a new tab and retry |

223| "Receiving end does not exist" | Extension service worker went idle | Run `/chrome` and select "Reconnect extension" |

214 224

215## See also225## See also

216 226

217* [CLI reference](/en/cli-reference) - Command-line flags including `--chrome`227* [Use Claude Code in VS Code](/en/vs-code#automate-browser-tasks-with-chrome): browser automation in the VS Code extension

218* [Common workflows](/en/common-workflows) - More ways to use Claude Code228* [CLI reference](/en/cli-reference): command-line flags including `--chrome`

219* [Getting started with Claude for Chrome](https://support.anthropic.com/en/articles/12012173-getting-started-with-claude-for-chrome) - Full documentation for the Chrome extension, including shortcuts, scheduling, and permissions229* [Common workflows](/en/common-workflows): more ways to use Claude Code

230* [Data and privacy](/en/data-usage): how Claude Code handles your data

231* [Getting started with Claude in Chrome](https://support.claude.com/en/articles/12012173-getting-started-with-claude-in-chrome): full documentation for the Chrome extension, including shortcuts, scheduling, and permissions

claude-code-on-the-web.md +167 −50

Details

20* **Repositories not on your local machine**: Work on code you don't have checked out locally20* **Repositories not on your local machine**: Work on code you don't have checked out locally

21* **Backend changes**: Where Claude Code can write tests and then write code to pass those tests21* **Backend changes**: Where Claude Code can write tests and then write code to pass those tests

22 22

~~23Claude Code is also available on the Claude iOS app for kicking off tasks on the go and monitoring work in progress.~~23Claude Code is also available on the Claude app for [iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) and [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude) for kicking off tasks on the go and monitoring work in progress.

24 24

25You can move between local and remote development: [send tasks from your terminal to run on the web](#from-terminal-to-web) with the `&` prefix, or [teleport web sessions back to your terminal](#from-web-to-terminal) to continue locally.25You can [kick off new tasks on the web from your terminal](#from-terminal-to-web) with `--remote`, or [teleport web sessions back to your terminal](#from-web-to-terminal) to continue locally. To use the web interface while running Claude Code on your own machine instead of cloud infrastructure, see [Remote Control](/en/remote-control).

26 26

27## Who can use Claude Code on the web?27## Who can use Claude Code on the web?

28 28

30 30

31* **Pro users**31* **Pro users**

32* **Max users**32* **Max users**

~~33* **Team premium seat users**~~33* **Team users**

~~34* **Enterprise premium seat users**~~34* **Enterprise users** with premium seats or Chat + Claude Code seats

35 35

36## Getting started36## Getting started

37 37

381. Visit [claude.ai/code](https://claude.ai/code)381. Visit [claude.ai/code](https://claude.ai/code)

392. Connect your GitHub account392. Connect your GitHub account

~~403. Install the Claude GitHub app in your repositories~~403. Install the Claude GitHub App in your repositories

414. Select your default environment414. Select your default environment

425. Submit your coding task425. Submit your coding task

436. Review changes in diff view, iterate with comments, then create a pull request436. Review changes in diff view, iterate with comments, then create a pull request

47When you start a task on Claude Code on the web:47When you start a task on Claude Code on the web:

48 48

491. **Repository cloning**: Your repository is cloned to an Anthropic-managed virtual machine491. **Repository cloning**: Your repository is cloned to an Anthropic-managed virtual machine

~~502. **Environment setup**: Claude prepares a secure cloud environment with your code~~502. **Environment setup**: Claude prepares a secure cloud environment with your code, then runs your [setup script](#setup-scripts) if configured

513. **Network configuration**: Internet access is configured based on your settings513. **Network configuration**: Internet access is configured based on your settings

524. **Task execution**: Claude analyzes code, makes changes, runs tests, and checks its work524. **Task execution**: Claude analyzes code, makes changes, runs tests, and checks its work

535. **Completion**: You're notified when finished and can create a PR with the changes535. **Completion**: You're notified when finished and can create a PR with the changes

67 67

68This lets you refine changes through multiple rounds of feedback without creating draft PRs or switching to GitHub.68This lets you refine changes through multiple rounds of feedback without creating draft PRs or switching to GitHub.

69 69

~~70## Moving tasks between web and terminal~~70## Auto-fix pull requests

71 71

72You can start tasks on the web and continue them in your terminal, or send tasks from your terminal to run on the web. Web sessions persist even if you close your laptop, and you can monitor them from anywhere including the Claude iOS app.72Claude can watch a pull request and automatically respond to CI failures and review comments. Claude subscribes to GitHub activity on the PR, and when a check fails or a reviewer leaves a comment, Claude investigates and pushes a fix if one is clear.

73 73

74<Note>74<Note>

75 Session handoff is one-way: you can pull web sessions into your terminal, but you can't push an existing terminal session to the web. The [`&` prefix](#from-terminal-to-web) creates a *new* web session with your current conversation context.75 Auto-fix requires the Claude GitHub App to be installed on your repository. If you haven't already, install it from the [GitHub App page](https://github.com/apps/claude) or when prompted during [setup](#getting-started).

76</Note>76</Note>

77 77

~~78### From terminal to web~~78There are a few ways to turn on auto-fix depending on where the PR came from and what device you're using:

79 79

~~80Start a message with `&` inside Claude Code to send a task to run on the web:~~80* **PRs created in Claude Code on the web**: open the CI status bar and select **Auto-fix**

81* **From the mobile app**: tell Claude to auto-fix the PR, for example "watch this PR and fix any CI failures or review comments"

82* **Any existing PR**: paste the PR URL into a session and tell Claude to auto-fix it

81 83

~~82```~~84### How Claude responds to PR activity

~~83& Fix the authentication bug in src/auth/login.ts~~85

~~84```~~86When auto-fix is active, Claude receives GitHub events for the PR including new review comments and CI check failures. For each event, Claude investigates and decides how to proceed:

88* **Clear fixes**: if Claude is confident in a fix and it doesn't conflict with earlier instructions, Claude makes the change, pushes it, and explains what was done in the session

89* **Ambiguous requests**: if a reviewer's comment could be interpreted multiple ways or involves something architecturally significant, Claude asks you before acting

90* **Duplicate or no-action events**: if an event is a duplicate or requires no change, Claude notes it in the session and moves on

85 91

86This creates a new web session on claude.ai with your current conversation context. The task runs in the cloud while you continue working locally. Use `/tasks` to check progress, or open the session on claude.ai or the Claude iOS app to interact directly. From there you can steer Claude, provide feedback, or answer questions just like any other conversation.92Claude may reply to review comment threads on GitHub as part of resolving them. These replies are posted using your GitHub account, so they appear under your username, but each reply is labeled as coming from Claude Code so reviewers know it was written by the agent and not by you directly.

87 93

~~88You can also start a web session directly from the command line:~~94## Moving tasks between web and terminal

96You can start new tasks on the web from your terminal, or pull web sessions into your terminal to continue locally. Web sessions persist even if you close your laptop, and you can monitor them from anywhere including the Claude mobile app.

98<Note>

99 Session handoff is one-way: you can pull web sessions into your terminal, but you can't push an existing terminal session to the web. The `--remote` flag creates a *new* web session for your current repository.

100</Note>

101

102### From terminal to web

103

104Start a web session from the command line with the `--remote` flag:

89 105

90```bash theme={null}106```bash theme={null}

91claude --remote "Fix the authentication bug in src/auth/login.ts"107claude --remote "Fix the authentication bug in src/auth/login.ts"

92```108```

93 109

~~94#### Tips for background tasks~~110This creates a new web session on claude.ai. The task runs in the cloud while you continue working locally. Use `/tasks` to check progress, or open the session on claude.ai or the Claude mobile app to interact directly. From there you can steer Claude, provide feedback, or answer questions just like any other conversation.

95 111

~~96**Plan locally, execute remotely**: For complex tasks, start Claude in plan mode to collaborate on the approach before sending work to the web:~~112#### Tips for remote tasks

113

114**Plan locally, execute remotely**: For complex tasks, start Claude in plan mode to collaborate on the approach, then send work to the web:

97 115

98```bash theme={null}116```bash theme={null}

99claude --permission-mode plan117claude --permission-mode plan

100```118```

101 119

102In plan mode, Claude can only read files and explore the codebase. Once you're satisfied with the plan, send it to the web for autonomous execution:120In plan mode, Claude can only read files and explore the codebase. Once you're satisfied with the plan, start a remote session for autonomous execution:

103 121

104```122```bash theme={null}

105& Execute the migration plan we discussed123claude --remote "Execute the migration plan in docs/migration-plan.md"

106```124```

107 125

108This pattern gives you control over the strategy while letting Claude execute autonomously in the cloud.126This pattern gives you control over the strategy while letting Claude execute autonomously in the cloud.

109 127

110**Run tasks in parallel**: Each `&` command creates its own web session that runs independently. You can kick off multiple tasks and they'll all run simultaneously in separate sessions:128**Run tasks in parallel**: Each `--remote` command creates its own web session that runs independently. You can kick off multiple tasks and they'll all run simultaneously in separate sessions:

111 129

112```130```bash theme={null}

113& Fix the flaky test in auth.spec.ts131claude --remote "Fix the flaky test in auth.spec.ts"

114& Update the API documentation132claude --remote "Update the API documentation"

115& Refactor the logger to use structured output133claude --remote "Refactor the logger to use structured output"

116```134```

117 135

118Monitor all sessions with `/tasks`. When a session completes, you can create a PR from the web interface or [teleport](#from-web-to-terminal) the session to your terminal to continue working.136Monitor all sessions with `/tasks`. When a session completes, you can create a PR from the web interface or [teleport](#from-web-to-terminal) the session to your terminal to continue working.

139| Branch available | The branch from the web session must have been pushed to the remote. Teleport automatically fetches and checks it out. |157| Branch available | The branch from the web session must have been pushed to the remote. Teleport automatically fetches and checks it out. |

140| Same account | You must be authenticated to the same Claude.ai account used in the web session. |158| Same account | You must be authenticated to the same Claude.ai account used in the web session. |

141 159

160### Sharing sessions

161

162To share a session, toggle its visibility according to the account

163types below. After that, share the session link as-is. Recipients who open your

164shared session will see the latest state of the session upon load, but the

165recipient's page will not update in real time.

166

167#### Sharing from an Enterprise or Teams account

168

169For Enterprise and Teams accounts, the two visibility options are **Private**

170and **Team**. Team visibility makes the session visible to other members of your

171Claude.ai organization. Repository access verification is enabled by default,

172based on the GitHub account connected to the recipient's account. Your account's

173display name is visible to all recipients with access. [Claude in Slack](/en/slack)

174sessions are automatically shared with Team visibility.

175

176#### Sharing from a Max or Pro account

177

178For Max and Pro accounts, the two visibility options are **Private**

179and **Public**. Public visibility makes the session visible to any user logged

180into claude.ai.

181

182Check your session for sensitive content before sharing. Sessions may contain

183code and credentials from private GitHub repositories. Repository access

184verification is not enabled by default.

185

186Enable repository access verification and/or withhold your name from your shared

187sessions by going to Settings > Claude Code > Sharing settings.

188

189## Schedule recurring tasks

190

191Run Claude on a recurring schedule to automate work like daily PR reviews, dependency audits, and CI failure analysis. See [Schedule tasks on the web](/en/web-scheduled-tasks) for the full guide.

192

193## Managing sessions

194

195### Archiving sessions

196

197You can archive sessions to keep your session list organized. Archived sessions are hidden from the default session list but can be viewed by filtering for archived sessions.

198

199To archive a session, hover over the session in the sidebar and click the archive icon.

200

201### Deleting sessions

202

203Deleting a session permanently removes the session and its data. This action cannot be undone. You can delete a session in two ways:

204

205* **From the sidebar**: Filter for archived sessions, then hover over the session you want to delete and click the delete icon

206* **From the session menu**: Open a session, click the dropdown next to the session title, and select **Delete**

207

208You will be asked to confirm before a session is deleted.

209

142## Cloud environment210## Cloud environment

143 211

144### Default image212### Default image

187 255

188When you start a session in Claude Code on the web, here's what happens under the hood:256When you start a session in Claude Code on the web, here's what happens under the hood:

189 257

1901. **Environment preparation**: We clone your repository and run any configured Claude hooks for initialization. The repo will be cloned with the default branch on your GitHub repo. If you would like to check out a specific branch, you can specify that in the prompt.2581. **Environment preparation**: We clone your repository and run any configured [setup script](#setup-scripts). The repo will be cloned with the default branch on your GitHub repo. If you would like to check out a specific branch, you can specify that in the prompt.

191 259

1922. **Network configuration**: We configure internet access for the agent. Internet access is limited by default, but you can configure the environment to have no internet or full internet access based on your needs.2602. **Network configuration**: We configure internet access for the agent. Internet access is limited by default, but you can configure the environment to have no internet or full internet access based on your needs.

193 261

199 Claude operates entirely through the terminal and CLI tools available in the environment. It uses the pre-installed tools in the universal image and any additional tools you install through hooks or dependency management.267 Claude operates entirely through the terminal and CLI tools available in the environment. It uses the pre-installed tools in the universal image and any additional tools you install through hooks or dependency management.

200</Note>268</Note>

201 269

202**To add a new environment:** Select the current environment to open the environment selector, and then select "Add environment". This will open a dialog where you can specify the environment name, network access level, and any environment variables you want to set.270**To add a new environment:** Select the current environment to open the environment selector, and then select "Add environment". This will open a dialog where you can specify the environment name, network access level, environment variables, and a [setup script](#setup-scripts).

203 271

204**To update an existing environment:** Select the current environment, to the right of the environment name, and select the settings button. This will open a dialog where you can update the environment name, network access, and environment variables.272**To update an existing environment:** Select the current environment, to the right of the environment name, and select the settings button. This will open a dialog where you can update the environment name, network access, environment variables, and setup script.

205 273

206**To select your default environment from the terminal:** If you have multiple environments configured, run `/remote-env` to choose which one to use when starting web sessions from your terminal with `&` or `--remote`. With a single environment, this command shows your current configuration.274**To select your default environment from the terminal:** If you have multiple environments configured, run `/remote-env` to choose which one to use when starting web sessions from your terminal with `--remote`. With a single environment, this command shows your current configuration.

207 275

208<Note>276<Note>

209 Environment variables must be specified as key-value pairs, in [`.env` format](https://www.dotenv.org/). For example:277 Environment variables must be specified as key-value pairs, in [`.env` format](https://www.dotenv.org/). For example:

210 278

211 ```279 ```text theme={null}

212 API_KEY=your_api_key280 API_KEY=your_api_key

213 DEBUG=true281 DEBUG=true

214 ```282 ```

215</Note>283</Note>

216 284

285### Setup scripts

286

287A setup script is a Bash script that runs when a new cloud session starts, before Claude Code launches. Use setup scripts to install dependencies, configure tools, or prepare anything the cloud environment needs that isn't in the [default image](#default-image).

288

289Scripts run as root on Ubuntu 24.04, so `apt install` and most language package managers work.

290

291<Tip>

292 To check what's already installed before adding it to your script, ask Claude to run `check-tools` in a cloud session.

293</Tip>

294

295To add a setup script, open the environment settings dialog and enter your script in the **Setup script** field.

296

297This example installs the `gh` CLI, which isn't in the default image:

298

299```bash theme={null}

300#!/bin/bash

301apt update && apt install -y gh

302```

303

304Setup scripts run only when creating a new session. They are skipped when resuming an existing session.

305

306If the script exits non-zero, the session fails to start. Append `|| true` to non-critical commands to avoid blocking the session on a flaky install.

307

308<Note>

309 Setup scripts that install packages need network access to reach registries. The default network access allows connections to [common package registries](#default-allowed-domains) including npm, PyPI, RubyGems, and crates.io. Scripts will fail to install packages if your environment has network access disabled.

310</Note>

311

312#### Setup scripts vs. SessionStart hooks

313

314Use a setup script to install things the cloud needs but your laptop already has, like a language runtime or CLI tool. Use a [SessionStart hook](/en/hooks#sessionstart) for project setup that should run everywhere, cloud and local, like `npm install`.

315

316Both run at the start of a session, but they belong to different places:

317

318| | Setup scripts | SessionStart hooks |

319| ------------- | ------------------------------------------------- | -------------------------------------------------------------- |

320| Attached to | The cloud environment | Your repository |

321| Configured in | Cloud environment UI | `.claude/settings.json` in your repo |

322| Runs | Before Claude Code launches, on new sessions only | After Claude Code launches, on every session including resumed |

323| Scope | Cloud environments only | Both local and cloud |

324

325SessionStart hooks can also be defined in your user-level `~/.claude/settings.json` locally, but user-level settings don't carry over to cloud sessions. In the cloud, only hooks committed to the repo run.

326

217### Dependency management327### Dependency management

218 328

219Configure automatic dependency installation using [SessionStart hooks](/en/hooks#sessionstart). This can be configured in your repository's `.claude/settings.json` file:329Custom environment images and snapshots are not yet supported. Use [setup scripts](#setup-scripts) to install packages when a session starts, or [SessionStart hooks](/en/hooks#sessionstart) for dependency installation that should also run in local environments. SessionStart hooks have [known limitations](#dependency-management-limitations).

330

331To configure automatic dependency installation with a setup script, open your environment settings and add a script:

332

333```bash theme={null}

334#!/bin/bash

335npm install

336pip install -r requirements.txt

337```

338

339Alternatively, you can use SessionStart hooks in your repository's `.claude/settings.json` file for dependency installation that should also run in local environments:

220 340

221```json theme={null}341```json theme={null}

222{342{

238 358

239Create the corresponding script at `scripts/install_pkgs.sh`:359Create the corresponding script at `scripts/install_pkgs.sh`:

240 360

241```bash theme={null}

242#!/bin/bash

243npm install

244pip install -r requirements.txt

245exit 0

246```

~~247~~

248Make it executable: `chmod +x scripts/install_pkgs.sh`

~~249~~

250#### Local vs remote execution

~~251~~

252By default, all hooks execute both locally and in remote (web) environments. To run a hook only in one environment, check the `CLAUDE_CODE_REMOTE` environment variable in your hook script.

~~253~~

254```bash theme={null}361```bash theme={null}

255#!/bin/bash362#!/bin/bash

256 363

257# Example: Only run in remote environments364# Only run in remote environments

258if [ "$CLAUDE_CODE_REMOTE" != "true" ]; then365if [ "$CLAUDE_CODE_REMOTE" != "true" ]; then

259 exit 0366 exit 0

260fi367fi

261 368

262npm install369npm install

263pip install -r requirements.txt370pip install -r requirements.txt

371exit 0

264```372```

265 373

266#### Persisting environment variables374Make it executable: `chmod +x scripts/install_pkgs.sh`

375

376#### Persist environment variables

377

378SessionStart hooks can persist environment variables for subsequent Bash commands by writing to the file specified in the `CLAUDE_ENV_FILE` environment variable. For details, see [SessionStart hooks](/en/hooks#sessionstart) in the hooks reference.

379

380#### Dependency management limitations

267 381

268SessionStart hooks can persist environment variables for subsequent bash commands by writing to the file specified in the `CLAUDE_ENV_FILE` environment variable. For details, see [SessionStart hooks](/en/hooks#sessionstart) in the hooks reference.382* **Hooks fire for all sessions**: SessionStart hooks run in both local and remote environments. There is no hook configuration to scope a hook to remote sessions only. To skip local execution, check the `CLAUDE_CODE_REMOTE` environment variable in your script as shown above.

383* **Requires network access**: Install commands need network access to reach package registries. If your environment is configured with "No internet" access, these hooks will fail. Use "Limited" (the default) or "Full" network access. The [default allowlist](#default-allowed-domains) includes common registries like npm, PyPI, RubyGems, and crates.io.

384* **Proxy compatibility**: All outbound traffic in remote environments passes through a [security proxy](#security-proxy). Some package managers do not work correctly with this proxy. Bun is a known example.

385* **Runs on every session start**: Hooks run each time a session starts or resumes, adding startup latency. Keep install scripts fast by checking whether dependencies are already present before reinstalling.

269 386

270## Network access and security387## Network access and security

271 388

301 418

302* api.anthropic.com419* api.anthropic.com

303* statsig.anthropic.com420* statsig.anthropic.com

304* docs.claude.com421* platform.claude.com

305* code.claude.com422* code.claude.com

306* claude.ai423* claude.ai

307 424

572 689

573## Best practices690## Best practices

574 691

5751. **Use Claude Code hooks**: Configure [SessionStart hooks](/en/hooks#sessionstart) to automate environment setup and dependency installation.6921. **Automate environment setup**: Use [setup scripts](#setup-scripts) to install dependencies and configure tools before Claude Code launches. For more advanced scenarios, configure [SessionStart hooks](/en/hooks#sessionstart).

5762. **Document requirements**: Clearly specify dependencies and commands in your `CLAUDE.md` file. If you have an `AGENTS.md` file, you can source it in your `CLAUDE.md` using `@AGENTS.md` to maintain a single source of truth.6932. **Document requirements**: Clearly specify dependencies and commands in your `CLAUDE.md` file. If you have an `AGENTS.md` file, you can source it in your `CLAUDE.md` using `@AGENTS.md` to maintain a single source of truth.

577 694

578## Related resources695## Related resources

claude-directory.md +82 −0 added

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# Explore the .claude directory

7> Where Claude Code reads CLAUDE.md, settings.json, hooks, skills, commands, subagents, rules, and auto memory. Explore the .claude directory in your project and ~/.claude in your home directory.

10Claude Code reads instructions, settings, skills, subagents, and memory from your project directory and from `~/.claude` in your home directory. Commit project files to git to share them with your team; files in `~/.claude` are personal configuration that applies across all your projects.

12Most users only edit `CLAUDE.md` and `settings.json`. The rest of the directory is optional: add skills, rules, or subagents as you need them.

14This page is an interactive explorer: click files in the tree to see what each one does, when it loads, and an example. For a quick reference, see the [file reference table](#file-reference) below.

16<ClaudeExplorer />

18## What's not shown

20The explorer covers the files you'll interact with most. A few things live elsewhere:

22| File | Location | Purpose |

23| ----------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------- |

24| `managed-settings.json` | System-level, varies by OS | Enterprise-enforced settings that you can't override. See [server-managed settings](/en/server-managed-settings). |

25| `CLAUDE.local.md` | Project root | Your private preferences for this project, loaded alongside CLAUDE.md. Create it manually and add it to `.gitignore`. |

27## File reference

29This table lists every file the explorer covers. Project-scope files live in your repo under `.claude/` (or at the root for `CLAUDE.md`, `.mcp.json`, and `.worktreeinclude`). Global-scope files live in `~/.claude/` and apply across all projects.

31<Note>

32 Several things can override what you put in these files:

34 * [Managed settings](/en/server-managed-settings) deployed by your organization take precedence over everything

35 * CLI flags like `--permission-mode` or `--settings` override `settings.json` for that session

36 * Some environment variables take precedence over their equivalent setting, but this varies: check the [environment variables reference](/en/env-vars) for each one

38 See [settings precedence](/en/settings#settings-precedence) for the full order.

39</Note>

41Click a filename to open that node in the explorer above.

44| --------------------------------------------------- | ------------------ | ------ | ----------------------------------------------------- | -------------------------------------------------------------------- |

46| [`rules/*.md`](#ce-rules) | Project and global | ✓ | Topic-scoped instructions, optionally path-gated | [Rules](/en/memory#organize-rules-with-claude/rules/) |

52| [`commands/*.md`](#ce-commands) | Project and global | ✓ | Single-file prompts; same mechanism as skills | [Skills](/en/skills) |

53| [`output-styles/*.md`](#ce-output-styles) | Project and global | ✓ | Custom system-prompt sections | [Output styles](/en/output-styles) |

54| [`agents/*.md`](#ce-agents) | Project and global | ✓ | Subagent definitions with their own prompt and tools | [Subagents](/en/sub-agents) |

60## Check what loaded

62The explorer shows what files can exist. To see what actually loaded in your current session, use these commands:

64| Command | Shows |

65| -------------- | ------------------------------------------------------------------------------------- |

66| `/context` | Token usage by category: system prompt, memory files, skills, MCP tools, and messages |

67| `/memory` | Which CLAUDE.md and rules files loaded, plus auto-memory entries |

68| `/agents` | Configured subagents and their settings |

69| `/hooks` | Active hook configurations |

70| `/mcp` | Connected MCP servers and their status |

71| `/skills` | Available skills from project, user, and plugin sources |

72| `/permissions` | Current allow and deny rules |

73| `/doctor` | Installation and configuration diagnostics |

75Run `/context` first for the overview, then the specific command for the area you want to investigate.

77## Related resources

79* [Manage Claude's memory](/en/memory): write and organize CLAUDE.md, rules, and auto memory

80* [Configure settings](/en/settings): set permissions, hooks, environment variables, and model defaults

81* [Create skills](/en/skills): build reusable prompts and workflows

82* [Configure subagents](/en/sub-agents): define specialized agents with their own context

cli-reference.md +47 −85

Details

8 8

9## CLI commands9## CLI commands

10 10

11You can start sessions, pipe content, resume conversations, and manage updates with these commands:

~~12| :------------------------------ | :----------------------------------------------------- | :------------------------------------------------ |~~14| :------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------- |

23| `claude auth login` | Sign in to your Anthropic account. Use `--email` to pre-fill your email address, `--sso` to force SSO authentication, and `--console` to sign in with Anthropic Console for API usage billing instead of a Claude subscription | `claude auth login --console` |

24| `claude auth logout` | Log out from your Anthropic account | `claude auth logout` |

25| `claude auth status` | Show authentication status as JSON. Use `--text` for human-readable output. Exits with code 0 if logged in, 1 if not | `claude auth status` |

26| `claude agents` | List all configured [subagents](/en/sub-agents), grouped by source | `claude agents` |

27| `claude auto-mode defaults` | Print the built-in [auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) classifier rules as JSON. Use `claude auto-mode config` to see your effective config with settings applied | `claude auto-mode defaults > rules.json` |

29| `claude plugin` | Manage Claude Code [plugins](/en/plugins). Alias: `claude plugins`. See [plugin reference](/en/plugins-reference#cli-commands-reference) for subcommands | `claude plugin install code-review@claude-plugins-official` |

30| `claude remote-control` | Start a [Remote Control](/en/remote-control) server to control Claude Code from Claude.ai or the Claude app. Runs in server mode (no local interactive session). See [Server mode flags](/en/remote-control#server-mode) | `claude remote-control --name "My Project"` |

22 31

23## CLI flags32## CLI flags

24 33

25Customize Claude Code's behavior with these command-line flags:34Customize Claude Code's behavior with these command-line flags:

26 35

28| :------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------- |37| :---------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------- |

31| `--agents` | Define custom [subagents](/en/sub-agents) dynamically via JSON (see below for format) | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` |40| `--agents` | Define custom subagents dynamically via JSON. Uses the same field names as subagent [frontmatter](/en/sub-agents#supported-frontmatter-fields), plus a `prompt` field for the agent's instructions | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` |

32| `--allow-dangerously-skip-permissions` | Enable permission bypassing as an option without immediately activating it. Allows composing with `--permission-mode` (use with caution) | `claude --permission-mode plan --allow-dangerously-skip-permissions` |41| `--allow-dangerously-skip-permissions` | Enable permission bypassing as an option without immediately activating it. Allows composing with `--permission-mode` (use with caution) | `claude --permission-mode plan --allow-dangerously-skip-permissions` |

33| `--allowedTools` | Tools that execute without prompting for permission. See [permission rule syntax](/en/settings#permission-rule-syntax) for pattern matching. To restrict which tools are available, use `--tools` instead | `"Bash(git log *)" "Bash(git diff *)" "Read"` |42| `--allowedTools` | Tools that execute without prompting for permission. See [permission rule syntax](/en/settings#permission-rule-syntax) for pattern matching. To restrict which tools are available, use `--tools` instead | `"Bash(git log *)" "Bash(git diff *)" "Read"` |

35| `--append-system-prompt-file` | Load additional system prompt text from a file and append to the default prompt (print mode only) | `claude -p --append-system-prompt-file ./extra-rules.txt "query"` |44| `--append-system-prompt-file` | Load additional system prompt text from a file and append to the default prompt | `claude --append-system-prompt-file ./extra-rules.txt` |

45| `--bare` | Minimal mode: skip auto-discovery of hooks, skills, plugins, MCP servers, auto memory, and CLAUDE.md so scripted calls start faster. Claude has access to Bash, file read, and file edit tools. Sets [`CLAUDE_CODE_SIMPLE`](/en/env-vars). See [bare mode](/en/headless#start-faster-with-bare-mode) | `claude --bare -p "query"` |

47| `--channels` | (Research preview) MCP servers whose [channel](/en/channels) notifications Claude should listen for in this session. Space-separated list of `plugin:<name>@<marketplace>` entries. Requires Claude.ai authentication | `claude --channels plugin:my-notifier@my-marketplace` |

39| `--dangerously-skip-permissions` | Skip all permission prompts (use with caution) | `claude --dangerously-skip-permissions` |50| `--dangerously-load-development-channels` | Enable [channels](/en/channels-reference#test-during-the-research-preview) that are not on the approved allowlist, for local development. Accepts `plugin:<name>@<marketplace>` and `server:<name>` entries. Prompts for confirmation | `claude --dangerously-load-development-channels server:webhook` |

51| `--dangerously-skip-permissions` | Skip permission prompts (use with caution). See [permission modes](/en/permission-modes#skip-all-checks-with-bypasspermissions-mode) for what this does and does not skip | `claude --dangerously-skip-permissions` |

55| `--effort` | Set the [effort level](/en/model-config#adjust-effort-level) for the current session. Options: `low`, `medium`, `high`, `max` (Opus 4.6 only). Session-scoped and does not persist to settings | `claude --effort high` |

44| `--fork-session` | When resuming, create a new session ID instead of reusing the original (use with `--resume` or `--continue`) | `claude --resume abc123 --fork-session` |57| `--fork-session` | When resuming, create a new session ID instead of reusing the original (use with `--resume` or `--continue`) | `claude --resume abc123 --fork-session` |

45| `--from-pr` | Resume sessions linked to a specific GitHub PR. Accepts a PR number or URL. Sessions are automatically linked when created via `gh pr create` | `claude --from-pr 123` |58| `--from-pr` | Resume sessions linked to a specific GitHub PR. Accepts a PR number or URL. Sessions are automatically linked when created via `gh pr create` | `claude --from-pr 123` |

49| `--include-partial-messages` | Include partial streaming events in output (requires `--print` and `--output-format=stream-json`) | `claude -p --output-format stream-json --include-partial-messages "query"` |62| `--include-partial-messages` | Include partial streaming events in output (requires `--print` and `--output-format=stream-json`) | `claude -p --output-format stream-json --include-partial-messages "query"` |

51| `--json-schema` | Get validated JSON output matching a JSON Schema after agent completes its workflow (print mode only, see [Agent SDK Structured Outputs](https://docs.claude.com/en/docs/agent-sdk/structured-outputs)) | `claude -p --json-schema '{"type":"object","properties":{...}}' "query"` |64| `--json-schema` | Get validated JSON output matching a JSON Schema after agent completes its workflow (print mode only, see [structured outputs](https://platform.claude.com/docs/en/agent-sdk/structured-outputs)) | `claude -p --json-schema '{"type":"object","properties":{...}}' "query"` |

54| `--max-turns` | Limit the number of agentic turns (print mode only). Exits with an error when the limit is reached. No limit by default | `claude -p --max-turns 3 "query"` |67| `--max-turns` | Limit the number of agentic turns (print mode only). Exits with an error when the limit is reached. No limit by default | `claude -p --max-turns 3 "query"` |

56| `--model` | Sets the model for the current session with an alias for the latest model (`sonnet` or `opus`) or a model's full name | `claude --model claude-sonnet-4-5-20250929` |69| `--model` | Sets the model for the current session with an alias for the latest model (`sonnet` or `opus`) or a model's full name | `claude --model claude-sonnet-4-6` |

70| `--name`, `-n` | Set a display name for the session, shown in `/resume` and the terminal title. You can resume a named session with `claude --resume <name>`. [`/rename`](/en/commands) changes the name mid-session and also shows it on the prompt bar | `claude -n "my-feature-work"` |

58| `--no-session-persistence` | Disable session persistence so sessions are not saved to disk and cannot be resumed (print mode only) | `claude -p --no-session-persistence "query"` |72| `--no-session-persistence` | Disable session persistence so sessions are not saved to disk and cannot be resumed (print mode only) | `claude -p --no-session-persistence "query"` |

60| `--permission-mode` | Begin in a specified [permission mode](/en/iam#permission-modes) | `claude --permission-mode plan` |74| `--enable-auto-mode` | Unlock [auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) in the `Shift+Tab` cycle. Requires a Team plan (Enterprise and API support rolling out shortly) and Claude Sonnet 4.6 or Opus 4.6 | `claude --enable-auto-mode` |

75| `--permission-mode` | Begin in a specified [permission mode](/en/permission-modes) | `claude --permission-mode plan` |

63| `--print`, `-p` | Print response without interactive mode (see [SDK documentation](https://docs.claude.com/en/docs/agent-sdk) for programmatic usage details) | `claude -p "query"` |78| `--print`, `-p` | Print response without interactive mode (see [Agent SDK documentation](https://platform.claude.com/docs/en/agent-sdk/overview) for programmatic usage details) | `claude -p "query"` |

80| `--remote-control`, `--rc` | Start an interactive session with [Remote Control](/en/remote-control#interactive-session) enabled so you can also control it from claude.ai or the Claude app. Optionally pass a name for the session | `claude --remote-control "My Project"` |

73| `--tools` | Restrict which built-in tools Claude can use (works in both interactive and print modes). Use `""` to disable all, `"default"` for all, or tool names like `"Bash,Edit,Read"` | `claude --tools "Bash,Edit,Read"` |89| `--teammate-mode` | Set how [agent team](/en/agent-teams) teammates display: `auto` (default), `in-process`, or `tmux`. See [set up agent teams](/en/agent-teams#set-up-agent-teams) | `claude --teammate-mode in-process` |

91| `--verbose` | Enable verbose logging, shows full turn-by-turn output | `claude --verbose` |

76 93| `--worktree`, `-w` | Start Claude in an isolated [git worktree](/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees) at `<repo>/.claude/worktrees/<name>`. If no name is given, one is auto-generated | `claude -w feature-auth` |

~~77<Tip>~~94| `--tmux` | Create a tmux session for the worktree. Requires `--worktree`. Uses iTerm2 native panes when available; pass `--tmux=classic` for traditional tmux | `claude -w feature-auth --tmux` |

~~78 The `--output-format json` flag is particularly useful for scripting and~~

~~79 automation, allowing you to parse Claude's responses programmatically.~~

~~80</Tip>~~

~~82### Agents flag format~~

~~84The `--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| Field | Required | Description |~~

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

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

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

~~90| `tools` | No | Array of specific tools the subagent can use (for example, `["Read", "Edit", "Bash"]`). If omitted, inherits all tools |~~

~~91| `model` | No | Model alias to use: `sonnet`, `opus`, `haiku`, or `inherit`. If omitted, defaults to `inherit` (uses the main conversation's model) |~~

~~93Example:~~

~~95```bash theme={null}~~

~~96claude --agents '{~~

~~97 "code-reviewer": {~~

~~98 "description": "Expert code reviewer. Use proactively after code changes.",~~

~~99 "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",~~

100 "tools": ["Read", "Grep", "Glob", "Bash"],

101 "model": "sonnet"

102 },

103 "debugger": {

104 "description": "Debugging specialist for errors and test failures.",

105 "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."

106 }

107}'

108```

~~109~~

110For more details on creating and using subagents, see the [subagents documentation](/en/sub-agents).

111 95

112### System prompt flags96### System prompt flags

113 97

114Claude Code provides four flags for customizing the system prompt, each serving a different purpose:98Claude Code provides four flags for customizing the system prompt. All four work in both interactive and non-interactive modes.

~~115~~

117| :---------------------------- | :------------------------------------------ | :------------------ | :------------------------------------------------------------------- |

~~122~~

123**When to use each:**

~~124~~

125* **`--system-prompt`**: Use when you need complete control over Claude's system prompt. This removes all default Claude Code instructions, giving you a blank slate.

126 ```bash theme={null}

127 claude --system-prompt "You are a Python expert who only writes type-annotated code"

128 ```

~~129~~

130* **`--system-prompt-file`**: Use when you want to load a custom prompt from a file, useful for team consistency or version-controlled prompt templates.

131 ```bash theme={null}

132 claude -p --system-prompt-file ./prompts/code-review.txt "Review this PR"

133 ```

~~134~~

135* **`--append-system-prompt`**: Use when you want to add specific instructions while keeping Claude Code's default capabilities intact. This is the safest option for most use cases.

136 ```bash theme={null}

137 claude --append-system-prompt "Always use TypeScript and include JSDoc comments"

138 ```

139 99

140* **`--append-system-prompt-file`**: Use when you want to append instructions from a file while keeping Claude Code's defaults. Useful for version-controlled additions.100| Flag | Behavior | Example |

141 ```bash theme={null}101| :---------------------------- | :------------------------------------------ | :------------------------------------------------------ |

142 claude -p --append-system-prompt-file ./prompts/style-rules.txt "Review this PR"102| `--system-prompt` | Replaces the entire default prompt | `claude --system-prompt "You are a Python expert"` |

143 ```103| `--system-prompt-file` | Replaces with file contents | `claude --system-prompt-file ./prompts/review.txt` |

104| `--append-system-prompt` | Appends to the default prompt | `claude --append-system-prompt "Always use TypeScript"` |

105| `--append-system-prompt-file` | Appends file contents to the default prompt | `claude --append-system-prompt-file ./style-rules.txt` |

144 106

145`--system-prompt` and `--system-prompt-file` are mutually exclusive. The append flags can be used together with either replacement flag.107`--system-prompt` and `--system-prompt-file` are mutually exclusive. The append flags can be combined with either replacement flag.

146 108

147For most use cases, `--append-system-prompt` or `--append-system-prompt-file` is recommended as they preserve Claude Code's built-in capabilities while adding your custom requirements. Use `--system-prompt` or `--system-prompt-file` only when you need complete control over the system prompt.109For most use cases, use an append flag. Appending preserves Claude Code's built-in capabilities while adding your requirements. Use a replacement flag only when you need complete control over the system prompt.

148 110

149## See also111## See also

150 112

153* [Quickstart guide](/en/quickstart) - Getting started with Claude Code115* [Quickstart guide](/en/quickstart) - Getting started with Claude Code

154* [Common workflows](/en/common-workflows) - Advanced workflows and patterns116* [Common workflows](/en/common-workflows) - Advanced workflows and patterns

155* [Settings](/en/settings) - Configuration options117* [Settings](/en/settings) - Configuration options

156* [SDK documentation](https://docs.claude.com/en/docs/agent-sdk) - Programmatic usage and integrations118* [Agent SDK documentation](https://platform.claude.com/docs/en/agent-sdk/overview) - Programmatic usage and integrations

code-review.md +217 −0 added

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# Code Review

7> Set up automated PR reviews that catch logic errors, security vulnerabilities, and regressions using multi-agent analysis of your full codebase

9<Note>

10 Code Review is in research preview, available for [Teams and Enterprise](https://claude.ai/admin-settings/claude-code) subscriptions. It is not available for organizations with [Zero Data Retention](/en/zero-data-retention) enabled.

11</Note>

13Code Review analyzes your GitHub pull requests and posts findings as inline comments on the lines of code where it found issues. A fleet of specialized agents examine the code changes in the context of your full codebase, looking for logic errors, security vulnerabilities, broken edge cases, and subtle regressions.

15Findings are tagged by severity and don't approve or block your PR, so existing review workflows stay intact. You can tune what Claude flags by adding a `CLAUDE.md` or `REVIEW.md` file to your repository.

17To run Claude in your own CI infrastructure instead of this managed service, see [GitHub Actions](/en/github-actions) or [GitLab CI/CD](/en/gitlab-ci-cd).

19This page covers:

21* [How reviews work](#how-reviews-work)

22* [Setup](#set-up-code-review)

23* [Triggering reviews manually](#manually-trigger-reviews) with `@claude review` and `@claude review once`

24* [Customizing reviews](#customize-reviews) with `CLAUDE.md` and `REVIEW.md`

25* [Pricing](#pricing)

27## How reviews work

29Once an admin [enables Code Review](#set-up-code-review) for your organization, reviews trigger when a PR opens, on every push, or when manually requested, depending on the repository's configured behavior. Commenting `@claude review` [starts reviews on a PR](#manually-trigger-reviews) in any mode.

31When a review runs, multiple agents analyze the diff and surrounding code in parallel on Anthropic infrastructure. Each agent looks for a different class of issue, then a verification step checks candidates against actual code behavior to filter out false positives. The results are deduplicated, ranked by severity, and posted as inline comments on the specific lines where issues were found. If no issues are found, Claude posts a short confirmation comment on the PR.

33Reviews scale in cost with PR size and complexity, completing in 20 minutes on average. Admins can monitor review activity and spend via the [analytics dashboard](#view-usage).

35### Severity levels

37Each finding is tagged with a severity level:

39| Marker | Severity | Meaning |

40| :----- | :----------- | :------------------------------------------------------------------ |

41| 🔴 | Important | A bug that should be fixed before merging |

42| 🟡 | Nit | A minor issue, worth fixing but not blocking |

43| 🟣 | Pre-existing | A bug that exists in the codebase but was not introduced by this PR |

45Findings include a collapsible extended reasoning section you can expand to understand why Claude flagged the issue and how it verified the problem.

47### Check run output

49Beyond the inline review comments, each review populates the **Claude Code Review** check run that appears alongside your CI checks. Expand its **Details** link to see a summary of every finding in one place, sorted by severity:

51| Severity | File:Line | Issue |

52| ------------ | ------------------------- | -------------------------------------------------------------- |

53| 🔴 Important | `src/auth/session.ts:142` | Token refresh races with logout, leaving stale sessions active |

54| 🟡 Nit | `src/auth/session.ts:88` | `parseExpiry` silently returns 0 on malformed input |

56Each finding also appears as an annotation in the **Files changed** tab, marked directly on the relevant diff lines. Important findings render with a red marker, nits with a yellow warning, and pre-existing bugs with a gray notice.

58The check run always completes with a neutral conclusion so it never blocks merging through branch protection rules. If you want to gate merges on Code Review findings, read the severity breakdown from the check run output in your own CI. The last line of the Details text is a machine-readable comment your workflow can parse with `gh` and jq:

60```bash theme={null}

61gh api repos/OWNER/REPO/check-runs/CHECK_RUN_ID \

62 --jq '.output.text | split("bughunter-severity: ")[1] | split(" -->")[0] | fromjson'

63```

65This returns a JSON object with counts per severity, for example `{"normal": 2, "nit": 1, "pre_existing": 0}`. The `normal` key holds the count of Important findings; a non-zero value means Claude found at least one bug worth fixing before merge.

67### What Code Review checks

69By default, Code Review focuses on correctness: bugs that would break production, not formatting preferences or missing test coverage. You can expand what it checks by [adding guidance files](#customize-reviews) to your repository.

71## Set up Code Review

73An admin enables Code Review once for the organization and selects which repositories to include.

75<Steps>

76 <Step title="Open Claude Code admin settings">

77 Go to [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) and find the Code Review section. You need admin access to your Claude organization and permission to install GitHub Apps in your GitHub organization.

78 </Step>

80 <Step title="Start setup">

81 Click **Setup**. This begins the GitHub App installation flow.

82 </Step>

84 <Step title="Install the Claude GitHub App">

85 Follow the prompts to install the Claude GitHub App to your GitHub organization. The app requests these repository permissions:

87 * **Contents**: read and write

88 * **Issues**: read and write

89 * **Pull requests**: read and write

91 Code Review uses read access to contents and write access to pull requests. The broader permission set also supports [GitHub Actions](/en/github-actions) if you enable that later.

92 </Step>

94 <Step title="Select repositories">

95 Choose which repositories to enable for Code Review. If you don't see a repository, make sure you gave the Claude GitHub App access to it during installation. You can add more repositories later.

96 </Step>

98 <Step title="Set review triggers per repo">

99 After setup completes, the Code Review section shows your repositories in a table. For each repository, use the **Review Behavior** dropdown to choose when reviews run:

100

101 * **Once after PR creation**: review runs once when a PR is opened or marked ready for review

102 * **After every push**: review runs on every push to the PR branch, catching new issues as the PR evolves and auto-resolving threads when you fix flagged issues

103 * **Manual**: reviews start only when someone [comments `@claude review` or `@claude review once` on a PR](#manually-trigger-reviews); `@claude review` also subscribes the PR to reviews on subsequent pushes

104

105 Reviewing on every push runs the most reviews and costs the most. Manual mode is useful for high-traffic repos where you want to opt specific PRs into review, or to only start reviewing your PRs once they're ready.

106 </Step>

107</Steps>

108

109The repositories table also shows the average cost per review for each repo based on recent activity. Use the row actions menu to turn Code Review on or off per repository, or to remove a repository entirely.

110

111To verify setup, open a test PR. If you chose an automatic trigger, a check run named **Claude Code Review** appears within a few minutes. If you chose Manual, comment `@claude review` on the PR to start the first review. If no check run appears, confirm the repository is listed in your admin settings and the Claude GitHub App has access to it.

112

113## Manually trigger reviews

114

115Two comment commands start a review on demand. Both work regardless of the repository's configured trigger, so you can use them to opt specific PRs into review in Manual mode or to get an immediate re-review in other modes.

116

117| Command | What it does |

118| :-------------------- | :---------------------------------------------------------------------------- |

119| `@claude review` | Starts a review and subscribes the PR to push-triggered reviews going forward |

120| `@claude review once` | Starts a single review without subscribing the PR to future pushes |

121

122Use `@claude review once` when you want feedback on the current state of a PR but don't want every subsequent push to incur a review. This is useful for long-running PRs with frequent pushes, or when you want a one-off second opinion without changing the PR's review behavior.

123

124For either command to trigger a review:

125

126* Post it as a top-level PR comment, not an inline comment on a diff line

127* Put the command at the start of the comment, with `once` on the same line if you're using the one-shot form

128* You must have owner, member, or collaborator access to the repository

129* The PR must be open

130

131Unlike automatic triggers, manual triggers run on draft PRs, since an explicit request signals you want the review now regardless of draft status.

132

133If a review is already running on that PR, the request is queued until the in-progress review completes. You can monitor progress via the check run on the PR.

134

135## Customize reviews

136

137Code Review reads two files from your repository to guide what it flags. Both are additive on top of the default correctness checks:

138

139* **`CLAUDE.md`**: shared project instructions that Claude Code uses for all tasks, not just reviews. Use it when guidance also applies to interactive Claude Code sessions.

140* **`REVIEW.md`**: review-only guidance, read exclusively during code reviews. Use it for rules that are strictly about what to flag or skip during review and would clutter your general `CLAUDE.md`.

141

142### CLAUDE.md

143

144Code Review reads your repository's `CLAUDE.md` files and treats newly-introduced violations as nit-level findings. This works bidirectionally: if your PR changes code in a way that makes a `CLAUDE.md` statement outdated, Claude flags that the docs need updating too.

145

146Claude reads `CLAUDE.md` files at every level of your directory hierarchy, so rules in a subdirectory's `CLAUDE.md` apply only to files under that path. See the [memory documentation](/en/memory) for more on how `CLAUDE.md` works.

147

148For review-specific guidance that you don't want applied to general Claude Code sessions, use [`REVIEW.md`](#review-md) instead.

149

150### REVIEW\.md

151

152Add a `REVIEW.md` file to your repository root for review-specific rules. Use it to encode:

153

154* Company or team style guidelines: "prefer early returns over nested conditionals"

155* Language- or framework-specific conventions not covered by linters

156* Things Claude should always flag: "any new API route must have an integration test"

157* Things Claude should skip: "don't comment on formatting in generated code under `/gen/`"

158

159Example `REVIEW.md`:

160

161```markdown theme={null}

162# Code Review Guidelines

163

164## Always check

165- New API endpoints have corresponding integration tests

166- Database migrations are backward-compatible

167- Error messages don't leak internal details to users

168

169## Style

170- Prefer `match` statements over chained `isinstance` checks

171- Use structured logging, not f-string interpolation in log calls

172

173## Skip

174- Generated files under `src/gen/`

175- Formatting-only changes in `*.lock` files

176```

177

178Claude auto-discovers `REVIEW.md` at the repository root. No configuration needed.

179

180## View usage

181

182Go to [claude.ai/analytics/code-review](https://claude.ai/analytics/code-review) to see Code Review activity across your organization. The dashboard shows:

183

184| Section | What it shows |

185| :------------------- | :--------------------------------------------------------------------------------------- |

186| PRs reviewed | Daily count of pull requests reviewed over the selected time range |

187| Cost weekly | Weekly spend on Code Review |

188| Feedback | Count of review comments that were auto-resolved because a developer addressed the issue |

189| Repository breakdown | Per-repo counts of PRs reviewed and comments resolved |

190

191The repositories table in admin settings also shows average cost per review for each repo.

192

193## Pricing

194

195Code Review is billed based on token usage. Each review averages \$15-25 in cost, scaling with PR size, codebase complexity, and how many issues require verification. Code Review usage is billed separately through [extra usage](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) and does not count against your plan's included usage.

196

197The review trigger you choose affects total cost:

198

199* **Once after PR creation**: runs once per PR

200* **After every push**: runs on each push, multiplying cost by the number of pushes

201* **Manual**: no reviews until someone comments `@claude review` on a PR

202

203In any mode, commenting `@claude review` [opts the PR into push-triggered reviews](#manually-trigger-reviews), so additional cost accrues per push after that comment. To run a single review without subscribing to future pushes, comment `@claude review once` instead.

204

205Costs appear on your Anthropic bill regardless of whether your organization uses AWS Bedrock or Google Vertex AI for other Claude Code features. To set a monthly spend cap for Code Review, go to [claude.ai/admin-settings/usage](https://claude.ai/admin-settings/usage) and configure the limit for the Claude Code Review service.

206

207Monitor spend via the weekly cost chart in [analytics](#view-usage) or the per-repo average cost column in admin settings.

208

209## Related resources

210

211Code Review is designed to work alongside the rest of Claude Code. If you want to run reviews locally before opening a PR, need a self-hosted setup, or want to go deeper on how `CLAUDE.md` shapes Claude's behavior across tools, these pages are good next stops:

212

213* [Plugins](/en/discover-plugins): browse the plugin marketplace, including a `code-review` plugin for running on-demand reviews locally before pushing

214* [GitHub Actions](/en/github-actions): run Claude in your own GitHub Actions workflows for custom automation beyond code review

215* [GitLab CI/CD](/en/gitlab-ci-cd): self-hosted Claude integration for GitLab pipelines

216* [Memory](/en/memory): how `CLAUDE.md` files work across Claude Code

217* [Analytics](/en/analytics): track Claude Code usage beyond code review

commands.md +90 −0 added

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# Built-in commands

7> Complete reference for built-in commands available in Claude Code.

9Type `/` in Claude Code to see all available commands, or type `/` followed by any letters to filter. Not all commands are visible to every user. Some depend on your platform, plan, or environment. For example, `/desktop` only appears on macOS and Windows, `/upgrade` and `/privacy-settings` are only available on Pro and Max plans, and `/terminal-setup` is hidden when your terminal natively supports its keybindings.

11Claude Code also includes [bundled skills](/en/skills#bundled-skills) like `/simplify`, `/batch`, `/debug`, and `/loop` that appear alongside built-in commands when you type `/`. To create your own commands, see [skills](/en/skills).

13In the table below, `<arg>` indicates a required argument and `[arg]` indicates an optional one.

15| Command | Purpose |

16| :--------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

17| `/add-dir <path>` | Add a new working directory to the current session |

18| `/agents` | Manage [agent](/en/sub-agents) configurations |

19| `/btw <question>` | Ask a quick [side question](/en/interactive-mode#side-questions-with-btw) without adding to the conversation |

20| `/chrome` | Configure [Claude in Chrome](/en/chrome) settings |

21| `/clear` | Clear conversation history and free up context. Aliases: `/reset`, `/new` |

22| `/color [color\|default]` | Set the prompt bar color for the current session. Available colors: `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, `cyan`. Use `default` to reset |

23| `/compact [instructions]` | Compact conversation with optional focus instructions |

24| `/config` | Open the [Settings](/en/settings) interface to adjust theme, model, [output style](/en/output-styles), and other preferences. Alias: `/settings` |

25| `/context` | Visualize current context usage as a colored grid. Shows optimization suggestions for context-heavy tools, memory bloat, and capacity warnings |

26| `/copy [N]` | Copy the last assistant response to clipboard. Pass a number `N` to copy the Nth-latest response: `/copy 2` copies the second-to-last. When code blocks are present, shows an interactive picker to select individual blocks or the full response. Press `w` in the picker to write the selection to a file instead of the clipboard, which is useful over SSH |

27| `/cost` | Show token usage statistics. See [cost tracking guide](/en/costs#using-the-cost-command) for subscription-specific details |

28| `/desktop` | Continue the current session in the Claude Code Desktop app. macOS and Windows only. Alias: `/app` |

29| `/diff` | Open an interactive diff viewer showing uncommitted changes and per-turn diffs. Use left/right arrows to switch between the current git diff and individual Claude turns, and up/down to browse files |

30| `/doctor` | Diagnose and verify your Claude Code installation and settings |

31| `/effort [low\|medium\|high\|max\|auto]` | Set the model [effort level](/en/model-config#adjust-effort-level). `low`, `medium`, and `high` persist across sessions. `max` applies to the current session only and requires Opus 4.6. `auto` resets to the model default. Without an argument, shows the current level. Takes effect immediately without waiting for the current response to finish |

32| `/exit` | Exit the CLI. Alias: `/quit` |

33| `/export [filename]` | Export the current conversation as plain text. With a filename, writes directly to that file. Without, opens a dialog to copy to clipboard or save to a file |

34| `/extra-usage` | Configure extra usage to keep working when rate limits are hit |

35| `/fast [on\|off]` | Toggle [fast mode](/en/fast-mode) on or off |

36| `/feedback [report]` | Submit feedback about Claude Code. Alias: `/bug` |

37| `/branch [name]` | Create a branch of the current conversation at this point. Alias: `/fork` |

38| `/help` | Show help and available commands |

39| `/hooks` | View [hook](/en/hooks) configurations for tool events |

40| `/ide` | Manage IDE integrations and show status |

41| `/init` | Initialize project with a `CLAUDE.md` guide. Set `CLAUDE_CODE_NEW_INIT=true` for an interactive flow that also walks through skills, hooks, and personal memory files |

42| `/insights` | Generate a report analyzing your Claude Code sessions, including project areas, interaction patterns, and friction points |

43| `/install-github-app` | Set up the [Claude GitHub Actions](/en/github-actions) app for a repository. Walks you through selecting a repo and configuring the integration |

44| `/install-slack-app` | Install the Claude Slack app. Opens a browser to complete the OAuth flow |

45| `/keybindings` | Open or create your keybindings configuration file |

46| `/login` | Sign in to your Anthropic account |

47| `/logout` | Sign out from your Anthropic account |

48| `/mcp` | Manage MCP server connections and OAuth authentication |

49| `/memory` | Edit `CLAUDE.md` memory files, enable or disable [auto-memory](/en/memory#auto-memory), and view auto-memory entries |

50| `/mobile` | Show QR code to download the Claude mobile app. Aliases: `/ios`, `/android` |

51| `/model [model]` | Select or change the AI model. For models that support it, use left/right arrows to [adjust effort level](/en/model-config#adjust-effort-level). The change takes effect immediately without waiting for the current response to finish |

52| `/passes` | Share a free week of Claude Code with friends. Only visible if your account is eligible |

53| `/permissions` | View or update [permissions](/en/permissions#manage-permissions). Alias: `/allowed-tools` |

54| `/plan [description]` | Enter plan mode directly from the prompt. Pass an optional description to enter plan mode and immediately start with that task, for example `/plan fix the auth bug` |

55| `/plugin` | Manage Claude Code [plugins](/en/plugins) |

56| `/pr-comments [PR]` | Fetch and display comments from a GitHub pull request. Automatically detects the PR for the current branch, or pass a PR URL or number. Requires the `gh` CLI |

57| `/privacy-settings` | View and update your privacy settings. Only available for Pro and Max plan subscribers |

58| `/release-notes` | View the full changelog, with the most recent version closest to your prompt |

59| `/reload-plugins` | Reload all active [plugins](/en/plugins) to apply pending changes without restarting. Reports counts for each reloaded component and flags any load errors |

60| `/remote-control` | Make this session available for [remote control](/en/remote-control) from claude.ai. Alias: `/rc` |

61| `/remote-env` | Configure the default remote environment for [web sessions started with `--remote`](/en/claude-code-on-the-web#environment-configuration) |

62| `/rename [name]` | Rename the current session and show the name on the prompt bar. Without a name, auto-generates one from conversation history |

63| `/resume [session]` | Resume a conversation by ID or name, or open the session picker. Alias: `/continue` |

64| `/review` | Deprecated. Install the [`code-review` plugin](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/code-review) instead: `claude plugin install code-review@claude-plugins-official` |

65| `/rewind` | Rewind the conversation and/or code to a previous point, or summarize from a selected message. See [checkpointing](/en/checkpointing). Alias: `/checkpoint` |

66| `/sandbox` | Toggle [sandbox mode](/en/sandboxing). Available on supported platforms only |

67| `/schedule [description]` | Create, update, list, or run [Cloud scheduled tasks](/en/web-scheduled-tasks). Claude walks you through the setup conversationally |

68| `/security-review` | Analyze pending changes on the current branch for security vulnerabilities. Reviews the git diff and identifies risks like injection, auth issues, and data exposure |

69| `/skills` | List available [skills](/en/skills) |

70| `/stats` | Visualize daily usage, session history, streaks, and model preferences |

71| `/status` | Open the Settings interface (Status tab) showing version, model, account, and connectivity. Works while Claude is responding, without waiting for the current response to finish |

72| `/statusline` | Configure Claude Code's [status line](/en/statusline). Describe what you want, or run without arguments to auto-configure from your shell prompt |

73| `/stickers` | Order Claude Code stickers |

74| `/tasks` | List and manage background tasks |

75| `/terminal-setup` | Configure terminal keybindings for Shift+Enter and other shortcuts. Only visible in terminals that need it, like VS Code, Alacritty, or Warp |

76| `/theme` | Change the color theme. Includes light and dark variants, colorblind-accessible (daltonized) themes, and ANSI themes that use your terminal's color palette |

77| `/upgrade` | Open the upgrade page to switch to a higher plan tier |

78| `/usage` | Show plan usage limits and rate limit status |

79| `/vim` | Toggle between Vim and Normal editing modes |

80| `/voice` | Toggle push-to-talk [voice dictation](/en/voice-dictation). Requires a Claude.ai account |

82## MCP prompts

84MCP servers can expose prompts that appear as commands. These use the format `/mcp__<server>__<prompt>` and are dynamically discovered from connected servers. See [MCP prompts](/en/mcp#use-mcp-prompts-as-commands) for details.

86## See also

88* [Skills](/en/skills): create your own commands

89* [Interactive mode](/en/interactive-mode): keyboard shortcuts, Vim mode, and command history

90* [CLI reference](/en/cli-reference): launch-time flags

common-workflows.md +328 −189

Details

28 </Step>28 </Step>

29 29

30 <Step title="Ask for a high-level overview">30 <Step title="Ask for a high-level overview">

~~31 ```~~31 ```text theme={null}

~~32 > give me an overview of this codebase~~ 32 give me an overview of this codebase

33 ```33 ```

34 </Step>34 </Step>

35 35

36 <Step title="Dive deeper into specific components">36 <Step title="Dive deeper into specific components">

~~37 ```~~37 ```text theme={null}

~~38 > explain the main architecture patterns used here~~ 38 explain the main architecture patterns used here

39 ```39 ```

40 40

~~41 ```~~41 ```text theme={null}

~~42 > what are the key data models?~~42 what are the key data models?

43 ```43 ```

44 44

~~45 ```~~45 ```text theme={null}

~~46 > how is authentication handled?~~46 how is authentication handled?

47 ```47 ```

48 </Step>48 </Step>

49</Steps>49</Steps>

62 62

63<Steps>63<Steps>

64 <Step title="Ask Claude to find relevant files">64 <Step title="Ask Claude to find relevant files">

~~65 ```~~65 ```text theme={null}

~~66 > find the files that handle user authentication~~ 66 find the files that handle user authentication

67 ```67 ```

68 </Step>68 </Step>

69 69

70 <Step title="Get context on how components interact">70 <Step title="Get context on how components interact">

~~71 ```~~71 ```text theme={null}

~~72 > how do these authentication files work together?~~ 72 how do these authentication files work together?

73 ```73 ```

74 </Step>74 </Step>

75 75

76 <Step title="Understand the execution flow">76 <Step title="Understand the execution flow">

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

~~78 > trace the login process from front-end to database~~ 78 trace the login process from front-end to database

79 ```79 ```

80 </Step>80 </Step>

81</Steps>81</Steps>

96 96

97<Steps>97<Steps>

98 <Step title="Share the error with Claude">98 <Step title="Share the error with Claude">

~~99 ```~~99 ```text theme={null}

100 > I'm seeing an error when I run npm test 100 I'm seeing an error when I run npm test

101 ```101 ```

102 </Step>102 </Step>

103 103

104 <Step title="Ask for fix recommendations">104 <Step title="Ask for fix recommendations">

105 ```105 ```text theme={null}

106 > suggest a few ways to fix the @ts-ignore in user.ts 106 suggest a few ways to fix the @ts-ignore in user.ts

107 ```107 ```

108 </Step>108 </Step>

109 109

110 <Step title="Apply the fix">110 <Step title="Apply the fix">

111 ```111 ```text theme={null}

112 > update user.ts to add the null check you suggested 112 update user.ts to add the null check you suggested

113 ```113 ```

114 </Step>114 </Step>

115</Steps>115</Steps>

130 130

131<Steps>131<Steps>

132 <Step title="Identify legacy code for refactoring">132 <Step title="Identify legacy code for refactoring">

133 ```133 ```text theme={null}

134 > find deprecated API usage in our codebase 134 find deprecated API usage in our codebase

135 ```135 ```

136 </Step>136 </Step>

137 137

138 <Step title="Get refactoring recommendations">138 <Step title="Get refactoring recommendations">

139 ```139 ```text theme={null}

140 > suggest how to refactor utils.js to use modern JavaScript features 140 suggest how to refactor utils.js to use modern JavaScript features

141 ```141 ```

142 </Step>142 </Step>

143 143

144 <Step title="Apply the changes safely">144 <Step title="Apply the changes safely">

145 ```145 ```text theme={null}

146 > refactor utils.js to use ES2024 features while maintaining the same behavior 146 refactor utils.js to use ES2024 features while maintaining the same behavior

147 ```147 ```

148 </Step>148 </Step>

149 149

150 <Step title="Verify the refactoring">150 <Step title="Verify the refactoring">

151 ```151 ```text theme={null}

152 > run tests for the refactored code 152 run tests for the refactored code

153 ```153 ```

154 </Step>154 </Step>

155</Steps>155</Steps>

170 170

171<Steps>171<Steps>

172 <Step title="View available subagents">172 <Step title="View available subagents">

173 ```173 ```text theme={null}

174 > /agents174 /agents

175 ```175 ```

176 176

177 This shows all available subagents and lets you create new ones.177 This shows all available subagents and lets you create new ones.

180 <Step title="Use subagents automatically">180 <Step title="Use subagents automatically">

181 Claude Code automatically delegates appropriate tasks to specialized subagents:181 Claude Code automatically delegates appropriate tasks to specialized subagents:

182 182

183 ```183 ```text theme={null}

184 > review my recent code changes for security issues184 review my recent code changes for security issues

185 ```185 ```

186 186

187 ```187 ```text theme={null}

188 > run all tests and fix any failures188 run all tests and fix any failures

189 ```189 ```

190 </Step>190 </Step>

191 191

192 <Step title="Explicitly request specific subagents">192 <Step title="Explicitly request specific subagents">

193 ```193 ```text theme={null}

194 > use the code-reviewer subagent to check the auth module194 use the code-reviewer subagent to check the auth module

195 ```195 ```

196 196

197 ```197 ```text theme={null}

198 > have the debugger subagent investigate why users can't log in198 have the debugger subagent investigate why users can't log in

199 ```199 ```

200 </Step>200 </Step>

201 201

202 <Step title="Create custom subagents for your workflow">202 <Step title="Create custom subagents for your workflow">

203 ```203 ```text theme={null}

204 > /agents204 /agents

205 ```205 ```

206 206

207 Then select "Create New subagent" and follow the prompts to define:207 Then select "Create New subagent" and follow the prompts to define:

226 226

227## Use Plan Mode for safe code analysis227## Use Plan Mode for safe code analysis

228 228

229Plan Mode instructs Claude to create a plan by analyzing the codebase with read-only operations, perfect for exploring codebases, planning complex changes, or reviewing code safely. In Plan Mode, Claude uses [`AskUserQuestion`](/en/settings#tools-available-to-claude) to gather requirements and clarify your goals before proposing a plan.229Plan Mode instructs Claude to create a plan by analyzing the codebase with read-only operations, perfect for exploring codebases, planning complex changes, or reviewing code safely. In Plan Mode, Claude uses [`AskUserQuestion`](/en/tools-reference) to gather requirements and clarify your goals before proposing a plan.

230 230

231### When to use Plan Mode231### When to use Plan Mode

232 232

264claude --permission-mode plan264claude --permission-mode plan

265```265```

266 266

267```267```text theme={null}

268> I need to refactor our authentication system to use OAuth2. Create a detailed migration plan.268I need to refactor our authentication system to use OAuth2. Create a detailed migration plan.

269```269```

270 270

271Claude analyzes the current implementation and create a comprehensive plan. Refine with follow-ups:271Claude analyzes the current implementation and create a comprehensive plan. Refine with follow-ups:

272 272

273```text theme={null}

274What about backward compatibility?

273```275```

274> What about backward compatibility?276

275> How should we handle database migration?277```text theme={null}

278How should we handle database migration?

276```279```

277 280

278<Tip>Press `Ctrl+G` to open the plan in your default text editor, where you can edit it directly before Claude proceeds.</Tip>281<Tip>Press `Ctrl+G` to open the plan in your default text editor, where you can edit it directly before Claude proceeds.</Tip>

279 282

283When you accept a plan, Claude automatically names the session from the plan content. The name appears on the prompt bar and in the session picker. If you've already set a name with `--name` or `/rename`, accepting a plan won't overwrite it.

284

280### Configure Plan Mode as default285### Configure Plan Mode as default

281 286

282```json theme={null}287```json theme={null}

298 303

299<Steps>304<Steps>

300 <Step title="Identify untested code">305 <Step title="Identify untested code">

301 ```306 ```text theme={null}

302 > find functions in NotificationsService.swift that are not covered by tests 307 find functions in NotificationsService.swift that are not covered by tests

303 ```308 ```

304 </Step>309 </Step>

305 310

306 <Step title="Generate test scaffolding">311 <Step title="Generate test scaffolding">

307 ```312 ```text theme={null}

308 > add tests for the notification service 313 add tests for the notification service

309 ```314 ```

310 </Step>315 </Step>

311 316

312 <Step title="Add meaningful test cases">317 <Step title="Add meaningful test cases">

313 ```318 ```text theme={null}

314 > add test cases for edge conditions in the notification service 319 add test cases for edge conditions in the notification service

315 ```320 ```

316 </Step>321 </Step>

317 322

318 <Step title="Run and verify tests">323 <Step title="Run and verify tests">

319 ```324 ```text theme={null}

320 > run the new tests and fix any failures 325 run the new tests and fix any failures

321 ```326 ```

322 </Step>327 </Step>

323</Steps>328</Steps>

330 335

331## Create pull requests336## Create pull requests

332 337

333You can create pull requests by asking Claude directly ("create a pr for my changes") or by using the `/commit-push-pr` skill, which commits, pushes, and opens a PR in one step.338You can create pull requests by asking Claude directly ("create a pr for my changes"), or guide Claude through it step-by-step:

~~334~~

335```

336> /commit-push-pr

337```

~~338~~

339If you have a Slack MCP server configured and specify channels in your CLAUDE.md (for example, "post PR URLs to #team-prs"), the skill automatically posts the PR URL to those channels.

~~340~~

341For more control over the process, guide Claude through it step-by-step or [create your own skill](/en/skills):

342 339

343<Steps>340<Steps>

344 <Step title="Summarize your changes">341 <Step title="Summarize your changes">

345 ```342 ```text theme={null}

346 > summarize the changes I've made to the authentication module343 summarize the changes I've made to the authentication module

347 ```344 ```

348 </Step>345 </Step>

349 346

350 <Step title="Generate a pull request">347 <Step title="Generate a pull request">

351 ```348 ```text theme={null}

352 > create a pr349 create a pr

353 ```350 ```

354 </Step>351 </Step>

355 352

356 <Step title="Review and refine">353 <Step title="Review and refine">

357 ```354 ```text theme={null}

358 > enhance the PR description with more context about the security improvements355 enhance the PR description with more context about the security improvements

359 ```356 ```

360 </Step>357 </Step>

361</Steps>358</Steps>

372 369

373<Steps>370<Steps>

374 <Step title="Identify undocumented code">371 <Step title="Identify undocumented code">

375 ```372 ```text theme={null}

376 > find functions without proper JSDoc comments in the auth module 373 find functions without proper JSDoc comments in the auth module

377 ```374 ```

378 </Step>375 </Step>

379 376

380 <Step title="Generate documentation">377 <Step title="Generate documentation">

381 ```378 ```text theme={null}

382 > add JSDoc comments to the undocumented functions in auth.js 379 add JSDoc comments to the undocumented functions in auth.js

383 ```380 ```

384 </Step>381 </Step>

385 382

386 <Step title="Review and enhance">383 <Step title="Review and enhance">

387 ```384 ```text theme={null}

388 > improve the generated documentation with more context and examples 385 improve the generated documentation with more context and examples

389 ```386 ```

390 </Step>387 </Step>

391 388

392 <Step title="Verify documentation">389 <Step title="Verify documentation">

393 ```390 ```text theme={null}

394 > check if the documentation follows our project standards 391 check if the documentation follows our project standards

395 ```392 ```

396 </Step>393 </Step>

397</Steps>394</Steps>

420 </Step>417 </Step>

421 418

422 <Step title="Ask Claude to analyze the image">419 <Step title="Ask Claude to analyze the image">

423 ```420 ```text theme={null}

424 > What does this image show?421 What does this image show?

425 ```422 ```

426 423

427 ```424 ```text theme={null}

428 > Describe the UI elements in this screenshot425 Describe the UI elements in this screenshot

429 ```426 ```

430 427

431 ```428 ```text theme={null}

432 > Are there any problematic elements in this diagram?429 Are there any problematic elements in this diagram?

433 ```430 ```

434 </Step>431 </Step>

435 432

436 <Step title="Use images for context">433 <Step title="Use images for context">

437 ```434 ```text theme={null}

438 > Here's a screenshot of the error. What's causing it?435 Here's a screenshot of the error. What's causing it?

439 ```436 ```

440 437

441 ```438 ```text theme={null}

442 > This is our current database schema. How should we modify it for the new feature?439 This is our current database schema. How should we modify it for the new feature?

443 ```440 ```

444 </Step>441 </Step>

445 442

446 <Step title="Get code suggestions from visual content">443 <Step title="Get code suggestions from visual content">

447 ```444 ```text theme={null}

448 > Generate CSS to match this design mockup445 Generate CSS to match this design mockup

449 ```446 ```

450 447

451 ```448 ```text theme={null}

452 > What HTML structure would recreate this component?449 What HTML structure would recreate this component?

453 ```450 ```

454 </Step>451 </Step>

455</Steps>452</Steps>

472 469

473<Steps>470<Steps>

474 <Step title="Reference a single file">471 <Step title="Reference a single file">

475 ```472 ```text theme={null}

476 > Explain the logic in @src/utils/auth.js473 Explain the logic in @src/utils/auth.js

477 ```474 ```

478 475

479 This includes the full content of the file in the conversation.476 This includes the full content of the file in the conversation.

480 </Step>477 </Step>

481 478

482 <Step title="Reference a directory">479 <Step title="Reference a directory">

483 ```480 ```text theme={null}

484 > What's the structure of @src/components?481 What's the structure of @src/components?

485 ```482 ```

486 483

487 This provides a directory listing with file information.484 This provides a directory listing with file information.

488 </Step>485 </Step>

489 486

490 <Step title="Reference MCP resources">487 <Step title="Reference MCP resources">

491 ```488 ```text theme={null}

492 > Show me the data from @github:repos/owner/repo/issues489 Show me the data from @github:repos/owner/repo/issues

493 ```490 ```

494 491

495 This fetches data from connected MCP servers using the format @server:resource. See [MCP resources](/en/mcp#use-mcp-resources) for details.492 This fetches data from connected MCP servers using the format @server:resource. See [MCP resources](/en/mcp#use-mcp-resources) for details.

509 506

510## Use extended thinking (thinking mode)507## Use extended thinking (thinking mode)

511 508

512[Extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) is enabled by default, reserving a portion of the output token budget (up to 31,999 tokens) for Claude to reason through complex problems step-by-step. This reasoning is visible in verbose mode, which you can toggle on with `Ctrl+O`.509[Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) is enabled by default, giving Claude space to reason through complex problems step-by-step before responding. This reasoning is visible in verbose mode, which you can toggle on with `Ctrl+O`.

510

511Additionally, Opus 4.6 and Sonnet 4.6 support adaptive reasoning: instead of a fixed thinking token budget, the model dynamically allocates thinking based on your [effort level](/en/model-config#adjust-effort-level) setting. Extended thinking and adaptive reasoning work together to give you control over how deeply Claude reasons before responding.

513 512

514Extended thinking is particularly valuable for complex architectural decisions, challenging bugs, multi-step implementation planning, and evaluating tradeoffs between different approaches. It provides more space for exploring multiple solutions, analyzing edge cases, and self-correcting mistakes.513Extended thinking is particularly valuable for complex architectural decisions, challenging bugs, multi-step implementation planning, and evaluating tradeoffs between different approaches.

515 514

516<Note>515<Note>

517 Phrases like "think", "think hard", "ultrathink", and "think more" are interpreted as regular prompt instructions and don't allocate thinking tokens.516 Phrases like "think", "think hard", and "think more" are interpreted as regular prompt instructions and don't allocate thinking tokens.

518</Note>517</Note>

519 518

520### Configure thinking mode519### Configure thinking mode

522Thinking is enabled by default, but you can adjust or disable it.521Thinking is enabled by default, but you can adjust or disable it.

523 522

525| ---------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |524| ------------------------ | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

526| **Toggle shortcut** | Press `Option+T` (macOS) or `Alt+T` (Windows/Linux) | Toggle thinking on/off for the current session. May require [terminal configuration](/en/terminal-config) to enable Option key shortcuts |525| **Effort level** | Run `/effort`, adjust in `/model`, or set [`CLAUDE_CODE_EFFORT_LEVEL`](/en/env-vars) | Control thinking depth for Opus 4.6 and Sonnet 4.6. See [Adjust effort level](/en/model-config#adjust-effort-level) |

527| **Global default** | Use `/config` to toggle thinking mode | Sets your default across all projects. Saved as `alwaysThinkingEnabled` in `~/.claude/settings.json` |526| **`ultrathink` keyword** | Include "ultrathink" anywhere in your prompt | Sets effort to high for that turn on Opus 4.6 and Sonnet 4.6. Useful for one-off tasks requiring deep reasoning without permanently changing your effort setting |

528| **Limit token budget** | Set [`MAX_THINKING_TOKENS`](/en/settings#environment-variables) environment variable | Limit the thinking budget to a specific number of tokens. Example: `export MAX_THINKING_TOKENS=10000` |527| **Toggle shortcut** | Press `Option+T` (macOS) or `Alt+T` (Windows/Linux) | Toggle thinking on/off for the current session (all models). May require [terminal configuration](/en/terminal-config) to enable Option key shortcuts |

528| **Global default** | Use `/config` to toggle thinking mode | Sets your default across all projects (all models). Saved as `alwaysThinkingEnabled` in `~/.claude/settings.json` |

529| **Limit token budget** | Set [`MAX_THINKING_TOKENS`](/en/env-vars) environment variable | Limit the thinking budget to a specific number of tokens. On Opus 4.6 and Sonnet 4.6, only `0` applies unless adaptive reasoning is disabled. Example: `export MAX_THINKING_TOKENS=10000` |

529 530

530To view Claude's thinking process, press `Ctrl+O` to toggle verbose mode and see the internal reasoning displayed as gray italic text.531To view Claude's thinking process, press `Ctrl+O` to toggle verbose mode and see the internal reasoning displayed as gray italic text.

531 532

532### How extended thinking token budgets work533### How extended thinking works

~~533~~

534Extended thinking uses a **token budget** that controls how much internal reasoning Claude can perform before responding.

~~535~~

536A larger thinking token budget provides:

~~537~~

538* More space to explore multiple solution approaches step-by-step

539* Room to analyze edge cases and evaluate tradeoffs thoroughly

540* Ability to revise reasoning and self-correct mistakes

541 534

542Token budgets for thinking mode:535Extended thinking controls how much internal reasoning Claude performs before responding. More thinking provides more space to explore solutions, analyze edge cases, and self-correct mistakes.

543 536

544* When thinking is **enabled**, Claude can use up to **31,999 tokens** from your output budget for internal reasoning537**With Opus 4.6 and Sonnet 4.6**, thinking uses adaptive reasoning: the model dynamically allocates thinking tokens based on the [effort level](/en/model-config#adjust-effort-level) you select. This is the recommended way to tune the tradeoff between speed and reasoning depth.

545* When thinking is **disabled** (via toggle or `/config`), Claude uses **0 tokens** for thinking

546 538

547**Limit the thinking budget:**539**With older models**, thinking uses a fixed token budget drawn from your output allocation. The budget varies by model; see [`MAX_THINKING_TOKENS`](/en/env-vars) for per-model ceilings. You can limit the budget with that environment variable, or disable thinking entirely via `/config` or the `Option+T`/`Alt+T` toggle.

548 540

549* Use the [`MAX_THINKING_TOKENS` environment variable](/en/settings#environment-variables) to cap the thinking budget541On Opus 4.6 and Sonnet 4.6, [adaptive reasoning](/en/model-config#adjust-effort-level) controls thinking depth, so `MAX_THINKING_TOKENS` only applies when set to `0` to disable thinking, or when `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` reverts these models to the fixed budget. See [environment variables](/en/env-vars).

550* When set, this value limits the maximum tokens Claude can use for thinking

551* See the [extended thinking documentation](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for valid token ranges

552 542

553<Warning>543<Warning>

554 You're charged for all thinking tokens used, even though Claude 4 models show summarized thinking544 You're charged for all thinking tokens used, even though Claude 4 models show summarized thinking

573Give sessions descriptive names to find them later. This is a best practice when working on multiple tasks or features.563Give sessions descriptive names to find them later. This is a best practice when working on multiple tasks or features.

574 564

575<Steps>565<Steps>

576 <Step title="Name the current session">566 <Step title="Name the session">

577 Use `/rename` during a session to give it a memorable name:567 Name a session at startup with `-n`:

578 568

569 ```bash theme={null}

570 claude -n auth-refactor

579 ```571 ```

580 > /rename auth-refactor572

573 Or use `/rename` during a session, which also shows the name on the prompt bar:

574

575 ```text theme={null}

576 /rename auth-refactor

581 ```577 ```

582 578

583 You can also rename any session from the picker: run `/resume`, navigate to a session, and press `R`.579 You can also rename any session from the picker: run `/resume`, navigate to a session, and press `R`.

592 588

593 Or from inside an active session:589 Or from inside an active session:

594 590

595 ```591 ```text theme={null}

596 > /resume auth-refactor592 /resume auth-refactor

597 ```593 ```

598 </Step>594 </Step>

599</Steps>595</Steps>

625* Message count621* Message count

626* Git branch (if applicable)622* Git branch (if applicable)

627 623

628Forked sessions (created with `/rewind` or `--fork-session`) are grouped together under their root session, making it easier to find related conversations.624Forked sessions (created with `/branch`, `/rewind`, or `--fork-session`) are grouped together under their root session, making it easier to find related conversations.

629 625

630<Tip>626<Tip>

631 Tips:627 Tips:

632 628

633 * **Name sessions early**: Use `/rename` when starting work on a distinct task—it's much easier to find "payment-integration" than "explain this function" later629 * **Name sessions early**: Use `/rename` when starting work on a distinct task: it's much easier to find "payment-integration" than "explain this function" later

634 * Use `--continue` for quick access to your most recent conversation in the current directory630 * Use `--continue` for quick access to your most recent conversation in the current directory

635 * Use `--resume session-name` when you know which session you need631 * Use `--resume session-name` when you know which session you need

636 * Use `--resume` (without a name) when you need to browse and select632 * Use `--resume` (without a name) when you need to browse and select

650 646

651## Run parallel Claude Code sessions with Git worktrees647## Run parallel Claude Code sessions with Git worktrees

652 648

653Suppose you need to work on multiple tasks simultaneously with complete code isolation between Claude Code instances.649When working on multiple tasks at once, you need each Claude session to have its own copy of the codebase so changes don't collide. Git worktrees solve this by creating separate working directories that each have their own files and branch, while sharing the same repository history and remote connections. This means you can have Claude working on a feature in one worktree while fixing a bug in another, without either session interfering with the other.

654 650

655<Steps>651Use the `--worktree` (`-w`) flag to create an isolated worktree and start Claude in it. The value you pass becomes the worktree directory name and branch name:

656 <Step title="Understand Git worktrees">

657 Git worktrees allow you to check out multiple branches from the same

658 repository into separate directories. Each worktree has its own working

659 directory with isolated files, while sharing the same Git history. Learn

660 more in the [official Git worktree

661 documentation](https://git-scm.com/docs/git-worktree).

662 </Step>

663 652

664 <Step title="Create a new worktree">653```bash theme={null}

665 ```bash theme={null}654# Start Claude in a worktree named "feature-auth"

666 # Create a new worktree with a new branch 655# Creates .claude/worktrees/feature-auth/ with a new branch

667 git worktree add ../project-feature-a -b feature-a656claude --worktree feature-auth

668 657

669 # Or create a worktree with an existing branch658# Start another session in a separate worktree

670 git worktree add ../project-bugfix bugfix-123659claude --worktree bugfix-123

671 ```660```

672 661

673 This creates a new directory with a separate working copy of your repository.662If you omit the name, Claude generates a random one automatically:

674 </Step>

675 663

676 <Step title="Run Claude Code in each worktree">664```bash theme={null}

677 ```bash theme={null}665# Auto-generates a name like "bright-running-fox"

678 # Navigate to your worktree 666claude --worktree

679 cd ../project-feature-a667```

680 668

681 # Run Claude Code in this isolated environment669Worktrees are created at `<repo>/.claude/worktrees/<name>` and branch from the default remote branch, which is where `origin/HEAD` points. The worktree branch is named `worktree-<name>`.

682 claude

683 ```

684 </Step>

685 670

686 <Step title="Run Claude in another worktree">671The base branch is not configurable through a Claude Code flag or setting. `origin/HEAD` is a reference stored in your local `.git` directory that Git set once when you cloned. If the repository's default branch later changes on GitHub or GitLab, your local `origin/HEAD` keeps pointing at the old one, and worktrees will branch from there. To re-sync your local reference with whatever the remote currently considers its default:

687 ```bash theme={null}672

688 cd ../project-bugfix673```bash theme={null}

689 claude674git remote set-head origin -a

675```

676

677This is a standard Git command that only updates your local `.git` directory. Nothing on the remote server changes. If you want worktrees to base off a specific branch rather than the remote's default, set it explicitly with `git remote set-head origin your-branch-name`.

678

679For full control over how worktrees are created, including choosing a different base per invocation, configure a [WorktreeCreate hook](/en/hooks#worktreecreate). The hook replaces Claude Code's default `git worktree` logic entirely, so you can fetch and branch from whatever ref you need.

680

681You can also ask Claude to "work in a worktree" or "start a worktree" during a session, and it will create one automatically.

682

683### Subagent worktrees

684

685Subagents can also use worktree isolation to work in parallel without conflicts. Ask Claude to "use worktrees for your agents" or configure it in a [custom subagent](/en/sub-agents#supported-frontmatter-fields) by adding `isolation: worktree` to the agent's frontmatter. Each subagent gets its own worktree that is automatically cleaned up when the subagent finishes without changes.

686

687### Worktree cleanup

688

689When you exit a worktree session, Claude handles cleanup based on whether you made changes:

690

691* **No changes**: the worktree and its branch are removed automatically

692* **Changes or commits exist**: Claude prompts you to keep or remove the worktree. Keeping preserves the directory and branch so you can return later. Removing deletes the worktree directory and its branch, discarding all uncommitted changes and commits

693

694To clean up worktrees outside of a Claude session, use [manual worktree management](#manage-worktrees-manually).

695

696<Tip>

697 Add `.claude/worktrees/` to your `.gitignore` to prevent worktree contents from appearing as untracked files in your main repository.

698</Tip>

699

700### Copy gitignored files to worktrees

701

702Git worktrees are fresh checkouts, so they don't include untracked files like `.env` or `.env.local` from your main repository. To automatically copy these files when Claude creates a worktree, add a `.worktreeinclude` file to your project root.

703

704The file uses `.gitignore` syntax to list which files to copy. Only files that match a pattern and are also gitignored get copied, so tracked files are never duplicated.

705

706```text .worktreeinclude theme={null}

707.env

708.env.local

709config/secrets.json

710```

711

712This applies to worktrees created with `--worktree`, subagent worktrees, and parallel sessions in the [desktop app](/en/desktop#work-in-parallel-with-sessions).

713

714### Manage worktrees manually

715

716For more control over worktree location and branch configuration, create worktrees with Git directly. This is useful when you need to check out a specific existing branch or place the worktree outside the repository.

717

718```bash theme={null}

719# Create a worktree with a new branch

720git worktree add ../project-feature-a -b feature-a

721

722# Create a worktree with an existing branch

723git worktree add ../project-bugfix bugfix-123

724

725# Start Claude in the worktree

726cd ../project-feature-a && claude

727

728# Clean up when done

729git worktree list

730git worktree remove ../project-feature-a

731```

732

733Learn more in the [official Git worktree documentation](https://git-scm.com/docs/git-worktree).

734

735<Tip>

736 Remember to initialize your development environment in each new worktree according to your project's setup. Depending on your stack, this might include running dependency installation (`npm install`, `yarn`), setting up virtual environments, or following your project's standard setup process.

737</Tip>

738

739### Non-git version control

740

741Worktree isolation works with git by default. For other version control systems like SVN, Perforce, or Mercurial, configure [WorktreeCreate and WorktreeRemove hooks](/en/hooks#worktreecreate) to provide custom worktree creation and cleanup logic. When configured, these hooks replace the default git behavior when you use `--worktree`, so [`.worktreeinclude`](#copy-gitignored-files-to-worktrees) is not processed. Copy any local configuration files inside your hook script instead.

742

743For automated coordination of parallel sessions with shared tasks and messaging, see [agent teams](/en/agent-teams).

744

745***

746

747## Get notified when Claude needs your attention

748

749When you kick off a long-running task and switch to another window, you can set up desktop notifications so you know when Claude finishes or needs your input. This uses the `Notification` [hook event](/en/hooks-guide#get-notified-when-claude-needs-input), which fires whenever Claude is waiting for permission, idle and ready for a new prompt, or completing authentication.

750

751<Steps>

752 <Step title="Add the hook to your settings">

753 Open `~/.claude/settings.json` and add a `Notification` hook that calls your platform's native notification command:

754

755 <Tabs>

756 <Tab title="macOS">

757 ```json theme={null}

758 {

759 "hooks": {

760 "Notification": [

761 {

762 "matcher": "",

763 "hooks": [

764 {

765 "type": "command",

766 "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"

767 }

768 ]

769 }

770 ]

771 }

772 }

773 ```

774 </Tab>

775

776 <Tab title="Linux">

777 ```json theme={null}

778 {

779 "hooks": {

780 "Notification": [

781 {

782 "matcher": "",

783 "hooks": [

784 {

785 "type": "command",

786 "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"

787 }

788 ]

789 }

790 ]

791 }

792 }

690 ```793 ```

794 </Tab>

795

796 <Tab title="Windows">

797 ```json theme={null}

798 {

799 "hooks": {

800 "Notification": [

801 {

802 "matcher": "",

803 "hooks": [

804 {

805 "type": "command",

806 "command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')\""

807 }

808 ]

809 }

810 ]

811 }

812 }

813 ```

814 </Tab>

815 </Tabs>

816

817 If your settings file already has a `hooks` key, merge the `Notification` entry into it rather than overwriting. You can also ask Claude to write the hook for you by describing what you want in the CLI.

691 </Step>818 </Step>

692 819

693 <Step title="Manage your worktrees">820 <Step title="Optionally narrow the matcher">

694 ```bash theme={null}821 By default the hook fires on all notification types. To fire only for specific events, set the `matcher` field to one of these values:

695 # List all worktrees

696 git worktree list

697 822

698 # Remove a worktree when done823 | Matcher | Fires when |

699 git worktree remove ../project-feature-a824 | :------------------- | :---------------------------------------------- |

700 ```825 | `permission_prompt` | Claude needs you to approve a tool use |

826 | `idle_prompt` | Claude is done and waiting for your next prompt |

827 | `auth_success` | Authentication completes |

828 | `elicitation_dialog` | Claude is asking you a question |

701 </Step>829 </Step>

702</Steps>

703 830

704<Tip>831 <Step title="Verify the hook">

705 Tips:832 Type `/hooks` and select `Notification` to confirm the hook appears. Selecting it shows the command that will run. To test it end-to-end, ask Claude to run a command that requires permission and switch away from the terminal, or ask Claude to trigger a notification directly.

833 </Step>

834</Steps>

706 835

707 * Each worktree has its own independent file state, making it perfect for parallel Claude Code sessions836For the complete event schema and notification types, see the [Notification reference](/en/hooks#notification).

708 * Changes made in one worktree won't affect others, preventing Claude instances from interfering with each other

709 * All worktrees share the same Git history and remote connections

710 * For long-running tasks, you can have Claude working in one worktree while you continue development in another

711 * Use descriptive directory names to easily identify which task each worktree is for

712 * Remember to initialize your development environment in each new worktree according to your project's setup. Depending on your stack, this might include:

713 * JavaScript projects: Running dependency installation (`npm install`, `yarn`)

714 * Python projects: Setting up virtual environments or installing with package managers

715 * Other languages: Following your project's standard setup process

716</Tip>

717 837

718***838***

719 839

802 922

803***923***

804 924

925## Run Claude on a schedule

926

927Suppose you want Claude to handle a task automatically on a recurring basis, like reviewing open PRs every morning, auditing dependencies weekly, or checking for CI failures overnight.

928

929Pick a scheduling option based on where you want the task to run:

930

931| Option | Where it runs | Best for |

932| :-------------------------------------------------------------- | :-------------------------------- | :------------------------------------------------------------------------------------------------------------ |

933| [Cloud scheduled tasks](/en/web-scheduled-tasks) | Anthropic-managed infrastructure | Tasks that should run even when your computer is off. Configure at [claude.ai/code](https://claude.ai/code). |

934| [Desktop scheduled tasks](/en/desktop#schedule-recurring-tasks) | Your machine, via the desktop app | Tasks that need direct access to local files, tools, or uncommitted changes. |

935| [GitHub Actions](/en/github-actions) | Your CI pipeline | Tasks tied to repo events like opened PRs, or cron schedules that should live alongside your workflow config. |

936| [`/loop`](/en/scheduled-tasks) | The current CLI session | Quick polling while a session is open. Tasks are cancelled when you exit. |

937

938<Tip>

939 When writing prompts for scheduled tasks, be explicit about what success looks like and what to do with results. The task runs autonomously, so it can't ask clarifying questions. For example: "Review open PRs labeled `needs-review`, leave inline comments on any issues, and post a summary in the `#eng-reviews` Slack channel."

940</Tip>

941

942***

943

805## Ask Claude about its capabilities944## Ask Claude about its capabilities

806 945

807Claude has built-in access to its documentation and can answer questions about its own features and limitations.946Claude has built-in access to its documentation and can answer questions about its own features and limitations.

808 947

809### Example questions948### Example questions

810 949

811```950```text theme={null}

812> can Claude Code create pull requests?951can Claude Code create pull requests?

813```952```

814 953

815```954```text theme={null}

816> how does Claude Code handle permissions?955how does Claude Code handle permissions?

817```956```

818 957

819```958```text theme={null}

820> what skills are available?959what skills are available?

821```960```

822 961

823```962```text theme={null}

824> how do I use MCP with Claude Code?963how do I use MCP with Claude Code?

825```964```

826 965

827```966```text theme={null}

828> how do I configure Claude Code for Amazon Bedrock?967how do I configure Claude Code for Amazon Bedrock?

829```968```

830 969

831```970```text theme={null}

832> what are the limitations of Claude Code?971what are the limitations of Claude Code?

833```972```

834 973

835<Note>974<Note>

862 </Card>1001 </Card>

863 1002

864 <Card title="Reference implementation" icon="code" href="https://github.com/anthropics/claude-code/tree/main/.devcontainer">1003 <Card title="Reference implementation" icon="code" href="https://github.com/anthropics/claude-code/tree/main/.devcontainer">

865 Clone our development container reference implementation1004 Clone the development container reference implementation

866 </Card>1005 </Card>

867</CardGroup>1006</CardGroup>

context-window.md +35 −0 added

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# Explore the context window

7> An interactive simulation of how Claude Code's context window fills during a session. See what loads automatically, what each file read costs, and when rules and hooks fire.

10Claude Code's context window holds everything Claude knows about your session: your instructions, the files it reads, its own responses, and content that never appears in your terminal. The timeline below walks through what loads and when. See [the written breakdown](#what-the-timeline-shows) for the same content as a list.

12<ContextWindow />

14## What the timeline shows

16The session walks through a realistic flow with representative token counts:

18* **Before you type anything**: CLAUDE.md, auto memory, MCP tool names, and skill descriptions all load into context. Your own setup may add more here, like an [output style](/en/output-styles) or text from [`--append-system-prompt`](/en/cli-reference), which both go into the system prompt the same way.

19* **As Claude works**: each file read adds to context, [path-scoped rules](/en/memory#path-specific-rules) load automatically alongside matching files, and a [PostToolUse hook](/en/hooks-guide) fires after each edit.

20* **The follow-up prompt**: a [subagent](/en/sub-agents) handles the research in its own separate context window, so the large file reads stay out of yours. Only the summary and a small metadata trailer come back.

21* **At the end**: `/compact` replaces the conversation with a structured summary. Most startup content reloads automatically. The [skill](/en/skills) listing is the one exception.

23## Check your own session

25The visualization uses representative numbers. To see your actual context usage at any point, run `/context` for a live breakdown by category with optimization suggestions. Run `/memory` to check which CLAUDE.md and auto memory files loaded at startup.

27## Related resources

29For deeper coverage of the features shown in the timeline, see these pages:

31* [Extend Claude Code](/en/features-overview): when to use CLAUDE.md vs skills vs rules vs hooks vs MCP

32* [Store instructions and memories](/en/memory): CLAUDE.md hierarchy and auto memory

33* [Subagents](/en/sub-agents): delegate research to a separate context window

34* [Best practices](/en/best-practices): managing context as your primary constraint

35* [Reduce token usage](/en/costs#reduce-token-usage): strategies for keeping context usage low

costs.md +23 −8

Details

8 8

9Claude Code consumes tokens for each interaction. Costs vary based on codebase size, query complexity, and conversation length. The average cost is \$6 per developer per day, with daily costs remaining below \$12 for 90% of users.9Claude Code consumes tokens for each interaction. Costs vary based on codebase size, query complexity, and conversation length. The average cost is \$6 per developer per day, with daily costs remaining below \$12 for 90% of users.

10 10

11For team usage, Claude Code charges by API token consumption. On average, Claude Code costs \~\$100-200/developer per month with Sonnet 4.5 though there is large variance depending on how many instances users are running and whether they're using it in automation.11For team usage, Claude Code charges by API token consumption. On average, Claude Code costs \~\$100-200/developer per month with Sonnet 4.6 though there is large variance depending on how many instances users are running and whether they're using it in automation.

12 12

13This page covers how to [track your costs](#track-your-costs), [manage costs for teams](#managing-costs-for-teams), and [reduce token usage](#reduce-token-usage).13This page covers how to [track your costs](#track-your-costs), [manage costs for teams](#managing-costs-for-teams), and [reduce token usage](#reduce-token-usage).

14 14

22 22

23The `/cost` command provides detailed token usage statistics for your current session:23The `/cost` command provides detailed token usage statistics for your current session:

24 24

~~25```~~25```text theme={null}

26Total cost: $0.5526Total cost: $0.55

27Total duration (API): 6m 19.7s27Total duration (API): 6m 19.7s

28Total duration (wall): 6h 33m 10.2s28Total duration (wall): 6h 33m 10.2s

37 When you first authenticate Claude Code with your Claude Console account, a workspace called "Claude Code" is automatically created for you. This workspace provides centralized cost tracking and management for all Claude Code usage in your organization. You cannot create API keys for this workspace; it is exclusively for Claude Code authentication and usage.37 When you first authenticate Claude Code with your Claude Console account, a workspace called "Claude Code" is automatically created for you. This workspace provides centralized cost tracking and management for all Claude Code usage in your organization. You cannot create API keys for this workspace; it is exclusively for Claude Code authentication and usage.

38</Note>38</Note>

39 39

40On Bedrock, Vertex, and Foundry, Claude Code does not send metrics from your cloud. To get cost metrics, several large enterprises reported using [LiteLLM](/en/llm-gateway#litellm-configuration), which is an open-source tool that helps companies [track spend by key](https://docs.litellm.ai/docs/proxy/virtual_keys#tracking-spend). This project is unaffiliated with Anthropic and we have not audited its security.40On Bedrock, Vertex, and Foundry, Claude Code does not send metrics from your cloud. To get cost metrics, several large enterprises reported using [LiteLLM](/en/llm-gateway#litellm-configuration), which is an open-source tool that helps companies [track spend by key](https://docs.litellm.ai/docs/proxy/virtual_keys#tracking-spend). This project is unaffiliated with Anthropic and has not been audited for security.

41 41

42### Rate limit recommendations42### Rate limit recommendations

43 43

54 54

55For example, if you have 200 users, you might request 20k TPM for each user, or 4 million total TPM (200\*20,000 = 4 million).55For example, if you have 200 users, you might request 20k TPM for each user, or 4 million total TPM (200\*20,000 = 4 million).

56 56

57The TPM per user decreases as team size grows because we expect fewer users to use Claude Code concurrently in larger organizations. These rate limits apply at the organization level, not per individual user, which means individual users can temporarily consume more than their calculated share when others aren't actively using the service.57The TPM per user decreases as team size grows because fewer users tend to use Claude Code concurrently in larger organizations. These rate limits apply at the organization level, not per individual user, which means individual users can temporarily consume more than their calculated share when others aren't actively using the service.

58 58

59<Note>59<Note>

60 If you anticipate scenarios with unusually high concurrent usage (such as live training sessions with large groups), you may need higher TPM allocations per user.60 If you anticipate scenarios with unusually high concurrent usage (such as live training sessions with large groups), you may need higher TPM allocations per user.

61</Note>61</Note>

62 62

63### Agent team token costs

65[Agent teams](/en/agent-teams) spawn multiple Claude Code instances, each with its own context window. Token usage scales with the number of active teammates and how long each one runs.

67To keep agent team costs manageable:

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

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

71* 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.

72* Clean up teams when work is done. Active teammates continue consuming tokens even if idle.

73* 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).

63## Reduce token usage75## Reduce token usage

64 76

65Token costs scale with context size: the more context Claude processes, the more tokens you use. Claude Code automatically optimizes costs through prompt caching (which reduces costs for repeated content like system prompts) and auto-compaction (which summarizes conversation history when approaching context limits).77Token costs scale with context size: the more context Claude processes, the more tokens you use. Claude Code automatically optimizes costs through prompt caching (which reduces costs for repeated content like system prompts) and auto-compaction (which summarizes conversation history when approaching context limits).

87 99

88### Reduce MCP server overhead100### Reduce MCP server overhead

89 101

~~90Each MCP server adds tool definitions to your context, even when idle. Run `/context` to see what's consuming space.~~102MCP tool definitions are [deferred by default](/en/mcp#scale-with-mcp-tool-search), so only tool names enter context until Claude uses a specific tool. Run `/context` to see what's consuming space.

91 103

92* **Prefer CLI tools when available**: Tools like `gh`, `aws`, `gcloud`, and `sentry-cli` are more context-efficient than MCP servers because they don't add persistent tool definitions. Claude can run CLI commands directly without the overhead.104* **Prefer CLI tools when available**: Tools like `gh`, `aws`, `gcloud`, and `sentry-cli` are still more context-efficient than MCP servers because they don't add any per-tool listing. Claude can run CLI commands directly.

93* **Disable unused servers**: Run `/mcp` to see configured servers and disable any you're not actively using.105* **Disable unused servers**: Run `/mcp` to see configured servers and disable any you're not actively using.

94* **Tool search is automatic**: When MCP tool descriptions exceed 10% of your context window, Claude Code automatically defers them and loads tools on-demand via [tool search](/en/mcp#scale-with-mcp-tool-search). Since deferred tools only enter context when actually used, a lower threshold means fewer idle tool definitions consuming space. Set a lower threshold with `ENABLE_TOOL_SEARCH=auto:<N>` (for example, `auto:5` triggers when tools exceed 5% of your context window).

95 106

96### Install code intelligence plugins for typed languages107### Install code intelligence plugins for typed languages

97 108

153 164

154### Adjust extended thinking165### Adjust extended thinking

155 166

156Extended thinking is enabled by default with a budget of 31,999 tokens because it significantly improves performance on complex planning and reasoning tasks. However, thinking tokens are billed as output tokens, so for simpler tasks where deep reasoning isn't needed, you can reduce costs by disabling it in `/config` or lowering the budget (for example, `MAX_THINKING_TOKENS=8000`).167Extended thinking is enabled by default because it significantly improves performance on complex planning and reasoning tasks. Thinking tokens are billed as output tokens, and the default budget can be tens of thousands of tokens per request depending on the model. For simpler tasks where deep reasoning isn't needed, you can reduce costs by lowering the [effort level](/en/model-config#adjust-effort-level) with `/effort` or in `/model`, disabling thinking in `/config`, or lowering the budget with `MAX_THINKING_TOKENS=8000`.

157 168

158### Delegate verbose operations to subagents169### Delegate verbose operations to subagents

159 170

160Running tests, fetching documentation, or processing log files can consume significant context. Delegate these to [subagents](/en/sub-agents#isolate-high-volume-operations) so the verbose output stays in the subagent's context while only a summary returns to your main conversation.171Running tests, fetching documentation, or processing log files can consume significant context. Delegate these to [subagents](/en/sub-agents#isolate-high-volume-operations) so the verbose output stays in the subagent's context while only a summary returns to your main conversation.

161 172

173### Manage agent team costs

174

175Agent teams use approximately 7x more tokens than standard sessions when teammates run in plan mode, because each teammate maintains its own context window and runs as a separate Claude instance. Keep team tasks small and self-contained to limit per-teammate token usage. See [agent teams](/en/agent-teams) for details.

176

162### Write specific prompts177### Write specific prompts

163 178

164Vague requests like "improve this codebase" trigger broad scanning. Specific requests like "add input validation to the login function in auth.ts" let Claude work efficiently with minimal file reads.179Vague requests like "improve this codebase" trigger broad scanning. Specific requests like "add input validation to the login function in auth.ts" let Claude work efficiently with minimal file reads.

data-usage.md +14 −12

Details

19 19

20If you explicitly opt in to methods to provide us with materials to train on, such as via the [Development Partner Program](https://support.claude.com/en/articles/11174108-about-the-development-partner-program), we may use those materials provided to train our models. An organization admin can expressly opt-in to the Development Partner Program for their organization. Note that this program is available only for Anthropic first-party API, and not for Bedrock or Vertex users.20If you explicitly opt in to methods to provide us with materials to train on, such as via the [Development Partner Program](https://support.claude.com/en/articles/11174108-about-the-development-partner-program), we may use those materials provided to train our models. An organization admin can expressly opt-in to the Development Partner Program for their organization. Note that this program is available only for Anthropic first-party API, and not for Bedrock or Vertex users.

21 21

~~22### Feedback using the `/bug` command~~22### Feedback using the `/feedback` command

23 23

~~24If you choose to send us feedback about Claude Code using the `/bug` command, we may use your feedback to improve our products and services. Transcripts shared via `/bug` are retained for 5 years.~~24If you choose to send us feedback about Claude Code using the `/feedback` command, we may use your feedback to improve our products and services. Transcripts shared via `/feedback` are retained for 5 years.

25 25

26### Session quality surveys26### Session quality surveys

27 27

28When you see the "How is Claude doing this session?" prompt in Claude Code, responding to this survey (including selecting "Dismiss"), only your numeric rating (1, 2, 3, or dismiss) is recorded. We do not collect or store any conversation transcripts, inputs, outputs, or other session data as part of this survey. Unlike thumbs up/down feedback or `/bug` reports, this session quality survey is a simple product satisfaction metric. Your responses to this survey do not impact your data training preferences and cannot be used to train our AI models.28When you see the "How is Claude doing this session?" prompt in Claude Code, responding to this survey (including selecting "Dismiss"), only your numeric rating (1, 2, 3, or dismiss) is recorded. We do not collect or store any conversation transcripts, inputs, outputs, or other session data as part of this survey. Unlike thumbs up/down feedback or `/feedback` reports, this session quality survey is a simple product satisfaction metric. Your responses to this survey do not impact your data training preferences and cannot be used to train our AI models.

29 29

30To disable these surveys, set `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1`. The survey is also automatically disabled when using third-party providers (Bedrock, Vertex, Foundry) or when telemetry is disabled.30To disable these surveys, set `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1`. The survey is also disabled when `DISABLE_TELEMETRY` or `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` is set. To control frequency instead of disabling, set [`feedbackSurveyRate`](/en/settings#available-settings) in your settings file to a probability between `0` and `1`.

31 31

32### Data retention32### Data retention

33 33

42**Commercial users (Team, Enterprise, and API)**:42**Commercial users (Team, Enterprise, and API)**:

43 43

44* Standard: 30-day retention period44* Standard: 30-day retention period

~~45* Zero data retention: Available with appropriately configured API keys - Claude Code will not retain chat transcripts on servers~~45* [Zero data retention](/en/zero-data-retention): available for Claude Code on Claude for Enterprise. ZDR is enabled on a per-organization basis; each new organization must have ZDR enabled separately by your account team

46* Local caching: Claude Code clients may store sessions locally for up to 30 days to enable session resumption (configurable)46* Local caching: Claude Code clients may store sessions locally for up to 30 days to enable session resumption (configurable)

47 47

48You can delete individual Claude Code on the web sessions at any time. Deleting a session permanently removes the session's event data. For instructions on how to delete sessions, see [Managing sessions](/en/claude-code-on-the-web#managing-sessions).

48Learn more about data retention practices in our [Privacy Center](https://privacy.anthropic.com/).50Learn more about data retention practices in our [Privacy Center](https://privacy.anthropic.com/).

49 51

50For full details, please review our [Commercial Terms of Service](https://www.anthropic.com/legal/commercial-terms) (for Team, Enterprise, and API users) or [Consumer Terms](https://www.anthropic.com/legal/consumer-terms) (for Free, Pro, and Max users) and [Privacy Policy](https://www.anthropic.com/legal/privacy).52For full details, please review our [Commercial Terms of Service](https://www.anthropic.com/legal/commercial-terms) (for Team, Enterprise, and API users) or [Consumer Terms](https://www.anthropic.com/legal/consumer-terms) (for Free, Pro, and Max users) and [Privacy Policy](https://www.anthropic.com/legal/privacy).

51 53

52## Data access54## Data access

53 55

54For all first party users, you can learn more about what data is logged for [local Claude Code](#local-claude-code-data-flow-and-dependencies) and [remote Claude Code](#cloud-execution-data-flow-and-dependencies). Note for remote Claude Code, Claude accesses the repository where you initiate your Claude Code session. Claude does not access repositories that you have connected but have not started a session in.56For all first party users, you can learn more about what data is logged for [local Claude Code](#local-claude-code-data-flow-and-dependencies) and [remote Claude Code](#cloud-execution-data-flow-and-dependencies). [Remote Control](/en/remote-control) sessions follow the local data flow since all execution happens on your machine. Note for remote Claude Code, Claude accesses the repository where you initiate your Claude Code session. Claude does not access repositories that you have connected but have not started a session in.

55 57

56## Local Claude Code: Data flow and dependencies58## Local Claude Code: Data flow and dependencies

57 59

58The diagram below shows how Claude Code connects to external services during installation and normal operation. Solid lines indicate required connections, while dashed lines represent optional or user-initiated data flows.60The diagram below shows how Claude Code connects to external services during installation and normal operation. Solid lines indicate required connections, while dashed lines represent optional or user-initiated data flows.

59 61

60<img src="https://mintcdn.com/claude-code/I9Dpo7RZuIbc86cX/images/claude-code-data-flow.svg?fit=max&auto=format&n=I9Dpo7RZuIbc86cX&q=85&s=9e77f476347e7c9983f6e211d27cf6a9" alt="Diagram showing Claude Code's external connections: install/update connects to NPM, and user requests connect to Anthropic services including Console auth, public-api, and optionally Statsig, Sentry, and bug reporting" data-og-width="720" width="720" data-og-height="520" height="520" data-path="images/claude-code-data-flow.svg" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/I9Dpo7RZuIbc86cX/images/claude-code-data-flow.svg?w=280&fit=max&auto=format&n=I9Dpo7RZuIbc86cX&q=85&s=94c033b9b6db3d10b9e2d7c6d681d9dc 280w, https://mintcdn.com/claude-code/I9Dpo7RZuIbc86cX/images/claude-code-data-flow.svg?w=560&fit=max&auto=format&n=I9Dpo7RZuIbc86cX&q=85&s=430aaaf77c28c501d5753ffa456ee227 560w, https://mintcdn.com/claude-code/I9Dpo7RZuIbc86cX/images/claude-code-data-flow.svg?w=840&fit=max&auto=format&n=I9Dpo7RZuIbc86cX&q=85&s=63c3c3f160b522220a8291fe2f93f970 840w, https://mintcdn.com/claude-code/I9Dpo7RZuIbc86cX/images/claude-code-data-flow.svg?w=1100&fit=max&auto=format&n=I9Dpo7RZuIbc86cX&q=85&s=a7f6e838482f4a1a0a0b4683439369ea 1100w, https://mintcdn.com/claude-code/I9Dpo7RZuIbc86cX/images/claude-code-data-flow.svg?w=1650&fit=max&auto=format&n=I9Dpo7RZuIbc86cX&q=85&s=5fbf749c2f94babb3ef72edfb7aba1e9 1650w, https://mintcdn.com/claude-code/I9Dpo7RZuIbc86cX/images/claude-code-data-flow.svg?w=2500&fit=max&auto=format&n=I9Dpo7RZuIbc86cX&q=85&s=7a1babbdccc4986957698d9c5c30c4a8 2500w" />62<img src="https://mintcdn.com/claude-code/c5r9_6tjPMzFdDDT/images/claude-code-data-flow.svg?fit=max&auto=format&n=c5r9_6tjPMzFdDDT&q=85&s=b3f71c69d743bff63343207dfb7ad6ce" alt="Diagram showing Claude Code's external connections: install/update connects to NPM, and user requests connect to Anthropic services including Console auth, public-api, and optionally Statsig, Sentry, and bug reporting" width="720" height="520" data-path="images/claude-code-data-flow.svg" />

61 63

62Claude Code is installed from [NPM](https://www.npmjs.com/package/@anthropic-ai/claude-code). Claude Code runs locally. In order to interact with the LLM, Claude Code sends data over the network. This data includes all user prompts and model outputs. The data is encrypted in transit via TLS and is not encrypted at rest. Claude Code is compatible with most popular VPNs and LLM proxies.64Claude Code is installed from [NPM](https://www.npmjs.com/package/@anthropic-ai/claude-code). Claude Code runs locally. In order to interact with the LLM, Claude Code sends data over the network. This data includes all user prompts and model outputs. The data is encrypted in transit via TLS and is not encrypted at rest. Claude Code is compatible with most popular VPNs and LLM proxies.

63 65

80 82

81Claude Code connects from users' machines to Sentry for operational error logging. The data is encrypted in transit using TLS and at rest using 256-bit AES encryption. Read more in the [Sentry security documentation](https://sentry.io/security/). To opt out of error logging, set the `DISABLE_ERROR_REPORTING` environment variable.83Claude Code connects from users' machines to Sentry for operational error logging. The data is encrypted in transit using TLS and at rest using 256-bit AES encryption. Read more in the [Sentry security documentation](https://sentry.io/security/). To opt out of error logging, set the `DISABLE_ERROR_REPORTING` environment variable.

82 84

83When users run the `/bug` command, a copy of their full conversation history including code is sent to Anthropic. The data is encrypted in transit and at rest. Optionally, a Github issue is created in our public repository. To opt out of bug reporting, set the `DISABLE_BUG_COMMAND` environment variable.85When users run the `/feedback` command, a copy of their full conversation history including code is sent to Anthropic. The data is encrypted in transit and at rest. Optionally, a Github issue is created in our public repository. To opt out, set the `DISABLE_FEEDBACK_COMMAND` environment variable to `1`.

84 86

85## Default behaviors by API provider87## Default behaviors by API provider

86 88

87By default, we disable all non-essential traffic (including error reporting, telemetry, bug reporting functionality, and session quality surveys) when using Bedrock, Vertex, or Foundry. You can also opt out of all of these at once by setting the `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` environment variable. Here are the full default behaviors:89By default, error reporting, telemetry, and bug reporting are disabled when using Bedrock, Vertex, or Foundry. Session quality surveys are the exception and appear regardless of provider. You can opt out of all non-essential traffic, including surveys, at once by setting `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`. Here are the full default behaviors:

88 90

90| ------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------ |92| ------------------------------------ | -------------------------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------- |

94| **Session quality surveys** | Default on. `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1` to disable. | Default off. `CLAUDE_CODE_USE_VERTEX` must be 1. | Default off. `CLAUDE_CODE_USE_BEDROCK` must be 1. | Default off. `CLAUDE_CODE_USE_FOUNDRY` must be 1. |96| **Session quality surveys** | Default on. `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1` to disable. | Default on. `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1` to disable. | Default on. `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1` to disable. | Default on. `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1` to disable. |

95 97

96All environment variables can be checked into `settings.json` ([read more](/en/settings)).98All environment variables can be checked into `settings.json` ([read more](/en/settings)).

desktop.md +588 −169

Details

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt2> 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.3> Use this file to discover all available pages before exploring further.

4 4

~~5# Claude Code on desktop~~5# Use Claude Code Desktop

6 6

~~7> Run Claude Code tasks locally or on secure cloud infrastructure with the Claude desktop app~~7> Get more out of Claude Code Desktop: computer use, Dispatch sessions from your phone, parallel sessions with Git isolation, visual diff review, app previews, PR monitoring, connectors, and enterprise configuration.

8 8

~~9<Note>~~9The Code tab within the Claude Desktop app lets you use Claude Code through a graphical interface instead of the terminal.

~~10 Claude Code on desktop is currently in preview.~~

~~11</Note>~~

12 10

13Claude Code is an AI coding assistant that works directly with your codebase. Unlike Claude.ai chat, it can read your project files, edit code, run terminal commands, and understand how different parts of your code connect. You watch changes happen in real time.11Desktop adds these capabilities on top of the standard Claude Code experience:

14 12

15You can use Claude Code through the terminal ([CLI](/en/quickstart)) or through the desktop app described here. Both provide the same core capabilities. The desktop app adds a graphical interface and visual session management.13* [Visual diff review](#review-changes-with-diff-view) with inline comments

14* [Live app preview](#preview-your-app) with dev servers

15* [Computer use](#let-claude-use-your-computer) to open apps and control your screen on macOS

16* [GitHub PR monitoring](#monitor-pull-request-status) with auto-fix and auto-merge

17* [Parallel sessions](#work-in-parallel-with-sessions) with automatic Git worktree isolation

18* [Dispatch](#sessions-from-dispatch) integration: send a task from your phone, get a session here

19* [Scheduled tasks](#schedule-recurring-tasks) that run Claude on a recurring schedule

20* [Connectors](#connect-external-tools) for GitHub, Slack, Linear, and more

21* Local, [SSH](#ssh-sessions), and [cloud](#run-long-running-tasks-remotely) environments

16 22

~~17<CardGroup cols={2}>~~23<Tip>

~~18 <Card title="New to Claude Code?" icon="rocket" href="#installation-and-setup">~~24 New to Desktop? Start with [Get started](/en/desktop-quickstart) to install the app and make your first edit.

~~19 Start here to install and make your first edit~~25</Tip>

~~20 </Card>~~

21 26

~~22 <Card title="Coming from the CLI?" icon="terminal" href="#how-desktop-relates-to-cli">~~27This page covers [working with code](#work-with-code), [computer use](#let-claude-use-your-computer), [managing sessions](#manage-sessions), [extending Claude Code](#extend-claude-code), [scheduled tasks](#schedule-recurring-tasks), and [configuration](#environment-configuration). It also includes a [CLI comparison](#coming-from-the-cli) and [troubleshooting](#troubleshooting).

~~23 See what's shared and what's different~~

~~24 </Card>~~

~~25</CardGroup>~~

26 28

~~27The desktop app has three tabs:~~29## Start a session

28 30

~~29* **Chat**: A conversational interface for general questions and tasks (like Claude.ai)~~31Before you send your first message, configure four things in the prompt area:

~~30* **Cowork**: An autonomous agent that works on tasks in the background~~

~~31* **Code**: An AI coding assistant that reads and edits your project files directly~~

32 32

~~33This documentation covers the **Code** tab. For the chat interface, see the [Claude Desktop support articles](https://support.claude.com/en/collections/16163169-claude-desktop).~~33* **Environment**: choose where Claude runs. Select **Local** for your machine, **Remote** for Anthropic-hosted cloud sessions, or an [**SSH connection**](#ssh-sessions) for a remote machine you manage. See [environment configuration](#environment-configuration).

34* **Project folder**: select the folder or repository Claude works in. For remote sessions, you can add [multiple repositories](#run-long-running-tasks-remotely).

35* **Model**: pick a [model](/en/model-config#available-models) from the dropdown next to the send button. The model is locked once the session starts.

36* **Permission mode**: choose how much autonomy Claude has from the [mode selector](#choose-a-permission-mode). You can change this during the session.

34 37

~~35## Installation and setup~~38Type your task and press **Enter** to start. Each session tracks its own context and changes independently.

36 39

~~37<Steps>~~40## Work with code

~~38 <Step title="Download the app">~~

~~39 Download Claude for your platform. You'll need an Anthropic account ([sign up at claude.ai](https://claude.ai) if you don't have one).~~

40 41

~~41 <CardGroup cols={2}>~~42Give Claude the right context, control how much it does on its own, and review what it changed.

~~42 <Card title="macOS" icon="apple" href="https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code&utm_medium=docs">~~

~~43 Universal build for Intel and Apple Silicon~~

~~44 </Card>~~

45 43

~~46 <Card title="Windows" icon="windows" href="https://claude.ai/api/desktop/win32/x64/exe/latest/redirect?utm_source=claude_code&utm_medium=docs">~~44### Use the prompt box

~~47 For x64 processors~~

~~48 </Card>~~

~~49 </CardGroup>~~

50 45

51 For Windows ARM64, [download here](https://claude.ai/api/desktop/win32/arm64/exe/latest/redirect?utm_source=claude_code\&utm_medium=docs). Local sessions are not available on ARM64 devices, so use remote sessions instead.46Type what you want Claude to do and press **Enter** to send. Claude reads your project files, makes changes, and runs commands based on your [permission mode](#choose-a-permission-mode). You can interrupt Claude at any point: click the stop button or type your correction and press **Enter**. Claude stops what it's doing and adjusts based on your input.

52 47

~~53 Linux is not currently supported.~~48The **+** button next to the prompt box gives you access to file attachments, [skills](#use-skills), [connectors](#connect-external-tools), and [plugins](#install-plugins).

~~54 </Step>~~

55 49

~~56 <Step title="Open the app and sign in">~~50### Add files and context to prompts

~~57 Launch Claude from your Applications folder (macOS) or Start menu (Windows). Sign in with your Anthropic account.~~

~~58 </Step>~~

59 51

~~60 <Step title="Select the Code tab">~~52The prompt box supports two ways to bring in external context:

~~61 Click the **Code** tab in the top left. If clicking Code prompts you to sign in online, complete the sign-in and restart the app.~~

~~62 </Step>~~

~~63</Steps>~~

64 53

~~65## Getting started~~54* **@mention files**: type `@` followed by a filename to add a file to the conversation context. Claude can then read and reference that file. @mention is not available in remote sessions.

55* **Attach files**: attach images, PDFs, and other files to your prompt using the attachment button, or drag and drop files directly into the prompt. This is useful for sharing screenshots of bugs, design mockups, or reference documents.

66 56

~~67If you already use the CLI, you can skip to [How Desktop relates to CLI](#how-desktop-relates-to-cli) for a quick overview of differences.~~57### Choose a permission mode

68 58

~~69<Steps>~~59Permission modes control how much autonomy Claude has during a session: whether it asks before editing files, running commands, or both. You can switch modes at any time using the mode selector next to the send button. Start with Ask permissions to see exactly what Claude does, then move to Auto accept edits or Plan mode as you get comfortable.

~~70 <Step title="Choose a folder and environment">~~

~~71 Select **Local** to run Claude on your machine using your files directly. This is the best choice for getting started. Click **Select folder** and choose your project directory.~~

72 60

~~73 You can also run [remote sessions](/en/claude-code-on-the-web) that continue in the cloud even if you close the app.~~61| Mode | Settings key | Behavior |

~~74 </Step>~~62| ---------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

63| **Ask permissions** | `default` | Claude asks before editing files or running commands. You see a diff and can accept or reject each change. Recommended for new users. |

64| **Auto accept edits** | `acceptEdits` | Claude auto-accepts file edits but still asks before running terminal commands. Use this when you trust file changes and want faster iteration. |

65| **Plan mode** | `plan` | Claude analyzes your code and creates a plan without modifying files or running commands. Good for complex tasks where you want to review the approach first. |

66| **Auto** | `auto` | Claude executes all actions with background safety checks that verify alignment with your request. Reduces permission prompts while maintaining oversight. Currently a research preview. Available on Team plans (Enterprise rolling out shortly). Requires Claude Sonnet 4.6 or Opus 4.6. Enable in your Settings → Claude Code. |

67| **Bypass permissions** | `bypassPermissions` | Claude runs without any permission prompts, equivalent to `--dangerously-skip-permissions` in the CLI. Enable in your Settings → Claude Code under "Allow bypass permissions mode". Only use this in sandboxed containers or VMs. Enterprise admins can disable this option. |

75 68

~~76 <Step title="Start a session">~~69The `dontAsk` permission mode is available only in the [CLI](/en/permission-modes#allow-only-pre-approved-tools-with-dontask-mode).

~~77 Type what you want Claude to do:~~

78 70

~~79 * "Find a TODO comment and fix it"~~71<Tip title="Best practice">

~~80 * "Add tests for the main function"~~72 Start complex tasks in Plan mode so Claude maps out an approach before making changes. Once you approve the plan, switch to Auto accept edits or Ask permissions to execute it. See [explore first, then plan, then code](/en/best-practices#explore-first-then-plan-then-code) for more on this workflow.

~~81 * "Create a CLAUDE.md with instructions for this codebase"~~73</Tip>

82 74

~~83 A **session** is a conversation with Claude about your code. Each session tracks its own context and changes, so you can work on multiple tasks without them interfering with each other.~~75Remote sessions support Auto accept edits and Plan mode. Ask permissions is not available because remote sessions auto-accept file edits by default, and Bypass permissions is not available because the remote environment is already sandboxed.

~~84 </Step>~~

85 76

~~86 <Step title="Review and accept changes">~~77Enterprise admins can restrict which permission modes are available. See [enterprise configuration](#enterprise-configuration) for details.

~~87 By default, Code is in **Ask** mode, where Claude proposes changes and waits for your approval before applying them. You'll see:~~

88 78

~~89 1. **A diff view** showing exactly what will change in each file~~79### Preview your app

~~90 2. **Accept/Reject buttons** to approve or decline each change~~

~~91 3. **Real-time updates** as Claude works through your request~~

92 80

~~93 If you reject a change, Claude will ask how you'd like to proceed differently. Your files aren't modified until you accept.~~81Claude can start a dev server and open an embedded browser to verify its changes. This works for frontend web apps as well as backend servers: Claude can test API endpoints, view server logs, and iterate on issues it finds. In most cases, Claude starts the server automatically after editing project files. You can also ask Claude to preview at any time. By default, Claude [auto-verifies](#auto-verify-changes) changes after every edit.

~~94 </Step>~~

~~95</Steps>~~

96 82

~~97The sections below cover commands, permission modes, parallel sessions, and ways to extend Claude Code with custom workflows and integrations.~~83From the preview panel, you can:

98 84

~~99## What you can do~~85* Interact with your running app directly in the embedded browser

86* Watch Claude verify its own changes automatically: it takes screenshots, inspects the DOM, clicks elements, fills forms, and fixes issues it finds

87* Start or stop servers from the **Preview** dropdown in the session toolbar

88* Persist cookies and local storage across server restarts by selecting **Persist sessions** in the dropdown, so you don't have to re-login during development

89* Edit the server configuration or stop all servers at once

100 90

101Claude Code can edit files, run terminal commands, and understand how your code connects. Try prompts like:91Claude creates the initial server configuration based on your project. If your app uses a custom dev command, edit `.claude/launch.json` to match your setup. See [Configure preview servers](#configure-preview-servers) for the full reference.

102 92

103* `Fix the bug in the login function`93To clear saved session data, toggle **Persist preview sessions** off in Settings → Claude Code. To disable preview entirely, toggle off **Preview** in Settings → Claude Code.

104* `Run the tests and fix any failures`

105* `How does the authentication flow work?`

106 94

107You can rename, resume, and archive sessions through the sidebar.95### Review changes with diff view

108 96

109### Choose a permission mode97After Claude makes changes to your code, the diff view lets you review modifications file by file before creating a pull request.

110 98

111Control how Claude works using the mode selector next to the send button:99When Claude changes files, a diff stats indicator appears showing the number of lines added and removed, such as `+12 -1`. Click this indicator to open the diff viewer, which displays a file list on the left and the changes for each file on the right.

112 100

113* **Ask** (recommended for new users): Claude asks for your approval before each file edit or command. You see a diff view and can accept or reject each change.101To comment on specific lines, click any line in the diff to open a comment box. Type your feedback and press **Enter** to add the comment. After adding comments to multiple lines, submit all comments at once:

114* **Code**: Claude auto-accepts file edits but still asks before running terminal commands. Use this when you trust file changes and want faster iteration.

115* **Plan**: Claude creates a detailed plan for your approval before making any changes. Good for complex tasks where you want to review the approach first.

116 102

117To stop Claude mid-task, click the stop button.103* **macOS**: press **Cmd+Enter**

104* **Windows**: press **Ctrl+Enter**

118 105

119Remote sessions only support **Code** and **Plan** modes because they continue running in the background without requiring your active participation. See [permission modes](/en/iam#permission-modes) for details on how these work internally.106Claude reads your comments and makes the requested changes, which appear as a new diff you can review.

120 107

121### Work in parallel with sessions108### Review your code

109

110In the diff view, click **Review code** in the top-right toolbar to ask Claude to evaluate the changes before you commit. Claude examines the current diffs and leaves comments directly in the diff view. You can respond to any comment or ask Claude to revise.

111

112The review focuses on high-signal issues: compile errors, definite logic errors, security vulnerabilities, and obvious bugs. It does not flag style, formatting, pre-existing issues, or anything a linter would catch.

113

114### Monitor pull request status

122 115

123Click **+ New session** in the sidebar to work on multiple tasks in parallel. For Git repositories, each session gets its own isolated copy of your project using worktrees, so changes in one session don't affect another until you commit them. Worktrees are stored in `~/.claude-worktrees/` by default.116After you open a pull request, a CI status bar appears in the session. Claude Code uses the GitHub CLI to poll check results and surface failures.

117

118* **Auto-fix**: when enabled, Claude automatically attempts to fix failing CI checks by reading the failure output and iterating.

119* **Auto-merge**: when enabled, Claude merges the PR once all checks pass. The merge method is squash. Auto-merge must be [enabled in your GitHub repository settings](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository) for this to work.

120

121Use the **Auto-fix** and **Auto-merge** toggles in the CI status bar to enable either option. Claude Code also sends a desktop notification when CI finishes.

124 122

125<Note>123<Note>

126 Session isolation requires [Git](https://git-scm.com/downloads). Without Git, sessions in the same directory edit the same files, so changes in one session are immediately visible in others.124 PR monitoring requires the [GitHub CLI (`gh`)](https://cli.github.com/) to be installed and authenticated on your machine. If `gh` is not installed, Desktop prompts you to install it the first time you try to create a PR.

127</Note>125</Note>

128 126

129To include files listed in your `.gitignore` (like `.env`) in new worktrees, create a `.worktreeinclude` file in your project root listing the file patterns to copy.127## Let Claude use your computer

128

129Computer use lets Claude open your apps, control your screen, and work directly on your machine the way you would. Ask Claude to test a native app in the iOS simulator, interact with a desktop tool that has no CLI, or automate something that only works through a GUI.

130

131<Note>

132 Computer use is a research preview on macOS that requires a Pro or Max plan. It is not available on Team or Enterprise plans. The Claude Desktop app must be running.

133</Note>

134

135Computer use is off by default. [Enable it in Settings](#enable-computer-use) and grant the required macOS permissions before Claude can control your screen.

136

137<Warning>

138 Unlike the [sandboxed Bash tool](/en/sandboxing), computer use runs on your actual desktop with access to whatever you approve. Claude checks each action and flags potential prompt injection from on-screen content, but the trust boundary is different. See the [computer use safety guide](https://support.claude.com/en/articles/14128542) for best practices.

139</Warning>

140

141### When computer use applies

142

143Claude has several ways to interact with an app or service, and computer use is the broadest and slowest. It tries the most precise tool first:

144

145* If you have a [connector](#connect-external-tools) for a service, Claude uses the connector.

146* If the task is a shell command, Claude uses Bash.

147* If the task is browser work and you have [Claude in Chrome](/en/chrome) set up, Claude uses that.

148* If none of those apply, Claude uses computer use.

149

150The [per-app access tiers](#app-permissions) reinforce this: browsers are capped at view-only, and terminals and IDEs at click-only, steering Claude toward the dedicated tool even when computer use is active. Screen control is reserved for things nothing else can reach, like native apps, hardware control panels, the iOS simulator, or proprietary tools without an API.

151

152### Enable computer use

153

154Computer use is off by default. If you ask Claude to do something that needs it while it's off, Claude tells you it could do the task if you enable computer use in Settings. To enable it, open **Settings > Desktop app > General** and toggle **Computer use** on. Before the toggle takes effect, you need to grant two macOS system permissions:

155

156* **Accessibility**: lets Claude click, type, and scroll

157* **Screen Recording**: lets Claude see what's on your screen

158

159The Settings page shows the current status of each permission. If either is denied, click the badge to open the relevant System Settings pane.

160

161### App permissions

162

163The first time Claude needs to use an app, a prompt appears in your session. Click **Allow for this session** or **Deny**. Approvals last for the current session, or 30 minutes in [Dispatch-spawned sessions](#sessions-from-dispatch).

164

165The prompt also shows what level of control Claude gets for that app. These tiers are fixed by app category and can't be changed:

166

167| Tier | What Claude can do | Applies to |

168| :----------- | :------------------------------------------------------- | :-------------------------- |

169| View only | See the app in screenshots | Browsers, trading platforms |

170| Click only | Click and scroll, but not type or use keyboard shortcuts | Terminals, IDEs |

171| Full control | Click, type, drag, and use keyboard shortcuts | Everything else |

172

173Apps with broad reach like Terminal, Finder, and System Settings show an extra warning in the prompt so you know what approving them grants.

174

175You can configure two settings in **Settings > Desktop app > General**:

176

177* **Denied apps**: add apps here to reject them without prompting. Claude may still affect a denied app indirectly through actions in an allowed app, but it can't interact with the denied app directly.

178* **Unhide apps when Claude finishes**: while Claude is working, your other windows are hidden so it interacts with only the approved app. When Claude finishes, hidden windows are restored unless you turn this setting off.

179

180## Manage sessions

181

182Each session is an independent conversation with its own context and changes. You can run multiple sessions in parallel, send work to the cloud, or let Dispatch start sessions for you from your phone.

183

184### Work in parallel with sessions

185

186Click **+ New session** in the sidebar to work on multiple tasks in parallel. For Git repositories, each session gets its own isolated copy of your project using [Git worktrees](/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees), so changes in one session don't affect other sessions until you commit them.

187

188Worktrees are stored in `<project-root>/.claude/worktrees/` by default. You can change this to a custom directory in Settings → Claude Code under "Worktree location". You can also set a branch prefix that gets prepended to every worktree branch name, which is useful for keeping Claude-created branches organized. To remove a worktree when you're done, hover over the session in the sidebar and click the archive icon.

189

190To include gitignored files like `.env` in new worktrees, create a [`.worktreeinclude` file](/en/common-workflows#copy-gitignored-files-to-worktrees) in your project root.

191

192<Note>

193 Session isolation requires [Git](https://git-scm.com/downloads). Most Macs include Git by default. Run `git --version` in Terminal to check. On Windows, Git is required for the Code tab to work: [download Git for Windows](https://git-scm.com/downloads/win), install it, and restart the app. If you run into Git errors, try a Cowork session to help troubleshoot your setup.

194</Note>

130 195

131To manage a session, click its dropdown in the sidebar to rename it, archive it, or check context usage. When context fills up, Claude automatically summarizes the conversation. You can also ask Claude to compact if you want to free up space earlier.196Use the filter icon at the top of the sidebar to filter sessions by status (Active, Archived) and environment (Local, Cloud). To rename a session or check context usage, click the session title in the toolbar at the top of the active session. When context fills up, Claude automatically summarizes the conversation and continues working. You can also type `/compact` to trigger summarization earlier and free up context space. See [the context window](/en/how-claude-code-works#the-context-window) for details on how compaction works.

132 197

133### Run long-running tasks remotely198### Run long-running tasks remotely

134 199

135For large refactors, test suites, migrations, or other long-running tasks, select **Remote** instead of **Local** when starting a session. Remote sessions run on Anthropic's cloud infrastructure and continue even if you close the app or shut down your computer. Check back anytime to see progress or steer Claude in a different direction.200For large refactors, test suites, migrations, or other long-running tasks, select **Remote** instead of **Local** when starting a session. Remote sessions run on Anthropic's cloud infrastructure and continue even if you close the app or shut down your computer. Check back anytime to see progress or steer Claude in a different direction. You can also monitor remote sessions from [claude.ai/code](https://claude.ai/code) or the Claude iOS app.

136 201

137Remote sessions support **Code** and **Plan** modes. See [Claude Code on the web](/en/claude-code-on-the-web) for details on configuring remote environments.202Remote sessions also support multiple repositories. After selecting a cloud environment, click the **+** button next to the repo pill to add additional repositories to the session. Each repo gets its own branch selector. This is useful for tasks that span multiple codebases, such as updating a shared library and its consumers.

138 203

139### Review changes with diff view204See [Claude Code on the web](/en/claude-code-on-the-web) for more on how remote sessions work.

140 205

141After Claude makes changes to your code, the diff view lets you review modifications file by file before creating a pull request.206### Continue in another surface

207

208The **Continue in** menu, accessible from the VS Code icon in the bottom right of the session toolbar, lets you move your session to another surface:

209

210* **Claude Code on the Web**: sends your local session to continue running remotely. Desktop pushes your branch, generates a summary of the conversation, and creates a new remote session with the full context. You can then choose to archive the local session or keep it. This requires a clean working tree, and is not available for SSH sessions.

211* **Your IDE**: opens your project in a supported IDE at the current working directory.

142 212

143When Claude changes files, a diff stats indicator appears showing the number of lines added and removed (for example, `+12 -1`). Click this indicator to open the diff viewer, which displays a file list on the left and the changes for each file on the right.213### Sessions from Dispatch

144 214

145To comment on specific lines, click any line in the diff to open a comment box. Type your feedback and press **Enter** to send. In the full diff view, press **Enter** to accept each comment, then **Cmd+Enter** to send them all. Claude reads your comments and makes the requested changes, which appear as a new diff you can review.215[Dispatch](https://support.claude.com/en/articles/13947068) is a persistent conversation with Claude that lives in the [Cowork](https://claude.com/product/cowork#dispatch-and-computer-use) tab. You message Dispatch a task, and it decides how to handle it.

216

217A task can end up as a Code session in two ways: you ask for one directly, such as "open a Claude Code session and fix the login bug", or Dispatch decides the task is development work and spawns one on its own. Tasks that typically route to Code include fixing bugs, updating dependencies, running tests, or opening pull requests. Research, document editing, and spreadsheet work stay in Cowork.

218

219Either way, the Code session appears in the Code tab's sidebar with a **Dispatch** badge. You get a push notification on your phone when it finishes or needs your approval.

220

221If you have [computer use](#let-claude-use-your-computer) enabled, Dispatch-spawned Code sessions can use it too. App approvals in those sessions expire after 30 minutes and re-prompt, rather than lasting the full session like regular Code sessions.

222

223For setup, pairing, and Dispatch settings, see the [Dispatch help article](https://support.claude.com/en/articles/13947068). Dispatch requires a Pro or Max plan and is not available on Team or Enterprise plans.

224

225Dispatch is one of several ways to work with Claude when you're away from your terminal. See [Platforms and integrations](/en/platforms#work-when-you-are-away-from-your-terminal) to compare it with Remote Control, Channels, Slack, and scheduled tasks.

146 226

147## Extend Claude Code227## Extend Claude Code

148 228

149You can extend Claude Code with custom commands, automated workflows, and external integrations.229Connect external services, add reusable workflows, customize Claude's behavior, and configure preview servers.

150 230

151### Connect external tools231### Connect external tools

152 232

153For local sessions, click the **...** button before starting and select **Connectors** to add integrations like Google Calendar, Slack, GitHub, Linear, Notion, and more. Connectors must be configured before the session starts and are only available for local sessions. Once connected, Claude can read your calendar, send messages, create issues, and interact with your tools directly. You can ask Claude what connectors are configured in your session.233For local and [SSH](#ssh-sessions) sessions, click the **+** button next to the prompt box and select **Connectors** to add integrations like Google Calendar, Slack, GitHub, Linear, Notion, and more. You can add connectors before or during a session. The **+** button is not available in remote sessions, but [scheduled tasks](/en/web-scheduled-tasks) configure connectors at task creation time.

234

235To manage or disconnect connectors, go to Settings → Connectors in the desktop app, or select **Manage connectors** from the Connectors menu in the prompt box.

236

237Once connected, Claude can read your calendar, send messages, create issues, and interact with your tools directly. You can ask Claude what connectors are configured in your session.

238

239Connectors are [MCP servers](/en/mcp) with a graphical setup flow. Use them for quick integration with supported services. For integrations not listed in Connectors, add MCP servers manually via [settings files](/en/mcp#installing-mcp-servers). You can also [create custom connectors](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp).

240

241### Use skills

154 242

155Connectors are [MCP (Model Context Protocol) servers](/en/mcp) with built-in setup. You can also [create custom connectors](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp) or add MCP servers manually via [configuration files](/en/mcp#configure-mcp-servers).243[Skills](/en/skills) extend what Claude can do. Claude loads them automatically when relevant, or you can invoke one directly: type `/` in the prompt box or click the **+** button and select **Slash commands** to browse what's available. This includes [built-in commands](/en/commands), your [custom skills](/en/skills#create-custom-skills), project skills from your codebase, and skills from any [installed plugins](/en/plugins). Select one and it appears highlighted in the input field. Type your task after it and send as usual.

156 244

157### Create custom skills245### Install plugins

246

247[Plugins](/en/plugins) are reusable packages that add skills, agents, hooks, MCP servers, and LSP configurations to Claude Code. You can install plugins from the desktop app without using the terminal.

248

249For local and [SSH](#ssh-sessions) sessions, click the **+** button next to the prompt box and select **Plugins** to see your installed plugins and their commands. To add a plugin, select **Add plugin** from the submenu to open the plugin browser, which shows available plugins from your configured [marketplaces](/en/plugin-marketplaces) including the official Anthropic marketplace. Select **Manage plugins** to enable, disable, or uninstall plugins.

250

251Plugins can be scoped to your user account, a specific project, or local-only. Plugins are not available for remote sessions. For the full plugin reference including creating your own plugins, see [plugins](/en/plugins).

252

253### Configure preview servers

254

255Claude automatically detects your dev server setup and stores the configuration in `.claude/launch.json` at the root of the folder you selected when starting the session. Preview uses this folder as its working directory, so if you selected a parent folder, subfolders with their own dev servers won't be detected automatically. To work with a subfolder's server, either start a session in that folder directly or add a configuration manually.

256

257To customize how your server starts, for example to use `yarn dev` instead of `npm run dev` or to change the port, edit the file manually or click **Edit configuration** in the Preview dropdown to open it in your code editor. The file supports JSON with comments.

258

259```json theme={null}

260{

261 "version": "0.0.1",

262 "configurations": [

263 {

264 "name": "my-app",

265 "runtimeExecutable": "npm",

266 "runtimeArgs": ["run", "dev"],

267 "port": 3000

268 }

269 ]

270}

271```

272

273You can define multiple configurations to run different servers from the same project, such as a frontend and an API. See the [examples](#examples) below.

274

275#### Auto-verify changes

276

277When `autoVerify` is enabled, Claude automatically verifies code changes after editing files. It takes screenshots, checks for errors, and confirms changes work before completing its response.

278

279Auto-verify is on by default. Disable it per-project by adding `"autoVerify": false` to `.claude/launch.json`, or toggle it from the **Preview** dropdown menu.

280

281```json theme={null}

282{

283 "version": "0.0.1",

284 "autoVerify": false,

285 "configurations": [...]

286}

287```

288

289When disabled, preview tools are still available and you can ask Claude to verify at any time. Auto-verify makes it automatic after every edit.

290

291#### Configuration fields

292

293Each entry in the `configurations` array accepts the following fields:

294

295| Field | Type | Description |

296| ------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

297| `name` | string | A unique identifier for this server |

298| `runtimeExecutable` | string | The command to run, such as `npm`, `yarn`, or `node` |

299| `runtimeArgs` | string\[] | Arguments passed to `runtimeExecutable`, such as `["run", "dev"]` |

300| `port` | number | The port your server listens on. Defaults to 3000 |

301| `cwd` | string | Working directory relative to your project root. Defaults to the project root. Use `${workspaceFolder}` to reference the project root explicitly |

302| `env` | object | Additional environment variables as key-value pairs, such as `{ "NODE_ENV": "development" }`. Don't put secrets here since this file is committed to your repo. Secrets set in your shell profile are inherited automatically. |

303| `autoPort` | boolean | How to handle port conflicts. See below |

304| `program` | string | A script to run with `node`. See [when to use `program` vs `runtimeExecutable`](#when-to-use-program-vs-runtimeexecutable) |

305| `args` | string\[] | Arguments passed to `program`. Only used when `program` is set |

306

307##### When to use `program` vs `runtimeExecutable`

308

309Use `runtimeExecutable` with `runtimeArgs` to start a dev server through a package manager. For example, `"runtimeExecutable": "npm"` with `"runtimeArgs": ["run", "dev"]` runs `npm run dev`.

310

311Use `program` when you have a standalone script you want to run with `node` directly. For example, `"program": "server.js"` runs `node server.js`. Pass additional flags with `args`.

312

313#### Port conflicts

314

315The `autoPort` field controls what happens when your preferred port is already in use:

316

317* **`true`**: Claude finds and uses a free port automatically. Suitable for most dev servers.

318* **`false`**: Claude fails with an error. Use this when your server must use a specific port, such as for OAuth callbacks or CORS allowlists.

319* **Not set (default)**: Claude asks whether the server needs that exact port, then saves your answer.

320

321When Claude picks a different port, it passes the assigned port to your server via the `PORT` environment variable.

322

323#### Examples

324

325These configurations show common setups for different project types:

326

327<Tabs>

328 <Tab title="Next.js">

329 This configuration runs a Next.js app using Yarn on port 3000:

330

331 ```json theme={null}

332 {

333 "version": "0.0.1",

334 "configurations": [

335 {

336 "name": "web",

337 "runtimeExecutable": "yarn",

338 "runtimeArgs": ["dev"],

339 "port": 3000

340 }

341 ]

342 }

343 ```

344 </Tab>

345

346 <Tab title="Multiple servers">

347 For a monorepo with a frontend and an API server, define multiple configurations. The frontend uses `autoPort: true` so it picks a free port if 3000 is taken, while the API server requires port 8080 exactly:

348

349 ```json theme={null}

350 {

351 "version": "0.0.1",

352 "configurations": [

353 {

354 "name": "frontend",

355 "runtimeExecutable": "npm",

356 "runtimeArgs": ["run", "dev"],

357 "cwd": "apps/web",

358 "port": 3000,

359 "autoPort": true

360 },

361 {

362 "name": "api",

363 "runtimeExecutable": "npm",

364 "runtimeArgs": ["run", "start"],

365 "cwd": "server",

366 "port": 8080,

367 "env": { "NODE_ENV": "development" },

368 "autoPort": false

369 }

370 ]

371 }

372 ```

373 </Tab>

374

375 <Tab title="Node.js script">

376 To run a Node.js script directly instead of using a package manager command, use the `program` field:

377

378 ```json theme={null}

379 {

380 "version": "0.0.1",

381 "configurations": [

382 {

383 "name": "server",

384 "program": "server.js",

385 "args": ["--verbose"],

386 "port": 4000

387 }

388 ]

389 }

390 ```

391 </Tab>

392</Tabs>

393

394## Schedule recurring tasks

395

396By default, scheduled tasks start a new session automatically at a time and frequency you choose. Use them for recurring work like daily code reviews, dependency update checks, or morning briefings that pull from your calendar and inbox.

397

398### Compare scheduling options

399

400Claude Code offers three ways to schedule recurring work:

401

403| :------------------------- | :------------------------------- | :---------------------------------------------- | :----------------------------- |

405| Requires machine on | No | Yes | Yes |

406| Requires open session | No | No | Yes |

407| Persistent across restarts | Yes | Yes | No (session-scoped) |

408| Access to local files | No (fresh clone) | Yes | Yes |

411| Customizable schedule | Via `/schedule` in the CLI | Yes | Yes |

413

414<Tip>

415 Use **cloud tasks** for work that should run reliably without your machine. Use **Desktop tasks** when you need access to local files and tools. Use **`/loop`** for quick polling during a session.

416</Tip>

417

418The Schedule page supports two kinds of tasks:

419

420* **Local tasks**: run on your machine. They have direct access to your local files and tools, but the desktop app must be open and your computer awake for them to run.

421* **Remote tasks**: run on Anthropic-managed cloud infrastructure. They keep running even when your computer is off, but work against a fresh clone of your repository rather than your local checkout.

422

423Both kinds appear in the same task grid. Click **New task** to pick which kind to create. The rest of this section covers local tasks; for remote tasks, see [Cloud scheduled tasks](/en/web-scheduled-tasks).

424

425See [How scheduled tasks run](#how-scheduled-tasks-run) for details on missed runs and catch-up behavior for local tasks.

426

427<Note>

428 By default, local scheduled tasks run against whatever state your working directory is in, including uncommitted changes. Enable the worktree toggle in the prompt input to give each run its own isolated Git worktree, the same way [parallel sessions](#work-in-parallel-with-sessions) work.

429</Note>

158 430

159[Skills](/en/skills) are reusable prompts that extend Claude's capabilities. For example, you could create a `review` skill that runs your standard code review checklist, or a `deploy` skill that walks through your deployment steps. Skills are defined as markdown files in `.claude/skills/` and can include instructions, context, and even call other tools. Ask Claude what skills are available or to run a specific skill. Claude can also help you create a skill if you describe what you want, or see [skills](/en/skills) to learn how to write them yourself.431To create a local scheduled task, click **Schedule** in the sidebar, click **New task**, and choose **New local task**. Configure these fields:

160 432

161### Automate workflows with hooks433| Field | Description |

434| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

435| Name | Identifier for the task. Converted to lowercase kebab-case and used as the folder name on disk. Must be unique across your tasks. |

436| Description | Short summary shown in the task list. |

437| Prompt | The instructions sent to Claude when the task runs. Write this the same way you'd write any message in the prompt box. The prompt input also includes controls for model, permission mode, working folder, and worktree. |

438| Frequency | How often the task runs. See [frequency options](#frequency-options) below. |

162 439

163[Hooks](/en/hooks) run shell commands automatically in response to Claude Code events. For example, you could run a linter after every file edit, auto-format code, or send notifications when tasks complete. Hooks are configured in your [settings files](/en/settings). See [hooks](/en/hooks) for available events and configuration examples.440You can also create a task by describing what you want in any session. For example, "set up a daily code review that runs every morning at 9am."

441

442### Frequency options

443

444* **Manual**: no schedule, only runs when you click **Run now**. Useful for saving a prompt you trigger on demand

445* **Hourly**: runs every hour. Each task gets a fixed offset of up to 10 minutes from the top of the hour to stagger API traffic

446* **Daily**: shows a time picker, defaults to 9:00 AM local time

447* **Weekdays**: same as Daily but skips Saturday and Sunday

448* **Weekly**: shows a time picker and a day picker

449

450For intervals the picker doesn't offer (every 15 minutes, first of each month, etc.), ask Claude in any Desktop session to set the schedule. Use plain language; for example, "schedule a task to run all the tests every 6 hours."

451

452### How scheduled tasks run

453

454Local scheduled tasks run on your machine. Desktop checks the schedule every minute while the app is open and starts a fresh session when a task is due, independent of any manual sessions you have open. Each task gets a fixed delay of up to 10 minutes after the scheduled time to stagger API traffic. The delay is deterministic: the same task always starts at the same offset.

455

456When a task fires, you get a desktop notification and a new session appears under a **Scheduled** section in the sidebar. Open it to see what Claude did, review changes, or respond to permission prompts. The session works like any other: Claude can edit files, run commands, create commits, and open pull requests.

457

458Tasks only run while the desktop app is running and your computer is awake. If your computer sleeps through a scheduled time, the run is skipped. To prevent idle-sleep, enable **Keep computer awake** in Settings under **Desktop app → General**. Closing the laptop lid still puts it to sleep. For tasks that need to run even when your computer is off, use a [remote task](/en/web-scheduled-tasks) instead.

459

460### Missed runs

461

462When the app starts or your computer wakes, Desktop checks whether each task missed any runs in the last seven days. If it did, Desktop starts exactly one catch-up run for the most recently missed time and discards anything older. A daily task that missed six days runs once on wake. Desktop shows a notification when a catch-up run starts.

463

464Keep this in mind when writing prompts. A task scheduled for 9am might run at 11pm if your computer was asleep all day. If timing matters, add guardrails to the prompt itself, for example: "Only review today's commits. If it's after 5pm, skip the review and just post a summary of what was missed."

465

466### Permissions for scheduled tasks

467

468Each task has its own permission mode, which you set when creating or editing the task. Allow rules from `~/.claude/settings.json` also apply to scheduled task sessions. If a task runs in Ask mode and needs to run a tool it doesn't have permission for, the run stalls until you approve it. The session stays open in the sidebar so you can answer later.

469

470To avoid stalls, click **Run now** after creating a task, watch for permission prompts, and select "always allow" for each one. Future runs of that task auto-approve the same tools without prompting. You can review and revoke these approvals from the task's detail page.

471

472### Manage scheduled tasks

473

474Click a task in the **Schedule** list to open its detail page. From here you can:

475

476* **Run now**: start the task immediately without waiting for the next scheduled time

477* **Toggle repeats**: pause or resume scheduled runs without deleting the task

478* **Edit**: change the prompt, frequency, folder, or other settings

479* **Review history**: see every past run, including ones that were skipped because your computer was asleep

480* **Review allowed permissions**: see and revoke saved tool approvals for this task from the **Always allowed** panel

481* **Delete**: remove the task and archive all sessions it created

482

483You can also manage tasks by asking Claude in any Desktop session. For example, "pause my dependency-audit task", "delete the standup-prep task", or "show me my scheduled tasks."

484

485To edit a task's prompt on disk, open `~/.claude/scheduled-tasks/<task-name>/SKILL.md` (or under [`CLAUDE_CONFIG_DIR`](/en/env-vars) if set). The file uses YAML frontmatter for `name` and `description`, with the prompt as the body. Changes take effect on the next run. Schedule, folder, model, and enabled state are not in this file: change them through the Edit form or ask Claude.

164 486

165## Environment configuration487## Environment configuration

166 488

167When starting a session, you choose between **Local** (runs on your machine) or **Remote** (runs on Anthropic's cloud).489The environment you pick when [starting a session](#start-a-session) determines where Claude executes and how you connect:

490

491* **Local**: runs on your machine with direct access to your files

492* **Remote**: runs on Anthropic's cloud infrastructure. Sessions continue even if you close the app.

493* **SSH**: runs on a remote machine you connect to over SSH, such as your own servers, cloud VMs, or dev containers

494

495### Local sessions

496

497Local sessions inherit environment variables from your shell. If you need additional variables, set them in your shell profile, such as `~/.zshrc` or `~/.bashrc`, and restart the desktop app. See [environment variables](/en/env-vars) for the full list of supported variables.

498

499[Extended thinking](/en/common-workflows#use-extended-thinking-thinking-mode) is enabled by default, which improves performance on complex reasoning tasks but uses additional tokens. To disable thinking entirely, set `MAX_THINKING_TOKENS=0` in your shell profile. On Opus, `MAX_THINKING_TOKENS` is ignored except for `0` because adaptive reasoning controls thinking depth instead.

500

501### Remote sessions

502

503Remote sessions continue in the background even if you close the app. Usage counts toward your [subscription plan limits](/en/costs) with no separate compute charges.

504

505You can create custom cloud environments with different network access levels and environment variables. Select the environment dropdown when starting a remote session and choose **Add environment**. See [cloud environments](/en/claude-code-on-the-web#cloud-environment) for details on configuring network access and environment variables.

506

507### SSH sessions

508

509SSH sessions let you run Claude Code on a remote machine while using the desktop app as your interface. This is useful for working with codebases that live on cloud VMs, dev containers, or servers with specific hardware or dependencies.

510

511To add an SSH connection, click the environment dropdown before starting a session and select **+ Add SSH connection**. The dialog asks for:

512

513* **Name**: a friendly label for this connection

514* **SSH Host**: `user@hostname` or a host defined in `~/.ssh/config`

515* **SSH Port**: defaults to 22 if left empty, or uses the port from your SSH config

516* **Identity File**: path to your private key, such as `~/.ssh/id_rsa`. Leave empty to use the default key or your SSH config.

517

518Once added, the connection appears in the environment dropdown. Select it to start a session on that machine. Claude runs on the remote machine with access to its files and tools.

519

520Claude Code must be installed on the remote machine. Once connected, SSH sessions support permission modes, connectors, plugins, and MCP servers.

521

522## Enterprise configuration

523

524Organizations on Teams or Enterprise plans can manage desktop app behavior through admin console controls, managed settings files, and device management policies.

525

526### Admin console controls

527

528These settings are configured through the [admin settings console](https://claude.ai/admin-settings/claude-code):

529

530* **Code in the desktop**: control whether users in your organization can access Claude Code in the desktop app

531* **Code in the web**: enable or disable [web sessions](/en/claude-code-on-the-web) for your organization

532* **Remote Control**: enable or disable [Remote Control](/en/remote-control) for your organization

533* **Disable Bypass permissions mode**: prevent users in your organization from enabling bypass permissions mode

168 534

169**Local sessions** inherit environment variables from your shell. If you need additional variables, set them in your shell profile (`~/.zshrc`, `~/.bashrc`) and restart the desktop app. See [environment variables](/en/settings#environment-variables) for the full list of supported variables.535### Managed settings

170 536

171[Extended thinking](/en/common-workflows#use-extended-thinking-thinking-mode) is enabled by default, which improves performance on complex reasoning tasks but uses additional tokens. The thinking process runs in the background but isn't displayed in the Desktop interface. To disable it or adjust the budget, set `MAX_THINKING_TOKENS` in your shell profile (use `0` to disable).537Managed settings override project and user settings and apply when Desktop spawns CLI sessions. You can set these keys in your organization's [managed settings](/en/settings#settings-precedence) file or push them remotely through the admin console.

172 538

173**Remote sessions** run on Anthropic's cloud infrastructure and continue even if you close the app. Usage counts toward your subscription plan limits with no separate compute charges. See [Claude Code on the web](/en/claude-code-on-the-web) for details on configuring remote environments.539| Key | Description |

540| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

541| `permissions.disableBypassPermissionsMode` | set to `"disable"` to prevent users from enabling Bypass permissions mode. |

542| `disableAutoMode` | set to `"disable"` to prevent users from enabling [Auto](/en/permission-modes#eliminate-prompts-with-auto-mode) mode. Removes Auto from the mode selector. Also accepted under `permissions`. |

543| `autoMode` | customize what the auto mode classifier trusts and blocks across your organization. See [Configure the auto mode classifier](/en/permissions#configure-the-auto-mode-classifier). |

174 544

175## How Desktop relates to CLI545`permissions.disableBypassPermissionsMode` and `disableAutoMode` also work in user and project settings, but placing them in managed settings prevents users from overriding them. `autoMode` is read from user settings, `.claude/settings.local.json`, and managed settings, but not from the checked-in `.claude/settings.json`: a cloned repo cannot inject its own classifier rules. For the complete list of managed-only settings including `allowManagedPermissionRulesOnly` and `allowManagedHooksOnly`, see [managed-only settings](/en/permissions#managed-only-settings).

176 546

177If you already use the Claude Code CLI, Desktop runs the same underlying engine with a graphical interface. You can run both simultaneously on the same machine, even on the same project. Each maintains separate session history, but they share configuration and project memory (CLAUDE.md files).547Remote managed settings uploaded through the admin console currently apply to CLI and IDE sessions only. For Desktop-specific restrictions, use the admin console controls above.

548

549### Device management policies

550

551IT teams can manage the desktop app through MDM on macOS or group policy on Windows. Available policies include enabling or disabling the Claude Code feature, controlling auto-updates, and setting a custom deployment URL.

552

553* **macOS**: configure via `com.anthropic.Claude` preference domain using tools like Jamf or Kandji

554* **Windows**: configure via registry at `SOFTWARE\Policies\Claude`

555

556### Authentication and SSO

557

558Enterprise organizations can require SSO for all users. See [authentication](/en/authentication) for plan-level details and [Setting up SSO](https://support.claude.com/en/articles/13132885-setting-up-single-sign-on-sso) for SAML and OIDC configuration.

559

560### Data handling

561

562Claude Code processes your code locally in local sessions or on Anthropic's cloud infrastructure in remote sessions. Conversations and code context are sent to Anthropic's API for processing. See [data handling](/en/data-usage) for details on data retention, privacy, and compliance.

563

564### Deployment

565

566Desktop can be distributed through enterprise deployment tools:

567

568* **macOS**: distribute via MDM such as Jamf or Kandji using the `.dmg` installer

569* **Windows**: deploy via MSIX package or `.exe` installer. See [Deploy Claude Desktop for Windows](https://support.claude.com/en/articles/12622703-deploy-claude-desktop-for-windows) for enterprise deployment options including silent installation

570

571For network configuration such as proxy settings, firewall allowlisting, and LLM gateways, see [network configuration](/en/network-config).

572

573For the full enterprise configuration reference, see the [enterprise configuration guide](https://support.claude.com/en/articles/12622667-enterprise-configuration).

574

575## Coming from the CLI?

576

577If you already use the Claude Code CLI, Desktop runs the same underlying engine with a graphical interface. You can run both simultaneously on the same machine, even on the same project. Each maintains separate session history, but they share configuration and project memory via CLAUDE.md files.

578

579To move a CLI session into Desktop, run `/desktop` in the terminal. Claude saves your session and opens it in the desktop app, then exits the CLI. This command is available on macOS and Windows only.

580

581<Tip>

582 When to use Desktop vs CLI: use Desktop when you want visual diff review, file attachments, or session management in a sidebar. Use the CLI when you need scripting, automation, third-party providers, or prefer a terminal workflow.

583</Tip>

178 584

179### CLI flag equivalents585### CLI flag equivalents

180 586

181If you're used to CLI flags, the table below shows the Desktop equivalent for each. Some flags have no Desktop equivalent because they're designed for scripting or automation.587This table shows the desktop app equivalent for common CLI flags. Flags not listed have no desktop equivalent because they are designed for scripting or automation.

182 588

183| CLI | Desktop equivalent |589| CLI | Desktop equivalent |

184| ------------------------------------- | ---------------------------------------------- |590| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |

593| `--permission-mode` | Mode selector next to the send button |

594| `--dangerously-skip-permissions` | Bypass permissions mode. Enable in Settings → Claude Code → "Allow bypass permissions mode". Enterprise admins can disable this setting. |

595| `--add-dir` | Add multiple repos with the **+** button in remote sessions |

599| `ANTHROPIC_MODEL` env var | Model dropdown next to the send button |

600| `MAX_THINKING_TOKENS` env var | Set in shell profile; applies to local sessions. See [environment configuration](#environment-configuration). |

190 601

191### Shared configuration602### Shared configuration

192 603

193Desktop and CLI read the same configuration files, so your setup carries over:604Desktop and CLI read the same configuration files, so your setup carries over:

194 605

195* **[CLAUDE.md](/en/memory)** and **CLAUDE.local.md** files in your project are used by both606* **[CLAUDE.md](/en/memory)** files in your project are used by both

196* **[MCP servers](/en/mcp)** configured in `~/.claude.json` or `.mcp.json` work in both607* **[MCP servers](/en/mcp)** configured in `~/.claude.json` or `.mcp.json` work in both

197* **[Hooks](/en/hooks)** and **[skills](/en/skills)** defined in settings apply to both608* **[Hooks](/en/hooks)** and **[skills](/en/skills)** defined in settings apply to both

198* **[Settings](/en/settings)** in `~/.claude.json` and `~/.claude/settings.json` are shared609* **[Settings](/en/settings)** in `~/.claude.json` and `~/.claude/settings.json` are shared. Permission rules, allowed tools, and other settings in `settings.json` apply to Desktop sessions.

199* **Models** (Sonnet, Opus, Haiku) are available in both (Desktop requires selecting before starting a session)610* **Models**: Sonnet, Opus, and Haiku are available in both. In Desktop, select the model from the dropdown next to the send button before starting a session. You cannot change the model during an active session.

200 611

201<Note>612<Note>

202 MCP servers configured for the **Claude Desktop chat app** (in `claude_desktop_config.json`) are separate from Claude Code. To use MCP servers in Claude Code, configure them in `~/.claude.json` or your project's `.mcp.json` file. See [MCP configuration](/en/mcp#configure-mcp-servers) for details.613 **MCP servers: desktop chat app vs Claude Code**: MCP servers configured for the Claude Desktop chat app in `claude_desktop_config.json` are separate from Claude Code and will not appear in the Code tab. To use MCP servers in Claude Code, configure them in `~/.claude.json` or your project's `.mcp.json` file. See [MCP configuration](/en/mcp#installing-mcp-servers) for details.

203</Note>614</Note>

204 615

205### What's different616### Feature comparison

206 617

207**Desktop adds:**618This table compares core capabilities between the CLI and Desktop. For a full list of CLI flags, see the [CLI reference](/en/cli-reference).

208 619

209* Graphical interface with visual session management620| Feature | CLI | Desktop |

210* Built-in connectors for common integrations621| ----------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------- |

211* Automatic session isolation for Git repositories (each session gets its own worktree)622| Permission modes | All modes including `dontAsk` | Ask permissions, Auto accept edits, Plan mode, Auto, and Bypass permissions via Settings |

623| `--dangerously-skip-permissions` | CLI flag | Bypass permissions mode. Enable in Settings → Claude Code → "Allow bypass permissions mode" |

624| [Third-party providers](/en/third-party-integrations) | Bedrock, Vertex, Foundry | Not available. Desktop connects to Anthropic's API directly. |

625| [MCP servers](/en/mcp) | Configure in settings files | Connectors UI for local and SSH sessions, or settings files |

626| [Plugins](/en/plugins) | `/plugin` command | Plugin manager UI |

627| @mention files | Text-based | With autocomplete; local and SSH sessions only |

628| File attachments | Not available | Images, PDFs |

629| Session isolation | [`--worktree`](/en/cli-reference) flag | Automatic worktrees |

630| Multiple sessions | Separate terminals | Sidebar tabs |

631| Recurring tasks | Cron jobs, CI pipelines | [Scheduled tasks](#schedule-recurring-tasks) |

632| Computer use | Not available | [App and screen control](#let-claude-use-your-computer) on macOS |

633| Dispatch integration | Not available | [Dispatch sessions](#sessions-from-dispatch) in the sidebar |

634| Scripting and automation | [`--print`](/en/cli-reference), [Agent SDK](/en/headless) | Not available |

212 635

213**CLI adds:**636### What's not available in Desktop

214 637

215* [Third-party API providers](/en/third-party-integrations) (Bedrock, Vertex, Foundry). If you use these, continue using CLI for those projects.638The following features are only available in the CLI or VS Code extension:

216* [CLI flags](/en/cli-reference) for scripting (`--print`, `--resume`, `--continue`)

217* [Programmatic usage](/en/headless) via the Agent SDK

218 639

219## Troubleshooting640* **Third-party providers**: Desktop connects to Anthropic's API directly. Use the [CLI](/en/quickstart) with Bedrock, Vertex, or Foundry instead.

641* **Linux**: the desktop app is available on macOS and Windows only.

642* **Inline code suggestions**: Desktop does not provide autocomplete-style suggestions. It works through conversational prompts and explicit code changes.

643* **Agent teams**: multi-agent orchestration is available via the [CLI](/en/agent-teams) and [Agent SDK](/en/headless), not in Desktop.

220 644

221Solutions to common issues with the Claude desktop app. For CLI issues, see [CLI troubleshooting](/en/troubleshooting).645## Troubleshooting

222 646

223### Check your version647### Check your version

224 648

225To see which version of the desktop app you're running:649To see which version of the desktop app you're running:

226 650

227* **macOS**: Click **Claude** in the menu bar, then **About Claude**651* **macOS**: click **Claude** in the menu bar, then **About Claude**

228* **Windows**: Click **Help**, then **About**652* **Windows**: click **Help**, then **About**

229 653

230Click the version number to copy it to your clipboard.654Click the version number to copy it to your clipboard.

231 655

232### "Branch doesn't exist yet" when opening in CLI656### 403 or authentication errors in the Code tab

233 657

234Remote sessions can create branches that don't exist on your local machine. Click the branch name in the session toolbar to copy it, then fetch it locally:658If you see `Error 403: Forbidden` or other authentication failures when using the Code tab:

235 659

236```bash theme={null}6601. Sign out and back in from the app menu. This is the most common fix.

237git fetch origin <branch-name>6612. Verify you have an active paid subscription: Pro, Max, Teams, or Enterprise.

238git checkout <branch-name>6623. If the CLI works but Desktop does not, quit the desktop app completely, not just close the window, then reopen and sign in again.

239```6634. Check your internet connection and proxy settings.

240 664

241### "Failed to load session" error665### Blank or stuck screen on launch

242 666

243This error can occur for several reasons:667If the app opens but shows a blank or unresponsive screen:

244 668

245* The selected folder no longer exists or is inaccessible6691. Restart the app.

246* A Git repository requires Git LFS but it's not installed (see [Git LFS errors](#git-lfs-errors))6702. Check for pending updates. The app auto-updates on launch.

247* File permissions prevent access to the project directory6713. On Windows, check Event Viewer for crash logs under **Windows Logs → Application**.

248 672

249Try selecting a different folder or restarting the desktop app.673### "Failed to load session"

250 674

251### App won't quit675If you see `Failed to load session`, the selected folder may no longer exist, a Git repository may require Git LFS that isn't installed, or file permissions may prevent access. Try selecting a different folder or restarting the app.

252 676

253If the desktop app doesn't close properly:677### Session not finding installed tools

254 678

255* **macOS**: Press Cmd+Q. If the app doesn't respond, use Force Quit (Cmd+Option+Esc, select Claude, click Force Quit).679If Claude can't find tools like `npm`, `node`, or other CLI commands, verify the tools work in your regular terminal, check that your shell profile properly sets up PATH, and restart the desktop app to reload environment variables.

256* **Windows**: Use Task Manager (Ctrl+Shift+Esc) to end the Claude process.

257 680

258### Windows installation issues681### Git and Git LFS errors

259 682

260If the installer fails silently or doesn't complete properly:683On Windows, Git is required for the Code tab to start local sessions. If you see "Git is required," install [Git for Windows](https://git-scm.com/downloads/win) and restart the app.

261 684

2621. **PATH not updated**: After installation, open a new terminal window. The PATH updates only apply to new terminal sessions.685If you see "Git LFS is required by this repository but is not installed," install Git LFS from [git-lfs.com](https://git-lfs.com/), run `git lfs install`, and restart the app.

2632. **Concurrent installation error**: If you see an error about another installation in progress but there isn't one, try running the installer as Administrator.

264 686

265### Session not finding installed tools687### MCP servers not working on Windows

266 688

267If Claude can't find tools like `npm`, `node`, or other CLI commands:689If MCP server toggles don't respond or servers fail to connect on Windows, check that the server is properly configured in your settings, restart the app, verify the server process is running in Task Manager, and review server logs for connection errors.

268 690

2691. Verify the tools work in your regular terminal691### App won't quit

2702. Check that your shell profile (`~/.zshrc`, `~/.bashrc`) properly sets up PATH

2713. Restart the desktop app to reload environment variables

272 692

273### MCP servers not working (Windows)693* **macOS**: press Cmd+Q. If the app doesn't respond, use Force Quit with Cmd+Option+Esc, select Claude, and click Force Quit.

694* **Windows**: use Task Manager with Ctrl+Shift+Esc to end the Claude process.

274 695

275If MCP server toggles don't respond or servers fail to connect on Windows:696### Windows-specific issues

276 697

2771. Check that the MCP server is properly configured in your settings698* **PATH not updated after install**: open a new terminal window. PATH updates only apply to new terminal sessions.

2782. Restart the desktop app after making changes699* **Concurrent installation error**: if you see an error about another installation in progress but there isn't one, try running the installer as Administrator.

2793. Verify the MCP server process is running (check Task Manager)700* **ARM64**: Windows ARM64 devices are fully supported.

2804. Review the server logs for connection errors

281 701

282### Git LFS errors702### Cowork tab unavailable on Intel Macs

283 703

284If you see "Git LFS is required by this repository but is not installed," your repository uses Git Large File Storage for large binary files. Install Git LFS before opening this repository:704The Cowork tab requires Apple Silicon (M1 or later) on macOS. On Windows, Cowork is available on all supported hardware. The Chat and Code tabs work normally on Intel Macs.

285 705

2861. Install Git LFS from [git-lfs.com](https://git-lfs.com/)706### "Branch doesn't exist yet" when opening in CLI

2872. Run `git lfs install` in your terminal

2883. Restart the desktop app

289 707

290## Enterprise configuration708Remote sessions can create branches that don't exist on your local machine. Click the branch name in the session toolbar to copy it, then fetch it locally:

709

710```bash theme={null}

711git fetch origin <branch-name>

712git checkout <branch-name>

713```

291 714

292Organizations can disable local Claude Code use in the desktop application with the `isClaudeCodeForDesktopEnabled` [enterprise policy option](https://support.claude.com/en/articles/12622667-enterprise-configuration#h_003283c7cb). Additionally, Claude Code on the web can be disabled in your [admin settings](https://claude.ai/admin-settings/claude-code).715### Still stuck?

293 716

294## Related resources717* Search or file a bug on [GitHub Issues](https://github.com/anthropics/claude-code/issues)

718* Visit the [Claude support center](https://support.claude.com/)

295 719

296* [Claude Code on the web](/en/claude-code-on-the-web): Run remote sessions that continue in the cloud720When filing a bug, include your desktop app version, your operating system, the exact error message, and relevant logs. On macOS, check Console.app. On Windows, check Event Viewer → Windows Logs → Application.

297* [CLI reference](/en/cli-reference): Use Claude Code in your terminal with flags and scripting

298* [Common workflows](/en/common-workflows): Tutorials for debugging, refactoring, testing, and more

299* [Settings reference](/en/settings): Configure Claude Code behavior with settings files

300* [Claude Desktop support](https://support.claude.com/en/collections/16163169-claude-desktop): Help articles for the Chat tab and general desktop app usage

301* [Enterprise configuration](https://support.claude.com/en/articles/12622667-enterprise-configuration): Admin policies for organizational deployments

desktop-quickstart.md +139 −0 added

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# Get started with the desktop app

7> Install Claude Code on desktop and start your first coding session

9The desktop app gives you Claude Code with a graphical interface: visual diff review, live app preview, GitHub PR monitoring with auto-merge, parallel sessions with Git worktree isolation, scheduled tasks, and the ability to run tasks remotely. No terminal required.

11This page walks through installing the app and starting your first session. If you're already set up, see [Use Claude Code Desktop](/en/desktop) for the full reference.

13<Frame>

14 <img src="https://mintcdn.com/claude-code/CNLUpFGiXoc9mhvD/images/desktop-code-tab-light.png?fit=max&auto=format&n=CNLUpFGiXoc9mhvD&q=85&s=9a36a7a27b9f4c6f2e1c83bdb34f69ce" className="block dark:hidden" alt="The Claude Code Desktop interface showing the Code tab selected, with a prompt box, permission mode selector set to Ask permissions, model picker, folder selector, and Local environment option" width="2500" height="1376" data-path="images/desktop-code-tab-light.png" />

16 <img src="https://mintcdn.com/claude-code/CNLUpFGiXoc9mhvD/images/desktop-code-tab-dark.png?fit=max&auto=format&n=CNLUpFGiXoc9mhvD&q=85&s=5463defe81c459fb9b1f91f6a958cfb8" className="hidden dark:block" alt="The Claude Code Desktop interface in dark mode showing the Code tab selected, with a prompt box, permission mode selector set to Ask permissions, model picker, folder selector, and Local environment option" width="2504" height="1374" data-path="images/desktop-code-tab-dark.png" />

17</Frame>

19The desktop app has three tabs:

21* **Chat**: General conversation with no file access, similar to claude.ai.

22* **Cowork**: An autonomous background agent that works on tasks in a cloud VM with its own environment. It can run independently while you do other work.

23* **Code**: An interactive coding assistant with direct access to your local files. You review and approve each change in real time.

25Chat and Cowork are covered in the [Claude Desktop support articles](https://support.claude.com/en/collections/16163169-claude-desktop). This page focuses on the **Code** tab.

27<Note>

28 Claude Code requires a [Pro, Max, Teams, or Enterprise subscription](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=desktop_quickstart_pricing).

29</Note>

31## Install

33<Steps>

34 <Step title="Download the app">

35 Download Claude for your platform.

37 <CardGroup cols={2}>

38 <Card title="macOS" icon="apple" href="https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code&utm_medium=docs">

39 Universal build for Intel and Apple Silicon

40 </Card>

42 <Card title="Windows" icon="windows" href="https://claude.ai/api/desktop/win32/x64/exe/latest/redirect?utm_source=claude_code&utm_medium=docs">

43 For x64 processors

44 </Card>

45 </CardGroup>

47 For Windows ARM64, [download here](https://claude.ai/api/desktop/win32/arm64/exe/latest/redirect?utm_source=claude_code\&utm_medium=docs).

49 Linux is not currently supported.

50 </Step>

52 <Step title="Sign in">

53 Launch Claude from your Applications folder (macOS) or Start menu (Windows). Sign in with your Anthropic account.

54 </Step>

56 <Step title="Open the Code tab">

57 Click the **Code** tab at the top center. If clicking Code prompts you to upgrade, you need to [subscribe to a paid plan](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=desktop_quickstart_upgrade) first. If it prompts you to sign in online, complete the sign-in and restart the app. If you see a 403 error, see [authentication troubleshooting](/en/desktop#403-or-authentication-errors-in-the-code-tab).

58 </Step>

59</Steps>

61The desktop app includes Claude Code. You don't need to install Node.js or the CLI separately. To use `claude` from the terminal, install the CLI separately. See [Get started with the CLI](/en/quickstart).

63## Start your first session

65With the Code tab open, choose a project and give Claude something to do.

67<Steps>

68 <Step title="Choose an environment and folder">

69 Select **Local** to run Claude on your machine using your files directly. Click **Select folder** and choose your project directory.

71 <Tip>

72 Start with a small project you know well. It's the fastest way to see what Claude Code can do. On Windows, [Git](https://git-scm.com/downloads/win) must be installed for local sessions to work. Most Macs include Git by default.

73 </Tip>

75 You can also select:

77 * **Remote**: Run sessions on Anthropic's cloud infrastructure that continue even if you close the app. Remote sessions use the same infrastructure as [Claude Code on the web](/en/claude-code-on-the-web).

78 * **SSH**: Connect to a remote machine over SSH (your own servers, cloud VMs, or dev containers). Claude Code must be installed on the remote machine.

79 </Step>

81 <Step title="Choose a model">

82 Select a model from the dropdown next to the send button. See [models](/en/model-config#available-models) for a comparison of Opus, Sonnet, and Haiku. You cannot change the model after the session starts.

83 </Step>

85 <Step title="Tell Claude what to do">

86 Type what you want Claude to do:

88 * `Find a TODO comment and fix it`

89 * `Add tests for the main function`

90 * `Create a CLAUDE.md with instructions for this codebase`

92 A [session](/en/desktop#work-in-parallel-with-sessions) is a conversation with Claude about your code. Each session tracks its own context and changes, so you can work on multiple tasks without them interfering with each other.

93 </Step>

95 <Step title="Review and accept changes">

96 By default, the Code tab starts in [Ask permissions mode](/en/desktop#choose-a-permission-mode), where Claude proposes changes and waits for your approval before applying them. You'll see:

98 1. A [diff view](/en/desktop#review-changes-with-diff-view) showing exactly what will change in each file

99 2. Accept/Reject buttons to approve or decline each change

100 3. Real-time updates as Claude works through your request

101

102 If you reject a change, Claude will ask how you'd like to proceed differently. Your files aren't modified until you accept.

103 </Step>

104</Steps>

105

106## Now what?

107

108You've made your first edit. For the full reference on everything Desktop can do, see [Use Claude Code Desktop](/en/desktop). Here are some things to try next.

109

110**Interrupt and steer.** You can interrupt Claude at any point. If it's going down the wrong path, click the stop button or type your correction and press **Enter**. Claude stops what it's doing and adjusts based on your input. You don't have to wait for it to finish or start over.

111

112**Give Claude more context.** Type `@filename` in the prompt box to pull a specific file into the conversation, attach images and PDFs using the attachment button, or drag and drop files directly into the prompt. The more context Claude has, the better the results. See [Add files and context](/en/desktop#add-files-and-context-to-prompts).

113

114**Use skills for repeatable tasks.** Type `/` or click **+** → **Slash commands** to browse [built-in commands](/en/commands), [custom skills](/en/skills), and plugin skills. Skills are reusable prompts you can invoke whenever you need them, like code review checklists or deployment steps.

115

116**Review changes before committing.** After Claude edits files, a `+12 -1` indicator appears. Click it to open the [diff view](/en/desktop#review-changes-with-diff-view), review modifications file by file, and comment on specific lines. Claude reads your comments and revises. Click **Review code** to have Claude evaluate the diffs itself and leave inline suggestions.

117

118**Adjust how much control you have.** Your [permission mode](/en/desktop#choose-a-permission-mode) controls the balance. Ask permissions (default) requires approval before every edit. Auto accept edits auto-accepts file edits for faster iteration. Plan mode lets Claude map out an approach without touching any files, which is useful before a large refactor.

119

120**Add plugins for more capabilities.** Click the **+** button next to the prompt box and select **Plugins** to browse and install [plugins](/en/desktop#install-plugins) that add skills, agents, MCP servers, and more.

121

122**Preview your app.** Click the **Preview** dropdown to run your dev server directly in the desktop. Claude can view the running app, test endpoints, inspect logs, and iterate on what it sees. See [Preview your app](/en/desktop#preview-your-app).

123

124**Track your pull request.** After opening a PR, Claude Code monitors CI check results and can automatically fix failures or merge the PR once all checks pass. See [Monitor pull request status](/en/desktop#monitor-pull-request-status).

125

126**Put Claude on a schedule.** Set up [scheduled tasks](/en/desktop#schedule-recurring-tasks) to run Claude automatically on a recurring basis: a daily code review every morning, a weekly dependency audit, or a briefing that pulls from your connected tools.

127

128**Scale up when you're ready.** Open [parallel sessions](/en/desktop#work-in-parallel-with-sessions) from the sidebar to work on multiple tasks at once, each in its own Git worktree. Send [long-running work to the cloud](/en/desktop#run-long-running-tasks-remotely) so it continues even if you close the app, or [continue a session on the web or in your IDE](/en/desktop#continue-in-another-surface) if a task takes longer than expected. [Connect external tools](/en/desktop#extend-claude-code) like GitHub, Slack, and Linear to bring your workflow together.

129

130## Coming from the CLI?

131

132Desktop runs the same engine as the CLI with a graphical interface. You can run both simultaneously on the same project, and they share configuration (CLAUDE.md files, MCP servers, hooks, skills, and settings). For a full comparison of features, flag equivalents, and what's not available in Desktop, see [CLI comparison](/en/desktop#coming-from-the-cli).

133

134## What's next

135

136* [Use Claude Code Desktop](/en/desktop): permission modes, parallel sessions, diff view, connectors, and enterprise configuration

137* [Troubleshooting](/en/desktop#troubleshooting): solutions to common errors and setup issues

138* [Best practices](/en/best-practices): tips for writing effective prompts and getting the most out of Claude Code

139* [Common workflows](/en/common-workflows): tutorials for debugging, refactoring, testing, and more

discover-plugins.md +40 −6

Details

28 28

29## Official Anthropic marketplace29## Official Anthropic marketplace

30 30

~~31The official Anthropic marketplace (`claude-plugins-official`) is automatically available when you start Claude Code. Run `/plugin` and go to the **Discover** tab to browse what's available.~~31The official Anthropic marketplace (`claude-plugins-official`) is automatically available when you start Claude Code. Run `/plugin` and go to the **Discover** tab to browse what's available, or view the catalog at [claude.com/plugins](https://claude.com/plugins).

32 32

~~33To install a plugin from the official marketplace:~~33To install a plugin from the official marketplace, use `/plugin install <name>@claude-plugins-official`. For example, to install the GitHub integration:

34 34

35```shell theme={null}35```shell theme={null}

~~36/plugin install plugin-name@claude-plugins-official~~36/plugin install github@claude-plugins-official

37```37```

38 38

39<Note>39<Note>

~~40 The official marketplace is maintained by Anthropic. To distribute your own plugins, [create your own marketplace](/en/plugin-marketplaces) and share it with users.~~40 The official marketplace is maintained by Anthropic. To submit a plugin to the official marketplace, use one of the in-app submission forms:

42 * **Claude.ai**: [claude.ai/settings/plugins/submit](https://claude.ai/settings/plugins/submit)

43 * **Console**: [platform.claude.com/plugins/submit](https://platform.claude.com/plugins/submit)

45 To distribute plugins independently, [create your own marketplace](/en/plugin-marketplaces) and share it with users.

41</Note>46</Note>

42 47

43The official marketplace includes several categories of plugins:48The official marketplace includes several categories of plugins:

149 </Step>154 </Step>

150 155

151 <Step title="Use your new plugin">156 <Step title="Use your new plugin">

152 After installing, the plugin's commands are immediately available. Plugin commands are namespaced by the plugin name, so **commit-commands** provides commands like `/commit-commands:commit`.157 After installing, run `/reload-plugins` to activate the plugin. Plugin commands are namespaced by the plugin name, so **commit-commands** provides commands like `/commit-commands:commit`.

153 158

154 Try it out by making a change to a file and running:159 Try it out by making a change to a file and running:

155 160

289claude plugin uninstall formatter@your-org --scope project294claude plugin uninstall formatter@your-org --scope project

290```295```

291 296

297### Apply plugin changes without restarting

298

299When you install, enable, or disable plugins during a session, run `/reload-plugins` to pick up all changes without restarting:

300

301```shell theme={null}

302/reload-plugins

303```

304

305Claude Code reloads all active plugins and shows counts for plugins, skills, agents, hooks, plugin MCP servers, and plugin LSP servers.

306

292## Manage marketplaces307## Manage marketplaces

293 308

294You can manage marketplaces through the interactive `/plugin` interface or with CLI commands.309You can manage marketplaces through the interactive `/plugin` interface or with CLI commands.

330 345

331### Configure auto-updates346### Configure auto-updates

332 347

333Claude Code can automatically update marketplaces and their installed plugins at startup. When auto-update is enabled for a marketplace, Claude Code refreshes the marketplace data and updates installed plugins to their latest versions. If any plugins were updated, you'll see a notification suggesting you restart Claude Code.348Claude Code can automatically update marketplaces and their installed plugins at startup. When auto-update is enabled for a marketplace, Claude Code refreshes the marketplace data and updates installed plugins to their latest versions. If any plugins were updated, you'll see a notification prompting you to run `/reload-plugins`.

334 349

335Toggle auto-update for individual marketplaces through the UI:350Toggle auto-update for individual marketplaces through the UI:

336 351

356 371

357Team admins can set up automatic marketplace installation for projects by adding marketplace configuration to `.claude/settings.json`. When team members trust the repository folder, Claude Code prompts them to install these marketplaces and plugins.372Team admins can set up automatic marketplace installation for projects by adding marketplace configuration to `.claude/settings.json`. When team members trust the repository folder, Claude Code prompts them to install these marketplaces and plugins.

358 373

374Add `extraKnownMarketplaces` to your project's `.claude/settings.json`:

375

376```json theme={null}

377{

378 "extraKnownMarketplaces": {

379 "my-team-tools": {

380 "source": {

381 "source": "github",

382 "repo": "your-org/claude-plugins"

383 }

384 }

385 }

386}

387```

388

359For full configuration options including `extraKnownMarketplaces` and `enabledPlugins`, see [Plugin settings](/en/settings#plugin-settings).389For full configuration options including `extraKnownMarketplaces` and `enabledPlugins`, see [Plugin settings](/en/settings#plugin-settings).

360 390

391## Security

392

393Plugins and marketplaces are highly trusted components that can execute arbitrary code on your machine with your user privileges. Only install plugins and add marketplaces from sources you trust. Organizations can restrict which marketplaces users are allowed to add using [managed marketplace restrictions](/en/plugin-marketplaces#managed-marketplace-restrictions).

394

361## Troubleshooting395## Troubleshooting

362 396

363### /plugin command not recognized397### /plugin command not recognized

env-vars.md +136 −0 added

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# Environment variables

7> Complete reference for environment variables that control Claude Code behavior.

9Claude Code supports the following environment variables to control its behavior. Set them in your shell before launching `claude`, or configure them in [`settings.json`](/en/settings#available-settings) under the `env` key to apply them to every session or roll them out across your team.

11| Variable | Purpose |

12| :------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

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

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

15| `ANTHROPIC_BASE_URL` | Override the API endpoint to route requests through a proxy or gateway. When set to a non-first-party host, [MCP tool search](/en/mcp#scale-with-mcp-tool-search) is disabled by default. Set `ENABLE_TOOL_SEARCH=true` if your proxy forwards `tool_reference` blocks |

16| `ANTHROPIC_CUSTOM_HEADERS` | Custom headers to add to requests (`Name: Value` format, newline-separated for multiple headers) |

17| `ANTHROPIC_CUSTOM_MODEL_OPTION` | Model ID to add as a custom entry in the `/model` picker. Use this to make a non-standard or gateway-specific model selectable without replacing built-in aliases. See [Model configuration](/en/model-config#add-a-custom-model-option) |

18| `ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION` | Display description for the custom model entry in the `/model` picker. Defaults to `Custom model (<model-id>)` when not set |

19| `ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` | Display name for the custom model entry in the `/model` picker. Defaults to the model ID when not set |

20| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | See [Model configuration](/en/model-config#environment-variables) |

21| `ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION` | See [Model configuration](/en/model-config#customize-pinned-model-display-and-capabilities) |

22| `ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME` | See [Model configuration](/en/model-config#customize-pinned-model-display-and-capabilities) |

23| `ANTHROPIC_DEFAULT_HAIKU_MODEL_SUPPORTED_CAPABILITIES` | See [Model configuration](/en/model-config#customize-pinned-model-display-and-capabilities) |

24| `ANTHROPIC_DEFAULT_OPUS_MODEL` | See [Model configuration](/en/model-config#environment-variables) |

25| `ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION` | See [Model configuration](/en/model-config#customize-pinned-model-display-and-capabilities) |

26| `ANTHROPIC_DEFAULT_OPUS_MODEL_NAME` | See [Model configuration](/en/model-config#customize-pinned-model-display-and-capabilities) |

27| `ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES` | See [Model configuration](/en/model-config#customize-pinned-model-display-and-capabilities) |

28| `ANTHROPIC_DEFAULT_SONNET_MODEL` | See [Model configuration](/en/model-config#environment-variables) |

29| `ANTHROPIC_DEFAULT_SONNET_MODEL_DESCRIPTION` | See [Model configuration](/en/model-config#customize-pinned-model-display-and-capabilities) |

30| `ANTHROPIC_DEFAULT_SONNET_MODEL_NAME` | See [Model configuration](/en/model-config#customize-pinned-model-display-and-capabilities) |

31| `ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES` | See [Model configuration](/en/model-config#customize-pinned-model-display-and-capabilities) |

32| `ANTHROPIC_FOUNDRY_API_KEY` | API key for Microsoft Foundry authentication (see [Microsoft Foundry](/en/microsoft-foundry)) |

33| `ANTHROPIC_FOUNDRY_BASE_URL` | Full base URL for the Foundry resource (for example, `https://my-resource.services.ai.azure.com/anthropic`). Alternative to `ANTHROPIC_FOUNDRY_RESOURCE` (see [Microsoft Foundry](/en/microsoft-foundry)) |

34| `ANTHROPIC_FOUNDRY_RESOURCE` | Foundry resource name (for example, `my-resource`). Required if `ANTHROPIC_FOUNDRY_BASE_URL` is not set (see [Microsoft Foundry](/en/microsoft-foundry)) |

35| `ANTHROPIC_MODEL` | Name of the model setting to use (see [Model Configuration](/en/model-config#environment-variables)) |

36| `ANTHROPIC_SMALL_FAST_MODEL` | \[DEPRECATED] Name of [Haiku-class model for background tasks](/en/costs) |

37| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | Override AWS region for the Haiku-class model when using Bedrock |

38| `AWS_BEARER_TOKEN_BEDROCK` | Bedrock API key for authentication (see [Bedrock API keys](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)) |

39| `BASH_DEFAULT_TIMEOUT_MS` | Default timeout for long-running bash commands |

40| `BASH_MAX_OUTPUT_LENGTH` | Maximum number of characters in bash outputs before they are middle-truncated |

41| `BASH_MAX_TIMEOUT_MS` | Maximum timeout the model can set for long-running bash commands |

42| `CLAUDECODE` | Set to `1` in shell environments Claude Code spawns (Bash tool, tmux sessions). Not set in [hooks](/en/hooks) or [status line](/en/statusline) commands. Use to detect when a script is running inside a shell spawned by Claude Code |

43| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | Set the percentage of context capacity (1-100) at which auto-compaction triggers. By default, auto-compaction triggers at approximately 95% capacity. Use lower values like `50` to compact earlier. Values above the default threshold have no effect. Applies to both main conversations and subagents. This percentage aligns with the `context_window.used_percentage` field available in [status line](/en/statusline) |

44| `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR` | Return to the original working directory after each Bash command |

45| `CLAUDE_CODE_ACCOUNT_UUID` | Account UUID for the authenticated user. Used by SDK callers to provide account information synchronously, avoiding a race condition where early telemetry events lack account metadata. Requires `CLAUDE_CODE_USER_EMAIL` and `CLAUDE_CODE_ORGANIZATION_UUID` to also be set |

46| `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` | Set to `1` to load CLAUDE.md files from directories specified with `--add-dir`. By default, additional directories do not load memory files |

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

48| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` | Interval in milliseconds at which credentials should be refreshed (when using [`apiKeyHelper`](/en/settings#available-settings)) |

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

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

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

52| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | Set to `1` to disable [1M context window](/en/model-config#extended-context) support. When set, 1M model variants are unavailable in the model picker. Useful for enterprise environments with compliance requirements |

53| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | Set to `1` to disable [adaptive reasoning](/en/model-config#adjust-effort-level) for Opus 4.6 and Sonnet 4.6. When disabled, these models fall back to the fixed thinking budget controlled by `MAX_THINKING_TOKENS` |

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

55| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | Set to `1` to remove built-in commit and PR workflow instructions and the git status snapshot from Claude's system prompt. Useful when using your own git workflow skills. Takes precedence over the [`includeGitInstructions`](/en/settings#available-settings) setting when set |

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

57| `CLAUDE_CODE_DISABLE_CRON` | Set to `1` to disable [scheduled tasks](/en/scheduled-tasks). The `/loop` skill and cron tools become unavailable and any already-scheduled tasks stop firing, including tasks that are already running mid-session |

58| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Set to `1` to strip Anthropic-specific `anthropic-beta` request headers and beta tool-schema fields (such as `defer_loading` and `eager_input_streaming`) from API requests. Use this when a proxy gateway rejects requests with errors like "Unexpected value(s) for the `anthropic-beta` header" or "Extra inputs are not permitted". Standard fields (`name`, `description`, `input_schema`, `cache_control`) are preserved. |

59| `CLAUDE_CODE_DISABLE_FAST_MODE` | Set to `1` to disable [fast mode](/en/fast-mode) |

60| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | Set to `1` to disable the "How is Claude doing?" session quality surveys. Surveys are also disabled when `DISABLE_TELEMETRY` or `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` is set. See [Session quality surveys](/en/data-usage#session-quality-surveys) |

61| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | Equivalent of setting `DISABLE_AUTOUPDATER`, `DISABLE_FEEDBACK_COMMAND`, `DISABLE_ERROR_REPORTING`, and `DISABLE_TELEMETRY` |

62| `CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK` | Set to `1` to disable the non-streaming fallback when a streaming request fails mid-stream. Streaming errors propagate to the retry layer instead. Useful when a proxy or gateway causes the fallback to produce duplicate tool execution |

63| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | Set to `1` to disable automatic terminal title updates based on conversation context |

64| `CLAUDE_CODE_EFFORT_LEVEL` | Set the effort level for supported models. Values: `low`, `medium`, `high`, `max` (Opus 4.6 only), or `auto` to use the model default. Takes precedence over `/effort` and the `effortLevel` setting. See [Adjust effort level](/en/model-config#adjust-effort-level) |

65| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | Set to `false` to disable prompt suggestions (the "Prompt suggestions" toggle in `/config`). These are the grayed-out predictions that appear in your prompt input after Claude responds. See [Prompt suggestions](/en/interactive-mode#prompt-suggestions) |

66| `CLAUDE_CODE_ENABLE_TASKS` | Set to `true` to enable the task tracking system in non-interactive mode (the `-p` flag). Tasks are on by default in interactive mode. See [Task list](/en/interactive-mode#task-list) |

67| `CLAUDE_CODE_ENABLE_TELEMETRY` | Set to `1` to enable OpenTelemetry data collection for metrics and logging. Required before configuring OTel exporters. See [Monitoring](/en/monitoring-usage) |

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

69| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | Set to `1` to enable [agent teams](/en/agent-teams). Agent teams are experimental and disabled by default |

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

71| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | Skip auto-installation of IDE extensions. Equivalent to setting [`autoInstallIdeExtension`](/en/settings#global-config-settings) to `false` |

72| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | Set the maximum number of output tokens for most requests. Defaults and caps vary by model; see [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison). Increasing this value reduces the effective context window available before [auto-compaction](/en/costs#reduce-token-usage) triggers. |

73| `CLAUDE_CODE_NEW_INIT` | Set to `true` to make `/init` run an interactive setup flow. The flow asks which files to generate, including CLAUDE.md, skills, and hooks, before exploring the codebase and writing them. Without this variable, `/init` generates a CLAUDE.md automatically without prompting. |

74| `CLAUDE_CODE_ORGANIZATION_UUID` | Organization UUID for the authenticated user. Used by SDK callers to provide account information synchronously. Requires `CLAUDE_CODE_ACCOUNT_UUID` and `CLAUDE_CODE_USER_EMAIL` to also be set |

75| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | Interval for refreshing dynamic OpenTelemetry headers in milliseconds (default: 1740000 / 29 minutes). See [Dynamic headers](/en/monitoring-usage#dynamic-headers) |

76| `CLAUDE_CODE_PLAN_MODE_REQUIRED` | Auto-set to `true` on [agent team](/en/agent-teams) teammates that require plan approval. Read-only: set by Claude Code when spawning teammates. See [require plan approval](/en/agent-teams#require-plan-approval-for-teammates) |

77| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | Timeout in milliseconds for git operations when installing or updating plugins (default: 120000). Increase this value for large repositories or slow network connections. See [Git operations time out](/en/plugin-marketplaces#git-operations-time-out) |

78| `CLAUDE_CODE_PLUGIN_SEED_DIR` | Path to one or more read-only plugin seed directories, separated by `:` on Unix or `;` on Windows. Use this to bundle a pre-populated plugins directory into a container image. Claude Code registers marketplaces from these directories at startup and uses pre-cached plugins without re-cloning. See [Pre-populate plugins for containers](/en/plugin-marketplaces#pre-populate-plugins-for-containers) |

79| `CLAUDE_CODE_PROXY_RESOLVES_HOSTS` | Set to `true` to allow the proxy to perform DNS resolution instead of the caller. Opt-in for environments where the proxy should handle hostname resolution |

80| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | Maximum time in milliseconds for [SessionEnd](/en/hooks#sessionend) hooks to complete (default: `1500`). Applies to session exit, `/clear`, and switching sessions via interactive `/resume`. Per-hook `timeout` values are also capped by this budget |

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

82| `CLAUDE_CODE_SHELL_PREFIX` | Command prefix to wrap all bash commands (for example, for logging or auditing). Example: `/path/to/logger.sh` will execute `/path/to/logger.sh <command>` |

83| `CLAUDE_CODE_SIMPLE` | Set to `1` to run with a minimal system prompt and only the Bash, file read, and file edit tools. MCP tools from `--mcp-config` are still available. Disables auto-discovery of hooks, skills, plugins, MCP servers, auto memory, and CLAUDE.md. The [`--bare`](/en/headless#start-faster-with-bare-mode) CLI flag sets this |

84| `CLAUDE_CODE_SKIP_BEDROCK_AUTH` | Skip AWS authentication for Bedrock (for example, when using an LLM gateway) |

85| `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS` | Set to `1` to allow [fast mode](/en/fast-mode) when the organization status check fails due to a network error. Useful when a corporate proxy blocks the status endpoint. The API still enforces organization-level disable separately |

86| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | Skip Azure authentication for Microsoft Foundry (for example, when using an LLM gateway) |

87| `CLAUDE_CODE_SKIP_VERTEX_AUTH` | Skip Google authentication for Vertex (for example, when using an LLM gateway) |

88| `CLAUDE_CODE_SUBAGENT_MODEL` | See [Model configuration](/en/model-config) |

89| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | Set to `1` to strip Anthropic and cloud provider credentials from subprocess environments (Bash tool, hooks, MCP stdio servers). The parent Claude process keeps these credentials for API calls, but child processes cannot read them, reducing exposure to prompt injection attacks that attempt to exfiltrate secrets via shell expansion. `claude-code-action` sets this automatically when `allowed_non_write_users` is configured |

90| `CLAUDE_CODE_TASK_LIST_ID` | Share a task list across sessions. Set the same ID in multiple Claude Code instances to coordinate on a shared task list. See [Task list](/en/interactive-mode#task-list) |

91| `CLAUDE_CODE_TEAM_NAME` | Name of the agent team this teammate belongs to. Set automatically on [agent team](/en/agent-teams) members |

92| `CLAUDE_CODE_TMPDIR` | Override the temp directory used for internal temp files. Claude Code appends `/claude/` to this path. Default: `/tmp` on Unix/macOS, `os.tmpdir()` on Windows |

93| `CLAUDE_CODE_USER_EMAIL` | Email address for the authenticated user. Used by SDK callers to provide account information synchronously. Requires `CLAUDE_CODE_ACCOUNT_UUID` and `CLAUDE_CODE_ORGANIZATION_UUID` to also be set |

94| `CLAUDE_CODE_USE_BEDROCK` | Use [Bedrock](/en/amazon-bedrock) |

95| `CLAUDE_CODE_USE_FOUNDRY` | Use [Microsoft Foundry](/en/microsoft-foundry) |

96| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | Set to `1` to enable the PowerShell tool on Windows (opt-in preview). When enabled, Claude can run PowerShell commands natively instead of routing through Git Bash. Only supported on native Windows, not WSL. See [PowerShell tool](/en/tools-reference#powershell-tool) |

97| `CLAUDE_CODE_USE_VERTEX` | Use [Vertex](/en/google-vertex-ai) |

98| `CLAUDE_CONFIG_DIR` | Customize where Claude Code stores its configuration and data files |

99| `CLAUDE_ENV_FILE` | Path to a shell script that Claude Code sources before each Bash command. Use to persist virtualenv or conda activation across commands. Also populated dynamically by [SessionStart](/en/hooks#persist-environment-variables), [CwdChanged](/en/hooks#cwdchanged), and [FileChanged](/en/hooks#filechanged) hooks |

100| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | Timeout in milliseconds before the streaming idle watchdog closes a stalled connection. Default: `90000` (90 seconds). Increase this value if long-running tools or slow networks cause premature timeout errors |

101| `DISABLE_AUTOUPDATER` | Set to `1` to disable automatic updates. |

102| `DISABLE_COST_WARNINGS` | Set to `1` to disable cost warning messages |

103| `DISABLE_ERROR_REPORTING` | Set to `1` to opt out of Sentry error reporting |

104| `DISABLE_FEEDBACK_COMMAND` | Set to `1` to disable the `/feedback` command. The older name `DISABLE_BUG_COMMAND` is also accepted |

105| `DISABLE_INSTALLATION_CHECKS` | Set to `1` to disable installation warnings. Use only when manually managing the installation location, as this can mask issues with standard installations |

106| `DISABLE_PROMPT_CACHING` | Set to `1` to disable prompt caching for all models (takes precedence over per-model settings) |

107| `DISABLE_PROMPT_CACHING_HAIKU` | Set to `1` to disable prompt caching for Haiku models |

108| `DISABLE_PROMPT_CACHING_OPUS` | Set to `1` to disable prompt caching for Opus models |

109| `DISABLE_PROMPT_CACHING_SONNET` | Set to `1` to disable prompt caching for Sonnet models |

110| `DISABLE_TELEMETRY` | Set to `1` to opt out of Statsig telemetry (note that Statsig events do not include user data like code, file paths, or bash commands) |

111| `ENABLE_CLAUDEAI_MCP_SERVERS` | Set to `false` to disable [claude.ai MCP servers](/en/mcp#use-mcp-servers-from-claude-ai) in Claude Code. Enabled by default for logged-in users |

112| `ENABLE_TOOL_SEARCH` | Controls [MCP tool search](/en/mcp#scale-with-mcp-tool-search). Unset: all MCP tools deferred by default, but loaded upfront when `ANTHROPIC_BASE_URL` points to a non-first-party host. Values: `true` (always defer including proxies), `auto` (threshold mode: load upfront if tools fit within 10% of context), `auto:N` (custom threshold, e.g., `auto:5` for 5%), `false` (load all upfront) |

113| `FORCE_AUTOUPDATE_PLUGINS` | Set to `true` to force plugin auto-updates even when the main auto-updater is disabled via `DISABLE_AUTOUPDATER` |

114| `HTTP_PROXY` | Specify HTTP proxy server for network connections |

115| `HTTPS_PROXY` | Specify HTTPS proxy server for network connections |

116| `IS_DEMO` | Set to `true` to enable demo mode: hides email and organization from the UI, skips onboarding, and hides internal commands. Useful for streaming or recording sessions |

117| `MAX_MCP_OUTPUT_TOKENS` | Maximum number of tokens allowed in MCP tool responses. Claude Code displays a warning when output exceeds 10,000 tokens (default: 25000) |

118| `MAX_THINKING_TOKENS` | Override the [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) token budget. The ceiling is the model's [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison) minus one. Set to `0` to disable thinking entirely. On models with adaptive reasoning (Opus 4.6, Sonnet 4.6), the budget is ignored unless adaptive reasoning is disabled via `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` |

119| `MCP_CLIENT_SECRET` | OAuth client secret for MCP servers that require [pre-configured credentials](/en/mcp#use-pre-configured-oauth-credentials). Avoids the interactive prompt when adding a server with `--client-secret` |

120| `MCP_OAUTH_CALLBACK_PORT` | Fixed port for the OAuth redirect callback, as an alternative to `--callback-port` when adding an MCP server with [pre-configured credentials](/en/mcp#use-pre-configured-oauth-credentials) |

121| `MCP_TIMEOUT` | Timeout in milliseconds for MCP server startup |

122| `MCP_TOOL_TIMEOUT` | Timeout in milliseconds for MCP tool execution |

123| `NO_PROXY` | List of domains and IPs to which requests will be directly issued, bypassing proxy |

124| `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 1% of the context window, with a fallback of 8,000 characters. Legacy name kept for backwards compatibility |

125| `USE_BUILTIN_RIPGREP` | Set to `0` to use system-installed `rg` instead of `rg` included with Claude Code |

126| `VERTEX_REGION_CLAUDE_3_5_HAIKU` | Override region for Claude 3.5 Haiku when using Vertex AI |

127| `VERTEX_REGION_CLAUDE_3_7_SONNET` | Override region for Claude 3.7 Sonnet when using Vertex AI |

128| `VERTEX_REGION_CLAUDE_4_0_OPUS` | Override region for Claude 4.0 Opus when using Vertex AI |

129| `VERTEX_REGION_CLAUDE_4_0_SONNET` | Override region for Claude 4.0 Sonnet when using Vertex AI |

130| `VERTEX_REGION_CLAUDE_4_1_OPUS` | Override region for Claude 4.1 Opus when using Vertex AI |

131

132## See also

133

134* [Settings](/en/settings): configure environment variables in `settings.json` so they apply to every session

135* [CLI reference](/en/cli-reference): launch-time flags

136* [Network configuration](/en/network-config): proxy and TLS setup

fast-mode.md +150 −0 added

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 is a high-speed configuration for Claude Opus 4.6, making the model 2.5x faster 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.

17<Note>

18 Fast mode requires Claude Code v2.1.36 or later. Check your version with `claude --version`.

19</Note>

21What to know:

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

24* Fast mode for Opus 4.6 pricing is \$30/150 MTok.

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

26* 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.

28This 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), [per-session opt-in](#require-per-session-opt-in), and [rate limit behavior](#handle-rate-limits).

30## Toggle fast mode

32Toggle fast mode in either of these ways:

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

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

37By default, fast mode persists across sessions. Administrators can configure fast mode to reset each session. See [require per-session opt-in](#require-per-session-opt-in) for details.

39For 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.

41When you enable fast mode:

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

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

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

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

48When 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`.

50## Understand the cost tradeoff

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

54| Mode | Input (MTok) | Output (MTok) |

55| --------------------- | ------------ | ------------- |

56| Fast mode on Opus 4.6 | \$30 | \$150 |

58Fast mode pricing is flat across the full 1M token context window.

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

62## Decide when to use fast mode

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

66* Rapid iteration on code changes

67* Live debugging sessions

68* Time-sensitive work with tight deadlines

70Standard mode is better for:

72* Long autonomous tasks where speed matters less

73* Batch processing or CI/CD pipelines

74* Cost-sensitive workloads

76### Fast mode vs effort level

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

80| Setting | Effect |

81| ---------------------- | -------------------------------------------------------------------------------- |

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

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

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

87## Requirements

89Fast mode requires all of the following:

91* **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.

92* **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.

94<Note>

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

96</Note>

98* **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.

100<Note>

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

102</Note>

103

104### Enable fast mode for your organization

105

106Admins can enable fast mode in:

107

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

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

110

111Another option to disable fast mode entirely is to set `CLAUDE_CODE_DISABLE_FAST_MODE=1`. See [Environment variables](/en/env-vars).

112

113### Require per-session opt-in

114

115By default, fast mode persists across sessions: if a user enables fast mode, it stays on in future sessions. Administrators on [Teams](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_teams#team-&-enterprise) or [Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_enterprise) plans can prevent this by setting `fastModePerSessionOptIn` to `true` in [managed settings](/en/settings#settings-files) or [server-managed settings](/en/server-managed-settings). This causes each session to start with fast mode off, requiring users to explicitly enable it with `/fast`.

116

117```json theme={null}

118{

119 "fastModePerSessionOptIn": true

120}

121```

122

123This is useful for controlling costs in organizations where users run multiple concurrent sessions. Users can still enable fast mode with `/fast` when they need speed, but it resets at the start of each new session. The user's fast mode preference is still saved, so removing this setting restores the default persistent behavior.

124

125## Handle rate limits

126

127Fast 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:

128

1291. Fast mode automatically falls back to standard Opus 4.6

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

1313. You continue working at standard speed and pricing

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

133

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

135

136## Research preview

137

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

139

140* The feature may change based on feedback

141* Availability and pricing are subject to change

142* The underlying API configuration may evolve

143

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

145

146## See also

147

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

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

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

features-overview.md +61 −14

Details

22* **[Skills](/en/skills)** add reusable knowledge and invocable workflows22* **[Skills](/en/skills)** add reusable knowledge and invocable workflows

23* **[MCP](/en/mcp)** connects Claude to external services and tools23* **[MCP](/en/mcp)** connects Claude to external services and tools

24* **[Subagents](/en/sub-agents)** run their own loops in isolated context, returning summaries24* **[Subagents](/en/sub-agents)** run their own loops in isolated context, returning summaries

25* **[Agent teams](/en/agent-teams)** coordinate multiple independent sessions with shared tasks and peer-to-peer messaging

25* **[Hooks](/en/hooks)** run outside the loop entirely as deterministic scripts26* **[Hooks](/en/hooks)** run outside the loop entirely as deterministic scripts

26* **[Plugins](/en/plugins)** and **[marketplaces](/en/plugin-marketplaces)** package and distribute these features27* **[Plugins](/en/plugins)** and **[marketplaces](/en/plugin-marketplaces)** package and distribute these features

27 28

28[Skills](/en/skills) are the most flexible extension. A skill is a markdown file containing knowledge, workflows, or instructions. You can invoke skills with a slash command like `/deploy`, or Claude can load them automatically when relevant. Skills can run in your current conversation or in an isolated context via subagents.29[Skills](/en/skills) are the most flexible extension. A skill is a markdown file containing knowledge, workflows, or instructions. You can invoke skills with a command like `/deploy`, or Claude can load them automatically when relevant. Skills can run in your current conversation or in an isolated context via subagents.

29 30

30## Match features to your goal31## Match features to your goal

31 32

32Features range from always-on context that Claude sees every session, to on-demand capabilities you or Claude can invoke, to background automation that runs on specific events. The table below shows what's available and when each one makes sense.33Features range from always-on context that Claude sees every session, to on-demand capabilities you or Claude can invoke, to background automation that runs on specific events. The table below shows what's available and when each one makes sense.

33 34

35| ------------- | ---------------------------------------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------- |36| ---------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |

39| **MCP** | Connect to external services | External data or actions | Query your database, post to Slack, control a browser |41| **MCP** | Connect to external services | External data or actions | Query your database, post to Slack, control a browser |

41 43

79 81

80 **Put it in a skill** if it's reference material Claude needs sometimes (API docs, style guides) or a workflow you trigger with `/<name>` (deploy, review, release).82 **Put it in a skill** if it's reference material Claude needs sometimes (API docs, style guides) or a workflow you trigger with `/<name>` (deploy, review, release).

81 83

~~82 **Rule of thumb:** Keep CLAUDE.md under \~500 lines. If it's growing, move reference content to skills.~~84 **Rule of thumb:** Keep CLAUDE.md under 200 lines. If it's growing, move reference content to skills or split into [`.claude/rules/`](/en/memory#organize-rules-with-claude/rules/) files.

85 </Tab>

87 <Tab title="CLAUDE.md vs Rules vs Skills">

88 All three store instructions, but they load differently:

91 | ------------ | ----------------------------------- | -------------------------------------------------- | ---------------------------------------- |

96 **Use CLAUDE.md** for instructions every session needs: build commands, test conventions, project architecture.

98 **Use rules** to keep CLAUDE.md focused. Rules with [`paths` frontmatter](/en/memory#path-specific-rules) only load when Claude works with matching files, saving context.

100 **Use skills** for content Claude only needs sometimes, like API documentation or a deployment checklist you trigger with `/<name>`.

101 </Tab>

102

103 <Tab title="Subagent vs Agent team">

104 Both parallelize work, but they're architecturally different:

105

106 * **Subagents** run inside your session and report results back to your main context

107 * **Agent teams** are independent Claude Code sessions that communicate with each other

108

109 | Aspect | Subagent | Agent team |

110 | ----------------- | ------------------------------------------------ | --------------------------------------------------- |

111 | **Context** | Own context window; results return to the caller | Own context window; fully independent |

112 | **Communication** | Reports results back to the main agent only | Teammates message each other directly |

113 | **Coordination** | Main agent manages all work | Shared task list with self-coordination |

114 | **Best for** | Focused tasks where only the result matters | Complex work requiring discussion and collaboration |

115 | **Token cost** | Lower: results summarized back to main context | Higher: each teammate is a separate Claude instance |

116

117 **Use a subagent** when you need a quick, focused worker: research a question, verify a claim, review a file. The subagent does the work and returns a summary. Your main conversation stays clean.

118

119 **Use an agent team** when teammates need to share findings, challenge each other, and coordinate independently. Agent teams are best for research with competing hypotheses, parallel code review, and new feature development where each teammate owns a separate piece.

120

121 **Transition point:** If you're running parallel subagents but hitting context limits, or if your subagents need to communicate with each other, agent teams are the natural next step.

122

123 <Note>

124 Agent teams are experimental and disabled by default. See [agent teams](/en/agent-teams) for setup and current limitations.

125 </Note>

83 </Tab>126 </Tab>

84 127

85 <Tab title="MCP vs Skill">128 <Tab title="MCP vs Skill">

105 148

106Features can be defined at multiple levels: user-wide, per-project, via plugins, or through managed policies. You can also nest CLAUDE.md files in subdirectories or place skills in specific packages of a monorepo. When the same feature exists at multiple levels, here's how they layer:149Features can be defined at multiple levels: user-wide, per-project, via plugins, or through managed policies. You can also nest CLAUDE.md files in subdirectories or place skills in specific packages of a monorepo. When the same feature exists at multiple levels, here's how they layer:

107 150

108* **CLAUDE.md files** are additive: all levels contribute content to Claude's context simultaneously. Files from your working directory and above load at launch; subdirectories load as you work in them. When instructions conflict, Claude uses judgment to reconcile them, with more specific instructions typically taking precedence. See [how Claude looks up memories](/en/memory#how-claude-looks-up-memories).151* **CLAUDE.md files** are additive: all levels contribute content to Claude's context simultaneously. Files from your working directory and above load at launch; subdirectories load as you work in them. When instructions conflict, Claude uses judgment to reconcile them, with more specific instructions typically taking precedence. See [how CLAUDE.md files load](/en/memory#how-claude-md-files-load).

109* **Skills and subagents** override by name: when the same name exists at multiple levels, one definition wins based on priority (managed > user > project for skills; managed > CLI flag > project > user > plugin for subagents). Plugin skills are [namespaced](/en/plugins#add-skills-to-your-plugin) to avoid conflicts. See [skill discovery](/en/skills#where-skills-live) and [subagent scope](/en/sub-agents#choose-the-subagent-scope).152* **Skills and subagents** override by name: when the same name exists at multiple levels, one definition wins based on priority (managed > user > project for skills; managed > CLI flag > project > user > plugin for subagents). Plugin skills are [namespaced](/en/plugins#add-skills-to-your-plugin) to avoid conflicts. See [skill discovery](/en/skills#where-skills-live) and [subagent scope](/en/sub-agents#choose-the-subagent-scope).

110* **MCP servers** override by name: local > project > user. See [MCP scope](/en/mcp#scope-hierarchy-and-precedence).153* **MCP servers** override by name: local > project > user. See [MCP scope](/en/mcp#scope-hierarchy-and-precedence).

111* **Hooks** merge: all registered hooks fire for their matching events regardless of source. See [hooks](/en/hooks).154* **Hooks** merge: all registered hooks fire for their matching events regardless of source. See [hooks](/en/hooks).

117For example, you might use CLAUDE.md for project conventions, a skill for your deployment workflow, MCP to connect to your database, and a hook to run linting after every edit. Each feature handles what it's best at.160For example, you might use CLAUDE.md for project conventions, a skill for your deployment workflow, MCP to connect to your database, and a hook to run linting after every edit. Each feature handles what it's best at.

118 161

120| ---------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |163| ---------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |

122| **Skill + Subagent** | A skill spawns subagents for parallel work | `/review` skill kicks off security, performance, and style subagents that work in isolated context |165| **Skill + Subagent** | A skill spawns subagents for parallel work | `/audit` skill kicks off security, performance, and style subagents that work in isolated context |

123| **CLAUDE.md + Skills** | CLAUDE.md holds always-on rules; skills hold reference material loaded on demand | CLAUDE.md says "follow our API conventions," a skill contains the full API style guide |166| **CLAUDE.md + Skills** | CLAUDE.md holds always-on rules; skills hold reference material loaded on demand | CLAUDE.md says "follow our API conventions," a skill contains the full API style guide |

125 168

126## Understand context costs169## Understand context costs

127 170

128Every feature you add consumes some of Claude's context. Too much can fill up your context window, but it can also add noise that makes Claude less effective; skills may not trigger correctly, or Claude may lose track of your conventions. Understanding these trade-offs helps you build an effective setup.171Every feature you add consumes some of Claude's context. Too much can fill up your context window, but it can also add noise that makes Claude less effective; skills may not trigger correctly, or Claude may lose track of your conventions. Understanding these trade-offs helps you build an effective setup. For an interactive view of how these features combine in a running session, see [Explore the context window](/en/context-window).

129 172

130### Context cost by feature173### Context cost by feature

131 174

135| --------------- | ------------------------- | --------------------------------------------- | -------------------------------------------- |178| --------------- | ------------------------- | --------------------------------------------- | -------------------------------------------- |

141 184

145 188

146Each feature loads at different points in your session. The tabs below explain when each one loads and what goes into context.189Each feature loads at different points in your session. The tabs below explain when each one loads and what goes into context.

147 190

148<img src="https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/context-loading.svg?fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=bd2e24b8e6a99b31ecfffb63f5b23bf5" alt="Context loading: CLAUDE.md and MCP load at session start and stay in every request. Skills load descriptions at start, full content on invocation. Subagents get isolated context. Hooks run externally." data-og-width="720" width="720" data-og-height="410" height="410" data-path="images/context-loading.svg" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/context-loading.svg?w=280&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=aebaadd1f484f285dd9cb4e0ea6d49b9 280w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/context-loading.svg?w=560&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=030c9b46126d750de315612560082727 560w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/context-loading.svg?w=840&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=6c73f8b0389da4f3190843140c810fe9 840w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/context-loading.svg?w=1100&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=9844c55d08d2c386672447f2e8518669 1100w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/context-loading.svg?w=1650&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=21a9522d0e4bd10ced146aab850ede76 1650w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/context-loading.svg?w=2500&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=d318525915aee1a1a6a4215cfaa61fb9 2500w" />191<img src="https://mintcdn.com/claude-code/6yTCYq1p37ZB8-CQ/images/context-loading.svg?fit=max&auto=format&n=6yTCYq1p37ZB8-CQ&q=85&s=5a58ce953a35a2412892015e2ad6cb67" alt="Context loading: CLAUDE.md loads at session start and stays in every request. MCP tool names load at start with full schemas deferred until use. Skills load descriptions at start, full content on invocation. Subagents get isolated context. Hooks run externally." width="720" height="410" data-path="images/context-loading.svg" />

149 192

150<Tabs>193<Tabs>

151 <Tab title="CLAUDE.md">194 <Tab title="CLAUDE.md">

153 196

154 **What loads:** Full content of all CLAUDE.md files (managed, user, and project levels).197 **What loads:** Full content of all CLAUDE.md files (managed, user, and project levels).

155 198

156 **Inheritance:** Claude reads CLAUDE.md files from your working directory up to the root, and discovers nested ones in subdirectories as it accesses those files. See [How Claude looks up memories](/en/memory#how-claude-looks-up-memories) for details.199 **Inheritance:** Claude reads CLAUDE.md files from your working directory up to the root, and discovers nested ones in subdirectories as it accesses those files. See [How CLAUDE.md files load](/en/memory#how-claude-md-files-load) for details.

157 200

158 <Tip>Keep CLAUDE.md under \~500 lines. Move reference material to skills, which load on-demand.</Tip>201 <Tip>Keep CLAUDE.md under \~500 lines. Move reference material to skills, which load on-demand.</Tip>

159 </Tab>202 </Tab>

160 203

161 <Tab title="Skills">204 <Tab title="Skills">

162 Skills are extra capabilities in Claude's toolkit. They can be reference material (like an API style guide) or invocable workflows you trigger with `/<name>` (like `/deploy`). Some are built-in; you can also create your own. Claude uses skills when appropriate, or you can invoke one directly.205 Skills are extra capabilities in Claude's toolkit. They can be reference material (like an API style guide) or invocable workflows you trigger with `/<name>` (like `/deploy`). Claude Code ships with [bundled skills](/en/skills#bundled-skills) like `/simplify`, `/batch`, and `/debug` that work out of the box. You can also create your own. Claude uses skills when appropriate, or you can invoke one directly.

163 206

164 **When:** Depends on the skill's configuration. By default, descriptions load at session start and full content loads when used. For user-only skills (`disable-model-invocation: true`), nothing loads until you invoke them.207 **When:** Depends on the skill's configuration. By default, descriptions load at session start and full content loads when used. For user-only skills (`disable-model-invocation: true`), nothing loads until you invoke them.

165 208

177 <Tab title="MCP servers">220 <Tab title="MCP servers">

178 **When:** Session start.221 **When:** Session start.

179 222

180 **What loads:** All tool definitions and JSON schemas from connected servers.223 **What loads:** Tool names from connected servers. Full JSON schemas stay deferred until Claude needs a specific tool.

181 224

182 **Context cost:** [Tool search](/en/mcp#scale-with-mcp-tool-search) (enabled by default) loads MCP tools up to 10% of context and defers the rest until needed.225 **Context cost:** [Tool search](/en/mcp#scale-with-mcp-tool-search) is on by default, so idle MCP tools consume minimal context.

183 226

184 **Reliability note:** MCP connections can fail silently mid-session. If a server disconnects, its tools disappear without warning. Claude may try to use a tool that no longer exists. If you notice Claude failing to use an MCP tool it previously could access, check the connection with `/mcp`.227 **Reliability note:** MCP connections can fail silently mid-session. If a server disconnects, its tools disappear without warning. Claude may try to use a tool that no longer exists. If you notice Claude failing to use an MCP tool it previously could access, check the connection with `/mcp`.

185 228

229 Offload work to isolated context272 Offload work to isolated context

230 </Card>273 </Card>

231 274

275 <Card title="Agent teams" icon="network" href="/en/agent-teams">

276 Coordinate multiple sessions working in parallel

277 </Card>

278

232 <Card title="MCP" icon="plug" href="/en/mcp">279 <Card title="MCP" icon="plug" href="/en/mcp">

233 Connect Claude to external services280 Connect Claude to external services

234 </Card>281 </Card>

github-actions.md +16 −19

Details

6 6

7> Learn about integrating Claude Code into your development workflow with Claude Code GitHub Actions7> Learn about integrating Claude Code into your development workflow with Claude Code GitHub Actions

8 8

9Claude Code GitHub Actions brings AI-powered automation to your GitHub workflow. With a simple `@claude` mention in any PR or issue, Claude can analyze your code, create pull requests, implement features, and fix bugs - all while following your project's standards.9Claude Code GitHub Actions brings AI-powered automation to your GitHub workflow. With a simple `@claude` mention in any PR or issue, Claude can analyze your code, create pull requests, implement features, and fix bugs - all while following your project's standards. For automatic reviews posted on every PR without a trigger, see [GitHub Code Review](/en/code-review).

10 10

11<Note>11<Note>

~~12 Claude Code GitHub Actions is built on top of the [Claude Code~~12 Claude Code GitHub Actions is built on top of the [Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview), which enables programmatic integration of Claude Code into your applications. You can use the SDK to build custom automation workflows beyond GitHub Actions.

~~13 SDK](https://docs.claude.com/en/docs/agent-sdk), which enables programmatic integration of~~

~~14 Claude Code into your applications. You can use the SDK to build custom~~

~~15 automation workflows beyond GitHub Actions.~~

16</Note>13</Note>

17 14

18<Info>15<Info>

~~19 **Claude Opus 4.5 is now available.** Claude Code GitHub Actions default to Sonnet. To use Opus 4.5, configure the [model parameter](#breaking-changes-reference) to use `claude-opus-4-5-20251101`.~~16 **Claude Opus 4.6 is now available.** Claude Code GitHub Actions default to Sonnet. To use Opus 4.6, configure the [model parameter](#breaking-changes-reference) to use `claude-opus-4-6`.

20</Info>17</Info>

21 18

22## Why use Claude Code GitHub Actions?19## Why use Claude Code GitHub Actions?

117 anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}114 anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

118 custom_instructions: "Follow our coding standards"115 custom_instructions: "Follow our coding standards"

119 max_turns: "10"116 max_turns: "10"

120 model: "claude-sonnet-4-5-20250929"117 model: "claude-sonnet-4-6"

121```118```

122 119

123**GA version (v1.0):**120**GA version (v1.0):**

130 claude_args: |127 claude_args: |

131 --append-system-prompt "Follow our coding standards"128 --append-system-prompt "Follow our coding standards"

132 --max-turns 10129 --max-turns 10

133 --model claude-sonnet-4-5-20250929130 --model claude-sonnet-4-6

134```131```

135 132

136<Tip>133<Tip>

174 - uses: anthropics/claude-code-action@v1171 - uses: anthropics/claude-code-action@v1

175 with:172 with:

176 anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}173 anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

177 prompt: "/review"174 prompt: "Review this pull request for code quality, correctness, and security. Analyze the diff, then post your findings as review comments."

178 claude_args: "--max-turns 5"175 claude_args: "--max-turns 5"

179```176```

180 177

193 with:190 with:

194 anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}191 anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

195 prompt: "Generate a summary of yesterday's commits and open issues"192 prompt: "Generate a summary of yesterday's commits and open issues"

196 claude_args: "--model claude-opus-4-5-20251101"193 claude_args: "--model opus"

197```194```

198 195

199### Common use cases196### Common use cases

200 197

201In issue or PR comments:198In issue or PR comments:

202 199

203```200```text theme={null}

204@claude implement this feature based on the issue description201@claude implement this feature based on the issue description

205@claude how should I implement user authentication for this endpoint?202@claude how should I implement user authentication for this endpoint?

206@claude fix the TypeError in the user dashboard component203@claude fix the TypeError in the user dashboard component

270Key features:267Key features:

271 268

272* **Unified prompt interface** - Use `prompt` for all instructions269* **Unified prompt interface** - Use `prompt` for all instructions

273* **Commands** - Prebuilt prompts like `/review` or `/fix`270* **Skills** - Invoke installed [skills](/en/skills) directly from the prompt

274* **CLI passthrough** - Any Claude Code CLI argument via `claude_args`271* **CLI passthrough** - Any Claude Code CLI argument via `claude_args`

275* **Flexible triggers** - Works with any GitHub event272* **Flexible triggers** - Works with any GitHub event

276 273

521 with:518 with:

522 github_token: ${{ steps.app-token.outputs.token }}519 github_token: ${{ steps.app-token.outputs.token }}

523 use_bedrock: "true"520 use_bedrock: "true"

524 claude_args: '--model us.anthropic.claude-sonnet-4-5-20250929-v1:0 --max-turns 10'521 claude_args: '--model us.anthropic.claude-sonnet-4-6 --max-turns 10'

525 ```522 ```

526 523

527 <Tip>524 <Tip>

528 The model ID format for Bedrock includes the region prefix (e.g., `us.anthropic.claude...`) and version suffix.525 The model ID format for Bedrock includes a region prefix (for example, `us.anthropic.claude-sonnet-4-6`).

529 </Tip>526 </Tip>

530 </Accordion>527 </Accordion>

531 528

628The Claude Code Action v1 uses a simplified configuration:625The Claude Code Action v1 uses a simplified configuration:

629 626

631| ------------------- | ------------------------------------------------------ | -------- |628| ------------------- | ------------------------------------------------------------------ | -------- |

632| `prompt` | Instructions for Claude (text or skill like `/review`) | No\* |629| `prompt` | Instructions for Claude (plain text or a [skill](/en/skills) name) | No\* |

633| `claude_args` | CLI arguments passed to Claude Code | No |630| `claude_args` | CLI arguments passed to Claude Code | No |

634| `anthropic_api_key` | Claude API key | Yes\*\* |631| `anthropic_api_key` | Claude API key | Yes\*\* |

635| `github_token` | GitHub token for API access | No |632| `github_token` | GitHub token for API access | No |

645The `claude_args` parameter accepts any Claude Code CLI arguments:642The `claude_args` parameter accepts any Claude Code CLI arguments:

646 643

647```yaml theme={null}644```yaml theme={null}

648claude_args: "--max-turns 5 --model claude-sonnet-4-5-20250929 --mcp-config /path/to/config.json"645claude_args: "--max-turns 5 --model claude-sonnet-4-6 --mcp-config /path/to/config.json"

649```646```

650 647

651Common arguments:648Common arguments:

652 649

653* `--max-turns`: Maximum conversation turns (default: 10)650* `--max-turns`: Maximum conversation turns (default: 10)

654* `--model`: Model to use (for example, `claude-sonnet-4-5-20250929`)651* `--model`: Model to use (for example, `claude-sonnet-4-6`)

655* `--mcp-config`: Path to MCP configuration652* `--mcp-config`: Path to MCP configuration

656* `--allowed-tools`: Comma-separated list of allowed tools653* `--allowedTools`: Comma-separated list of allowed tools. The `--allowed-tools` alias also works.

657* `--debug`: Enable debug output654* `--debug`: Enable debug output

658 655

659### Alternative integration methods656### Alternative integration methods

gitlab-ci-cd.md +6 −6

Details

13</Info>13</Info>

14 14

15<Note>15<Note>

16 This integration is built on top of the [Claude Code CLI and SDK](https://docs.claude.com/en/docs/agent-sdk), enabling programmatic use of Claude in your CI/CD jobs and custom automation workflows.16 This integration is built on top of the [Claude Code CLI and Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview), enabling programmatic use of Claude in your CI/CD jobs and custom automation workflows.

17</Note>17</Note>

18 18

19## Why use Claude Code with GitLab?19## Why use Claude Code with GitLab?

126 126

127In an issue comment:127In an issue comment:

128 128

129```129```text theme={null}

130@claude implement this feature based on the issue description130@claude implement this feature based on the issue description

131```131```

132 132

136 136

137In an MR discussion:137In an MR discussion:

138 138

139```139```text theme={null}

140@claude suggest a concrete approach to cache the results of this API call140@claude suggest a concrete approach to cache the results of this API call

141```141```

142 142

146 146

147In an issue or MR comment:147In an issue or MR comment:

148 148

149```149```text theme={null}

150@claude fix the TypeError in the user dashboard component150@claude fix the TypeError in the user dashboard component

151```151```

152 152

319```319```

320 320

321<Note>321<Note>

322 Model IDs for Bedrock include region-specific prefixes and version suffixes (for example, `us.anthropic.claude-sonnet-4-5-20250929-v1:0`). Pass the desired model via your job configuration or prompt if your workflow supports it.322 Model IDs for Bedrock include region-specific prefixes (for example, `us.anthropic.claude-sonnet-4-6`). Pass the desired model via your job configuration or prompt if your workflow supports it.

323</Note>323</Note>

324 324

325### Google Vertex AI job example (Workload Identity Federation)325### Google Vertex AI job example (Workload Identity Federation)

408* **API costs**:408* **API costs**:

409 * Each Claude interaction consumes tokens based on prompt and response size409 * Each Claude interaction consumes tokens based on prompt and response size

410 * Token usage varies by task complexity and codebase size410 * Token usage varies by task complexity and codebase size

411 * See [Anthropic pricing](https://docs.claude.com/en/docs/about-claude/pricing) for details411 * See [Anthropic pricing](https://platform.claude.com/docs/en/about-claude/pricing) for details

412 412

413* **Cost optimization tips**:413* **Cost optimization tips**:

414 * Use specific `@claude` commands to reduce unnecessary turns414 * Use specific `@claude` commands to reduce unnecessary turns

google-vertex-ai.md +32 −30

Details

12 12

13* A Google Cloud Platform (GCP) account with billing enabled13* A Google Cloud Platform (GCP) account with billing enabled

14* A GCP project with Vertex AI API enabled14* A GCP project with Vertex AI API enabled

~~15* Access to desired Claude models (for example, Claude Sonnet 4.5)~~15* Access to desired Claude models (for example, Claude Sonnet 4.6)

16* Google Cloud SDK (`gcloud`) installed and configured16* Google Cloud SDK (`gcloud`) installed and configured

17* Quota allocated in desired GCP region17* Quota allocated in desired GCP region

18 18

19<Note>

20 If you are deploying Claude Code to multiple users, [pin your model versions](#5-pin-model-versions) to prevent breakage when Anthropic releases new models.

21</Note>

19## Region Configuration23## Region Configuration

20 24

21Claude Code can be used with both Vertex AI [global](https://cloud.google.com/blog/products/ai-machine-learning/global-endpoint-for-claude-models-generally-available-on-vertex-ai) and regional endpoints.25Claude Code can be used with both Vertex AI [global](https://cloud.google.com/blog/products/ai-machine-learning/global-endpoint-for-claude-models-generally-available-on-vertex-ai) and regional endpoints.

22 26

23<Note>27<Note>

24 Vertex AI may not support the Claude Code default models on all regions. You may need to switch to a [supported region or model](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations#genai-partner-models).28 Vertex AI may not support the Claude Code default models in all [regions](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations#genai-partner-models) or on [global endpoints](https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/use-partner-models#supported_models). You may need to switch to a supported region, use a regional endpoint, or specify a supported model.

~~25</Note>~~

~~27<Note>~~

28 Vertex AI may not support the Claude Code default models on global endpoints. You may need to switch to a regional endpoint or [supported model](https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/use-partner-models#supported_models).

29</Note>29</Note>

30 30

31## Setup31## Setup

48 48

491. Navigate to the [Vertex AI Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)491. Navigate to the [Vertex AI Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)

502. Search for "Claude" models502. Search for "Claude" models

~~513. Request access to desired Claude models (for example, Claude Sonnet 4.5)~~513. Request access to desired Claude models (for example, Claude Sonnet 4.6)

524. Wait for approval (may take 24-48 hours)524. Wait for approval (may take 24-48 hours)

53 53

54### 3. Configure GCP credentials54### 3. Configure GCP credentials

85export VERTEX_REGION_CLAUDE_4_1_OPUS=europe-west185export VERTEX_REGION_CLAUDE_4_1_OPUS=europe-west1

86```86```

87 87

~~88<Note>~~88[Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) is automatically supported when you specify the `cache_control` ephemeral flag. To disable it, set `DISABLE_PROMPT_CACHING=1`. For heightened rate limits, contact Google Cloud support. When using Vertex AI, the `/login` and `/logout` commands are disabled since authentication is handled through Google Cloud credentials.

89 [Prompt caching](https://docs.claude.com/en/docs/build-with-claude/prompt-caching) is automatically supported when you specify the `cache_control` ephemeral flag. To disable it, set `DISABLE_PROMPT_CACHING=1`. For heightened rate limits, contact Google Cloud support.

~~90</Note>~~

91 89

~~92<Note>~~90### 5. Pin model versions

~~93 When using Vertex AI, the `/login` and `/logout` commands are disabled since authentication is handled through Google Cloud credentials.~~

~~94</Note>~~

95 91

~~96### 5. Model configuration~~92<Warning>

93 Pin specific model versions for every deployment. If you use model aliases (`sonnet`, `opus`, `haiku`) without pinning, Claude Code may attempt to use a newer model version that isn't enabled in your Vertex AI project, breaking existing users when Anthropic releases updates.

94</Warning>

97 95

~~98Claude Code uses these default models for Vertex AI:~~96Set these environment variables to specific Vertex AI model IDs:

98```bash theme={null}

99export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-6'

100export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-6'

101export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

102```

103

104For current and legacy model IDs, see [Models overview](https://platform.claude.com/docs/en/about-claude/models/overview). See [Model configuration](/en/model-config#pin-models-for-third-party-deployments) for the full list of environment variables.

105

106Claude Code uses these default models when no pinning variables are set:

99 107

100| Model type | Default value |108| Model type | Default value |

101| :--------------- | :--------------------------- |109| :--------------- | :-------------------------- |

104 112

105<Note>113To customize models further:

106 For Vertex AI users, Claude Code will not automatically upgrade from Haiku 3.5 to Haiku 4.5. To manually switch to a newer Haiku model, set the `ANTHROPIC_DEFAULT_HAIKU_MODEL` environment variable to the full model name (for example, `claude-haiku-4-5@20251001`).

107</Note>

~~108~~

109To customize models:

110 114

111```bash theme={null}115```bash theme={null}

112export ANTHROPIC_MODEL='claude-opus-4-1@20250805'116export ANTHROPIC_MODEL='claude-opus-4-6'

113export ANTHROPIC_SMALL_FAST_MODEL='claude-haiku-4-5@20251001'117export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

114```118```

115 119

116## IAM configuration120## IAM configuration

126For details, see [Vertex IAM documentation](https://cloud.google.com/vertex-ai/docs/general/access-control).130For details, see [Vertex IAM documentation](https://cloud.google.com/vertex-ai/docs/general/access-control).

127 131

128<Note>132<Note>

129 We recommend creating a dedicated GCP project for Claude Code to simplify cost tracking and access control.133 Create a dedicated GCP project for Claude Code to simplify cost tracking and access control.

130</Note>134</Note>

131 135

132## 1M token context window136## 1M token context window

133 137

134Claude Sonnet 4 and Sonnet 4.5 support the [1M token context window](https://docs.claude.com/en/docs/build-with-claude/context-windows#1m-token-context-window) on Vertex AI.138Claude Opus 4.6, Sonnet 4.6, Sonnet 4.5, and Sonnet 4 support the [1M token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window) on Vertex AI. Claude Code automatically enables the extended context window when you select a 1M model variant.

135 139

136<Note>140To enable the 1M context window for your pinned model, append `[1m]` to the model ID. See [Pin models for third-party deployments](/en/model-config#pin-models-for-third-party-deployments) for details.

137 The 1M token context window is currently in beta. To use the extended context window, include the `context-1m-2025-08-07` beta header in your Vertex AI requests.

138</Note>

139 141

140## Troubleshooting142## Troubleshooting

141 143

148* Confirm model is Enabled in [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)150* Confirm model is Enabled in [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden)

149* Verify you have access to the specified region151* Verify you have access to the specified region

150* If using `CLOUD_ML_REGION=global`, check that your models support global endpoints in [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) under "Supported features". For models that don't support global endpoints, either:152* If using `CLOUD_ML_REGION=global`, check that your models support global endpoints in [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) under "Supported features". For models that don't support global endpoints, either:

151 * Specify a supported model via `ANTHROPIC_MODEL` or `ANTHROPIC_SMALL_FAST_MODEL`, or153 * Specify a supported model via `ANTHROPIC_MODEL` or `ANTHROPIC_DEFAULT_HAIKU_MODEL`, or

152 * Set a regional endpoint using `VERTEX_REGION_<MODEL_NAME>` environment variables154 * Set a regional endpoint using `VERTEX_REGION_<MODEL_NAME>` environment variables

153 155

154If you encounter 429 errors:156If you encounter 429 errors:

headless.md +48 −19

Details

34claude -p "What does the auth module do?"34claude -p "What does the auth module do?"

35```35```

36 36

37### Start faster with bare mode

39Add `--bare` to reduce startup time by skipping auto-discovery of hooks, skills, plugins, MCP servers, auto memory, and CLAUDE.md. Without it, `claude -p` loads the same [context](/en/how-claude-code-works#the-context-window) an interactive session would, including anything configured in the working directory or `~/.claude`.

41Bare mode is useful for CI and scripts where you need the same result on every machine. A hook in a teammate's `~/.claude` or an MCP server in the project's `.mcp.json` won't run, because bare mode never reads them. Only flags you pass explicitly take effect.

43This example runs a one-off summarize task in bare mode and pre-approves the Read tool so the call completes without a permission prompt:

45```bash theme={null}

46claude --bare -p "Summarize this file" --allowedTools "Read"

47```

49In bare mode Claude has access to the Bash, file read, and file edit tools. Pass any context you need with a flag:

51| To load | Use |

52| ----------------------- | ------------------------------------------------------- |

53| System prompt additions | `--append-system-prompt`, `--append-system-prompt-file` |

54| Settings | `--settings <file-or-json>` |

55| MCP servers | `--mcp-config <file-or-json>` |

56| Custom agents | `--agents <json>` |

57| A plugin directory | `--plugin-dir <path>` |

59Bare mode skips OAuth and keychain reads. Anthropic authentication must come from `ANTHROPIC_API_KEY` or an `apiKeyHelper` in the JSON passed to `--settings`. Bedrock, Vertex, and Foundry use their usual provider credentials.

61<Note>

62 `--bare` is the recommended mode for scripted and SDK calls, and will become the default for `-p` in a future release.

63</Note>

37## Examples65## Examples

38 66

~~39These examples highlight common CLI patterns.~~67These examples highlight common CLI patterns. For CI and other scripted calls, add [`--bare`](#start-faster-with-bare-mode) so they don't pick up whatever happens to be configured locally.

40 68

41### Get structured output69### Get structured output

42 70

92 jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'120 jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'

93```121```

94 122

123When an API request fails with a retryable error, Claude Code emits a `system/api_retry` event before retrying. You can use this to surface retry progress or implement custom backoff logic.

124

125| Field | Type | Description |

126| ---------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |

127| `type` | `"system"` | message type |

128| `subtype` | `"api_retry"` | identifies this as a retry event |

129| `attempt` | integer | current attempt number, starting at 1 |

130| `max_retries` | integer | total retries permitted |

131| `retry_delay_ms` | integer | milliseconds until the next attempt |

132| `error_status` | integer or null | HTTP status code, or `null` for connection errors with no HTTP response |

133| `error` | string | error category: `authentication_failed`, `billing_error`, `rate_limit`, `invalid_request`, `server_error`, `max_output_tokens`, or `unknown` |

134| `uuid` | string | unique event identifier |

135| `session_id` | string | session the event belongs to |

136

95For programmatic streaming with callbacks and message objects, see [Stream responses in real-time](https://platform.claude.com/docs/en/agent-sdk/streaming-output) in the Agent SDK documentation.137For programmatic streaming with callbacks and message objects, see [Stream responses in real-time](https://platform.claude.com/docs/en/agent-sdk/streaming-output) in the Agent SDK documentation.

96 138

97### Auto-approve tools139### Auto-approve tools

115The `--allowedTools` flag uses [permission rule syntax](/en/settings#permission-rule-syntax). The trailing ` *` enables prefix matching, so `Bash(git diff *)` allows any command starting with `git diff`. The space before `*` is important: without it, `Bash(git diff*)` would also match `git diff-index`.157The `--allowedTools` flag uses [permission rule syntax](/en/settings#permission-rule-syntax). The trailing ` *` enables prefix matching, so `Bash(git diff *)` allows any command starting with `git diff`. The space before `*` is important: without it, `Bash(git diff*)` would also match `git diff-index`.

116 158

117<Note>159<Note>

118 User-invoked [skills](/en/skills) like `/commit` and [built-in commands](/en/interactive-mode#built-in-commands) are only available in interactive mode. In `-p` mode, describe the task you want to accomplish instead.160 User-invoked [skills](/en/skills) like `/commit` and [built-in commands](/en/commands) are only available in interactive mode. In `-p` mode, describe the task you want to accomplish instead.

119</Note>161</Note>

120 162

121### Customize the system prompt163### Customize the system prompt

152 194

153## Next steps195## Next steps

154 196

155<CardGroup cols={2}>197* [Agent SDK quickstart](https://platform.claude.com/docs/en/agent-sdk/quickstart): build your first agent with Python or TypeScript

156 <Card title="Agent SDK quickstart" icon="play" href="https://platform.claude.com/docs/en/agent-sdk/quickstart">198* [CLI reference](/en/cli-reference): all CLI flags and options

157 Build your first agent with Python or TypeScript199* [GitHub Actions](/en/github-actions): use the Agent SDK in GitHub workflows

158 </Card>200* [GitLab CI/CD](/en/gitlab-ci-cd): use the Agent SDK in GitLab pipelines

~~159~~

160 <Card title="CLI reference" icon="terminal" href="/en/cli-reference">

161 Explore all CLI flags and options

162 </Card>

~~163~~

164 <Card title="GitHub Actions" icon="github" href="/en/github-actions">

165 Use the Agent SDK in GitHub workflows

166 </Card>

~~167~~

168 <Card title="GitLab CI/CD" icon="gitlab" href="/en/gitlab-ci-cd">

169 Use the Agent SDK in GitLab pipelines

170 </Card>

171</CardGroup>

hooks.md +877 −67

Details

4 4

5# Hooks reference5# Hooks reference

6 6

~~7> Reference for Claude Code hook events, configuration schema, JSON input/output formats, exit codes, async hooks, prompt hooks, and MCP tool hooks.~~7> Reference for Claude Code hook events, configuration schema, JSON input/output formats, exit codes, async hooks, HTTP hooks, prompt hooks, and MCP tool hooks.

8 8

9<Tip>9<Tip>

10 For a quickstart guide with examples, see [Automate workflows with hooks](/en/hooks-guide).10 For a quickstart guide with examples, see [Automate workflows with hooks](/en/hooks-guide).

11</Tip>11</Tip>

12 12

13Hooks are user-defined shell commands or LLM prompts that execute automatically at specific points in Claude Code's lifecycle. Use this reference to look up event schemas, configuration options, JSON input/output formats, and advanced features like async hooks and MCP tool hooks. If you're setting up hooks for the first time, start with the [guide](/en/hooks-guide) instead.13Hooks are user-defined shell commands, HTTP endpoints, or LLM prompts that execute automatically at specific points in Claude Code's lifecycle. Use this reference to look up event schemas, configuration options, JSON input/output formats, and advanced features like async hooks, HTTP hooks, and MCP tool hooks. If you're setting up hooks for the first time, start with the [guide](/en/hooks-guide) instead.

14 14

15## Hook lifecycle15## Hook lifecycle

16 16

17Hooks fire at specific points during a Claude Code session. When an event fires and a matcher matches, Claude Code passes JSON context about the event to your hook handler. For command hooks, this arrives on stdin. Your handler can then inspect the input, take action, and optionally return a decision. Some events fire once per session, while others fire repeatedly inside the agentic loop:17Hooks fire at specific points during a Claude Code session. When an event fires and a matcher matches, Claude Code passes JSON context about the event to your hook handler. For command hooks, input arrives on stdin. For HTTP hooks, it arrives as the POST request body. Your handler can then inspect the input, take action, and optionally return a decision. Some events fire once per session, while others fire repeatedly inside the agentic loop:

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/1wr0LPds6lVWZkQB/images/hooks-lifecycle.svg?fit=max&auto=format&n=1wr0LPds6lVWZkQB&q=85&s=53a826e7bb64c6bff5f867506c0530ad" alt="Hook lifecycle diagram showing the sequence of hooks from SessionStart through the agentic loop (PreToolUse, PermissionRequest, PostToolUse, SubagentStart/Stop, TaskCreated, TaskCompleted) to Stop or StopFailure, TeammateIdle, PreCompact, PostCompact, and SessionEnd, with Elicitation and ElicitationResult nested inside MCP tool execution and WorktreeCreate, WorktreeRemove, Notification, ConfigChange, InstructionsLoaded, CwdChanged, and FileChanged as standalone async events" width="520" height="1155" data-path="images/hooks-lifecycle.svg" />

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 |

35| `Notification` | When Claude Code sends a notification |35| `Notification` | When Claude Code sends a notification |

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| `TaskCreated` | When a task is being created via `TaskCreate` |

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

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

41| `StopFailure` | When the turn ends due to an API error. Output and exit code are ignored |

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

43| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |

44| `ConfigChange` | When a configuration file changes during a session |

45| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |

46| `FileChanged` | When a watched file changes on disk. The `matcher` field specifies which filenames to watch |

47| `WorktreeCreate` | When a worktree is being created via `--worktree` or `isolation: "worktree"`. Replaces default git behavior |

48| `WorktreeRemove` | When a worktree is being removed, either at session exit or when a subagent finishes |

39| `PreCompact` | Before context compaction |49| `PreCompact` | Before context compaction |

50| `PostCompact` | After context compaction completes |

51| `Elicitation` | When an MCP server requests user input during a tool call |

52| `ElicitationResult` | After a user responds to an MCP elicitation, before the response is sent back to the server |

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

41 54

42### How a hook resolves55### How a hook resolves

43 56

~~44To see how these pieces fit together, consider this `PreToolUse` hook that blocks destructive shell commands. The hook runs `block-rm.sh` before every Bash tool call:~~57To see how these pieces fit together, consider this `PreToolUse` hook that blocks destructive shell commands. The `matcher` narrows to Bash tool calls and the `if` condition narrows further to commands starting with `rm`, so `block-rm.sh` only spawns when both filters match:

45 58

46```json theme={null}59```json theme={null}

47{60{

52 "hooks": [65 "hooks": [

53 {66 {

54 "type": "command",67 "type": "command",

~~55 "command": ".claude/hooks/block-rm.sh"~~68 "if": "Bash(rm *)",

69 "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm.sh"

56 }70 }

57 ]71 ]

58 }72 }

84Now suppose Claude Code decides to run `Bash "rm -rf /tmp/build"`. Here's what happens:98Now suppose Claude Code decides to run `Bash "rm -rf /tmp/build"`. Here's what happens:

85 99

86<Frame>100<Frame>

87 <img src="https://mintcdn.com/claude-code/s7NM0vfd_wres2nf/images/hook-resolution.svg?fit=max&auto=format&n=s7NM0vfd_wres2nf&q=85&s=7c13f51ffcbc37d22a593b27e2f2de72" alt="Hook resolution flow: PreToolUse event fires, matcher checks for Bash match, hook handler runs, result returns to Claude Code" data-og-width="780" width="780" data-og-height="290" height="290" data-path="images/hook-resolution.svg" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/s7NM0vfd_wres2nf/images/hook-resolution.svg?w=280&fit=max&auto=format&n=s7NM0vfd_wres2nf&q=85&s=36a39a07e8bc1995dcb4639e09846905 280w, https://mintcdn.com/claude-code/s7NM0vfd_wres2nf/images/hook-resolution.svg?w=560&fit=max&auto=format&n=s7NM0vfd_wres2nf&q=85&s=6568d90c596c7605bbac2c325b0a0c86 560w, https://mintcdn.com/claude-code/s7NM0vfd_wres2nf/images/hook-resolution.svg?w=840&fit=max&auto=format&n=s7NM0vfd_wres2nf&q=85&s=255a6f68b9475a0e41dbde7b88002dad 840w, https://mintcdn.com/claude-code/s7NM0vfd_wres2nf/images/hook-resolution.svg?w=1100&fit=max&auto=format&n=s7NM0vfd_wres2nf&q=85&s=dcecf8d5edc88cd2bc49deb006d5760d 1100w, https://mintcdn.com/claude-code/s7NM0vfd_wres2nf/images/hook-resolution.svg?w=1650&fit=max&auto=format&n=s7NM0vfd_wres2nf&q=85&s=04fe51bf69ae375e9fd517f18674e35f 1650w, https://mintcdn.com/claude-code/s7NM0vfd_wres2nf/images/hook-resolution.svg?w=2500&fit=max&auto=format&n=s7NM0vfd_wres2nf&q=85&s=b1b76e0b77fddb5c7fa7bf302dacd80b 2500w" />101 <img src="https://mintcdn.com/claude-code/-tYw1BD_DEqfyyOZ/images/hook-resolution.svg?fit=max&auto=format&n=-tYw1BD_DEqfyyOZ&q=85&s=c73ebc1eeda2037570427d7af1e0a891" alt="Hook resolution flow: PreToolUse event fires, matcher checks for Bash match, if condition checks for Bash(rm *) match, hook handler runs, result returns to Claude Code" width="930" height="290" data-path="images/hook-resolution.svg" />

88</Frame>102</Frame>

89 103

90<Steps>104<Steps>

97 </Step>111 </Step>

98 112

99 <Step title="Matcher checks">113 <Step title="Matcher checks">

100 The matcher `"Bash"` matches the tool name, so `block-rm.sh` runs. If you omit the matcher or use `"*"`, the hook runs on every occurrence of the event. Hooks only skip when a matcher is defined and doesn't match.114 The matcher `"Bash"` matches the tool name, so this hook group activates. If you omit the matcher or use `"*"`, the group activates on every occurrence of the event.

115 </Step>

116

117 <Step title="If condition checks">

118 The `if` condition `"Bash(rm *)"` matches because the command starts with `rm`, so this handler spawns. If the command had been `npm test`, the `if` check would fail and `block-rm.sh` would never run, avoiding the process spawn overhead. The `if` field is optional; without it, every handler in the matched group runs.

101 </Step>119 </Step>

102 120

103 <Step title="Hook handler runs">121 <Step title="Hook handler runs">

104 The script extracts `"rm -rf /tmp/build"` from the input and finds `rm -rf`, so it prints a decision to stdout:122 The script inspects the full command and finds `rm -rf`, so it prints a decision to stdout:

105 123

106 ```json theme={null}124 ```json theme={null}

107 {125 {

113 }131 }

114 ```132 ```

115 133

116 If the command had been safe (like `npm test`), the script would hit `exit 0` instead, which tells Claude Code to allow the tool call with no further action.134 If the command had been a safer `rm` variant like `rm file.txt`, the script would hit `exit 0` instead, which tells Claude Code to allow the tool call with no further action.

117 </Step>135 </Step>

118 136

119 <Step title="Claude Code acts on the result">137 <Step title="Claude Code acts on the result">

134See [How a hook resolves](#how-a-hook-resolves) above for a complete walkthrough with an annotated example.152See [How a hook resolves](#how-a-hook-resolves) above for a complete walkthrough with an annotated example.

135 153

136<Note>154<Note>

137 This page uses specific terms for each level: **hook event** for the lifecycle point, **matcher group** for the filter, and **hook handler** for the shell command, prompt, or agent that runs. "Hook" on its own refers to the general feature.155 This page uses specific terms for each level: **hook event** for the lifecycle point, **matcher group** for the filter, and **hook handler** for the shell command, HTTP endpoint, prompt, or agent that runs. "Hook" on its own refers to the general feature.

138</Note>156</Note>

139 157

140### Hook locations158### Hook locations

157The `matcher` field is a regex string that filters when hooks fire. Use `"*"`, `""`, or omit `matcher` entirely to match all occurrences. Each event type matches on a different field:175The `matcher` field is a regex string that filters when hooks fire. Use `"*"`, `""`, or omit `matcher` entirely to match all occurrences. Each event type matches on a different field:

158 176

160| :--------------------------------------------------------------------- | :------------------------ | :----------------------------------------------------------------------------- |178| :------------------------------------------------------------------------------------------------------------- | :-------------------------------------- | :------------------------------------------------------------------------------------------------------------------------ |

187| `CwdChanged` | no matcher support | always fires on every directory change |

188| `FileChanged` | filename (basename of the changed file) | `.envrc`, `.env`, any filename you want to watch |

189| `StopFailure` | error type | `rate_limit`, `authentication_failed`, `billing_error`, `invalid_request`, `server_error`, `max_output_tokens`, `unknown` |

190| `InstructionsLoaded` | load reason | `session_start`, `nested_traversal`, `path_glob_match`, `include`, `compact` |

191| `Elicitation` | MCP server name | your configured MCP server names |

192| `ElicitationResult` | MCP server name | same values as `Elicitation` |

193| `UserPromptSubmit`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove` | no matcher support | always fires on every occurrence |

169 194

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.195The 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 196

189}214}

190```215```

191 216

192`UserPromptSubmit` and `Stop` don't support matchers and always fire on every occurrence. If you add a `matcher` field to these events, it is silently ignored.217`UserPromptSubmit`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, and `CwdChanged` don't support matchers and always fire on every occurrence. If you add a `matcher` field to these events, it is silently ignored.

218

219For tool events, you can filter more narrowly by setting the [`if` field](#common-fields) on individual hook handlers. `if` uses [permission rule syntax](/en/permissions) to match against the tool name and arguments together, so `"Bash(git *)"` runs only for `git` commands and `"Edit(*.ts)"` runs only for TypeScript files.

193 220

194#### Match MCP tools221#### Match MCP tools

195 222

237 264

238### Hook handler fields265### Hook handler fields

239 266

240Each object in the inner `hooks` array is a hook handler: the shell command, LLM prompt, or agent that runs when the matcher matches. There are three types:267Each object in the inner `hooks` array is a hook handler: the shell command, HTTP endpoint, LLM prompt, or agent that runs when the matcher matches. There are four types:

241 268

242* **[Command hooks](#command-hook-fields)** (`type: "command"`): run a shell command. Your script receives the event's [JSON input](#hook-input-and-output) on stdin and communicates results back through exit codes and stdout.269* **[Command hooks](#command-hook-fields)** (`type: "command"`): run a shell command. Your script receives the event's [JSON input](#hook-input-and-output) on stdin and communicates results back through exit codes and stdout.

270* **[HTTP hooks](#http-hook-fields)** (`type: "http"`): send the event's JSON input as an HTTP POST request to a URL. The endpoint communicates results back through the response body using the same [JSON output format](#json-output) as command hooks.

243* **[Prompt hooks](#prompt-and-agent-hook-fields)** (`type: "prompt"`): send a prompt to a Claude model for single-turn evaluation. The model returns a yes/no decision as JSON. See [Prompt-based hooks](#prompt-based-hooks).271* **[Prompt hooks](#prompt-and-agent-hook-fields)** (`type: "prompt"`): send a prompt to a Claude model for single-turn evaluation. The model returns a yes/no decision as JSON. See [Prompt-based hooks](#prompt-based-hooks).

244* **[Agent hooks](#prompt-and-agent-hook-fields)** (`type: "agent"`): spawn a subagent that can use tools like Read, Grep, and Glob to verify conditions before returning a decision. See [Agent-based hooks](#agent-based-hooks).272* **[Agent hooks](#prompt-and-agent-hook-fields)** (`type: "agent"`): spawn a subagent that can use tools like Read, Grep, and Glob to verify conditions before returning a decision. See [Agent-based hooks](#agent-based-hooks).

245 273

248These fields apply to all hook types:276These fields apply to all hook types:

249 277

251| :-------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------- |279| :-------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

252| `type` | yes | `"command"`, `"prompt"`, or `"agent"` |280| `type` | yes | `"command"`, `"http"`, `"prompt"`, or `"agent"` |

281| `if` | no | Permission rule syntax to filter when this hook runs, such as `"Bash(git *)"` or `"Edit(*.ts)"`. The hook only spawns if the tool call matches the pattern. Only evaluated on tool events: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, and `PermissionRequest`. On other events, a hook with `if` set never runs. Uses the same syntax as [permission rules](/en/permissions) |

253| `timeout` | no | Seconds before canceling. Defaults: 600 for command, 30 for prompt, 60 for agent |282| `timeout` | no | Seconds before canceling. Defaults: 600 for command, 30 for prompt, 60 for agent |

254| `statusMessage` | no | Custom spinner message displayed while the hook runs |283| `statusMessage` | no | Custom spinner message displayed while the hook runs |

255| `once` | no | If `true`, runs only once per session then is removed. Skills only, not agents. See [Hooks in skills and agents](#hooks-in-skills-and-agents) |284| `once` | no | If `true`, runs only once per session then is removed. Skills only, not agents. See [Hooks in skills and agents](#hooks-in-skills-and-agents) |

259In addition to the [common fields](#common-fields), command hooks accept these fields:288In addition to the [common fields](#common-fields), command hooks accept these fields:

260 289

262| :-------- | :------- | :------------------------------------------------------------------------------------------------------------------ |291| :-------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

263| `command` | yes | Shell command to execute |292| `command` | yes | Shell command to execute |

264| `async` | no | If `true`, runs in the background without blocking. See [Run hooks in the background](#run-hooks-in-the-background) |293| `async` | no | If `true`, runs in the background without blocking. See [Run hooks in the background](#run-hooks-in-the-background) |

294| `shell` | no | Shell to use for this hook. Accepts `"bash"` (default) or `"powershell"`. Setting `"powershell"` runs the command via PowerShell on Windows. Does not require `CLAUDE_CODE_USE_POWERSHELL_TOOL` since hooks spawn PowerShell directly |

295

296#### HTTP hook fields

297

298In addition to the [common fields](#common-fields), HTTP hooks accept these fields:

299

300| Field | Required | Description |

301| :--------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

302| `url` | yes | URL to send the POST request to |

303| `headers` | no | Additional HTTP headers as key-value pairs. Values support environment variable interpolation using `$VAR_NAME` or `${VAR_NAME}` syntax. Only variables listed in `allowedEnvVars` are resolved |

304| `allowedEnvVars` | no | List of environment variable names that may be interpolated into header values. References to unlisted variables are replaced with empty strings. Required for any env var interpolation to work |

305

306Claude Code sends the hook's [JSON input](#hook-input-and-output) as the POST request body with `Content-Type: application/json`. The response body uses the same [JSON output format](#json-output) as command hooks.

307

308Error handling differs from command hooks: non-2xx responses, connection failures, and timeouts all produce non-blocking errors that allow execution to continue. To block a tool call or deny a permission, return a 2xx response with a JSON body containing `decision: "block"` or a `hookSpecificOutput` with `permissionDecision: "deny"`.

309

310This example sends `PreToolUse` events to a local validation service, authenticating with a token from the `MY_TOKEN` environment variable:

311

312```json theme={null}

313{

314 "hooks": {

315 "PreToolUse": [

316 {

317 "matcher": "Bash",

318 "hooks": [

319 {

320 "type": "http",

321 "url": "http://localhost:8080/hooks/pre-tool-use",

322 "timeout": 30,

323 "headers": {

324 "Authorization": "Bearer $MY_TOKEN"

325 },

326 "allowedEnvVars": ["MY_TOKEN"]

327 }

328 ]

329 }

330 ]

331 }

332}

333```

265 334

266#### Prompt and agent hook fields335#### Prompt and agent hook fields

267 336

272| `prompt` | yes | Prompt text to send to the model. Use `$ARGUMENTS` as a placeholder for the hook input JSON |341| `prompt` | yes | Prompt text to send to the model. Use `$ARGUMENTS` as a placeholder for the hook input JSON |

273| `model` | no | Model to use for evaluation. Defaults to a fast model |342| `model` | no | Model to use for evaluation. Defaults to a fast model |

274 343

275All matching hooks run in parallel, and identical handlers are deduplicated automatically. Handlers run in the current directory with Claude Code's environment. The `$CLAUDE_CODE_REMOTE` environment variable is set to `"true"` in remote web environments and not set in the local CLI.344All matching hooks run in parallel, and identical handlers are deduplicated automatically. Command hooks are deduplicated by command string, and HTTP hooks are deduplicated by URL. Handlers run in the current directory with Claude Code's environment. The `$CLAUDE_CODE_REMOTE` environment variable is set to `"true"` in remote web environments and not set in the local CLI.

276 345

277### Reference scripts by path346### Reference scripts by path

278 347

279Use environment variables to reference hook scripts relative to the project or plugin root, regardless of the working directory when the hook runs:348Use environment variables to reference hook scripts relative to the project or plugin root, regardless of the working directory when the hook runs:

280 349

281* `$CLAUDE_PROJECT_DIR`: the project root. Wrap in quotes to handle paths with spaces.350* `$CLAUDE_PROJECT_DIR`: the project root. Wrap in quotes to handle paths with spaces.

282* `${CLAUDE_PLUGIN_ROOT}`: the plugin's root directory, for scripts bundled with a [plugin](/en/plugins).351* `${CLAUDE_PLUGIN_ROOT}`: the plugin's installation directory, for scripts bundled with a [plugin](/en/plugins). Changes on each plugin update.

352* `${CLAUDE_PLUGIN_DATA}`: the plugin's [persistent data directory](/en/plugins-reference#persistent-data-directory), for dependencies and state that should survive plugin updates.

283 353

284<Tabs>354<Tabs>

285 <Tab title="Project scripts">355 <Tab title="Project scripts">

360 430

361### The `/hooks` menu431### The `/hooks` menu

362 432

363Type `/hooks` in Claude Code to open the interactive hooks manager, where you can view, add, and delete hooks without editing settings files directly. For a step-by-step walkthrough, see [Set up your first hook](/en/hooks-guide#set-up-your-first-hook) in the guide.433Type `/hooks` in Claude Code to open a read-only browser for your configured hooks. The menu shows every hook event with a count of configured hooks, lets you drill into matchers, and shows the full details of each hook handler. Use it to verify configuration, check which settings file a hook came from, or inspect a hook's command, prompt, or URL.

364 434

365Each hook in the menu is labeled with a bracket prefix indicating its source:435The menu displays all four hook types: `command`, `prompt`, `agent`, and `http`. Each hook is labeled with a `[type]` prefix and a source indicating where it was defined:

366 436

367* `[User]`: from `~/.claude/settings.json`437* `User`: from `~/.claude/settings.json`

368* `[Project]`: from `.claude/settings.json`438* `Project`: from `.claude/settings.json`

369* `[Local]`: from `.claude/settings.local.json`439* `Local`: from `.claude/settings.local.json`

370* `[Plugin]`: from a plugin's `hooks/hooks.json`, read-only440* `Plugin`: from a plugin's `hooks/hooks.json`

441* `Session`: registered in memory for the current session

442* `Built-in`: registered internally by Claude Code

443

444Selecting a hook opens a detail view showing its event, matcher, type, source file, and the full command, prompt, or URL. The menu is read-only: to add, modify, or remove hooks, edit the settings JSON directly or ask Claude to make the change.

371 445

372### Disable or remove hooks446### Disable or remove hooks

373 447

374To remove a hook, delete its entry from the settings JSON file, or use the `/hooks` menu and select the hook to delete it.448To remove a hook, delete its entry from the settings JSON file.

449

450To temporarily disable all hooks without removing them, set `"disableAllHooks": true` in your settings file. There is no way to disable an individual hook while keeping it in the configuration.

375 451

376To temporarily disable all hooks without removing them, set `"disableAllHooks": true` in your settings file or use the toggle in the `/hooks` menu. There is no way to disable an individual hook while keeping it in the configuration.452The `disableAllHooks` setting respects the managed settings hierarchy. If an administrator has configured hooks through managed policy settings, `disableAllHooks` set in user, project, or local settings cannot disable those managed hooks. Only `disableAllHooks` set at the managed settings level can disable managed hooks.

377 453

378Direct edits to hooks in settings files don't take effect immediately. Claude Code captures a snapshot of hooks at startup and uses it throughout the session. This prevents malicious or accidental hook modifications from taking effect mid-session without your review. If hooks are modified externally, Claude Code warns you and requires review in the `/hooks` menu before changes apply.454Direct edits to hooks in settings files are normally picked up automatically by the file watcher.

379 455

380## Hook input and output456## Hook input and output

381 457

382Hooks receive JSON data via stdin and communicate results through exit codes, stdout, and stderr. This section covers fields and behavior common to all events. Each event's section under [Hook events](#hook-events) includes its specific input schema and decision control options.458Command hooks receive JSON data via stdin and communicate results through exit codes, stdout, and stderr. HTTP hooks receive the same JSON as the POST request body and communicate results through the HTTP response body. This section covers fields and behavior common to all events. Each event's section under [Hook events](#hook-events) includes its specific input schema and decision control options.

383 459

384### Common input fields460### Common input fields

385 461

386All hook events receive these fields via stdin as JSON, in addition to event-specific fields documented in each [hook event](#hook-events) section:462Hook events receive these fields as JSON, in addition to event-specific fields documented in each [hook event](#hook-events) section. For command hooks, this JSON arrives via stdin. For HTTP hooks, it arrives as the POST request body.

387 463

388| Field | Description |464| Field | Description |

389| :---------------- | :--------------------------------------------------------------------------------------------------------------------------------- |465| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

392| `cwd` | Current working directory when the hook is invoked |468| `cwd` | Current working directory when the hook is invoked |

393| `permission_mode` | Current [permission mode](/en/iam#permission-modes): `"default"`, `"plan"`, `"acceptEdits"`, `"dontAsk"`, or `"bypassPermissions"` |469| `permission_mode` | Current [permission mode](/en/permissions#permission-modes): `"default"`, `"plan"`, `"acceptEdits"`, `"auto"`, `"dontAsk"`, or `"bypassPermissions"`. Not all events receive this field: see each event's JSON example below to check |

395 471

472When running with `--agent` or inside a subagent, two additional fields are included:

473

474| Field | Description |

475| :----------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

476| `agent_id` | Unique identifier for the subagent. Present only when the hook fires inside a subagent call. Use this to distinguish subagent hook calls from main-thread calls. |

477| `agent_type` | Agent name (for example, `"Explore"` or `"security-reviewer"`). Present when the session uses `--agent` or the hook fires inside a subagent. For subagents, the subagent's type takes precedence over the session's `--agent` value. |

478

396For example, a `PreToolUse` hook for a Bash command receives this on stdin:479For example, a `PreToolUse` hook for a Bash command receives this on stdin:

397 480

398```json theme={null}481```json theme={null}

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.524Exit 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 525

444| :------------------- | :--------- | :-------------------------------------------------------- |527| :------------------- | :--------- | :---------------------------------------------------------------------------- |

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

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

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

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

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

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

534| `TaskCreated` | Yes | Prevents the task from being created |

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

536| `ConfigChange` | Yes | Blocks the configuration change from taking effect (except `policy_settings`) |

537| `StopFailure` | No | Output and exit code are ignored |

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

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

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

453| `SubagentStart` | No | Shows stderr to user only |541| `SubagentStart` | No | Shows stderr to user only |

454| `SessionStart` | No | Shows stderr to user only |542| `SessionStart` | No | Shows stderr to user only |

455| `SessionEnd` | No | Shows stderr to user only |543| `SessionEnd` | No | Shows stderr to user only |

544| `CwdChanged` | No | Shows stderr to user only |

545| `FileChanged` | No | Shows stderr to user only |

456| `PreCompact` | No | Shows stderr to user only |546| `PreCompact` | No | Shows stderr to user only |

547| `PostCompact` | No | Shows stderr to user only |

548| `Elicitation` | Yes | Denies the elicitation |

549| `ElicitationResult` | Yes | Blocks the response (action becomes decline) |

550| `WorktreeCreate` | Yes | Any non-zero exit code causes worktree creation to fail |

551| `WorktreeRemove` | No | Failures are logged in debug mode only |

552| `InstructionsLoaded` | No | Exit code is ignored |

553

554### HTTP response handling

555

556HTTP hooks use HTTP status codes and response bodies instead of exit codes and stdout:

557

558* **2xx with an empty body**: success, equivalent to exit code 0 with no output

559* **2xx with a plain text body**: success, the text is added as context

560* **2xx with a JSON body**: success, parsed using the same [JSON output](#json-output) schema as command hooks

561* **Non-2xx status**: non-blocking error, execution continues

562* **Connection failure or timeout**: non-blocking error, execution continues

563

564Unlike command hooks, HTTP hooks cannot signal a blocking error through status codes alone. To block a tool call or deny a permission, return a 2xx response with a JSON body containing the appropriate decision fields.

457 565

458### JSON output566### JSON output

459 567

489Not every event supports blocking or controlling behavior through JSON. The events that do each use a different set of fields to express that decision. Use this table as a quick reference before writing a hook:597Not every event supports blocking or controlling behavior through JSON. The events that do each use a different set of fields to express that decision. Use this table as a quick reference before writing a hook:

490 598

492| :-------------------------------------------------------------------- | :------------------- | :---------------------------------------------------------------- |600| :-------------------------------------------------------------------------------------------------------------------------- | :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

602| TeammateIdle, TaskCreated, TaskCompleted | Exit code or `continue: false` | Exit code 2 blocks the action with stderr feedback. JSON `{"continue": false, "stopReason": "..."}` also stops the teammate entirely, matching `Stop` hook behavior |

605| WorktreeCreate | path return | Command hook prints path on stdout; HTTP hook returns `hookSpecificOutput.worktreePath`. Hook failure or missing path fails creation |

606| Elicitation | `hookSpecificOutput` | `action` (accept/decline/cancel), `content` (form field values for accept) |

607| ElicitationResult | `hookSpecificOutput` | `action` (accept/decline/cancel), `content` (form field values override) |

608| WorktreeRemove, Notification, SessionEnd, PreCompact, PostCompact, InstructionsLoaded, StopFailure, CwdChanged, FileChanged | None | No decision control. Used for side effects like logging or cleanup |

496 609

497Here are examples of each pattern in action:610Here are examples of each pattern in action:

498 611

499<Tabs>612<Tabs>

500 <Tab title="Top-level decision">613 <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:614 Used by `UserPromptSubmit`, `PostToolUse`, `PostToolUseFailure`, `Stop`, `SubagentStop`, and `ConfigChange`. 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 615

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

504 {617 {

551 664

552Runs when Claude Code starts a new session or resumes an existing session. Useful for loading development context like existing issues or recent changes to your codebase, or setting up environment variables. For static context that does not require a script, use [CLAUDE.md](/en/memory) instead.665Runs when Claude Code starts a new session or resumes an existing session. Useful for loading development context like existing issues or recent changes to your codebase, or setting up environment variables. For static context that does not require a script, use [CLAUDE.md](/en/memory) instead.

553 666

554SessionStart runs on every session, so keep these hooks fast.667SessionStart runs on every session, so keep these hooks fast. Only `type: "command"` hooks are supported.

555 668

556The matcher value corresponds to how the session was initiated:669The matcher value corresponds to how the session was initiated:

557 670

571 "session_id": "abc123",684 "session_id": "abc123",

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

573 "cwd": "/Users/...",686 "cwd": "/Users/...",

574 "permission_mode": "default",

575 "hook_event_name": "SessionStart",687 "hook_event_name": "SessionStart",

576 "source": "startup",688 "source": "startup",

577 "model": "claude-sonnet-4-5-20250929"689 "model": "claude-sonnet-4-6"

578}690}

579```691```

580 692

635Any variables written to this file will be available in all subsequent Bash commands that Claude Code executes during the session.747Any variables written to this file will be available in all subsequent Bash commands that Claude Code executes during the session.

636 748

637<Note>749<Note>

638 `CLAUDE_ENV_FILE` is available for SessionStart hooks. Other hook types do not have access to this variable.750 `CLAUDE_ENV_FILE` is available for SessionStart, [CwdChanged](#cwdchanged), and [FileChanged](#filechanged) hooks. Other hook types do not have access to this variable.

639</Note>751</Note>

640 752

753### InstructionsLoaded

754

755Fires when a `CLAUDE.md` or `.claude/rules/*.md` file is loaded into context. This event fires at session start for eagerly-loaded files and again later when files are lazily loaded, for example when Claude accesses a subdirectory that contains a nested `CLAUDE.md` or when conditional rules with `paths:` frontmatter match. The hook does not support blocking or decision control. It runs asynchronously for observability purposes.

756

757The matcher runs against `load_reason`. For example, use `"matcher": "session_start"` to fire only for files loaded at session start, or `"matcher": "path_glob_match|nested_traversal"` to fire only for lazy loads.

758

759#### InstructionsLoaded input

760

761In addition to the [common input fields](#common-input-fields), InstructionsLoaded hooks receive these fields:

762

763| Field | Description |

764| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

765| `file_path` | Absolute path to the instruction file that was loaded |

766| `memory_type` | Scope of the file: `"User"`, `"Project"`, `"Local"`, or `"Managed"` |

767| `load_reason` | Why the file was loaded: `"session_start"`, `"nested_traversal"`, `"path_glob_match"`, `"include"`, or `"compact"`. The `"compact"` value fires when instruction files are re-loaded after a compaction event |

768| `globs` | Path glob patterns from the file's `paths:` frontmatter, if any. Present only for `path_glob_match` loads |

769| `trigger_file_path` | Path to the file whose access triggered this load, for lazy loads |

770| `parent_file_path` | Path to the parent instruction file that included this one, for `include` loads |

771

772```json theme={null}

773{

774 "session_id": "abc123",

775 "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",

776 "cwd": "/Users/my-project",

777 "hook_event_name": "InstructionsLoaded",

778 "file_path": "/Users/my-project/CLAUDE.md",

779 "memory_type": "Project",

780 "load_reason": "session_start"

781}

782```

783

784#### InstructionsLoaded decision control

785

786InstructionsLoaded hooks have no decision control. They cannot block or modify instruction loading. Use this event for audit logging, compliance tracking, or observability.

787

641### UserPromptSubmit788### UserPromptSubmit

642 789

643Runs when the user submits a prompt, before Claude processes it. This allows you790Runs when the user submits a prompt, before Claude processes it. This allows you

696 843

697### PreToolUse844### PreToolUse

698 845

699Runs after Claude creates tool parameters and before processing the tool call. Matches on tool name: `Bash`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Task`, `WebFetch`, `WebSearch`, and any [MCP tool names](#match-mcp-tools).846Runs after Claude creates tool parameters and before processing the tool call. Matches on tool name: `Bash`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Agent`, `WebFetch`, `WebSearch`, `AskUserQuestion`, `ExitPlanMode`, and any [MCP tool names](#match-mcp-tools).

700 847

701Use [PreToolUse decision control](#pretooluse-decision-control) to allow, deny, or ask for permission to use the tool.848Use [PreToolUse decision control](#pretooluse-decision-control) to allow, deny, or ask for permission to use the tool.

702 849

788 935

789##### Task936##### Agent

790 937

791Spawns a [subagent](/en/sub-agents).938Spawns a [subagent](/en/sub-agents).

792 939

799 946

947##### AskUserQuestion

948

949Asks the user one to four multiple-choice questions.

950

952| :---------- | :----- | :----------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

953| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React"}], "multiSelect": false}]` | Questions to present, each with a `question` string, short `header`, `options` array, and optional `multiSelect` flag |

954| `answers` | object | `{"Which framework?": "React"}` | Optional. Maps question text to the selected option label. Multi-select answers join labels with commas. Claude does not set this field; supply it via `updatedInput` to answer programmatically |

955

800#### PreToolUse decision control956#### PreToolUse decision control

801 957

802`PreToolUse` hooks can control whether a tool call proceeds. Unlike other hooks that use a top-level `decision` field, PreToolUse returns its decision inside a `hookSpecificOutput` object. This gives it richer control: three outcomes (allow, deny, or ask) plus the ability to modify tool input before execution.958`PreToolUse` hooks can control whether a tool call proceeds. Unlike other hooks that use a top-level `decision` field, PreToolUse returns its decision inside a `hookSpecificOutput` object. This gives it richer control: three outcomes (allow, deny, or ask) plus the ability to modify tool input before execution.

803 959

804| Field | Description |960| Field | Description |

805| :------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- |961| :------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

806| `permissionDecision` | `"allow"` bypasses the permission system, `"deny"` prevents the tool call, `"ask"` prompts the user to confirm |962| `permissionDecision` | `"allow"` skips the permission prompt. `"deny"` prevents the tool call. `"ask"` prompts the user to confirm. [Deny and ask rules](/en/permissions#manage-permissions) still apply when a hook returns `"allow"` |

807| `permissionDecisionReason` | For `"allow"` and `"ask"`, shown to the user but not Claude. For `"deny"`, shown to Claude |963| `permissionDecisionReason` | For `"allow"` and `"ask"`, shown to the user but not Claude. For `"deny"`, shown to Claude |

808| `updatedInput` | Modifies the tool's input parameters before execution. Combine with `"allow"` to auto-approve, or `"ask"` to show the modified input to the user |964| `updatedInput` | Modifies the tool's input parameters before execution. Replaces the entire input object, so include unchanged fields alongside modified ones. Combine with `"allow"` to auto-approve, or `"ask"` to show the modified input to the user |

810 966

967When a hook returns `"ask"`, the permission prompt displayed to the user includes a label identifying where the hook came from: for example, `[User]`, `[Project]`, `[Plugin]`, or `[Local]`. This helps users understand which configuration source is requesting confirmation.

968

811```json theme={null}969```json theme={null}

812{970{

813 "hookSpecificOutput": {971 "hookSpecificOutput": {

822}980}

823```981```

824 982

983`AskUserQuestion` and `ExitPlanMode` require user interaction and normally block in [non-interactive mode](/en/headless) with the `-p` flag. Returning `permissionDecision: "allow"` together with `updatedInput` satisfies that requirement: the hook reads the tool's input from stdin, collects the answer through your own UI, and returns it in `updatedInput` so the tool runs without prompting. Returning `"allow"` alone is not sufficient for these tools. For `AskUserQuestion`, echo back the original `questions` array and add an [`answers`](#askuserquestion) object mapping each question's text to the chosen answer.

984

825<Note>985<Note>

826 PreToolUse previously used top-level `decision` and `reason` fields, but these are deprecated for this event. Use `hookSpecificOutput.permissionDecision` and `hookSpecificOutput.permissionDecisionReason` instead. The deprecated values `"approve"` and `"block"` map to `"allow"` and `"deny"` respectively. Other events like PostToolUse and Stop continue to use top-level `decision` and `reason` as their current format.986 PreToolUse previously used top-level `decision` and `reason` fields, but these are deprecated for this event. Use `hookSpecificOutput.permissionDecision` and `hookSpecificOutput.permissionDecisionReason` instead. The deprecated values `"approve"` and `"block"` map to `"allow"` and `"deny"` respectively. Other events like PostToolUse and Stop continue to use top-level `decision` and `reason` as their current format.

827</Note>987</Note>

850 "description": "Remove node_modules directory"1010 "description": "Remove node_modules directory"

851 },1011 },

852 "permission_suggestions": [1012 "permission_suggestions": [

853 { "type": "toolAlwaysAllow", "tool": "Bash" }1013 {

1014 "type": "addRules",

1015 "rules": [{ "toolName": "Bash", "ruleContent": "rm -rf node_modules" }],

1016 "behavior": "allow",

1017 "destination": "localSettings"

1018 }

854 ]1019 ]

855}1020}

856```1021```

860`PermissionRequest` hooks can allow or deny permission requests. In addition to the [JSON output fields](#json-output) available to all hooks, your hook script can return a `decision` object with these event-specific fields:1025`PermissionRequest` hooks can allow or deny permission requests. In addition to the [JSON output fields](#json-output) available to all hooks, your hook script can return a `decision` object with these event-specific fields:

861 1026

862| Field | Description |1027| Field | Description |

863| :------------------- | :------------------------------------------------------------------------------------------------------------- |1028| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

865| `updatedInput` | For `"allow"` only: modifies the tool's input parameters before execution |1030| `updatedInput` | For `"allow"` only: modifies the tool's input parameters before execution. Replaces the entire input object, so include unchanged fields alongside modified ones |

866| `updatedPermissions` | For `"allow"` only: applies permission rule updates, equivalent to the user selecting an "always allow" option |1031| `updatedPermissions` | For `"allow"` only: array of [permission update entries](#permission-update-entries) to apply, such as adding an allow rule or changing the session permission mode |

869 1034

881}1046}

882```1047```

883 1048

1049#### Permission update entries

1050

1051The `updatedPermissions` output field and the [`permission_suggestions` input field](#permissionrequest-input) both use the same array of entry objects. Each entry has a `type` that determines its other fields, and a `destination` that controls where the change is written.

1052

1053| `type` | Fields | Effect |

1054| :------------------ | :--------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1055| `addRules` | `rules`, `behavior`, `destination` | Adds permission rules. `rules` is an array of `{toolName, ruleContent?}` objects. Omit `ruleContent` to match the whole tool. `behavior` is `"allow"`, `"deny"`, or `"ask"` |

1056| `replaceRules` | `rules`, `behavior`, `destination` | Replaces all rules of the given `behavior` at the `destination` with the provided `rules` |

1057| `removeRules` | `rules`, `behavior`, `destination` | Removes matching rules of the given `behavior` |

1058| `setMode` | `mode`, `destination` | Changes the permission mode. Valid modes are `default`, `acceptEdits`, `dontAsk`, `bypassPermissions`, and `plan` |

1059| `addDirectories` | `directories`, `destination` | Adds working directories. `directories` is an array of path strings |

1060| `removeDirectories` | `directories`, `destination` | Removes working directories |

1061

1062The `destination` field on every entry determines whether the change stays in memory or persists to a settings file.

1063

1064| `destination` | Writes to |

1065| :---------------- | :---------------------------------------------- |

1066| `session` | in-memory only, discarded when the session ends |

1067| `localSettings` | `.claude/settings.local.json` |

1068| `projectSettings` | `.claude/settings.json` |

1069| `userSettings` | `~/.claude/settings.json` |

1070

1071A hook can echo one of the `permission_suggestions` it received as its own `updatedPermissions` output, which is equivalent to the user selecting that "always allow" option in the dialog.

1072

884### PostToolUse1073### PostToolUse

885 1074

886Runs immediately after a tool completes successfully.1075Runs immediately after a tool completes successfully.

1025 "session_id": "abc123",1214 "session_id": "abc123",

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

1027 "cwd": "/Users/...",1216 "cwd": "/Users/...",

1028 "permission_mode": "default",

1029 "hook_event_name": "Notification",1217 "hook_event_name": "Notification",

1030 "message": "Claude needs your permission to use Bash",1218 "message": "Claude needs your permission to use Bash",

1031 "title": "Permission needed",1219 "title": "Permission needed",

1041 1229

1042### SubagentStart1230### SubagentStart

1043 1231

1044Runs when a Claude Code subagent is spawned via the Task tool. Supports matchers to filter by agent type name (built-in agents like `Bash`, `Explore`, `Plan`, or custom agent names from `.claude/agents/`).1232Runs when a Claude Code subagent is spawned via the Agent tool. Supports matchers to filter by agent type name (built-in agents like `Bash`, `Explore`, `Plan`, or custom agent names from `.claude/agents/`).

1045 1233

1046#### SubagentStart input1234#### SubagentStart input

1047 1235

1052 "session_id": "abc123",1240 "session_id": "abc123",

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

1054 "cwd": "/Users/...",1242 "cwd": "/Users/...",

1055 "permission_mode": "default",

1056 "hook_event_name": "SubagentStart",1243 "hook_event_name": "SubagentStart",

1057 "agent_id": "agent-abc123",1244 "agent_id": "agent-abc123",

1058 "agent_type": "Explore"1245 "agent_type": "Explore"

1080 1267

1081#### SubagentStop input1268#### SubagentStop input

1082 1269

1083In addition to the [common input fields](#common-input-fields), SubagentStop hooks receive `stop_hook_active`, `agent_id`, `agent_type`, and `agent_transcript_path`. The `agent_type` field is the value used for matcher filtering. The `transcript_path` is the main session's transcript, while `agent_transcript_path` is the subagent's own transcript stored in a nested `subagents/` folder.1270In addition to the [common input fields](#common-input-fields), SubagentStop hooks receive `stop_hook_active`, `agent_id`, `agent_type`, `agent_transcript_path`, and `last_assistant_message`. The `agent_type` field is the value used for matcher filtering. The `transcript_path` is the main session's transcript, while `agent_transcript_path` is the subagent's own transcript stored in a nested `subagents/` folder. The `last_assistant_message` field contains the text content of the subagent's final response, so hooks can access it without parsing the transcript file.

1084 1271

1085```json theme={null}1272```json theme={null}

1086{1273{

1092 "stop_hook_active": false,1279 "stop_hook_active": false,

1093 "agent_id": "def456",1280 "agent_id": "def456",

1094 "agent_type": "Explore",1281 "agent_type": "Explore",

1095 "agent_transcript_path": "~/.claude/projects/.../abc123/subagents/agent-def456.jsonl"1282 "agent_transcript_path": "~/.claude/projects/.../abc123/subagents/agent-def456.jsonl",

1283 "last_assistant_message": "Analysis complete. Found 3 potential issues..."

1096}1284}

1097```1285```

1098 1286

1099SubagentStop hooks use the same decision control format as [Stop hooks](#stop-decision-control).1287SubagentStop hooks use the same decision control format as [Stop hooks](#stop-decision-control).

1100 1288

1289### TaskCreated

1290

1291Runs when a task is being created via the `TaskCreate` tool. Use this to enforce naming conventions, require task descriptions, or prevent certain tasks from being created.

1292

1293When a `TaskCreated` hook exits with code 2, the task is not created and the stderr message is fed back to the model as feedback. To stop the teammate entirely instead of re-running it, return JSON with `{"continue": false, "stopReason": "..."}`. TaskCreated hooks do not support matchers and fire on every occurrence.

1294

1295#### TaskCreated input

1296

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

1298

1299```json theme={null}

1300{

1301 "session_id": "abc123",

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

1303 "cwd": "/Users/...",

1304 "permission_mode": "default",

1305 "hook_event_name": "TaskCreated",

1306 "task_id": "task-001",

1307 "task_subject": "Implement user authentication",

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

1309 "teammate_name": "implementer",

1310 "team_name": "my-project"

1311}

1312```

1313

1314| Field | Description |

1315| :----------------- | :---------------------------------------------------- |

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

1317| `task_subject` | Title of the task |

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

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

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

1321

1322#### TaskCreated decision control

1323

1324TaskCreated hooks support two ways to control task creation:

1325

1326* **Exit code 2**: the task is not created and the stderr message is fed back to the model as feedback.

1327* **JSON `{"continue": false, "stopReason": "..."}`**: stops the teammate entirely, matching `Stop` hook behavior. The `stopReason` is shown to the user.

1328

1329This example blocks tasks whose subjects don't follow the required format:

1330

1331```bash theme={null}

1332#!/bin/bash

1333INPUT=$(cat)

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

1335

1336if [[ ! "$TASK_SUBJECT" =~ ^\[TICKET-[0-9]+\] ]]; then

1337 echo "Task subject must start with a ticket number, e.g. '[TICKET-123] Add feature'" >&2

1338 exit 2

1339fi

1340

1341exit 0

1342```

1343

1344### TaskCompleted

1345

1346Runs 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.

1347

1348When 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. To stop the teammate entirely instead of re-running it, return JSON with `{"continue": false, "stopReason": "..."}`. TaskCompleted hooks do not support matchers and fire on every occurrence.

1349

1350#### TaskCompleted input

1351

1352In 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`.

1353

1354```json theme={null}

1355{

1356 "session_id": "abc123",

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

1358 "cwd": "/Users/...",

1359 "permission_mode": "default",

1360 "hook_event_name": "TaskCompleted",

1361 "task_id": "task-001",

1362 "task_subject": "Implement user authentication",

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

1364 "teammate_name": "implementer",

1365 "team_name": "my-project"

1366}

1367```

1368

1369| Field | Description |

1370| :----------------- | :------------------------------------------------------ |

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

1372| `task_subject` | Title of the task |

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

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

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

1376

1377#### TaskCompleted decision control

1378

1379TaskCompleted hooks support two ways to control task completion:

1380

1381* **Exit code 2**: the task is not marked as completed and the stderr message is fed back to the model as feedback.

1382* **JSON `{"continue": false, "stopReason": "..."}`**: stops the teammate entirely, matching `Stop` hook behavior. The `stopReason` is shown to the user.

1383

1384This example runs tests and blocks task completion if they fail:

1385

1386```bash theme={null}

1387#!/bin/bash

1388INPUT=$(cat)

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

1390

1391# Run the test suite

1392if ! npm test 2>&1; then

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

1394 exit 2

1395fi

1396

1397exit 0

1398```

1399

1101### Stop1400### Stop

1102 1401

1103Runs when the main Claude Code agent has finished responding. Does not run if1402Runs when the main Claude Code agent has finished responding. Does not run if

1104the stoppage occurred due to a user interrupt.1403the stoppage occurred due to a user interrupt. API errors fire

1404[StopFailure](#stopfailure) instead.

1105 1405

1106#### Stop input1406#### Stop input

1107 1407

1108In addition to the [common input fields](#common-input-fields), Stop hooks receive `stop_hook_active`. This field is `true` when Claude Code is already continuing as a result of a stop hook. Check this value or process the transcript to prevent Claude Code from running indefinitely.1408In addition to the [common input fields](#common-input-fields), Stop hooks receive `stop_hook_active` and `last_assistant_message`. The `stop_hook_active` field is `true` when Claude Code is already continuing as a result of a stop hook. Check this value or process the transcript to prevent Claude Code from running indefinitely. The `last_assistant_message` field contains the text content of Claude's final response, so hooks can access it without parsing the transcript file.

1109 1409

1110```json theme={null}1410```json theme={null}

1111{1411{

1114 "cwd": "/Users/...",1414 "cwd": "/Users/...",

1115 "permission_mode": "default",1415 "permission_mode": "default",

1116 "hook_event_name": "Stop",1416 "hook_event_name": "Stop",

1117 "stop_hook_active": true1417 "stop_hook_active": true,

1418 "last_assistant_message": "I've completed the refactoring. Here's a summary..."

1118}1419}

1119```1420```

1120 1421

1134}1435}

1135```1436```

1136 1437

1438### StopFailure

1439

1440Runs instead of [Stop](#stop) when the turn ends due to an API error. Output and exit code are ignored. Use this to log failures, send alerts, or take recovery actions when Claude cannot complete a response due to rate limits, authentication problems, or other API errors.

1441

1442#### StopFailure input

1443

1444In addition to the [common input fields](#common-input-fields), StopFailure hooks receive `error`, optional `error_details`, and optional `last_assistant_message`. The `error` field identifies the error type and is used for matcher filtering.

1445

1446| Field | Description |

1447| :----------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1448| `error` | Error type: `rate_limit`, `authentication_failed`, `billing_error`, `invalid_request`, `server_error`, `max_output_tokens`, or `unknown` |

1449| `error_details` | Additional details about the error, when available |

1450| `last_assistant_message` | The rendered error text shown in the conversation. Unlike `Stop` and `SubagentStop`, where this field holds Claude's conversational output, for `StopFailure` it contains the API error string itself, such as `"API Error: Rate limit reached"` |

1451

1452```json theme={null}

1453{

1454 "session_id": "abc123",

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

1456 "cwd": "/Users/...",

1457 "hook_event_name": "StopFailure",

1458 "error": "rate_limit",

1459 "error_details": "429 Too Many Requests",

1460 "last_assistant_message": "API Error: Rate limit reached"

1461}

1462```

1463

1464StopFailure hooks have no decision control. They run for notification and logging purposes only.

1465

1466### TeammateIdle

1467

1468Runs 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.

1469

1470When a `TeammateIdle` hook exits with code 2, the teammate receives the stderr message as feedback and continues working instead of going idle. To stop the teammate entirely instead of re-running it, return JSON with `{"continue": false, "stopReason": "..."}`. TeammateIdle hooks do not support matchers and fire on every occurrence.

1471

1472#### TeammateIdle input

1473

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

1475

1476```json theme={null}

1477{

1478 "session_id": "abc123",

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

1480 "cwd": "/Users/...",

1481 "permission_mode": "default",

1482 "hook_event_name": "TeammateIdle",

1483 "teammate_name": "researcher",

1484 "team_name": "my-project"

1485}

1486```

1487

1488| Field | Description |

1489| :-------------- | :-------------------------------------------- |

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

1491| `team_name` | Name of the team |

1492

1493#### TeammateIdle decision control

1494

1495TeammateIdle hooks support two ways to control teammate behavior:

1496

1497* **Exit code 2**: the teammate receives the stderr message as feedback and continues working instead of going idle.

1498* **JSON `{"continue": false, "stopReason": "..."}`**: stops the teammate entirely, matching `Stop` hook behavior. The `stopReason` is shown to the user.

1499

1500This example checks that a build artifact exists before allowing a teammate to go idle:

1501

1502```bash theme={null}

1503#!/bin/bash

1504

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

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

1507 exit 2

1508fi

1509

1510exit 0

1511```

1512

1513### ConfigChange

1514

1515Runs when a configuration file changes during a session. Use this to audit settings changes, enforce security policies, or block unauthorized modifications to configuration files.

1516

1517ConfigChange hooks fire for changes to settings files, managed policy settings, and skill files. The `source` field in the input tells you which type of configuration changed, and the optional `file_path` field provides the path to the changed file.

1518

1519The matcher filters on the configuration source:

1520

1521| Matcher | When it fires |

1522| :----------------- | :---------------------------------------- |

1523| `user_settings` | `~/.claude/settings.json` changes |

1524| `project_settings` | `.claude/settings.json` changes |

1525| `local_settings` | `.claude/settings.local.json` changes |

1526| `policy_settings` | Managed policy settings change |

1527| `skills` | A skill file in `.claude/skills/` changes |

1528

1529This example logs all configuration changes for security auditing:

1530

1531```json theme={null}

1532{

1533 "hooks": {

1534 "ConfigChange": [

1535 {

1536 "hooks": [

1537 {

1538 "type": "command",

1539 "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/audit-config-change.sh"

1540 }

1541 ]

1542 }

1543 ]

1544 }

1545}

1546```

1547

1548#### ConfigChange input

1549

1550In addition to the [common input fields](#common-input-fields), ConfigChange hooks receive `source` and optionally `file_path`. The `source` field indicates which configuration type changed, and `file_path` provides the path to the specific file that was modified.

1551

1552```json theme={null}

1553{

1554 "session_id": "abc123",

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

1556 "cwd": "/Users/...",

1557 "hook_event_name": "ConfigChange",

1558 "source": "project_settings",

1559 "file_path": "/Users/.../my-project/.claude/settings.json"

1560}

1561```

1562

1563#### ConfigChange decision control

1564

1565ConfigChange hooks can block configuration changes from taking effect. Use exit code 2 or a JSON `decision` to prevent the change. When blocked, the new settings are not applied to the running session.

1566

1567| Field | Description |

1568| :--------- | :--------------------------------------------------------------------------------------- |

1569| `decision` | `"block"` prevents the configuration change from being applied. Omit to allow the change |

1570| `reason` | Explanation shown to the user when `decision` is `"block"` |

1571

1572```json theme={null}

1573{

1574 "decision": "block",

1575 "reason": "Configuration changes to project settings require admin approval"

1576}

1577```

1578

1579`policy_settings` changes cannot be blocked. Hooks still fire for `policy_settings` sources, so you can use them for audit logging, but any blocking decision is ignored. This ensures enterprise-managed settings always take effect.

1580

1581### CwdChanged

1582

1583Runs when the working directory changes during a session, for example when Claude executes a `cd` command. Use this to react to directory changes: reload environment variables, activate project-specific toolchains, or run setup scripts automatically. Pairs with [FileChanged](#filechanged) for tools like [direnv](https://direnv.net/) that manage per-directory environment.

1584

1585CwdChanged hooks have access to `CLAUDE_ENV_FILE`. Variables written to that file persist into subsequent Bash commands for the session, just as in [SessionStart hooks](#persist-environment-variables). Only `type: "command"` hooks are supported.

1586

1587CwdChanged does not support matchers and fires on every directory change.

1588

1589#### CwdChanged input

1590

1591In addition to the [common input fields](#common-input-fields), CwdChanged hooks receive `old_cwd` and `new_cwd`.

1592

1593```json theme={null}

1594{

1595 "session_id": "abc123",

1596 "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",

1597 "cwd": "/Users/my-project/src",

1598 "hook_event_name": "CwdChanged",

1599 "old_cwd": "/Users/my-project",

1600 "new_cwd": "/Users/my-project/src"

1601}

1602```

1603

1604#### CwdChanged output

1605

1606In addition to the [JSON output fields](#json-output) available to all hooks, CwdChanged hooks can return `watchPaths` to dynamically set which file paths [FileChanged](#filechanged) watches:

1607

1608| Field | Description |

1609| :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

1610| `watchPaths` | Array of absolute paths. Replaces the current dynamic watch list (paths from your `matcher` configuration are always watched). Returning an empty array clears the dynamic list, which is typical when entering a new directory |

1611

1612CwdChanged hooks have no decision control. They cannot block the directory change.

1613

1614### FileChanged

1615

1616Runs when a watched file changes on disk. The `matcher` field in your hook configuration controls which filenames to watch: it is a pipe-separated list of basenames (filenames without directory paths, for example `".envrc|.env"`). The same `matcher` value is also used to filter which hooks run when a file changes, matching against the basename of the changed file. Useful for reloading environment variables when project configuration files are modified.

1617

1618FileChanged hooks have access to `CLAUDE_ENV_FILE`. Variables written to that file persist into subsequent Bash commands for the session, just as in [SessionStart hooks](#persist-environment-variables). Only `type: "command"` hooks are supported.

1619

1620#### FileChanged input

1621

1622In addition to the [common input fields](#common-input-fields), FileChanged hooks receive `file_path` and `event`.

1623

1624| Field | Description |

1625| :---------- | :---------------------------------------------------------------------------------------------- |

1626| `file_path` | Absolute path to the file that changed |

1627| `event` | What happened: `"change"` (file modified), `"add"` (file created), or `"unlink"` (file deleted) |

1628

1629```json theme={null}

1630{

1631 "session_id": "abc123",

1632 "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",

1633 "cwd": "/Users/my-project",

1634 "hook_event_name": "FileChanged",

1635 "file_path": "/Users/my-project/.envrc",

1636 "event": "change"

1637}

1638```

1639

1640#### FileChanged output

1641

1642In addition to the [JSON output fields](#json-output) available to all hooks, FileChanged hooks can return `watchPaths` to dynamically update which file paths are watched:

1643

1644| Field | Description |

1645| :----------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1646| `watchPaths` | Array of absolute paths. Replaces the current dynamic watch list (paths from your `matcher` configuration are always watched). Use this when your hook script discovers additional files to watch based on the changed file |

1647

1648FileChanged hooks have no decision control. They cannot block the file change from occurring.

1649

1650### WorktreeCreate

1651

1652When you run `claude --worktree` or a [subagent uses `isolation: "worktree"`](/en/sub-agents#choose-the-subagent-scope), Claude Code creates an isolated working copy using `git worktree`. If you configure a WorktreeCreate hook, it replaces the default git behavior, letting you use a different version control system like SVN, Perforce, or Mercurial.

1653

1654Because the hook replaces the default behavior entirely, [`.worktreeinclude`](/en/common-workflows#copy-gitignored-files-to-worktrees) is not processed. If you need to copy local configuration files like `.env` into the new worktree, do it inside your hook script.

1655

1656The hook must return the absolute path to the created worktree directory. Claude Code uses this path as the working directory for the isolated session. Command hooks print it on stdout; HTTP hooks return it via `hookSpecificOutput.worktreePath`.

1657

1658This example creates an SVN working copy and prints the path for Claude Code to use. Replace the repository URL with your own:

1659

1660```json theme={null}

1661{

1662 "hooks": {

1663 "WorktreeCreate": [

1664 {

1665 "hooks": [

1666 {

1667 "type": "command",

1668 "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"

1669 }

1670 ]

1671 }

1672 ]

1673 }

1674}

1675```

1676

1677The hook reads the worktree `name` from the JSON input on stdin, checks out a fresh copy into a new directory, and prints the directory path. The `echo` on the last line is what Claude Code reads as the worktree path. Redirect any other output to stderr so it doesn't interfere with the path.

1678

1679#### WorktreeCreate input

1680

1681In addition to the [common input fields](#common-input-fields), WorktreeCreate hooks receive the `name` field. This is a slug identifier for the new worktree, either specified by the user or auto-generated (for example, `bold-oak-a3f2`).

1682

1683```json theme={null}

1684{

1685 "session_id": "abc123",

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

1687 "cwd": "/Users/...",

1688 "hook_event_name": "WorktreeCreate",

1689 "name": "feature-auth"

1690}

1691```

1692

1693#### WorktreeCreate output

1694

1695WorktreeCreate hooks do not use the standard allow/block decision model. Instead, the hook's success or failure determines the outcome. The hook must return the absolute path to the created worktree directory:

1696

1697* **Command hooks** (`type: "command"`): print the path on stdout.

1698* **HTTP hooks** (`type: "http"`): return `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` in the response body.

1699

1700If the hook fails or produces no path, worktree creation fails with an error.

1701

1702### WorktreeRemove

1703

1704The cleanup counterpart to [WorktreeCreate](#worktreecreate). This hook fires when a worktree is being removed, either when you exit a `--worktree` session and choose to remove it, or when a subagent with `isolation: "worktree"` finishes. For git-based worktrees, Claude handles cleanup automatically with `git worktree remove`. If you configured a WorktreeCreate hook for a non-git version control system, pair it with a WorktreeRemove hook to handle cleanup. Without one, the worktree directory is left on disk.

1705

1706Claude Code passes the path returned by WorktreeCreate as `worktree_path` in the hook input. This example reads that path and removes the directory:

1707

1708```json theme={null}

1709{

1710 "hooks": {

1711 "WorktreeRemove": [

1712 {

1713 "hooks": [

1714 {

1715 "type": "command",

1716 "command": "bash -c 'jq -r .worktree_path | xargs rm -rf'"

1717 }

1718 ]

1719 }

1720 ]

1721 }

1722}

1723```

1724

1725#### WorktreeRemove input

1726

1727In addition to the [common input fields](#common-input-fields), WorktreeRemove hooks receive the `worktree_path` field, which is the absolute path to the worktree being removed.

1728

1729```json theme={null}

1730{

1731 "session_id": "abc123",

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

1733 "cwd": "/Users/...",

1734 "hook_event_name": "WorktreeRemove",

1735 "worktree_path": "/Users/.../my-project/.claude/worktrees/feature-auth"

1736}

1737```

1738

1739WorktreeRemove hooks have no decision control. They cannot block worktree removal but can perform cleanup tasks like removing version control state or archiving changes. Hook failures are logged in debug mode only.

1740

1137### PreCompact1741### PreCompact

1138 1742

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

1154 "session_id": "abc123",1758 "session_id": "abc123",

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

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

1157 "permission_mode": "default",

1158 "hook_event_name": "PreCompact",1761 "hook_event_name": "PreCompact",

1159 "trigger": "manual",1762 "trigger": "manual",

1160 "custom_instructions": ""1763 "custom_instructions": ""

1161}1764}

1162```1765```

1163 1766

1767### PostCompact

1768

1769Runs after Claude Code completes a compact operation. Use this event to react to the new compacted state, for example to log the generated summary or update external state.

1770

1771The same matcher values apply as for `PreCompact`:

1772

1773| Matcher | When it fires |

1774| :------- | :------------------------------------------------- |

1775| `manual` | After `/compact` |

1776| `auto` | After auto-compact when the context window is full |

1777

1778#### PostCompact input

1779

1780In addition to the [common input fields](#common-input-fields), PostCompact hooks receive `trigger` and `compact_summary`. The `compact_summary` field contains the conversation summary generated by the compact operation.

1781

1782```json theme={null}

1783{

1784 "session_id": "abc123",

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

1786 "cwd": "/Users/...",

1787 "hook_event_name": "PostCompact",

1788 "trigger": "manual",

1789 "compact_summary": "Summary of the compacted conversation..."

1790}

1791```

1792

1793PostCompact hooks have no decision control. They cannot affect the compaction result but can perform follow-up tasks.

1794

1164### SessionEnd1795### SessionEnd

1165 1796

1166Runs when a Claude Code session ends. Useful for cleanup tasks, logging session1797Runs when a Claude Code session ends. Useful for cleanup tasks, logging session

1171| Reason | Description |1802| Reason | Description |

1172| :---------------------------- | :----------------------------------------- |1803| :---------------------------- | :----------------------------------------- |

1805| `resume` | Session switched via interactive `/resume` |

1185 "session_id": "abc123",1817 "session_id": "abc123",

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

1187 "cwd": "/Users/...",1819 "cwd": "/Users/...",

1188 "permission_mode": "default",

1189 "hook_event_name": "SessionEnd",1820 "hook_event_name": "SessionEnd",

1190 "reason": "other"1821 "reason": "other"

1191}1822}

1193 1824

1194SessionEnd hooks have no decision control. They cannot block session termination but can perform cleanup tasks.1825SessionEnd hooks have no decision control. They cannot block session termination but can perform cleanup tasks.

1195 1826

1827SessionEnd hooks have a default timeout of 1.5 seconds. This applies to session exit, `/clear`, and switching sessions via interactive `/resume`. If your hooks need more time, set the `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` environment variable to a higher value in milliseconds. Any per-hook `timeout` setting is also capped by this value.

1828

1829```bash theme={null}

1830CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude

1831```

1832

1833### Elicitation

1834

1835Runs when an MCP server requests user input mid-task. By default, Claude Code shows an interactive dialog for the user to respond. Hooks can intercept this request and respond programmatically, skipping the dialog entirely.

1836

1837The matcher field matches against the MCP server name.

1838

1839#### Elicitation input

1840

1841In addition to the [common input fields](#common-input-fields), Elicitation hooks receive `mcp_server_name`, `message`, and optional `mode`, `url`, `elicitation_id`, and `requested_schema` fields.

1842

1843For form-mode elicitation (the most common case):

1844

1845```json theme={null}

1846{

1847 "session_id": "abc123",

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

1849 "cwd": "/Users/...",

1850 "permission_mode": "default",

1851 "hook_event_name": "Elicitation",

1852 "mcp_server_name": "my-mcp-server",

1853 "message": "Please provide your credentials",

1854 "mode": "form",

1855 "requested_schema": {

1856 "type": "object",

1857 "properties": {

1858 "username": { "type": "string", "title": "Username" }

1859 }

1860 }

1861}

1862```

1863

1864For URL-mode elicitation (browser-based authentication):

1865

1866```json theme={null}

1867{

1868 "session_id": "abc123",

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

1870 "cwd": "/Users/...",

1871 "permission_mode": "default",

1872 "hook_event_name": "Elicitation",

1873 "mcp_server_name": "my-mcp-server",

1874 "message": "Please authenticate",

1875 "mode": "url",

1876 "url": "https://auth.example.com/login"

1877}

1878```

1879

1880#### Elicitation output

1881

1882To respond programmatically without showing the dialog, return a JSON object with `hookSpecificOutput`:

1883

1884```json theme={null}

1885{

1886 "hookSpecificOutput": {

1887 "hookEventName": "Elicitation",

1888 "action": "accept",

1889 "content": {

1890 "username": "alice"

1891 }

1892 }

1893}

1894```

1895

1896| Field | Values | Description |

1897| :-------- | :---------------------------- | :--------------------------------------------------------------- |

1898| `action` | `accept`, `decline`, `cancel` | Whether to accept, decline, or cancel the request |

1899| `content` | object | Form field values to submit. Only used when `action` is `accept` |

1900

1901Exit code 2 denies the elicitation and shows stderr to the user.

1902

1903### ElicitationResult

1904

1905Runs after a user responds to an MCP elicitation. Hooks can observe, modify, or block the response before it is sent back to the MCP server.

1906

1907The matcher field matches against the MCP server name.

1908

1909#### ElicitationResult input

1910

1911In addition to the [common input fields](#common-input-fields), ElicitationResult hooks receive `mcp_server_name`, `action`, and optional `mode`, `elicitation_id`, and `content` fields.

1912

1913```json theme={null}

1914{

1915 "session_id": "abc123",

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

1917 "cwd": "/Users/...",

1918 "permission_mode": "default",

1919 "hook_event_name": "ElicitationResult",

1920 "mcp_server_name": "my-mcp-server",

1921 "action": "accept",

1922 "content": { "username": "alice" },

1923 "mode": "form",

1924 "elicitation_id": "elicit-123"

1925}

1926```

1927

1928#### ElicitationResult output

1929

1930To override the user's response, return a JSON object with `hookSpecificOutput`:

1931

1932```json theme={null}

1933{

1934 "hookSpecificOutput": {

1935 "hookEventName": "ElicitationResult",

1936 "action": "decline",

1937 "content": {}

1938 }

1939}

1940```

1941

1942| Field | Values | Description |

1943| :-------- | :---------------------------- | :--------------------------------------------------------------------- |

1944| `action` | `accept`, `decline`, `cancel` | Overrides the user's action |

1945| `content` | object | Overrides form field values. Only meaningful when `action` is `accept` |

1946

1947Exit code 2 blocks the response, changing the effective action to `decline`.

1948

1196## Prompt-based hooks1949## Prompt-based hooks

1197 1950

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`.1951In addition to command and HTTP hooks, Claude Code supports prompt-based hooks (`type: "prompt"`) that use an LLM to evaluate whether to allow or block an action, and agent hooks (`type: "agent"`) that spawn an agentic verifier with tool access. Not all events support every hook type.

1952

1953Events that support all four hook types (`command`, `http`, `prompt`, and `agent`):

1954

1955* `PermissionRequest`

1956* `PostToolUse`

1957* `PostToolUseFailure`

1958* `PreToolUse`

1959* `Stop`

1960* `SubagentStop`

1961* `TaskCompleted`

1962* `TaskCreated`

1963* `UserPromptSubmit`

1964

1965Events that support `command` and `http` hooks but not `prompt` or `agent`:

1966

1967* `ConfigChange`

1968* `CwdChanged`

1969* `Elicitation`

1970* `ElicitationResult`

1971* `FileChanged`

1972* `InstructionsLoaded`

1973* `Notification`

1974* `PostCompact`

1975* `PreCompact`

1976* `SessionEnd`

1977* `StopFailure`

1978* `SubagentStart`

1979* `TeammateIdle`

1980* `WorktreeCreate`

1981* `WorktreeRemove`

1982

1983`SessionStart` supports only `command` hooks.

1199 1984

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

1201 1986

1359 2144

1360After the background process exits, if the hook produced a JSON response with a `systemMessage` or `additionalContext` field, that content is delivered to Claude as context on the next conversation turn.2145After the background process exits, if the hook produced a JSON response with a `systemMessage` or `additionalContext` field, that content is delivered to Claude as context on the next conversation turn.

1361 2146

2147Async hook completion notifications are suppressed by default. To see them, enable verbose mode with `Ctrl+O` or start Claude Code with `--verbose`.

2148

1362### Example: run tests after file changes2149### Example: run tests after file changes

1363 2150

1364This hook starts a test suite in the background whenever Claude writes a file, then reports the results back to Claude when the tests finish. Save this script to `.claude/hooks/run-tests-async.sh` in your project and make it executable with `chmod +x`:2151This hook starts a test suite in the background whenever Claude writes a file, then reports the results back to Claude when the tests finish. Save this script to `.claude/hooks/run-tests-async.sh` in your project and make it executable with `chmod +x`:

1422 2209

1423### Disclaimer2210### Disclaimer

1424 2211

1425Hooks run with your system user's full permissions.2212Command hooks run with your system user's full permissions.

1426 2213

1427<Warning>2214<Warning>

1428 Hooks execute shell commands with your full user permissions. They can modify, delete, or access any files your user account can access. Review and test all hook commands before adding them to your configuration.2215 Command hooks execute shell commands with your full user permissions. They can modify, delete, or access any files your user account can access. Review and test all hook commands before adding them to your configuration.

1429</Warning>2216</Warning>

1430 2217

1431### Security best practices2218### Security best practices

1438* **Use absolute paths**: specify full paths for scripts, using `"$CLAUDE_PROJECT_DIR"` for the project root2225* **Use absolute paths**: specify full paths for scripts, using `"$CLAUDE_PROJECT_DIR"` for the project root

1439* **Skip sensitive files**: avoid `.env`, `.git/`, keys, etc.2226* **Skip sensitive files**: avoid `.env`, `.git/`, keys, etc.

1440 2227

2228## Windows PowerShell tool

2229

2230On Windows, you can run individual hooks in PowerShell by setting `"shell": "powershell"` on a command hook. Hooks spawn PowerShell directly, so this works regardless of whether `CLAUDE_CODE_USE_POWERSHELL_TOOL` is set. Claude Code auto-detects `pwsh.exe` (PowerShell 7+) with a fallback to `powershell.exe` (5.1).

2231

2232```json theme={null}

2233{

2234 "hooks": {

2235 "PostToolUse": [

2236 {

2237 "matcher": "Write",

2238 "hooks": [

2239 {

2240 "type": "command",

2241 "shell": "powershell",

2242 "command": "Write-Host 'File written'"

2243 }

2244 ]

2245 }

2246 ]

2247 }

2248}

2249```

2250

1441## Debug hooks2251## Debug hooks

1442 2252

1443Run `claude --debug` to see hook execution details, including which hooks matched, their exit codes, and output. Toggle verbose mode with `Ctrl+O` to see hook progress in the transcript.2253Run `claude --debug` to see hook execution details, including which hooks matched, their exit codes, and output. Toggle verbose mode with `Ctrl+O` to see hook progress in the transcript.

1444 2254

1445```2255```text theme={null}

1446[DEBUG] Executing hooks for PostToolUse:Write2256[DEBUG] Executing hooks for PostToolUse:Write

1447[DEBUG] Getting matching hook commands for PostToolUse with query: Write2257[DEBUG] Getting matching hook commands for PostToolUse with query: Write

1448[DEBUG] Found 1 hook matchers in settings2258[DEBUG] Found 1 hook matchers in settings

hooks-guide.md +266 −51

Details

18 18

19## Set up your first hook19## Set up your first hook

20 20

21The fastest way to create a hook is through the `/hooks` interactive menu in Claude Code. This walkthrough creates a desktop notification hook, so you get alerted whenever Claude is waiting for your input instead of watching the terminal.21To create a hook, add a `hooks` block to a [settings file](#configure-hook-location). This walkthrough creates a desktop notification hook, so you get alerted whenever Claude is waiting for your input instead of watching the terminal.

22 22

23<Steps>23<Steps>

~~24 <Step title="Open the hooks menu">~~24 <Step title="Add the hook to your settings">

25 Type `/hooks` in the Claude Code CLI. You'll see a list of all available hook events, plus an option to disable all hooks. Each event corresponds to a point in Claude's lifecycle where you can run custom code. Select `Notification` to create a hook that fires when Claude needs your attention.25 Open `~/.claude/settings.json` and add a `Notification` hook. The example below uses `osascript` for macOS; see [Get notified when Claude needs input](#get-notified-when-claude-needs-input) for Linux and Windows commands.

~~26 </Step>~~

~~28 <Step title="Configure the matcher">~~

29 The menu shows a list of matchers, which filter when the hook fires. Set the matcher to `*` to fire on all notification types. You can narrow it later by changing the matcher to a specific value like `permission_prompt` or `idle_prompt`.

~~30 </Step>~~

~~32 <Step title="Add your command">~~

33 Select `+ Add new hook…`. The menu prompts you for a shell command to run when the event fires. Hooks run any shell command you provide, so you can use your platform's built-in notification tool. Copy the command for your OS:

~~35 <Tabs>~~

~~36 <Tab title="macOS">~~

~~37 Uses [`osascript`](https://ss64.com/mac/osascript.html) to trigger a native macOS notification through AppleScript:~~

~~39 ```~~

~~40 osascript -e 'display notification "Claude Code needs your attention" with title "Claude Code"'~~

~~41 ```~~

~~42 </Tab>~~

~~44 <Tab title="Linux">~~

~~45 Uses `notify-send`, which is pre-installed on most Linux desktops with a notification daemon:~~

46 26

27 ```json theme={null}

28 {

29 "hooks": {

30 "Notification": [

31 {

32 "matcher": "",

33 "hooks": [

34 {

35 "type": "command",

36 "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"

37 }

38 ]

39 }

40 ]

41 }

42 }

47 ```43 ```

~~48 notify-send 'Claude Code' 'Claude Code needs your attention'~~

~~49 ```~~

~~50 </Tab>~~

~~52 <Tab title="Windows (PowerShell)">~~

~~53 Uses PowerShell to show a native message box through .NET's Windows Forms:~~

54 44

~~55 ```~~45 If your settings file already has a `hooks` key, merge the `Notification` entry into it rather than replacing the whole object. You can also ask Claude to write the hook for you by describing what you want in the CLI.

56 powershell.exe -Command "[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')"

~~57 ```~~

~~58 </Tab>~~

~~59 </Tabs>~~

60 </Step>46 </Step>

61 47

~~62 <Step title="Choose a storage location">~~48 <Step title="Verify the configuration">

63 The menu asks where to save the hook configuration. Select `User settings` to store it in `~/.claude/settings.json`, which applies the hook to all your projects. You could also choose `Project settings` to scope it to the current project. See [Configure hook location](#configure-hook-location) for all available scopes.49 Type `/hooks` to open the hooks browser. You'll see a list of all available hook events, with a count next to each event that has hooks configured. Select `Notification` to confirm your new hook appears in the list. Selecting the hook shows its details: the event, matcher, type, source file, and command.

64 </Step>50 </Step>

65 51

66 <Step title="Test the hook">52 <Step title="Test the hook">

68 </Step>54 </Step>

69</Steps>55</Steps>

70 56

57<Tip>

58 The `/hooks` menu is read-only. To add, modify, or remove hooks, edit your settings JSON directly or ask Claude to make the change.

59</Tip>

71## What you can automate61## What you can automate

72 62

73Hooks let you run code at key points in Claude Code's lifecycle: format files after edits, block commands before they execute, send notifications when Claude needs input, inject context at session start, and more. For the full list of hook events, see the [Hooks reference](/en/hooks#hook-lifecycle).63Hooks let you run code at key points in Claude Code's lifecycle: format files after edits, block commands before they execute, send notifications when Claude needs input, inject context at session start, and more. For the full list of hook events, see the [Hooks reference](/en/hooks#hook-lifecycle).

78* [Auto-format code after edits](#auto-format-code-after-edits)68* [Auto-format code after edits](#auto-format-code-after-edits)

79* [Block edits to protected files](#block-edits-to-protected-files)69* [Block edits to protected files](#block-edits-to-protected-files)

80* [Re-inject context after compaction](#re-inject-context-after-compaction)70* [Re-inject context after compaction](#re-inject-context-after-compaction)

71* [Audit configuration changes](#audit-configuration-changes)

72* [Reload environment when directory or files change](#reload-environment-when-directory-or-files-change)

73* [Auto-approve specific permission prompts](#auto-approve-specific-permission-prompts)

81 74

82### Get notified when Claude needs input75### Get notified when Claude needs input

83 76

84Get a desktop notification whenever Claude finishes working and needs your input, so you can switch to other tasks without checking the terminal.77Get a desktop notification whenever Claude finishes working and needs your input, so you can switch to other tasks without checking the terminal.

85 78

86This hook uses the `Notification` event, which fires when Claude is waiting for input or permission. Each tab below uses the platform's native notification command. Add this to `~/.claude/settings.json`, or use the [interactive walkthrough](#set-up-your-first-hook) above to configure it with `/hooks`:79This hook uses the `Notification` event, which fires when Claude is waiting for input or permission. Each tab below uses the platform's native notification command. Add this to `~/.claude/settings.json`:

87 80

88<Tabs>81<Tabs>

89 <Tab title="macOS">82 <Tab title="macOS">

104 }97 }

105 }98 }

106 ```99 ```

100

101 <Accordion title="If no notification appears">

102 `osascript` routes notifications through the built-in Script Editor app. If Script Editor doesn't have notification permission, the command fails silently, and macOS won't prompt you to grant it. Run this in Terminal once to make Script Editor appear in your notification settings:

103

104 ```bash theme={null}

105 osascript -e 'display notification "test"'

106 ```

107

108 Nothing will appear yet. Open **System Settings > Notifications**, find **Script Editor** in the list, and turn on **Allow Notifications**. Run the command again to confirm the test notification appears.

109 </Accordion>

107 </Tab>110 </Tab>

108 111

109 <Tab title="Linux">112 <Tab title="Linux">

262 265

263You can replace the `echo` with any command that produces dynamic output, like `git log --oneline -5` to show recent commits. For injecting context on every session start, consider using [CLAUDE.md](/en/memory) instead. For environment variables, see [`CLAUDE_ENV_FILE`](/en/hooks#persist-environment-variables) in the reference.266You can replace the `echo` with any command that produces dynamic output, like `git log --oneline -5` to show recent commits. For injecting context on every session start, consider using [CLAUDE.md](/en/memory) instead. For environment variables, see [`CLAUDE_ENV_FILE`](/en/hooks#persist-environment-variables) in the reference.

264 267

268### Audit configuration changes

269

270Track when settings or skills files change during a session. The `ConfigChange` event fires when an external process or editor modifies a configuration file, so you can log changes for compliance or block unauthorized modifications.

271

272This example appends each change to an audit log. Add this to `~/.claude/settings.json`:

273

274```json theme={null}

275{

276 "hooks": {

277 "ConfigChange": [

278 {

279 "matcher": "",

280 "hooks": [

281 {

282 "type": "command",

283 "command": "jq -c '{timestamp: now | todate, source: .source, file: .file_path}' >> ~/claude-config-audit.log"

284 }

285 ]

286 }

287 ]

288 }

289}

290```

291

292The matcher filters by configuration type: `user_settings`, `project_settings`, `local_settings`, `policy_settings`, or `skills`. To block a change from taking effect, exit with code 2 or return `{"decision": "block"}`. See the [ConfigChange reference](/en/hooks#configchange) for the full input schema.

293

294### Reload environment when directory or files change

295

296Some projects set different environment variables depending on which directory you are in. Tools like [direnv](https://direnv.net/) do this automatically in your shell, but Claude's Bash tool does not pick up those changes on its own.

297

298A `CwdChanged` hook fixes this: it runs each time Claude changes directory, so you can reload the correct variables for the new location. The hook writes the updated values to `CLAUDE_ENV_FILE`, which Claude Code applies before each Bash command. Add this to `~/.claude/settings.json`:

299

300```json theme={null}

301{

302 "hooks": {

303 "CwdChanged": [

304 {

305 "hooks": [

306 {

307 "type": "command",

308 "command": "direnv export bash >> \"$CLAUDE_ENV_FILE\""

309 }

310 ]

311 }

312 ]

313 }

314}

315```

316

317To react to specific files instead of every directory change, use `FileChanged` with a `matcher` listing the filenames to watch (pipe-separated). The `matcher` both configures which files to watch and filters which hooks run. This example watches `.envrc` and `.env` for changes in the current directory:

318

319```json theme={null}

320{

321 "hooks": {

322 "FileChanged": [

323 {

324 "matcher": ".envrc|.env",

325 "hooks": [

326 {

327 "type": "command",

328 "command": "direnv export bash >> \"$CLAUDE_ENV_FILE\""

329 }

330 ]

331 }

332 ]

333 }

334}

335```

336

337See the [CwdChanged](/en/hooks#cwdchanged) and [FileChanged](/en/hooks#filechanged) reference entries for input schemas, `watchPaths` output, and `CLAUDE_ENV_FILE` details.

338

339### Auto-approve specific permission prompts

340

341Skip the approval dialog for tool calls you always allow. This example auto-approves `ExitPlanMode`, the tool Claude calls when it finishes presenting a plan and asks to proceed, so you aren't prompted every time a plan is ready.

342

343Unlike the exit-code examples above, auto-approval requires your hook to write a JSON decision to stdout. A `PermissionRequest` hook fires when Claude Code is about to show a permission dialog, and returning `"behavior": "allow"` answers it on your behalf.

344

345The matcher scopes the hook to `ExitPlanMode` only, so no other prompts are affected. Add this to `~/.claude/settings.json`:

346

347```json theme={null}

348{

349 "hooks": {

350 "PermissionRequest": [

351 {

352 "matcher": "ExitPlanMode",

353 "hooks": [

354 {

355 "type": "command",

356 "command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"PermissionRequest\", \"decision\": {\"behavior\": \"allow\"}}}'"

357 }

358 ]

359 }

360 ]

361 }

362}

363```

364

365When the hook approves, Claude Code exits plan mode and restores whatever permission mode was active before you entered plan mode. The transcript shows "Allowed by PermissionRequest hook" where the dialog would have appeared. The hook path always keeps the current conversation: it cannot clear context and start a fresh implementation session the way the dialog can.

366

367To set a specific permission mode instead, your hook's output can include an `updatedPermissions` array with a `setMode` entry. The `mode` value is any permission mode like `default`, `acceptEdits`, or `bypassPermissions`, and `destination: "session"` applies it for the current session only.

368

369To switch the session to `acceptEdits`, your hook writes this JSON to stdout:

370

371```json theme={null}

372{

373 "hookSpecificOutput": {

374 "hookEventName": "PermissionRequest",

375 "decision": {

376 "behavior": "allow",

377 "updatedPermissions": [

378 { "type": "setMode", "mode": "acceptEdits", "destination": "session" }

379 ]

380 }

381 }

382}

383```

384

385Keep the matcher as narrow as possible. Matching on `.*` or leaving the matcher empty would auto-approve every permission prompt, including file writes and shell commands. See the [PermissionRequest reference](/en/hooks#permissionrequest-decision-control) for the full set of decision fields.

386

265## How hooks work387## How hooks work

266 388

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:389Hook 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 390

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

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

402| `TaskCreated` | When a task is being created via `TaskCreate` |

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

405| `StopFailure` | When the turn ends due to an API error. Output and exit code are ignored |

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

407| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |

408| `ConfigChange` | When a configuration file changes during a session |

409| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |

410| `FileChanged` | When a watched file changes on disk. The `matcher` field specifies which filenames to watch |

411| `WorktreeCreate` | When a worktree is being created via `--worktree` or `isolation: "worktree"`. Replaces default git behavior |

412| `WorktreeRemove` | When a worktree is being removed, either at session exit or when a subagent finishes |

414| `PostCompact` | After context compaction completes |

415| `Elicitation` | When an MCP server requests user input during a tool call |

416| `ElicitationResult` | After a user responds to an MCP elicitation, before the response is sent back to the server |

283 418

284Each hook has a `type` that determines how it runs. Most hooks use `"type": "command"`, which runs a shell command. Two other options use a Claude model to make decisions: `"type": "prompt"` for single-turn evaluation and `"type": "agent"` for multi-turn verification with tool access. See [Prompt-based hooks](#prompt-based-hooks) and [Agent-based hooks](#agent-based-hooks) for details.419Each hook has a `type` that determines how it runs. Most hooks use `"type": "command"`, which runs a shell command. Three other types are available:

420

421* `"type": "http"`: POST event data to a URL. See [HTTP hooks](#http-hooks).

422* `"type": "prompt"`: single-turn LLM evaluation. See [Prompt-based hooks](#prompt-based-hooks).

423* `"type": "agent"`: multi-turn verification with tool access. See [Agent-based hooks](#agent-based-hooks).

285 424

286### Read input and return output425### Read input and return output

287 426

303}442}

304```443```

305 444

306Your script can parse that JSON and act on any of those fields. `UserPromptSubmit` hooks get the `prompt` text instead, `SessionStart` hooks get the `source` (startup, resume, compact), and so on. See [Common input fields](/en/hooks#common-input-fields) in the reference for shared fields, and each event's section for event-specific schemas.445Your script can parse that JSON and act on any of those fields. `UserPromptSubmit` hooks get the `prompt` text instead, `SessionStart` hooks get the `source` (startup, resume, clear, compact), and so on. See [Common input fields](/en/hooks#common-input-fields) in the reference for shared fields, and each event's section for event-specific schemas.

307 446

308#### Hook output447#### Hook output

309 448

350 489

351Claude Code reads `permissionDecision` and cancels the tool call, then feeds `permissionDecisionReason` back to Claude as feedback. These three options are specific to `PreToolUse`:490Claude Code reads `permissionDecision` and cancels the tool call, then feeds `permissionDecisionReason` back to Claude as feedback. These three options are specific to `PreToolUse`:

352 491

353* `"allow"`: proceed without showing a permission prompt492* `"allow"`: skip the interactive permission prompt. Deny and ask rules, including enterprise managed deny lists, still apply

354* `"deny"`: cancel the tool call and send the reason to Claude493* `"deny"`: cancel the tool call and send the reason to Claude

355* `"ask"`: show the permission prompt to the user as normal494* `"ask"`: show the permission prompt to the user as normal

356 495

496Returning `"allow"` skips the interactive prompt but does not override [permission rules](/en/permissions#manage-permissions). If a deny rule matches the tool call, the call is blocked even when your hook returns `"allow"`. If an ask rule matches, the user is still prompted. This means deny rules from any settings scope, including [managed settings](/en/settings#settings-files), always take precedence over hook approvals.

497

357Other events use different decision patterns. For example, `PostToolUse` and `Stop` hooks use a top-level `decision: "block"` field, while `PermissionRequest` uses `hookSpecificOutput.decision.behavior`. See the [summary table](/en/hooks#decision-control) in the reference for a full breakdown by event.498Other events use different decision patterns. For example, `PostToolUse` and `Stop` hooks use a top-level `decision: "block"` field, while `PermissionRequest` uses `hookSpecificOutput.decision.behavior`. See the [summary table](/en/hooks#decision-control) in the reference for a full breakdown by event.

358 499

359For `UserPromptSubmit` hooks, use `additionalContext` instead to inject text into Claude's context. Prompt-based hooks (`type: "prompt"`) handle output differently: see [Prompt-based hooks](#prompt-based-hooks).500For `UserPromptSubmit` hooks, use `additionalContext` instead to inject text into Claude's context. Prompt-based hooks (`type: "prompt"`) handle output differently: see [Prompt-based hooks](#prompt-based-hooks).

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

383 524

385| :--------------------------------------------------------------------- | :------------------------ | :----------------------------------------------------------------------- |526| :--------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------- | :------------------------------------------------------------------------------------------------------------------------ |

392| `UserPromptSubmit`, `Stop` | no matcher support | always fires on every occurrence |

534| `ConfigChange` | configuration source | `user_settings`, `project_settings`, `local_settings`, `policy_settings`, `skills` |

535| `StopFailure` | error type | `rate_limit`, `authentication_failed`, `billing_error`, `invalid_request`, `server_error`, `max_output_tokens`, `unknown` |

536| `InstructionsLoaded` | load reason | `session_start`, `nested_traversal`, `path_glob_match`, `include`, `compact` |

537| `Elicitation` | MCP server name | your configured MCP server names |

538| `ElicitationResult` | MCP server name | same values as `Elicitation` |

539| `FileChanged` | filename (basename of the changed file) | `.envrc`, `.env`, any filename you want to watch |

540| `UserPromptSubmit`, `Stop`, `TeammateIdle`, `TaskCreated`, `TaskCompleted`, `WorktreeCreate`, `WorktreeRemove`, `CwdChanged` | no matcher support | always fires on every occurrence |

394 541

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

396 543

466 613

467For full matcher syntax, see the [Hooks reference](/en/hooks#configuration).614For full matcher syntax, see the [Hooks reference](/en/hooks#configuration).

468 615

616#### Filter by tool name and arguments with the `if` field

617

618<Note>

619 The `if` field requires Claude Code v2.1.85 or later. Earlier versions ignore it and run the hook on every matched call.

620</Note>

621

622The `if` field uses [permission rule syntax](/en/permissions) to filter hooks by tool name and arguments together, so the hook process only spawns when the tool call matches. This goes beyond `matcher`, which filters at the group level by tool name only.

623

624For example, to run a hook only when Claude uses `git` commands rather than all Bash commands:

625

626```json theme={null}

627{

628 "hooks": {

629 "PreToolUse": [

630 {

631 "matcher": "Bash",

632 "hooks": [

633 {

634 "type": "command",

635 "if": "Bash(git *)",

636 "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-git-policy.sh"

637 }

638 ]

639 }

640 ]

641 }

642}

643```

644

645The hook process only spawns when the Bash command starts with `git`. Other Bash commands skip this handler entirely. The `if` field accepts the same patterns as permission rules: `"Bash(git *)"`, `"Edit(*.ts)"`, and so on. To match multiple tool names, use separate handlers each with its own `if` value, or match at the `matcher` level where pipe alternation is supported.

646

647`if` only works on tool events: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, and `PermissionRequest`. Adding it to any other event prevents the hook from running.

648

469### Configure hook location649### Configure hook location

470 650

471Where you add a hook determines its scope:651Where you add a hook determines its scope:

481 661

482You can also use the [`/hooks` menu](/en/hooks#the-hooks-menu) in Claude Code to add, delete, and view hooks interactively. To disable all hooks at once, use the toggle at the bottom of the `/hooks` menu or set `"disableAllHooks": true` in your settings file.662Run [`/hooks`](/en/hooks#the-hooks-menu) in Claude Code to browse all configured hooks grouped by event. To disable all hooks at once, set `"disableAllHooks": true` in your settings file.

483 663

484Hooks added through the `/hooks` menu take effect immediately. If you edit settings files directly while Claude Code is running, the changes won't take effect until you review them in the `/hooks` menu or restart your session.664If you edit settings files directly while Claude Code is running, the file watcher normally picks up hook changes automatically.

485 665

486## Prompt-based hooks666## Prompt-based hooks

487 667

543 723

544For full configuration options, see [Agent-based hooks](/en/hooks#agent-based-hooks) in the reference.724For full configuration options, see [Agent-based hooks](/en/hooks#agent-based-hooks) in the reference.

545 725

726## HTTP hooks

727

728Use `type: "http"` hooks to POST event data to an HTTP endpoint instead of running a shell command. The endpoint receives the same JSON that a command hook would receive on stdin, and returns results through the HTTP response body using the same JSON format.

729

730HTTP hooks are useful when you want a web server, cloud function, or external service to handle hook logic: for example, a shared audit service that logs tool use events across a team.

731

732This example posts every tool use to a local logging service:

733

734```json theme={null}

735{

736 "hooks": {

737 "PostToolUse": [

738 {

739 "hooks": [

740 {

741 "type": "http",

742 "url": "http://localhost:8080/hooks/tool-use",

743 "headers": {

744 "Authorization": "Bearer $MY_TOKEN"

745 },

746 "allowedEnvVars": ["MY_TOKEN"]

747 }

748 ]

749 }

750 ]

751 }

752}

753```

754

755The endpoint should return a JSON response body using the same [output format](/en/hooks#json-output) as command hooks. To block a tool call, return a 2xx response with the appropriate `hookSpecificOutput` fields. HTTP status codes alone cannot block actions.

756

757Header values support environment variable interpolation using `$VAR_NAME` or `${VAR_NAME}` syntax. Only variables listed in the `allowedEnvVars` array are resolved; all other `$VAR` references remain empty.

758

759For full configuration options and response handling, see [HTTP hooks](/en/hooks#http-hook-fields) in the reference.

760

546## Limitations and troubleshooting761## Limitations and troubleshooting

547 762

548### Limitations763### Limitations

549 764

550* Hooks communicate through stdout, stderr, and exit codes only. They cannot trigger slash commands or tool calls directly.765* Command hooks communicate through stdout, stderr, and exit codes only. They cannot trigger commands or tool calls directly. HTTP hooks communicate through the response body instead.

551* Hook timeout is 10 minutes by default, configurable per hook with the `timeout` field (in seconds).766* Hook timeout is 10 minutes by default, configurable per hook with the `timeout` field (in seconds).

552* `PostToolUse` hooks cannot undo actions since the tool has already executed.767* `PostToolUse` hooks cannot undo actions since the tool has already executed.

553* `PermissionRequest` hooks do not fire in [non-interactive mode](/en/headless) (`-p`). Use `PreToolUse` hooks for automated permission decisions.768* `PermissionRequest` hooks do not fire in [non-interactive mode](/en/headless) (`-p`). Use `PreToolUse` hooks for automated permission decisions.

554* `Stop` hooks fire whenever Claude finishes responding, not only at task completion. They do not fire on user interrupts.769* `Stop` hooks fire whenever Claude finishes responding, not only at task completion. They do not fire on user interrupts. API errors fire [StopFailure](/en/hooks#stopfailure) instead.

555 770

556### Hook not firing771### Hook not firing

557 772

579 794

580You edited a settings file but the hooks don't appear in the menu.795You edited a settings file but the hooks don't appear in the menu.

581 796

582* Restart your session or open `/hooks` to reload. Hooks added through the `/hooks` menu take effect immediately, but manual file edits require a reload.797* File edits are normally picked up automatically. If they haven't appeared after a few seconds, the file watcher may have missed the change: restart your session to force a reload.

583* Verify your JSON is valid (trailing commas and comments are not allowed)798* Verify your JSON is valid (trailing commas and comments are not allowed)

584* Confirm the settings file is in the correct location: `.claude/settings.json` for project hooks, `~/.claude/settings.json` for global hooks799* Confirm the settings file is in the correct location: `.claude/settings.json` for project hooks, `~/.claude/settings.json` for global hooks

585 800

604 819

605When Claude Code runs a hook, it spawns a shell that sources your profile (`~/.zshrc` or `~/.bashrc`). If your profile contains unconditional `echo` statements, that output gets prepended to your hook's JSON:820When Claude Code runs a hook, it spawns a shell that sources your profile (`~/.zshrc` or `~/.bashrc`). If your profile contains unconditional `echo` statements, that output gets prepended to your hook's JSON:

606 821

607```822```text theme={null}

608Shell ready on arm64823Shell ready on arm64

609{"decision": "block", "reason": "Not allowed"}824{"decision": "block", "reason": "Not allowed"}

610```825```

how-claude-code-works.md +52 −28

Details

14 14

15When you give Claude a task, it works through three phases: **gather context**, **take action**, and **verify results**. These phases blend together. Claude uses tools throughout, whether searching files to understand your code, editing to make changes, or running tests to check its work.15When you give Claude a task, it works through three phases: **gather context**, **take action**, and **verify results**. These phases blend together. Claude uses tools throughout, whether searching files to understand your code, editing to make changes, or running tests to check its work.

16 16

17<img src="https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/agentic-loop.svg?fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=e30acfc80d6ff01ec877dd19c7af58b2" alt="The agentic loop: Your prompt leads to Claude gathering context, taking action, verifying results, and repeating until task complete. You can interrupt at any point." data-og-width="720" width="720" data-og-height="280" height="280" data-path="images/agentic-loop.svg" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/agentic-loop.svg?w=280&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=8620f6ebce761a1e8bbf7f0a0255cc15 280w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/agentic-loop.svg?w=560&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=7b46b5ff4454aa4a03725eee625b39a0 560w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/agentic-loop.svg?w=840&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=7fa0397bc37d147e3bf3bb6296c6477f 840w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/agentic-loop.svg?w=1100&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=73b2a7040c4c93821c4d5bbee9f4a2d4 1100w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/agentic-loop.svg?w=1650&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=17703cbeb6f59b40a00ab24f56d5f8f9 1650w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/agentic-loop.svg?w=2500&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=20dedb60b95d45a1bd60a0cccaf3e1ff 2500w" />17<img src="https://mintcdn.com/claude-code/c5r9_6tjPMzFdDDT/images/agentic-loop.svg?fit=max&auto=format&n=c5r9_6tjPMzFdDDT&q=85&s=5f1827dec8539f38adee90ead3a85a38" alt="The agentic loop: Your prompt leads to Claude gathering context, taking action, verifying results, and repeating until task complete. You can interrupt at any point." width="720" height="280" data-path="images/agentic-loop.svg" />

18 18

19The loop adapts to what you ask. A question about your codebase might only need context gathering. A bug fix cycles through all three phases repeatedly. A refactor might involve extensive verification. Claude decides what each step requires based on what it learned from the previous step, chaining dozens of actions together and course-correcting along the way.19The loop adapts to what you ask. A question about your codebase might only need context gathering. A bug fix cycles through all three phases repeatedly. A refactor might involve extensive verification. Claude decides what each step requires based on what it learned from the previous step, chaining dozens of actions together and course-correcting along the way.

20 20

34 34

35Tools are what make Claude Code agentic. Without tools, Claude can only respond with text. With tools, Claude can act: read your code, edit files, run commands, search the web, and interact with external services. Each tool use returns information that feeds back into the loop, informing Claude's next decision.35Tools are what make Claude Code agentic. Without tools, Claude can only respond with text. With tools, Claude can act: read your code, edit files, run commands, search the web, and interact with external services. Each tool use returns information that feeds back into the loop, informing Claude's next decision.

36 36

~~37The built-in tools generally fall into four categories, each representing a different kind of agency.~~37The built-in tools generally fall into five categories, each representing a different kind of agency.

38 38

39| Category | What Claude can do |39| Category | What Claude can do |

40| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |40| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |

44| **Web** | Search the web, fetch documentation, look up error messages |44| **Web** | Search the web, fetch documentation, look up error messages |

45| **Code intelligence** | See type errors and warnings after edits, jump to definitions, find references (requires [code intelligence plugins](/en/discover-plugins#code-intelligence)) |45| **Code intelligence** | See type errors and warnings after edits, jump to definitions, find references (requires [code intelligence plugins](/en/discover-plugins#code-intelligence)) |

46 46

47These are the primary capabilities. Claude also has tools for spawning subagents, asking you questions, and other orchestration tasks. See [Tools available to Claude](/en/settings#tools-available-to-claude) for the complete list.47These are the primary capabilities. Claude also has tools for spawning subagents, asking you questions, and other orchestration tasks. See [Tools available to Claude](/en/tools-reference) for the complete list.

48 48

49Claude chooses which tools to use based on your prompt and what it learns along the way. When you say "fix the failing tests," Claude might:49Claude chooses which tools to use based on your prompt and what it learns along the way. When you say "fix the failing tests," Claude might:

50 50

61 61

62## What Claude can access62## What Claude can access

63 63

~~64This guide focuses on the terminal. Claude Code also runs in [VS Code, JetBrains IDEs, and other environments](/en/ide-integrations).~~64This guide focuses on the terminal. Claude Code also runs in [VS Code](/en/vs-code), [JetBrains IDEs](/en/jetbrains), and other environments.

65 65

66When you run `claude` in a directory, Claude Code gains access to:66When you run `claude` in a directory, Claude Code gains access to:

67 67

69* **Your terminal.** Any command you could run: build tools, git, package managers, system utilities, scripts. If you can do it from the command line, Claude can too.69* **Your terminal.** Any command you could run: build tools, git, package managers, system utilities, scripts. If you can do it from the command line, Claude can too.

70* **Your git state.** Current branch, uncommitted changes, and recent commit history.70* **Your git state.** Current branch, uncommitted changes, and recent commit history.

71* **Your [CLAUDE.md](/en/memory).** A markdown file where you store project-specific instructions, conventions, and context that Claude should know every session.71* **Your [CLAUDE.md](/en/memory).** A markdown file where you store project-specific instructions, conventions, and context that Claude should know every session.

72* **[Auto memory](/en/memory#auto-memory).** Learnings Claude saves automatically as you work, like project patterns and your preferences. The first 200 lines or 25KB of MEMORY.md, whichever comes first, load at the start of each session.

72* **Extensions you configure.** [MCP servers](/en/mcp) for external services, [skills](/en/skills) for workflows, [subagents](/en/sub-agents) for delegated work, and [Claude in Chrome](/en/chrome) for browser interaction.73* **Extensions you configure.** [MCP servers](/en/mcp) for external services, [skills](/en/skills) for workflows, [subagents](/en/sub-agents) for delegated work, and [Claude in Chrome](/en/chrome) for browser interaction.

73 74

74Because Claude sees your whole project, it can work across it. When you ask Claude to "fix the authentication bug," it searches for relevant files, reads multiple files to understand context, makes coordinated edits across them, runs tests to verify the fix, and commits the changes if you ask. This is different from inline code assistants that only see the current file.75Because Claude sees your whole project, it can work across it. When you ask Claude to "fix the authentication bug," it searches for relevant files, reads multiple files to understand context, makes coordinated edits across them, runs tests to verify the fix, and commits the changes if you ask. This is different from inline code assistants that only see the current file.

75 76

77## Environments and interfaces

79The agentic loop, tools, and capabilities described above are the same everywhere you use Claude Code. What changes is where the code executes and how you interact with it.

81### Execution environments

83Claude Code runs in three environments, each with different tradeoffs for where your code executes.

85| Environment | Where code runs | Use case |

86| ------------------ | --------------------------------------- | ---------------------------------------------------------- |

87| **Local** | Your machine | Default. Full access to your files, tools, and environment |

88| **Cloud** | Anthropic-managed VMs | Offload tasks, work on repos you don't have locally |

89| **Remote Control** | Your machine, controlled from a browser | Use the web UI while keeping everything local |

91### Interfaces

93You can access Claude Code through the terminal, the [desktop app](/en/desktop), [IDE extensions](/en/ide-integrations), [claude.ai/code](https://claude.ai/code), [Remote Control](/en/remote-control), [Slack](/en/slack), and [CI/CD pipelines](/en/github-actions). The interface determines how you see and interact with Claude, but the underlying agentic loop is identical. See [Use Claude Code everywhere](/en/overview#use-claude-code-everywhere) for the full list.

76## Work with sessions95## Work with sessions

77 96

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.97Claude 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 98

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).99**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 100

82### Work across branches101### Work across branches

83 102

91 110

92When you resume a session with `claude --continue` or `claude --resume`, you pick up where you left off using the same session ID. New messages append to the existing conversation. Your full conversation history is restored, but session-scoped permissions are not. You'll need to re-approve those.111When you resume a session with `claude --continue` or `claude --resume`, you pick up where you left off using the same session ID. New messages append to the existing conversation. Your full conversation history is restored, but session-scoped permissions are not. You'll need to re-approve those.

93 112

94<img src="https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/session-continuity.svg?fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=f671b603cc856119c95475b9084ebfef" alt="Session continuity: resume continues the same session, fork creates a new branch with a new ID." data-og-width="560" width="560" data-og-height="280" height="280" data-path="images/session-continuity.svg" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/session-continuity.svg?w=280&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=bddf1f33d419a27d7427acdf06058804 280w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/session-continuity.svg?w=560&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=417478eb9b86003b8eebaac058a8618a 560w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/session-continuity.svg?w=840&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=1d89d26e2c0487f067d187c3fa5f7170 840w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/session-continuity.svg?w=1100&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=8ea739a1f7860e4edbbcf74d444e37b2 1100w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/session-continuity.svg?w=1650&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=9cb5095d6a8920f04c3b78d31a69c809 1650w, https://mintcdn.com/claude-code/ELkJZG54dIaeldDC/images/session-continuity.svg?w=2500&fit=max&auto=format&n=ELkJZG54dIaeldDC&q=85&s=d67e1744e4878813d20c6c3f39d9459d 2500w" />113<img src="https://mintcdn.com/claude-code/c5r9_6tjPMzFdDDT/images/session-continuity.svg?fit=max&auto=format&n=c5r9_6tjPMzFdDDT&q=85&s=fa41d12bfb57579cabfeece907151d30" alt="Session continuity: resume continues the same session, fork creates a new branch with a new ID." width="560" height="280" data-path="images/session-continuity.svg" />

95 114

96To branch off and try a different approach without affecting the original session, use the `--fork-session` flag:115To branch off and try a different approach without affecting the original session, use the `--fork-session` flag:

97 116

105 124

106### The context window125### The context window

107 126

108Claude's context window holds your conversation history, file contents, command outputs, [CLAUDE.md](/en/memory), loaded skills, and system instructions. As you work, context fills up. Claude compacts automatically, but instructions from early in the conversation can get lost. Put persistent rules in CLAUDE.md, and run `/context` to see what's using space.127Claude's context window holds your conversation history, file contents, command outputs, [CLAUDE.md](/en/memory), [auto memory](/en/memory#auto-memory), loaded skills, and system instructions. As you work, context fills up. Claude compacts automatically, but instructions from early in the conversation can get lost. Put persistent rules in CLAUDE.md, and run `/context` to see what's using space.

128

129For an interactive walkthrough of what loads and when, see [Explore the context window](/en/context-window).

109 130

110#### When context fills up131#### When context fills up

111 132

113 134

114To control what's preserved during compaction, add a "Compact Instructions" section to CLAUDE.md or run `/compact` with a focus (like `/compact focus on the API changes`).135To control what's preserved during compaction, add a "Compact Instructions" section to CLAUDE.md or run `/compact` with a focus (like `/compact focus on the API changes`).

115 136

116Run `/context` to see what's using space. MCP servers add tool definitions to every request, so a few servers can consume significant context before you start working. Run `/mcp` to check per-server costs.137Run `/context` to see what's using space. MCP tool definitions are deferred by default and loaded on demand via [tool search](/en/mcp#scale-with-mcp-tool-search), so only tool names consume context until Claude uses a specific tool. Run `/mcp` to check per-server costs.

117 138

118#### Manage context with skills and subagents139#### Manage context with skills and subagents

119 140

142* **Default**: Claude asks before file edits and shell commands163* **Default**: Claude asks before file edits and shell commands

143* **Auto-accept edits**: Claude edits files without asking, still asks for commands164* **Auto-accept edits**: Claude edits files without asking, still asks for commands

144* **Plan mode**: Claude uses read-only tools only, creating a plan you can approve before execution165* **Plan mode**: Claude uses read-only tools only, creating a plan you can approve before execution

166* **Auto mode**: Claude evaluates all actions with background safety checks. Currently a research preview

145 167

146You can also allow specific commands in `.claude/settings.json` so Claude doesn't ask each time. This is useful for trusted commands like `npm test` or `git status`. Settings can be scoped from organization-wide policies down to personal preferences. See [Permissions](/en/iam) for details.168You can also allow specific commands in `.claude/settings.json` so Claude doesn't ask each time. This is useful for trusted commands like `npm test` or `git status`. Settings can be scoped from organization-wide policies down to personal preferences. See [Permissions](/en/permissions) for details.

147 169

148***170***

149 171

165 187

166Claude Code is conversational. You don't need perfect prompts. Start with what you want, then refine:188Claude Code is conversational. You don't need perfect prompts. Start with what you want, then refine:

167 189

190```text theme={null}

191Fix the login bug

168```192```

169> Fix the login bug

~~170~~

171[Claude investigates, tries something]

172 193

173> That's not quite right. The issue is in the session handling.194\[Claude investigates, tries something]

174 195

175[Claude adjusts approach]196```text theme={null}

197That's not quite right. The issue is in the session handling.

176```198```

177 199

200\[Claude adjusts approach]

201

178When the first attempt isn't right, you don't start over. You iterate.202When the first attempt isn't right, you don't start over. You iterate.

179 203

180#### Interrupt and steer204#### Interrupt and steer

185 209

186The more precise your initial prompt, the fewer corrections you'll need. Reference specific files, mention constraints, and point to example patterns.210The more precise your initial prompt, the fewer corrections you'll need. Reference specific files, mention constraints, and point to example patterns.

187 211

188```212```text theme={null}

189> The checkout flow is broken for users with expired cards.213The checkout flow is broken for users with expired cards.

190> Check src/payments/ for the issue, especially token refresh.214Check src/payments/ for the issue, especially token refresh.

191> Write a failing test first, then fix it.215Write a failing test first, then fix it.

192```216```

193 217

194Vague prompts like "fix the login bug" work, but you'll spend more time steering. Specific prompts like the above often succeed on the first attempt.218Vague prompts work, but you'll spend more time steering. Specific prompts like the one above often succeed on the first attempt.

195 219

196### Give Claude something to verify against220### Give Claude something to verify against

197 221

198Claude performs better when it can check its own work. Include test cases, paste screenshots of expected UI, or define the output you want.222Claude performs better when it can check its own work. Include test cases, paste screenshots of expected UI, or define the output you want.

199 223

200```224```text theme={null}

201> Implement validateEmail. Test cases: 'user@example.com' → true,225Implement validateEmail. Test cases: 'user@example.com' → true,

202> 'invalid' → false, 'user@.com' → false. Run the tests after.226'invalid' → false, 'user@.com' → false. Run the tests after.

203```227```

204 228

205For visual work, paste a screenshot of the design and ask Claude to compare its implementation against it.229For visual work, paste a screenshot of the design and ask Claude to compare its implementation against it.

208 232

209For complex problems, separate research from coding. Use plan mode (`Shift+Tab` twice) to analyze the codebase first:233For complex problems, separate research from coding. Use plan mode (`Shift+Tab` twice) to analyze the codebase first:

210 234

211```235```text theme={null}

212> Read src/auth/ and understand how we handle sessions.236Read src/auth/ and understand how we handle sessions.

213> Then create a plan for adding OAuth support.237Then create a plan for adding OAuth support.

214```238```

215 239

216Review the plan, refine it through conversation, then let Claude implement. This two-phase approach produces better results than jumping straight to code.240Review the plan, refine it through conversation, then let Claude implement. This two-phase approach produces better results than jumping straight to code.

219 243

220Think of delegating to a capable colleague. Give context and direction, then trust Claude to figure out the details:244Think of delegating to a capable colleague. Give context and direction, then trust Claude to figure out the details:

221 245

222```246```text theme={null}

223> The checkout flow is broken for users with expired cards.247The checkout flow is broken for users with expired cards.

224> The relevant code is in src/payments/. Can you investigate and fix it?248The relevant code is in src/payments/. Can you investigate and fix it?

225```249```

226 250

227You don't need to specify which files to read or what commands to run. Claude figures that out.251You don't need to specify which files to read or what commands to run. Claude figures that out.

iam.md +0 −239 deleted

File DeletedView Diff

~~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# Identity and Access Management~~

~~7> Learn how to configure user authentication, authorization, and access controls for Claude Code in your organization.~~

~~9## Authentication methods~~

~~11Setting up Claude Code requires access to Anthropic models. For teams, you can set up Claude Code access in one of these ways:~~

~~13* [Claude for Teams or Enterprise](/en/setup#for-teams-and-organizations) (recommended)~~

~~14* [Claude Console with team billing](/en/setup#for-teams-and-organizations)~~

~~15* [Amazon Bedrock](/en/amazon-bedrock)~~

~~16* [Google Vertex AI](/en/google-vertex-ai)~~

~~17* [Microsoft Foundry](/en/microsoft-foundry)~~

~~19### Claude for Teams or Enterprise (recommended)~~

21[Claude for Teams](https://claude.com/pricing#team-&-enterprise) and [Claude for Enterprise](https://anthropic.com/contact-sales) provide the best experience for organizations using Claude Code. Team members get access to both Claude Code and Claude on the web with centralized billing and team management.

~~23* **Claude for Teams**: Self-service plan with collaboration features, admin tools, and billing management. Best for smaller teams.~~

24* **Claude for Enterprise**: Adds SSO, domain capture, role-based permissions, compliance API, and managed policy settings for organization-wide Claude Code configurations. Best for larger organizations with security and compliance requirements.

~~26**To set up Claude Code access:**~~

~~281. Subscribe to [Claude for Teams](https://claude.com/pricing#team-&-enterprise) or contact sales for [Claude for Enterprise](https://anthropic.com/contact-sales)~~

~~292. Invite team members from the admin dashboard~~

~~303. Team members install Claude Code and log in with their Claude.ai accounts~~

~~32### Claude Console authentication~~

~~34For organizations that prefer API-based billing, you can set up access through the Claude Console.~~

~~36**To set up Claude Code access for your team via Claude Console:**~~

~~381. Use your existing Claude Console account or create a new Claude Console account~~

~~392. You can add users through either method below:~~

~~40 * Bulk invite users from within the Console (Console -> Settings -> Members -> Invite)~~

~~41 * [Set up SSO](https://support.claude.com/en/articles/13132885-setting-up-single-sign-on-sso)~~

~~423. When inviting users, they need one of the following roles:~~

~~43 * "Claude Code" role means users can only create Claude Code API keys~~

~~44 * "Developer" role means users can create any kind of API key~~

~~454. Each invited user needs to complete these steps:~~

~~46 * Accept the Console invite~~

~~47 * [Check system requirements](/en/setup#system-requirements)~~

~~48 * [Install Claude Code](/en/setup#installation)~~

~~49 * Login with Console account credentials~~

~~51### Cloud provider authentication~~

~~53**To set up Claude Code access for your team via Bedrock, Vertex, or Azure:**~~

~~551. Follow the [Bedrock docs](/en/amazon-bedrock), [Vertex docs](/en/google-vertex-ai), or [Microsoft Foundry docs](/en/microsoft-foundry)~~

~~562. Distribute the environment variables and instructions for generating cloud credentials to your users. Read more about how to [manage configuration here](/en/settings).~~

~~573. Users can [install Claude Code](/en/setup#installation)~~

~~59## Access control and permissions~~

61We support fine-grained permissions so that you're able to specify exactly what the agent is allowed to do (e.g. run tests, run linter) and what it is not allowed to do (e.g. update cloud infrastructure). These permission settings can be checked into version control and distributed to all developers in your organization, as well as customized by individual developers.

~~63### Permission system~~

~~65Claude Code uses a tiered permission system to balance power and safety:~~

~~68| :---------------- | :--------------- | :---------------- | :-------------------------------------------- |~~

~~69| Read-only | File reads, Grep | No | N/A |~~

~~70| Bash Commands | Shell execution | Yes | Permanently per project directory and command |~~

~~71| File Modification | Edit/write files | Yes | Until session end |~~

~~73### Configuring permissions~~

~~75You can view & manage Claude Code's tool permissions with `/permissions`. This UI lists all permission rules and the settings.json file they are sourced from.~~

~~77* **Allow** rules let Claude Code use the specified tool without manual approval.~~

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

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

~~81Rules are evaluated in order: **deny → ask → allow**. The first matching rule wins, so deny rules always take precedence.~~

~~83* **Additional directories** extend Claude's file access to directories beyond the initial working directory.~~

~~84* **Default mode** controls Claude's permission behavior when encountering new requests.~~

~~86Permission rules use the format: `Tool` or `Tool(optional-specifier)`~~

88A rule that is just the tool name matches any use of that tool. For example, adding `Bash` to the allow list allows Claude Code to use the Bash tool without requiring user approval. `Bash(*)` is equivalent to `Bash` and can be used interchangeably.

~~90<Note>~~

~~91 For a quick reference on permission rule syntax including wildcards, see [Permission rule syntax](/en/settings#permission-rule-syntax) in the settings documentation.~~

~~92</Note>~~

~~94#### Permission modes~~

~~96Claude Code supports several permission modes that can be set as the `defaultMode` in [settings files](/en/settings#settings-files):~~

~~98| Mode | Description |~~

~~99| :------------------ | :------------------------------------------------------------------------------------------------------------------------ |~~

100| `default` | Standard behavior - prompts for permission on first use of each tool |

101| `acceptEdits` | Automatically accepts file edit permissions for the session |

102| `plan` | Plan Mode - Claude can analyze but not modify files or execute commands |

103| `dontAsk` | Auto-denies tools unless pre-approved via `/permissions` or [`permissions.allow`](/en/settings#permission-settings) rules |

104| `bypassPermissions` | Skips all permission prompts (requires safe environment - see warning below) |

~~105~~

106#### Working directories

~~107~~

108By default, Claude has access to files in the directory where it was launched. You can extend this access:

~~109~~

110* **During startup**: Use `--add-dir <path>` CLI argument

111* **During session**: Use `/add-dir` command

112* **Persistent configuration**: Add to `additionalDirectories` in [settings files](/en/settings#settings-files)

~~113~~

114Files in additional directories follow the same permission rules as the original working directory - they become readable without prompts, and file editing permissions follow the current permission mode.

~~115~~

116#### Tool-specific permission rules

~~117~~

118Some tools support more fine-grained permission controls:

~~119~~

120**Bash**

~~121~~

122Bash permission rules support wildcard matching with `*`. Wildcards can appear at any position in the command, including at the beginning, middle, or end:

~~123~~

124* `Bash(npm run build)` Matches the exact Bash command `npm run build`

125* `Bash(npm run test *)` Matches Bash commands starting with `npm run test`

126* `Bash(npm *)` Matches any command starting with `npm ` (e.g., `npm install`, `npm run build`)

127* `Bash(* install)` Matches any command ending with ` install` (e.g., `npm install`, `yarn install`)

128* `Bash(git * main)` Matches commands like `git checkout main`, `git merge main`

129* `Bash(* --help *)` Matches any command with `--help` followed by additional arguments

~~130~~

131When `*` appears at the end with a space before it (like `Bash(ls *)`), it enforces a word boundary, requiring the prefix to be followed by a space or end-of-string. For example, `Bash(ls *)` matches `ls -la` but not `lsof`. In contrast, `Bash(ls*)` without a space matches both `ls -la` and `lsof` because there's no word boundary constraint. The legacy `:*` suffix syntax is equivalent to ` *` but is deprecated.

~~132~~

133<Tip>

134 Claude Code is aware of shell operators (like `&&`) so a prefix match rule like `Bash(safe-cmd *)` won't give it permission to run the command `safe-cmd && other-cmd`

135</Tip>

~~136~~

137<Warning>

138 Important limitations of Bash permission patterns:

~~139~~

140 1. The space before `*` matters: `Bash(ls *)` matches `ls -la` but not `lsof`, while `Bash(ls*)` matches both

141 2. The `*` wildcard can appear at any position and matches any sequence of characters

142 3. Patterns like `Bash(curl http://github.com/ *)` can be bypassed in many ways:

143 * Options before URL: `curl -X GET http://github.com/...` won't match

144 * Different protocol: `curl https://github.com/...` won't match

145 * Redirects: `curl -L http://bit.ly/xyz` (redirects to github)

146 * Variables: `URL=http://github.com && curl $URL` won't match

147 * Extra spaces: `curl http://github.com` won't match

~~148~~

149 For more reliable URL filtering, consider:

~~150~~

151 * **Restrict Bash network tools**: Use deny rules to block `curl`, `wget`, and similar commands, then use the WebFetch tool with `WebFetch(domain:github.com)` permission for allowed domains

152 * **Use PreToolUse hooks**: Implement a hook that validates URLs in Bash commands and blocks disallowed domains

153 * Instructing Claude Code about your allowed curl patterns via CLAUDE.md

~~154~~

155 Note that using WebFetch alone does not prevent network access. If Bash is allowed, Claude can still use `curl`, `wget`, or other tools to reach any URL.

156</Warning>

~~157~~

158**Read & Edit**

~~159~~

160`Edit` rules apply to all built-in tools that edit files. Claude will make a best-effort attempt to apply `Read` rules to all built-in tools that read files like Grep and Glob.

~~161~~

162Read & Edit rules both follow the [gitignore](https://git-scm.com/docs/gitignore) specification with four distinct pattern types:

~~163~~

165| ------------------ | -------------------------------------- | -------------------------------- | ---------------------------------- |

166| `//path` | **Absolute** path from filesystem root | `Read(//Users/alice/secrets/**)` | `/Users/alice/secrets/**` |

167| `~/path` | Path from **home** directory | `Read(~/Documents/*.pdf)` | `/Users/alice/Documents/*.pdf` |

168| `/path` | Path **relative to settings file** | `Edit(/src/**/*.ts)` | `<settings file path>/src/**/*.ts` |

169| `path` or `./path` | Path **relative to current directory** | `Read(*.env)` | `<cwd>/*.env` |

~~170~~

171<Warning>

172 A pattern like `/Users/alice/file` is NOT an absolute path - it's relative to your settings file! Use `//Users/alice/file` for absolute paths.

173</Warning>

~~174~~

175* `Edit(/docs/**)` - Edits in `<project>/docs/` (NOT `/docs/`!)

176* `Read(~/.zshrc)` - Reads your home directory's `.zshrc`

177* `Edit(//tmp/scratch.txt)` - Edits the absolute path `/tmp/scratch.txt`

178* `Read(src/**)` - Reads from `<current-directory>/src/`

~~179~~

180<Note>

181 In gitignore patterns, `*` matches files in a single directory while `**` matches recursively across directories. To allow all file access, use just the tool name without parentheses: `Read`, `Edit`, or `Write`.

182</Note>

~~183~~

184**WebFetch**

~~185~~

186* `WebFetch(domain:example.com)` Matches fetch requests to example.com

~~187~~

188**MCP**

~~189~~

190* `mcp__puppeteer` Matches any tool provided by the `puppeteer` server (name configured in Claude Code)

191* `mcp__puppeteer__*` Wildcard syntax that also matches all tools from the `puppeteer` server

192* `mcp__puppeteer__puppeteer_navigate` Matches the `puppeteer_navigate` tool provided by the `puppeteer` server

~~193~~

194**Task (Subagents)**

~~195~~

196Use `Task(AgentName)` rules to control which [subagents](/en/sub-agents) Claude can use:

~~197~~

198* `Task(Explore)` Matches the Explore subagent

199* `Task(Plan)` Matches the Plan subagent

200* `Task(Verify)` Matches the Verify subagent

~~201~~

202Add these rules to the `deny` array in your [settings](/en/settings#permission-settings) or use the `--disallowedTools` CLI flag to disable specific agents. For example, to disable the Explore agent:

~~203~~

204```json theme={null}

205{

206 "permissions": {

207 "deny": ["Task(Explore)"]

208 }

209}

210```

~~211~~

212### Additional permission control with hooks

~~213~~

214[Claude Code hooks](/en/hooks-guide) provide a way to register custom shell commands to perform permission evaluation at runtime. When Claude Code makes a tool call, PreToolUse hooks run before the permission system runs, and the hook output can determine whether to approve or deny the tool call in place of the permission system.

~~215~~

216### Managed settings

~~217~~

218For organizations that need centralized control over Claude Code configuration, administrators can deploy `managed-settings.json` files to [system directories](/en/settings#settings-files). These policy files follow the same format as regular settings files and cannot be overridden by user or project settings.

~~219~~

220### Settings precedence

~~221~~

222When multiple settings sources exist, they are applied in the following order (highest to lowest precedence):

~~223~~

2241. Managed settings (`managed-settings.json`)

2252. Command line arguments

2263. Local project settings (`.claude/settings.local.json`)

2274. Shared project settings (`.claude/settings.json`)

2285. User settings (`~/.claude/settings.json`)

~~229~~

230This hierarchy ensures that organizational policies are always enforced while still allowing flexibility at the project and user levels where appropriate.

~~231~~

232## Credential management

~~233~~

234Claude Code securely manages your authentication credentials:

~~235~~

236* **Storage location**: On macOS, API keys, OAuth tokens, and other credentials are stored in the encrypted macOS Keychain.

237* **Supported authentication types**: Claude.ai credentials, Claude API credentials, Azure Auth, Bedrock Auth, and Vertex Auth.

238* **Custom credential scripts**: The [`apiKeyHelper`](/en/settings#available-settings) setting can be configured to run a shell script that returns an API key.

239* **Refresh intervals**: By default, `apiKeyHelper` is called after 5 minutes or on HTTP 401 response. Set `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` environment variable for custom refresh intervals.

interactive-mode.md +62 −62

Details

13 13

14 **macOS users**: Option/Alt key shortcuts (`Alt+B`, `Alt+F`, `Alt+Y`, `Alt+M`, `Alt+P`) require configuring Option as Meta in your terminal:14 **macOS users**: Option/Alt key shortcuts (`Alt+B`, `Alt+F`, `Alt+Y`, `Alt+M`, `Alt+P`) require configuring Option as Meta in your terminal:

15 15

~~16 * **iTerm2**: Settings → Profiles → Keys → Set Left/Right Option key to "Esc+"~~16 * **iTerm2**: settings → Profiles → Keys → set Left/Right Option key to "Esc+"

~~17 * **Terminal.app**: Settings → Profiles → Keyboard → Check "Use Option as Meta Key"~~17 * **Terminal.app**: settings → Profiles → Keyboard → check "Use Option as Meta Key"

~~18 * **VS Code**: Settings → Profiles → Keys → Set Left/Right Option key to "Esc+"~~18 * **VS Code**: settings → Profiles → Keys → set Left/Right Option key to "Esc+"

19 19

20 See [Terminal configuration](/en/terminal-config) for details.20 See [Terminal configuration](/en/terminal-config) for details.

21</Note>21</Note>

23### General controls23### General controls

24 24

~~26| :------------------------------------------------ | :--------------------------------- | :-------------------------------------------------------------------------------------------- |~~26| :------------------------------------------------ | :------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

28| `Ctrl+X Ctrl+K` | Kill all background agents. Press twice within 3 seconds to confirm | Background agent control |

36| `Ctrl+T` | Toggle task list | Show or hide the [task list](#task-list) in the terminal status area |

~~38| `Shift+Tab` or `Alt+M` (some configurations) | Toggle permission modes | Switch between Auto-Accept Mode, Plan Mode, and normal mode |~~40| `Shift+Tab` or `Alt+M` (some configurations) | Cycle permission modes | Cycle through `default`, `acceptEdits`, `plan`, and any modes you have enabled, such as `auto` or `bypassPermissions`. See [permission modes](/en/permission-modes). |

40| `Option+T` (macOS) or `Alt+T` (Windows/Linux) | Toggle extended thinking | Enable or disable extended thinking mode. Run `/terminal-setup` first to enable this shortcut |42| `Option+T` (macOS) or `Alt+T` (Windows/Linux) | Toggle extended thinking | Enable or disable extended thinking mode. Run `/terminal-setup` first to enable this shortcut |

43| `Option+O` (macOS) or `Alt+O` (Windows/Linux) | Toggle fast mode | Enable or disable [fast mode](/en/fast-mode) |

41 44

42### Text editing45### Text editing

43 46

~~45| :----------------------- | :--------------------------- | :------------------------------------------------------------------------------------------------------------ |~~48| :----------------------- | :------------------------------- | :------------------------------------------------------------------------------------------------------------ |

56| :------- | :----------------------------------------- | :----------------------------------------------------------------------------------------------------------- |59| :------- | :----------------------------------------- | :----------------------------------------------------------------------------------------------------------- |

58 61

~~59<Note>~~

~~60 Syntax highlighting is only available in the native build of Claude Code.~~

~~61</Note>~~

63### Multiline input62### Multiline input

64 63

83| `@` | File path mention | Trigger file path autocomplete |82| `@` | File path mention | Trigger file path autocomplete |

84 83

84### Transcript viewer

86When the transcript viewer is open (toggled with `Ctrl+O`), these shortcuts are available. `Ctrl+E` can be rebound via [`transcript:toggleShowAll`](/en/keybindings).

88| Shortcut | Description |

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

90| `Ctrl+E` | Toggle show all content |

91| `q`, `Ctrl+C`, `Esc` | Exit transcript view. `Ctrl+C` and `Esc` can be rebound via [`transcript:exit`](/en/keybindings); `q` is not rebindable |

93### Voice input

95| Shortcut | Description | Notes |

96| :----------- | :--------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |

97| Hold `Space` | Push-to-talk dictation | Requires [voice dictation](/en/voice-dictation) to be enabled. Transcript inserts at cursor. [Rebindable](/en/voice-dictation#rebind-the-push-to-talk-key) |

85## Built-in commands99## Built-in commands

86 100

87Built-in commands are shortcuts for common actions. The table below covers commonly used commands but not all available options. Type `/` in Claude Code to see the full list, or type `/` followed by any letters to filter.101Type `/` in Claude Code to see all available commands, or type `/` followed by any letters to filter. The `/` menu shows both built-in commands and [bundled skills](/en/skills#bundled-skills) like `/simplify`. Not all commands are visible to every user since some depend on your platform or plan.

88 102

~~89To create your own commands you can invoke with `/`, see [skills](/en/skills).~~103See the [commands reference](/en/commands) for the full list of built-in commands. To create your own commands, see [skills](/en/skills).

~~91| Command | Purpose |~~

~~92| :------------------------ | :-------------------------------------------------------------------------------------------------------------------------- |~~

~~93| `/clear` | Clear conversation history |~~

~~94| `/compact [instructions]` | Compact conversation with optional focus instructions |~~

~~95| `/config` | Open the Settings interface (Config tab) |~~

~~96| `/context` | Visualize current context usage as a colored grid |~~

~~97| `/cost` | Show token usage statistics. See [cost tracking guide](/en/costs#using-the-cost-command) for subscription-specific details. |~~

~~98| `/doctor` | Checks the health of your Claude Code installation |~~

~~99| `/exit` | Exit the REPL |~~

100| `/export [filename]` | Export the current conversation to a file or clipboard |

101| `/help` | Get usage help |

102| `/init` | Initialize project with `CLAUDE.md` guide |

103| `/mcp` | Manage MCP server connections and OAuth authentication |

104| `/memory` | Edit `CLAUDE.md` memory files |

105| `/model` | Select or change the AI model |

106| `/permissions` | View or update [permissions](/en/iam#configuring-permissions) |

107| `/plan` | Enter plan mode directly from the prompt |

108| `/rename <name>` | Rename the current session for easier identification |

109| `/resume [session]` | Resume a conversation by ID or name, or open the session picker |

110| `/rewind` | Rewind the conversation and/or code |

111| `/stats` | Visualize daily usage, session history, streaks, and model preferences |

112| `/status` | Open the Settings interface (Status tab) showing version, model, account, and connectivity |

113| `/statusline` | Set up Claude Code's status line UI |

114| `/copy` | Copy the last assistant response to clipboard |

115| `/tasks` | List and manage background tasks |

116| `/teleport` | Resume a remote session from claude.ai (subscribers only) |

117| `/theme` | Change the color theme |

118| `/todos` | List current TODO items |

119| `/usage` | For subscription plans only: show plan usage limits and rate limit status |

~~120~~

121### MCP prompts

~~122~~

123MCP servers can expose prompts that appear as commands. These use the format `/mcp__<server>__<prompt>` and are dynamically discovered from connected servers. See [MCP prompts](/en/mcp#use-mcp-prompts-as-commands) for details.

124 104

125## Vim editor mode105## Vim editor mode

126 106

200 180

201Claude Code maintains command history for the current session:181Claude Code maintains command history for the current session:

202 182

203* History is stored per working directory183* Input history is stored per working directory

204* Cleared with `/clear` command184* Input history resets when you run `/clear` to start a new session. The previous session's conversation is preserved and can be resumed.

205* Use Up/Down arrows to navigate (see keyboard shortcuts above)185* Use Up/Down arrows to navigate (see keyboard shortcuts above)

206* **Note**: History expansion (`!`) is disabled by default186* **Note**: history expansion (`!`) is disabled by default

207 187

208### Reverse search with Ctrl+R188### Reverse search with Ctrl+R

209 189

210Press `Ctrl+R` to interactively search through your command history:190Press `Ctrl+R` to interactively search through your command history:

211 191

2121. **Start search**: Press `Ctrl+R` to activate reverse history search1921. **Start search**: press `Ctrl+R` to activate reverse history search

2132. **Type query**: Enter text to search for in previous commands - the search term will be highlighted in matching results1932. **Type query**: enter text to search for in previous commands. The search term is highlighted in matching results

2143. **Navigate matches**: Press `Ctrl+R` again to cycle through older matches1943. **Navigate matches**: press `Ctrl+R` again to cycle through older matches

2154. **Accept match**:1954. **Accept match**:

216 * Press `Tab` or `Esc` to accept the current match and continue editing196 * Press `Tab` or `Esc` to accept the current match and continue editing

217 * Press `Enter` to accept and execute the command immediately197 * Press `Enter` to accept and execute the command immediately

219 * Press `Ctrl+C` to cancel and restore your original input199 * Press `Ctrl+C` to cancel and restore your original input

220 * Press `Backspace` on empty search to cancel200 * Press `Backspace` on empty search to cancel

221 201

222The search displays matching commands with the search term highlighted, making it easy to find and reuse previous inputs.202The search displays matching commands with the search term highlighted, so you can find and reuse previous inputs.

223 203

224## Background bash commands204## Background bash commands

225 205

236 216

237**Key features:**217**Key features:**

238 218

239* Output is buffered and Claude can retrieve it using the TaskOutput tool219* Output is written to a file and Claude can retrieve it using the Read tool

240* Background tasks have unique IDs for tracking and output retrieval220* Background tasks have unique IDs for tracking and output retrieval

241* Background tasks are automatically cleaned up when Claude Code exits221* Background tasks are automatically cleaned up when Claude Code exits

222* Background tasks are automatically terminated if output exceeds 5GB, with a note in stderr explaining why

242 223

243To disable all background task functionality, set the `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` environment variable to `1`. See [Environment variables](/en/settings#environment-variables) for details.224To disable all background task functionality, set the `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` environment variable to `1`. See [Environment variables](/en/env-vars) for details.

244 225

245**Common backgrounded commands:**226**Common backgrounded commands:**

246 227

267* Supports the same `Ctrl+B` backgrounding for long-running commands248* Supports the same `Ctrl+B` backgrounding for long-running commands

268* Does not require Claude to interpret or approve the command249* Does not require Claude to interpret or approve the command

269* Supports history-based autocomplete: type a partial command and press **Tab** to complete from previous `!` commands in the current project250* Supports history-based autocomplete: type a partial command and press **Tab** to complete from previous `!` commands in the current project

251* Exit with `Escape`, `Backspace`, or `Ctrl+U` on an empty prompt

270 252

271This is useful for quick shell operations while maintaining conversation context.253This is useful for quick shell operations while maintaining conversation context.

272 254

289export CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=false271export CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=false

290```272```

291 273

274## Side questions with /btw

275

276Use `/btw` to ask a quick question about your current work without adding to the conversation history. This is useful when you want a fast answer but don't want to clutter the main context or derail Claude from a long-running task.

277

278```

279/btw what was the name of that config file again?

280```

281

282Side questions have full visibility into the current conversation, so you can ask about code Claude has already read, decisions it made earlier, or anything else from the session. The question and answer are ephemeral: they appear in a dismissible overlay and never enter the conversation history.

283

284* **Available while Claude is working**: you can run `/btw` even while Claude is processing a response. The side question runs independently and does not interrupt the main turn.

285* **No tool access**: side questions answer only from what is already in context. Claude cannot read files, run commands, or search when answering a side question.

286* **Single response**: there are no follow-up turns. If you need a back-and-forth, use a normal prompt instead.

287* **Low cost**: the side question reuses the parent conversation's prompt cache, so the additional cost is minimal.

288

289Press **Space**, **Enter**, or **Escape** to dismiss the answer and return to the prompt.

290

291`/btw` is the inverse of a [subagent](/en/sub-agents): it sees your full conversation but has no tools, while a subagent has full tools but starts with an empty context. Use `/btw` to ask about what Claude already knows from this session; use a subagent to go find out something new.

292

292## Task list293## Task list

293 294

294When working on complex, multi-step work, Claude creates a task list to track progress. Tasks appear in the status area of your terminal with indicators showing what's pending, in progress, or complete.295When working on complex, multi-step work, Claude creates a task list to track progress. Tasks appear in the status area of your terminal with indicators showing what's pending, in progress, or complete.

297* To see all tasks or clear them, ask Claude directly: "show me all tasks" or "clear all tasks"298* To see all tasks or clear them, ask Claude directly: "show me all tasks" or "clear all tasks"

298* Tasks persist across context compactions, helping Claude stay organized on larger projects299* Tasks persist across context compactions, helping Claude stay organized on larger projects

299* To share a task list across sessions, set `CLAUDE_CODE_TASK_LIST_ID` to use a named directory in `~/.claude/tasks/`: `CLAUDE_CODE_TASK_LIST_ID=my-project claude`300* To share a task list across sessions, set `CLAUDE_CODE_TASK_LIST_ID` to use a named directory in `~/.claude/tasks/`: `CLAUDE_CODE_TASK_LIST_ID=my-project claude`

300* To revert to the previous TODO list, set `CLAUDE_CODE_ENABLE_TASKS=false`.

301 301

302## PR review status302## PR review status

303 303

jetbrains.md +4 −1

Details

51 51

52```bash theme={null}52```bash theme={null}

53claude53claude

~~54> /ide~~54```

56```text theme={null}

57/ide

55```58```

56 59

57If you want Claude to have access to the same files as your IDE, start Claude Code from the same directory as your IDE project root.60If you want Claude to have access to the same files as your IDE, start Claude Code from the same directory as your IDE project root.

keybindings.md +50 −13

Details

6 6

7> Customize keyboard shortcuts in Claude Code with a keybindings configuration file.7> Customize keyboard shortcuts in Claude Code with a keybindings configuration file.

8 8

9<Note>

10 Customizable keyboard shortcuts require Claude Code v2.1.18 or later. Check your version with `claude --version`.

11</Note>

9Claude Code supports customizable keyboard shortcuts. Run `/keybindings` to create or open your configuration file at `~/.claude/keybindings.json`.13Claude Code supports customizable keyboard shortcuts. Run `/keybindings` to create or open your configuration file at `~/.claude/keybindings.json`.

10 14

11## Configuration file15## Configuration file

24 28

25```json theme={null}29```json theme={null}

26{30{

~~27 "$schema": "https://platform.claude.com/docs/schemas/claude-code/keybindings.json",~~31 "$schema": "https://www.schemastore.org/claude-code-keybindings.json",

28 "$docs": "https://code.claude.com/docs/en/keybindings",32 "$docs": "https://code.claude.com/docs/en/keybindings",

29 "bindings": [33 "bindings": [

30 {34 {

55| `HistorySearch` | History search mode (Ctrl+R) |59| `HistorySearch` | History search mode (Ctrl+R) |

56| `Task` | Background task is running |60| `Task` | Background task is running |

57| `ThemePicker` | Theme picker dialog |61| `ThemePicker` | Theme picker dialog |

59| `Footer` | Footer indicator navigation (tasks, teams, diff) |63| `Footer` | Footer indicator navigation (tasks, teams, diff) |

61| `DiffDialog` | Diff viewer navigation |65| `DiffDialog` | Diff viewer navigation |

62| `ModelPicker` | Model picker effort level |66| `ModelPicker` | Model picker effort level |

63| `Select` | Generic select/list components |67| `Select` | Generic select/list components |

93Actions available in the `Chat` context:97Actions available in the `Chat` context:

94 98

~~96| :-------------------- | :------------------------ | :----------------------- |~~100| :-------------------- | :------------------------ | :---------------------------------- |

102| `chat:killAgents` | Ctrl+X Ctrl+K | Kill all background agents |

105| `chat:fastMode` | Meta+O | Toggle fast mode |

108| `chat:newline` | (unbound) | Insert a newline without submitting |

106 113

206 213

207### Footer actions214### Footer actions

208 215

209Actions available in the `Footer` context:216Actions available in the `Footer` context:

210 217

212| :---------------------- | :------ | :------------------------ |219| :---------------------- | :------ | :--------------------------------------- |

222| `footer:up` | Up | Navigate up in footer (deselects at top) |

223| `footer:down` | Down | Navigate down in footer |

217 226

221 230

223| :----------------------- | :---------------------------------------- | :---------------- |232| :----------------------- | :---------------------------------------- | :---------------- |

279| `settings:search` | / | Enter search mode |288| `settings:search` | / | Enter search mode |

280| `settings:retry` | R | Retry loading usage data (on error) |289| `settings:retry` | R | Retry loading usage data (on error) |

281 290

291### Voice actions

292

293Actions available in the `Chat` context when [voice dictation](/en/voice-dictation) is enabled:

294

295| Action | Default | Description |

296| :----------------- | :------ | :----------------------- |

297| `voice:pushToTalk` | Space | Hold to dictate a prompt |

298

282## Keystroke syntax299## Keystroke syntax

283 300

284### Modifiers301### Modifiers

292 309

293For example:310For example:

294 311

295```312```text theme={null}

296ctrl+k Single key with modifier313ctrl+k Single key with modifier

297shift+tab Shift + Tab314shift+tab Shift + Tab

298meta+p Command/Meta + P315meta+p Command/Meta + P

303 320

304A standalone uppercase letter implies Shift. For example, `K` is equivalent to `shift+k`. This is useful for vim-style bindings where uppercase and lowercase keys have different meanings.321A standalone uppercase letter implies Shift. For example, `K` is equivalent to `shift+k`. This is useful for vim-style bindings where uppercase and lowercase keys have different meanings.

305 322

306Uppercase letters with modifiers (e.g., `ctrl+K`) are treated as stylistic and do **not** imply Shift — `ctrl+K` is the same as `ctrl+k`.323Uppercase letters with modifiers (e.g., `ctrl+K`) are treated as stylistic and do **not** imply Shift: `ctrl+K` is the same as `ctrl+k`.

307 324

308### Chords325### Chords

309 326

310Chords are sequences of keystrokes separated by spaces:327Chords are sequences of keystrokes separated by spaces:

311 328

312```329```text theme={null}

313ctrl+k ctrl+s Press Ctrl+K, release, then Ctrl+S330ctrl+k ctrl+s Press Ctrl+K, release, then Ctrl+S

314```331```

315 332

339}356}

340```357```

341 358

359This also works for chord bindings. Unbinding every chord that shares a prefix frees that prefix for use as a single-key binding:

360

361```json theme={null}

362{

363 "bindings": [

364 {

365 "context": "Chat",

366 "bindings": {

367 "ctrl+x ctrl+k": null,

368 "ctrl+x ctrl+e": null,

369 "ctrl+x": "chat:newline"

370 }

371 }

372 ]

373}

374```

375

376If you unbind some but not all chords on a prefix, pressing the prefix still enters chord-wait mode for the remaining bindings.

377

342## Reserved shortcuts378## Reserved shortcuts

343 379

344These shortcuts cannot be rebound:380These shortcuts cannot be rebound:

345 381

346| Shortcut | Reason |382| Shortcut | Reason |

347| :------- | :------------------------- |383| :------- | :--------------------------------------------- |

348| Ctrl+C | Hardcoded interrupt/cancel |384| Ctrl+C | Hardcoded interrupt/cancel |

349| Ctrl+D | Hardcoded exit |385| Ctrl+D | Hardcoded exit |

386| Ctrl+M | Identical to Enter in terminals (both send CR) |

350 387

351## Terminal conflicts388## Terminal conflicts

352 389

legal-and-compliance.md +19 −2

Details

13Your use of Claude Code is subject to:13Your use of Claude Code is subject to:

14 14

15* [Commercial Terms](https://www.anthropic.com/legal/commercial-terms) - for Team, Enterprise, and Claude API users15* [Commercial Terms](https://www.anthropic.com/legal/commercial-terms) - for Team, Enterprise, and Claude API users

~~16* [Consumer Terms](https://www.anthropic.com/legal/consumer-terms) - for Free, Pro, and Max users~~16* [Consumer Terms of Service](https://www.anthropic.com/legal/consumer-terms) - for Free, Pro, and Max users

17 17

18### Commercial agreements18### Commercial agreements

19 19

23 23

24### Healthcare compliance (BAA)24### Healthcare compliance (BAA)

25 25

26If a customer has a Business Associate Agreement (BAA) with us, and wants to use Claude Code, the BAA will automatically extend to cover Claude Code if the customer has executed a BAA and has Zero Data Retention (ZDR) activated. The BAA will be applicable to that customer's API traffic flowing through Claude Code.26If a customer has a Business Associate Agreement (BAA) with us, and wants to use Claude Code, the BAA will automatically extend to cover Claude Code if the customer has executed a BAA and has [Zero Data Retention (ZDR)](/en/zero-data-retention) activated. The BAA will be applicable to that customer's API traffic flowing through Claude Code. ZDR is enabled on a per-organization basis, so each organization must have ZDR enabled separately to be covered under the BAA.

28## Usage policy

30### Acceptable use

32Claude Code usage is subject to the [Anthropic Usage Policy](https://www.anthropic.com/legal/aup). Advertised usage limits for Pro and Max plans assume ordinary, individual usage of Claude Code and the Agent SDK.

34### Authentication and credential use

36Claude Code authenticates with Anthropic's servers using OAuth tokens or API keys. These authentication methods serve different purposes:

38* **OAuth authentication** (used with Free, Pro, and Max plans) is intended exclusively for Claude Code and Claude.ai. Using OAuth tokens obtained through Claude Free, Pro, or Max accounts in any other product, tool, or service — including the [Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview) — is not permitted and constitutes a violation of the [Consumer Terms of Service](https://www.anthropic.com/legal/consumer-terms).

39* **Developers** building products or services that interact with Claude's capabilities, including those using the [Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview), should use API key authentication through [Claude Console](https://platform.claude.com/) or a supported cloud provider. Anthropic does not permit third-party developers to offer Claude.ai login or to route requests through Free, Pro, or Max plan credentials on behalf of their users.

41Anthropic reserves the right to take measures to enforce these restrictions and may do so without prior notice.

43For questions about permitted authentication methods for your use case, please [contact sales](https://www.anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=legal_compliance_contact_sales).

27 44

28## Security and trust45## Security and trust

29 46

llm-gateway.md +16 −2

Details

37 Claude Code determines which features to enable based on the API format. When using the Anthropic Messages format with Bedrock or Vertex, you may need to set environment variable `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`.37 Claude Code determines which features to enable based on the API format. When using the Anthropic Messages format with Bedrock or Vertex, you may need to set environment variable `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`.

38</Note>38</Note>

39 39

40**Request headers**

42Claude Code includes the following headers on every API request:

44| Header | Description |

45| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

46| `X-Claude-Code-Session-Id` | A unique identifier for the current Claude Code session. Proxies can use this to aggregate all API requests from a single session without parsing the request body. |

40## Configuration48## Configuration

41 49

42### Model selection50### Model selection

47 55

48## LiteLLM configuration56## LiteLLM configuration

49 57

~~50<Note>~~58<Warning>

59 LiteLLM PyPI versions 1.82.7 and 1.82.8 were compromised with credential-stealing malware. Do not install these versions. If you have already installed them:

61 * Remove the package

62 * Rotate all credentials on affected systems

63 * Follow the remediation steps in [BerriAI/litellm#24518](https://github.com/BerriAI/litellm/issues/24518)

51 LiteLLM is a third-party proxy service. Anthropic doesn't endorse, maintain, or audit LiteLLM's security or functionality. This guide is provided for informational purposes and may become outdated. Use at your own discretion.65 LiteLLM is a third-party proxy service. Anthropic doesn't endorse, maintain, or audit LiteLLM's security or functionality. This guide is provided for informational purposes and may become outdated. Use at your own discretion.

~~52</Note>~~66</Warning>

53 67

54### Prerequisites68### Prerequisites

55 69

mcp.md +302 −54

Details

18* **Query databases**: "Find emails of 10 random users who used feature ENG-4521, based on our PostgreSQL database."18* **Query databases**: "Find emails of 10 random users who used feature ENG-4521, based on our PostgreSQL database."

19* **Integrate designs**: "Update our standard email template based on the new Figma designs that were posted in Slack"19* **Integrate designs**: "Update our standard email template based on the new Figma designs that were posted in Slack"

20* **Automate workflows**: "Create Gmail drafts inviting these 10 users to a feedback session about the new feature."20* **Automate workflows**: "Create Gmail drafts inviting these 10 users to a feedback session about the new feature."

21* **React to external events**: An MCP server can also act as a [channel](/en/channels) that pushes messages into your session, so Claude reacts to Telegram messages, Discord chats, or webhook events while you're away.

21 22

22## Popular MCP servers23## Popular MCP servers

23 24

123 124

124Claude Code supports MCP `list_changed` notifications, allowing MCP servers to dynamically update their available tools, prompts, and resources without requiring you to disconnect and reconnect. When an MCP server sends a `list_changed` notification, Claude Code automatically refreshes the available capabilities from that server.125Claude Code supports MCP `list_changed` notifications, allowing MCP servers to dynamically update their available tools, prompts, and resources without requiring you to disconnect and reconnect. When an MCP server sends a `list_changed` notification, Claude Code automatically refreshes the available capabilities from that server.

125 126

127### Push messages with channels

128

129An MCP server can also push messages directly into your session so Claude can react to external events like CI results, monitoring alerts, or chat messages. To enable this, your server declares the `claude/channel` capability and you opt it in with the `--channels` flag at startup. See [Channels](/en/channels) to use an officially supported channel, or [Channels reference](/en/channels-reference) to build your own.

130

126<Tip>131<Tip>

127 Tips:132 Tips:

128 133

164 169

165```json theme={null}170```json theme={null}

166{171{

172 "mcpServers": {

167 "database-tools": {173 "database-tools": {

168 "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",174 "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",

169 "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],175 "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],

171 "DB_URL": "${DB_URL}"177 "DB_URL": "${DB_URL}"

172 }178 }

173 }179 }

180 }

174}181}

175```182```

176 183

190 197

191**Plugin MCP features**:198**Plugin MCP features**:

192 199

193* **Automatic lifecycle**: Servers start when plugin enables, but you must restart Claude Code to apply MCP server changes (enabling or disabling)200* **Automatic lifecycle**: At session startup, servers for enabled plugins connect automatically. If you enable or disable a plugin during a session, run `/reload-plugins` to connect or disconnect its MCP servers

194* **Environment variables**: Use `${CLAUDE_PLUGIN_ROOT}` for plugin-relative paths201* **Environment variables**: use `${CLAUDE_PLUGIN_ROOT}` for bundled plugin files and `${CLAUDE_PLUGIN_DATA}` for [persistent state](/en/plugins-reference#persistent-data-directory) that survives plugin updates

195* **User environment access**: Access to same environment variables as manually configured servers202* **User environment access**: Access to same environment variables as manually configured servers

196* **Multiple transport types**: Support stdio, SSE, and HTTP transports (transport support may vary by server)203* **Multiple transport types**: Support stdio, SSE, and HTTP transports (transport support may vary by server)

197 204

286 293

287MCP server configurations follow a clear precedence hierarchy. When servers with the same name exist at multiple scopes, the system resolves conflicts by prioritizing local-scoped servers first, followed by project-scoped servers, and finally user-scoped servers. This design ensures that personal configurations can override shared ones when needed.294MCP server configurations follow a clear precedence hierarchy. When servers with the same name exist at multiple scopes, the system resolves conflicts by prioritizing local-scoped servers first, followed by project-scoped servers, and finally user-scoped servers. This design ensures that personal configurations can override shared ones when needed.

288 295

296If a server is configured both locally and through a [claude.ai connector](#use-mcp-servers-from-claude-ai), the local configuration takes precedence and the connector entry is skipped.

297

289### Environment variable expansion in `.mcp.json`298### Environment variable expansion in `.mcp.json`

290 299

291Claude Code supports environment variable expansion in `.mcp.json` files, allowing teams to share configurations while maintaining flexibility for machine-specific paths and sensitive values like API keys.300Claude Code supports environment variable expansion in `.mcp.json` files, allowing teams to share configurations while maintaining flexibility for machine-specific paths and sensitive values like API keys.

327{/* ### Example: Automate browser testing with Playwright336{/* ### Example: Automate browser testing with Playwright

328 337

329 ```bash338 ```bash

330 # 1. Add the Playwright MCP server

331 claude mcp add --transport stdio playwright -- npx -y @playwright/mcp@latest339 claude mcp add --transport stdio playwright -- npx -y @playwright/mcp@latest

340 ```

341

342 Then write and run browser tests:

332 343

333 # 2. Write and run browser tests344 ```text

334 > "Test if the login flow works with test@example.com"345 Test if the login flow works with test@example.com

335 > "Take a screenshot of the checkout page on mobile"346 ```

336 > "Verify that the search feature returns results"347 ```text

348 Take a screenshot of the checkout page on mobile

349 ```

350 ```text

351 Verify that the search feature returns results

337 ``` */}352 ``` */}

338 353

339### Example: Monitor errors with Sentry354### Example: Monitor errors with Sentry

340 355

341```bash theme={null}356```bash theme={null}

342# 1. Add the Sentry MCP server

343claude mcp add --transport http sentry https://mcp.sentry.dev/mcp357claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

358```

344 359

345# 2. Use /mcp to authenticate with your Sentry account360Authenticate with your Sentry account:

346> /mcp

347 361

348# 3. Debug production issues362```text theme={null}

349> "What are the most common errors in the last 24 hours?"363/mcp

350> "Show me the stack trace for error ID abc123"364```

351> "Which deployment introduced these new errors?"365

366Then debug production issues:

367

368```text theme={null}

369What are the most common errors in the last 24 hours?

370```

371

372```text theme={null}

373Show me the stack trace for error ID abc123

374```

375

376```text theme={null}

377Which deployment introduced these new errors?

352```378```

353 379

354### Example: Connect to GitHub for code reviews380### Example: Connect to GitHub for code reviews

355 381

356```bash theme={null}382```bash theme={null}

357# 1. Add the GitHub MCP server

358claude mcp add --transport http github https://api.githubcopilot.com/mcp/383claude mcp add --transport http github https://api.githubcopilot.com/mcp/

384```

359 385

360# 2. In Claude Code, authenticate if needed386Authenticate if needed by selecting "Authenticate" for GitHub:

361> /mcp

362# Select "Authenticate" for GitHub

363 387

364# 3. Now you can ask Claude to work with GitHub388```text theme={null}

365> "Review PR #456 and suggest improvements"389/mcp

366> "Create a new issue for the bug we just found"390```

367> "Show me all open PRs assigned to me"391

392Then work with GitHub:

393

394```text theme={null}

395Review PR #456 and suggest improvements

396```

397

398```text theme={null}

399Create a new issue for the bug we just found

400```

401

402```text theme={null}

403Show me all open PRs assigned to me

368```404```

369 405

370### Example: Query your PostgreSQL database406### Example: Query your PostgreSQL database

371 407

372```bash theme={null}408```bash theme={null}

373# 1. Add the database server with your connection string

374claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \409claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \

375 --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"410 --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

411```

376 412

377# 2. Query your database naturally413Then query your database naturally:

378> "What's our total revenue this month?"414

379> "Show me the schema for the orders table"415```text theme={null}

380> "Find customers who haven't made a purchase in 90 days"416What's our total revenue this month?

417```

418

419```text theme={null}

420Show me the schema for the orders table

421```

422

423```text theme={null}

424Find customers who haven't made a purchase in 90 days

381```425```

382 426

383## Authenticate with remote MCP servers427## Authenticate with remote MCP servers

396 <Step title="Use the /mcp command within Claude Code">440 <Step title="Use the /mcp command within Claude Code">

397 In Claude code, use the command:441 In Claude code, use the command:

398 442

399 ```443 ```text theme={null}

400 > /mcp444 /mcp

401 ```445 ```

402 446

403 Then follow the steps in your browser to login.447 Then follow the steps in your browser to login.

409 453

410 * Authentication tokens are stored securely and refreshed automatically454 * Authentication tokens are stored securely and refreshed automatically

411 * Use "Clear authentication" in the `/mcp` menu to revoke access455 * Use "Clear authentication" in the `/mcp` menu to revoke access

412 * If your browser doesn't open automatically, copy the provided URL456 * If your browser doesn't open automatically, copy the provided URL and open it manually

457 * If the browser redirect fails with a connection error after authenticating, paste the full callback URL from your browser's address bar into the URL prompt that appears in Claude Code

413 * OAuth authentication works with HTTP servers458 * OAuth authentication works with HTTP servers

414</Tip>459</Tip>

415 460

461### Use a fixed OAuth callback port

462

463Some MCP servers require a specific redirect URI registered in advance. By default, Claude Code picks a random available port for the OAuth callback. Use `--callback-port` to fix the port so it matches a pre-registered redirect URI of the form `http://localhost:PORT/callback`.

464

465You can use `--callback-port` on its own (with dynamic client registration) or together with `--client-id` (with pre-configured credentials).

466

467```bash theme={null}

468# Fixed callback port with dynamic client registration

469claude mcp add --transport http \

470 --callback-port 8080 \

471 my-server https://mcp.example.com/mcp

472```

473

474### Use pre-configured OAuth credentials

475

476Some MCP servers don't support automatic OAuth setup via Dynamic Client Registration. If you see an error like "Incompatible auth server: does not support dynamic client registration," the server requires pre-configured credentials. Claude Code also supports servers that use a Client ID Metadata Document (CIMD) instead of Dynamic Client Registration, and discovers these automatically. If automatic discovery fails, register an OAuth app through the server's developer portal first, then provide the credentials when adding the server.

477

478<Steps>

479 <Step title="Register an OAuth app with the server">

480 Create an app through the server's developer portal and note your client ID and client secret.

481

482 Many servers also require a redirect URI. If so, choose a port and register a redirect URI in the format `http://localhost:PORT/callback`. Use that same port with `--callback-port` in the next step.

483 </Step>

484

485 <Step title="Add the server with your credentials">

486 Choose one of the following methods. The port used for `--callback-port` can be any available port. It just needs to match the redirect URI you registered in the previous step.

487

488 <Tabs>

489 <Tab title="claude mcp add">

490 Use `--client-id` to pass your app's client ID. The `--client-secret` flag prompts for the secret with masked input:

491

492 ```bash theme={null}

493 claude mcp add --transport http \

494 --client-id your-client-id --client-secret --callback-port 8080 \

495 my-server https://mcp.example.com/mcp

496 ```

497 </Tab>

498

499 <Tab title="claude mcp add-json">

500 Include the `oauth` object in the JSON config and pass `--client-secret` as a separate flag:

501

502 ```bash theme={null}

503 claude mcp add-json my-server \

504 '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \

505 --client-secret

506 ```

507 </Tab>

508

509 <Tab title="claude mcp add-json (callback port only)">

510 Use `--callback-port` without a client ID to fix the port while using dynamic client registration:

511

512 ```bash theme={null}

513 claude mcp add-json my-server \

514 '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"callbackPort":8080}}'

515 ```

516 </Tab>

517

518 <Tab title="CI / env var">

519 Set the secret via environment variable to skip the interactive prompt:

520

521 ```bash theme={null}

522 MCP_CLIENT_SECRET=your-secret claude mcp add --transport http \

523 --client-id your-client-id --client-secret --callback-port 8080 \

524 my-server https://mcp.example.com/mcp

525 ```

526 </Tab>

527 </Tabs>

528 </Step>

529

530 <Step title="Authenticate in Claude Code">

531 Run `/mcp` in Claude Code and follow the browser login flow.

532 </Step>

533</Steps>

534

535<Tip>

536 Tips:

537

538 * The client secret is stored securely in your system keychain (macOS) or a credentials file, not in your config

539 * If the server uses a public OAuth client with no secret, use only `--client-id` without `--client-secret`

540 * `--callback-port` can be used with or without `--client-id`

541 * These flags only apply to HTTP and SSE transports. They have no effect on stdio servers

542 * Use `claude mcp get <name>` to verify that OAuth credentials are configured for a server

543</Tip>

544

545### Override OAuth metadata discovery

546

547If your MCP server's standard OAuth metadata endpoints return errors but the server exposes a working OIDC endpoint, you can point Claude Code at a specific metadata URL to bypass the default discovery chain. By default, Claude Code first checks RFC 9728 Protected Resource Metadata at `/.well-known/oauth-protected-resource`, then falls back to RFC 8414 authorization server metadata at `/.well-known/oauth-authorization-server`.

548

549Set `authServerMetadataUrl` in the `oauth` object of your server's config in `.mcp.json`:

550

551```json theme={null}

552{

553 "mcpServers": {

554 "my-server": {

555 "type": "http",

556 "url": "https://mcp.example.com/mcp",

557 "oauth": {

558 "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration"

559 }

560 }

561 }

562}

563```

564

565The URL must use `https://`. This option requires Claude Code v2.1.64 or later.

566

567### Use dynamic headers for custom authentication

568

569If your MCP server uses an authentication scheme other than OAuth (such as Kerberos, short-lived tokens, or an internal SSO), use `headersHelper` to generate request headers at connection time. Claude Code runs the command and merges its output into the connection headers.

570

571```json theme={null}

572{

573 "mcpServers": {

574 "internal-api": {

575 "type": "http",

576 "url": "https://mcp.internal.example.com",

577 "headersHelper": "/opt/bin/get-mcp-auth-headers.sh"

578 }

579 }

580}

581```

582

583The command can also be inline:

584

585```json theme={null}

586{

587 "mcpServers": {

588 "internal-api": {

589 "type": "http",

590 "url": "https://mcp.internal.example.com",

591 "headersHelper": "echo '{\"Authorization\": \"Bearer '\"$(get-token)\"'\"}'"

592 }

593 }

594}

595```

596

597**Requirements:**

598

599* The command must write a JSON object of string key-value pairs to stdout

600* The command runs in a shell with a 10-second timeout

601* Dynamic headers override any static `headers` with the same name

602

603The helper runs fresh on each connection (at session start and on reconnect). There is no caching, so your script is responsible for any token reuse.

604

605Claude Code sets these environment variables when executing the helper:

606

607| Variable | Value |

608| :---------------------------- | :------------------------- |

609| `CLAUDE_CODE_MCP_SERVER_NAME` | the name of the MCP server |

610| `CLAUDE_CODE_MCP_SERVER_URL` | the URL of the MCP server |

611

612Use these to write a single helper script that serves multiple MCP servers.

613

614<Note>

615 `headersHelper` executes arbitrary shell commands. When defined at project or local scope, it only runs after you accept the workspace trust dialog.

616</Note>

617

416## Add MCP servers from JSON configuration618## Add MCP servers from JSON configuration

417 619

418If you have a JSON configuration for an MCP server, you can add it directly:620If you have a JSON configuration for an MCP server, you can add it directly:

428 630

429 # Example: Adding a stdio server with JSON configuration631 # Example: Adding a stdio server with JSON configuration

430 claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'632 claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

633

634 # Example: Adding an HTTP server with pre-configured OAuth credentials

635 claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' --client-secret

431 ```636 ```

432 </Step>637 </Step>

433 638

479 * If servers with the same names already exist, they will get a numerical suffix (for example, `server_1`)684 * If servers with the same names already exist, they will get a numerical suffix (for example, `server_1`)

480</Tip>685</Tip>

481 686

687## Use MCP servers from Claude.ai

688

689If you've logged into Claude Code with a [Claude.ai](https://claude.ai) account, MCP servers you've added in Claude.ai are automatically available in Claude Code:

690

691<Steps>

692 <Step title="Configure MCP servers in Claude.ai">

693 Add servers at [claude.ai/settings/connectors](https://claude.ai/settings/connectors). On Team and Enterprise plans, only admins can add servers.

694 </Step>

695

696 <Step title="Authenticate the MCP server">

697 Complete any required authentication steps in Claude.ai.

698 </Step>

699

700 <Step title="View and manage servers in Claude Code">

701 In Claude Code, use the command:

702

703 ```text theme={null}

704 /mcp

705 ```

706

707 Claude.ai servers appear in the list with indicators showing they come from Claude.ai.

708 </Step>

709</Steps>

710

711To disable claude.ai MCP servers in Claude Code, set the `ENABLE_CLAUDEAI_MCP_SERVERS` environment variable to `false`:

712

713```bash theme={null}

714ENABLE_CLAUDEAI_MCP_SERVERS=false claude

715```

716

482## Use Claude Code as an MCP server717## Use Claude Code as an MCP server

483 718

484You can use Claude Code itself as an MCP server that other applications can connect to:719You can use Claude Code itself as an MCP server that other applications can connect to:

564 If you frequently encounter output warnings with specific MCP servers, consider increasing the limit or configuring the server to paginate or filter its responses.799 If you frequently encounter output warnings with specific MCP servers, consider increasing the limit or configuring the server to paginate or filter its responses.

565</Warning>800</Warning>

566 801

802## Respond to MCP elicitation requests

803

804MCP servers can request structured input from you mid-task using elicitation. When a server needs information it can't get on its own, Claude Code displays an interactive dialog and passes your response back to the server. No configuration is required on your side: elicitation dialogs appear automatically when a server requests them.

805

806Servers can request input in two ways:

807

808* **Form mode**: Claude Code shows a dialog with form fields defined by the server (for example, a username and password prompt). Fill in the fields and submit.

809* **URL mode**: Claude Code opens a browser URL for authentication or approval. Complete the flow in the browser, then confirm in the CLI.

810

811To auto-respond to elicitation requests without showing a dialog, use the [`Elicitation` hook](/en/hooks#elicitation).

812

813If you're building an MCP server that uses elicitation, see the [MCP elicitation specification](https://modelcontextprotocol.io/docs/learn/client-concepts#elicitation) for protocol details and schema examples.

814

567## Use MCP resources815## Use MCP resources

568 816

569MCP servers can expose resources that you can reference using @ mentions, similar to how you reference files.817MCP servers can expose resources that you can reference using @ mentions, similar to how you reference files.

578 <Step title="Reference a specific resource">826 <Step title="Reference a specific resource">

579 Use the format `@server:protocol://resource/path` to reference a resource:827 Use the format `@server:protocol://resource/path` to reference a resource:

580 828

581 ```829 ```text theme={null}

582 > Can you analyze @github:issue://123 and suggest a fix?830 Can you analyze @github:issue://123 and suggest a fix?

583 ```831 ```

584 832

585 ```833 ```text theme={null}

586 > Please review the API documentation at @docs:file://api/authentication834 Please review the API documentation at @docs:file://api/authentication

587 ```835 ```

588 </Step>836 </Step>

589 837

590 <Step title="Multiple resource references">838 <Step title="Multiple resource references">

591 You can reference multiple resources in a single prompt:839 You can reference multiple resources in a single prompt:

592 840

593 ```841 ```text theme={null}

594 > Compare @postgres:schema://users with @docs:file://database/user-model842 Compare @postgres:schema://users with @docs:file://database/user-model

595 ```843 ```

596 </Step>844 </Step>

597</Steps>845</Steps>

607 855

608## Scale with MCP Tool Search856## Scale with MCP Tool Search

609 857

610When you have many MCP servers configured, tool definitions can consume a significant portion of your context window. MCP Tool Search solves this by dynamically loading tools on-demand instead of preloading all of them.858Tool search keeps MCP context usage low by deferring tool definitions until Claude needs them. Only tool names load at session start, so adding more MCP servers has minimal impact on your context window.

611 859

612### How it works860### How it works

613 861

614Claude Code automatically enables Tool Search when your MCP tool descriptions would consume more than 10% of the context window. You can [adjust this threshold](#configure-tool-search) or disable tool search entirely. When triggered:862Tool search is enabled by default. MCP tools are deferred rather than loaded into context upfront, and Claude uses a search tool to discover relevant ones when a task needs them. Only the tools Claude actually uses enter context. From your perspective, MCP tools work exactly as before.

615 863

6161. MCP tools are deferred rather than loaded into context upfront864If you prefer threshold-based loading, set `ENABLE_TOOL_SEARCH=auto` to load schemas upfront when they fit within 10% of the context window and defer only the overflow. See [Configure tool search](#configure-tool-search) for all options.

6172. Claude uses a search tool to discover relevant MCP tools when needed

6183. Only the tools Claude actually needs are loaded into context

6194. MCP tools continue to work exactly as before from your perspective

620 865

621### For MCP server authors866### For MCP server authors

622 867

628* When Claude should search for your tools873* When Claude should search for your tools

629* Key capabilities your server provides874* Key capabilities your server provides

630 875

876Claude Code truncates tool descriptions and server instructions at 2KB each. Keep them concise to avoid truncation, and put critical details near the start.

877

631### Configure tool search878### Configure tool search

632 879

633Tool search runs in auto mode by default, meaning it activates only when your MCP tool definitions exceed the context threshold. If you have few tools, they load normally without tool search. This feature requires models that support `tool_reference` blocks: Sonnet 4 and later, or Opus 4 and later. Haiku models do not support tool search.880Tool search is enabled by default: MCP tools are deferred and discovered on demand. When `ANTHROPIC_BASE_URL` points to a non-first-party host, tool search is disabled by default because most proxies do not forward `tool_reference` blocks. Set `ENABLE_TOOL_SEARCH` explicitly if your proxy does. This feature requires models that support `tool_reference` blocks: Sonnet 4 and later, or Opus 4 and later. Haiku models do not support tool search.

634 881

635Control tool search behavior with the `ENABLE_TOOL_SEARCH` environment variable:882Control tool search behavior with the `ENABLE_TOOL_SEARCH` environment variable:

636 883

637| Value | Behavior |884| Value | Behavior |

638| :--------- | :--------------------------------------------------------------------------------- |885| :--------- | :----------------------------------------------------------------------------------------------------------------------------- |

890| `false` | All MCP tools loaded upfront, no deferral |

643 891

644```bash theme={null}892```bash theme={null}

645# Use a custom 5% threshold893# Use a custom 5% threshold

673 </Step>921 </Step>

674 922

675 <Step title="Execute a prompt without arguments">923 <Step title="Execute a prompt without arguments">

676 ```924 ```text theme={null}

677 > /mcp__github__list_prs925 /mcp__github__list_prs

678 ```926 ```

679 </Step>927 </Step>

680 928

681 <Step title="Execute a prompt with arguments">929 <Step title="Execute a prompt with arguments">

682 Many prompts accept arguments. Pass them space-separated after the command:930 Many prompts accept arguments. Pass them space-separated after the command:

683 931

684 ```932 ```text theme={null}

685 > /mcp__github__pr_review 456933 /mcp__github__pr_review 456

686 ```934 ```

687 935

688 ```936 ```text theme={null}

689 > /mcp__jira__create_issue "Bug in login flow" high937 /mcp__jira__create_issue "Bug in login flow" high

690 ```938 ```

691 </Step>939 </Step>

692</Steps>940</Steps>

memory.md +264 −115

Details

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt2> 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.3> Use this file to discover all available pages before exploring further.

4 4

~~5# Manage Claude's memory~~5# How Claude remembers your project

6 6

~~7> Learn how to manage Claude Code's memory across sessions with different memory locations and best practices.~~7> Give Claude persistent instructions with CLAUDE.md files, and let Claude accumulate learnings automatically with auto memory.

8 8

~~9Claude Code can remember your preferences across sessions, like style guidelines and common commands in your workflow.~~9Each Claude Code session begins with a fresh context window. Two mechanisms carry knowledge across sessions:

10 10

~~11## Determine memory type~~11* **CLAUDE.md files**: instructions you write to give Claude persistent context

12* **Auto memory**: notes Claude writes itself based on your corrections and preferences

12 13

~~13Claude Code offers four memory locations in a hierarchical structure, each serving a different purpose:~~14This page covers how to:

14 15

16| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------- |17* [Scope rules to specific file types](#organize-rules-with-claude/rules/) with `.claude/rules/`

17| **Managed policy** | • macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md` • Linux: `/etc/claude-code/CLAUDE.md` • Windows: `C:\Program Files\ClaudeCode\CLAUDE.md` | Organization-wide instructions managed by IT/DevOps | Company coding standards, security policies, compliance requirements | All users in organization |18* [Configure auto memory](#auto-memory) so Claude takes notes automatically

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

22 20

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.21## CLAUDE.md vs auto memory

24 22

~~25<Note>~~23Claude Code has two complementary memory systems. Both are loaded at the start of every conversation. Claude treats them as context, not enforced configuration. The more specific and concise your instructions, the more consistently Claude follows them.

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

~~27</Note>~~

28 24

~~29## CLAUDE.md imports~~25| | CLAUDE.md files | Auto memory |

26| :------------------- | :------------------------------------------------ | :--------------------------------------------------------------- |

27| **Who writes it** | You | Claude |

28| **What it contains** | Instructions and rules | Learnings and patterns |

29| **Scope** | Project, user, or org | Per working tree |

30| **Loaded into** | Every session | Every session (first 200 lines or 25KB) |

31| **Use for** | Coding standards, workflows, project architecture | Build commands, debugging insights, preferences Claude discovers |

30 32

~~31CLAUDE.md files can import additional files using `@path/to/import` syntax. The following example imports 3 files:~~33Use CLAUDE.md files when you want to guide Claude's behavior. Auto memory lets Claude learn from your corrections without manual effort.

32 34

~~33```~~35Subagents can also maintain their own auto memory. See [subagent configuration](/en/sub-agents#enable-persistent-memory) for details.

37## CLAUDE.md files

39CLAUDE.md files are markdown files that give Claude persistent instructions for a project, your personal workflow, or your entire organization. You write these files in plain text; Claude reads them at the start of every session.

41### Choose where to put CLAUDE.md files

43CLAUDE.md files can live in several locations, each with a different scope. More specific locations take precedence over broader ones.

46| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------- |

47| **Managed policy** | • macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md` • Linux and WSL: `/etc/claude-code/CLAUDE.md` • Windows: `C:\Program Files\ClaudeCode\CLAUDE.md` | Organization-wide instructions managed by IT/DevOps | Company coding standards, security policies, compliance requirements | All users in organization |

51CLAUDE.md files in the directory hierarchy above the working directory are loaded in full at launch. CLAUDE.md files in subdirectories load on demand when Claude reads files in those directories. See [How CLAUDE.md files load](#how-claude-md-files-load) for the full resolution order.

53For large projects, you can break instructions into topic-specific files using [project rules](#organize-rules-with-claude/rules/). Rules let you scope instructions to specific file types or subdirectories.

55### Set up a project CLAUDE.md

57A project CLAUDE.md can be stored in either `./CLAUDE.md` or `./.claude/CLAUDE.md`. Create this file and add instructions that apply to anyone working on the project: build and test commands, coding standards, architectural decisions, naming conventions, and common workflows. These instructions are shared with your team through version control, so focus on project-level standards rather than personal preferences.

59<Tip>

60 Run `/init` to generate a starting CLAUDE.md automatically. Claude analyzes your codebase and creates a file with build commands, test instructions, and project conventions it discovers. If a CLAUDE.md already exists, `/init` suggests improvements rather than overwriting it. Refine from there with instructions Claude wouldn't discover on its own.

62 Set `CLAUDE_CODE_NEW_INIT=true` to enable an interactive multi-phase flow. `/init` asks which artifacts to set up: CLAUDE.md files, skills, and hooks. It then explores your codebase with a subagent, fills in gaps via follow-up questions, and presents a reviewable proposal before writing any files.

63</Tip>

65### Write effective instructions

67CLAUDE.md files are loaded into the context window at the start of every session, consuming tokens alongside your conversation. The [context window visualization](/en/context-window) shows where CLAUDE.md loads relative to the rest of the startup context. Because they're context rather than enforced configuration, how you write instructions affects how reliably Claude follows them. Specific, concise, well-structured instructions work best.

69**Size**: target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence. If your instructions are growing large, split them using [imports](#import-additional-files) or [`.claude/rules/`](#organize-rules-with-claude/rules/) files.

71**Structure**: use markdown headers and bullets to group related instructions. Claude scans structure the same way readers do: organized sections are easier to follow than dense paragraphs.

73**Specificity**: write instructions that are concrete enough to verify. For example:

75* "Use 2-space indentation" instead of "Format code properly"

76* "Run `npm test` before committing" instead of "Test your changes"

77* "API handlers live in `src/api/handlers/`" instead of "Keep files organized"

79**Consistency**: if two rules contradict each other, Claude may pick one arbitrarily. Review your CLAUDE.md files, nested CLAUDE.md files in subdirectories, and [`.claude/rules/`](#organize-rules-with-claude/rules/) periodically to remove outdated or conflicting instructions. In monorepos, use [`claudeMdExcludes`](#exclude-specific-claude-md-files) to skip CLAUDE.md files from other teams that aren't relevant to your work.

81### Import additional files

83CLAUDE.md files can import additional files using `@path/to/import` syntax. Imported files are expanded and loaded into context at launch alongside the CLAUDE.md that references them.

85Both relative and absolute paths are allowed. Relative paths resolve relative to the file containing the import, not the working directory. Imported files can recursively import other files, with a maximum depth of five hops.

87To pull in a README, package.json, and a workflow guide, reference them with `@` syntax anywhere in your CLAUDE.md:

89```text theme={null}

34See @README for project overview and @package.json for available npm commands for this project.90See @README for project overview and @package.json for available npm commands for this project.

35 91

36# Additional Instructions92# Additional Instructions

37- git workflow @docs/git-instructions.md93- git workflow @docs/git-instructions.md

38```94```

39 95

40Both relative and absolute paths are allowed. Relative paths resolve relative to the file containing the import, not the working directory. For private per-project preferences that shouldn't be checked into version control, prefer `CLAUDE.local.md`: it is automatically loaded and added to `.gitignore`.96For personal preferences you don't want to check in, import a file from your home directory. The import goes in the shared CLAUDE.md, but the file it points to stays on your machine:

~~42If you work across multiple git worktrees, `CLAUDE.local.md` only exists in one. Use a home-directory import instead so all worktrees share the same personal instructions:~~

43 97

~~44```~~98```text theme={null}

45# Individual Preferences99# Individual Preferences

46- @~/.claude/my-project-instructions.md100- @~/.claude/my-project-instructions.md

47```101```

48 102

49<Warning>103<Warning>

50 The first time Claude Code encounters external imports in a project, it shows an approval dialog listing the specific files. Approve to load them; decline to skip them. This is a one-time decision per project: once declined, the dialog does not resurface and the imports remain disabled.104 The first time Claude Code encounters external imports in a project, it shows an approval dialog listing the files. If you decline, the imports stay disabled and the dialog does not appear again.

51</Warning>105</Warning>

52 106

~~53To avoid potential collisions, imports are not evaluated inside markdown code spans and code blocks.~~107For a more structured approach to organizing instructions, see [`.claude/rules/`](#organize-rules-with-claude/rules/).

54 108

~~55```~~109### AGENTS.md

~~56This code span will not be treated as an import: `@anthropic-ai/claude-code`~~

~~57```~~

58 110

~~59Imported files can recursively import additional files, with a max-depth of 5 hops. You can see what memory files are loaded by running `/memory` command.~~111Claude Code reads `CLAUDE.md`, not `AGENTS.md`. If your repository already uses `AGENTS.md` for other coding agents, create a `CLAUDE.md` that imports it so both tools read the same instructions without duplicating them. You can also add Claude-specific instructions below the import. Claude loads the imported file at session start, then appends the rest:

60 112

~~61## How Claude looks up memories~~113```markdown CLAUDE.md theme={null}

114@AGENTS.md

62 115

63Claude Code reads memories recursively: starting in the cwd, Claude Code recurses up to (but not including) the root directory */* and reads any CLAUDE.md or CLAUDE.local.md files it finds. This is especially convenient when working in large repositories where you run Claude Code in *foo/bar/*, and have memories in both *foo/CLAUDE.md* and *foo/bar/CLAUDE.md*.116## Claude Code

64 117

~~65Claude will also discover CLAUDE.md nested in subtrees under your current working directory. Instead of loading them at launch, they are only included when Claude reads files in those subtrees.~~118Use plan mode for changes under `src/billing/`.

119```

66 120

~~67### Load memory from additional directories~~121### How CLAUDE.md files load

68 122

~~69The `--add-dir` flag gives Claude access to additional directories outside your main working directory. By default, CLAUDE.md files from these directories are not loaded.~~123Claude Code reads CLAUDE.md files by walking up the directory tree from your current working directory, checking each directory along the way. This means if you run Claude Code in `foo/bar/`, it loads instructions from both `foo/bar/CLAUDE.md` and `foo/CLAUDE.md`.

70 124

~~71To also load memory files (CLAUDE.md, .claude/CLAUDE.md, and .claude/rules/\*.md) from additional directories, set the `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` environment variable:~~125Claude also discovers CLAUDE.md files in subdirectories under your current working directory. Instead of loading them at launch, they are included when Claude reads files in those subdirectories.

72 126

~~73```bash theme={null}~~127If you work in a large monorepo where other teams' CLAUDE.md files get picked up, use [`claudeMdExcludes`](#exclude-specific-claude-md-files) to skip them.

~~74CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config~~

~~75```~~

76 128

~~77## Directly edit memories with `/memory`~~129Block-level HTML comments (``) in CLAUDE.md files are stripped before the content is injected into Claude's context. Use them to leave notes for human maintainers without spending context tokens on them. Comments inside code blocks are preserved. When you open a CLAUDE.md file directly with the Read tool, comments remain visible.

78 130

~~79Use the `/memory` command during a session to open any memory file in your system editor for more extensive additions or organization.~~131#### Load from additional directories

80 132

~~81## Set up project memory~~133The `--add-dir` flag gives Claude access to additional directories outside your main working directory. By default, CLAUDE.md files from these directories are not loaded.

83Suppose you want to set up a CLAUDE.md file to store important project information, conventions, and frequently used commands. Project memory can be stored in either `./CLAUDE.md` or `./.claude/CLAUDE.md`.

84 134

~~85Bootstrap a CLAUDE.md for your codebase with the following command:~~135To also load CLAUDE.md files from additional directories, including `CLAUDE.md`, `.claude/CLAUDE.md`, and `.claude/rules/*.md`, set the `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` environment variable:

86 136

~~87```~~137```bash theme={null}

~~88> /init~~138CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config

89```139```

90 140

~~91<Tip>~~141### Organize rules with `.claude/rules/`

~~92 Tips:~~

93 142

~~94 * Include frequently used commands (build, test, lint) to avoid repeated searches~~143For larger projects, you can organize instructions into multiple files using the `.claude/rules/` directory. This keeps instructions modular and easier for teams to maintain. Rules can also be [scoped to specific file paths](#path-specific-rules), so they only load into context when Claude works with matching files, reducing noise and saving context space.

~~95 * Document code style preferences and naming conventions~~

~~96 * Add important architectural patterns specific to your project~~

~~97 * CLAUDE.md memories can be used for both instructions shared with your team and for your individual preferences.~~

~~98</Tip>~~

99 144

100## Modular rules with `.claude/rules/`145<Note>

~~101~~ 146 Rules load into context every session or when matching files are opened. For task-specific instructions that don't need to be in context all the time, use [skills](/en/skills) instead, which only load when you invoke them or when Claude determines they're relevant to your prompt.

102For larger projects, you can organize instructions into multiple files using the `.claude/rules/` directory. This allows teams to maintain focused, well-organized rule files instead of one large CLAUDE.md.147</Note>

103 148

104### Basic structure149#### Set up rules

105 150

106Place markdown files in your project's `.claude/rules/` directory:151Place markdown files in your project's `.claude/rules/` directory. Each file should cover one topic, with a descriptive filename like `testing.md` or `api-design.md`. All `.md` files are discovered recursively, so you can organize rules into subdirectories like `frontend/` or `backend/`:

107 152

108```153```text theme={null}

109your-project/154your-project/

110├── .claude/155├── .claude/

111│ ├── CLAUDE.md # Main project instructions156│ ├── CLAUDE.md # Main project instructions

115│ └── security.md # Security requirements160│ └── security.md # Security requirements

116```161```

117 162

118All `.md` files in `.claude/rules/` are automatically loaded as project memory, with the same priority as `.claude/CLAUDE.md`.163Rules without [`paths` frontmatter](#path-specific-rules) are loaded at launch with the same priority as `.claude/CLAUDE.md`.

119 164

120### Path-specific rules165#### Path-specific rules

121 166

122Rules can be scoped to specific files using YAML frontmatter with the `paths` field. These conditional rules only apply when Claude is working with files matching the specified patterns.167Rules can be scoped to specific files using YAML frontmatter with the `paths` field. These conditional rules only apply when Claude is working with files matching the specified patterns.

123 168

134- Include OpenAPI documentation comments179- Include OpenAPI documentation comments

135```180```

136 181

137Rules without a `paths` field are loaded unconditionally and apply to all files.182Rules without a `paths` field are loaded unconditionally and apply to all files. Path-scoped rules trigger when Claude reads files matching the pattern, not on every tool use.

138 183

139### Glob patterns184Use glob patterns in the `paths` field to match files by extension, directory, or any combination:

~~140~~

141The `paths` field supports standard glob patterns:

142 185

143| Pattern | Matches |186| Pattern | Matches |

144| ---------------------- | ---------------------------------------- |187| ---------------------- | ---------------------------------------- |

147| `*.md` | Markdown files in the project root |190| `*.md` | Markdown files in the project root |

148| `src/components/*.tsx` | React components in a specific directory |191| `src/components/*.tsx` | React components in a specific directory |

149 192

150You can specify multiple patterns:193You can specify multiple patterns and use brace expansion to match multiple extensions in one pattern:

151 194

152```markdown theme={null}195```markdown theme={null}

153---196---

154paths:197paths:

155 - "src/**/*.ts"198 - "src/**/*.{ts,tsx}"

156 - "lib/**/*.ts"199 - "lib/**/*.ts"

157 - "tests/**/*.test.ts"200 - "tests/**/*.test.ts"

158---201---

159```202```

160 203

161Brace expansion is supported for matching multiple extensions or directories:204#### Share rules across projects with symlinks

162 205

163```markdown theme={null}206The `.claude/rules/` directory supports symlinks, so you can maintain a shared set of rules and link them into multiple projects. Symlinks are resolved and loaded normally, and circular symlinks are detected and handled gracefully.

164paths:

165 - "src/**/*.{ts,tsx}"

166 - "{src,lib}/**/*.ts"

167 207

168# TypeScript/React Rules208This example links both a shared directory and an individual file:

169```

170 209

171This expands `src/**/*.{ts,tsx}` to match both `.ts` and `.tsx` files.210```bash theme={null}

211ln -s ~/shared-claude-rules .claude/rules/shared

212ln -s ~/company-standards/security.md .claude/rules/security.md

213```

172 214

173### Subdirectories215#### User-level rules

174 216

175Rules can be organized into subdirectories for better structure:217Personal rules in `~/.claude/rules/` apply to every project on your machine. Use them for preferences that aren't project-specific:

176 218

219```text theme={null}

220~/.claude/rules/

221├── preferences.md # Your personal coding preferences

222└── workflows.md # Your preferred workflows

177```223```

178.claude/rules/224

179├── frontend/225User-level rules are loaded before project rules, giving project rules higher priority.

180│ ├── react.md226

181│ └── styles.md227### Manage CLAUDE.md for large teams

182├── backend/228

183│ ├── api.md229For organizations deploying Claude Code across teams, you can centralize instructions and control which CLAUDE.md files are loaded.

184│ └── database.md230

185└── general.md231#### Deploy organization-wide CLAUDE.md

232

233Organizations can deploy a centrally managed CLAUDE.md that applies to all users on a machine. This file cannot be excluded by individual settings.

234

235<Steps>

236 <Step title="Create the file at the managed policy location">

237 * macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md`

238 * Linux and WSL: `/etc/claude-code/CLAUDE.md`

239 * Windows: `C:\Program Files\ClaudeCode\CLAUDE.md`

240 </Step>

241

242 <Step title="Deploy with your configuration management system">

243 Use MDM, Group Policy, Ansible, or similar tools to distribute the file across developer machines. See [managed settings](/en/permissions#managed-settings) for other organization-wide configuration options.

244 </Step>

245</Steps>

246

247A managed CLAUDE.md and [managed settings](/en/settings#settings-files) serve different purposes. Use settings for technical enforcement and CLAUDE.md for behavioral guidance:

248

249| Concern | Configure in |

250| :--------------------------------------------- | :-------------------------------------------------------- |

251| Block specific tools, commands, or file paths | Managed settings: `permissions.deny` |

252| Enforce sandbox isolation | Managed settings: `sandbox.enabled` |

253| Environment variables and API provider routing | Managed settings: `env` |

254| Authentication method and organization lock | Managed settings: `forceLoginMethod`, `forceLoginOrgUUID` |

255| Code style and quality guidelines | Managed CLAUDE.md |

256| Data handling and compliance reminders | Managed CLAUDE.md |

257| Behavioral instructions for Claude | Managed CLAUDE.md |

258

259Settings rules are enforced by the client regardless of what Claude decides to do. CLAUDE.md instructions shape Claude's behavior but are not a hard enforcement layer.

260

261#### Exclude specific CLAUDE.md files

262

263In large monorepos, ancestor CLAUDE.md files may contain instructions that aren't relevant to your work. The `claudeMdExcludes` setting lets you skip specific files by path or glob pattern.

264

265This example excludes a top-level CLAUDE.md and a rules directory from a parent folder. Add it to `.claude/settings.local.json` so the exclusion stays local to your machine:

266

267```json theme={null}

268{

269 "claudeMdExcludes": [

270 "**/monorepo/CLAUDE.md",

271 "/home/user/monorepo/other-team/.claude/rules/**"

272 ]

273}

186```274```

187 275

188All `.md` files are discovered recursively.276Patterns are matched against absolute file paths using glob syntax. You can configure `claudeMdExcludes` at any [settings layer](/en/settings#settings-files): user, project, local, or managed policy. Arrays merge across layers.

189 277

190### Symlinks278Managed policy CLAUDE.md files cannot be excluded. This ensures organization-wide instructions always apply regardless of individual settings.

191 279

192The `.claude/rules/` directory supports symlinks, allowing you to share common rules across multiple projects:280## Auto memory

193 281

194```bash theme={null}282Auto memory lets Claude accumulate knowledge across sessions without you writing anything. Claude saves notes for itself as it works: build commands, debugging insights, architecture notes, code style preferences, and workflow habits. Claude doesn't save something every session. It decides what's worth remembering based on whether the information would be useful in a future conversation.

195# Symlink a shared rules directory

196ln -s ~/shared-claude-rules .claude/rules/shared

197 283

198# Symlink individual rule files284<Note>

199ln -s ~/company-standards/security.md .claude/rules/security.md285 Auto memory requires Claude Code v2.1.59 or later. Check your version with `claude --version`.

286</Note>

287

288### Enable or disable auto memory

289

290Auto memory is on by default. To toggle it, open `/memory` in a session and use the auto memory toggle, or set `autoMemoryEnabled` in your project settings:

291

292```json theme={null}

293{

294 "autoMemoryEnabled": false

295}

200```296```

201 297

202Symlinks are resolved and their contents are loaded normally. Circular symlinks are detected and handled gracefully.298To disable auto memory via environment variable, set `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`.

299

300### Storage location

203 301

204### User-level rules302Each project gets its own memory directory at `~/.claude/projects/<project>/memory/`. The `<project>` path is derived from the git repository, so all worktrees and subdirectories within the same repo share one auto memory directory. Outside a git repo, the project root is used instead.

205 303

206You can create personal rules that apply to all your projects in `~/.claude/rules/`:304To store auto memory in a different location, set `autoMemoryDirectory` in your user or local settings:

207 305

306```json theme={null}

307{

308 "autoMemoryDirectory": "~/my-custom-memory-dir"

309}

208```310```

209~/.claude/rules/311

210├── preferences.md # Your personal coding preferences312This setting is accepted from policy, local, and user settings. It is not accepted from project settings (`.claude/settings.json`) to prevent a shared project from redirecting auto memory writes to sensitive locations.

211└── workflows.md # Your preferred workflows313

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

315

316```text theme={null}

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

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

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

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

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

212```322```

213 323

214User-level rules are loaded before project rules, giving project rules higher priority.324`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.

215 325

216<Tip>326Auto memory is machine-local. All worktrees and subdirectories within the same git repository share one auto memory directory. Files are not shared across machines or cloud environments.

217 Best practices for `.claude/rules/`:327

328### How it works

329

330The first 200 lines of `MEMORY.md`, or the first 25KB, whichever comes first, are loaded at the start of every conversation. Content beyond that threshold is not loaded at session start. Claude keeps `MEMORY.md` concise by moving detailed notes into separate topic files.

331

332This limit applies only to `MEMORY.md`. CLAUDE.md files are loaded in full regardless of length, though shorter files produce better adherence.

333

334Topic 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.

335

336Claude reads and writes memory files during your session. When you see "Writing memory" or "Recalled memory" in the Claude Code interface, Claude is actively updating or reading from `~/.claude/projects/<project>/memory/`.

337

338### Audit and edit your memory

218 339

219 * **Keep rules focused**: Each file should cover one topic (e.g., `testing.md`, `api-design.md`)340Auto memory files are plain markdown you can edit or delete at any time. Run [`/memory`](#view-and-edit-with-memory) to browse and open memory files from within a session.

220 * **Use descriptive filenames**: The filename should indicate what the rules cover341

221 * **Use conditional rules sparingly**: Only add `paths` frontmatter when rules truly apply to specific file types342## View and edit with `/memory`

222 * **Organize with subdirectories**: Group related rules (e.g., `frontend/`, `backend/`)343

344The `/memory` command lists all CLAUDE.md and rules files loaded in your current session, lets you toggle auto memory on or off, and provides a link to open the auto memory folder. Select any file to open it in your editor.

345

346When you ask Claude to remember something, like "always use pnpm, not npm" or "remember that the API tests require a local Redis instance," Claude saves it to auto memory. To add instructions to CLAUDE.md instead, ask Claude directly, like "add this to CLAUDE.md," or edit the file yourself via `/memory`.

347

348## Troubleshoot memory issues

349

350These are the most common issues with CLAUDE.md and auto memory, along with steps to debug them.

351

352### Claude isn't following my CLAUDE.md

353

354CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself. Claude reads it and tries to follow it, but there's no guarantee of strict compliance, especially for vague or conflicting instructions.

355

356To debug:

357

358* Run `/memory` to verify your CLAUDE.md files are being loaded. If a file isn't listed, Claude can't see it.

359* Check that the relevant CLAUDE.md is in a location that gets loaded for your session (see [Choose where to put CLAUDE.md files](#choose-where-to-put-claude-md-files)).

360* Make instructions more specific. "Use 2-space indentation" works better than "format code nicely."

361* Look for conflicting instructions across CLAUDE.md files. If two files give different guidance for the same behavior, Claude may pick one arbitrarily.

362

363For instructions you want at the system prompt level, use [`--append-system-prompt`](/en/cli-reference#system-prompt-flags). This must be passed every invocation, so it's better suited to scripts and automation than interactive use.

364

365<Tip>

366 Use the [`InstructionsLoaded` hook](/en/hooks#instructionsloaded) to log exactly which instruction files are loaded, when they load, and why. This is useful for debugging path-specific rules or lazy-loaded files in subdirectories.

223</Tip>367</Tip>

224 368

225## Organization-level memory management369### I don't know what auto memory saved

370

371Run `/memory` and select the auto memory folder to browse what Claude has saved. Everything is plain markdown you can read, edit, or delete.

372

373### My CLAUDE.md is too large

226 374

227Organizations can deploy centrally managed CLAUDE.md files that apply to all users.375Files over 200 lines consume more context and may reduce adherence. Move detailed content into separate files referenced with `@path` imports (see [Import additional files](#import-additional-files)), or split your instructions across `.claude/rules/` files.

228 376

229To set up organization-level memory management:377### Instructions seem lost after `/compact`

230 378

2311. Create the managed memory file at the **Managed policy** location shown in the [memory types table above](#determine-memory-type).379CLAUDE.md fully survives compaction. After `/compact`, Claude re-reads your CLAUDE.md from disk and re-injects it fresh into the session. If an instruction disappeared after compaction, it was given only in conversation, not written to CLAUDE.md. Add it to CLAUDE.md to make it persist across sessions.

232 380

2332. Deploy via your configuration management system (MDM, Group Policy, Ansible, etc.) to ensure consistent distribution across all developer machines.381See [Write effective instructions](#write-effective-instructions) for guidance on size, structure, and specificity.

234 382

235## Memory best practices383## Related resources

236 384

237* **Be specific**: "Use 2-space indentation" is better than "Format code properly".385* [Skills](/en/skills): package repeatable workflows that load on demand

238* **Use structure to organize**: Format each individual memory as a bullet point and group related memories under descriptive markdown headings.386* [Settings](/en/settings): configure Claude Code behavior with settings files

239* **Review periodically**: Update memories as your project evolves to ensure Claude is always using the most up to date information and context.387* [Manage sessions](/en/sessions): manage context, resume conversations, and run parallel sessions

388* [Subagent memory](/en/sub-agents#enable-persistent-memory): let subagents maintain their own auto memory

microsoft-foundry.md +18 −5

Details

14* RBAC permissions to create Microsoft Foundry resources and deployments14* RBAC permissions to create Microsoft Foundry resources and deployments

15* Azure CLI installed and configured (optional - only needed if you don't have another mechanism for getting credentials)15* Azure CLI installed and configured (optional - only needed if you don't have another mechanism for getting credentials)

16 16

17<Note>

18 If you are deploying Claude Code to multiple users, [pin your model versions](#4-pin-model-versions) to prevent breakage when Anthropic releases new models.

19</Note>

17## Setup21## Setup

18 22

19### 1. Provision Microsoft Foundry resource23### 1. Provision Microsoft Foundry resource

59 63

60### 3. Configure Claude Code64### 3. Configure Claude Code

61 65

62Set the following environment variables to enable Microsoft Foundry. Note that your deployments' names are set as the model identifiers in Claude Code (may be optional if using suggested deployment names).66Set the following environment variables to enable Microsoft Foundry:

63 67

64```bash theme={null}68```bash theme={null}

65# Enable Microsoft Foundry integration69# Enable Microsoft Foundry integration

69export ANTHROPIC_FOUNDRY_RESOURCE={resource}73export ANTHROPIC_FOUNDRY_RESOURCE={resource}

70# Or provide the full base URL:74# Or provide the full base URL:

71# export ANTHROPIC_FOUNDRY_BASE_URL=https://{resource}.services.ai.azure.com/anthropic75# export ANTHROPIC_FOUNDRY_BASE_URL=https://{resource}.services.ai.azure.com/anthropic

76```

72 77

~~73# Set models to your resource's deployment names~~78### 4. Pin model versions

~~74export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-5'~~79

80<Warning>

81 Pin specific model versions for every deployment. If you use model aliases (`sonnet`, `opus`, `haiku`) without pinning, Claude Code may attempt to use a newer model version that isn't available in your Foundry account, breaking existing users when Anthropic releases updates. When you create Azure deployments, select a specific model version rather than "auto-update to latest."

82</Warning>

84Set the model variables to match the deployment names you created in step 1:

86```bash theme={null}

87export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-6'

88export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-6'

75export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5'89export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5'

~~76export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-1'~~

77```90```

78 91

~~79For more details on model configuration options, see [Model configuration](/en/model-config).~~92For current and legacy model IDs, see [Models overview](https://platform.claude.com/docs/en/about-claude/models/overview). See [Model configuration](/en/model-config#pin-models-for-third-party-deployments) for the full list of environment variables.

80 93

81## Azure RBAC configuration94## Azure RBAC configuration

82 95

model-config.md +214 −19

Details

12 12

13* A **model alias**13* A **model alias**

14* A **model name**14* A **model name**

~~15 * Anthropic API: A full **[model name](https://docs.claude.com/en/docs/about-claude/models/overview#model-names)**~~15 * Anthropic API: A full **[model name](https://platform.claude.com/docs/en/about-claude/models/overview)**

16 * Bedrock: an inference profile ARN16 * Bedrock: an inference profile ARN

17 * Foundry: a deployment name17 * Foundry: a deployment name

18 * Vertex: a version name18 * Vertex: a version name

23remembering exact version numbers:23remembering exact version numbers:

24 24

25| Model alias | Behavior |25| Model alias | Behavior |

~~26| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |~~26| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

27| **`default`** | Recommended model setting, depending on your account type |27| **`default`** | Recommended model setting, depending on your account type |

30| **`haiku`** | Uses the fast and efficient Haiku model for simple tasks |30| **`haiku`** | Uses the fast and efficient Haiku model for simple tasks |

~~31| **`sonnet[1m]`** | Uses Sonnet with a [1 million token context window](https://docs.claude.com/en/docs/build-with-claude/context-windows#1m-token-context-window) window for long sessions |~~31| **`sonnet[1m]`** | Uses Sonnet with a [1 million token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window) for long sessions |

32| **`opus[1m]`** | Uses Opus with a [1 million token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window) for long sessions |

32| **`opusplan`** | Special mode that uses `opus` during plan mode, then switches to `sonnet` for execution |33| **`opusplan`** | Special mode that uses `opus` during plan mode, then switches to `sonnet` for execution |

33 34

35Aliases always point to the latest version. To pin to a specific version, use the full model name (for example, `claude-opus-4-6`) or set the corresponding environment variable like `ANTHROPIC_DEFAULT_OPUS_MODEL`.

34### Setting your model37### Setting your model

35 38

36You can configure your model in several ways, listed in order of priority:39You can configure your model in several ways, listed in order of priority:

53 56

54Example settings file:57Example settings file:

55 58

~~56```~~59```json theme={null}

57{60{

58 "permissions": {61 "permissions": {

59 ...62 ...

62}65}

63```66```

64 67

68## Restrict model selection

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

72When `availableModels` is set, users cannot switch to models not in the list via `/model`, `--model` flag, Config tool, or `ANTHROPIC_MODEL` environment variable.

74```json theme={null}

75{

76 "availableModels": ["sonnet", "haiku"]

77}

78```

80### Default model behavior

82The Default option in the model picker is not affected by `availableModels`. It always remains available and represents the system's runtime default [based on the user's subscription tier](#default-model-setting).

84Even with `availableModels: []`, users can still use Claude Code with the Default model for their tier.

86### Control the model users run on

88To fully control the model experience, use `availableModels` together with the `model` setting:

90* **availableModels**: restricts what users can switch to

91* **model**: sets the explicit model override, taking precedence over the Default

93This example ensures all users run Sonnet 4.6 and can only choose between Sonnet and Haiku:

95```json theme={null}

96{

97 "model": "sonnet",

98 "availableModels": ["sonnet", "haiku"]

99}

100```

101

102### Merge behavior

103

104When `availableModels` is set at multiple levels, such as user settings and project settings, arrays are merged and deduplicated. To enforce a strict allowlist, set `availableModels` in managed or policy settings which take highest priority.

105

65## Special model behavior106## Special model behavior

66 107

67### `default` model setting108### `default` model setting

68 109

~~69The behavior of `default` depends on your account type.~~110The behavior of `default` depends on your account type:

70 111

~~71For certain Max users, Claude Code will automatically fall back to Sonnet if you~~112* **Max and Team Premium**: defaults to Opus 4.6

~~72hit a usage threshold with Opus.~~113* **Pro and Team Standard**: defaults to Sonnet 4.6

114* **Enterprise**: Opus 4.6 is available but not the default

115

116Claude Code may automatically fall back to Sonnet if you hit a usage threshold with Opus.

73 117

74### `opusplan` model setting118### `opusplan` model setting

75 119

83This gives you the best of both worlds: Opus's superior reasoning for planning,127This gives you the best of both worlds: Opus's superior reasoning for planning,

84and Sonnet's efficiency for execution.128and Sonnet's efficiency for execution.

85 129

~~86### Extended context with \[1m]~~130### Adjust effort level

131

132[Effort levels](https://platform.claude.com/docs/en/build-with-claude/effort) control adaptive reasoning, which dynamically allocates thinking based on task complexity. Lower effort is faster and cheaper for straightforward tasks, while higher effort provides deeper reasoning for complex problems.

133

134Three levels persist across sessions: **low**, **medium**, and **high**. A fourth level, **max**, provides the deepest reasoning with no constraint on token spending, so responses are slower and cost more than at `high`. `max` is available on Opus 4.6 only and does not persist across sessions except through the `CLAUDE_CODE_EFFORT_LEVEL` environment variable.

135

136Opus 4.6 and Sonnet 4.6 default to medium effort. This applies to all providers, including Bedrock, Vertex AI, and direct API access.

137

138Medium is the recommended level for most coding tasks: it balances speed and reasoning depth, and higher levels can cause the model to overthink routine work. Reserve `high` or `max` for tasks that genuinely benefit from deeper reasoning, such as hard debugging problems or complex architectural decisions.

139

140For one-off deep reasoning without changing your session setting, include "ultrathink" in your prompt to trigger high effort for that turn.

141

142**Setting effort:**

143

144* **`/effort`**: run `/effort low`, `/effort medium`, `/effort high`, or `/effort max` to change the level, or `/effort auto` to reset to the model default

145* **In `/model`**: use left/right arrow keys to adjust the effort slider when selecting a model

146* **`--effort` flag**: pass `low`, `medium`, `high`, or `max` to set the level for a single session when launching Claude Code

147* **Environment variable**: set `CLAUDE_CODE_EFFORT_LEVEL` to `low`, `medium`, `high`, `max`, or `auto`

148* **Settings**: set `effortLevel` in your settings file to `"low"`, `"medium"`, or `"high"`

149* **Skill and subagent frontmatter**: set `effort` in a [skill](/en/skills#frontmatter-reference) or [subagent](/en/sub-agents#supported-frontmatter-fields) markdown file to override the effort level when that skill or subagent runs

150

151The environment variable takes precedence over all other methods, then your configured level, then the model default. Frontmatter effort applies when that skill or subagent is active, overriding the session level but not the environment variable.

152

153Effort is supported on Opus 4.6 and Sonnet 4.6. The effort slider appears in `/model` when a supported model is selected. The current effort level is also displayed next to the logo and spinner, for example "with low effort", so you can confirm which setting is active without opening `/model`.

154

155To disable adaptive reasoning on Opus 4.6 and Sonnet 4.6 and revert to the previous fixed thinking budget, set `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1`. When disabled, these models use the fixed budget controlled by `MAX_THINKING_TOKENS`. See [environment variables](/en/env-vars).

87 156

~~88For Console/API users, the `[1m]` suffix can be added to full model names to~~157### Extended context

~~89enable a~~158

~~90[1 million token context window](https://docs.claude.com/en/docs/build-with-claude/context-windows#1m-token-context-window).~~159Opus 4.6 and Sonnet 4.6 support a [1 million token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window) for long sessions with large codebases.

160

161Availability varies by model and plan. On Max, Team, and Enterprise plans, Opus is automatically upgraded to 1M context with no additional configuration. This applies to both Team Standard and Team Premium seats.

162

163| Plan | Opus 4.6 with 1M context | Sonnet 4.6 with 1M context |

164| ------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |

165| Max, Team, and Enterprise | Included with subscription | Requires [extra usage](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |

166| Pro | Requires [extra usage](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) | Requires [extra usage](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |

167| API and pay-as-you-go | Full access | Full access |

168

169To disable 1M context entirely, set `CLAUDE_CODE_DISABLE_1M_CONTEXT=1`. This removes 1M model variants from the model picker. See [environment variables](/en/env-vars).

170

171The 1M context window uses standard model pricing with no premium for tokens beyond 200K. For plans where extended context is included with your subscription, usage remains covered by your subscription. For plans that access extended context through extra usage, tokens are billed to extra usage.

172

173If your account supports 1M context, the option appears in the model picker (`/model`) in the latest versions of Claude Code. If you don't see it, try restarting your session.

174

175You can also use the `[1m]` suffix with model aliases or full model names:

91 176

92```bash theme={null}177```bash theme={null}

~~93# Example of using a full model name with the [1m] suffix~~178# Use the opus[1m] or sonnet[1m] alias

~~94/model anthropic.claude-sonnet-4-5-20250929-v1:0[1m]~~179/model opus[1m]

~~95```~~180/model sonnet[1m]

96 181

~~97Note: Extended context models have~~182# Or append [1m] to a full model name

~~98[different pricing](https://docs.claude.com/en/docs/about-claude/pricing#long-context-pricing).~~183/model claude-opus-4-6[1m]

184```

99 185

100## Checking your current model186## Checking your current model

101 187

1041. In [status line](/en/statusline) (if configured)1901. In [status line](/en/statusline) (if configured)

1052. In `/status`, which also displays your account information.1912. In `/status`, which also displays your account information.

106 192

193## Add a custom model option

194

195Use `ANTHROPIC_CUSTOM_MODEL_OPTION` to add a single custom entry to the `/model` picker without replacing the built-in aliases. This is useful for LLM gateway deployments or testing model IDs that Claude Code does not list by default.

196

197This example sets all three variables to make a gateway-routed Opus deployment selectable:

198

199```bash theme={null}

200export ANTHROPIC_CUSTOM_MODEL_OPTION="my-gateway/claude-opus-4-6"

201export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="Opus via Gateway"

202export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION="Custom deployment routed through the internal LLM gateway"

203```

204

205The custom entry appears at the bottom of the `/model` picker. `ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` and `ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION` are optional. If omitted, the model ID is used as the name and the description defaults to `Custom model (<model-id>)`.

206

207Claude Code skips validation for the model ID set in `ANTHROPIC_CUSTOM_MODEL_OPTION`, so you can use any string your API endpoint accepts.

208

107## Environment variables209## Environment variables

108 210

109You can use the following environment variables, which must be full **model211You can use the following environment variables, which must be full **model

119Note: `ANTHROPIC_SMALL_FAST_MODEL` is deprecated in favor of221Note: `ANTHROPIC_SMALL_FAST_MODEL` is deprecated in favor of

120`ANTHROPIC_DEFAULT_HAIKU_MODEL`.222`ANTHROPIC_DEFAULT_HAIKU_MODEL`.

121 223

224### Pin models for third-party deployments

225

226When deploying Claude Code through [Bedrock](/en/amazon-bedrock), [Vertex AI](/en/google-vertex-ai), or [Foundry](/en/microsoft-foundry), pin model versions before rolling out to users.

227

228Without pinning, Claude Code uses model aliases (`sonnet`, `opus`, `haiku`) that resolve to the latest version. When Anthropic releases a new model, users whose accounts don't have the new version enabled will break silently.

229

230<Warning>

231 Set all three model environment variables to specific version IDs as part of your initial setup. Skipping this step means a Claude Code update can break your users without any action on your part.

232</Warning>

233

234Use the following environment variables with version-specific model IDs for your provider:

235

236| Provider | Example |

237| :-------- | :---------------------------------------------------------------------- |

238| Bedrock | `export ANTHROPIC_DEFAULT_OPUS_MODEL='us.anthropic.claude-opus-4-6-v1'` |

239| Vertex AI | `export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-6'` |

240| Foundry | `export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-6'` |

241

242Apply the same pattern for `ANTHROPIC_DEFAULT_SONNET_MODEL` and `ANTHROPIC_DEFAULT_HAIKU_MODEL`. For current and legacy model IDs across all providers, see [Models overview](https://platform.claude.com/docs/en/about-claude/models/overview). To upgrade users to a new model version, update these environment variables and redeploy.

243

244To enable [extended context](#extended-context) for a pinned model, append `[1m]` to the model ID in `ANTHROPIC_DEFAULT_OPUS_MODEL` or `ANTHROPIC_DEFAULT_SONNET_MODEL`:

245

246```bash theme={null}

247export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-6[1m]'

248```

249

250The `[1m]` suffix applies the 1M context window to all usage of that alias, including `opusplan`. Claude Code strips the suffix before sending the model ID to your provider. Only append `[1m]` when the underlying model supports 1M context, such as Opus 4.6 or Sonnet 4.6.

251

252<Note>

253 The `settings.availableModels` allowlist still applies when using third-party providers. Filtering matches on the model alias (`opus`, `sonnet`, `haiku`), not the provider-specific model ID.

254</Note>

255

256### Customize pinned model display and capabilities

257

258When you pin a model on a third-party provider, the provider-specific ID appears as-is in the `/model` picker and Claude Code may not recognize which features the model supports. You can override the display name and declare capabilities with companion environment variables for each pinned model.

259

260These variables only take effect on third-party providers such as Bedrock, Vertex AI, and Foundry. They have no effect when using the Anthropic API directly.

261

262| Environment variable | Description |

263| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |

264| `ANTHROPIC_DEFAULT_OPUS_MODEL_NAME` | Display name for the pinned Opus model in the `/model` picker. Defaults to the model ID when not set |

265| `ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION` | Display description for the pinned Opus model in the `/model` picker. Defaults to `Custom Opus model` when not set |

266| `ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES` | Comma-separated list of capabilities the pinned Opus model supports |

267

268The same `_NAME`, `_DESCRIPTION`, and `_SUPPORTED_CAPABILITIES` suffixes are available for `ANTHROPIC_DEFAULT_SONNET_MODEL` and `ANTHROPIC_DEFAULT_HAIKU_MODEL`.

269

270Claude Code enables features like [effort levels](#adjust-effort-level) and [extended thinking](/en/common-workflows#use-extended-thinking-thinking-mode) by matching the model ID against known patterns. Provider-specific IDs such as Bedrock ARNs or custom deployment names often don't match these patterns, leaving supported features disabled. Set `_SUPPORTED_CAPABILITIES` to tell Claude Code which features the model actually supports:

271

272| Capability value | Enables |

273| ---------------------- | ------------------------------------------------------------------------------- |

274| `effort` | [Effort levels](#adjust-effort-level) and the `/effort` command |

275| `max_effort` | The `max` effort level |

276| `thinking` | [Extended thinking](/en/common-workflows#use-extended-thinking-thinking-mode) |

277| `adaptive_thinking` | Adaptive reasoning that dynamically allocates thinking based on task complexity |

278| `interleaved_thinking` | Thinking between tool calls |

279

280When `_SUPPORTED_CAPABILITIES` is set, listed capabilities are enabled and unlisted capabilities are disabled for the matching pinned model. When the variable is unset, Claude Code falls back to built-in detection based on the model ID.

281

282This example pins Opus to a Bedrock custom model ARN, sets a friendly name, and declares its capabilities:

283

284```bash theme={null}

285export ANTHROPIC_DEFAULT_OPUS_MODEL='arn:aws:bedrock:us-east-1:123456789012:custom-model/abc'

286export ANTHROPIC_DEFAULT_OPUS_MODEL_NAME='Opus via Bedrock'

287export ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION='Opus 4.6 routed through a Bedrock custom endpoint'

288export ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES='effort,max_effort,thinking,adaptive_thinking,interleaved_thinking'

289```

290

291### Override model IDs per version

292

293The family-level environment variables above configure one model ID per family alias. If you need to map several versions within the same family to distinct provider IDs, use the `modelOverrides` setting instead.

294

295`modelOverrides` maps individual Anthropic model IDs to the provider-specific strings that Claude Code sends to your provider's API. When a user selects a mapped model in the `/model` picker, Claude Code uses your configured value instead of the built-in default.

296

297This lets enterprise administrators route each model version to a specific Bedrock inference profile ARN, Vertex AI version name, or Foundry deployment name for governance, cost allocation, or regional routing.

298

299Set `modelOverrides` in your [settings file](/en/settings#settings-files):

300

301```json theme={null}

302{

303 "modelOverrides": {

304 "claude-opus-4-6": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-prod",

305 "claude-opus-4-5-20251101": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-45-prod",

306 "claude-sonnet-4-6": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/sonnet-prod"

307 }

308}

309```

310

311Keys must be Anthropic model IDs as listed in the [Models overview](https://platform.claude.com/docs/en/about-claude/models/overview). For dated model IDs, include the date suffix exactly as it appears there. Unknown keys are ignored.

312

313Overrides replace the built-in model IDs that back each entry in the `/model` picker. On Bedrock, overrides take precedence over any inference profiles that Claude Code discovers automatically at startup. Values you supply directly through `ANTHROPIC_MODEL`, `--model`, or the `ANTHROPIC_DEFAULT_*_MODEL` environment variables are passed to the provider as-is and are not transformed by `modelOverrides`.

314

315`modelOverrides` works alongside `availableModels`. The allowlist is evaluated against the Anthropic model ID, not the override value, so an entry like `"opus"` in `availableModels` continues to match even when Opus versions are mapped to ARNs.

316

122### Prompt caching configuration317### Prompt caching configuration

123 318

124Claude Code automatically uses [prompt caching](https://docs.claude.com/en/docs/build-with-claude/prompt-caching) to optimize performance and reduce costs. You can disable prompt caching globally or for specific model tiers:319Claude Code automatically uses [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) to optimize performance and reduce costs. You can disable prompt caching globally or for specific model tiers:

125 320

126| Environment variable | Description |321| Environment variable | Description |

127| ------------------------------- | ---------------------------------------------------------------------------------------------- |322| ------------------------------- | ---------------------------------------------------------------------------------------------- |

monitoring-usage.md +85 −43

Details

6 6

7> Learn how to enable and configure OpenTelemetry for Claude Code.7> Learn how to enable and configure OpenTelemetry for Claude Code.

8 8

~~9Claude Code supports OpenTelemetry (OTel) metrics and events for monitoring and observability.~~9Track Claude Code usage, costs, and tool activity across your organization by exporting telemetry data through OpenTelemetry (OTel). Claude Code exports metrics as time series data via the standard metrics protocol, and events via the logs/events protocol. Configure your metrics and logs backends to match your monitoring requirements.

11All metrics are time series data exported via OpenTelemetry's standard metrics protocol, and events are exported via OpenTelemetry's logs/events protocol. It is the user's responsibility to ensure their metrics and logs backends are properly configured and that the aggregation granularity meets their monitoring requirements.

12 10

13## Quick start11## Quick start

14 12

19export CLAUDE_CODE_ENABLE_TELEMETRY=117export CLAUDE_CODE_ENABLE_TELEMETRY=1

20 18

21# 2. Choose exporters (both are optional - configure only what you need)19# 2. Choose exporters (both are optional - configure only what you need)

~~22export OTEL_METRICS_EXPORTER=otlp # Options: otlp, prometheus, console~~20export OTEL_METRICS_EXPORTER=otlp # Options: otlp, prometheus, console, none

~~23export OTEL_LOGS_EXPORTER=otlp # Options: otlp, console~~21export OTEL_LOGS_EXPORTER=otlp # Options: otlp, console, none

24 22

25# 3. Configure OTLP endpoint (for OTLP exporter)23# 3. Configure OTLP endpoint (for OTLP exporter)

26export OTEL_EXPORTER_OTLP_PROTOCOL=grpc24export OTEL_EXPORTER_OTLP_PROTOCOL=grpc

56 "OTEL_METRICS_EXPORTER": "otlp",54 "OTEL_METRICS_EXPORTER": "otlp",

57 "OTEL_LOGS_EXPORTER": "otlp",55 "OTEL_LOGS_EXPORTER": "otlp",

58 "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",56 "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",

~~59 "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.company.com:4317",~~57 "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4317",

~~60 "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer company-token"~~58 "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer example-token"

61 }59 }

62}60}

63```61```

71### Common configuration variables69### Common configuration variables

72 70

~~74| ----------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------ |~~72| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |

75| `CLAUDE_CODE_ENABLE_TELEMETRY` | Enables telemetry collection (required) | `1` |73| `CLAUDE_CODE_ENABLE_TELEMETRY` | Enables telemetry collection (required) | `1` |

87| `OTEL_METRIC_EXPORT_INTERVAL` | Export interval in milliseconds (default: 60000) | `5000`, `60000` |85| `OTEL_METRIC_EXPORT_INTERVAL` | Export interval in milliseconds (default: 60000) | `5000`, `60000` |

88| `OTEL_LOGS_EXPORT_INTERVAL` | Logs export interval in milliseconds (default: 5000) | `1000`, `10000` |86| `OTEL_LOGS_EXPORT_INTERVAL` | Logs export interval in milliseconds (default: 5000) | `1000`, `10000` |

88| `OTEL_LOG_TOOL_DETAILS` | Enable logging of tool parameters and input arguments in tool events: Bash commands, MCP server and tool names, skill names, and tool input (default: disabled) | `1` to enable |

89| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` | Metrics temporality preference (default: `delta`). Set to `cumulative` if your backend expects cumulative temporality | `delta`, `cumulative` |

90| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | Interval for refreshing dynamic headers (default: 1740000ms / 29 minutes) | `900000` |90| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | Interval for refreshing dynamic headers (default: 1740000ms / 29 minutes) | `900000` |

91 91

92### Metrics cardinality control92### Metrics cardinality control

94The following environment variables control which attributes are included in metrics to manage cardinality:94The following environment variables control which attributes are included in metrics to manage cardinality:

95 95

~~97| ----------------------------------- | ----------------------------------------------- | ------------- | ------------------ |~~97| ----------------------------------- | --------------------------------------------------------------------- | ------------- | ------------------ |

101 101

102These variables help control the cardinality of metrics, which affects storage requirements and query performance in your metrics backend. Lower cardinality generally means better performance and lower storage costs but less granular data for analysis.102These variables help control the cardinality of metrics, which affects storage requirements and query performance in your metrics backend. Lower cardinality generally means better performance and lower storage costs but less granular data for analysis.

103 103

148<Warning>148<Warning>

149 **Important formatting requirements for OTEL\_RESOURCE\_ATTRIBUTES:**149 **Important formatting requirements for OTEL\_RESOURCE\_ATTRIBUTES:**

150 150

151 The `OTEL_RESOURCE_ATTRIBUTES` environment variable follows the [W3C Baggage specification](https://www.w3.org/TR/baggage/), which has strict formatting requirements:151 The `OTEL_RESOURCE_ATTRIBUTES` environment variable uses comma-separated key=value pairs with strict formatting requirements:

152 152

153 * **No spaces allowed**: Values cannot contain spaces. For example, `user.organizationName=My Company` is invalid153 * **No spaces allowed**: Values cannot contain spaces. For example, `user.organizationName=My Company` is invalid

154 * **Format**: Must be comma-separated key=value pairs: `key1=value1,key2=value2`154 * **Format**: Must be comma-separated key=value pairs: `key1=value1,key2=value2`

174 174

175### Example configurations175### Example configurations

176 176

177Set these environment variables before running `claude`. Each block shows a complete configuration for a different exporter or deployment scenario:

178

177```bash theme={null}179```bash theme={null}

178# Console debugging (1-second intervals)180# Console debugging (1-second intervals)

179export CLAUDE_CODE_ENABLE_TELEMETRY=1181export CLAUDE_CODE_ENABLE_TELEMETRY=1

200export OTEL_METRICS_EXPORTER=otlp202export OTEL_METRICS_EXPORTER=otlp

201export OTEL_LOGS_EXPORTER=otlp203export OTEL_LOGS_EXPORTER=otlp

202export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf204export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf

203export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://metrics.company.com:4318205export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://metrics.example.com:4318

204export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc206export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc

205export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.company.com:4317207export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.com:4317

206 208

207# Metrics only (no events/logs)209# Metrics only (no events/logs)

208export CLAUDE_CODE_ENABLE_TELEMETRY=1210export CLAUDE_CODE_ENABLE_TELEMETRY=1

224All metrics and events share these standard attributes:226All metrics and events share these standard attributes:

225 227

227| ------------------- | -------------------------------------------------------------------- | --------------------------------------------------- |229| ------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |

235| `user.id` | Anonymous device/installation identifier, generated per Claude Code installation | Always included |

236| `user.email` | User email address (when authenticated via OAuth) | Always included when available |

237| `terminal.type` | Terminal type, such as `iTerm.app`, `vscode`, `cursor`, or `tmux` | Always included when detected |

238

239Events additionally include the following attributes. These are never attached to metrics because they would cause unbounded cardinality:

240

241* `prompt.id`: UUID correlating a user prompt with all subsequent events until the next prompt. See [Event correlation attributes](#event-correlation-attributes).

242* `workspace.host_paths`: host workspace directories selected in the desktop app, as a string array

233 243

234### Metrics244### Metrics

235 245

248 258

249### Metric details259### Metric details

250 260

261Each metric includes the standard attributes listed above. Metrics with additional context-specific attributes are noted below.

262

251#### Session counter263#### Session counter

252 264

253Incremented at the start of each session.265Incremented at the start of each session.

288**Attributes**:300**Attributes**:

289 301

290* All [standard attributes](#standard-attributes)302* All [standard attributes](#standard-attributes)

291* `model`: Model identifier (for example, "claude-sonnet-4-5-20250929")303* `model`: Model identifier (for example, "claude-sonnet-4-6")

292 304

293#### Token counter305#### Token counter

294 306

298 310

299* All [standard attributes](#standard-attributes)311* All [standard attributes](#standard-attributes)

300* `type`: (`"input"`, `"output"`, `"cacheRead"`, `"cacheCreation"`)312* `type`: (`"input"`, `"output"`, `"cacheRead"`, `"cacheCreation"`)

301* `model`: Model identifier (for example, "claude-sonnet-4-5-20250929")313* `model`: Model identifier (for example, "claude-sonnet-4-6")

302 314

303#### Code edit tool decision counter315#### Code edit tool decision counter

304 316

307**Attributes**:319**Attributes**:

308 320

309* All [standard attributes](#standard-attributes)321* All [standard attributes](#standard-attributes)

310* `tool`: Tool name (`"Edit"`, `"Write"`, `"NotebookEdit"`)322* `tool_name`: Tool name (`"Edit"`, `"Write"`, `"NotebookEdit"`)

311* `decision`: User decision (`"accept"`, `"reject"`)323* `decision`: User decision (`"accept"`, `"reject"`)

312* `language`: Programming language of the edited file (for example, `"TypeScript"`, `"Python"`, `"JavaScript"`, `"Markdown"`). Returns `"unknown"` for unrecognized file extensions.324* `source`: Decision source - `"config"`, `"hook"`, `"user_permanent"`, `"user_temporary"`, `"user_abort"`, or `"user_reject"`

325* `language`: Programming language of the edited file, such as `"TypeScript"`, `"Python"`, `"JavaScript"`, or `"Markdown"`. Returns `"unknown"` for unrecognized file extensions.

313 326

314#### Active time counter327#### Active time counter

315 328

316Tracks actual time spent actively using Claude Code (not idle time). This metric is incremented during user interactions such as typing prompts or receiving responses.329Tracks actual time spent actively using Claude Code, excluding idle time. This metric is incremented during user interactions (typing, reading responses) and during CLI processing (tool execution, AI response generation).

317 330

318**Attributes**:331**Attributes**:

319 332

320* All [standard attributes](#standard-attributes)333* All [standard attributes](#standard-attributes)

334* `type`: `"user"` for keyboard interactions, `"cli"` for tool execution and AI responses

321 335

322### Events336### Events

323 337

324Claude Code exports the following events via OpenTelemetry logs/events (when `OTEL_LOGS_EXPORTER` is configured):338Claude Code exports the following events via OpenTelemetry logs/events (when `OTEL_LOGS_EXPORTER` is configured):

325 339

340#### Event correlation attributes

341

342When a user submits a prompt, Claude Code may make multiple API calls and run several tools. The `prompt.id` attribute lets you tie all of those events back to the single prompt that triggered them.

343

344| Attribute | Description |

345| ----------- | ------------------------------------------------------------------------------------ |

346| `prompt.id` | UUID v4 identifier linking all events produced while processing a single user prompt |

347

348To trace all activity triggered by a single prompt, filter your events by a specific `prompt.id` value. This returns the user\_prompt event, any api\_request events, and any tool\_result events that occurred while processing that prompt.

349

350<Note>

351 `prompt.id` is intentionally excluded from metrics because each prompt generates a unique ID, which would create an ever-growing number of time series. Use it for event-level analysis and audit trails only.

352</Note>

353

326#### User prompt event354#### User prompt event

327 355

328Logged when a user submits a prompt.356Logged when a user submits a prompt.

334* All [standard attributes](#standard-attributes)362* All [standard attributes](#standard-attributes)

335* `event.name`: `"user_prompt"`363* `event.name`: `"user_prompt"`

336* `event.timestamp`: ISO 8601 timestamp364* `event.timestamp`: ISO 8601 timestamp

365* `event.sequence`: monotonically increasing counter for ordering events within a session

337* `prompt_length`: Length of the prompt366* `prompt_length`: Length of the prompt

338* `prompt`: Prompt content (redacted by default, enable with `OTEL_LOG_USER_PROMPTS=1`)367* `prompt`: Prompt content (redacted by default, enable with `OTEL_LOG_USER_PROMPTS=1`)

339 368

348* All [standard attributes](#standard-attributes)377* All [standard attributes](#standard-attributes)

349* `event.name`: `"tool_result"`378* `event.name`: `"tool_result"`

350* `event.timestamp`: ISO 8601 timestamp379* `event.timestamp`: ISO 8601 timestamp

380* `event.sequence`: monotonically increasing counter for ordering events within a session

351* `tool_name`: Name of the tool381* `tool_name`: Name of the tool

352* `success`: `"true"` or `"false"`382* `success`: `"true"` or `"false"`

353* `duration_ms`: Execution time in milliseconds383* `duration_ms`: Execution time in milliseconds

354* `error`: Error message (if failed)384* `error`: Error message (if failed)

355* `decision`: Either `"accept"` or `"reject"`385* `decision_type`: Either `"accept"` or `"reject"`

356* `source`: Decision source - `"config"`, `"user_permanent"`, `"user_temporary"`, `"user_abort"`, or `"user_reject"`386* `decision_source`: Decision source - `"config"`, `"hook"`, `"user_permanent"`, `"user_temporary"`, `"user_abort"`, or `"user_reject"`

357* `tool_parameters`: JSON string containing tool-specific parameters (when available)387* `tool_result_size_bytes`: Size of the tool result in bytes

358 * For Bash tool: includes `bash_command`, `full_command`, `timeout`, `description`, `sandbox`388* `mcp_server_scope`: MCP server scope identifier (for MCP tools)

389* `tool_parameters` (when `OTEL_LOG_TOOL_DETAILS=1`): JSON string containing tool-specific parameters:

390 * For Bash tool: includes `bash_command`, `full_command`, `timeout`, `description`, `dangerouslyDisableSandbox`, and `git_commit_id` (the commit SHA, when a `git commit` command succeeds)

391 * For MCP tools: includes `mcp_server_name`, `mcp_tool_name`

392 * For Skill tool: includes `skill_name`

393* `tool_input` (when `OTEL_LOG_TOOL_DETAILS=1`): JSON-serialized tool arguments. Individual values over 512 characters are truncated, and the full payload is bounded to \~4 K characters. Applies to all tools including MCP tools.

359 394

360#### API request event395#### API request event

361 396

368* All [standard attributes](#standard-attributes)403* All [standard attributes](#standard-attributes)

369* `event.name`: `"api_request"`404* `event.name`: `"api_request"`

370* `event.timestamp`: ISO 8601 timestamp405* `event.timestamp`: ISO 8601 timestamp

371* `model`: Model used (for example, "claude-sonnet-4-5-20250929")406* `event.sequence`: monotonically increasing counter for ordering events within a session

407* `model`: Model used (for example, "claude-sonnet-4-6")

372* `cost_usd`: Estimated cost in USD408* `cost_usd`: Estimated cost in USD

373* `duration_ms`: Request duration in milliseconds409* `duration_ms`: Request duration in milliseconds

374* `input_tokens`: Number of input tokens410* `input_tokens`: Number of input tokens

375* `output_tokens`: Number of output tokens411* `output_tokens`: Number of output tokens

376* `cache_read_tokens`: Number of tokens read from cache412* `cache_read_tokens`: Number of tokens read from cache

377* `cache_creation_tokens`: Number of tokens used for cache creation413* `cache_creation_tokens`: Number of tokens used for cache creation

414* `speed`: `"fast"` or `"normal"`, indicating whether fast mode was active

378 415

379#### API error event416#### API error event

380 417

387* All [standard attributes](#standard-attributes)424* All [standard attributes](#standard-attributes)

388* `event.name`: `"api_error"`425* `event.name`: `"api_error"`

389* `event.timestamp`: ISO 8601 timestamp426* `event.timestamp`: ISO 8601 timestamp

390* `model`: Model used (for example, "claude-sonnet-4-5-20250929")427* `event.sequence`: monotonically increasing counter for ordering events within a session

428* `model`: Model used (for example, "claude-sonnet-4-6")

391* `error`: Error message429* `error`: Error message

392* `status_code`: HTTP status code (if applicable)430* `status_code`: HTTP status code as a string, or `"undefined"` for non-HTTP errors

393* `duration_ms`: Request duration in milliseconds431* `duration_ms`: Request duration in milliseconds

394* `attempt`: Attempt number (for retried requests)432* `attempt`: Attempt number (for retried requests)

433* `speed`: `"fast"` or `"normal"`, indicating whether fast mode was active

395 434

396#### Tool decision event435#### Tool decision event

397 436

404* All [standard attributes](#standard-attributes)443* All [standard attributes](#standard-attributes)

405* `event.name`: `"tool_decision"`444* `event.name`: `"tool_decision"`

406* `event.timestamp`: ISO 8601 timestamp445* `event.timestamp`: ISO 8601 timestamp

446* `event.sequence`: monotonically increasing counter for ordering events within a session

407* `tool_name`: Name of the tool (for example, "Read", "Edit", "Write", "NotebookEdit")447* `tool_name`: Name of the tool (for example, "Read", "Edit", "Write", "NotebookEdit")

408* `decision`: Either `"accept"` or `"reject"`448* `decision`: Either `"accept"` or `"reject"`

409* `source`: Decision source - `"config"`, `"user_permanent"`, `"user_temporary"`, `"user_abort"`, or `"user_reject"`449* `source`: Decision source - `"config"`, `"hook"`, `"user_permanent"`, `"user_temporary"`, `"user_abort"`, or `"user_reject"`

410 450

411## Interpreting metrics and events data451## Interpret metrics and events data

412 452

413The metrics exported by Claude Code provide valuable insights into usage patterns and productivity. Here are some common visualizations and analyses you can create:453The exported metrics and events support a range of analyses:

414 454

415### Usage monitoring455### Usage monitoring

416 456

440* Unusual token consumption480* Unusual token consumption

441* High session volume from specific users481* High session volume from specific users

442 482

443All metrics can be segmented by `user.account_uuid`, `organization.id`, `session.id`, `model`, and `app.version`.483All metrics can be segmented by `user.account_uuid`, `user.account_id`, `organization.id`, `session.id`, `model`, and `app.version`.

444 484

445### Event analysis485### Event analysis

446 486

489 529

490For a comprehensive guide on measuring return on investment for Claude Code, including telemetry setup, cost analysis, productivity metrics, and automated reporting, see the [Claude Code ROI Measurement Guide](https://github.com/anthropics/claude-code-monitoring-guide). This repository provides ready-to-use Docker Compose configurations, Prometheus and OpenTelemetry setups, and templates for generating productivity reports integrated with tools like Linear.530For a comprehensive guide on measuring return on investment for Claude Code, including telemetry setup, cost analysis, productivity metrics, and automated reporting, see the [Claude Code ROI Measurement Guide](https://github.com/anthropics/claude-code-monitoring-guide). This repository provides ready-to-use Docker Compose configurations, Prometheus and OpenTelemetry setups, and templates for generating productivity reports integrated with tools like Linear.

491 531

492## Security/privacy considerations532## Security and privacy

493 533

494* Telemetry is opt-in and requires explicit configuration534* Telemetry is opt-in and requires explicit configuration

495* Sensitive information like API keys or file contents are never included in metrics or events535* Raw file contents and code snippets are not included in metrics or events

496* User prompt content is redacted by default - only prompt length is recorded. To enable user prompt logging, set `OTEL_LOG_USER_PROMPTS=1`536* When authenticated via OAuth, `user.email` is included in telemetry attributes. If this is a concern for your organization, work with your telemetry backend to filter or redact this field

537* User prompt content is not collected by default. Only prompt length is recorded. To include prompt content, set `OTEL_LOG_USER_PROMPTS=1`

538* Tool input arguments and parameters are not logged by default. To include them, set `OTEL_LOG_TOOL_DETAILS=1`. When enabled, `tool_result` events include a `tool_parameters` attribute with Bash commands, MCP server and tool names, and skill names, plus a `tool_input` attribute with file paths, URLs, search patterns, and other arguments. Individual values over 512 characters are truncated and the total is bounded to \~4 K characters, but the arguments may still contain sensitive values. Configure your telemetry backend to filter or redact these attributes as needed

497 539

498## Monitoring Claude Code on Amazon Bedrock540## Monitor Claude Code on Amazon Bedrock

499 541

500For detailed Claude Code usage monitoring guidance for Amazon Bedrock, see [Claude Code Monitoring Implementation (Bedrock)](https://github.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock/blob/main/assets/docs/MONITORING.md).542For detailed Claude Code usage monitoring guidance for Amazon Bedrock, see [Claude Code Monitoring Implementation (Bedrock)](https://github.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock/blob/main/assets/docs/MONITORING.md).

network-config.md +11 −5

Details

80 80

81Claude Code requires access to the following URLs:81Claude Code requires access to the following URLs:

82 82

~~83* `api.anthropic.com` - Claude API endpoints~~83* `api.anthropic.com`: Claude API endpoints

~~84* `claude.ai` - WebFetch safeguards~~84* `claude.ai`: authentication for claude.ai accounts

~~85* `statsig.anthropic.com` - Telemetry and metrics~~85* `platform.claude.com`: authentication for Anthropic Console accounts

~~86* `sentry.io` - Error reporting~~

87 86

88Ensure these URLs are allowlisted in your proxy configuration and firewall rules. This is especially important when using Claude Code in containerized or restricted network environments.87Ensure these URLs are allowlisted in your proxy configuration and firewall rules. This is especially important when using Claude Code in containerized or restricted network environments.

89 88

89The native installer and update checks also require the following URLs. If you install Claude Code through npm or manage your own binary distribution, end users may not need access:

91* `downloads.claude.ai`: CDN hosting the install script, version pointers, manifests, and executables

92* `storage.googleapis.com`: legacy download bucket, deprecation in progress

94[Claude Code on the web](/en/claude-code-on-the-web) and [Code Review](/en/code-review) connect to your repositories from Anthropic-managed infrastructure. If your GitHub Enterprise Cloud organization restricts access by IP address, enable [IP allow list inheritance for installed GitHub Apps](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization#allowing-access-by-github-apps). The Claude GitHub App registers its IP ranges, so enabling this setting allows access without manual configuration. To [add the ranges to your allow list manually](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization#adding-an-allowed-ip-address) instead, or to configure other firewalls, see the [Anthropic API IP addresses](https://platform.claude.com/docs/en/api/ip-addresses).

90## Additional resources96## Additional resources

91 97

92* [Claude Code settings](/en/settings)98* [Claude Code settings](/en/settings)

~~93* [Environment variables reference](/en/settings#environment-variables)~~99* [Environment variables reference](/en/env-vars)

94* [Troubleshooting guide](/en/troubleshooting)100* [Troubleshooting guide](/en/troubleshooting)

output-styles.md +16 −11

Details

42 42

43## Change your output style43## Change your output style

44 44

~~45You can either:~~45Run `/config` and select **Output style** to pick a style from a menu. Your

46selection is saved to `.claude/settings.local.json` at the

47[local project level](/en/settings).

46 48

~~47* Run `/output-style` to access a menu and select your output style (this can~~49To set a style without the menu, edit the `outputStyle` field directly in a

~~48 also be accessed from the `/config` menu)~~50settings file:

49 51

~~50* Run `/output-style [style]`, such as `/output-style explanatory`, to directly~~52```json theme={null}

~~51 switch to a style~~53{

54 "outputStyle": "Explanatory"

55}

56```

52 57

~~53These changes apply to the [local project level](/en/settings) and are saved in~~58Because the output style is set in the system prompt at session start,

~~54`.claude/settings.local.json`. You can also directly edit the `outputStyle`~~59changes take effect the next time you start a new session. This keeps the system

~~55field in a settings file at a different level.~~60prompt stable throughout a conversation so prompt caching can reduce latency and

61cost.

56 62

57## Create a custom output style63## Create a custom output style

58 64

81 87

82### Frontmatter88### Frontmatter

83 89

~~84Output style files support frontmatter, useful for specifying metadata about the~~90Output style files support frontmatter for specifying metadata:

~~85command:~~

86 91

88| :------------------------- | :-------------------------------------------------------------------------- | :---------------------- |93| :------------------------- | :-------------------------------------------------------------------------- | :---------------------- |

92 97

93## Comparisons to related features98## Comparisons to related features

overview.md +155 −80

Details

4 4

5# Claude Code overview5# Claude Code overview

6 6

~~7> Learn about Claude Code, Anthropic's agentic coding tool that lives in your terminal and helps you turn ideas into code faster than ever before.~~7> Claude Code is an agentic coding tool that reads your codebase, edits files, runs commands, and integrates with your development tools. Available in your terminal, IDE, desktop app, and browser.

8 8

~~9## Get started in 30 seconds~~9Claude Code is an AI-powered coding assistant that helps you build features, fix bugs, and automate development tasks. It understands your entire codebase and can work across multiple files and tools to get things done.

10 10

~~11Prerequisites:~~11## Get started

12 12

~~13* A [Claude subscription](https://claude.com/pricing) (Pro, Max, Teams, or Enterprise) or [Claude Console](https://console.anthropic.com/) account~~13Choose your environment to get started. Most surfaces require a [Claude subscription](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=overview_pricing) or [Anthropic Console](https://console.anthropic.com/) account. The Terminal CLI and VS Code also support [third-party providers](/en/third-party-integrations).

14 14

~~15**Install Claude Code:**~~15<Tabs>

16 <Tab title="Terminal">

17 The full-featured CLI for working with Claude Code directly in your terminal. Edit files, run commands, and manage your entire project from the command line.

16 18

~~17To install Claude Code, use one of the following methods:~~19 To install Claude Code, use one of the following methods:

18 20

~~19<Tabs>~~21 <Tabs>

20 <Tab title="Native Install (Recommended)">22 <Tab title="Native Install (Recommended)">

21 **macOS, Linux, WSL:**23 **macOS, Linux, WSL:**

22 24

36 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd38 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

37 ```39 ```

38 40

41 **Windows requires [Git for Windows](https://git-scm.com/downloads/win).** Install it first if you don't have it.

39 <Info>43 <Info>

40 Native installations automatically update in the background to keep you on the latest version.44 Native installations automatically update in the background to keep you on the latest version.

41 </Info>45 </Info>

42 </Tab>46 </Tab>

43 47

44 <Tab title="Homebrew">48 <Tab title="Homebrew">

~~45 ```sh theme={null}~~49 ```bash theme={null}

46 brew install --cask claude-code50 brew install --cask claude-code

47 ```51 ```

48 52

60 WinGet installations do not auto-update. Run `winget upgrade Anthropic.ClaudeCode` periodically to get the latest features and security fixes.64 WinGet installations do not auto-update. Run `winget upgrade Anthropic.ClaudeCode` periodically to get the latest features and security fixes.

61 </Info>65 </Info>

62 </Tab>66 </Tab>

~~63</Tabs>~~67 </Tabs>

64 68

~~65**Start using Claude Code:**~~69 Then start Claude Code in any project:

66 70

~~67```bash theme={null}~~71 ```bash theme={null}

~~68cd your-project~~72 cd your-project

~~69claude~~73 claude

~~70```~~74 ```

71 75

~~72You'll be prompted to log in on first use. That's it! [Continue with Quickstart (5 minutes) →](/en/quickstart)~~76 You'll be prompted to log in on first use. That's it! [Continue with the Quickstart →](/en/quickstart)

73 77

~~74<Tip>~~78 <Tip>

75 See [advanced setup](/en/setup) for installation options, manual updates, or uninstallation instructions. Visit [troubleshooting](/en/troubleshooting) if you hit issues.79 See [advanced setup](/en/setup) for installation options, manual updates, or uninstallation instructions. Visit [troubleshooting](/en/troubleshooting) if you hit issues.

~~76</Tip>~~80 </Tip>

81 </Tab>

83 <Tab title="VS Code">

84 The VS Code extension provides inline diffs, @-mentions, plan review, and conversation history directly in your editor.

77 85

~~78## What Claude Code does for you~~86 * [Install for VS Code](vscode:extension/anthropic.claude-code)

87 * [Install for Cursor](cursor:extension/anthropic.claude-code)

79 88

~~80* **Build features from descriptions**: Tell Claude what you want to build in plain English. It will make a plan, write the code, and ensure it works.~~89 Or search for "Claude Code" in the Extensions view (`Cmd+Shift+X` on Mac, `Ctrl+Shift+X` on Windows/Linux). After installing, open the Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`), type "Claude Code", and select **Open in New Tab**.

~~81* **Debug and fix issues**: Describe a bug or paste an error message. Claude Code will analyze your codebase, identify the problem, and implement a fix.~~

82* **Navigate any codebase**: Ask anything about your team's codebase, and get a thoughtful answer back. Claude Code maintains awareness of your entire project structure, can find up-to-date information from the web, and with [MCP](/en/mcp) can pull from external data sources like Google Drive, Figma, and Slack.

~~83* **Automate tedious tasks**: Fix fiddly lint issues, resolve merge conflicts, and write release notes. Do all this in a single command from your developer machines, or automatically in CI.~~

84 90

~~85## Why developers love Claude Code~~91 [Get started with VS Code →](/en/vs-code#get-started)

92 </Tab>

86 93

~~87* **Works in your terminal**: Not another chat window. Not another IDE. Claude Code meets you where you already work, with the tools you already love.~~94 <Tab title="Desktop app">

88* **Takes action**: Claude Code can directly edit files, run commands, and create commits. Need more? [MCP](/en/mcp) lets Claude read your design docs in Google Drive, update your tickets in Jira, or use *your* custom developer tooling.95 A standalone app for running Claude Code outside your IDE or terminal. Review diffs visually, run multiple sessions side by side, schedule recurring tasks, and kick off cloud sessions.

89* **Unix philosophy**: Claude Code is composable and scriptable. `tail -f app.log | claude -p "Slack me if you see any anomalies appear in this log stream"` *works*. Your CI can run `claude -p "If there are new text strings, translate them into French and raise a PR for @lang-fr-team to review"`.

~~90* **Enterprise-ready**: Use the Claude API, or host on AWS or GCP. Enterprise-grade [security](/en/security), [privacy](/en/data-usage), and [compliance](https://trust.anthropic.com/) is built-in.~~

91 96

~~92## Use Claude Code everywhere~~97 Download and install:

93 98

~~94Claude Code works across your development environment: in your terminal, in your IDE, in the cloud, and in Slack.~~99 * [macOS](https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code\&utm_medium=docs) (Intel and Apple Silicon)

100 * [Windows](https://claude.ai/api/desktop/win32/x64/exe/latest/redirect?utm_source=claude_code\&utm_medium=docs) (x64)

101 * [Windows ARM64](https://claude.ai/api/desktop/win32/arm64/exe/latest/redirect?utm_source=claude_code\&utm_medium=docs) (remote sessions only)

95 102

~~96* **[Terminal (CLI)](/en/quickstart)**: the core Claude Code experience. Run `claude` in any terminal to start coding.~~103 After installing, launch Claude, sign in, and click the **Code** tab to start coding. A [paid subscription](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=overview_desktop_pricing) is required.

97* **[Claude Code on the web](/en/claude-code-on-the-web)**: use Claude Code from your browser at [claude.ai/code](https://claude.ai/code) or the Claude iOS app, with no local setup required. Run tasks in parallel, work on repos you don't have locally, and review changes in a built-in diff view.

~~98* **[Desktop app](/en/desktop)**: a standalone application with diff review, parallel sessions via git worktrees, and the ability to launch cloud sessions.~~

~~99* **[VS Code](/en/vs-code)**: a native extension with inline diffs, @-mentions, and plan review.~~

100* **[JetBrains IDEs](/en/jetbrains)**: a plugin for IntelliJ IDEA, PyCharm, WebStorm, and other JetBrains IDEs with IDE diff viewing and context sharing.

101* **[GitHub Actions](/en/github-actions)**: automate code review, issue triage, and other workflows in CI/CD with `@claude` mentions.

102* **[GitLab CI/CD](/en/gitlab-ci-cd)**: event-driven automation for GitLab merge requests and issues.

103* **[Slack](/en/slack)**: mention Claude in Slack to route coding tasks to Claude Code on the web and get PRs back.

104* **[Chrome](/en/chrome)**: connect Claude Code to your browser for live debugging, design verification, and web app testing.

105 104

106## Next steps105 [Learn more about the desktop app →](/en/desktop-quickstart)

106 </Tab>

107

108 <Tab title="Web">

109 Run Claude Code in your browser with no local setup. Kick off long-running tasks and check back when they're done, work on repos you don't have locally, or run multiple tasks in parallel. Available on desktop browsers and the Claude iOS app.

110

111 Start coding at [claude.ai/code](https://claude.ai/code).

112

113 [Get started on the web →](/en/claude-code-on-the-web#getting-started)

114 </Tab>

115

116 <Tab title="JetBrains">

117 A plugin for IntelliJ IDEA, PyCharm, WebStorm, and other JetBrains IDEs with interactive diff viewing and selection context sharing.

118

119 Install the [Claude Code plugin](https://plugins.jetbrains.com/plugin/27310-claude-code-beta-) from the JetBrains Marketplace and restart your IDE.

120

121 [Get started with JetBrains →](/en/jetbrains)

122 </Tab>

123</Tabs>

124

125## What you can do

126

127Here are some of the ways you can use Claude Code:

107 128

108<CardGroup>129<AccordionGroup>

109 <Card title="Quickstart" icon="rocket" href="/en/quickstart">130 <Accordion title="Automate the work you keep putting off" icon="wand-magic-sparkles">

110 See Claude Code in action with practical examples131 Claude Code handles the tedious tasks that eat up your day: writing tests for untested code, fixing lint errors across a project, resolving merge conflicts, updating dependencies, and writing release notes.

111 </Card>

112 132

113 <Card title="Common workflows" icon="graduation-cap" href="/en/common-workflows">133 ```bash theme={null}

114 Step-by-step guides for common workflows134 claude "write tests for the auth module, run them, and fix any failures"

115 </Card>135 ```

136 </Accordion>

137

138 <Accordion title="Build features and fix bugs" icon="hammer">

139 Describe what you want in plain language. Claude Code plans the approach, writes the code across multiple files, and verifies it works.

140

141 For bugs, paste an error message or describe the symptom. Claude Code traces the issue through your codebase, identifies the root cause, and implements a fix. See [common workflows](/en/common-workflows) for more examples.

142 </Accordion>

143

144 <Accordion title="Create commits and pull requests" icon="code-branch">

145 Claude Code works directly with git. It stages changes, writes commit messages, creates branches, and opens pull requests.

146

147 ```bash theme={null}

148 claude "commit my changes with a descriptive message"

149 ```

150

151 In CI, you can automate code review and issue triage with [GitHub Actions](/en/github-actions) or [GitLab CI/CD](/en/gitlab-ci-cd).

152 </Accordion>

153

154 <Accordion title="Connect your tools with MCP" icon="plug">

155 The [Model Context Protocol (MCP)](/en/mcp) is an open standard for connecting AI tools to external data sources. With MCP, Claude Code can read your design docs in Google Drive, update tickets in Jira, pull data from Slack, or use your own custom tooling.

156 </Accordion>

157

158 <Accordion title="Customize with instructions, skills, and hooks" icon="sliders">

159 [`CLAUDE.md`](/en/memory) is a markdown file you add to your project root that Claude Code reads at the start of every session. Use it to set coding standards, architecture decisions, preferred libraries, and review checklists. Claude also builds [auto memory](/en/memory#auto-memory) as it works, saving learnings like build commands and debugging insights across sessions without you writing anything.

160

161 Create [custom commands](/en/skills) to package repeatable workflows your team can share, like `/review-pr` or `/deploy-staging`.

116 162

117 <Card title="Troubleshooting" icon="wrench" href="/en/troubleshooting">163 [Hooks](/en/hooks) let you run shell commands before or after Claude Code actions, like auto-formatting after every file edit or running lint before a commit.

118 Solutions for common issues with Claude Code164 </Accordion>

119 </Card>

120 165

121 <Card title="Desktop app" icon="laptop" href="/en/desktop">166 <Accordion title="Run agent teams and build custom agents" icon="users">

122 Run Claude Code as a standalone application167 Spawn [multiple Claude Code agents](/en/sub-agents) that work on different parts of a task simultaneously. A lead agent coordinates the work, assigns subtasks, and merges results.

123 </Card>

124</CardGroup>

125 168

126## Additional resources169 For fully custom workflows, the [Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview) lets you build your own agents powered by Claude Code's tools and capabilities, with full control over orchestration, tool access, and permissions.

170 </Accordion>

127 171

128<CardGroup>172 <Accordion title="Pipe, script, and automate with the CLI" icon="terminal">

129 <Card title="About Claude Code" icon="sparkles" href="https://claude.com/product/claude-code">173 Claude Code is composable and follows the Unix philosophy. Pipe logs into it, run it in CI, or chain it with other tools:

130 Learn more about Claude Code on claude.com

131 </Card>

132 174

133 <Card title="Build with the Agent SDK" icon="code-branch" href="https://docs.claude.com/en/docs/agent-sdk/overview">175 ```bash theme={null}

134 Create custom AI agents with the Claude Agent SDK176 # Analyze recent log output

135 </Card>177 tail -200 app.log | claude -p "Slack me if you see any anomalies"

178

179 # Automate translations in CI

180 claude -p "translate new strings into French and raise a PR for review"

181

182 # Bulk operations across files

183 git diff main --name-only | claude -p "review these changed files for security issues"

184 ```

185

186 See the [CLI reference](/en/cli-reference) for the full set of commands and flags.

187 </Accordion>

188

189 <Accordion title="Schedule recurring tasks" icon="clock">

190 Run Claude on a schedule to automate work that repeats: morning PR reviews, overnight CI failure analysis, weekly dependency audits, or syncing docs after PRs merge.

136 191

137 <Card title="Host on AWS or GCP" icon="cloud" href="/en/third-party-integrations">192 * [Cloud scheduled tasks](/en/web-scheduled-tasks) run on Anthropic-managed infrastructure, so they keep running even when your computer is off. Create them from the web, the Desktop app, or by running `/schedule` in the CLI.

138 Configure Claude Code with Amazon Bedrock or Google Vertex AI193 * [Desktop scheduled tasks](/en/desktop#schedule-recurring-tasks) run on your machine, with direct access to your local files and tools

139 </Card>194 * [`/loop`](/en/scheduled-tasks) repeats a prompt within a CLI session for quick polling

195 </Accordion>

140 196

141 <Card title="Settings" icon="gear" href="/en/settings">197 <Accordion title="Work from anywhere" icon="globe">

142 Customize Claude Code for your workflow198 Sessions aren't tied to a single surface. Move work between environments as your context changes:

143 </Card>

144 199

145 <Card title="Commands" icon="terminal" href="/en/cli-reference">200 * Step away from your desk and keep working from your phone or any browser with [Remote Control](/en/remote-control)

146 Learn about CLI commands and controls201 * Message [Dispatch](/en/desktop#sessions-from-dispatch) a task from your phone and open the Desktop session it creates

147 </Card>202 * Kick off a long-running task on the [web](/en/claude-code-on-the-web) or [iOS app](https://apps.apple.com/app/claude-by-anthropic/id6473753684), then pull it into your terminal with `/teleport`

203 * Hand off a terminal session to the [Desktop app](/en/desktop) with `/desktop` for visual diff review

204 * Route tasks from team chat: mention `@Claude` in [Slack](/en/slack) with a bug report and get a pull request back

205 </Accordion>

206</AccordionGroup>

148 207

149 <Card title="Reference implementation" icon="code" href="https://github.com/anthropics/claude-code/tree/main/.devcontainer">208## Use Claude Code everywhere

150 Clone our development container reference implementation209

151 </Card>210Each surface connects to the same underlying Claude Code engine, so your CLAUDE.md files, settings, and MCP servers work across all of them.

211

212Beyond the [Terminal](/en/quickstart), [VS Code](/en/vs-code), [JetBrains](/en/jetbrains), [Desktop](/en/desktop), and [Web](/en/claude-code-on-the-web) environments above, Claude Code integrates with CI/CD, chat, and browser workflows:

213

214| I want to... | Best option |

215| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |

216| Continue a local session from my phone or another device | [Remote Control](/en/remote-control) |

217| Push events from Telegram, Discord, iMessage, or my own webhooks into a session | [Channels](/en/channels) |

218| Start a task locally, continue on mobile | [Web](/en/claude-code-on-the-web) or [Claude iOS app](https://apps.apple.com/app/claude-by-anthropic/id6473753684) |

219| Run Claude on a recurring schedule | [Cloud scheduled tasks](/en/web-scheduled-tasks) or [Desktop scheduled tasks](/en/desktop#schedule-recurring-tasks) |

220| Automate PR reviews and issue triage | [GitHub Actions](/en/github-actions) or [GitLab CI/CD](/en/gitlab-ci-cd) |

221| Get automatic code review on every PR | [GitHub Code Review](/en/code-review) |

222| Route bug reports from Slack to pull requests | [Slack](/en/slack) |

223| Debug live web applications | [Chrome](/en/chrome) |

224| Build custom agents for your own workflows | [Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview) |

225

226## Next steps

152 227

153 <Card title="Security" icon="shield" href="/en/security">228Once you've installed Claude Code, these guides help you go deeper.

154 Discover Claude Code's safeguards and best practices for safe usage

155 </Card>

156 229

157 <Card title="Privacy and data usage" icon="lock" href="/en/data-usage">230* [Quickstart](/en/quickstart): walk through your first real task, from exploring a codebase to committing a fix

158 Understand how Claude Code handles your data231* [Store instructions and memories](/en/memory): give Claude persistent instructions with CLAUDE.md files and auto memory

159 </Card>232* [Common workflows](/en/common-workflows) and [best practices](/en/best-practices): patterns for getting the most out of Claude Code

160</CardGroup>233* [Settings](/en/settings): customize Claude Code for your workflow

234* [Troubleshooting](/en/troubleshooting): solutions for common issues

235* [code.claude.com](https://code.claude.com/): demos, pricing, and product details

permission-modes.md +290 −0 added

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# Choose a permission mode

7> Switch between supervised editing, read-only planning, and auto mode where a background classifier replaces manual permission prompts. Cycle modes with Shift+Tab in the CLI or use the mode selector in VS Code, Desktop, and claude.ai.

9Permission modes control whether Claude asks before acting. Different tasks call for different levels of autonomy: you might want full oversight for sensitive work, minimal interruptions for a long refactor, or read-only access while exploring a codebase.

11This page covers how to:

13* [Switch modes](#switch-permission-modes) during a session, at startup, or as a default

14* [Choose a mode](#available-modes) based on what Claude should be able to do without asking

15* [Run auto mode](#eliminate-prompts-with-auto-mode) with background safety checks, and see what it [blocks by default](#what-the-classifier-blocks-by-default)

16* [Plan changes read-only](#analyze-before-you-edit-with-plan-mode) before approving edits

17* [Restrict Claude to pre-approved tools](#allow-only-pre-approved-tools-with-dontask-mode) for locked-down environments

18* [Skip checks entirely](#skip-all-checks-with-bypasspermissions-mode) in isolated environments

20## Switch permission modes

22You can switch modes at any time during a session, at startup, or as a persistent default. The mechanism depends on where you're running Claude Code.

24<Tabs>

25 <Tab title="CLI">

26 **During a session**: press `Shift+Tab` to cycle through `default` → `acceptEdits` → `plan` → `auto`. The current mode appears in the status bar. `auto` does not appear in the cycle until you pass `--enable-auto-mode` at startup. Auto also requires a Team (or Enterprise/API once available) plan and Claude Sonnet 4.6 or Opus 4.6, so the option may remain unavailable even with the flag. If `bypassPermissions` is also enabled, it appears in the cycle between `plan` and `auto`.

28 **At startup**: pass the mode as a CLI flag:

30 ```bash theme={null}

31 claude --permission-mode plan

32 ```

34 **As a default**: set `defaultMode` in your [settings file](/en/settings#settings-files):

36 ```json theme={null}

37 {

38 "permissions": {

39 "defaultMode": "acceptEdits"

40 }

41 }

42 ```

44 **Non-interactively**: the same flag works with `-p` for scripted runs:

46 ```bash theme={null}

47 claude -p "refactor auth" --permission-mode acceptEdits

48 ```

50 `dontAsk` is never in the `Shift+Tab` cycle. `bypassPermissions` appears in the cycle only if you started the session with `--permission-mode bypassPermissions`, `--dangerously-skip-permissions`, or `--allow-dangerously-skip-permissions`. The third flag adds the mode to the cycle without activating it, so you can compose it with a different starting mode like `--permission-mode plan`. Set any of these at startup or in your settings file.

51 </Tab>

53 <Tab title="JetBrains">

54 The JetBrains plugin launches Claude Code in the IDE terminal, so switching modes works the same as in the CLI: press `Shift+Tab` to cycle, or pass `--permission-mode` when launching.

55 </Tab>

57 <Tab title="VS Code">

58 **During a session**: click the mode indicator at the bottom of the prompt box to switch modes.

60 **As a default**: set `claudeCode.initialPermissionMode` in VS Code settings, or use the Claude Code extension settings panel.

62 The VS Code UI uses friendly labels that map to the settings keys below:

64 | UI label | Settings key |

65 | :----------------- | :------------------ |

66 | Ask permissions | `default` |

67 | Auto accept edits | `acceptEdits` |

68 | Plan mode | `plan` |

69 | Auto | `auto` |

70 | Bypass permissions | `bypassPermissions` |

72 Auto and Bypass permissions appear only after you enable **Allow dangerously skip permissions** in the extension settings. Auto also requires a Team plan and Claude Sonnet 4.6 or Opus 4.6, so the option may remain unavailable even with the toggle on.

74 See the [VS Code guide](/en/vs-code) for extension-specific details.

75 </Tab>

77 <Tab title="Desktop">

78 **During a session**: use the mode selector next to the send button. You can change it before or during a session.

80 The Desktop UI uses friendly labels that map to the settings keys below:

82 | UI label | Settings key |

83 | :----------------- | :------------------ |

84 | Ask permissions | `default` |

85 | Auto accept edits | `acceptEdits` |

86 | Plan mode | `plan` |

87 | Auto | `auto` |

88 | Bypass permissions | `bypassPermissions` |

90 Auto and Bypass permissions appear in the selector only after you enable them in Desktop settings. See the [Desktop guide](/en/desktop#choose-a-permission-mode) for details.

91 </Tab>

93 <Tab title="Web and mobile">

94 **During a session**: use the mode dropdown next to the prompt box on [claude.ai/code](https://claude.ai/code) or in the Claude mobile app.

96 For [Claude Code on the web](/en/claude-code-on-the-web) sessions running on Anthropic's cloud VMs, the dropdown offers Auto accept edits and Plan mode. Ask permissions and Auto are not available for cloud sessions.

98 For [Remote Control](/en/remote-control) sessions running on your local machine, the dropdown offers Ask permissions, Auto accept edits, and Plan mode. You can also set the starting mode when you launch the local host:

100 ```bash theme={null}

101 claude remote-control --permission-mode acceptEdits

102 ```

103

104 Permission prompts appear in claude.ai for approval.

105 </Tab>

106</Tabs>

107

108Permission modes are set through the UI, CLI flags, or settings files. Telling Claude "stop asking for permission" in the chat does not change the mode. See [Permissions](/en/permissions) for how modes interact with allow, ask, and deny rules.

109

110## Available modes

111

112Each mode makes a different tradeoff between convenience and oversight. Pick the one that matches your task.

113

114| Mode | What Claude can do without asking | Best for |

115| :------------------------------------------------------------------ | :----------------------------------------- | :------------------------------------------ |

116| `default` | Read files | Getting started, sensitive work |

117| `acceptEdits` | Read and edit files | Iterating on code you're reviewing |

118| [`plan`](#analyze-before-you-edit-with-plan-mode) | Read files | Exploring a codebase, planning a refactor |

119| [`auto`](#eliminate-prompts-with-auto-mode) | All actions, with background safety checks | Long-running tasks, reducing prompt fatigue |

120| [`bypassPermissions`](#skip-all-checks-with-bypasspermissions-mode) | All actions, no checks | Isolated containers and VMs only |

121| [`dontAsk`](#allow-only-pre-approved-tools-with-dontask-mode) | Only pre-approved tools | Locked-down environments |

122

123## Analyze before you edit with plan mode

124

125Plan mode tells Claude to research and propose changes without making them. Claude reads files, runs shell commands to explore, asks clarifying questions, and writes a plan file, but does not edit your source code. Permission prompts work the same as default mode: you still approve Bash commands, network requests, and other actions that would normally prompt.

126

127### When to use plan mode

128

129Plan mode is useful when you want Claude to research and propose an approach before making changes:

130

131* **Multi-step implementation**: when a feature requires edits across many files

132* **Code exploration**: when you want to research the codebase before changing anything

133* **Interactive development**: when you want to iterate on the direction with Claude

134

135### Start and use plan mode

136

137Enter plan mode for a single request by prefixing your prompt with `/plan`, or switch the whole session into plan mode by pressing `Shift+Tab` to [cycle through permission modes](#switch-permission-modes). You can also start in plan mode from the CLI:

138

139```bash theme={null}

140claude --permission-mode plan

141```

142

143This example starts a planning session for a complex refactor:

144

145```text theme={null}

146I need to refactor our authentication system to use OAuth2. Create a detailed migration plan.

147```

148

149Claude analyzes the current implementation and creates a plan. Refine with follow-ups:

150

151```text theme={null}

152What about backward compatibility?

153How should we handle database migration?

154```

155

156When the plan is ready, Claude presents it and asks how to proceed. From that prompt you can:

157

158* Approve and start in auto mode

159* Approve and accept edits

160* Approve and manually review each edit

161* Keep planning, which sends your feedback back to Claude for another round

162

163Each approve option also offers to clear the planning context first.

164

165## Eliminate prompts with auto mode

166

167Auto mode is available on Team plans, with Enterprise and API support rolling out shortly. On Team and Enterprise, an admin must enable it in [Claude Code admin settings](https://claude.ai/admin-settings/claude-code) before users can turn it on. It requires Claude Sonnet 4.6 or Claude Opus 4.6, and is not available on Haiku, claude-3 models, or third-party providers (Bedrock, Vertex, Foundry).

168

169Auto mode lets Claude execute actions without showing permission prompts. Before each action runs, a separate classifier model reviews the conversation and decides whether the action matches what you asked for: it blocks actions that escalate beyond the task scope, target infrastructure the classifier doesn't recognize as trusted, or appear to be driven by hostile content encountered in a file or web page. For a deeper look at how the classifier is designed, see the [auto mode announcement](https://claude.com/blog/auto-mode).

170

171<Warning>

172 Auto mode is a research preview. It reduces prompts but does not guarantee safety. It provides more protection than `bypassPermissions` but is not as thorough as manually reviewing each action. Use it for tasks where you trust the general direction, not as a replacement for review on sensitive operations.

173</Warning>

174

175**Model**: the classifier runs on Claude Sonnet 4.6, even if your main session uses a different model.

176

177**Cost**: classifier calls count toward your token usage the same as main-session calls. Each checked action sends a portion of the conversation transcript plus the pending action to the classifier. The extra cost comes mainly from shell commands and network operations, since read-only actions and file edits in your working directory don't trigger a classifier call.

178

179**Latency**: each classifier check adds a round-trip before the action executes.

180

181### How actions are evaluated

182

183Each action goes through a fixed decision order. The first matching step wins:

184

1851. Actions matching your [allow or deny rules](/en/permissions#manage-permissions) resolve immediately

1862. Read-only actions and file edits in your working directory are auto-approved

1873. Everything else goes to the classifier

1884. If the classifier blocks, Claude receives the reason and attempts an alternative approach

189

190On entering auto mode, Claude Code drops any allow rule that is known to grant arbitrary code execution: blanket shell access like `Bash(*)`, wildcarded script interpreters like `Bash(python*)` or `Bash(node*)`, package-manager run commands, and any `Agent` allow rule. These rules would auto-approve the commands and subagent delegations most capable of causing damage before the classifier ever sees them. Narrow rules like `Bash(npm test)` carry over. The dropped rules are restored when you leave auto mode.

191

192The classifier receives user messages and tool calls as input, with Claude's own text and tool results stripped out. It also receives your CLAUDE.md content, so actions described in your project instructions are factored into allow and block decisions. Because tool results never reach the classifier, hostile content in a file or web page cannot manipulate it directly. The classifier evaluates the pending action against a customizable set of block and allow rules, checking whether the action is an overeager escalation beyond what you asked for, a mistake about what's safe to touch, or a sudden departure from your stated intent that suggests Claude may have been steered by something it read.

193

194Unlike your permission rules, which match tool names and argument patterns, the classifier reads prose descriptions of what to block and allow: it reasons about the action in context rather than matching syntax.

195

196### How auto mode handles subagents

197

198When Claude spawns a [subagent](/en/sub-agents), the classifier evaluates the delegated task before the subagent starts. A task description that looks dangerous on its own, like "delete all remote branches matching this pattern", is blocked at spawn time.

199

200Inside the subagent, auto mode runs with the same block and allow rules as the parent session. Any `permissionMode` the subagent defines in its own frontmatter is ignored. The subagent's own tool calls go through the classifier independently.

201

202When the subagent finishes, the classifier reviews its full action history. A subagent that was benign at spawn could have been compromised mid-run by content it read. If the return check flags a concern, a security warning is prepended to the subagent's results so the main agent can decide how to proceed.

203

204### What the classifier blocks by default

205

206Out of the box, the classifier trusts your working directory and, if you're in a git repo, that repo's configured remotes. Everything else is treated as external: your company's source control orgs, cloud buckets, and internal services are unknown until you tell the classifier about them.

207

208**Blocked by default**:

209

210* Downloading and executing code, like `curl | bash` or scripts from cloned repos

211* Sending sensitive data to external endpoints

212* Production deploys and migrations

213* Mass deletion on cloud storage

214* Granting IAM or repo permissions

215* Modifying shared infrastructure

216* Irreversibly destroying files that existed before the session started

217* Destructive source control operations like force push or pushing directly to `main`

218

219**Allowed by default**:

220

221* Local file operations in your working directory

222* Installing dependencies already declared in your lock files or manifests

223* Reading `.env` and sending credentials to their matching API

224* Read-only HTTP requests

225* Pushing to the branch you started on or one Claude created

226

227To see the full default rule lists as the classifier receives them, run `claude auto-mode defaults`.

228

229If auto mode blocks something routine for your team, like pushing to your own org's repo or writing to a company bucket, it's because the classifier doesn't know those are trusted. Administrators can add trusted repos, buckets, and internal services via the `autoMode.environment` setting: see [Configure the auto mode classifier](/en/permissions#configure-the-auto-mode-classifier) for the full configuration guide.

230

231### When auto mode falls back

232

233The fallback design keeps false positives from derailing a session: a mistaken block costs Claude a retry, not your progress. If the classifier blocks an action 3 times in a row or 20 times total in one session, auto mode pauses and Claude Code resumes prompting for each action. These thresholds are not configurable.

234

235* **CLI**: you see a notification in the status area. Approving the prompted action resets the denial counters, so you can continue in auto mode

236* **Non-interactive mode** with the `-p` flag: aborts the session, since there is no user to prompt

237

238Repeated blocks usually mean one of two things: the task genuinely requires actions the classifier is built to stop, or the classifier is missing context about your trusted infrastructure and treating safe actions as risky. If the blocks look like false positives, or if the classifier misses something it should have caught, use `/feedback` to report it. If blocks are happening because the classifier doesn't recognize your repos or services as trusted, have an administrator [configure trusted infrastructure](/en/permissions#configure-the-auto-mode-classifier) in managed settings.

239

240## Allow only pre-approved tools with dontAsk mode

241

242`dontAsk` mode auto-denies every tool that is not explicitly allowed. Only actions matching your `/permissions` allow rules or `permissions.allow` settings can execute. If a tool has an explicit `ask` rule, the action is also denied rather than prompting. This makes the mode fully non-interactive, suitable for CI pipelines or restricted environments where you pre-define exactly what Claude is permitted to do.

243

244```bash theme={null}

245claude --permission-mode dontAsk

246```

247

248## Skip all checks with bypassPermissions mode

249

250`bypassPermissions` mode disables all permission prompts and safety checks. Every tool call executes immediately without any verification. Only use this in isolated environments like containers, VMs, or devcontainers without internet access, where Claude Code cannot cause damage to your host system.

251

252```bash theme={null}

253claude --permission-mode bypassPermissions

254```

255

256The `--dangerously-skip-permissions` flag is equivalent to `--permission-mode bypassPermissions`:

257

258```bash theme={null}

259claude -p "refactor the auth module" --dangerously-skip-permissions

260```

261

262<Warning>

263 `bypassPermissions` mode offers no protection against prompt injection or unintended actions. For a safer alternative that still maintains background safety checks, use [auto mode](#eliminate-prompts-with-auto-mode). Administrators can block this mode by setting `permissions.disableBypassPermissionsMode` to `"disable"` in [managed settings](/en/permissions#managed-settings).

264</Warning>

265

266## Compare permission approaches

267

268The table below summarizes the key differences in how each mode handles approvals. `plan` is omitted since it restricts what Claude can do rather than how approvals work.

269

271| :----------------- | :---------------------- | :------------------ | :---------------------------- | :------------------------------- | :------------------ |

275

276## Customize permissions further

277

278Permission modes set the baseline approval behavior. For control over individual tools or commands, layer additional configuration on top of the active mode.

279

280**Permission rules** are the first stop. Add `allow`, `ask`, or `deny` entries to your settings file to pre-approve safe commands, force a prompt for risky ones, or block specific tools entirely. Rules apply in every mode except `bypassPermissions`, which skips the permission layer entirely, and are matched by tool name and argument pattern. See [Manage permissions](/en/permissions#manage-permissions) for syntax and examples.

281

282**Hooks** cover logic that pattern-matching rules can't express. A [`PreToolUse` hook](/en/hooks#pretooluse-decision-control) runs before every tool call and can allow, deny, or escalate based on command content, file paths, time of day, or a response from an external policy service. A [`PermissionRequest` hook](/en/hooks#permissionrequest) intercepts the permission dialog itself and answers on your behalf. See [Hooks](/en/hooks) for configuration.

283

284## See also

285

286* [Permissions](/en/permissions): permission rules, syntax, managed policies

287* [Hooks](/en/hooks): custom permission logic, lifecycle scripting

288* [Security](/en/security): security safeguards and best practices

289* [Sandboxing](/en/sandboxing): filesystem and network isolation for Bash commands

290* [Non-interactive mode](/en/headless): run Claude Code programmatically with the `-p` flag

permissions.md +385 −0 added

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# Configure permissions

7> Control what Claude Code can access and do with fine-grained permission rules, modes, and managed policies.

9Claude Code supports fine-grained permissions so that you can specify exactly what the agent is allowed to do and what it cannot. Permission settings can be checked into version control and distributed to all developers in your organization, as well as customized by individual developers.

11## Permission system

13Claude Code uses a tiered permission system to balance power and safety:

16| :---------------- | :--------------- | :---------------- | :-------------------------------------------- |

17| Read-only | File reads, Grep | No | N/A |

18| Bash commands | Shell execution | Yes | Permanently per project directory and command |

19| File modification | Edit/write files | Yes | Until session end |

21## Manage permissions

23You can view and manage Claude Code's tool permissions with `/permissions`. This UI lists all permission rules and the settings.json file they are sourced from.

25* **Allow** rules let Claude Code use the specified tool without manual approval.

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.

29Rules are evaluated in order: **deny -> ask -> allow**. The first matching rule wins, so deny rules always take precedence.

31## Permission modes

33Claude Code supports several permission modes that control how tools are approved. See [Permission modes](/en/permission-modes) for when to use each one. Set the `defaultMode` in your [settings files](/en/settings#settings-files):

35| Mode | Description |

36| :------------------ | :------------------------------------------------------------------------------------------------------------------------------- |

37| `default` | Standard behavior: prompts for permission on first use of each tool |

38| `acceptEdits` | Automatically accepts file edit permissions for the session |

39| `plan` | Plan Mode: Claude can analyze but not modify files or execute commands |

40| `auto` | Auto-approves tool calls with background safety checks that verify actions align with your request. Currently a research preview |

41| `dontAsk` | Auto-denies tools unless pre-approved via `/permissions` or `permissions.allow` rules |

42| `bypassPermissions` | Skips permission prompts except for writes to protected directories (see warning below) |

44<Warning>

45 `bypassPermissions` mode skips permission prompts. Writes to `.git`, `.claude`, `.vscode`, and `.idea` directories still prompt for confirmation to prevent accidental corruption of repository state and local configuration. Writes to `.claude/commands`, `.claude/agents`, and `.claude/skills` are exempt and do not prompt, because Claude routinely writes there when creating skills, subagents, and commands. Only use this mode in isolated environments like containers or VMs where Claude Code cannot cause damage. Administrators can prevent this mode by setting `disableBypassPermissionsMode` to `"disable"` in [managed settings](#managed-settings).

46</Warning>

48To prevent `bypassPermissions` or `auto` mode from being used, set `permissions.disableBypassPermissionsMode` or `disableAutoMode` to `"disable"` in any [settings file](/en/settings#settings-files). These are most useful in [managed settings](#managed-settings) where they cannot be overridden.

50## Permission rule syntax

52Permission rules follow the format `Tool` or `Tool(specifier)`.

54### Match all uses of a tool

56To match all uses of a tool, use just the tool name without parentheses:

58| Rule | Effect |

59| :--------- | :----------------------------- |

60| `Bash` | Matches all Bash commands |

61| `WebFetch` | Matches all web fetch requests |

62| `Read` | Matches all file reads |

64`Bash(*)` is equivalent to `Bash` and matches all Bash commands.

66### Use specifiers for fine-grained control

68Add a specifier in parentheses to match specific tool uses:

70| Rule | Effect |

71| :----------------------------- | :------------------------------------------------------- |

72| `Bash(npm run build)` | Matches the exact command `npm run build` |

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

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

76### Wildcard patterns

78Bash 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:

80```json theme={null}

81{

82 "permissions": {

83 "allow": [

84 "Bash(npm run *)",

85 "Bash(git commit *)",

86 "Bash(git * main)",

87 "Bash(* --version)",

88 "Bash(* --help *)"

89 ],

90 "deny": [

91 "Bash(git push *)"

92 ]

93 }

94}

95```

97The space before `*` matters: `Bash(ls *)` matches `ls -la` but not `lsof`, while `Bash(ls*)` matches both. The legacy `:*` suffix syntax is equivalent to ` *` but is deprecated.

99## Tool-specific permission rules

100

101### Bash

102

103Bash permission rules support wildcard matching with `*`. Wildcards can appear at any position in the command, including at the beginning, middle, or end:

104

105* `Bash(npm run build)` matches the exact Bash command `npm run build`

106* `Bash(npm run test *)` matches Bash commands starting with `npm run test`

107* `Bash(npm *)` matches any command starting with `npm `

108* `Bash(* install)` matches any command ending with ` install`

109* `Bash(git * main)` matches commands like `git checkout main`, `git merge main`

110

111When `*` appears at the end with a space before it (like `Bash(ls *)`), it enforces a word boundary, requiring the prefix to be followed by a space or end-of-string. For example, `Bash(ls *)` matches `ls -la` but not `lsof`. In contrast, `Bash(ls*)` without a space matches both `ls -la` and `lsof` because there's no word boundary constraint.

112

113<Tip>

114 Claude Code is aware of shell operators (like `&&`) so a prefix match rule like `Bash(safe-cmd *)` won't give it permission to run the command `safe-cmd && other-cmd`.

115</Tip>

116

117When you approve a compound command with "Yes, don't ask again", Claude Code saves a separate rule for each subcommand that requires approval, rather than a single rule for the full compound string. For example, approving `git status && npm test` saves a rule for `npm test`, so future `npm test` invocations are recognized regardless of what precedes the `&&`. Subcommands like `cd` into a subdirectory generate their own Read rule for that path. Up to 5 rules may be saved for a single compound command.

118

119<Warning>

120 Bash permission patterns that try to constrain command arguments are fragile. For example, `Bash(curl http://github.com/ *)` intends to restrict curl to GitHub URLs, but won't match variations like:

121

122 * Options before URL: `curl -X GET http://github.com/...`

123 * Different protocol: `curl https://github.com/...`

124 * Redirects: `curl -L http://bit.ly/xyz` (redirects to github)

125 * Variables: `URL=http://github.com && curl $URL`

126 * Extra spaces: `curl http://github.com`

127

128 For more reliable URL filtering, consider:

129

130 * **Restrict Bash network tools**: use deny rules to block `curl`, `wget`, and similar commands, then use the WebFetch tool with `WebFetch(domain:github.com)` permission for allowed domains

131 * **Use PreToolUse hooks**: implement a hook that validates URLs in Bash commands and blocks disallowed domains

132 * Instructing Claude Code about your allowed curl patterns via CLAUDE.md

133

134 Note that using WebFetch alone does not prevent network access. If Bash is allowed, Claude can still use `curl`, `wget`, or other tools to reach any URL.

135</Warning>

136

137### Read and Edit

138

139`Edit` rules apply to all built-in tools that edit files. Claude makes a best-effort attempt to apply `Read` rules to all built-in tools that read files like Grep and Glob.

140

141<Warning>

142 Read and Edit deny rules apply to Claude's built-in file tools, not to Bash subprocesses. A `Read(./.env)` deny rule blocks the Read tool but does not prevent `cat .env` in Bash. For OS-level enforcement that blocks all processes from accessing a path, [enable the sandbox](/en/sandboxing).

143</Warning>

144

145Read and Edit rules both follow the [gitignore](https://git-scm.com/docs/gitignore) specification with four distinct pattern types:

146

148| ------------------ | -------------------------------------- | -------------------------------- | ------------------------------ |

149| `//path` | **Absolute** path from filesystem root | `Read(//Users/alice/secrets/**)` | `/Users/alice/secrets/**` |

150| `~/path` | Path from **home** directory | `Read(~/Documents/*.pdf)` | `/Users/alice/Documents/*.pdf` |

151| `/path` | Path **relative to project root** | `Edit(/src/**/*.ts)` | `<project root>/src/**/*.ts` |

152| `path` or `./path` | Path **relative to current directory** | `Read(*.env)` | `<cwd>/*.env` |

153

154<Warning>

155 A pattern like `/Users/alice/file` is NOT an absolute path. It's relative to the project root. Use `//Users/alice/file` for absolute paths.

156</Warning>

157

158On Windows, paths are normalized to POSIX form before matching. `C:\Users\alice` becomes `/c/Users/alice`, so use `//c/**/.env` to match `.env` files anywhere on that drive. To match across all drives, use `//**/.env`.

159

160Examples:

161

162* `Edit(/docs/**)`: edits in `<project>/docs/` (NOT `/docs/` and NOT `<project>/.claude/docs/`)

163* `Read(~/.zshrc)`: reads your home directory's `.zshrc`

164* `Edit(//tmp/scratch.txt)`: edits the absolute path `/tmp/scratch.txt`

165* `Read(src/**)`: reads from `<current-directory>/src/`

166

167<Note>

168 In gitignore patterns, `*` matches files in a single directory while `**` matches recursively across directories. To allow all file access, use just the tool name without parentheses: `Read`, `Edit`, or `Write`.

169</Note>

170

171### WebFetch

172

173* `WebFetch(domain:example.com)` matches fetch requests to example.com

174

175### MCP

176

177* `mcp__puppeteer` matches any tool provided by the `puppeteer` server (name configured in Claude Code)

178* `mcp__puppeteer__*` wildcard syntax that also matches all tools from the `puppeteer` server

179* `mcp__puppeteer__puppeteer_navigate` matches the `puppeteer_navigate` tool provided by the `puppeteer` server

180

181### Agent (subagents)

182

183Use `Agent(AgentName)` rules to control which [subagents](/en/sub-agents) Claude can use:

184

185* `Agent(Explore)` matches the Explore subagent

186* `Agent(Plan)` matches the Plan subagent

187* `Agent(my-custom-agent)` matches a custom subagent named `my-custom-agent`

188

189Add these rules to the `deny` array in your settings or use the `--disallowedTools` CLI flag to disable specific agents. To disable the Explore agent:

190

191```json theme={null}

192{

193 "permissions": {

194 "deny": ["Agent(Explore)"]

195 }

196}

197```

198

199## Extend permissions with hooks

200

201[Claude Code hooks](/en/hooks-guide) provide a way to register custom shell commands to perform permission evaluation at runtime. When Claude Code makes a tool call, PreToolUse hooks run before the permission prompt. The hook output can deny the tool call, force a prompt, or skip the prompt to let the call proceed.

202

203Skipping the prompt does not bypass permission rules. Deny and ask rules are still evaluated after a hook returns `"allow"`, so a matching deny rule still blocks the call. This preserves the deny-first precedence described in [Manage permissions](#manage-permissions), including deny rules set in managed settings.

204

205A blocking hook also takes precedence over allow rules. A hook that exits with code 2 stops the tool call before permission rules are evaluated, so the block applies even when an allow rule would otherwise let the call proceed. To run all Bash commands without prompts except for a few you want blocked, add `"Bash"` to your allow list and register a PreToolUse hook that rejects those specific commands. See [Block edits to protected files](/en/hooks-guide#block-edits-to-protected-files) for a hook script you can adapt.

206

207## Working directories

208

209By default, Claude has access to files in the directory where it was launched. You can extend this access:

210

211* **During startup**: use `--add-dir <path>` CLI argument

212* **During session**: use `/add-dir` command

213* **Persistent configuration**: add to `additionalDirectories` in [settings files](/en/settings#settings-files)

214

215Files in additional directories follow the same permission rules as the original working directory: they become readable without prompts, and file editing permissions follow the current permission mode.

216

217## How permissions interact with sandboxing

218

219Permissions and [sandboxing](/en/sandboxing) are complementary security layers:

220

221* **Permissions** control which tools Claude Code can use and which files or domains it can access. They apply to all tools (Bash, Read, Edit, WebFetch, MCP, and others).

222* **Sandboxing** provides OS-level enforcement that restricts the Bash tool's filesystem and network access. It applies only to Bash commands and their child processes.

223

224Use both for defense-in-depth:

225

226* Permission deny rules block Claude from even attempting to access restricted resources

227* Sandbox restrictions prevent Bash commands from reaching resources outside defined boundaries, even if a prompt injection bypasses Claude's decision-making

228* Filesystem restrictions in the sandbox use Read and Edit deny rules, not separate sandbox configuration

229* Network restrictions combine WebFetch permission rules with the sandbox's `allowedDomains` list

230

231## Managed settings

232

233For organizations that need centralized control over Claude Code configuration, administrators can deploy managed settings that cannot be overridden by user or project settings. These policy settings follow the same format as regular settings files and can be delivered through MDM/OS-level policies, managed settings files, or [server-managed settings](/en/server-managed-settings). See [settings files](/en/settings#settings-files) for delivery mechanisms and file locations.

234

235### Managed-only settings

236

237Some settings are only effective in managed settings:

238

239| Setting | Description |

240| :--------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

241| `allowManagedPermissionRulesOnly` | When `true`, prevents user and project settings from defining `allow`, `ask`, or `deny` permission rules. Only rules in managed settings apply |

242| `allowManagedHooksOnly` | When `true`, prevents loading of user, project, and plugin hooks. Only managed hooks and SDK hooks are allowed |

243| `allowManagedMcpServersOnly` | When `true`, only `allowedMcpServers` from managed settings are respected. `deniedMcpServers` still merges from all sources. See [Managed MCP configuration](/en/mcp#managed-mcp-configuration) |

244| `allowedChannelPlugins` | Allowlist of channel plugins that may push messages. Replaces the default Anthropic allowlist when set. Requires `channelsEnabled: true`. See [Restrict which channel plugins can run](/en/channels#restrict-which-channel-plugins-can-run) |

245| `blockedMarketplaces` | Blocklist of marketplace sources. Blocked sources are checked before downloading, so they never touch the filesystem. See [managed marketplace restrictions](/en/plugin-marketplaces#managed-marketplace-restrictions) |

246| `sandbox.network.allowManagedDomainsOnly` | When `true`, only `allowedDomains` and `WebFetch(domain:...)` allow rules from managed settings are respected. Non-allowed domains are blocked automatically without prompting the user. Denied domains still merge from all sources |

247| `sandbox.filesystem.allowManagedReadPathsOnly` | When `true`, only `allowRead` paths from managed settings are respected. `allowRead` entries from user, project, and local settings are ignored |

248| `strictKnownMarketplaces` | Controls which plugin marketplaces users can add. See [managed marketplace restrictions](/en/plugin-marketplaces#managed-marketplace-restrictions) |

249

250<Note>

251 Access to [Remote Control](/en/remote-control) and [web sessions](/en/claude-code-on-the-web) is not controlled by a managed settings key. On Team and Enterprise plans, an admin enables or disables these features in [Claude Code admin settings](https://claude.ai/admin-settings/claude-code).

252</Note>

253

254## Configure the auto mode classifier

255

256[Auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) uses a classifier model to decide whether each action is safe to run without prompting. Out of the box it trusts only the working directory and, if present, the current repo's remotes. Actions like pushing to your company's source control org or writing to a team cloud bucket will be blocked as potential data exfiltration. The `autoMode` settings block lets you tell the classifier which infrastructure your organization trusts.

257

258The classifier reads `autoMode` from user settings, `.claude/settings.local.json`, and managed settings. It does not read from shared project settings in `.claude/settings.json`, because a checked-in repo could otherwise inject its own allow rules.

259

260| Scope | File | Use for |

261| :------------------------- | :---------------------------- | :-------------------------------------------------- |

262| One developer | `~/.claude/settings.json` | Personal trusted infrastructure |

263| One project, one developer | `.claude/settings.local.json` | Per-project trusted buckets or services, gitignored |

264| Organization-wide | Managed settings | Trusted infrastructure enforced for all developers |

265

266Entries from each scope are combined. A developer can extend `environment`, `allow`, and `soft_deny` with personal entries but cannot remove entries that managed settings provide. Because allow rules act as exceptions to block rules inside the classifier, a developer-added `allow` entry can override an organization `soft_deny` entry: the combination is additive, not a hard policy boundary. If you need a rule that developers cannot work around, use `permissions.deny` in managed settings instead, which blocks actions before the classifier is consulted.

267

268### Define trusted infrastructure

269

270For most organizations, `autoMode.environment` is the only field you need to set. It tells the classifier which repos, buckets, and domains are trusted, without touching the built-in block and allow rules. The classifier uses `environment` to decide what "external" means: any destination not listed is a potential exfiltration target.

271

272```json theme={null}

273{

274 "autoMode": {

275 "environment": [

276 "Source control: github.example.com/acme-corp and all repos under it",

277 "Trusted cloud buckets: s3://acme-build-artifacts, gs://acme-ml-datasets",

278 "Trusted internal domains: *.corp.example.com, api.internal.example.com",

279 "Key internal services: Jenkins at ci.example.com, Artifactory at artifacts.example.com"

280 ]

281 }

282}

283```

284

285Entries are prose, not regex or tool patterns. The classifier reads them as natural-language rules. Write them the way you would describe your infrastructure to a new engineer. A thorough environment section covers:

286

287* **Organization**: your company name and what Claude Code is primarily used for, like software development, infrastructure automation, or data engineering

288* **Source control**: every GitHub, GitLab, or Bitbucket org your developers push to

289* **Cloud providers and trusted buckets**: bucket names or prefixes that Claude should be able to read from and write to

290* **Trusted internal domains**: hostnames for APIs, dashboards, and services inside your network, like `*.internal.example.com`

291* **Key internal services**: CI, artifact registries, internal package indexes, incident tooling

292* **Additional context**: regulated-industry constraints, multi-tenant infrastructure, or compliance requirements that affect what the classifier should treat as risky

293

294A useful starting template: fill in the bracketed fields and remove any lines that don't apply:

295

296```json theme={null}

297{

298 "autoMode": {

299 "environment": [

300 "Organization: {COMPANY_NAME}. Primary use: {PRIMARY_USE_CASE, e.g. software development, infrastructure automation}",

301 "Source control: {SOURCE_CONTROL, e.g. GitHub org github.example.com/acme-corp}",

302 "Cloud provider(s): {CLOUD_PROVIDERS, e.g. AWS, GCP, Azure}",

303 "Trusted cloud buckets: {TRUSTED_BUCKETS, e.g. s3://acme-builds, gs://acme-datasets}",

304 "Trusted internal domains: {TRUSTED_DOMAINS, e.g. *.internal.example.com, api.example.com}",

305 "Key internal services: {SERVICES, e.g. Jenkins at ci.example.com, Artifactory at artifacts.example.com}",

306 "Additional context: {EXTRA, e.g. regulated industry, multi-tenant infrastructure, compliance requirements}"

307 ]

308 }

309}

310```

311

312The more specific context you give, the better the classifier can distinguish routine internal operations from exfiltration attempts.

313

314You don't need to fill everything in at once. A reasonable rollout: start with the defaults and add your source control org and key internal services, which resolves the most common false positives like pushing to your own repos. Add trusted domains and cloud buckets next. Fill the rest as blocks come up.

315

316### Override the block and allow rules

317

318Two additional fields let you replace the classifier's built-in rule lists: `autoMode.soft_deny` controls what gets blocked, and `autoMode.allow` controls which exceptions apply. Each is an array of prose descriptions, read as natural-language rules.

319

320Inside the classifier, the precedence is: `soft_deny` rules block first, then `allow` rules override as exceptions, then explicit user intent overrides both. If the user's message directly and specifically describes the exact action Claude is about to take, the classifier allows it even if a `soft_deny` rule matches. General requests don't count: asking Claude to "clean up the repo" does not authorize force-pushing, but asking Claude to "force-push this branch" does.

321

322To loosen: remove rules from `soft_deny` when the defaults block something your pipeline already guards against with PR review, CI, or staging environments, or add to `allow` when the classifier repeatedly flags a routine pattern the default exceptions don't cover. To tighten: add to `soft_deny` for risks specific to your environment that the defaults miss, or remove from `allow` to hold a default exception to the block rules. In all cases, run `claude auto-mode defaults` to get the full default lists, then copy and edit: never start from an empty list.

323

324```json theme={null}

325{

326 "autoMode": {

327 "environment": [

328 "Source control: github.example.com/acme-corp and all repos under it"

329 ],

330 "allow": [

331 "Deploying to the staging namespace is allowed: staging is isolated from production and resets nightly",

332 "Writing to s3://acme-scratch/ is allowed: ephemeral bucket with a 7-day lifecycle policy"

333 ],

334 "soft_deny": [

335 "Never run database migrations outside the migrations CLI, even against dev databases",

336 "Never modify files under infra/terraform/prod/: production infrastructure changes go through the review workflow",

337 "...copy full default soft_deny list here first, then add your rules..."

338 ]

339 }

340}

341```

342

343<Danger>

344 Setting `allow` or `soft_deny` replaces the entire default list for that section. If you set `soft_deny` with a single entry, every built-in block rule is discarded: force push, data exfiltration, `curl | bash`, production deploys, and all other default block rules become allowed. To customize safely, run `claude auto-mode defaults` to print the built-in rules, copy them into your settings file, then review each rule against your own pipeline and risk tolerance. Only remove rules for risks your infrastructure already mitigates.

345</Danger>

346

347The three sections are evaluated independently, so setting `environment` alone leaves the default `allow` and `soft_deny` lists intact.

348

349### Inspect the defaults and your effective config

350

351Because setting `allow` or `soft_deny` replaces the defaults, start any customization by copying the full default lists. Three CLI subcommands help you inspect and validate:

352

353```bash theme={null}

354claude auto-mode defaults # the built-in environment, allow, and soft_deny rules

355claude auto-mode config # what the classifier actually uses: your settings where set, defaults otherwise

356claude auto-mode critique # get AI feedback on your custom allow and soft_deny rules

357```

358

359Save the output of `claude auto-mode defaults` to a file, edit the lists to match your policy, and paste the result into your settings file. After saving, run `claude auto-mode config` to confirm the effective rules are what you expect. If you've written custom rules, `claude auto-mode critique` reviews them and flags entries that are ambiguous, redundant, or likely to cause false positives.

360

361## Settings precedence

362

363Permission rules follow the same [settings precedence](/en/settings#settings-precedence) as all other Claude Code settings:

364

3651. **Managed settings**: cannot be overridden by any other level, including command line arguments

3662. **Command line arguments**: temporary session overrides

3673. **Local project settings** (`.claude/settings.local.json`)

3684. **Shared project settings** (`.claude/settings.json`)

3695. **User settings** (`~/.claude/settings.json`)

370

371If a tool is denied at any level, no other level can allow it. For example, a managed settings deny cannot be overridden by `--allowedTools`, and `--disallowedTools` can add restrictions beyond what managed settings define.

372

373If a permission is allowed in user settings but denied in project settings, the project setting takes precedence and the permission is blocked.

374

375## Example configurations

376

377This [repository](https://github.com/anthropics/claude-code/tree/main/examples/settings) includes starter settings configurations for common deployment scenarios. Use these as starting points and adjust them to fit your needs.

378

379## See also

380

381* [Settings](/en/settings): complete configuration reference including the permission settings table

382* [Sandboxing](/en/sandboxing): OS-level filesystem and network isolation for Bash commands

383* [Authentication](/en/authentication): set up user access to Claude Code

384* [Security](/en/security): security safeguards and best practices

385* [Hooks](/en/hooks-guide): automate workflows and extend permission evaluation

platforms.md +78 −0 added

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# Platforms and integrations

7> Choose where to run Claude Code and what to connect it to. Compare the CLI, Desktop, VS Code, JetBrains, web, and integrations like Chrome, Slack, and CI/CD.

9Claude Code runs the same underlying engine everywhere, but each surface is tuned for a different way of working. This page helps you pick the right platform for your workflow and connect the tools you already use.

11## Where to run Claude Code

13Choose a platform based on how you like to work and where your project lives.

15| Platform | Best for | What you get |

16| :-------------------------------- | :------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- |

17| [CLI](/en/quickstart) | Terminal workflows, scripting, remote servers | Full feature set, [Agent SDK](/en/headless), third-party providers |

18| [Desktop](/en/desktop) | Visual review, parallel sessions, managed setup | Diff viewer, app preview, [computer use](/en/desktop#let-claude-use-your-computer) and [Dispatch](/en/desktop#sessions-from-dispatch) on Pro and Max |

19| [VS Code](/en/vs-code) | Working inside VS Code without switching to a terminal | Inline diffs, integrated terminal, file context |

20| [JetBrains](/en/jetbrains) | Working inside IntelliJ, PyCharm, WebStorm, or other JetBrains IDEs | Diff viewer, selection sharing, terminal session |

21| [Web](/en/claude-code-on-the-web) | Long-running tasks that don't need much steering, or work that should continue when you're offline | Anthropic-managed cloud, continues after you disconnect |

23The CLI is the most complete surface for terminal-native work: scripting, third-party providers, and the Agent SDK are CLI-only. Desktop and the IDE extensions trade some CLI-only features for visual review and tighter editor integration. The web runs in Anthropic's cloud, so tasks keep going after you disconnect.

25You can mix surfaces on the same project. Configuration, project memory, and MCP servers are shared across the local surfaces.

27## Connect your tools

29Integrations let Claude work with services outside your codebase.

31| Integration | What it does | Use it for |

32| :----------------------------------- | :------------------------------------------------- | :--------------------------------------------------------------- |

33| [Chrome](/en/chrome) | Controls your browser with your logged-in sessions | Testing web apps, filling forms, automating sites without an API |

34| [GitHub Actions](/en/github-actions) | Runs Claude in your CI pipeline | Automated PR reviews, issue triage, scheduled maintenance |

35| [GitLab CI/CD](/en/gitlab-ci-cd) | Same as GitHub Actions for GitLab | CI-driven automation on GitLab |

36| [Code Review](/en/code-review) | Reviews every PR automatically | Catching bugs before human review |

37| [Slack](/en/slack) | Responds to `@Claude` mentions in your channels | Turning bug reports into pull requests from team chat |

39For integrations not listed here, [MCP servers](/en/mcp) and [connectors](/en/desktop#connect-external-tools) let you connect almost anything: Linear, Notion, Google Drive, or your own internal APIs.

41## Work when you are away from your terminal

43Claude Code offers several ways to work when you're not at your terminal. They differ in what triggers the work, where Claude runs, and how much you need to set up.

46| :--------------------------------------------- | :--------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------ |

53If you're not sure where to start, [install the CLI](/en/quickstart) and run it in a project directory. If you'd rather not use a terminal, [Desktop](/en/desktop-quickstart) gives you the same engine with a graphical interface.

55## Related resources

57### Platforms

59* [CLI quickstart](/en/quickstart): install and run your first command in the terminal

60* [Desktop](/en/desktop): visual diff review, parallel sessions, computer use, and Dispatch

61* [VS Code](/en/vs-code): the Claude Code extension inside your editor

62* [JetBrains](/en/jetbrains): the extension for IntelliJ, PyCharm, and other JetBrains IDEs

63* [Claude Code on the web](/en/claude-code-on-the-web): cloud sessions that keep running when you disconnect

65### Integrations

67* [Chrome](/en/chrome): automate browser tasks with your logged-in sessions

68* [GitHub Actions](/en/github-actions): run Claude in your CI pipeline

69* [GitLab CI/CD](/en/gitlab-ci-cd): the same for GitLab

70* [Code Review](/en/code-review): automatic review on every pull request

71* [Slack](/en/slack): send tasks from team chat, get PRs back

73### Remote access

75* [Dispatch](/en/desktop#sessions-from-dispatch): message a task from your phone and it can spawn a Desktop session

76* [Remote Control](/en/remote-control): drive a running session from your phone or browser

77* [Channels](/en/channels): push events from chat apps or your own servers into a session

78* [Scheduled tasks](/en/scheduled-tasks): run prompts on a recurring schedule

plugin-marketplaces.md +295 −30

Details

6 6

7> Build and host plugin marketplaces to distribute Claude Code extensions across teams and communities.7> Build and host plugin marketplaces to distribute Claude Code extensions across teams and communities.

8 8

9A plugin marketplace is a catalog that lets you distribute plugins to others. Marketplaces provide centralized discovery, version tracking, automatic updates, and support for multiple source types (git repositories, local paths, and more). This guide shows you how to create your own marketplace to share plugins with your team or community.9A **plugin marketplace** is a catalog that lets you distribute plugins to others. Marketplaces provide centralized discovery, version tracking, automatic updates, and support for multiple source types (git repositories, local paths, and more). This guide shows you how to create your own marketplace to share plugins with your team or community.

10 10

11Looking to install plugins from an existing marketplace? See [Discover and install prebuilt plugins](/en/discover-plugins).11Looking to install plugins from an existing marketplace? See [Discover and install prebuilt plugins](/en/discover-plugins).

12 12

23 23

24## Walkthrough: create a local marketplace24## Walkthrough: create a local marketplace

25 25

26This example creates a marketplace with one plugin: a `/review` skill for code reviews. You'll create the directory structure, add a skill, create the plugin manifest and marketplace catalog, then install and test it.26This example creates a marketplace with one plugin: a `/quality-review` skill for code reviews. You'll create the directory structure, add a skill, create the plugin manifest and marketplace catalog, then install and test it.

27 27

28<Steps>28<Steps>

29 <Step title="Create the directory structure">29 <Step title="Create the directory structure">

30 ```bash theme={null}30 ```bash theme={null}

31 mkdir -p my-marketplace/.claude-plugin31 mkdir -p my-marketplace/.claude-plugin

~~32 mkdir -p my-marketplace/plugins/review-plugin/.claude-plugin~~32 mkdir -p my-marketplace/plugins/quality-review-plugin/.claude-plugin

~~33 mkdir -p my-marketplace/plugins/review-plugin/skills/review~~33 mkdir -p my-marketplace/plugins/quality-review-plugin/skills/quality-review

34 ```34 ```

35 </Step>35 </Step>

36 36

37 <Step title="Create the skill">37 <Step title="Create the skill">

~~38 Create a `SKILL.md` file that defines what the `/review` skill does.~~38 Create a `SKILL.md` file that defines what the `/quality-review` skill does.

39 39

~~40 ```markdown my-marketplace/plugins/review-plugin/skills/review/SKILL.md theme={null}~~40 ```markdown my-marketplace/plugins/quality-review-plugin/skills/quality-review/SKILL.md theme={null}

41 ---41 ---

42 description: Review code for bugs, security, and performance42 description: Review code for bugs, security, and performance

43 disable-model-invocation: true43 disable-model-invocation: true

56 <Step title="Create the plugin manifest">56 <Step title="Create the plugin manifest">

57 Create a `plugin.json` file that describes the plugin. The manifest goes in the `.claude-plugin/` directory.57 Create a `plugin.json` file that describes the plugin. The manifest goes in the `.claude-plugin/` directory.

58 58

~~59 ```json my-marketplace/plugins/review-plugin/.claude-plugin/plugin.json theme={null}~~59 ```json my-marketplace/plugins/quality-review-plugin/.claude-plugin/plugin.json theme={null}

60 {60 {

~~61 "name": "review-plugin",~~61 "name": "quality-review-plugin",

~~62 "description": "Adds a /review skill for quick code reviews",~~62 "description": "Adds a /quality-review skill for quick code reviews",

63 "version": "1.0.0"63 "version": "1.0.0"

64 }64 }

65 ```65 ```

76 },76 },

77 "plugins": [77 "plugins": [

78 {78 {

~~79 "name": "review-plugin",~~79 "name": "quality-review-plugin",

~~80 "source": "./plugins/review-plugin",~~80 "source": "./plugins/quality-review-plugin",

~~81 "description": "Adds a /review skill for quick code reviews"~~81 "description": "Adds a /quality-review skill for quick code reviews"

82 }82 }

83 ]83 ]

84 }84 }

90 90

91 ```shell theme={null}91 ```shell theme={null}

92 /plugin marketplace add ./my-marketplace92 /plugin marketplace add ./my-marketplace

~~93 /plugin install review-plugin@my-plugins~~93 /plugin install quality-review-plugin@my-plugins

94 ```94 ```

95 </Step>95 </Step>

96 96

98 Select some code in your editor and run your new command.98 Select some code in your editor and run your new command.

99 99

100 ```shell theme={null}100 ```shell theme={null}

101 /review101 /quality-review

102 ```102 ```

103 </Step>103 </Step>

104</Steps>104</Steps>

108<Note>108<Note>

109 **How plugins are installed**: When users install a plugin, Claude Code copies the plugin directory to a cache location. This means plugins can't reference files outside their directory using paths like `../shared-utils`, because those files won't be copied.109 **How plugins are installed**: When users install a plugin, Claude Code copies the plugin directory to a cache location. This means plugins can't reference files outside their directory using paths like `../shared-utils`, because those files won't be copied.

110 110

111 If you need to share files across plugins, use symlinks (which are followed during copying) or restructure your marketplace so the shared directory is inside the plugin source path. See [Plugin caching and file resolution](/en/plugins-reference#plugin-caching-and-file-resolution) for details.111 If you need to share files across plugins, use symlinks (which are followed during copying). See [Plugin caching and file resolution](/en/plugins-reference#plugin-caching-and-file-resolution) for details.

112</Note>112</Note>

113 113

114## Create the marketplace file114## Create the marketplace file

158 158

159<Note>159<Note>

160 **Reserved names**: The following marketplace names are reserved for official Anthropic use and cannot be used by third-party marketplaces: `claude-code-marketplace`, `claude-code-plugins`, `claude-plugins-official`, `anthropic-marketplace`, `anthropic-plugins`, `agent-skills`, `life-sciences`. Names that impersonate official marketplaces (like `official-claude-plugins` or `anthropic-tools-v2`) are also blocked.160 **Reserved names**: The following marketplace names are reserved for official Anthropic use and cannot be used by third-party marketplaces: `claude-code-marketplace`, `claude-code-plugins`, `claude-plugins-official`, `anthropic-marketplace`, `anthropic-plugins`, `agent-skills`, `knowledge-work-plugins`, `life-sciences`. Names that impersonate official marketplaces (like `official-claude-plugins` or `anthropic-tools-v2`) are also blocked.

161</Note>161</Note>

162 162

163### Owner fields163### Owner fields

191**Standard metadata fields:**191**Standard metadata fields:**

192 192

194| :------------ | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |194| :------------ | :------ | :-------------------------------------------------------------------------------------------------------------------------------- |

204| `strict` | boolean | Controls whether plugins need their own `plugin.json` file. When `true` (default), the plugin source must contain a `plugin.json`, and any fields you add here in the marketplace entry get merged with it. When `false`, the plugin doesn't need its own `plugin.json`; the marketplace entry itself defines everything about the plugin. Use `false` when you want to define simple plugins entirely in your marketplace file. |204| `strict` | boolean | Controls whether `plugin.json` is the authority for component definitions (default: true). See [Strict mode](#strict-mode) below. |

205 205

206**Component configuration fields:**206**Component configuration fields:**

207 207

215 215

216## Plugin sources216## Plugin sources

217 217

218Plugin sources tell Claude Code where to fetch each individual plugin listed in your marketplace. These are set in the `source` field of each plugin entry in `marketplace.json`.

219

220Once a plugin is cloned or copied into the local machine, it is copied into the local versioned plugin cache at `~/.claude/plugins/cache`.

221

223| ------------- | ------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------- |

229

230<Note>

231 **Marketplace sources vs plugin sources**: These are different concepts that control different things.

232

233 * **Marketplace source** — where to fetch the `marketplace.json` catalog itself. Set when users run `/plugin marketplace add` or in `extraKnownMarketplaces` settings. Supports `ref` (branch/tag) but not `sha`.

234 * **Plugin source** — where to fetch an individual plugin listed in the marketplace. Set in the `source` field of each plugin entry inside `marketplace.json`. Supports both `ref` (branch/tag) and `sha` (exact commit).

235

236 For example, a marketplace hosted at `acme-corp/plugin-catalog` (marketplace source) can list a plugin fetched from `acme-corp/code-formatter` (plugin source). The marketplace source and plugin source point to different repositories and are pinned independently.

237</Note>

238

218### Relative paths239### Relative paths

219 240

220For plugins in the same repository:241For plugins in the same repository, use a path starting with `./`:

221 242

222```json theme={null}243```json theme={null}

223{244{

226}247}

227```248```

228 249

250Paths resolve relative to the marketplace root, which is the directory containing `.claude-plugin/`. In the example above, `./plugins/my-plugin` points to `<repo>/plugins/my-plugin`, even though `marketplace.json` lives at `<repo>/.claude-plugin/marketplace.json`. Do not use `../` to climb out of `.claude-plugin/`.

251

229<Note>252<Note>

230 Relative paths only work when users add your marketplace via Git (GitHub, GitLab, or git URL). If users add your marketplace via a direct URL to the `marketplace.json` file, relative paths will not resolve correctly. For URL-based distribution, use GitHub, npm, or git URL sources instead. See [Troubleshooting](#plugins-with-relative-paths-fail-in-url-based-marketplaces) for details.253 Relative paths only work when users add your marketplace via Git (GitHub, GitLab, or git URL). If users add your marketplace via a direct URL to the `marketplace.json` file, relative paths will not resolve correctly. For URL-based distribution, use GitHub, npm, or git URL sources instead. See [Troubleshooting](#plugins-with-relative-paths-fail-in-url-based-marketplaces) for details.

231</Note>254</Note>

289```312```

290 313

292| :---- | :----- | :-------------------------------------------------------------------- |315| :---- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------- |

293| `url` | string | Required. Full git repository URL (must end with `.git`) |316| `url` | string | Required. Full git repository URL (`https://` or `git@`). The `.git` suffix is optional, so Azure DevOps and AWS CodeCommit URLs without the suffix work |

317| `ref` | string | Optional. Git branch or tag (defaults to repository default branch) |

318| `sha` | string | Optional. Full 40-character git commit SHA to pin to an exact version |

319

320### Git subdirectories

321

322Use `git-subdir` to point to a plugin that lives inside a subdirectory of a git repository. Claude Code uses a sparse, partial clone to fetch only the subdirectory, minimizing bandwidth for large monorepos.

323

324```json theme={null}

325{

326 "name": "my-plugin",

327 "source": {

328 "source": "git-subdir",

329 "url": "https://github.com/acme-corp/monorepo.git",

330 "path": "tools/claude-plugin"

331 }

332}

333```

334

335You can pin to a specific branch, tag, or commit:

336

337```json theme={null}

338{

339 "name": "my-plugin",

340 "source": {

341 "source": "git-subdir",

342 "url": "https://github.com/acme-corp/monorepo.git",

343 "path": "tools/claude-plugin",

344 "ref": "v2.0.0",

345 "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"

346 }

347}

348```

349

350The `url` field also accepts a GitHub shorthand (`owner/repo`) or SSH URLs (`git@github.com:owner/repo.git`).

351

352| Field | Type | Description |

353| :----- | :----- | :------------------------------------------------------------------------------------------------------- |

354| `url` | string | Required. Git repository URL, GitHub `owner/repo` shorthand, or SSH URL |

355| `path` | string | Required. Subdirectory path within the repo containing the plugin (for example, `"tools/claude-plugin"`) |

294| `ref` | string | Optional. Git branch or tag (defaults to repository default branch) |356| `ref` | string | Optional. Git branch or tag (defaults to repository default branch) |

295| `sha` | string | Optional. Full 40-character git commit SHA to pin to an exact version |357| `sha` | string | Optional. Full 40-character git commit SHA to pin to an exact version |

296 358

359### npm packages

360

361Plugins distributed as npm packages are installed using `npm install`. This works with any package on the public npm registry or a private registry your team hosts.

362

363```json theme={null}

364{

365 "name": "my-npm-plugin",

366 "source": {

367 "source": "npm",

368 "package": "@acme/claude-plugin"

369 }

370}

371```

372

373To pin to a specific version, add the `version` field:

374

375```json theme={null}

376{

377 "name": "my-npm-plugin",

378 "source": {

379 "source": "npm",

380 "package": "@acme/claude-plugin",

381 "version": "2.1.0"

382 }

383}

384```

385

386To install from a private or internal registry, add the `registry` field:

387

388```json theme={null}

389{

390 "name": "my-npm-plugin",

391 "source": {

392 "source": "npm",

393 "package": "@acme/claude-plugin",

394 "version": "^2.0.0",

395 "registry": "https://npm.example.com"

396 }

397}

398```

399

400| Field | Type | Description |

401| :--------- | :----- | :------------------------------------------------------------------------------------------- |

402| `package` | string | Required. Package name or scoped package (for example, `@org/plugin`) |

403| `version` | string | Optional. Version or version range (for example, `2.1.0`, `^2.0.0`, `~1.5.0`) |

404| `registry` | string | Optional. Custom npm registry URL. Defaults to the system npm registry (typically npmjs.org) |

405

297### Advanced plugin entries406### Advanced plugin entries

298 407

299This example shows a plugin entry using many of the optional fields, including custom paths for commands, agents, hooks, and MCP servers:408This example shows a plugin entry using many of the optional fields, including custom paths for commands, agents, hooks, and MCP servers:

348Key things to notice:457Key things to notice:

349 458

350* **`commands` and `agents`**: You can specify multiple directories or individual files. Paths are relative to the plugin root.459* **`commands` and `agents`**: You can specify multiple directories or individual files. Paths are relative to the plugin root.

351* **`${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.460* **`${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.

352* **`strict: false`**: Since this is set to false, the plugin doesn't need its own `plugin.json`. The marketplace entry defines everything.461* **`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.

462

463### Strict mode

464

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

466

467| Value | Behavior |

468| :--------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- |

469| `true` (default) | `plugin.json` is the authority. The marketplace entry can supplement it with additional components, and both sources are merged. |

470| `false` | The marketplace entry is the entire definition. If the plugin also has a `plugin.json` that declares components, that's a conflict and the plugin fails to load. |

471

472**When to use each mode:**

473

474* **`strict: true`**: the plugin has its own `plugin.json` and manages its own components. The marketplace entry can add extra commands or hooks on top. This is the default and works for most plugins.

475* **`strict: false`**: the marketplace operator wants full control. The plugin repo provides raw files, and the marketplace entry defines which of those files are exposed as commands, agents, hooks, etc. Useful when the marketplace restructures or curates a plugin's components differently than the plugin author intended.

353 476

354## Host and distribute marketplaces477## Host and distribute marketplaces

355 478

434 557

435For full configuration options, see [Plugin settings](/en/settings#plugin-settings).558For full configuration options, see [Plugin settings](/en/settings#plugin-settings).

436 559

560### Pre-populate plugins for containers

561

562For container images and CI environments, you can pre-populate a plugins directory at build time so Claude Code starts with marketplaces and plugins already available, without cloning anything at runtime. Set the `CLAUDE_CODE_PLUGIN_SEED_DIR` environment variable to point at this directory.

563

564To layer multiple seed directories, separate paths with `:` on Unix or `;` on Windows. Claude Code searches each directory in order, and the first seed that contains a given marketplace or plugin cache wins.

565

566The seed directory mirrors the structure of `~/.claude/plugins`:

567

568```

569$CLAUDE_CODE_PLUGIN_SEED_DIR/

570 known_marketplaces.json

571 marketplaces/<name>/...

572 cache/<marketplace>/<plugin>/<version>/...

573```

574

575The simplest way to build a seed directory is to run Claude Code once during image build, install the plugins you need, then copy the resulting `~/.claude/plugins` directory into your image and point `CLAUDE_CODE_PLUGIN_SEED_DIR` at it.

576

577At startup, Claude Code registers marketplaces found in the seed's `known_marketplaces.json` into the primary configuration, and uses plugin caches found under `cache/` in place without re-cloning. This works in both interactive mode and non-interactive mode with the `-p` flag.

578

579Behavior details:

580

581* **Read-only**: the seed directory is never written to. Auto-updates are disabled for seed marketplaces since git pull would fail on a read-only filesystem.

582* **Seed entries take precedence**: marketplaces declared in the seed overwrite any matching entries in the user's configuration on each startup. To opt out of a seed plugin, use `/plugin disable` rather than removing the marketplace.

583* **Path resolution**: Claude Code locates marketplace content by probing `$CLAUDE_CODE_PLUGIN_SEED_DIR/marketplaces/<name>/` at runtime, not by trusting paths stored inside the seed's JSON. This means the seed works correctly even when mounted at a different path than where it was built.

584* **Composes with settings**: if `extraKnownMarketplaces` or `enabledPlugins` declare a marketplace that already exists in the seed, Claude Code uses the seed copy instead of cloning.

585

437### Managed marketplace restrictions586### Managed marketplace restrictions

438 587

439For organizations requiring strict control over plugin sources, administrators can restrict which plugin marketplaces users are allowed to add using the [`strictKnownMarketplaces`](/en/settings#strictknownmarketplaces) setting in managed settings.588For organizations requiring strict control over plugin sources, administrators can restrict which plugin marketplaces users are allowed to add using the [`strictKnownMarketplaces`](/en/settings#strictknownmarketplaces) setting in managed settings.

478}627}

479```628```

480 629

481Allow all marketplaces from an internal git server using regex pattern matching:630Allow all marketplaces from an internal git server using regex pattern matching on the host:

482 631

483```json theme={null}632```json theme={null}

484{633{

491}640}

492```641```

493 642

643Allow filesystem-based marketplaces from a specific directory using regex pattern matching on the path:

644

645```json theme={null}

646{

647 "strictKnownMarketplaces": [

648 {

649 "source": "pathPattern",

650 "pathPattern": "^/opt/approved/"

651 }

652 ]

653}

654```

655

656Use `".*"` as the `pathPattern` to allow any filesystem path while still controlling network sources with `hostPattern`.

657

658<Note>

659 `strictKnownMarketplaces` restricts what users can add, but does not register marketplaces on its own. To make allowed marketplaces available automatically without users running `/plugin marketplace add`, pair it with [`extraKnownMarketplaces`](/en/settings#extraknownmarketplaces) in the same `managed-settings.json`. See [Using both together](/en/settings#strictknownmarketplaces).

660</Note>

661

494#### How restrictions work662#### How restrictions work

495 663

496Restrictions are validated early in the plugin installation process, before any network requests or filesystem operations occur. This prevents unauthorized marketplace access attempts.664Restrictions are validated early in the plugin installation process, before any network requests or filesystem operations occur. This prevents unauthorized marketplace access attempts.

500* For GitHub sources: `repo` is required, and `ref` or `path` must also match if specified in the allowlist668* For GitHub sources: `repo` is required, and `ref` or `path` must also match if specified in the allowlist

501* For URL sources: the full URL must match exactly669* For URL sources: the full URL must match exactly

502* For `hostPattern` sources: the marketplace host is matched against the regex pattern670* For `hostPattern` sources: the marketplace host is matched against the regex pattern

671* For `pathPattern` sources: the marketplace's filesystem path is matched against the regex pattern

503 672

504Because `strictKnownMarketplaces` is set in [managed settings](/en/settings#settings-files), individual users and project configurations cannot override these restrictions.673Because `strictKnownMarketplaces` is set in [managed settings](/en/settings#settings-files), individual users and project configurations cannot override these restrictions.

505 674

506For complete configuration details including all supported source types and comparison with `extraKnownMarketplaces`, see the [strictKnownMarketplaces reference](/en/settings#strictknownmarketplaces).675For complete configuration details including all supported source types and comparison with `extraKnownMarketplaces`, see the [strictKnownMarketplaces reference](/en/settings#strictknownmarketplaces).

507 676

677### Version resolution and release channels

678

679Plugin versions determine cache paths and update detection. You can specify the version in the plugin manifest (`plugin.json`) or in the marketplace entry (`marketplace.json`).

680

681<Warning>

682 When possible, avoid setting the version in both places. The plugin manifest always wins silently, which can cause the marketplace version to be ignored. For relative-path plugins, set the version in the marketplace entry. For all other plugin sources, set it in the plugin manifest.

683</Warning>

684

685#### Set up release channels

686

687To support "stable" and "latest" release channels for your plugins, you can set up two marketplaces that point to different refs or SHAs of the same repo. You can then assign the two marketplaces to different user groups through [managed settings](/en/settings#settings-files).

688

689<Warning>

690 The plugin's `plugin.json` must declare a different `version` at each pinned ref or commit. If two refs or commits have the same manifest version, Claude Code treats them as identical and skips the update.

691</Warning>

692

693##### Example

694

695```json theme={null}

696{

697 "name": "stable-tools",

698 "plugins": [

699 {

700 "name": "code-formatter",

701 "source": {

702 "source": "github",

703 "repo": "acme-corp/code-formatter",

704 "ref": "stable"

705 }

706 }

707 ]

708}

709```

710

711```json theme={null}

712{

713 "name": "latest-tools",

714 "plugins": [

715 {

716 "name": "code-formatter",

717 "source": {

718 "source": "github",

719 "repo": "acme-corp/code-formatter",

720 "ref": "latest"

721 }

722 }

723 ]

724}

725```

726

727##### Assign channels to user groups

728

729Assign each marketplace to the appropriate user group through managed settings. For example, the stable group receives:

730

731```json theme={null}

732{

733 "extraKnownMarketplaces": {

734 "stable-tools": {

735 "source": {

736 "source": "github",

737 "repo": "acme-corp/stable-tools"

738 }

739 }

740 }

741}

742```

743

744The early-access group receives `latest-tools` instead:

745

746```json theme={null}

747{

748 "extraKnownMarketplaces": {

749 "latest-tools": {

750 "source": {

751 "source": "github",

752 "repo": "acme-corp/latest-tools"

753 }

754 }

755 }

756}

757```

758

508## Validation and testing759## Validation and testing

509 760

510Test your marketplace before sharing.761Test your marketplace before sharing.

545 796

546* Verify the marketplace URL is accessible797* Verify the marketplace URL is accessible

547* Check that `.claude-plugin/marketplace.json` exists at the specified path798* Check that `.claude-plugin/marketplace.json` exists at the specified path

548* Ensure JSON syntax is valid using `claude plugin validate` or `/plugin validate`799* Ensure JSON syntax is valid and frontmatter is well-formed using `claude plugin validate` or `/plugin validate`

549* For private repositories, confirm you have access permissions800* For private repositories, confirm you have access permissions

550 801

551### Marketplace validation errors802### Marketplace validation errors

552 803

553Run `claude plugin validate .` or `/plugin validate .` from your marketplace directory to check for issues. Common errors:804Run `claude plugin validate .` or `/plugin validate .` from your marketplace directory to check for issues. The validator checks `plugin.json`, skill/agent/command frontmatter, and `hooks/hooks.json` for syntax and schema errors. Common errors:

554 805

556| :------------------------------------------------ | :------------------------------ | :------------------------------------------------------------ |807| :------------------------------------------------ | :---------------------------------------------- | :--------------------------------------------------------------------------------------------- |

812| `YAML frontmatter failed to parse: ...` | Invalid YAML in a skill, agent, or command file | Fix the YAML syntax in the frontmatter block. At runtime this file loads with no metadata. |

813| `Invalid JSON syntax: ...` (hooks.json) | Malformed `hooks/hooks.json` | Fix JSON syntax. A malformed `hooks/hooks.json` prevents the entire plugin from loading. |

561 814

562**Warnings** (non-blocking):815**Warnings** (non-blocking):

563 816

564* `Marketplace has no plugins defined`: add at least one plugin to the `plugins` array817* `Marketplace has no plugins defined`: add at least one plugin to the `plugins` array

565* `No marketplace description provided`: add `metadata.description` to help users understand your marketplace818* `No marketplace description provided`: add `metadata.description` to help users understand your marketplace

566* `Plugin "x" uses npm source which is not yet fully implemented`: use `github` or local path sources instead819* `Plugin name "x" is not kebab-case`: the plugin name contains uppercase letters, spaces, or special characters. Rename to lowercase letters, digits, and hyphens only (for example, `my-plugin`). Claude Code accepts other forms, but the Claude.ai marketplace sync rejects them.

567 820

568### Plugin installation failures821### Plugin installation failures

569 822

596* For GitLab, ensure the token has at least `read_repository` scope849* For GitLab, ensure the token has at least `read_repository` scope

597* Verify the token hasn't expired850* Verify the token hasn't expired

598 851

852### Git operations time out

853

854**Symptoms**: Plugin installation or marketplace updates fail with a timeout error like "Git clone timed out after 120s" or "Git pull timed out after 120s".

855

856**Cause**: Claude Code uses a 120-second timeout for all git operations, including cloning plugin repositories and pulling marketplace updates. Large repositories or slow network connections may exceed this limit.

857

858**Solution**: Increase the timeout using the `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` environment variable. The value is in milliseconds:

859

860```bash theme={null}

861export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000 # 5 minutes

862```

863

599### Plugins with relative paths fail in URL-based marketplaces864### Plugins with relative paths fail in URL-based marketplaces

600 865

601**Symptoms**: Added a marketplace via URL (such as `https://example.com/marketplace.json`), but plugins with relative path sources like `"./plugins/my-plugin"` fail to install with "path not found" errors.866**Symptoms**: Added a marketplace via URL (such as `https://example.com/marketplace.json`), but plugins with relative path sources like `"./plugins/my-plugin"` fail to install with "path not found" errors.

plugins.md +39 −15

Details

24* You're customizing Claude Code for a single project24* You're customizing Claude Code for a single project

25* The configuration is personal and doesn't need to be shared25* The configuration is personal and doesn't need to be shared

26* You're experimenting with skills or hooks before packaging them26* You're experimenting with skills or hooks before packaging them

~~27* You want short skill names like `/hello` or `/review`~~27* You want short skill names like `/hello` or `/deploy`

28 28

29**Use plugins when**:29**Use plugins when**:

30 30

122 claude --plugin-dir ./my-first-plugin122 claude --plugin-dir ./my-first-plugin

123 ```123 ```

124 124

125 Once Claude Code starts, try your new command:125 Once Claude Code starts, try your new skill:

126 126

127 ```shell theme={null}127 ```shell theme={null}

128 /my-first-plugin:hello128 /my-first-plugin:hello

129 ```129 ```

130 130

131 You'll see Claude respond with a greeting. Run `/help` to see your command listed under the plugin namespace.131 You'll see Claude respond with a greeting. Run `/help` to see your skill listed under the plugin namespace.

132 132

133 <Note>133 <Note>

134 **Why namespacing?** Plugin skills are always namespaced (like `/greet:hello`) to prevent conflicts when multiple plugins have skills with the same name.134 **Why namespacing?** Plugin skills are always namespaced (like `/my-first-plugin:hello`) to prevent conflicts when multiple plugins have skills with the same name.

135 135

136 To change the namespace prefix, update the `name` field in `plugin.json`.136 To change the namespace prefix, update the `name` field in `plugin.json`.

137 </Note>137 </Note>

140 <Step title="Add skill arguments">140 <Step title="Add skill arguments">

141 Make your skill dynamic by accepting user input. The `$ARGUMENTS` placeholder captures any text the user provides after the skill name.141 Make your skill dynamic by accepting user input. The `$ARGUMENTS` placeholder captures any text the user provides after the skill name.

142 142

143 Update your `hello.md` file:143 Update your `SKILL.md` file:

144 144

145 ```markdown my-first-plugin/commands/hello.md theme={null}145 ```markdown my-first-plugin/skills/hello/SKILL.md theme={null}

146 ---146 ---

147 description: Greet the user with a personalized message147 description: Greet the user with a personalized message

148 ---148 ---

149 149

150 # Hello Command150 # Hello Skill

151 151

152 Greet the user named "$ARGUMENTS" warmly and ask how you can help them today. Make the greeting personal and encouraging.152 Greet the user named "$ARGUMENTS" warmly and ask how you can help them today. Make the greeting personal and encouraging.

153 ```153 ```

154 154

155 Restart Claude Code to pick up the changes, then try the command with your name:155 Run `/reload-plugins` to pick up the changes, then try the skill with your name:

156 156

157 ```shell theme={null}157 ```shell theme={null}

158 /my-first-plugin:hello Alex158 /my-first-plugin:hello Alex

165You've successfully created and tested a plugin with these key components:165You've successfully created and tested a plugin with these key components:

166 166

167* **Plugin manifest** (`.claude-plugin/plugin.json`): describes your plugin's metadata167* **Plugin manifest** (`.claude-plugin/plugin.json`): describes your plugin's metadata

168* **Commands directory** (`commands/`): contains your custom skills168* **Skills directory** (`skills/`): contains your custom skills

169* **Skill arguments** (`$ARGUMENTS`): captures user input for dynamic behavior169* **Skill arguments** (`$ARGUMENTS`): captures user input for dynamic behavior

170 170

171<Tip>171<Tip>

181</Warning>181</Warning>

182 182

184| :---------------- | :---------- | :---------------------------------------------- |184| :---------------- | :---------- | :----------------------------------------------------------------------------- |

192| `settings.json` | Plugin root | Default [settings](/en/settings) applied when the plugin is enabled |

192 193

193<Note>194<Note>

194 **Next steps**: Ready to add more features? Jump to [Develop more complex plugins](#develop-more-complex-plugins) to add agents, hooks, MCP servers, and LSP servers. For complete technical specifications of all plugin components, see [Plugins reference](/en/plugins-reference).195 **Next steps**: Ready to add more features? Jump to [Develop more complex plugins](#develop-more-complex-plugins) to add agents, hooks, MCP servers, and LSP servers. For complete technical specifications of all plugin components, see [Plugins reference](/en/plugins-reference).

204 205

205Add a `skills/` directory at your plugin root with Skill folders containing `SKILL.md` files:206Add a `skills/` directory at your plugin root with Skill folders containing `SKILL.md` files:

206 207

207```208```text theme={null}

208my-plugin/209my-plugin/

209├── .claude-plugin/210├── .claude-plugin/

210│ └── plugin.json211│ └── plugin.json

2284. Test coverage2294. Test coverage

229```230```

230 231

231After installing the plugin, restart Claude Code to load the Skills. For complete Skill authoring guidance including progressive disclosure and tool restrictions, see [Agent Skills](/en/skills).232After installing the plugin, run `/reload-plugins` to load the Skills. For complete Skill authoring guidance including progressive disclosure and tool restrictions, see [Agent Skills](/en/skills).

232 233

233### Add LSP servers to your plugin234### Add LSP servers to your plugin

234 235

254 255

255For complete LSP configuration options, see [LSP servers](/en/plugins-reference#lsp-servers).256For complete LSP configuration options, see [LSP servers](/en/plugins-reference#lsp-servers).

256 257

258### Ship default settings with your plugin

259

260Plugins can include a `settings.json` file at the plugin root to apply default configuration when the plugin is enabled. Currently, only the `agent` key is supported.

261

262Setting `agent` activates one of the plugin's [custom agents](/en/sub-agents) as the main thread, applying its system prompt, tool restrictions, and model. This lets a plugin change how Claude Code behaves by default when enabled.

263

264```json settings.json theme={null}

265{

266 "agent": "security-reviewer"

267}

268```

269

270This example activates the `security-reviewer` agent defined in the plugin's `agents/` directory. Settings from `settings.json` take priority over `settings` declared in `plugin.json`. Unknown keys are silently ignored.

271

257### Organize complex plugins272### Organize complex plugins

258 273

259For plugins with many components, organize your directory structure by functionality. For complete directory layouts and organization patterns, see [Plugin directory structure](/en/plugins-reference#plugin-directory-structure).274For plugins with many components, organize your directory structure by functionality. For complete directory layouts and organization patterns, see [Plugin directory structure](/en/plugins-reference#plugin-directory-structure).

266claude --plugin-dir ./my-plugin281claude --plugin-dir ./my-plugin

267```282```

268 283

269As you make changes to your plugin, restart Claude Code to pick up the updates. Test your plugin components:284When a `--plugin-dir` plugin has the same name as an installed marketplace plugin, the local copy takes precedence for that session. This lets you test changes to a plugin you already have installed without uninstalling it first. Marketplace plugins force-enabled by managed settings are the only exception and cannot be overridden.

285

286As you make changes to your plugin, run `/reload-plugins` to pick up the updates without restarting. This reloads plugins, skills, agents, hooks, plugin MCP servers, and plugin LSP servers. Test your plugin components:

270 287

271* Try your commands with `/command-name`288* Try your skills with `/plugin-name:skill-name`

272* Check that agents appear in `/agents`289* Check that agents appear in `/agents`

273* Verify hooks work as expected290* Verify hooks work as expected

274 291

299 316

300Once your plugin is in a marketplace, others can install it using the instructions in [Discover and install plugins](/en/discover-plugins).317Once your plugin is in a marketplace, others can install it using the instructions in [Discover and install plugins](/en/discover-plugins).

301 318

319### Submit your plugin to the official marketplace

320

321To submit a plugin to the official Anthropic marketplace, use one of the in-app submission forms:

322

323* **Claude.ai**: [claude.ai/settings/plugins/submit](https://claude.ai/settings/plugins/submit)

324* **Console**: [platform.claude.com/plugins/submit](https://platform.claude.com/plugins/submit)

325

302<Note>326<Note>

303 For complete technical specifications, debugging techniques, and distribution strategies, see [Plugins reference](/en/plugins-reference).327 For complete technical specifications, debugging techniques, and distribution strategies, see [Plugins reference](/en/plugins-reference).

304</Note>328</Note>

plugins-reference.md +204 −103

Details

12 12

13This reference provides complete technical specifications for the Claude Code plugin system, including component schemas, CLI commands, and development tools.13This reference provides complete technical specifications for the Claude Code plugin system, including component schemas, CLI commands, and development tools.

14 14

~~15## Plugin components reference~~15A **plugin** is a self-contained directory of components that extends Claude Code with custom functionality. Plugin components include skills, agents, hooks, MCP servers, and LSP servers.

16 16

~~17This section documents the types of components that plugins can provide.~~17## Plugin components reference

18 18

19### Skills19### Skills

20 20

26 26

27**Skill structure**:27**Skill structure**:

28 28

~~29```~~29```text theme={null}

30skills/30skills/

31├── pdf-processor/31├── pdf-processor/

32│ ├── SKILL.md32│ ├── SKILL.md

56 56

57```markdown theme={null}57```markdown theme={null}

58---58---

~~59description: What this agent specializes in~~59name: agent-name

~~60capabilities: ["task1", "task2", "task3"]~~60description: What this agent specializes in and when Claude should invoke it

61model: sonnet

62effort: medium

63maxTurns: 20

64disallowedTools: Write, Edit

61---65---

62 66

~~63# Agent Name~~67Detailed system prompt for the agent describing its role, expertise, and behavior.

~~65Detailed description of the agent's role, expertise, and when Claude should invoke it.~~

~~67## Capabilities~~

~~68- Specific task the agent excels at~~

~~69- Another specialized capability~~

~~70- When to use this agent vs others~~

~~72## Context and examples~~

~~73Provide examples of when this agent should be used and what kinds of problems it solves.~~

74```68```

75 69

70Plugin agents support `name`, `description`, `model`, `effort`, `maxTurns`, `tools`, `disallowedTools`, `skills`, `memory`, `background`, and `isolation` frontmatter fields. The only valid `isolation` value is `"worktree"`. For security reasons, `hooks`, `mcpServers`, and `permissionMode` are not supported for plugin-shipped agents.

76**Integration points**:72**Integration points**:

77 73

78* Agents appear in the `/agents` interface74* Agents appear in the `/agents` interface

80* Agents can be invoked manually by users76* Agents can be invoked manually by users

81* Plugin agents work alongside built-in Claude agents77* Plugin agents work alongside built-in Claude agents

82 78

79For complete details, see [Subagents](/en/sub-agents).

83### Hooks81### Hooks

84 82

85Plugins can provide event handlers that respond to Claude Code events automatically.83Plugins can provide event handlers that respond to Claude Code events automatically.

108}106}

109```107```

110 108

111**Available events**:109Plugin hooks respond to the same lifecycle events as [user-defined hooks](/en/hooks):

~~112~~ 110

113* `PreToolUse`: Before Claude uses any tool111| Event | When it fires |

114* `PostToolUse`: After Claude successfully uses any tool112| :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |

115* `PostToolUseFailure`: After Claude tool execution fails113| `SessionStart` | When a session begins or resumes |

116* `PermissionRequest`: When a permission dialog is shown114| `UserPromptSubmit` | When you submit a prompt, before Claude processes it |

117* `UserPromptSubmit`: When user submits a prompt115| `PreToolUse` | Before a tool call executes. Can block it |

118* `Notification`: When Claude Code sends notifications116| `PermissionRequest` | When a permission dialog appears |

119* `Stop`: When Claude attempts to stop117| `PostToolUse` | After a tool call succeeds |

120* `SubagentStart`: When a subagent is started118| `PostToolUseFailure` | After a tool call fails |

121* `SubagentStop`: When a subagent attempts to stop119| `Notification` | When Claude Code sends a notification |

122* `SessionStart`: At the beginning of sessions120| `SubagentStart` | When a subagent is spawned |

123* `SessionEnd`: At the end of sessions121| `SubagentStop` | When a subagent finishes |

124* `PreCompact`: Before conversation history is compacted122| `TaskCreated` | When a task is being created via `TaskCreate` |

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

124| `Stop` | When Claude finishes responding |

125| `StopFailure` | When the turn ends due to an API error. Output and exit code are ignored |

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

127| `InstructionsLoaded` | When a CLAUDE.md or `.claude/rules/*.md` file is loaded into context. Fires at session start and when files are lazily loaded during a session |

128| `ConfigChange` | When a configuration file changes during a session |

129| `CwdChanged` | When the working directory changes, for example when Claude executes a `cd` command. Useful for reactive environment management with tools like direnv |

130| `FileChanged` | When a watched file changes on disk. The `matcher` field specifies which filenames to watch |

131| `WorktreeCreate` | When a worktree is being created via `--worktree` or `isolation: "worktree"`. Replaces default git behavior |

132| `WorktreeRemove` | When a worktree is being removed, either at session exit or when a subagent finishes |

133| `PreCompact` | Before context compaction |

134| `PostCompact` | After context compaction completes |

135| `Elicitation` | When an MCP server requests user input during a tool call |

136| `ElicitationResult` | After a user responds to an MCP elicitation, before the response is sent back to the server |

137| `SessionEnd` | When a session terminates |

125 138

126**Hook types**:139**Hook types**:

127 140

128* `command`: Execute shell commands or scripts141* `command`: execute shell commands or scripts

129* `prompt`: Evaluate a prompt with an LLM (uses `$ARGUMENTS` placeholder for context)142* `http`: send the event JSON as a POST request to a URL

130* `agent`: Run an agentic verifier with tools for complex verification tasks143* `prompt`: evaluate a prompt with an LLM (uses `$ARGUMENTS` placeholder for context)

144* `agent`: run an agentic verifier with tools for complex verification tasks

131 145

132### MCP servers146### MCP servers

133 147

168### LSP servers182### LSP servers

169 183

170<Tip>184<Tip>

171 Looking to use LSP plugins? Install them from the official marketplace—search for "lsp" in the `/plugin` Discover tab. This section documents how to create LSP plugins for languages not covered by the official marketplace.185 Looking to use LSP plugins? Install them from the official marketplace: search for "lsp" in the `/plugin` Discover tab. This section documents how to create LSP plugins for languages not covered by the official marketplace.

172</Tip>186</Tip>

173 187

174Plugins can provide [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP) servers to give Claude real-time code intelligence while working on your codebase.188Plugins can provide [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) (LSP) servers to give Claude real-time code intelligence while working on your codebase.

257When you install a plugin, you choose a **scope** that determines where the plugin is available and who else can use it:271When you install a plugin, you choose a **scope** that determines where the plugin is available and who else can use it:

258 272

260| :-------- | :---------------------------- | :------------------------------------------------------- |274| :-------- | :---------------------------------------------- | :------------------------------------------------------- |

265 279

266Plugins use the same scope system as other Claude Code configurations. For installation instructions and scope flags, see [Install plugins](/en/discover-plugins#install-plugins). For a complete explanation of scopes, see [Configuration scopes](/en/settings#configuration-scopes).280Plugins use the same scope system as other Claude Code configurations. For installation instructions and scope flags, see [Install plugins](/en/discover-plugins#install-plugins). For a complete explanation of scopes, see [Configuration scopes](/en/settings#configuration-scopes).

267 281

269 283

270## Plugin manifest schema284## Plugin manifest schema

271 285

272The `plugin.json` file defines your plugin's metadata and configuration. This section documents all supported fields and options.286The `.claude-plugin/plugin.json` file defines your plugin's metadata and configuration. This section documents all supported fields and options.

287

288The manifest is optional. If omitted, Claude Code auto-discovers components in [default locations](#file-locations-reference) and derives the plugin name from the directory name. Use a manifest when you need to provide metadata or custom component paths.

273 289

274### Complete schema290### Complete schema

275 291

299 315

300### Required fields316### Required fields

301 317

318If you include a manifest, `name` is the only required field.

319

303| :----- | :----- | :---------------------------------------- | :------------------- |321| :----- | :----- | :---------------------------------------- | :------------------- |

305 323

324This name is used for namespacing components. For example, in the UI, the

325agent `agent-creator` for the plugin with name `plugin-dev` will appear as

326`plugin-dev:agent-creator`.

327

306### Metadata fields328### Metadata fields

307 329

309| :------------ | :----- | :---------------------------------- | :------------------------------------------------- |331| :------------ | :----- | :-------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------- |

312| `author` | object | Author information | `{"name": "Dev Team", "email": "dev@company.com"}` |334| `author` | object | Author information | `{"name": "Dev Team", "email": "dev@company.com"}` |

318### Component path fields340### Component path fields

319 341

321| :------------- | :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------- |343| :------------- | :-------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------- |

353

354### User configuration

355

356The `userConfig` field declares values that Claude Code prompts the user for when the plugin is enabled. Use this instead of requiring users to hand-edit `settings.json`.

357

358```json theme={null}

359{

360 "userConfig": {

361 "api_endpoint": {

362 "description": "Your team's API endpoint",

363 "sensitive": false

364 },

365 "api_token": {

366 "description": "API authentication token",

367 "sensitive": true

368 }

369 }

370}

371```

372

373Keys must be valid identifiers. Each value is available for substitution as `${user_config.KEY}` in MCP and LSP server configs, hook commands, and (for non-sensitive values only) skill and agent content. Values are also exported to plugin subprocesses as `CLAUDE_PLUGIN_OPTION_<KEY>` environment variables.

374

375Non-sensitive values are stored in `settings.json` under `pluginConfigs[<plugin-id>].options`. Sensitive values go to the system keychain (or `~/.claude/.credentials.json` where the keychain is unavailable). Keychain storage is shared with OAuth tokens and has an approximately 2 KB total limit, so keep sensitive values small.

376

377### Channels

378

379The `channels` field lets a plugin declare one or more message channels that inject content into the conversation. Each channel binds to an MCP server that the plugin provides.

380

381```json theme={null}

382{

383 "channels": [

384 {

385 "server": "telegram",

386 "userConfig": {

387 "bot_token": { "description": "Telegram bot token", "sensitive": true },

388 "owner_id": { "description": "Your Telegram user ID", "sensitive": false }

389 }

390 }

391 ]

392}

393```

394

395The `server` field is required and must match a key in the plugin's `mcpServers`. The optional per-channel `userConfig` uses the same schema as the top-level field, letting the plugin prompt for bot tokens or owner IDs when the plugin is enabled.

329 396

330### Path behavior rules397### Path behavior rules

331 398

332**Important**: Custom paths supplement default directories - they don't replace them.399For `commands`, `agents`, `skills`, and `outputStyles`, custom paths replace the default directory. If the manifest specifies `commands`, the default `commands/` directory is not scanned. [Hooks](#hooks), [MCP servers](#mcp-servers), and [LSP servers](#lsp-servers) have different semantics for handling multiple sources.

333 400

334* If `commands/` exists, it's loaded in addition to custom command paths401* All paths must be relative to the plugin root and start with `./`

335* All paths must be relative to plugin root and start with `./`402* Components from custom paths use the same naming and namespacing rules

336* Commands from custom paths use the same naming and namespacing rules403* Multiple paths can be specified as arrays

337* Multiple paths can be specified as arrays for flexibility404* To keep the default directory and add more paths for commands, agents, skills, or output styles, include the default in your array: `"commands": ["./commands/", "./extras/deploy.md"]`

338 405

339**Path examples**:406**Path examples**:

340 407

353 420

354### Environment variables421### Environment variables

355 422

356**`${CLAUDE_PLUGIN_ROOT}`**: Contains the absolute path to your plugin directory. Use this in hooks, MCP servers, and scripts to ensure correct paths regardless of installation location.423Claude Code provides two variables for referencing plugin paths. Both are substituted inline anywhere they appear in skill content, agent content, hook commands, and MCP or LSP server configs. Both are also exported as environment variables to hook processes and MCP or LSP server subprocesses.

424

425**`${CLAUDE_PLUGIN_ROOT}`**: the absolute path to your plugin's installation directory. Use this to reference scripts, binaries, and config files bundled with the plugin. This path changes when the plugin updates, so files you write here do not survive an update.

426

427**`${CLAUDE_PLUGIN_DATA}`**: a persistent directory for plugin state that survives updates. Use this for installed dependencies such as `node_modules` or Python virtual environments, generated code, caches, and any other files that should persist across plugin versions. The directory is created automatically the first time this variable is referenced.

357 428

358```json theme={null}429```json theme={null}

359{430{

372}443}

373```444```

374 445

375***446#### Persistent data directory

376 447

377## Plugin caching and file resolution448The `${CLAUDE_PLUGIN_DATA}` directory resolves to `~/.claude/plugins/data/{id}/`, where `{id}` is the plugin identifier with characters outside `a-z`, `A-Z`, `0-9`, `_`, and `-` replaced by `-`. For a plugin installed as `formatter@my-marketplace`, the directory is `~/.claude/plugins/data/formatter-my-marketplace/`.

378 449

379For security and verification purposes, Claude Code copies plugins to a cache directory rather than using them in-place. Understanding this behavior is important when developing plugins that reference external files.450A common use is installing language dependencies once and reusing them across sessions and plugin updates. Because the data directory outlives any single plugin version, a check for directory existence alone cannot detect when an update changes the plugin's dependency manifest. The recommended pattern compares the bundled manifest against a copy in the data directory and reinstalls when they differ.

380 451

381### How plugin caching works452This `SessionStart` hook installs `node_modules` on the first run and again whenever a plugin update includes a changed `package.json`:

382 453

383When you install a plugin, Claude Code copies the plugin files to a cache directory:454```json theme={null}

455{

456 "hooks": {

457 "SessionStart": [

458 {

459 "hooks": [

460 {

461 "type": "command",

462 "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""

463 }

464 ]

465 }

466 ]

467 }

468}

469```

384 470

385* **For marketplace plugins with relative paths**: The path specified in the `source` field is copied recursively. For example, if your marketplace entry specifies `"source": "./plugins/my-plugin"`, the entire `./plugins` directory is copied.471The `diff` exits nonzero when the stored copy is missing or differs from the bundled one, covering both first run and dependency-changing updates. If `npm install` fails, the trailing `rm` removes the copied manifest so the next session retries.

386* **For plugins with `.claude-plugin/plugin.json`**: The implicit root directory (the directory containing `.claude-plugin/plugin.json`) is copied recursively.

387 472

388### Path traversal limitations473Scripts bundled in `${CLAUDE_PLUGIN_ROOT}` can then run against the persisted `node_modules`:

389 474

390Plugins cannot reference files outside their copied directory structure. Paths that traverse outside the plugin root (such as `../shared-utils`) will not work after installation because those external files are not copied to the cache.475```json theme={null}

476{

477 "mcpServers": {

478 "routines": {

479 "command": "node",

480 "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],

481 "env": {

482 "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"

483 }

484 }

485 }

486}

487```

391 488

392### Working with external dependencies489The data directory is deleted automatically when you uninstall the plugin from the last scope where it is installed. The `/plugin` interface shows the directory size and prompts before deleting. The CLI deletes by default; pass [`--keep-data`](#plugin-uninstall) to preserve it.

393 490

394If your plugin needs to access files outside its directory, you have two options:491***

395 492

396**Option 1: Use symlinks**493## Plugin caching and file resolution

397 494

398Create symbolic links to external files within your plugin directory. Symlinks are honored during the copy process:495Plugins are specified in one of two ways:

399 496

400```bash theme={null}497* Through `claude --plugin-dir`, for the duration of a session.

401# Inside your plugin directory498* Through a marketplace, installed for future sessions.

402ln -s /path/to/shared-utils ./shared-utils

403```

404 499

405The symlinked content will be copied into the plugin cache.500For security and verification purposes, Claude Code copies *marketplace* plugins to the user's local **plugin cache** (`~/.claude/plugins/cache`) rather than using them in-place. Understanding this behavior is important when developing plugins that reference external files.

406 501

407**Option 2: Restructure your marketplace**502### Path traversal limitations

408 503

409Set the plugin path to a parent directory that contains all required files, then provide the rest of the plugin manifest directly in the marketplace entry:504Installed plugins cannot reference files outside their directory. Paths that traverse outside the plugin root (such as `../shared-utils`) will not work after installation because those external files are not copied to the cache.

410 505

411```json theme={null}506### Working with external dependencies

412{507

413 "name": "my-plugin",508If your plugin needs to access files outside its directory, you can create symbolic links to external files within your plugin directory. Symlinks are honored during the copy process:

414 "source": "./",

415 "description": "Plugin that needs root-level access",

416 "commands": ["./plugins/my-plugin/commands/"],

417 "agents": ["./plugins/my-plugin/agents/"],

418 "strict": false

419}

420```

421 509

422This approach copies the entire marketplace root, giving your plugin access to sibling directories.510```bash theme={null}

511# Inside your plugin directory

512ln -s /path/to/shared-utils ./shared-utils

513```

423 514

424<Note>515The symlinked content will be copied into the plugin cache. This provides flexibility while maintaining the security benefits of the caching system.

425 Symlinks that point to locations outside the plugin's logical root are followed during copying. This provides flexibility while maintaining the security benefits of the caching system.

426</Note>

427 516

428***517***

429 518

433 522

434A complete plugin follows this structure:523A complete plugin follows this structure:

435 524

436```525```text theme={null}

437enterprise-plugin/526enterprise-plugin/

438├── .claude-plugin/ # Metadata directory527├── .claude-plugin/ # Metadata directory (optional)

439│ └── plugin.json # Required: plugin manifest528│ └── plugin.json # plugin manifest

440├── commands/ # Default command location529├── commands/ # Default command location

441│ ├── status.md530│ ├── status.md

442│ └── logs.md531│ └── logs.md

450│ └── pdf-processor/539│ └── pdf-processor/

451│ ├── SKILL.md540│ ├── SKILL.md

452│ └── scripts/541│ └── scripts/

542├── output-styles/ # Output style definitions

543│ └── terse.md

453├── hooks/ # Hook configurations544├── hooks/ # Hook configurations

454│ ├── hooks.json # Main hook config545│ ├── hooks.json # Main hook config

455│ └── security-hooks.json # Additional hooks546│ └── security-hooks.json # Additional hooks

547├── settings.json # Default settings for the plugin

456├── .mcp.json # MCP server definitions548├── .mcp.json # MCP server definitions

457├── .lsp.json # LSP server configurations549├── .lsp.json # LSP server configurations

458├── scripts/ # Hook and utility scripts550├── scripts/ # Hook and utility scripts

464```556```

465 557

466<Warning>558<Warning>

467 The `.claude-plugin/` directory contains the `plugin.json` file. All other directories (commands/, agents/, skills/, hooks/) must be at the plugin root, not inside `.claude-plugin/`.559 The `.claude-plugin/` directory contains the `plugin.json` file. All other directories (commands/, agents/, skills/, output-styles/, hooks/) must be at the plugin root, not inside `.claude-plugin/`.

468</Warning>560</Warning>

469 561

470### File locations reference562### File locations reference

471 563

473| :-------------- | :--------------------------- | :---------------------------------------------------------- |565| :---------------- | :--------------------------- | :------------------------------------------------------------------------------------------------------------------------ |

570| **Output styles** | `output-styles/` | Output style definitions |

574| **Settings** | `settings.json` | Default configuration applied when the plugin is enabled. Only [`agent`](/en/sub-agents) settings are currently supported |

481 575

482***576***

483 577

506 600

601Scope determines which settings file the installed plugin is added to. For example, --scope project writes to `enabledPlugins` in .claude/settings.json, making the plugin available to everyone who clones the project repository.

602

507**Examples:**603**Examples:**

508 604

509```bash theme={null}605```bash theme={null}

532**Options:**628**Options:**

533 629

535| :-------------------- | :-------------------------------------------------- | :------ |631| :-------------------- | :---------------------------------------------------------------------------- | :------ |

633| `--keep-data` | Preserve the plugin's [persistent data directory](#persistent-data-directory) | |

538 635

539**Aliases:** `remove`, `rm`636**Aliases:** `remove`, `rm`

540 637

638By default, uninstalling from the last remaining scope also deletes the plugin's `${CLAUDE_PLUGIN_DATA}` directory. Use `--keep-data` to preserve it, for example when reinstalling after testing a new version.

639

541### plugin enable640### plugin enable

542 641

543Enable a disabled plugin.642Enable a disabled plugin.

603 702

604Use `claude --debug` to see plugin loading details:703Use `claude --debug` to see plugin loading details:

605 704

606```bash theme={null}

607claude --debug

608```

~~609~~

610This shows:705This shows:

611 706

612* Which plugins are being loaded707* Which plugins are being loaded

617### Common issues712### Common issues

618 713

620| :---------------------------------- | :------------------------------ | :-------------------------------------------------------------------------------- |715| :---------------------------------- | :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- |

624| MCP server fails | Missing `${CLAUDE_PLUGIN_ROOT}` | Use variable for all plugin paths |719| MCP server fails | Missing `${CLAUDE_PLUGIN_ROOT}` | Use variable for all plugin paths |

637 732

638* `Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories.`: command path exists but contains no valid command files733* `Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories.`: command path exists but contains no valid command files

639* `Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path.`: the `source` path in marketplace.json points to a non-existent directory734* `Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path.`: the `source` path in marketplace.json points to a non-existent directory

640* `Plugin my-plugin has conflicting manifests: both plugin.json and marketplace entry specify components.`: remove duplicate component definitions or set `strict: true` in marketplace entry735* `Plugin my-plugin has conflicting manifests: both plugin.json and marketplace entry specify components.`: remove duplicate component definitions or remove `strict: false` in marketplace entry

641 736

642### Hook troubleshooting737### Hook troubleshooting

643 738

652 747

6531. Verify the event name is correct (case-sensitive): `PostToolUse`, not `postToolUse`7481. Verify the event name is correct (case-sensitive): `PostToolUse`, not `postToolUse`

6542. Check the matcher pattern matches your tools: `"matcher": "Write|Edit"` for file operations7492. Check the matcher pattern matches your tools: `"matcher": "Write|Edit"` for file operations

6553. Confirm the hook type is valid: `command`, `prompt`, or `agent`7503. Confirm the hook type is valid: `command`, `http`, `prompt`, or `agent`

656 751

657### MCP server troubleshooting752### MCP server troubleshooting

658 753

675 770

676**Correct structure**: Components must be at the plugin root, not inside `.claude-plugin/`. Only `plugin.json` belongs in `.claude-plugin/`.771**Correct structure**: Components must be at the plugin root, not inside `.claude-plugin/`. Only `plugin.json` belongs in `.claude-plugin/`.

677 772

678```773```text theme={null}

679my-plugin/774my-plugin/

680├── .claude-plugin/775├── .claude-plugin/

681│ └── plugin.json ← Only manifest here776│ └── plugin.json ← Only manifest here

720* Document changes in a `CHANGELOG.md` file815* Document changes in a `CHANGELOG.md` file

721* Use pre-release versions like `2.0.0-beta.1` for testing816* Use pre-release versions like `2.0.0-beta.1` for testing

722 817

818<Warning>

819 Claude Code uses the version to determine whether to update your plugin. If you change your plugin's code but don't bump the version in `plugin.json`, your plugin's existing users won't see your changes due to caching.

820

821 If your plugin is within a [marketplace](/en/plugin-marketplaces) directory, you can manage the version through `marketplace.json` instead and omit the `version` field from `plugin.json`.

822</Warning>

823

723***824***

724 825

725## See also826## See also

quickstart.md +36 −29

Details

6 6

7> Welcome to Claude Code!7> Welcome to Claude Code!

8 8

~~9This quickstart guide will have you using AI-powered coding assistance in just a few minutes. By the end, you'll understand how to use Claude Code for common development tasks.~~9

11This quickstart guide will have you using AI-powered coding assistance in a few minutes. By the end, you'll understand how to use Claude Code for common development tasks.

13<Experiment flag="quickstart-install-configurator" treatment={<InstallConfigurator />} />

10 14

11## Before you begin15## Before you begin

12 16

13Make sure you have:17Make sure you have:

14 18

15* A terminal or command prompt open19* A terminal or command prompt open

20 * If you've never used the terminal before, check out the [terminal guide](/en/terminal-guide)

16* A code project to work with21* A code project to work with

17* A [Claude subscription](https://claude.com/pricing) (Pro, Max, Teams, or Enterprise), [Claude Console](https://console.anthropic.com/) account, or access through a [supported cloud provider](/en/third-party-integrations)22* A [Claude subscription](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=quickstart_prereq) (Pro, Max, Teams, or Enterprise), [Claude Console](https://console.anthropic.com/) account, or access through a [supported cloud provider](/en/third-party-integrations)

18 23

19<Note>24<Note>

20 This guide covers the terminal CLI. Claude Code is also available on the [web](https://claude.ai/code), as a [desktop app](/en/desktop), in [VS Code](/en/vs-code) and [JetBrains IDEs](/en/jetbrains), in [Slack](/en/slack), and in CI/CD with [GitHub Actions](/en/github-actions) and [GitLab](/en/gitlab-ci-cd). See [all interfaces](/en/overview#use-claude-code-everywhere).25 This guide covers the terminal CLI. Claude Code is also available on the [web](https://claude.ai/code), as a [desktop app](/en/desktop), in [VS Code](/en/vs-code) and [JetBrains IDEs](/en/jetbrains), in [Slack](/en/slack), and in CI/CD with [GitHub Actions](/en/github-actions) and [GitLab](/en/gitlab-ci-cd). See [all interfaces](/en/overview#use-claude-code-everywhere).

44 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd49 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

45 ```50 ```

46 51

52 **Windows requires [Git for Windows](https://git-scm.com/downloads/win).** Install it first if you don't have it.

47 <Info>54 <Info>

48 Native installations automatically update in the background to keep you on the latest version.55 Native installations automatically update in the background to keep you on the latest version.

49 </Info>56 </Info>

50 </Tab>57 </Tab>

51 58

52 <Tab title="Homebrew">59 <Tab title="Homebrew">

~~53 ```sh theme={null}~~60 ```bash theme={null}

54 brew install --cask claude-code61 brew install --cask claude-code

55 ```62 ```

56 63

86 93

87You can log in using any of these account types:94You can log in using any of these account types:

88 95

~~89* [Claude Pro, Max, Teams, or Enterprise](https://claude.com/pricing) (recommended)~~96* [Claude Pro, Max, Teams, or Enterprise](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=quickstart_login) (recommended)

90* [Claude Console](https://console.anthropic.com/) (API access with pre-paid credits). On first login, a "Claude Code" workspace is automatically created in the Console for centralized cost tracking.97* [Claude Console](https://console.anthropic.com/) (API access with pre-paid credits). On first login, a "Claude Code" workspace is automatically created in the Console for centralized cost tracking.

91* [Amazon Bedrock, Google Vertex AI, or Microsoft Foundry](/en/third-party-integrations) (enterprise cloud providers)98* [Amazon Bedrock, Google Vertex AI, or Microsoft Foundry](/en/third-party-integrations) (enterprise cloud providers)

92 99

104You'll see the Claude Code welcome screen with your session information, recent conversations, and latest updates. Type `/help` for available commands or `/resume` to continue a previous conversation.111You'll see the Claude Code welcome screen with your session information, recent conversations, and latest updates. Type `/help` for available commands or `/resume` to continue a previous conversation.

105 112

106<Tip>113<Tip>

107 After logging in (Step 2), your credentials are stored on your system. Learn more in [Credential Management](/en/iam#credential-management).114 After logging in (Step 2), your credentials are stored on your system. Learn more in [Credential Management](/en/authentication#credential-management).

108</Tip>115</Tip>

109 116

110## Step 4: Ask your first question117## Step 4: Ask your first question

111 118

112Let's start with understanding your codebase. Try one of these commands:119Let's start with understanding your codebase. Try one of these commands:

113 120

114```121```text theme={null}

115what does this project do?122what does this project do?

116```123```

117 124

118Claude will analyze your files and provide a summary. You can also ask more specific questions:125Claude will analyze your files and provide a summary. You can also ask more specific questions:

119 126

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

121what technologies does this project use?128what technologies does this project use?

122```129```

123 130

124```131```text theme={null}

125where is the main entry point?132where is the main entry point?

126```133```

127 134

128```135```text theme={null}

129explain the folder structure136explain the folder structure

130```137```

131 138

132You can also ask Claude about its own capabilities:139You can also ask Claude about its own capabilities:

133 140

134```141```text theme={null}

135what can Claude Code do?142what can Claude Code do?

136```143```

137 144

138```145```text theme={null}

139how do I create custom skills in Claude Code?146how do I create custom skills in Claude Code?

140```147```

141 148

142```149```text theme={null}

143can Claude Code work with Docker?150can Claude Code work with Docker?

144```151```

145 152

146<Note>153<Note>

147 Claude Code reads your files as needed - you don't have to manually add context. Claude also has access to its own documentation and can answer questions about its features and capabilities.154 Claude Code reads your project files as needed. You don't have to manually add context.

148</Note>155</Note>

149 156

150## Step 5: Make your first code change157## Step 5: Make your first code change

151 158

152Now let's make Claude Code do some actual coding. Try a simple task:159Now let's make Claude Code do some actual coding. Try a simple task:

153 160

154```161```text theme={null}

155add a hello world function to the main file162add a hello world function to the main file

156```163```

157 164

170 177

171Claude Code makes Git operations conversational:178Claude Code makes Git operations conversational:

172 179

173```180```text theme={null}

174what files have I changed?181what files have I changed?

175```182```

176 183

177```184```text theme={null}

178commit my changes with a descriptive message185commit my changes with a descriptive message

179```186```

180 187

181You can also prompt for more complex Git operations:188You can also prompt for more complex Git operations:

182 189

183```190```text theme={null}

184create a new branch called feature/quickstart191create a new branch called feature/quickstart

185```192```

186 193

187```194```text theme={null}

188show me the last 5 commits195show me the last 5 commits

189```196```

190 197

191```198```text theme={null}

192help me resolve merge conflicts199help me resolve merge conflicts

193```200```

194 201

198 205

199Describe what you want in natural language:206Describe what you want in natural language:

200 207

201```208```text theme={null}

202add input validation to the user registration form209add input validation to the user registration form

203```210```

204 211

205Or fix existing issues:212Or fix existing issues:

206 213

207```214```text theme={null}

208there's a bug where users can submit empty forms - fix it215there's a bug where users can submit empty forms - fix it

209```216```

210 217

221 228

222**Refactor code**229**Refactor code**

223 230

224```231```text theme={null}

225refactor the authentication module to use async/await instead of callbacks232refactor the authentication module to use async/await instead of callbacks

226```233```

227 234

228**Write tests**235**Write tests**

229 236

230```237```text theme={null}

231write unit tests for the calculator functions238write unit tests for the calculator functions

232```239```

233 240

234**Update documentation**241**Update documentation**

235 242

236```243```text theme={null}

237update the README with installation instructions244update the README with installation instructions

238```245```

239 246

240**Code review**247**Code review**

241 248

242```249```text theme={null}

243review my changes and suggest improvements250review my changes and suggest improvements

244```251```

245 252

246<Tip>253<Tip>

247 **Remember**: Claude Code is your AI pair programmer. Talk to it like you would a helpful colleague - describe what you want to achieve, and it will help you get there.254 Talk to Claude like you would a helpful colleague. Describe what you want to achieve, and it will help you get there.

248</Tip>255</Tip>

249 256

250## Essential commands257## Essential commands

279 <Accordion title="Use step-by-step instructions">286 <Accordion title="Use step-by-step instructions">

280 Break complex tasks into steps:287 Break complex tasks into steps:

281 288

282 ```289 ```text theme={null}

283 1. create a new database table for user profiles290 1. create a new database table for user profiles

284 2. create an API endpoint to get and update user profiles291 2. create an API endpoint to get and update user profiles

285 3. build a webpage that allows users to see and edit their information292 3. build a webpage that allows users to see and edit their information

289 <Accordion title="Let Claude explore first">296 <Accordion title="Let Claude explore first">

290 Before making changes, let Claude understand your code:297 Before making changes, let Claude understand your code:

291 298

292 ```299 ```text theme={null}

293 analyze the database schema300 analyze the database schema

294 ```301 ```

295 302

296 ```303 ```text theme={null}

297 build a dashboard showing products that are most frequently returned by our UK customers304 build a dashboard showing products that are most frequently returned by our UK customers

298 ```305 ```

299 </Accordion>306 </Accordion>

remote-control.md +203 −0 added

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# Continue local sessions from any device with Remote Control

7> Continue a local Claude Code session from your phone, tablet, or any browser using Remote Control. Works with claude.ai/code and the Claude mobile app.

9<Note>

10 Remote Control is available on all plans. On Team and Enterprise, it is off by default until an admin enables the Remote Control toggle in [Claude Code admin settings](https://claude.ai/admin-settings/claude-code).

11</Note>

13Remote Control connects [claude.ai/code](https://claude.ai/code) or the Claude app for [iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) and [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude) to a Claude Code session running on your machine. Start a task at your desk, then pick it up from your phone on the couch or a browser on another computer.

15When you start a Remote Control session on your machine, Claude keeps running locally the entire time, so nothing moves to the cloud. With Remote Control you can:

17* **Use your full local environment remotely**: your filesystem, [MCP servers](/en/mcp), tools, and project configuration all stay available

18* **Work from both surfaces at once**: the conversation stays in sync across all connected devices, so you can send messages from your terminal, browser, and phone interchangeably

19* **Survive interruptions**: if your laptop sleeps or your network drops, the session reconnects automatically when your machine comes back online

21Unlike [Claude Code on the web](/en/claude-code-on-the-web), which runs on cloud infrastructure, Remote Control sessions run directly on your machine and interact with your local filesystem. The web and mobile interfaces are just a window into that local session.

23<Note>

24 Remote Control requires Claude Code v2.1.51 or later. Check your version with `claude --version`.

25</Note>

27This page covers setup, how to start and connect to sessions, and how Remote Control compares to Claude Code on the web.

29## Requirements

31Before using Remote Control, confirm that your environment meets these conditions:

33* **Subscription**: available on Pro, Max, Team, and Enterprise plans. API keys are not supported. On Team and Enterprise, an admin must first enable the Remote Control toggle in [Claude Code admin settings](https://claude.ai/admin-settings/claude-code).

34* **Authentication**: run `claude` and use `/login` to sign in through claude.ai if you haven't already.

35* **Workspace trust**: run `claude` in your project directory at least once to accept the workspace trust dialog.

37## Start a Remote Control session

39You can start a dedicated Remote Control server, start an interactive session with Remote Control enabled, or connect a session that's already running.

41<Tabs>

42 <Tab title="Server mode">

43 Navigate to your project directory and run:

45 ```bash theme={null}

46 claude remote-control

47 ```

49 The process stays running in your terminal in server mode, waiting for remote connections. It displays a session URL you can use to [connect from another device](#connect-from-another-device), and you can press spacebar to show a QR code for quick access from your phone. While a remote session is active, the terminal shows connection status and tool activity.

51 Available flags:

53 | Flag | Description |

54 | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

55 | `--name "My Project"` | Set a custom session title visible in the session list at claude.ai/code. |

56 | `--spawn <mode>` | How concurrent sessions are created. Press `w` at runtime to toggle. • `same-dir` (default): all sessions share the current working directory, so they can conflict if editing the same files. • `worktree`: each on-demand session gets its own [git worktree](/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees). Requires a git repository. |

57 | `--capacity <N>` | Maximum number of concurrent sessions. Default is 32. |

58 | `--verbose` | Show detailed connection and session logs. |

59 | `--sandbox` / `--no-sandbox` | Enable or disable [sandboxing](/en/sandboxing) for filesystem and network isolation. Off by default. |

60 </Tab>

62 <Tab title="Interactive session">

63 To start a normal interactive Claude Code session with Remote Control enabled, use the `--remote-control` flag (or `--rc`):

65 ```bash theme={null}

66 claude --remote-control

67 ```

69 Optionally pass a name for the session:

71 ```bash theme={null}

72 claude --remote-control "My Project"

73 ```

75 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 </Tab>

78 <Tab title="From an existing session">

79 If you're already in a Claude Code session and want to continue it remotely, use the `/remote-control` (or `/rc`) command:

81 ```text theme={null}

82 /remote-control

83 ```

85 Pass a name as an argument to set a custom session title:

87 ```text theme={null}

88 /remote-control My Project

89 ```

91 This starts a Remote Control session that carries over your current conversation history and displays a session URL and QR code you can use to [connect from another device](#connect-from-another-device). The `--verbose`, `--sandbox`, and `--no-sandbox` flags are not available with this command.

92 </Tab>

93</Tabs>

95### Connect from another device

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

99* **Open the session URL** in any browser to go directly to the session on [claude.ai/code](https://claude.ai/code). Both `claude remote-control` and `/remote-control` display this URL in the terminal.

100* **Scan the QR code** shown alongside the session URL to open it directly in the Claude app. With `claude remote-control`, press spacebar to toggle the QR code display.

101* **Open [claude.ai/code](https://claude.ai/code) or the Claude app** and find the session by name in the session list. Remote Control sessions show a computer icon with a green status dot when online.

102

103The remote session title is chosen in this order:

104

1051. The name you passed to `--name`, `--remote-control`, or `/remote-control`

1062. The title you set with `/rename`

1073. The last meaningful message in existing conversation history

1084. Your first prompt once you send one

109

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

111

112If you don't have the Claude app yet, use the `/mobile` command inside Claude Code to display a download QR code for [iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) or [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude).

113

114### Enable Remote Control for all sessions

115

116By default, Remote Control only activates when you explicitly run `claude remote-control`, `claude --remote-control`, or `/remote-control`. To enable it automatically for every interactive session, run `/config` inside Claude Code and set **Enable Remote Control for all sessions** to `true`. Set it back to `false` to disable.

117

118With this setting on, each interactive Claude Code process registers one remote session. If you run multiple instances, each one gets its own environment and session. To run multiple concurrent sessions from a single process, use server mode with `--spawn` instead.

119

120## Connection and security

121

122Your local Claude Code session makes outbound HTTPS requests only and never opens inbound ports on your machine. When you start Remote Control, it registers with the Anthropic API and polls for work. When you connect from another device, the server routes messages between the web or mobile client and your local session over a streaming connection.

123

124All traffic travels through the Anthropic API over TLS, the same transport security as any Claude Code session. The connection uses multiple short-lived credentials, each scoped to a single purpose and expiring independently.

125

126## Remote Control vs Claude Code on the web

127

128Remote Control and [Claude Code on the web](/en/claude-code-on-the-web) both use the claude.ai/code interface. The key difference is where the session runs: Remote Control executes on your machine, so your local MCP servers, tools, and project configuration stay available. Claude Code on the web executes in Anthropic-managed cloud infrastructure.

129

130Use Remote Control when you're in the middle of local work and want to keep going from another device. Use Claude Code on the web when you want to kick off a task without any local setup, work on a repo you don't have cloned, or run multiple tasks in parallel.

131

132## Limitations

133

134* **One remote session per interactive process**: outside of server mode, each Claude Code instance supports one remote session at a time. Use server mode with `--spawn` to run multiple concurrent sessions from a single process.

135* **Terminal must stay open**: Remote Control runs as a local process. If you close the terminal or stop the `claude` process, the session ends. Run `claude remote-control` again to start a new one.

136* **Extended network outage**: if your machine is awake but unable to reach the network for more than roughly 10 minutes, the session times out and the process exits. Run `claude remote-control` again to start a new session.

137

138## Troubleshooting

139

140### "Remote Control requires a claude.ai subscription"

141

142You're not authenticated with a claude.ai account. Run `claude auth login` and choose the claude.ai option. If `ANTHROPIC_API_KEY` is set in your environment, unset it first.

143

144### "Remote Control requires a full-scope login token"

145

146You're authenticated with a long-lived token from `claude setup-token` or the `CLAUDE_CODE_OAUTH_TOKEN` environment variable. These tokens are limited to inference-only and cannot establish Remote Control sessions. Run `claude auth login` to authenticate with a full-scope session token instead.

147

148### "Unable to determine your organization for Remote Control eligibility"

149

150Your cached account information is stale or incomplete. Run `claude auth login` to refresh it.

151

152### "Remote Control is not yet enabled for your account"

153

154The eligibility check can fail with certain environment variables present:

155

156* `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` or `DISABLE_TELEMETRY`: unset them and try again.

157* `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.

158

159If none of these are set, run `/logout` then `/login` to refresh.

160

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

162

163This error has three distinct causes. Run `/status` first to see which login method and subscription you're using.

164

165* **You're authenticated with an API key or Console account**: Remote Control requires claude.ai OAuth. Run `/login` and choose the claude.ai option. If `ANTHROPIC_API_KEY` is set in your environment, unset it.

166* **Your Team or Enterprise admin hasn't enabled it**: Remote Control is off by default on these plans. An admin can enable it at [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) by turning on the **Remote Control** toggle. This is a server-side organization setting, not a [managed settings](/en/permissions#managed-only-settings) key.

167* **The admin toggle is grayed out**: your organization has a data retention or compliance configuration that is incompatible with Remote Control. This cannot be changed from the admin panel. Contact Anthropic support to discuss options.

168

169### "Remote credentials fetch failed"

170

171Claude Code could not obtain a short-lived credential from the Anthropic API to establish the connection. Re-run with `--verbose` to see the full error:

172

173```bash theme={null}

174claude remote-control --verbose

175```

176

177Common causes:

178

179* Not signed in: run `claude` and use `/login` to authenticate with your claude.ai account. API key authentication is not supported for Remote Control.

180* Network or proxy issue: a firewall or proxy may be blocking the outbound HTTPS request. Remote Control requires access to the Anthropic API on port 443.

181* Session creation failed: if you also see `Session creation failed — see debug log`, the failure happened earlier in setup. Check that your subscription is active.

182

183## Choose the right approach

184

185Claude Code offers several ways to work when you're not at your terminal. They differ in what triggers the work, where Claude runs, and how much you need to set up.

186

188| :--------------------------------------------- | :--------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------ |

194

195## Related resources

196

197* [Claude Code on the web](/en/claude-code-on-the-web): run sessions in Anthropic-managed cloud environments instead of on your machine

198* [Channels](/en/channels): forward Telegram, Discord, or iMessage into a session so Claude reacts to messages while you're away

199* [Dispatch](/en/desktop#sessions-from-dispatch): message a task from your phone and it can spawn a Desktop session to handle it

200* [Authentication](/en/authentication): set up `/login` and manage credentials for claude.ai

201* [CLI reference](/en/cli-reference): full list of flags and commands including `claude remote-control`

202* [Security](/en/security): how Remote Control sessions fit into the Claude Code security model

203* [Data usage](/en/data-usage): what data flows through the Anthropic API during local and remote sessions

sandboxing.md +84 −6

Details

42* **Blocked access**: Cannot modify files outside the current working directory without explicit permission42* **Blocked access**: Cannot modify files outside the current working directory without explicit permission

43* **Configurable**: Define custom allowed and denied paths through settings43* **Configurable**: Define custom allowed and denied paths through settings

44 44

45You can grant write access to additional paths using `sandbox.filesystem.allowWrite` in your settings. These restrictions are enforced at the OS level (Seatbelt on macOS, bubblewrap on Linux), so they apply to all subprocess commands, including tools like `kubectl`, `terraform`, and `npm`, not just Claude's file tools.

45### Network isolation47### Network isolation

46 48

47Network access is controlled through a proxy server running outside the sandbox:49Network access is controlled through a proxy server running outside the sandbox:

48 50

49* **Domain restrictions**: Only approved domains can be accessed51* **Domain restrictions**: Only approved domains can be accessed

~~50* **User confirmation**: New domain requests trigger permission prompts~~52* **User confirmation**: New domain requests trigger permission prompts (unless [`allowManagedDomainsOnly`](/en/settings#sandbox-settings) is enabled, which blocks non-allowed domains automatically)

51* **Custom proxy support**: Advanced users can implement custom rules on outgoing traffic53* **Custom proxy support**: Advanced users can implement custom rules on outgoing traffic

52* **Comprehensive coverage**: Restrictions apply to all scripts, programs, and subprocesses spawned by commands54* **Comprehensive coverage**: Restrictions apply to all scripts, programs, and subprocesses spawned by commands

53 55

89 91

90You can enable sandboxing by running the `/sandbox` command:92You can enable sandboxing by running the `/sandbox` command:

91 93

~~92```~~94```text theme={null}

~~93> /sandbox~~95/sandbox

94```96```

95 97

96This opens a menu where you can choose between sandbox modes. If required dependencies are missing (such as `bubblewrap` or `socat` on Linux), the menu displays installation instructions for your platform.98This opens a menu where you can choose between sandbox modes. If required dependencies are missing (such as `bubblewrap` or `socat` on Linux), the menu displays installation instructions for your platform.

97 99

100By default, if the sandbox cannot start (missing dependencies, unsupported platform, or platform restrictions), Claude Code shows a warning and runs commands without sandboxing. To make this a hard failure instead, set [`sandbox.failIfUnavailable`](/en/settings#sandbox-settings) to `true`. This is intended for managed deployments that require sandboxing as a security gate.

101

98### Sandbox modes102### Sandbox modes

99 103

100Claude Code offers two sandbox modes:104Claude Code offers two sandbox modes:

113 117

114Customize sandbox behavior through your `settings.json` file. See [Settings](/en/settings#sandbox-settings) for complete configuration reference.118Customize sandbox behavior through your `settings.json` file. See [Settings](/en/settings#sandbox-settings) for complete configuration reference.

115 119

120#### Granting subprocess write access to specific paths

121

122By default, sandboxed commands can only write to the current working directory. If subprocess commands like `kubectl`, `terraform`, or `npm` need to write outside the project directory, use `sandbox.filesystem.allowWrite` to grant access to specific paths:

123

124```json theme={null}

125{

126 "sandbox": {

127 "enabled": true,

128 "filesystem": {

129 "allowWrite": ["~/.kube", "/tmp/build"]

130 }

131 }

132}

133```

134

135These paths are enforced at the OS level, so all commands running inside the sandbox, including their child processes, respect them. This is the recommended approach when a tool needs write access to a specific location, rather than excluding the tool from the sandbox entirely with `excludedCommands`.

136

137When `allowWrite` (or `denyWrite`/`denyRead`/`allowRead`) is defined in multiple [settings scopes](/en/settings#settings-precedence), the arrays are **merged**, meaning paths from every scope are combined, not replaced. For example, if managed settings allow writes to `/opt/company-tools` and a user adds `~/.kube` in their personal settings, both paths are included in the final sandbox configuration. This means users and projects can extend the list without duplicating or overriding paths set by higher-priority scopes.

138

139Path prefixes control how paths are resolved:

140

141| Prefix | Meaning | Example |

142| :---------------- | :------------------------------------------------------------------------------------- | :------------------------------------------------------------------------ |

143| `/` | Absolute path from filesystem root | `/tmp/build` stays `/tmp/build` |

144| `~/` | Relative to home directory | `~/.kube` becomes `$HOME/.kube` |

145| `./` or no prefix | Relative to the project root for project settings, or to `~/.claude` for user settings | `./output` in `.claude/settings.json` resolves to `<project-root>/output` |

146

147The older `//path` prefix for absolute paths still works. If you previously used single-slash `/path` expecting project-relative resolution, switch to `./path`. This syntax differs from [Read and Edit permission rules](/en/permissions#read-and-edit), which use `//path` for absolute and `/path` for project-relative. Sandbox filesystem paths use standard conventions: `/tmp/build` is an absolute path.

148

149You can also deny write or read access using `sandbox.filesystem.denyWrite` and `sandbox.filesystem.denyRead`. These are merged with any paths from `Edit(...)` and `Read(...)` permission rules. To re-allow reading specific paths within a denied region, use `sandbox.filesystem.allowRead`, which takes precedence over `denyRead`. When `allowManagedReadPathsOnly` is enabled in managed settings, only managed `allowRead` entries are respected; user, project, and local `allowRead` entries are ignored.

150

151For example, to block reading from the entire home directory while still allowing reads from the current project, add this to your project's `.claude/settings.json`:

152

153```json theme={null}

154{

155 "sandbox": {

156 "enabled": true,

157 "filesystem": {

158 "denyRead": ["~/"],

159 "allowRead": ["."]

160 }

161 }

162}

163```

164

165The `.` in `allowRead` resolves to the project root because this configuration lives in project settings. If you placed the same configuration in `~/.claude/settings.json`, `.` would resolve to `~/.claude` instead, and project files would remain blocked by the `denyRead` rule.

166

116<Tip>167<Tip>

117 Not all commands are compatible with sandboxing out of the box. Some notes that may help you make the most out of the sandbox:168 Not all commands are compatible with sandboxing out of the box. Some notes that may help you make the most out of the sandbox:

118 169

137 188

138* Cannot modify critical config files such as `~/.bashrc`189* Cannot modify critical config files such as `~/.bashrc`

139* Cannot modify system-level files in `/bin/`190* Cannot modify system-level files in `/bin/`

140* Cannot read files that are denied in your [Claude permission settings](/en/iam#configuring-permissions)191* Cannot read files that are denied in your [Claude permission settings](/en/permissions#manage-permissions)

141 192

142**Network protection:**193**Network protection:**

143 194

184* Filesystem Permission Escalation: Overly broad filesystem write permissions can enable privilege escalation attacks. Allowing writes to directories containing executables in `$PATH`, system configuration directories, or user shell configuration files (`.bashrc`, `.zshrc`) can lead to code execution in different security contexts when other users or system processes access these files.235* Filesystem Permission Escalation: Overly broad filesystem write permissions can enable privilege escalation attacks. Allowing writes to directories containing executables in `$PATH`, system configuration directories, or user shell configuration files (`.bashrc`, `.zshrc`) can lead to code execution in different security contexts when other users or system processes access these files.

185* Linux Sandbox Strength: The Linux implementation provides strong filesystem and network isolation but includes an `enableWeakerNestedSandbox` mode that enables it to work inside of Docker environments without privileged namespaces. This option considerably weakens security and should only be used in cases where additional isolation is otherwise enforced.236* Linux Sandbox Strength: The Linux implementation provides strong filesystem and network isolation but includes an `enableWeakerNestedSandbox` mode that enables it to work inside of Docker environments without privileged namespaces. This option considerably weakens security and should only be used in cases where additional isolation is otherwise enforced.

186 237

238## How sandboxing relates to permissions

239

240Sandboxing and [permissions](/en/permissions) are complementary security layers that work together:

241

242* **Permissions** control which tools Claude Code can use and are evaluated before any tool runs. They apply to all tools: Bash, Read, Edit, WebFetch, MCP, and others.

243* **Sandboxing** provides OS-level enforcement that restricts what Bash commands can access at the filesystem and network level. It applies only to Bash commands and their child processes.

244

245Filesystem and network restrictions are configured through both sandbox settings and permission rules:

246

247* Use `sandbox.filesystem.allowWrite` to grant subprocess write access to paths outside the working directory

248* Use `sandbox.filesystem.denyWrite` and `sandbox.filesystem.denyRead` to block subprocess access to specific paths

249* Use `sandbox.filesystem.allowRead` to re-allow reading specific paths within a `denyRead` region

250* Use `Read` and `Edit` deny rules to block access to specific files or directories

251* Use `WebFetch` allow/deny rules to control domain access

252* Use sandbox `allowedDomains` to control which domains Bash commands can reach

253

254Paths from both `sandbox.filesystem` settings and permission rules are merged together into the final sandbox configuration.

255

256This [repository](https://github.com/anthropics/claude-code/tree/main/examples/settings) includes starter settings configurations for common deployment scenarios, including sandbox-specific examples. Use these as starting points and adjust them to fit your needs.

257

187## Advanced usage258## Advanced usage

188 259

189### Custom proxy configuration260### Custom proxy configuration

210 281

211The sandboxed bash tool works alongside:282The sandboxed bash tool works alongside:

212 283

213* **IAM policies**: Combine with [permission settings](/en/iam) for defense-in-depth284* **Permission rules**: Combine with [permission settings](/en/permissions) for defense-in-depth

214* **Development containers**: Use with [devcontainers](/en/devcontainer) for additional isolation285* **Development containers**: Use with [devcontainers](/en/devcontainer) for additional isolation

215* **Enterprise policies**: Enforce sandbox configurations through [managed settings](/en/settings#settings-precedence)286* **Enterprise policies**: Enforce sandbox configurations through [managed settings](/en/settings#settings-precedence)

216 287

238* **Compatibility**: Some tools that require specific system access patterns may need configuration adjustments, or may even need to be run outside of the sandbox309* **Compatibility**: Some tools that require specific system access patterns may need configuration adjustments, or may even need to be run outside of the sandbox

239* **Platform support**: Supports macOS, Linux, and WSL2. WSL1 is not supported. Native Windows support is planned.310* **Platform support**: Supports macOS, Linux, and WSL2. WSL1 is not supported. Native Windows support is planned.

240 311

312## What sandboxing does not cover

313

314The sandbox isolates Bash subprocesses. Other tools operate under different boundaries:

315

316* **Built-in file tools**: Read, Edit, and Write use the permission system directly rather than running through the sandbox. See [permissions](/en/permissions).

317* **Computer use on Desktop**: when Claude opens apps and controls your screen on macOS, it runs on your actual desktop rather than in an isolated environment. Per-app permission prompts gate each application. See [computer use](/en/desktop#let-claude-use-your-computer).

318

241## See also319## See also

242 320

243* [Security](/en/security) - Comprehensive security features and best practices321* [Security](/en/security) - Comprehensive security features and best practices

244* [IAM](/en/iam) - Permission configuration and access control322* [Permissions](/en/permissions) - Permission configuration and access control

245* [Settings](/en/settings) - Complete configuration reference323* [Settings](/en/settings) - Complete configuration reference

246* [CLI reference](/en/cli-reference) - Command-line options324* [CLI reference](/en/cli-reference) - Command-line options

scheduled-tasks.md +157 −0 added

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# Run prompts on a schedule

7> Use /loop and the cron scheduling tools to run prompts repeatedly, poll for status, or set one-time reminders within a Claude Code session.

9<Note>

10 Scheduled tasks require Claude Code v2.1.72 or later. Check your version with `claude --version`.

11</Note>

13Scheduled tasks let Claude re-run a prompt automatically on an interval. Use them to poll a deployment, babysit a PR, check back on a long-running build, or remind yourself to do something later in the session. To react to events as they happen instead of polling, see [Channels](/en/channels): your CI can push the failure into the session directly.

15Tasks are session-scoped: they live in the current Claude Code process and are gone when you exit. For durable scheduling that survives restarts, use [Cloud](/en/web-scheduled-tasks) or [Desktop](/en/desktop#schedule-recurring-tasks) scheduled tasks, or [GitHub Actions](/en/github-actions).

17## Compare scheduling options

19Claude Code offers three ways to schedule recurring work:

22| :------------------------- | :------------------------------- | :---------------------------------------------- | :----------------------------- |

24| Requires machine on | No | Yes | Yes |

25| Requires open session | No | No | Yes |

26| Persistent across restarts | Yes | Yes | No (session-scoped) |

27| Access to local files | No (fresh clone) | Yes | Yes |

30| Customizable schedule | Via `/schedule` in the CLI | Yes | Yes |

33<Tip>

34 Use **cloud tasks** for work that should run reliably without your machine. Use **Desktop tasks** when you need access to local files and tools. Use **`/loop`** for quick polling during a session.

35</Tip>

37## Schedule a recurring prompt with /loop

39The `/loop` [bundled skill](/en/skills#bundled-skills) is the quickest way to schedule a recurring prompt. Pass an optional interval and a prompt, and Claude sets up a cron job that fires in the background while the session stays open.

41```text theme={null}

42/loop 5m check if the deployment finished and tell me what happened

43```

45Claude parses the interval, converts it to a cron expression, schedules the job, and confirms the cadence and job ID.

47### Interval syntax

49Intervals are optional. You can lead with them, trail with them, or leave them out entirely.

51| Form | Example | Parsed interval |

52| :---------------------- | :------------------------------------ | :--------------------------- |

53| Leading token | `/loop 30m check the build` | every 30 minutes |

54| Trailing `every` clause | `/loop check the build every 2 hours` | every 2 hours |

55| No interval | `/loop check the build` | defaults to every 10 minutes |

57Supported units are `s` for seconds, `m` for minutes, `h` for hours, and `d` for days. Seconds are rounded up to the nearest minute since cron has one-minute granularity. Intervals that don't divide evenly into their unit, such as `7m` or `90m`, are rounded to the nearest clean interval and Claude tells you what it picked.

59### Loop over another command

61The scheduled prompt can itself be a command or skill invocation. This is useful for re-running a workflow you've already packaged.

63```text theme={null}

64/loop 20m /review-pr 1234

65```

67Each time the job fires, Claude runs `/review-pr 1234` as if you had typed it.

69## Set a one-time reminder

71For one-shot reminders, describe what you want in natural language instead of using `/loop`. Claude schedules a single-fire task that deletes itself after running.

73```text theme={null}

74remind me at 3pm to push the release branch

75```

77```text theme={null}

78in 45 minutes, check whether the integration tests passed

79```

81Claude pins the fire time to a specific minute and hour using a cron expression and confirms when it will fire.

83## Manage scheduled tasks

85Ask Claude in natural language to list or cancel tasks, or reference the underlying tools directly.

87```text theme={null}

88what scheduled tasks do I have?

89```

91```text theme={null}

92cancel the deploy check job

93```

95Under the hood, Claude uses these tools:

97| Tool | Purpose |

98| :----------- | :-------------------------------------------------------------------------------------------------------------- |

99| `CronCreate` | Schedule a new task. Accepts a 5-field cron expression, the prompt to run, and whether it recurs or fires once. |

100| `CronList` | List all scheduled tasks with their IDs, schedules, and prompts. |

101| `CronDelete` | Cancel a task by ID. |

102

103Each scheduled task has an 8-character ID you can pass to `CronDelete`. A session can hold up to 50 scheduled tasks at once.

104

105## How scheduled tasks run

106

107The scheduler checks every second for due tasks and enqueues them at low priority. A scheduled prompt fires between your turns, not while Claude is mid-response. If Claude is busy when a task comes due, the prompt waits until the current turn ends.

108

109All times are interpreted in your local timezone. A cron expression like `0 9 * * *` means 9am wherever you're running Claude Code, not UTC.

110

111### Jitter

112

113To avoid every session hitting the API at the same wall-clock moment, the scheduler adds a small deterministic offset to fire times:

114

115* Recurring tasks fire up to 10% of their period late, capped at 15 minutes. An hourly job might fire anywhere from `:00` to `:06`.

116* One-shot tasks scheduled for the top or bottom of the hour fire up to 90 seconds early.

117

118The offset is derived from the task ID, so the same task always gets the same offset. If exact timing matters, pick a minute that is not `:00` or `:30`, for example `3 9 * * *` instead of `0 9 * * *`, and the one-shot jitter will not apply.

119

120### Three-day expiry

121

122Recurring tasks automatically expire 3 days after creation. The task fires one final time, then deletes itself. This bounds how long a forgotten loop can run. If you need a recurring task to last longer, cancel and recreate it before it expires, or use [Cloud scheduled tasks](/en/web-scheduled-tasks) or [Desktop scheduled tasks](/en/desktop#schedule-recurring-tasks) for durable scheduling.

123

124## Cron expression reference

125

126`CronCreate` accepts standard 5-field cron expressions: `minute hour day-of-month month day-of-week`. All fields support wildcards (`*`), single values (`5`), steps (`*/15`), ranges (`1-5`), and comma-separated lists (`1,15,30`).

127

128| Example | Meaning |

129| :------------- | :--------------------------- |

130| `*/5 * * * *` | Every 5 minutes |

131| `0 * * * *` | Every hour on the hour |

132| `7 * * * *` | Every hour at 7 minutes past |

133| `0 9 * * *` | Every day at 9am local |

134| `0 9 * * 1-5` | Weekdays at 9am local |

135| `30 14 15 3 *` | March 15 at 2:30pm local |

136

137Day-of-week uses `0` or `7` for Sunday through `6` for Saturday. Extended syntax like `L`, `W`, `?`, and name aliases such as `MON` or `JAN` is not supported.

138

139When both day-of-month and day-of-week are constrained, a date matches if either field matches. This follows standard vixie-cron semantics.

140

141## Disable scheduled tasks

142

143Set `CLAUDE_CODE_DISABLE_CRON=1` in your environment to disable the scheduler entirely. The cron tools and `/loop` become unavailable, and any already-scheduled tasks stop firing. See [Environment variables](/en/env-vars) for the full list of disable flags.

144

145## Limitations

146

147Session-scoped scheduling has inherent constraints:

148

149* Tasks only fire while Claude Code is running and idle. Closing the terminal or letting the session exit cancels everything.

150* No catch-up for missed fires. If a task's scheduled time passes while Claude is busy on a long-running request, it fires once when Claude becomes idle, not once per missed interval.

151* No persistence across restarts. Restarting Claude Code clears all session-scoped tasks.

152

153For cron-driven automation that needs to run unattended:

154

155* [Cloud scheduled tasks](/en/web-scheduled-tasks): run on Anthropic-managed infrastructure

156* [GitHub Actions](/en/github-actions): use a `schedule` trigger in CI

157* [Desktop scheduled tasks](/en/desktop#schedule-recurring-tasks): run locally on your machine

security.md +9 −6

Details

18 18

19We designed Claude Code to be transparent and secure. For example, we require approval for bash commands before executing them, giving you direct control. This approach enables users and organizations to configure permissions directly.19We designed Claude Code to be transparent and secure. For example, we require approval for bash commands before executing them, giving you direct control. This approach enables users and organizations to configure permissions directly.

20 20

~~21For detailed permission configuration, see [Identity and Access Management](/en/iam).~~21For detailed permission configuration, see [Permissions](/en/permissions).

22 22

23### Built-in protections23### Built-in protections

24 24

42* **Permission system**: Sensitive operations require explicit approval42* **Permission system**: Sensitive operations require explicit approval

43* **Context-aware analysis**: Detects potentially harmful instructions by analyzing the full request43* **Context-aware analysis**: Detects potentially harmful instructions by analyzing the full request

44* **Input sanitization**: Prevents command injection by processing user inputs44* **Input sanitization**: Prevents command injection by processing user inputs

45* **Command blocklist**: Blocks risky commands that fetch arbitrary content from the web like `curl` and `wget` by default. When explicitly allowed, be aware of [permission pattern limitations](/en/iam#tool-specific-permission-rules)45* **Command blocklist**: Blocks risky commands that fetch arbitrary content from the web like `curl` and `wget` by default. When explicitly allowed, be aware of [permission pattern limitations](/en/permissions#tool-specific-permission-rules)

46 46

47### Privacy safeguards47### Privacy safeguards

48 48

63* **Command injection detection**: Suspicious bash commands require manual approval even if previously allowlisted63* **Command injection detection**: Suspicious bash commands require manual approval even if previously allowlisted

64* **Fail-closed matching**: Unmatched commands default to requiring manual approval64* **Fail-closed matching**: Unmatched commands default to requiring manual approval

65* **Natural language descriptions**: Complex bash commands include explanations for user understanding65* **Natural language descriptions**: Complex bash commands include explanations for user understanding

~~66* **Secure credential storage**: API keys and tokens are encrypted. See [Credential Management](/en/iam#credential-management)~~66* **Secure credential storage**: API keys and tokens are encrypted. See [Credential Management](/en/authentication#credential-management)

67 67

68<Warning>68<Warning>

69 **Windows WebDAV security risk**: When running Claude Code on Windows, we recommend against enabling WebDAV or allowing Claude Code to access paths such as `\\*` that may contain WebDAV subdirectories. [WebDAV has been deprecated by Microsoft](https://learn.microsoft.com/en-us/windows/whats-new/deprecated-features#:~:text=The%20Webclient%20$WebDAV$%20service%20is%20deprecated) due to security risks. Enabling WebDAV may allow Claude Code to trigger network requests to remote hosts, bypassing the permission system.69 **Windows WebDAV security risk**: When running Claude Code on Windows, we recommend against enabling WebDAV or allowing Claude Code to access paths such as `\\*` that may contain WebDAV subdirectories. [WebDAV has been deprecated by Microsoft](https://learn.microsoft.com/en-us/windows/whats-new/deprecated-features#:~:text=The%20Webclient%20$WebDAV$%20service%20is%20deprecated) due to security risks. Enabling WebDAV may allow Claude Code to trigger network requests to remote hosts, bypassing the permission system.

752. Avoid piping untrusted content directly to Claude752. Avoid piping untrusted content directly to Claude

763. Verify proposed changes to critical files763. Verify proposed changes to critical files

774. Use virtual machines (VMs) to run scripts and make tool calls, especially when interacting with external web services774. Use virtual machines (VMs) to run scripts and make tool calls, especially when interacting with external web services

~~785. Report suspicious behavior with `/bug`~~785. Report suspicious behavior with `/feedback`

79 79

80<Warning>80<Warning>

81 While these protections significantly reduce risk, no system is completely81 While these protections significantly reduce risk, no system is completely

106 106

107For more details on cloud execution, see [Claude Code on the web](/en/claude-code-on-the-web).107For more details on cloud execution, see [Claude Code on the web](/en/claude-code-on-the-web).

108 108

109[Remote Control](/en/remote-control) sessions work differently: the web interface connects to a Claude Code process running on your local machine. All code execution and file access stays local, and the same data that flows during any local Claude Code session travels through the Anthropic API over TLS. No cloud VMs or sandboxing are involved. The connection uses multiple short-lived, narrowly scoped credentials, each limited to a specific purpose and expiring independently, to limit the blast radius of any single compromised credential.

110

109## Security best practices111## Security best practices

110 112

111### Working with sensitive code113### Working with sensitive code

117 119

118### Team security120### Team security

119 121

120* Use [managed settings](/en/iam#managed-settings) to enforce organizational standards122* Use [managed settings](/en/settings#settings-files) to enforce organizational standards

121* Share approved permission configurations through version control123* Share approved permission configurations through version control

122* Train team members on security best practices124* Train team members on security best practices

123* Monitor Claude Code usage through [OpenTelemetry metrics](/en/monitoring-usage)125* Monitor Claude Code usage through [OpenTelemetry metrics](/en/monitoring-usage)

126* Audit or block settings changes during sessions with [`ConfigChange` hooks](/en/hooks#configchange)

124 127

125### Reporting security issues128### Reporting security issues

126 129

134## Related resources137## Related resources

135 138

136* [Sandboxing](/en/sandboxing) - Filesystem and network isolation for bash commands139* [Sandboxing](/en/sandboxing) - Filesystem and network isolation for bash commands

137* [Identity and Access Management](/en/iam) - Configure permissions and access controls140* [Permissions](/en/permissions) - Configure permissions and access controls

138* [Monitoring usage](/en/monitoring-usage) - Track and audit Claude Code activity141* [Monitoring usage](/en/monitoring-usage) - Track and audit Claude Code activity

139* [Development containers](/en/devcontainer) - Secure, isolated environments142* [Development containers](/en/devcontainer) - Secure, isolated environments

140* [Anthropic Trust Center](https://trust.anthropic.com) - Security certifications and compliance143* [Anthropic Trust Center](https://trust.anthropic.com) - Security certifications and compliance

server-managed-settings.md +199 −0 added

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# Configure server-managed settings (public beta)

7> Centrally configure Claude Code for your organization through server-delivered settings, without requiring device management infrastructure.

9Server-managed settings allow administrators to centrally configure Claude Code through a web-based interface on Claude.ai. Claude Code clients automatically receive these settings when users authenticate with their organization credentials.

11This approach is designed for organizations that do not have device management infrastructure in place, or need to manage settings for users on unmanaged devices.

13<Note>

14 Server-managed settings are in public beta and available for [Claude for Teams](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=server_settings_teams#team-&-enterprise) and [Claude for Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=server_settings_enterprise) customers. Features may evolve before general availability.

15</Note>

17## Requirements

19To use server-managed settings, you need:

21* Claude for Teams or Claude for Enterprise plan

22* Claude Code version 2.1.38 or later for Claude for Teams, or version 2.1.30 or later for Claude for Enterprise

23* Network access to `api.anthropic.com`

25## Choose between server-managed and endpoint-managed settings

27Claude Code supports two approaches for centralized configuration. Server-managed settings deliver configuration from Anthropic's servers. [Endpoint-managed settings](/en/settings#settings-files) are deployed directly to devices through native OS policies (macOS managed preferences, Windows registry) or managed settings files.

29| Approach | Best for | Security model |

30| :----------------------------------------------------------- | :------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------- |

31| **Server-managed settings** | Organizations without MDM, or users on unmanaged devices | Settings delivered from Anthropic's servers at authentication time |

32| **[Endpoint-managed settings](/en/settings#settings-files)** | Organizations with MDM or endpoint management | Settings deployed to devices via MDM configuration profiles, registry policies, or managed settings files |

34If your devices are enrolled in an MDM or endpoint management solution, endpoint-managed settings provide stronger security guarantees because the settings file can be protected from user modification at the OS level.

36## Configure server-managed settings

38<Steps>

39 <Step title="Open the admin console">

40 In [Claude.ai](https://claude.ai), navigate to **Admin Settings > Claude Code > Managed settings**.

41 </Step>

43 <Step title="Define your settings">

44 Add your configuration as JSON. All [settings available in `settings.json`](/en/settings#available-settings) are supported, including [hooks](/en/hooks), [environment variables](/en/env-vars), and [managed-only settings](/en/permissions#managed-only-settings) like `allowManagedPermissionRulesOnly`.

46 This example enforces a permission deny list and prevents users from bypassing permissions:

48 ```json theme={null}

49 {

50 "permissions": {

51 "deny": [

52 "Bash(curl *)",

53 "Read(./.env)",

54 "Read(./.env.*)",

55 "Read(./secrets/**)"

56 ],

57 "disableBypassPermissionsMode": "disable"

58 }

59 }

60 ```

62 Hooks use the same format as in `settings.json`.

64 This example runs an audit script after every file edit across the organization:

66 ```json theme={null}

67 {

68 "hooks": {

69 "PostToolUse": [

70 {

71 "matcher": "Edit|Write",

72 "hooks": [

73 { "type": "command", "command": "/usr/local/bin/audit-edit.sh" }

74 ]

75 }

76 ]

77 }

78 }

79 ```

81 To configure the [auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) classifier so it knows which repos, buckets, and domains your organization trusts:

83 ```json theme={null}

84 {

85 "autoMode": {

86 "environment": [

87 "Source control: github.example.com/acme-corp and all repos under it",

88 "Trusted cloud buckets: s3://acme-build-artifacts, gs://acme-ml-datasets",

89 "Trusted internal domains: *.corp.example.com"

90 ]

91 }

92 }

93 ```

95 Because hooks execute shell commands, users see a [security approval dialog](#security-approval-dialogs) before they're applied. See [Configure the auto mode classifier](/en/permissions#configure-the-auto-mode-classifier) for how the `autoMode` entries affect what the classifier blocks and important warnings about the `allow` and `soft_deny` fields.

96 </Step>

98 <Step title="Save and deploy">

99 Save your changes. Claude Code clients receive the updated settings on their next startup or hourly polling cycle.

100 </Step>

101</Steps>

102

103### Verify settings delivery

104

105To confirm that settings are being applied, ask a user to restart Claude Code. If the configuration includes settings that trigger the [security approval dialog](#security-approval-dialogs), the user sees a prompt describing the managed settings on startup. You can also verify that managed permission rules are active by having a user run `/permissions` to view their effective permission rules.

106

107### Access control

108

109The following roles can manage server-managed settings:

110

111* **Primary Owner**

112* **Owner**

113

114Restrict access to trusted personnel, as settings changes apply to all users in the organization.

115

116### Current limitations

117

118Server-managed settings have the following limitations during the beta period:

119

120* Settings apply uniformly to all users in the organization. Per-group configurations are not yet supported.

121* [MCP server configurations](/en/mcp#managed-mcp-configuration) cannot be distributed through server-managed settings.

122

123## Settings delivery

124

125### Settings precedence

126

127Server-managed settings and [endpoint-managed settings](/en/settings#settings-files) both occupy the highest tier in the Claude Code [settings hierarchy](/en/settings#settings-precedence). No other settings level can override them, including command line arguments. When both are present, server-managed settings take precedence and endpoint-managed settings are not used.

128

129### Fetch and caching behavior

130

131Claude Code fetches settings from Anthropic's servers at startup and polls for updates hourly during active sessions.

132

133**First launch without cached settings:**

134

135* Claude Code fetches settings asynchronously

136* If the fetch fails, Claude Code continues without managed settings

137* There is a brief window before settings load where restrictions are not yet enforced

138

139**Subsequent launches with cached settings:**

140

141* Cached settings apply immediately at startup

142* Claude Code fetches fresh settings in the background

143* Cached settings persist through network failures

144

145Claude Code applies settings updates automatically without a restart, except for advanced settings like OpenTelemetry configuration, which require a full restart to take effect.

146

147### Security approval dialogs

148

149Certain settings that could pose security risks require explicit user approval before being applied:

150

151* **Shell command settings**: settings that execute shell commands

152* **Custom environment variables**: variables not in the known safe allowlist

153* **Hook configurations**: any hook definition

154

155When these settings are present, users see a security dialog explaining what is being configured. Users must approve to proceed. If a user rejects the settings, Claude Code exits.

156

157<Note>

158 In non-interactive mode with the `-p` flag, Claude Code skips security dialogs and applies settings without user approval.

159</Note>

160

161## Platform availability

162

163Server-managed settings require a direct connection to `api.anthropic.com` and are not available when using third-party model providers:

164

165* Amazon Bedrock

166* Google Vertex AI

167* Microsoft Foundry

168* Custom API endpoints via `ANTHROPIC_BASE_URL` or [LLM gateways](/en/llm-gateway)

169

170## Audit logging

171

172Audit log events for settings changes are available through the compliance API or audit log export. Contact your Anthropic account team for access.

173

174Audit events include the type of action performed, the account and device that performed the action, and references to the previous and new values.

175

176## Security considerations

177

178Server-managed settings provide centralized policy enforcement, but they operate as a client-side control. On unmanaged devices, users with admin or sudo access can modify the Claude Code binary, filesystem, or network configuration.

179

180| Scenario | Behavior |

181| :----------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |

182| User edits the cached settings file | Tampered file applies at startup, but correct settings restore on the next server fetch |

183| User deletes the cached settings file | First-launch behavior occurs: settings fetch asynchronously with a brief unenforced window |

184| API is unavailable | Cached settings apply if available, otherwise managed settings are not enforced until the next successful fetch |

185| User authenticates with a different organization | Settings are not delivered for accounts outside the managed organization |

186| User sets a non-default `ANTHROPIC_BASE_URL` | Server-managed settings are bypassed when using third-party API providers |

187

188To detect runtime configuration changes, use [`ConfigChange` hooks](/en/hooks#configchange) to log modifications or block unauthorized changes before they take effect.

189

190For stronger enforcement guarantees, use [endpoint-managed settings](/en/settings#settings-files) on devices enrolled in an MDM solution.

191

192## See also

193

194Related pages for managing Claude Code configuration:

195

196* [Settings](/en/settings): complete configuration reference including all available settings

197* [Endpoint-managed settings](/en/settings#settings-files): managed settings deployed to devices by IT

198* [Authentication](/en/authentication): set up user access to Claude Code

199* [Security](/en/security): security safeguards and best practices

settings.md +202 −291

Details

15### Available scopes15### Available scopes

16 16

~~18| :---------- | :----------------------------------- | :----------------------------------- | :--------------------- |~~18| :---------- | :--------------------------------------------------------------------------------- | :----------------------------------- | :--------------------- |

20| **User** | `~/.claude/` directory | You, across all projects | No |20| **User** | `~/.claude/` directory | You, across all projects | No |

~~22| **Local** | `.claude/*.local.*` files | You, in this repository only | No (gitignored) |~~22| **Local** | `.claude/settings.local.json` | You, in this repository only | No (gitignored) |

23 23

24### When to use each scope24### When to use each scope

25 25

67| :-------------- | :------------------------ | :--------------------------------- | :----------------------------- |67| :-------------- | :------------------------ | :--------------------------------- | :----------------------------- |

73 73

74***74***

75 75

76## Settings files76## Settings files

77 77

~~78The `settings.json` file is our official mechanism for configuring Claude~~78The `settings.json` file is the official mechanism for configuring Claude

79Code through hierarchical settings:79Code through hierarchical settings:

80 80

81* **User settings** are defined in `~/.claude/settings.json` and apply to all81* **User settings** are defined in `~/.claude/settings.json` and apply to all

83* **Project settings** are saved in your project directory:83* **Project settings** are saved in your project directory:

84 * `.claude/settings.json` for settings that are checked into source control and shared with your team84 * `.claude/settings.json` for settings that are checked into source control and shared with your team

85 * `.claude/settings.local.json` for settings that are not checked in, useful for personal preferences and experimentation. Claude Code will configure git to ignore `.claude/settings.local.json` when it is created.85 * `.claude/settings.local.json` for settings that are not checked in, useful for personal preferences and experimentation. Claude Code will configure git to ignore `.claude/settings.local.json` when it is created.

~~86* **Managed settings**: For organizations that need centralized control, Claude Code supports `managed-settings.json` and `managed-mcp.json` files that can be deployed to system directories:~~86* **Managed settings**: For organizations that need centralized control, Claude Code supports multiple delivery mechanisms for managed settings. All use the same JSON format and cannot be overridden by user or project settings:

88 * **Server-managed settings**: delivered from Anthropic's servers via the Claude.ai admin console. See [server-managed settings](/en/server-managed-settings).

89 * **MDM/OS-level policies**: delivered through native device management on macOS and Windows:

90 * macOS: `com.anthropic.claudecode` managed preferences domain (deployed via configuration profiles in Jamf, Kandji, or other MDM tools)

91 * Windows: `HKLM\SOFTWARE\Policies\ClaudeCode` registry key with a `Settings` value (REG\_SZ or REG\_EXPAND\_SZ) containing JSON (deployed via Group Policy or Intune)

92 * Windows (user-level): `HKCU\SOFTWARE\Policies\ClaudeCode` (lowest policy priority, only used when no admin-level source exists)

93 * **File-based**: `managed-settings.json` and `managed-mcp.json` deployed to system directories:

87 94

88 * macOS: `/Library/Application Support/ClaudeCode/`95 * macOS: `/Library/Application Support/ClaudeCode/`

89 * Linux and WSL: `/etc/claude-code/`96 * Linux and WSL: `/etc/claude-code/`

90 * Windows: `C:\Program Files\ClaudeCode\`97 * Windows: `C:\Program Files\ClaudeCode\`

91 98

~~92 <Note>~~99 <Warning>

~~93 These are system-wide paths (not user home directories like `~/Library/...`) that require administrator privileges. They are designed to be deployed by IT administrators.~~100 The legacy Windows path `C:\ProgramData\ClaudeCode\managed-settings.json` is no longer supported as of v2.1.75. Administrators who deployed settings to that location must migrate files to `C:\Program Files\ClaudeCode\managed-settings.json`.

~~94 </Note>~~101 </Warning>

102

103 File-based managed settings also support a drop-in directory at `managed-settings.d/` in the same system directory alongside `managed-settings.json`. This lets separate teams deploy independent policy fragments without coordinating edits to a single file.

104

105 Following the systemd convention, `managed-settings.json` is merged first as the base, then all `*.json` files in the drop-in directory are sorted alphabetically and merged on top. Later files override earlier ones for scalar values; arrays are concatenated and de-duplicated; objects are deep-merged. Hidden files starting with `.` are ignored.

95 106

~~96 See [Managed settings](/en/iam#managed-settings) and [Managed MCP configuration](/en/mcp#managed-mcp-configuration) for details.~~107 Use numeric prefixes to control merge order, for example `10-telemetry.json` and `20-security.json`.

108

109 See [managed settings](/en/permissions#managed-only-settings) and [Managed MCP configuration](/en/mcp#managed-mcp-configuration) for details.

97 110

98 <Note>111 <Note>

99 Managed deployments can also restrict **plugin marketplace additions** using112 Managed deployments can also restrict **plugin marketplace additions** using

140`settings.json` supports a number of options:153`settings.json` supports a number of options:

141 154

142| Key | Description | Example |155| Key | Description | Example |

143| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------- |156| :-------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------- |

144| `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 | `/bin/generate_temp_api_key.sh` |157| `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 | `/bin/generate_temp_api_key.sh` |

145| `cleanupPeriodDays` | Sessions inactive for longer than this period are deleted at startup. Setting to `0` immediately deletes all sessions. (default: 30 days) | `20` |158| `autoMemoryDirectory` | Custom directory for [auto memory](/en/memory#storage-location) storage. Accepts `~/`-expanded paths. Not accepted in project settings (`.claude/settings.json`) to prevent shared repos from redirecting memory writes to sensitive locations. Accepted from policy, local, and user settings | `"~/my-memory-dir"` |

159| `cleanupPeriodDays` | Sessions inactive for longer than this period are deleted at startup (default: 30 days). Setting to `0` deletes all existing transcripts at startup and disables session persistence entirely. No new `.jsonl` files are written, `/resume` shows no conversations, and hooks receive an empty `transcript_path`. | `20` |

146| `companyAnnouncements` | Announcement to display to users at startup. If multiple announcements are provided, they will be cycled through at random. | `["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"]` |160| `companyAnnouncements` | Announcement to display to users at startup. If multiple announcements are provided, they will be cycled through at random. | `["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"]` |

147| `env` | Environment variables that will be applied to every session | `{"FOO": "bar"}` |161| `env` | Environment variables that will be applied to every session | `{"FOO": "bar"}` |

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

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

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

166| `autoMode` | Customize what the [auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) classifier blocks and allows. Contains `environment`, `allow`, and `soft_deny` arrays of prose rules. See [Configure the auto mode classifier](/en/permissions#configure-the-auto-mode-classifier). Not read from shared project settings | `{"environment": ["Trusted repo: github.example.com/acme"]}` |

167| `disableAutoMode` | Set to `"disable"` to prevent [auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode) from being activated. Removes `auto` from the `Shift+Tab` cycle and rejects `--permission-mode auto` at startup. Most useful in [managed settings](/en/permissions#managed-settings) where users cannot override it | `"disable"` |

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

169| `disableDeepLinkRegistration` | Set to `"disable"` to prevent Claude Code from registering the `claude-cli://` protocol handler with the operating system on startup. Deep links let external tools open a Claude Code session with a pre-filled prompt via `claude-cli://open?q=...`. Useful in environments where protocol handler registration is restricted or managed separately | `"disable"` |

152| `disableAllHooks` | Disable all [hooks](/en/hooks) | `true` |171| `defaultShell` | Default shell for input-box `!` commands. Accepts `"bash"` (default) or `"powershell"`. Setting `"powershell"` routes interactive `!` commands through PowerShell on Windows. Requires `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`. See [PowerShell tool](/en/tools-reference#powershell-tool) | `"powershell"` |

172| `disableAllHooks` | Disable all [hooks](/en/hooks) and any custom [status line](/en/statusline) | `true` |

153| `allowManagedHooksOnly` | (Managed settings only) Prevent loading of user, project, and plugin hooks. Only allows managed hooks and SDK hooks. See [Hook configuration](#hook-configuration) | `true` |173| `allowManagedHooksOnly` | (Managed settings only) Prevent loading of user, project, and plugin hooks. Only allows managed hooks and SDK hooks. See [Hook configuration](#hook-configuration) | `true` |

154| `model` | Override the default model to use for Claude Code | `"claude-sonnet-4-5-20250929"` |174| `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/*"]` |

175| `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"]` |

176| `allowManagedPermissionRulesOnly` | (Managed settings only) Prevent user and project settings from defining `allow`, `ask`, or `deny` permission rules. Only rules in managed settings apply. See [Managed-only settings](/en/permissions#managed-only-settings) | `true` |

177| `allowManagedMcpServersOnly` | (Managed settings only) Only `allowedMcpServers` from managed settings are respected. `deniedMcpServers` still merges from all sources. Users can still add MCP servers, but only the admin-defined allowlist applies. See [Managed MCP configuration](/en/mcp#managed-mcp-configuration) | `true` |

178| `model` | Override the default model to use for Claude Code | `"claude-sonnet-4-6"` |

179| `availableModels` | Restrict which models users can select via `/model`, `--model`, Config tool, or `ANTHROPIC_MODEL`. Does not affect the Default option. See [Restrict model selection](/en/model-config#restrict-model-selection) | `["sonnet", "haiku"]` |

180| `modelOverrides` | Map Anthropic model IDs to provider-specific model IDs such as Bedrock inference profile ARNs. Each model picker entry uses its mapped value when calling the provider API. See [Override model IDs per version](/en/model-config#override-model-ids-per-version) | `{"claude-opus-4-6": "arn:aws:bedrock:..."}` |

181| `effortLevel` | Persist the [effort level](/en/model-config#adjust-effort-level) across sessions. Accepts `"low"`, `"medium"`, or `"high"`. Written automatically when you run `/effort low`, `/effort medium`, or `/effort high`. Supported on Opus 4.6 and Sonnet 4.6 | `"medium"` |

155| `otelHeadersHelper` | Script to generate dynamic OpenTelemetry headers. Runs at startup and periodically (see [Dynamic headers](/en/monitoring-usage#dynamic-headers)) | `/bin/generate_otel_headers.sh` |182| `otelHeadersHelper` | Script to generate dynamic OpenTelemetry headers. Runs at startup and periodically (see [Dynamic headers](/en/monitoring-usage#dynamic-headers)) | `/bin/generate_otel_headers.sh` |

156| `statusLine` | Configure a custom status line to display context. See [`statusLine` documentation](/en/statusline) | `{"type": "command", "command": "~/.claude/statusline.sh"}` |183| `statusLine` | Configure a custom status line to display context. See [`statusLine` documentation](/en/statusline) | `{"type": "command", "command": "~/.claude/statusline.sh"}` |

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

158| `respectGitignore` | Control whether the `@` file picker respects `.gitignore` patterns. When `true` (default), files matching `.gitignore` patterns are excluded from suggestions | `false` |185| `respectGitignore` | Control whether the `@` file picker respects `.gitignore` patterns. When `true` (default), files matching `.gitignore` patterns are excluded from suggestions | `false` |

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

160| `forceLoginMethod` | Use `claudeai` to restrict login to Claude.ai accounts, `console` to restrict login to Claude Console (API usage billing) accounts | `claudeai` |188| `forceLoginMethod` | Use `claudeai` to restrict login to Claude.ai accounts, `console` to restrict login to Claude Console (API usage billing) accounts | `claudeai` |

161| `forceLoginOrgUUID` | Specify the UUID of an organization to automatically select it during login, bypassing the organization selection step. Requires `forceLoginMethod` to be set | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` |189| `forceLoginOrgUUID` | Specify the UUID of an organization to automatically select it during login, bypassing the organization selection step. Requires `forceLoginMethod` to be set | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` |

193| `channelsEnabled` | (Managed settings only) Allow [channels](/en/channels) for Team and Enterprise users. Unset or `false` blocks channel message delivery regardless of what users pass to `--channels` | `true` |

194| `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" }]` |

165| `allowedMcpServers` | When set in managed-settings.json, allowlist of MCP servers users can configure. Undefined = no restrictions, empty array = lockdown. Applies to all scopes. Denylist takes precedence. See [Managed MCP configuration](/en/mcp#managed-mcp-configuration) | `[{ "serverName": "github" }]` |195| `allowedMcpServers` | When set in managed-settings.json, allowlist of MCP servers users can configure. Undefined = no restrictions, empty array = lockdown. Applies to all scopes. Denylist takes precedence. See [Managed MCP configuration](/en/mcp#managed-mcp-configuration) | `[{ "serverName": "github" }]` |

166| `deniedMcpServers` | When set in managed-settings.json, denylist of MCP servers that are explicitly blocked. Applies to all scopes including managed servers. Denylist takes precedence over allowlist. See [Managed MCP configuration](/en/mcp#managed-mcp-configuration) | `[{ "serverName": "filesystem" }]` |196| `deniedMcpServers` | When set in managed-settings.json, denylist of MCP servers that are explicitly blocked. Applies to all scopes including managed servers. Denylist takes precedence over allowlist. See [Managed MCP configuration](/en/mcp#managed-mcp-configuration) | `[{ "serverName": "filesystem" }]` |

167| `strictKnownMarketplaces` | When set in managed-settings.json, allowlist of plugin marketplaces users can add. Undefined = no restrictions, empty array = lockdown. Applies to marketplace additions only. See [Managed marketplace restrictions](/en/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "acme-corp/plugins" }]` |197| `strictKnownMarketplaces` | When set in managed-settings.json, allowlist of plugin marketplaces users can add. Undefined = no restrictions, empty array = lockdown. Applies to marketplace additions only. See [Managed marketplace restrictions](/en/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "acme-corp/plugins" }]` |

198| `blockedMarketplaces` | (Managed settings only) Blocklist of marketplace sources. Blocked sources are checked before downloading, so they never touch the filesystem. See [Managed marketplace restrictions](/en/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "untrusted/plugins" }]` |

199| `pluginTrustMessage` | (Managed settings only) Custom message appended to the plugin trust warning shown before installation. Use this to add organization-specific context, for example to confirm that plugins from your internal marketplace are vetted. | `"All plugins from our marketplace are approved by IT"` |

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

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

170| `alwaysThinkingEnabled` | Enable [extended thinking](/en/common-workflows#use-extended-thinking-thinking-mode) by default for all sessions. Typically configured via the `/config` command rather than editing directly | `true` |202| `alwaysThinkingEnabled` | Enable [extended thinking](/en/common-workflows#use-extended-thinking-thinking-mode) by default for all sessions. Typically configured via the `/config` command rather than editing directly | `true` |

173| `spinnerVerbs` | Customize the action verbs shown in the spinner and turn duration messages. Set `mode` to `"replace"` to use only your verbs, or `"append"` to add them to the defaults | `{"mode": "append", "verbs": ["Pondering", "Crafting"]}` |205| `spinnerVerbs` | Customize the action verbs shown in the spinner and turn duration messages. Set `mode` to `"replace"` to use only your verbs, or `"append"` to add them to the defaults | `{"mode": "append", "verbs": ["Pondering", "Crafting"]}` |

174| `language` | Configure Claude's preferred response language (e.g., `"japanese"`, `"spanish"`, `"french"`). Claude will respond in this language by default | `"japanese"` |206| `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"` |

207| `voiceEnabled` | Enable push-to-talk [voice dictation](/en/voice-dictation). Written automatically when you run `/voice`. Requires a Claude.ai account | `true` |

175| `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 | `"stable"` |208| `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 | `"stable"` |

177| `terminalProgressBarEnabled` | Enable the terminal progress bar that shows progress in supported terminals like Windows Terminal and iTerm2 (default: `true`) | `false` |210| `spinnerTipsOverride` | Override spinner tips with custom strings. `tips`: array of tip strings. `excludeDefault`: if `true`, only show custom tips; if `false` or absent, custom tips are merged with built-in tips | `{ "excludeDefault": true, "tips": ["Use our internal tool X"] }` |

211| `prefersReducedMotion` | Reduce or disable UI animations (spinners, shimmer, flash effects) for accessibility | `true` |

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

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

178 214

179### Permission settings215### Global config settings

180 216

181| Keys | Description | Example |217These settings are stored in `~/.claude.json` rather than `settings.json`. Adding them to `settings.json` will trigger a schema validation error.

182| :----------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------- |

183| `allow` | Array of permission rules to allow tool use. See [Permission rule syntax](#permission-rule-syntax) below for pattern matching details | `[ "Bash(git diff *)" ]` |

184| `ask` | Array of permission rules to ask for confirmation upon tool use. See [Permission rule syntax](#permission-rule-syntax) below | `[ "Bash(git push *)" ]` |

185| `deny` | Array of permission rules to deny tool use. Use this to exclude sensitive files from Claude Code access. See [Permission rule syntax](#permission-rule-syntax) and [Bash permission limitations](/en/iam#tool-specific-permission-rules) | `[ "WebFetch", "Bash(curl *)", "Read(./.env)", "Read(./secrets/**)" ]` |

186| `additionalDirectories` | Additional [working directories](/en/iam#working-directories) that Claude has access to | `[ "../docs/" ]` |

187| `defaultMode` | Default [permission mode](/en/iam#permission-modes) when opening Claude Code | `"acceptEdits"` |

188| `disableBypassPermissionsMode` | Set to `"disable"` to prevent `bypassPermissions` mode from being activated. This disables the `--dangerously-skip-permissions` command-line flag. See [managed settings](/en/iam#managed-settings) | `"disable"` |

~~189~~

190### Permission rule syntax

~~191~~

192Permission rules follow the format `Tool` or `Tool(specifier)`. Understanding the syntax helps you write rules that match exactly what you intend.

193 218

194#### Rule evaluation order219| Key | Description | Example |

220| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------- |

221| `autoConnectIde` | Automatically connect to a running IDE when Claude Code starts from an external terminal. Default: `false`. Appears in `/config` as **Auto-connect to IDE (external terminal)** when running outside a VS Code or JetBrains terminal | `true` |

222| `autoInstallIdeExtension` | Automatically install the Claude Code IDE extension when running from a VS Code terminal. Default: `true`. Appears in `/config` as **Auto-install IDE extension** when running inside a VS Code or JetBrains terminal. You can also set the [`CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL`](/en/env-vars) environment variable | `false` |

223| `editorMode` | Key binding mode for the input prompt: `"normal"` or `"vim"`. Default: `"normal"`. Written automatically when you run `/vim`. Appears in `/config` as **Key binding mode** | `"vim"` |

224| `showTurnDuration` | Show turn duration messages after responses, e.g. "Cooked for 1m 6s". Default: `true`. Appears in `/config` as **Show turn duration** | `false` |

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

226| `teammateMode` | How [agent team](/en/agent-teams) teammates display: `auto` (picks split panes in tmux or iTerm2, in-process otherwise), `in-process`, or `tmux`. See [choose a display mode](/en/agent-teams#choose-a-display-mode) | `"in-process"` |

195 227

196When multiple rules could match the same tool use, rules are evaluated in this order:228### Worktree settings

197 229

1981. **Deny** rules are checked first230Configure how `--worktree` creates and manages git worktrees. Use these settings to reduce disk usage and startup time in large monorepos.

1992. **Ask** rules are checked second

2003. **Allow** rules are checked last

201 231

202The first matching rule determines the behavior. This means deny rules always take precedence over allow rules, even if both match the same command.232| Key | Description | Example |

233| :---------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------ |

234| `worktree.symlinkDirectories` | Directories to symlink from the main repository into each worktree to avoid duplicating large directories on disk. No directories are symlinked by default | `["node_modules", ".cache"]` |

235| `worktree.sparsePaths` | Directories to check out in each worktree via git sparse-checkout (cone mode). Only the listed paths are written to disk, which is faster in large monorepos | `["packages/my-app", "shared/utils"]` |

203 236

204#### Matching all uses of a tool237To copy gitignored files like `.env` into new worktrees, use a [`.worktreeinclude` file](/en/common-workflows#copy-gitignored-files-to-worktrees) in your project root instead of a setting.

205 238

206To match all uses of a tool, use just the tool name without parentheses:239### Permission settings

207 240

209| :--------- | :--------------------------------- |242| :----------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------- |

211| `WebFetch` | Matches **all** web fetch requests |244| `ask` | Array of permission rules to ask for confirmation upon tool use. See [Permission rule syntax](#permission-rule-syntax) below | `[ "Bash(git push *)" ]` |

212| `Read` | Matches **all** file reads |245| `deny` | Array of permission rules to deny tool use. Use this to exclude sensitive files from Claude Code access. See [Permission rule syntax](#permission-rule-syntax) and [Bash permission limitations](/en/permissions#tool-specific-permission-rules) | `[ "WebFetch", "Bash(curl *)", "Read(./.env)", "Read(./secrets/**)" ]` |

246| `additionalDirectories` | Additional [working directories](/en/permissions#working-directories) that Claude has access to | `[ "../docs/" ]` |

247| `defaultMode` | Default [permission mode](/en/permission-modes) when opening Claude Code | `"acceptEdits"` |

248| `disableBypassPermissionsMode` | Set to `"disable"` to prevent `bypassPermissions` mode from being activated. Disables the `--dangerously-skip-permissions` flag. Most useful in [managed settings](/en/permissions#managed-settings) where users cannot override it | `"disable"` |

213 249

214`Bash(*)` is equivalent to `Bash` and matches all Bash commands. Both syntaxes can be used interchangeably.250### Permission rule syntax

215 251

216#### Using specifiers for fine-grained control252Permission rules follow the format `Tool` or `Tool(specifier)`. Rules are evaluated in order: deny rules first, then ask, then allow. The first matching rule wins.

217 253

218Add a specifier in parentheses to match specific tool uses:254Quick examples:

219 255

220| Rule | Effect |256| Rule | Effect |

221| :----------------------------- | :------------------------------------------------------- |257| :----------------------------- | :--------------------------------------- |

260| `Read(./.env)` | Matches reading the `.env` file |

225 262

226#### Wildcard patterns263For the complete rule syntax reference, including wildcard behavior, tool-specific patterns for Read, Edit, WebFetch, MCP, and Agent rules, and security limitations of Bash patterns, see [Permission rule syntax](/en/permissions#permission-rule-syntax).

~~227~~

228Bash rules support glob patterns with `*`. Wildcards can appear at any position in the command, including at the beginning, middle, or end. The following configuration allows npm and git commit commands while blocking git push:

~~229~~

230```json theme={null}

231{

232 "permissions": {

233 "allow": [

234 "Bash(npm run *)",

235 "Bash(git commit *)",

236 "Bash(git * main)",

237 "Bash(* --version)",

238 "Bash(* --help *)"

239 ],

240 "deny": [

241 "Bash(git push *)"

242 ]

243 }

244}

245```

~~246~~

247The space before `*` matters: `Bash(ls *)` matches `ls -la` but not `lsof`, while `Bash(ls*)` matches both. The legacy `:*` suffix syntax (e.g., `Bash(npm run:*)`) is equivalent to ` *` but is deprecated.

~~248~~

249<Warning>

250 Bash permission patterns that try to constrain command arguments are fragile. For example, `Bash(curl http://github.com/ *)` intends to restrict curl to GitHub URLs, but won't match `curl -X GET http://github.com/...` (flags before URL), `curl https://github.com/...` (different protocol), or commands using shell variables. Do not rely on argument-constraining patterns as a security boundary. See [Bash permission limitations](/en/iam#tool-specific-permission-rules) for alternatives.

251</Warning>

~~252~~

253For detailed information about tool-specific permission patterns—including Read, Edit, WebFetch, MCP, Task rules, and Bash permission limitations—see [Tool-specific permission rules](/en/iam#tool-specific-permission-rules).

254 264

255### Sandbox settings265### Sandbox settings

256 266

257Configure advanced sandboxing behavior. Sandboxing isolates bash commands from your filesystem and network. See [Sandboxing](/en/sandboxing) for details.267Configure advanced sandboxing behavior. Sandboxing isolates bash commands from your filesystem and network. See [Sandboxing](/en/sandboxing) for details.

258 268

259**Filesystem and network restrictions** are configured via Read, Edit, and WebFetch permission rules, not via these sandbox settings.

~~260~~

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

272| `failIfUnavailable` | Exit with an error at startup if `sandbox.enabled` is true but the sandbox cannot start (missing dependencies, unsupported platform, or platform restrictions). When false (default), a warning is shown and commands run unsandboxed. Intended for managed settings deployments that require sandboxing as a hard gate | `true` |

266| `allowUnsandboxedCommands` | Allow commands to run outside the sandbox via the `dangerouslyDisableSandbox` parameter. When set to `false`, the `dangerouslyDisableSandbox` escape hatch is completely disabled and all commands must run sandboxed (or be in `excludedCommands`). Useful for enterprise policies that require strict sandboxing. Default: true | `false` |275| `allowUnsandboxedCommands` | Allow commands to run outside the sandbox via the `dangerouslyDisableSandbox` parameter. When set to `false`, the `dangerouslyDisableSandbox` escape hatch is completely disabled and all commands must run sandboxed (or be in `excludedCommands`). Useful for enterprise policies that require strict sandboxing. Default: true | `false` |

276| `filesystem.allowWrite` | Additional paths where sandboxed commands can write. Arrays are merged across all settings scopes: user, project, and managed paths are combined, not replaced. Also merged with paths from `Edit(...)` allow permission rules. See [path prefixes](#sandbox-path-prefixes) below. | `["/tmp/build", "~/.kube"]` |

277| `filesystem.denyWrite` | Paths where sandboxed commands cannot write. Arrays are merged across all settings scopes. Also merged with paths from `Edit(...)` deny permission rules. | `["/etc", "/usr/local/bin"]` |

278| `filesystem.denyRead` | Paths where sandboxed commands cannot read. Arrays are merged across all settings scopes. Also merged with paths from `Read(...)` deny permission rules. | `["~/.aws/credentials"]` |

279| `filesystem.allowRead` | Paths to re-allow reading within `denyRead` regions. Takes precedence over `denyRead`. Arrays are merged across all settings scopes. Use this to create workspace-only read access patterns. | `["."]` |

280| `filesystem.allowManagedReadPathsOnly` | (Managed settings only) Only `allowRead` paths from managed settings are respected. `allowRead` entries from user, project, and local settings are ignored. Default: false | `true` |

285| `network.allowManagedDomainsOnly` | (Managed settings only) Only `allowedDomains` and `WebFetch(domain:...)` allow rules from managed settings are respected. Domains from user, project, and local settings are ignored. Non-allowed domains are blocked automatically without prompting the user. Denied domains are still respected from all sources. Default: false | `true` |

271| `network.httpProxyPort` | HTTP proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. | `8080` |286| `network.httpProxyPort` | HTTP proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. | `8080` |

272| `network.socksProxyPort` | SOCKS5 proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. | `8081` |287| `network.socksProxyPort` | SOCKS5 proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. | `8081` |

289| `enableWeakerNetworkIsolation` | (macOS only) Allow access to the system TLS trust service (`com.apple.trustd.agent`) in the sandbox. Required for Go-based tools like `gh`, `gcloud`, and `terraform` to verify TLS certificates when using `httpProxyPort` with a MITM proxy and custom CA. **Reduces security** by opening a potential data exfiltration path. Default: false | `true` |

290

291#### Sandbox path prefixes

292

293Paths in `filesystem.allowWrite`, `filesystem.denyWrite`, `filesystem.denyRead`, and `filesystem.allowRead` support these prefixes:

294

295| Prefix | Meaning | Example |

296| :---------------- | :------------------------------------------------------------------------------------- | :------------------------------------------------------------------------ |

297| `/` | Absolute path from filesystem root | `/tmp/build` stays `/tmp/build` |

298| `~/` | Relative to home directory | `~/.kube` becomes `$HOME/.kube` |

299| `./` or no prefix | Relative to the project root for project settings, or to `~/.claude` for user settings | `./output` in `.claude/settings.json` resolves to `<project-root>/output` |

300

301The older `//path` prefix for absolute paths still works. If you previously used single-slash `/path` expecting project-relative resolution, switch to `./path`. This syntax differs from [Read and Edit permission rules](/en/permissions#read-and-edit), which use `//path` for absolute and `/path` for project-relative. Sandbox filesystem paths use standard conventions: `/tmp/build` is an absolute path.

274 302

275**Configuration example:**303**Configuration example:**

276 304

280 "enabled": true,308 "enabled": true,

281 "autoAllowBashIfSandboxed": true,309 "autoAllowBashIfSandboxed": true,

282 "excludedCommands": ["docker"],310 "excludedCommands": ["docker"],

311 "filesystem": {

312 "allowWrite": ["/tmp/build", "~/.kube"],

313 "denyRead": ["~/.aws/credentials"]

314 },

283 "network": {315 "network": {

284 "allowedDomains": ["github.com", "*.npmjs.org", "registry.yarnpkg.com"],316 "allowedDomains": ["github.com", "*.npmjs.org", "registry.yarnpkg.com"],

285 "allowUnixSockets": [317 "allowUnixSockets": [

287 ],319 ],

288 "allowLocalBinding": true320 "allowLocalBinding": true

289 }321 }

290 },

291 "permissions": {

292 "deny": [

293 "Read(.envrc)",

294 "Read(~/.aws/**)"

295 ]

296 }322 }

297}323}

298```324```

299 325

300**Filesystem and network restrictions** use standard permission rules:326**Filesystem and network restrictions** can be configured in two ways that are merged together:

301 327

302* Use `Read` deny rules to block Claude from reading specific files or directories328* **`sandbox.filesystem` settings** (shown above): Control paths at the OS-level sandbox boundary. These restrictions apply to all subprocess commands (e.g., `kubectl`, `terraform`, `npm`), not just Claude's file tools.

303* Use `Edit` allow rules to let Claude write to directories beyond the current working directory329* **Permission rules**: Use `Edit` allow/deny rules to control Claude's file tool access, `Read` deny rules to block reads, and `WebFetch` allow/deny rules to control network domains. Paths from these rules are also merged into the sandbox configuration.

304* Use `Edit` deny rules to block writes to specific paths

305* Use `WebFetch` allow/deny rules to control which network domains Claude can access

306 330

307### Attribution settings331### Attribution settings

308 332

318 342

319**Default commit attribution:**343**Default commit attribution:**

320 344

321```345```text theme={null}

322🤖 Generated with [Claude Code](https://claude.com/claude-code)346🤖 Generated with [Claude Code](https://claude.com/claude-code)

323 347

324 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>348 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

325```349```

326 350

327**Default pull request attribution:**351**Default pull request attribution:**

328 352

329```353```text theme={null}

330🤖 Generated with [Claude Code](https://claude.com/claude-code)354🤖 Generated with [Claude Code](https://claude.com/claude-code)

331```355```

332 356

366 390

367Output newline-separated file paths to stdout (currently limited to 15):391Output newline-separated file paths to stdout (currently limited to 15):

368 392

369```393```text theme={null}

370src/components/Button.tsx394src/components/Button.tsx

371src/components/Modal.tsx395src/components/Modal.tsx

372src/components/Form.tsx396src/components/Form.tsx

382 406

383### Hook configuration407### Hook configuration

384 408

385**Managed settings only**: Controls which hooks are allowed to run. This setting can only be configured in [managed settings](#settings-files) and provides administrators with strict control over hook execution.409These 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.

386 410

387**Behavior when `allowManagedHooksOnly` is `true`:**411**Behavior when `allowManagedHooksOnly` is `true`:**

388 412

389* Managed hooks and SDK hooks are loaded413* Managed hooks and SDK hooks are loaded

390* User hooks, project hooks, and plugin hooks are blocked414* User hooks, project hooks, and plugin hooks are blocked

391 415

392**Configuration:**416**Restrict HTTP hook URLs:**

417

418Limit which URLs HTTP hooks can target. Supports `*` as a wildcard for matching. When the array is defined, HTTP hooks targeting non-matching URLs are silently blocked.

393 419

394```json theme={null}420```json theme={null}

395{421{

396 "allowManagedHooksOnly": true422 "allowedHttpHookUrls": ["https://hooks.example.com/*", "http://localhost:*"]

423}

424```

425

426**Restrict HTTP hook environment variables:**

427

428Limit which environment variable names HTTP hooks can interpolate into header values. Each hook's effective `allowedEnvVars` is the intersection of its own list and this setting.

429

430```json theme={null}

431{

432 "httpHookAllowedEnvVars": ["MY_TOKEN", "HOOK_SECRET"]

397}433}

398```434```

399 435

401 437

402Settings apply in order of precedence. From highest to lowest:438Settings apply in order of precedence. From highest to lowest:

403 439

4041. **Managed settings** (`managed-settings.json`)4401. **Managed settings** ([server-managed](/en/server-managed-settings), [MDM/OS-level policies](#configuration-scopes), or [managed settings](/en/settings#settings-files))

405 * Policies deployed by IT/DevOps to system directories441 * Policies deployed by IT through server delivery, MDM configuration profiles, registry policies, or managed settings files

406 * Cannot be overridden by user or project settings442 * Cannot be overridden by any other level, including command line arguments

443 * Within the managed tier, precedence is: server-managed > MDM/OS-level policies > file-based (`managed-settings.d/*.json` + `managed-settings.json`) > HKCU registry (Windows only). Only one managed source is used; sources do not merge across tiers. Within the file-based tier, drop-in files and the base file are merged together.

407 444

4082. **Command line arguments**4452. **Command line arguments**

409 * Temporary overrides for a specific session446 * Temporary overrides for a specific session

4175. **User settings** (`~/.claude/settings.json`)4545. **User settings** (`~/.claude/settings.json`)

418 * Personal global settings455 * Personal global settings

419 456

420This hierarchy ensures that organizational policies are always enforced while still allowing teams and individuals to customize their experience.457This hierarchy ensures that organizational policies are always enforced while still allowing teams and individuals to customize their experience. The same precedence applies whether you run Claude Code from the CLI, the [VS Code extension](/en/vs-code), or a [JetBrains IDE](/en/jetbrains).

421 458

422For example, if your user settings allow `Bash(npm run *)` but a project's shared settings deny it, the project setting takes precedence and the command is blocked.459For example, if your user settings allow `Bash(npm run *)` but a project's shared settings deny it, the project setting takes precedence and the command is blocked.

423 460

461<Note>

462 **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.

463</Note>

464

465### Verify active settings

466

467Run `/status` inside Claude Code to see which settings sources are active and where they come from. The output shows each configuration layer (managed, user, project) along with its origin, such as `Enterprise managed settings (remote)`, `Enterprise managed settings (plist)`, `Enterprise managed settings (HKLM)`, or `Enterprise managed settings (file)`. If a settings file contains errors, `/status` reports the issue so you can fix it.

468

424### Key points about the configuration system469### Key points about the configuration system

425 470

426* **Memory files (`CLAUDE.md`)**: Contain instructions and context that Claude loads at startup471* **Memory files (`CLAUDE.md`)**: Contain instructions and context that Claude loads at startup

496* **User settings** (`~/.claude/settings.json`): Personal plugin preferences541* **User settings** (`~/.claude/settings.json`): Personal plugin preferences

497* **Project settings** (`.claude/settings.json`): Project-specific plugins shared with team542* **Project settings** (`.claude/settings.json`): Project-specific plugins shared with team

498* **Local settings** (`.claude/settings.local.json`): Per-machine overrides (not committed)543* **Local settings** (`.claude/settings.local.json`): Per-machine overrides (not committed)

544* **Managed settings** (`managed-settings.json`): Organization-wide policy overrides that block installation at all scopes and hide the plugin from the marketplace

499 545

500**Example**:546**Example**:

501 547

547* `git`: Any git URL (uses `url`)593* `git`: Any git URL (uses `url`)

548* `directory`: Local filesystem path (uses `path`, for development only)594* `directory`: Local filesystem path (uses `path`, for development only)

549* `hostPattern`: regex pattern to match marketplace hosts (uses `hostPattern`)595* `hostPattern`: regex pattern to match marketplace hosts (uses `hostPattern`)

596* `settings`: inline marketplace declared directly in settings.json without a separate hosted repository (uses `name` and `plugins`)

597

598Use `source: 'settings'` to declare a small set of plugins inline without setting up a hosted marketplace repository. Plugins listed here must reference external sources such as GitHub or npm. You still need to enable each plugin separately in `enabledPlugins`.

599

600```json theme={null}

601{

602 "extraKnownMarketplaces": {

603 "team-tools": {

604 "source": {

605 "source": "settings",

606 "name": "team-tools",

607 "plugins": [

608 {

609 "name": "code-formatter",

610 "source": {

611 "source": "github",

612 "repo": "acme-corp/code-formatter"

613 }

614 }

615 ]

616 }

617 }

618 }

619}

620```

550 621

551#### `strictKnownMarketplaces`622#### `strictKnownMarketplaces`

552 623

553**Managed settings only**: Controls which plugin marketplaces users are allowed to add. This setting can only be configured in [`managed-settings.json`](/en/iam#managed-settings) and provides administrators with strict control over marketplace sources.624**Managed settings only**: Controls which plugin marketplaces users are allowed to add. This setting can only be configured in [managed settings](/en/settings#settings-files) and provides administrators with strict control over marketplace sources.

554 625

555**Managed settings file locations**:626**Managed settings file locations**:

556 627

573 644

574**All supported source types**:645**All supported source types**:

575 646

576The allowlist supports seven marketplace source types. Most sources use exact matching, while `hostPattern` uses regex matching against the marketplace host.647The allowlist supports multiple marketplace source types. Most sources use exact matching, while `hostPattern` uses regex matching against the marketplace host.

577 648

5781. **GitHub repositories**:6491. **GitHub repositories**:

579 650

758}829}

759```830```

760 831

832**Using both together**:

833

834`strictKnownMarketplaces` is a policy gate: it controls what users may add but does not register any marketplaces. To both restrict and pre-register a marketplace for all users, set both in `managed-settings.json`:

835

836```json theme={null}

837{

838 "strictKnownMarketplaces": [

839 { "source": "github", "repo": "acme-corp/plugins" }

840 ],

841 "extraKnownMarketplaces": {

842 "acme-tools": {

843 "source": { "source": "github", "repo": "acme-corp/plugins" }

844 }

845 }

846}

847```

848

849With only `strictKnownMarketplaces` set, users can still add the allowed marketplace manually via `/plugin marketplace add`, but it is not available automatically.

850

761**Important notes**:851**Important notes**:

762 852

763* Restrictions are checked BEFORE any network requests or filesystem operations853* Restrictions are checked BEFORE any network requests or filesystem operations

781 871

782## Environment variables872## Environment variables

783 873

784Claude Code supports the following environment variables to control its behavior:874Environment variables let you control Claude Code behavior without editing settings files. Any variable can also be configured in [`settings.json`](#available-settings) under the `env` key to apply it to every session or roll it out to your team.

~~785~~

786<Note>

787 All environment variables can also be configured in [`settings.json`](#available-settings). This is useful as a way to automatically set environment variables for each session, or to roll out a set of environment variables for your whole team or organization.

788</Note>

789 875

790| Variable | Purpose | |876See the [environment variables reference](/en/env-vars) for the full list.

791| :--------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- |

792| `ANTHROPIC_API_KEY` | API key sent as `X-Api-Key` header, typically for the Claude SDK (for interactive usage, run `/login`) | |

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

794| `ANTHROPIC_CUSTOM_HEADERS` | Custom headers to add to requests (`Name: Value` format, newline-separated for multiple headers) | |

795| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | See [Model configuration](/en/model-config#environment-variables) | |

796| `ANTHROPIC_DEFAULT_OPUS_MODEL` | See [Model configuration](/en/model-config#environment-variables) | |

797| `ANTHROPIC_DEFAULT_SONNET_MODEL` | See [Model configuration](/en/model-config#environment-variables) | |

798| `ANTHROPIC_FOUNDRY_API_KEY` | API key for Microsoft Foundry authentication (see [Microsoft Foundry](/en/microsoft-foundry)) | |

799| `ANTHROPIC_FOUNDRY_BASE_URL` | Full base URL for the Foundry resource (for example, `https://my-resource.services.ai.azure.com/anthropic`). Alternative to `ANTHROPIC_FOUNDRY_RESOURCE` (see [Microsoft Foundry](/en/microsoft-foundry)) | |

800| `ANTHROPIC_FOUNDRY_RESOURCE` | Foundry resource name (for example, `my-resource`). Required if `ANTHROPIC_FOUNDRY_BASE_URL` is not set (see [Microsoft Foundry](/en/microsoft-foundry)) | |

801| `ANTHROPIC_MODEL` | Name of the model setting to use (see [Model Configuration](/en/model-config#environment-variables)) | |

802| `ANTHROPIC_SMALL_FAST_MODEL` | \[DEPRECATED] Name of [Haiku-class model for background tasks](/en/costs) | |

803| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | Override AWS region for the Haiku-class model when using Bedrock | |

804| `AWS_BEARER_TOKEN_BEDROCK` | Bedrock API key for authentication (see [Bedrock API keys](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)) | |

805| `BASH_DEFAULT_TIMEOUT_MS` | Default timeout for long-running bash commands | |

806| `BASH_MAX_OUTPUT_LENGTH` | Maximum number of characters in bash outputs before they are middle-truncated | |

807| `BASH_MAX_TIMEOUT_MS` | Maximum timeout the model can set for long-running bash commands | |

808| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | Set the percentage of context capacity (1-100) at which auto-compaction triggers. By default, auto-compaction triggers at approximately 95% capacity. Use lower values like `50` to compact earlier. Values above the default threshold have no effect. Applies to both main conversations and subagents. This percentage aligns with the `context_window.used_percentage` field available in [status line](/en/statusline) | |

809| `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR` | Return to the original working directory after each Bash command | |

810| `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` | Set to `1` to load CLAUDE.md files from directories specified with `--add-dir`. By default, additional directories do not load memory files | `1` |

811| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` | Interval in milliseconds at which credentials should be refreshed (when using `apiKeyHelper`) | |

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

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

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

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

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

817| `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) | |

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

819| `CLAUDE_CODE_PROXY_RESOLVES_HOSTS` | Set to `true` to allow the proxy to perform DNS resolution instead of the caller. Opt-in for environments where the proxy should handle hostname resolution | |

820| `CLAUDE_CODE_TASK_LIST_ID` | Share a task list across sessions. Set the same ID in multiple Claude Code instances to coordinate on a shared task list. See [Task list](/en/interactive-mode#task-list) | |

821| `CLAUDE_CODE_TMPDIR` | Override the temp directory used for internal temp files. Claude Code appends `/claude/` to this path. Default: `/tmp` on Unix/macOS, `os.tmpdir()` on Windows | |

822| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | Equivalent of setting `DISABLE_AUTOUPDATER`, `DISABLE_BUG_COMMAND`, `DISABLE_ERROR_REPORTING`, and `DISABLE_TELEMETRY` | |

823| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | Set to `1` to disable automatic terminal title updates based on conversation context | |

824| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | Set to `false` to disable prompt suggestions (the "Prompt suggestions" toggle in `/config`). These are the grayed-out predictions that appear in your prompt input after Claude responds. See [Prompt suggestions](/en/interactive-mode#prompt-suggestions) | |

825| `CLAUDE_CODE_ENABLE_TASKS` | Set to `false` to temporarily revert to the previous TODO list instead of the task tracking system. Default: `true`. See [Task list](/en/interactive-mode#task-list) | |

826| `CLAUDE_CODE_ENABLE_TELEMETRY` | Set to `1` to enable OpenTelemetry data collection for metrics and logging. Required before configuring OTel exporters. See [Monitoring](/en/monitoring-usage) | |

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

828| `CLAUDE_CODE_HIDE_ACCOUNT_INFO` | Set to `1` to hide your email address and organization name from the Claude Code UI. Useful when streaming or recording | |

829| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | Skip auto-installation of IDE extensions | |

830| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | Set the maximum number of output tokens for most requests. Default: 32,000. Maximum: 64,000. Increasing this value reduces the effective context window available before [auto-compaction](/en/costs#reduce-token-usage) triggers. | |

831| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | Interval for refreshing dynamic OpenTelemetry headers in milliseconds (default: 1740000 / 29 minutes). See [Dynamic headers](/en/monitoring-usage#dynamic-headers) | |

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

833| `CLAUDE_CODE_SHELL_PREFIX` | Command prefix to wrap all bash commands (for example, for logging or auditing). Example: `/path/to/logger.sh` will execute `/path/to/logger.sh <command>` | |

834| `CLAUDE_CODE_SKIP_BEDROCK_AUTH` | Skip AWS authentication for Bedrock (for example, when using an LLM gateway) | |

835| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | Skip Azure authentication for Microsoft Foundry (for example, when using an LLM gateway) | |

836| `CLAUDE_CODE_SKIP_VERTEX_AUTH` | Skip Google authentication for Vertex (for example, when using an LLM gateway) | |

837| `CLAUDE_CODE_SUBAGENT_MODEL` | See [Model configuration](/en/model-config) | |

838| `CLAUDE_CODE_USE_BEDROCK` | Use [Bedrock](/en/amazon-bedrock) | |

839| `CLAUDE_CODE_USE_FOUNDRY` | Use [Microsoft Foundry](/en/microsoft-foundry) | |

840| `CLAUDE_CODE_USE_VERTEX` | Use [Vertex](/en/google-vertex-ai) | |

841| `CLAUDE_CONFIG_DIR` | Customize where Claude Code stores its configuration and data files | |

842| `DISABLE_AUTOUPDATER` | Set to `1` to disable automatic updates. | |

843| `DISABLE_BUG_COMMAND` | Set to `1` to disable the `/bug` command | |

844| `DISABLE_COST_WARNINGS` | Set to `1` to disable cost warning messages | |

845| `DISABLE_ERROR_REPORTING` | Set to `1` to opt out of Sentry error reporting | |

846| `DISABLE_INSTALLATION_CHECKS` | Set to `1` to disable installation warnings. Use only when manually managing the installation location, as this can mask issues with standard installations | |

847| `DISABLE_NON_ESSENTIAL_MODEL_CALLS` | Set to `1` to disable model calls for non-critical paths like flavor text | |

848| `DISABLE_PROMPT_CACHING` | Set to `1` to disable prompt caching for all models (takes precedence over per-model settings) | |

849| `DISABLE_PROMPT_CACHING_HAIKU` | Set to `1` to disable prompt caching for Haiku models | |

850| `DISABLE_PROMPT_CACHING_OPUS` | Set to `1` to disable prompt caching for Opus models | |

851| `DISABLE_PROMPT_CACHING_SONNET` | Set to `1` to disable prompt caching for Sonnet models | |

852| `DISABLE_TELEMETRY` | Set to `1` to opt out of Statsig telemetry (note that Statsig events do not include user data like code, file paths, or bash commands) | |

853| `ENABLE_TOOL_SEARCH` | Controls [MCP tool search](/en/mcp#scale-with-mcp-tool-search). Values: `auto` (default, enables at 10% context), `auto:N` (custom threshold, e.g., `auto:5` for 5%), `true` (always on), `false` (disabled) | |

854| `FORCE_AUTOUPDATE_PLUGINS` | Set to `true` to force plugin auto-updates even when the main auto-updater is disabled via `DISABLE_AUTOUPDATER` | |

855| `HTTP_PROXY` | Specify HTTP proxy server for network connections | |

856| `HTTPS_PROXY` | Specify HTTPS proxy server for network connections | |

857| `IS_DEMO` | Set to `true` to enable demo mode: hides email and organization from the UI, skips onboarding, and hides internal commands. Useful for streaming or recording sessions | |

858| `MAX_MCP_OUTPUT_TOKENS` | Maximum number of tokens allowed in MCP tool responses. Claude Code displays a warning when output exceeds 10,000 tokens (default: 25000) | |

859| `MAX_THINKING_TOKENS` | Override the [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) token budget. Thinking is enabled at max budget (31,999 tokens) by default. Use this to limit the budget (for example, `MAX_THINKING_TOKENS=10000`) or disable thinking entirely (`MAX_THINKING_TOKENS=0`). Extended thinking improves performance on complex reasoning and coding tasks but impacts [prompt caching efficiency](https://docs.claude.com/en/docs/build-with-claude/prompt-caching#caching-with-thinking-blocks). | |

860| `MCP_TIMEOUT` | Timeout in milliseconds for MCP server startup | |

861| `MCP_TOOL_TIMEOUT` | Timeout in milliseconds for MCP tool execution | |

862| `NO_PROXY` | List of domains and IPs to which requests will be directly issued, bypassing proxy | |

863| `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. | |

864| `USE_BUILTIN_RIPGREP` | Set to `0` to use system-installed `rg` instead of `rg` included with Claude Code | |

865| `VERTEX_REGION_CLAUDE_3_5_HAIKU` | Override region for Claude 3.5 Haiku when using Vertex AI | |

866| `VERTEX_REGION_CLAUDE_3_7_SONNET` | Override region for Claude 3.7 Sonnet when using Vertex AI | |

867| `VERTEX_REGION_CLAUDE_4_0_OPUS` | Override region for Claude 4.0 Opus when using Vertex AI | |

868| `VERTEX_REGION_CLAUDE_4_0_SONNET` | Override region for Claude 4.0 Sonnet when using Vertex AI | |

869| `VERTEX_REGION_CLAUDE_4_1_OPUS` | Override region for Claude 4.1 Opus when using Vertex AI | |

870 877

871## Tools available to Claude878## Tools available to Claude

872 879

873Claude Code has access to a set of powerful tools that help it understand and modify your codebase:880Claude Code has access to a set of tools for reading, editing, searching, running commands, and orchestrating subagents. Tool names are the exact strings you use in permission rules and hook matchers.

~~874~~

875| Tool | Description | Permission Required |

876| :------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------ |

877| **AskUserQuestion** | Asks multiple-choice questions to gather requirements or clarify ambiguity | No |

878| **Bash** | Executes shell commands in your environment (see [Bash tool behavior](#bash-tool-behavior) below) | Yes |

879| **TaskOutput** | Retrieves output from a background task (bash shell or subagent) | No |

880| **Edit** | Makes targeted edits to specific files | Yes |

881| **ExitPlanMode** | Prompts the user to exit plan mode and start coding | Yes |

882| **Glob** | Finds files based on pattern matching | No |

883| **Grep** | Searches for patterns in file contents | No |

884| **KillShell** | Kills a running background bash shell by its ID | No |

885| **MCPSearch** | Searches for and loads MCP tools when [tool search](/en/mcp#scale-with-mcp-tool-search) is enabled | No |

886| **NotebookEdit** | Modifies Jupyter notebook cells | Yes |

887| **Read** | Reads the contents of files | No |

888| **Skill** | Executes a [skill](/en/skills#control-who-invokes-a-skill) within the main conversation | Yes |

889| **Task** | Runs a sub-agent to handle complex, multi-step tasks | No |

890| **TaskCreate** | Creates a new task in the task list | No |

891| **TaskGet** | Retrieves full details for a specific task | No |

892| **TaskList** | Lists all tasks with their current status | No |

893| **TaskUpdate** | Updates task status, dependencies, details, or deletes tasks | No |

894| **WebFetch** | Fetches content from a specified URL | Yes |

895| **WebSearch** | Performs web searches with domain filtering | Yes |

896| **Write** | Creates or overwrites files | Yes |

897| **LSP** | Code intelligence via language servers. Reports type errors and warnings automatically after file edits. Also supports navigation operations: jump to definitions, find references, get type info, list symbols, find implementations, trace call hierarchies. Requires a [code intelligence plugin](/en/discover-plugins#code-intelligence) and its language server binary | No |

~~898~~

899Permission rules can be configured using `/allowed-tools` or in [permission settings](/en/settings#available-settings). Also see [Tool-specific permission rules](/en/iam#tool-specific-permission-rules).

~~900~~

901### Bash tool behavior

~~902~~

903The Bash tool executes shell commands with the following persistence behavior:

~~904~~

905* **Working directory persists**: When Claude changes the working directory (for example, `cd /path/to/dir`), subsequent Bash commands will execute in that directory. You can use `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1` to reset to the project directory after each command.

906* **Environment variables do NOT persist**: Environment variables set in one Bash command (for example, `export MY_VAR=value`) are **not** available in subsequent Bash commands. Each Bash command runs in a fresh shell environment.

~~907~~

908To make environment variables available in Bash commands, you have **three options**:

~~909~~

910**Option 1: Activate environment before starting Claude Code** (simplest approach)

~~911~~

912Activate your virtual environment in your terminal before launching Claude Code:

~~913~~

914```bash theme={null}

915conda activate myenv

916# or: source /path/to/venv/bin/activate

917claude

918```

~~919~~

920This works for shell environments but environment variables set within Claude's Bash commands will not persist between commands.

~~921~~

922**Option 2: Set CLAUDE\_ENV\_FILE before starting Claude Code** (persistent environment setup)

~~923~~

924Export the path to a shell script containing your environment setup:

~~925~~

926```bash theme={null}

927export CLAUDE_ENV_FILE=/path/to/env-setup.sh

928claude

929```

~~930~~

931Where `/path/to/env-setup.sh` contains:

~~932~~

933```bash theme={null}

934conda activate myenv

935# or: source /path/to/venv/bin/activate

936# or: export MY_VAR=value

937```

~~938~~

939Claude Code will source this file before each Bash command, making the environment persistent across all commands.

~~940~~

941**Option 3: Use a SessionStart hook** (project-specific configuration)

~~942~~

943Configure in `.claude/settings.json`:

~~944~~

945```json theme={null}

946{

947 "hooks": {

948 "SessionStart": [{

949 "matcher": "startup",

950 "hooks": [{

951 "type": "command",

952 "command": "echo 'conda activate myenv' >> \"$CLAUDE_ENV_FILE\""

953 }]

954 }]

955 }

956}

957```

~~958~~

959The hook writes to `$CLAUDE_ENV_FILE`, which is then sourced before each Bash command. This is ideal for team-shared project configurations.

~~960~~

961See [SessionStart hooks](/en/hooks#persist-environment-variables) for more details on Option 3.

~~962~~

963### Extending tools with hooks

~~964~~

965You can run custom commands before or after any tool executes using

966[Claude Code hooks](/en/hooks-guide).

967 881

968For example, you could automatically run a Python formatter after Claude882See the [tools reference](/en/tools-reference) for the full list and Bash tool behavior details.

969modifies Python files, or prevent modifications to production configuration

970files by blocking Write operations to certain paths.

971 883

972## See also884## See also

973 885

974* [Identity and Access Management](/en/iam#configuring-permissions) - Permission system overview and how allow/ask/deny rules interact886* [Permissions](/en/permissions): permission system, rule syntax, tool-specific patterns, and managed policies

975* [Tool-specific permission rules](/en/iam#tool-specific-permission-rules) - Detailed patterns for Bash, Read, Edit, WebFetch, MCP, and Task tools, including security limitations887* [Authentication](/en/authentication): set up user access to Claude Code

976* [Managed settings](/en/iam#managed-settings) - Managed policy configuration for organizations888* [Troubleshooting](/en/troubleshooting): solutions for common configuration issues

977* [Troubleshooting](/en/troubleshooting) - Solutions for common configuration issues

setup.md +208 −148

Details

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt2> 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.3> Use this file to discover all available pages before exploring further.

4 4

~~5# Set up Claude Code~~5# Advanced setup

6 6

~~7> Install, authenticate, and start using Claude Code on your development machine.~~7> System requirements, platform-specific installation, version management, and uninstallation for Claude Code.

9This page covers system requirements, platform-specific installation details, updates, and uninstallation. For a guided walkthrough of your first session, see the [quickstart](/en/quickstart). If you've never used a terminal before, see the [terminal guide](/en/terminal-guide).

8 10

9## System requirements11## System requirements

10 12

~~11* **Operating Systems**: macOS 13.0+, Ubuntu 20.04+/Debian 10+, or Windows 10 1809+ / Windows Server 2019+ (with WSL 1, WSL 2, or Git for Windows)~~13Claude Code runs on the following platforms and configurations:

15* **Operating system**:

16 * macOS 13.0+

17 * Windows 10 1809+ or Windows Server 2019+

18 * Ubuntu 20.04+

19 * Debian 10+

20 * Alpine Linux 3.19+

12* **Hardware**: 4 GB+ RAM21* **Hardware**: 4 GB+ RAM

~~13* **Network**: Internet connection required (see [network configuration](/en/network-config#network-access-requirements))~~22* **Network**: internet connection required. See [network configuration](/en/network-config#network-access-requirements).

~~14* **Shell**: Works best in Bash or Zsh~~23* **Shell**: Bash, Zsh, PowerShell, or CMD. On Windows, [Git for Windows](https://git-scm.com/downloads/win) is required.

15* **Location**: [Anthropic supported countries](https://www.anthropic.com/supported-countries)24* **Location**: [Anthropic supported countries](https://www.anthropic.com/supported-countries)

16 25

17### Additional dependencies26### Additional dependencies

18 27

~~19* **ripgrep**: Usually included with Claude Code. If search fails, see [search troubleshooting](/en/troubleshooting#search-and-discovery-issues).~~28* **ripgrep**: usually included with Claude Code. If search fails, see [search troubleshooting](/en/troubleshooting#search-and-discovery-issues).

~~20* **[Node.js 18+](https://nodejs.org/en/download)**: Only required for [deprecated npm installation](#npm-installation-deprecated)~~29

30## Install Claude Code

21 31

~~22## Installation~~32<Tip>

33 Prefer a graphical interface? The [Desktop app](/en/desktop-quickstart) lets you use Claude Code without the terminal. Download it for [macOS](https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code\&utm_medium=docs) or [Windows](https://claude.ai/api/desktop/win32/x64/exe/latest/redirect?utm_source=claude_code\&utm_medium=docs).

35 New to the terminal? See the [terminal guide](/en/terminal-guide) for step-by-step instructions.

36</Tip>

23 37

24To install Claude Code, use one of the following methods:38To install Claude Code, use one of the following methods:

25 39

43 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd57 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

44 ```58 ```

45 59

60 **Windows requires [Git for Windows](https://git-scm.com/downloads/win).** Install it first if you don't have it.

46 <Info>62 <Info>

47 Native installations automatically update in the background to keep you on the latest version.63 Native installations automatically update in the background to keep you on the latest version.

48 </Info>64 </Info>

49 </Tab>65 </Tab>

50 66

51 <Tab title="Homebrew">67 <Tab title="Homebrew">

~~52 ```sh theme={null}~~68 ```bash theme={null}

53 brew install --cask claude-code69 brew install --cask claude-code

54 ```70 ```

55 71

69 </Tab>85 </Tab>

70</Tabs>86</Tabs>

71 87

~~72After the installation process completes, navigate to your project and start Claude Code:~~88After installation completes, open a terminal in the project you want to work in and start Claude Code:

73 89

74```bash theme={null}90```bash theme={null}

~~75cd your-awesome-project~~

76claude91claude

77```92```

78 93

~~79If you encounter any issues during installation, consult the [troubleshooting guide](/en/troubleshooting).~~94If you encounter any issues during installation, see the [troubleshooting guide](/en/troubleshooting).

80 95

~~81<Tip>~~96### Set up on Windows

~~82 Run `claude doctor` after installation to check your installation type and version.~~97

~~83</Tip>~~98Claude Code on Windows requires [Git for Windows](https://git-scm.com/downloads/win) or WSL. You can launch `claude` from PowerShell, CMD, or Git Bash. Claude Code uses Git Bash internally to run commands. You do not need to run PowerShell as Administrator.

100**Option 1: Native Windows with Git Bash**

101

102Install [Git for Windows](https://git-scm.com/downloads/win), then run the install command from PowerShell or CMD.

103

104If Claude Code can't find your Git Bash installation, set the path in your [settings.json file](/en/settings):

105

106```json theme={null}

107{

108 "env": {

109 "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"

110 }

111}

112```

113

114Claude Code can also run PowerShell natively on Windows as an opt-in preview. See [PowerShell tool](/en/tools-reference#powershell-tool) for setup and limitations.

115

116**Option 2: WSL**

117

118Both WSL 1 and WSL 2 are supported. WSL 2 supports [sandboxing](/en/sandboxing) for enhanced security. WSL 1 does not support sandboxing.

119

120### Alpine Linux and musl-based distributions

121

122The native installer on Alpine and other musl/uClibc-based distributions requires `libgcc`, `libstdc++`, and `ripgrep`. Install these using your distribution's package manager, then set `USE_BUILTIN_RIPGREP=0`.

123

124This example installs the required packages on Alpine:

125

126```bash theme={null}

127apk add libgcc libstdc++ ripgrep

128```

129

130Then set `USE_BUILTIN_RIPGREP` to `0` in your [`settings.json`](/en/settings#available-settings) file:

131

132```json theme={null}

133{

134 "env": {

135 "USE_BUILTIN_RIPGREP": "0"

136 }

137}

138```

139

140## Verify your installation

141

142After installing, confirm Claude Code is working:

143

144```bash theme={null}

145claude --version

146```

147

148For a more detailed check of your installation and configuration, run [`claude doctor`](/en/troubleshooting#get-more-help):

149

150```bash theme={null}

151claude doctor

152```

153

154## Authenticate

155

156Claude Code requires a Pro, Max, Teams, Enterprise, or Console account. The free Claude.ai plan does not include Claude Code access. You can also use Claude Code with a third-party API provider like [Amazon Bedrock](/en/amazon-bedrock), [Google Vertex AI](/en/google-vertex-ai), or [Microsoft Foundry](/en/microsoft-foundry).

157

158After installing, log in by running `claude` and following the browser prompts. See [Authentication](/en/authentication) for all account types and team setup options.

159

160## Update Claude Code

161

162Native installations automatically update in the background. You can [configure the release channel](#configure-release-channel) to control whether you receive updates immediately or on a delayed stable schedule, or [disable auto-updates](#disable-auto-updates) entirely. Homebrew and WinGet installations require manual updates.

163

164### Auto-updates

165

166Claude Code checks for updates on startup and periodically while running. Updates download and install in the background, then take effect the next time you start Claude Code.

84 167

85<Note>168<Note>

86 **Alpine Linux and other musl/uClibc-based distributions**: The native installer requires `libgcc`, `libstdc++`, and `ripgrep`. For Alpine: `apk add libgcc libstdc++ ripgrep`. Set `USE_BUILTIN_RIPGREP=0`.169 Homebrew and WinGet installations do not auto-update. Use `brew upgrade claude-code` or `winget upgrade Anthropic.ClaudeCode` to update manually.

170

171 **Known issue:** Claude Code may notify you of updates before the new version is available in these package managers. If an upgrade fails, wait and try again later.

172

173 Homebrew keeps old versions on disk after upgrades. Run `brew cleanup claude-code` periodically to reclaim disk space.

87</Note>174</Note>

88 175

~~89### Authentication~~176### Configure release channel

177

178Control which release channel Claude Code follows for auto-updates and `claude update` with the `autoUpdatesChannel` setting:

179

180* `"latest"`, the default: receive new features as soon as they're released

181* `"stable"`: use a version that is typically about one week old, skipping releases with major regressions

182

183Configure this via `/config` → **Auto-update channel**, or add it to your [settings.json file](/en/settings):

184

185```json theme={null}

186{

187 "autoUpdatesChannel": "stable"

188}

189```

190

191For enterprise deployments, you can enforce a consistent release channel across your organization using [managed settings](/en/permissions#managed-settings).

90 192

~~91#### For individuals~~193### Disable auto-updates

92 194

931. **Claude Pro or Max plan** (recommended): Subscribe to Claude's [Pro or Max plan](https://claude.ai/pricing) for a unified subscription that includes both Claude Code and Claude on the web. Manage your account in one place and log in with your Claude.ai account.195Set `DISABLE_AUTOUPDATER` to `"1"` in the `env` key of your [`settings.json`](/en/settings#available-settings) file:

942. **Claude Console**: Connect through the [Claude Console](https://console.anthropic.com) and complete the OAuth process. Requires active billing in the Anthropic Console. A "Claude Code" workspace is automatically created for usage tracking and cost management. You can't create API keys for the Claude Code workspace; it's dedicated exclusively for Claude Code usage.

95 196

~~96#### For teams and organizations~~197```json theme={null}

198{

199 "env": {

200 "DISABLE_AUTOUPDATER": "1"

201 }

202}

203```

97 204

981. **Claude for Teams or Enterprise** (recommended): Subscribe to [Claude for Teams](https://claude.com/pricing#team-&-enterprise) or [Claude for Enterprise](https://anthropic.com/contact-sales) for centralized billing, team management, and access to both Claude Code and Claude on the web. Team members log in with their Claude.ai accounts.205### Update manually

~~992. **Claude Console with team billing**: Set up a shared [Claude Console](https://console.anthropic.com) organization with team billing. Invite team members and assign roles for usage tracking.~~206

1003. **Cloud providers**: Configure Claude Code to use [Amazon Bedrock, Google Vertex AI, or Microsoft Foundry](/en/third-party-integrations) for deployments with your existing cloud infrastructure.207To apply an update immediately without waiting for the next background check, run:

208

209```bash theme={null}

210claude update

211```

212

213## Advanced installation options

214

215These options are for version pinning, migrating from npm, and verifying binary integrity.

101 216

102### Install a specific version217### Install a specific version

103 218

104The native installer accepts either a specific version number or a release channel (`latest` or `stable`). The channel you choose at install time becomes your default for auto-updates. See [Configure release channel](#configure-release-channel) for more information.219The native installer accepts either a specific version number or a release channel (`latest` or `stable`). The channel you choose at install time becomes your default for auto-updates. See [configure release channel](#configure-release-channel) for more information.

105 220

106To install the latest version (default):221To install the latest version (default):

107 222

169 </Tab>284 </Tab>

170</Tabs>285</Tabs>

171 286

172### Binary integrity and code signing287### Deprecated npm installation

173 288

174* SHA256 checksums for all platforms are published in the release manifests, currently located at `https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases/{VERSION}/manifest.json` (example: replace `{VERSION}` with `2.0.30`)289npm installation is deprecated. The native installer is faster, requires no dependencies, and auto-updates in the background. Use the [native installation](#install-claude-code) method when possible.

175* Signed binaries are distributed for the following platforms:

176 * macOS: Signed by "Anthropic PBC" and notarized by Apple

177 * Windows: Signed by "Anthropic, PBC"

178 290

179## NPM installation (deprecated)291#### Migrate from npm to native

180 292

181NPM installation is deprecated. Use the [native installation](#installation) method when possible. To migrate an existing npm installation to native, run `claude install`.293If you previously installed Claude Code with npm, switch to the native installer:

182 294

183**Global npm installation**295```bash theme={null}

296# Install the native binary

297curl -fsSL https://claude.ai/install.sh | bash

184 298

185```sh theme={null}299# Remove the old npm installation

186npm install -g @anthropic-ai/claude-code300npm uninstall -g @anthropic-ai/claude-code

187```301```

188 302

189<Warning>303You can also run `claude install` from an existing npm installation to install the native binary alongside it, then remove the npm version.

190 Do NOT use `sudo npm install -g` as this can lead to permission issues and security risks.

191 If you encounter permission errors, see [troubleshooting permission errors](/en/troubleshooting#command-not-found-claude-or-permission-errors) for recommended solutions.

192</Warning>

~~193~~

194## Windows setup

~~195~~

196**Option 1: Claude Code within WSL**

~~197~~

198* Both WSL 1 and WSL 2 are supported

199* WSL 2 supports [sandboxing](/en/sandboxing) for enhanced security. WSL 1 does not support sandboxing.

~~200~~

201**Option 2: Claude Code on native Windows with Git Bash**

~~202~~

203* Requires [Git for Windows](https://git-scm.com/downloads/win)

204* For portable Git installations, specify the path to your `bash.exe`:

205 ```powershell theme={null}

206 $env:CLAUDE_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"

207 ```

~~208~~

209## Update Claude Code

~~210~~

211### Auto updates

~~212~~

213Claude Code automatically keeps itself up to date to ensure you have the latest features and security fixes.

~~214~~

215* **Update checks**: Performed on startup and periodically while running

216* **Update process**: Downloads and installs automatically in the background

217* **Notifications**: You'll see a notification when updates are installed

218* **Applying updates**: Updates take effect the next time you start Claude Code

~~219~~

220<Note>

221 Homebrew and WinGet installations do not auto-update. Use `brew upgrade claude-code` or `winget upgrade Anthropic.ClaudeCode` to update manually.

~~222~~

223 **Known issue:** Claude Code may notify you of updates before the new version is available in these package managers. If an upgrade fails, wait and try again later.

224</Note>

~~225~~

226### Configure release channel

227 304

228Configure which release channel Claude Code follows for both auto-updates and `claude update` with the `autoUpdatesChannel` setting:305#### Install with npm

229 306

230* `"latest"` (default): Receive new features as soon as they're released307If you need npm installation for compatibility reasons, you must have [Node.js 18+](https://nodejs.org/en/download) installed. Install the package globally:

231* `"stable"`: Use a version that is typically about one week old, skipping releases with major regressions

232 308

233Configure this via `/config` → **Auto-update channel**, or add it to your [settings.json file](/en/settings):309```bash theme={null}

~~234~~ 310npm install -g @anthropic-ai/claude-code

235```json theme={null}

236{

237 "autoUpdatesChannel": "stable"

238}

239```311```

240 312

241For enterprise deployments, you can enforce a consistent release channel across your organization using [managed settings](/en/iam#managed-settings).313<Warning>

~~242~~ 314 Do NOT use `sudo npm install -g` as this can lead to permission issues and security risks. If you encounter permission errors, see [troubleshooting permission errors](/en/troubleshooting#permission-errors-during-installation).

243### Disable auto-updates315</Warning>

~~244~~

245Set the `DISABLE_AUTOUPDATER` environment variable in your shell or [settings.json file](/en/settings):

246 316

247```bash theme={null}317### Binary integrity and code signing

248export DISABLE_AUTOUPDATER=1

249```

250 318

251### Update manually319You can verify the integrity of Claude Code binaries using SHA256 checksums and code signatures.

252 320

253```bash theme={null}321* SHA256 checksums for all platforms are published in the release manifests at `https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases/{VERSION}/manifest.json`. Replace `{VERSION}` with a version number such as `2.0.30`.

254claude update322* Signed binaries are distributed for the following platforms:

255```323 * **macOS**: signed by "Anthropic PBC" and notarized by Apple

324 * **Windows**: signed by "Anthropic, PBC"

256 325

257## Uninstall Claude Code326## Uninstall Claude Code

258 327

259If you need to uninstall Claude Code, follow the instructions for your installation method.328To remove Claude Code, follow the instructions for your installation method.

260 329

261### Native installation330### Native installation

262 331

263Remove the Claude Code binary and version files:332Remove the Claude Code binary and version files:

264 333

265**macOS, Linux, WSL:**334<Tabs>

~~266~~ 335 <Tab title="macOS, Linux, WSL">

267```bash theme={null}336 ```bash theme={null}

268rm -f ~/.local/bin/claude337 rm -f ~/.local/bin/claude

269rm -rf ~/.local/share/claude338 rm -rf ~/.local/share/claude

270```339 ```

~~271~~ 340 </Tab>

272**Windows PowerShell:**

~~273~~

274```powershell theme={null}

275Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force

276Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force

277```

~~278~~

279**Windows CMD:**

280 341

281```batch theme={null}342 <Tab title="Windows PowerShell">

282del "%USERPROFILE%\.local\bin\claude.exe"343 ```powershell theme={null}

283rmdir /s /q "%USERPROFILE%\.local\share\claude"344 Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force

284```345 Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force

346 ```

347 </Tab>

348</Tabs>

285 349

286### Homebrew installation350### Homebrew installation

287 351

352Remove the Homebrew cask:

353

288```bash theme={null}354```bash theme={null}

289brew uninstall --cask claude-code355brew uninstall --cask claude-code

290```356```

291 357

292### WinGet installation358### WinGet installation

293 359

360Remove the WinGet package:

361

294```powershell theme={null}362```powershell theme={null}

295winget uninstall Anthropic.ClaudeCode363winget uninstall Anthropic.ClaudeCode

296```364```

297 365

298### NPM installation366### npm

367

368Remove the global npm package:

299 369

300```bash theme={null}370```bash theme={null}

301npm uninstall -g @anthropic-ai/claude-code371npm uninstall -g @anthropic-ai/claude-code

302```372```

303 373

304### Clean up configuration files (optional)374### Remove configuration files

305 375

306<Warning>376<Warning>

307 Removing configuration files will delete all your settings, allowed tools, MCP server configurations, and session history.377 Removing configuration files will delete all your settings, allowed tools, MCP server configurations, and session history.

309 379

310To remove Claude Code settings and cached data:380To remove Claude Code settings and cached data:

311 381

312**macOS, Linux, WSL:**382<Tabs>

~~313~~ 383 <Tab title="macOS, Linux, WSL">

314```bash theme={null}384 ```bash theme={null}

315# Remove user settings and state385 # Remove user settings and state

316rm -rf ~/.claude386 rm -rf ~/.claude

317rm ~/.claude.json387 rm ~/.claude.json

~~318~~

319# Remove project-specific settings (run from your project directory)

320rm -rf .claude

321rm -f .mcp.json

322```

~~323~~

324**Windows PowerShell:**

~~325~~

326```powershell theme={null}

327# Remove user settings and state

328Remove-Item -Path "$env:USERPROFILE\.claude" -Recurse -Force

329Remove-Item -Path "$env:USERPROFILE\.claude.json" -Force

~~330~~

331# Remove project-specific settings (run from your project directory)

332Remove-Item -Path ".claude" -Recurse -Force

333Remove-Item -Path ".mcp.json" -Force

334```

335 388

336**Windows CMD:**389 # Remove project-specific settings (run from your project directory)

390 rm -rf .claude

391 rm -f .mcp.json

392 ```

393 </Tab>

337 394

338```batch theme={null}395 <Tab title="Windows PowerShell">

339REM Remove user settings and state396 ```powershell theme={null}

340rmdir /s /q "%USERPROFILE%\.claude"397 # Remove user settings and state

341del "%USERPROFILE%\.claude.json"398 Remove-Item -Path "$env:USERPROFILE\.claude" -Recurse -Force

399 Remove-Item -Path "$env:USERPROFILE\.claude.json" -Force

342 400

343REM Remove project-specific settings (run from your project directory)401 # Remove project-specific settings (run from your project directory)

344rmdir /s /q ".claude"402 Remove-Item -Path ".claude" -Recurse -Force

345del ".mcp.json"403 Remove-Item -Path ".mcp.json" -Force

346```404 ```

405 </Tab>

406</Tabs>

skills.md +51 −25

Details

4 4

5# Extend Claude with skills5# Extend Claude with skills

6 6

~~7> Create, manage, and share skills to extend Claude's capabilities in Claude Code. Includes custom slash commands.~~7> Create, manage, and share skills to extend Claude's capabilities in Claude Code. Includes custom commands and bundled skills.

8 8

9Skills extend what Claude can do. Create a `SKILL.md` file with instructions, and Claude adds it to its toolkit. Claude uses skills when relevant, or you can invoke one directly with `/skill-name`.9Skills extend what Claude can do. Create a `SKILL.md` file with instructions, and Claude adds it to its toolkit. Claude uses skills when relevant, or you can invoke one directly with `/skill-name`.

10 10

11<Note>11<Note>

~~12 For built-in commands like `/help` and `/compact`, see [interactive mode](/en/interactive-mode#built-in-commands).~~12 For built-in commands like `/help` and `/compact`, see the [built-in commands reference](/en/commands).

13 13

14 **Custom slash commands have been merged into skills.** A file at `.claude/commands/review.md` and a skill at `.claude/skills/review/SKILL.md` both create `/review` and work the same way. Your existing `.claude/commands/` files keep working. Skills add optional features: a directory for supporting files, frontmatter to [control whether you or Claude invokes them](#control-who-invokes-a-skill), and the ability for Claude to load them automatically when relevant.14 **Custom commands have been merged into skills.** A file at `.claude/commands/deploy.md` and a skill at `.claude/skills/deploy/SKILL.md` both create `/deploy` and work the same way. Your existing `.claude/commands/` files keep working. Skills add optional features: a directory for supporting files, frontmatter to [control whether you or Claude invokes them](#control-who-invokes-a-skill), and the ability for Claude to load them automatically when relevant.

15</Note>15</Note>

16 16

17Claude Code skills follow the [Agent Skills](https://agentskills.io) open standard, which works across multiple AI tools. Claude Code extends the standard with additional features like [invocation control](#control-who-invokes-a-skill), [subagent execution](#run-skills-in-a-subagent), and [dynamic context injection](#inject-dynamic-context).17Claude Code skills follow the [Agent Skills](https://agentskills.io) open standard, which works across multiple AI tools. Claude Code extends the standard with additional features like [invocation control](#control-who-invokes-a-skill), [subagent execution](#run-skills-in-a-subagent), and [dynamic context injection](#inject-dynamic-context).

18 18

19## Bundled skills

21Bundled skills ship with Claude Code and are available in every session. Unlike [built-in commands](/en/commands), which execute fixed logic directly, bundled skills are prompt-based: they give Claude a detailed playbook and let it orchestrate the work using its tools. This means bundled skills can spawn parallel agents, read files, and adapt to your codebase.

23You invoke bundled skills the same way as any other skill: type `/` followed by the skill name. In the table below, `<arg>` indicates a required argument and `[arg]` indicates an optional one.

25| Skill | Purpose |

26| :-------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

27| `/batch <instruction>` | Orchestrate large-scale changes across a codebase in parallel. Researches the codebase, decomposes the work into 5 to 30 independent units, and presents a plan. Once approved, spawns one background agent per unit in an isolated [git worktree](/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees). Each agent implements its unit, runs tests, and opens a pull request. Requires a git repository. Example: `/batch migrate src/ from Solid to React` |

28| `/claude-api` | Load Claude API reference material for your project's language (Python, TypeScript, Java, Go, Ruby, C#, PHP, or cURL) and Agent SDK reference for Python and TypeScript. Covers tool use, streaming, batches, structured outputs, and common pitfalls. Also activates automatically when your code imports `anthropic`, `@anthropic-ai/sdk`, or `claude_agent_sdk` |

29| `/debug [description]` | Enable debug logging for the current session and troubleshoot issues by reading the session debug log. Debug logging is off by default unless you started with `claude --debug`, so running `/debug` mid-session starts capturing logs from that point forward. Optionally describe the issue to focus the analysis |

30| `/loop [interval] <prompt>` | Run a prompt repeatedly on an interval while the session stays open. Useful for polling a deployment, babysitting a PR, or periodically re-running another skill. Example: `/loop 5m check if the deploy finished`. See [Run prompts on a schedule](/en/scheduled-tasks) |

31| `/simplify [focus]` | Review your recently changed files for code reuse, quality, and efficiency issues, then fix them. Spawns three review agents in parallel, aggregates their findings, and applies fixes. Pass text to focus on specific concerns: `/simplify focus on memory efficiency` |

19## Getting started33## Getting started

20 34

21### Create your first skill35### Create your first skill

58 72

59 **Let Claude invoke it automatically** by asking something that matches the description:73 **Let Claude invoke it automatically** by asking something that matches the description:

60 74

~~61 ```~~75 ```text theme={null}

62 How does this code work?76 How does this code work?

63 ```77 ```

64 78

65 **Or invoke it directly** with the skill name:79 **Or invoke it directly** with the skill name:

66 80

~~67 ```~~81 ```text theme={null}

68 /explain-code src/auth/login.ts82 /explain-code src/auth/login.ts

69 ```83 ```

70 84

77Where you store a skill determines who can use it:91Where you store a skill determines who can use it:

78 92

~~80| :--------- | :----------------------------------------------- | :----------------------------- |~~94| :--------- | :-------------------------------------------------- | :----------------------------- |

91 105

92Each skill is a directory with `SKILL.md` as the entrypoint:106Each skill is a directory with `SKILL.md` as the entrypoint:

93 107

~~94```~~108```text theme={null}

95my-skill/109my-skill/

96├── SKILL.md # Main instructions (required)110├── SKILL.md # Main instructions (required)

97├── template.md # Template for Claude to fill in111├── template.md # Template for Claude to fill in

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.121 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>122</Note>

109 123

124#### Skills from additional directories

125

126Skills 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.

127

128<Note>

129 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 from additional directories](/en/memory#load-from-additional-directories).

130</Note>

131

110## Configure skills132## Configure skills

111 133

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

165All fields are optional. Only `description` is recommended so Claude knows when to use the skill.187All fields are optional. Only `description` is recommended so Claude knows when to use the skill.

166 188

168| :------------------------- | :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |190| :------------------------- | :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

169| `name` | No | Display name for the skill. If omitted, uses the directory name. Lowercase letters, numbers, and hyphens only (max 64 characters). |191| `name` | No | Display name for the skill. If omitted, uses the directory name. Lowercase letters, numbers, and hyphens only (max 64 characters). |

170| `description` | Recommended | What the skill does and when to use it. Claude uses this to decide when to apply the skill. If omitted, uses the first paragraph of markdown content. |192| `description` | Recommended | What the skill does and when to use it. Claude uses this to decide when to apply the skill. If omitted, uses the first paragraph of markdown content. Front-load the key use case: descriptions longer than 250 characters are truncated in the skill listing to reduce context usage. |

171| `argument-hint` | No | Hint shown during autocomplete to indicate expected arguments. Example: `[issue-number]` or `[filename] [format]`. |193| `argument-hint` | No | Hint shown during autocomplete to indicate expected arguments. Example: `[issue-number]` or `[filename] [format]`. |

172| `disable-model-invocation` | No | Set to `true` to prevent Claude from automatically loading this skill. Use for workflows you want to trigger manually with `/name`. Default: `false`. |194| `disable-model-invocation` | No | Set to `true` to prevent Claude from automatically loading this skill. Use for workflows you want to trigger manually with `/name`. Default: `false`. |

173| `user-invocable` | No | Set to `false` to hide from the `/` menu. Use for background knowledge users shouldn't invoke directly. Default: `true`. |195| `user-invocable` | No | Set to `false` to hide from the `/` menu. Use for background knowledge users shouldn't invoke directly. Default: `true`. |

174| `allowed-tools` | No | Tools Claude can use without asking permission when this skill is active. |196| `allowed-tools` | No | Tools Claude can use without asking permission when this skill is active. |

175| `model` | No | Model to use when this skill is active. |197| `model` | No | Model to use when this skill is active. |

198| `effort` | No | [Effort level](/en/model-config#adjust-effort-level) when this skill is active. Overrides the session effort level. Default: inherits from session. Options: `low`, `medium`, `high`, `max` (Opus 4.6 only). |

176| `context` | No | Set to `fork` to run in a forked subagent context. |199| `context` | No | Set to `fork` to run in a forked subagent context. |

177| `agent` | No | Which subagent type to use when `context: fork` is set. |200| `agent` | No | Which subagent type to use when `context: fork` is set. |

178| `hooks` | No | Hooks scoped to this skill's lifecycle. See [Hooks in skills and agents](/en/hooks#hooks-in-skills-and-agents) for configuration format. |201| `hooks` | No | Hooks scoped to this skill's lifecycle. See [Hooks in skills and agents](/en/hooks#hooks-in-skills-and-agents) for configuration format. |

202| `paths` | No | Glob patterns that limit when this skill is activated. Accepts a comma-separated string or a YAML list. When set, Claude loads the skill automatically only when working with files matching the patterns. Uses the same format as [path-specific rules](/en/memory#path-specific-rules). |

203| `shell` | No | Shell to use for `` !`command` `` blocks in this skill. Accepts `bash` (default) or `powershell`. Setting `powershell` runs inline shell commands via PowerShell on Windows. Requires `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`. |

179 204

180#### Available string substitutions205#### Available string substitutions

181 206

182Skills support string substitution for dynamic values in the skill content:207Skills support string substitution for dynamic values in the skill content:

183 208

184| Variable | Description |209| Variable | Description |

185| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------- |210| :--------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

186| `$ARGUMENTS` | All arguments passed when invoking the skill. If `$ARGUMENTS` is not present in the content, arguments are appended as `ARGUMENTS: <value>`. |211| `$ARGUMENTS` | All arguments passed when invoking the skill. If `$ARGUMENTS` is not present in the content, arguments are appended as `ARGUMENTS: <value>`. |

188| `$N` | Shorthand for `$ARGUMENTS[N]`, such as `$0` for the first argument or `$1` for the second. |213| `$N` | Shorthand for `$ARGUMENTS[N]`, such as `$0` for the first argument or `$1` for the second. |

189| `${CLAUDE_SESSION_ID}` | The current session ID. Useful for logging, creating session-specific files, or correlating skill output with sessions. |214| `${CLAUDE_SESSION_ID}` | The current session ID. Useful for logging, creating session-specific files, or correlating skill output with sessions. |

215| `${CLAUDE_SKILL_DIR}` | The directory containing the skill's `SKILL.md` file. For plugin skills, this is the skill's subdirectory within the plugin, not the plugin root. Use this in bash injection commands to reference scripts or files bundled with the skill, regardless of the current working directory. |

190 216

191**Example using substitutions:**217**Example using substitutions:**

192 218

205 231

206Skills can include multiple files in their directory. This keeps `SKILL.md` focused on the essentials while letting Claude access detailed reference material only when needed. Large reference docs, API specifications, or example collections don't need to load into context every time the skill runs.232Skills can include multiple files in their directory. This keeps `SKILL.md` focused on the essentials while letting Claude access detailed reference material only when needed. Large reference docs, API specifications, or example collections don't need to load into context every time the skill runs.

207 233

208```234```text theme={null}

209my-skill/235my-skill/

210├── SKILL.md (required - overview and navigation)236├── SKILL.md (required - overview and navigation)

211├── reference.md (detailed API docs - loaded when needed)237├── reference.md (detailed API docs - loaded when needed)

328 354

329### Inject dynamic context355### Inject dynamic context

330 356

331The `!`command\`\` syntax runs shell commands before the skill content is sent to Claude. The command output replaces the placeholder, so Claude receives actual data, not the command itself.357The `` !`<command>` `` syntax runs shell commands before the skill content is sent to Claude. The command output replaces the placeholder, so Claude receives actual data, not the command itself.

332 358

333This skill summarizes a pull request by fetching live PR data with the GitHub CLI. The `!`gh pr diff\`\` and other commands run first, and their output gets inserted into the prompt:359This skill summarizes a pull request by fetching live PR data with the GitHub CLI. The `` !`gh pr diff` `` and other commands run first, and their output gets inserted into the prompt:

334 360

335```yaml theme={null}361```yaml theme={null}

336---362---

352 378

353When this skill runs:379When this skill runs:

354 380

3551. Each `!`command\`\` executes immediately (before Claude sees anything)3811. Each `` !`<command>` `` executes immediately (before Claude sees anything)

3562. The output replaces the placeholder in the skill content3822. The output replaces the placeholder in the skill content

3573. Claude receives the fully-rendered prompt with actual PR data3833. Claude receives the fully-rendered prompt with actual PR data

358 384

409 435

410### Restrict Claude's skill access436### Restrict Claude's skill access

411 437

412By default, Claude can invoke any skill that doesn't have `disable-model-invocation: true` set. Skills that define `allowed-tools` grant Claude access to those tools without per-use approval when the skill is active. Your [permission settings](/en/iam) still govern baseline approval behavior for all other tools. Built-in commands like `/compact` and `/init` are not available through the Skill tool.438By default, Claude can invoke any skill that doesn't have `disable-model-invocation: true` set. Skills that define `allowed-tools` grant Claude access to those tools without per-use approval when the skill is active. Your [permission settings](/en/permissions) still govern baseline approval behavior for all other tools. Built-in commands like `/compact` and `/init` are not available through the Skill tool.

413 439

414Three ways to control which skills Claude can invoke:440Three ways to control which skills Claude can invoke:

415 441

416**Disable all skills** by denying the Skill tool in `/permissions`:442**Disable all skills** by denying the Skill tool in `/permissions`:

417 443

418```444```text theme={null}

419# Add to deny rules:445# Add to deny rules:

420Skill446Skill

421```447```

422 448

423**Allow or deny specific skills** using [permission rules](/en/iam):449**Allow or deny specific skills** using [permission rules](/en/permissions):

424 450

425```451```text theme={null}

426# Allow only specific skills452# Allow only specific skills

427Skill(commit)453Skill(commit)

428Skill(review-pr *)454Skill(review-pr *)

445 471

446* **Project skills**: Commit `.claude/skills/` to version control472* **Project skills**: Commit `.claude/skills/` to version control

447* **Plugins**: Create a `skills/` directory in your [plugin](/en/plugins)473* **Plugins**: Create a `skills/` directory in your [plugin](/en/plugins)

448* **Managed**: Deploy organization-wide through [managed settings](/en/iam#managed-settings)474* **Managed**: Deploy organization-wide through [managed settings](/en/settings#settings-files)

449 475

450### Generate visual output476### Generate visual output

451 477

6541. Make the description more specific6801. Make the description more specific

6552. Add `disable-model-invocation: true` if you only want manual invocation6812. Add `disable-model-invocation: true` if you only want manual invocation

656 682

657### Claude doesn't see all my skills683### Skill descriptions are cut short

658 684

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.685Skill descriptions are loaded into context so Claude knows what's available. All skill names are always included, but if you have many skills, descriptions are shortened to fit the character budget, which can strip the keywords Claude needs to match your request. The budget scales dynamically at 1% of the context window, with a fallback of 8,000 characters.

660 686

661To increase the limit, set the `SLASH_COMMAND_TOOL_CHAR_BUDGET` environment variable.687To raise the limit, set the `SLASH_COMMAND_TOOL_CHAR_BUDGET` environment variable. Or trim descriptions at the source: front-load the key use case, since each entry is capped at 250 characters regardless of budget.

662 688

663## Related resources689## Related resources

664 690

666* **[Plugins](/en/plugins)**: package and distribute skills with other extensions692* **[Plugins](/en/plugins)**: package and distribute skills with other extensions

667* **[Hooks](/en/hooks)**: automate workflows around tool events693* **[Hooks](/en/hooks)**: automate workflows around tool events

668* **[Memory](/en/memory)**: manage CLAUDE.md files for persistent context694* **[Memory](/en/memory)**: manage CLAUDE.md files for persistent context

669* **[Interactive mode](/en/interactive-mode#built-in-commands)**: built-in commands and shortcuts695* **[Built-in commands](/en/commands)**: reference for built-in `/` commands

670* **[Permissions](/en/iam)**: control tool and skill access696* **[Permissions](/en/permissions)**: control tool and skill access

slack.md +28 −3

Details

23 23

24| Requirement | Details |24| Requirement | Details |

25| :--------------------- | :----------------------------------------------------------------------------- |25| :--------------------- | :----------------------------------------------------------------------------- |

~~26| Claude Plan | Pro, Max, Team, or Enterprise with Claude Code access (premium seats) |~~26| Claude Plan | Pro, Max, Teams, or Enterprise with Claude Code access (premium seats) |

27| Claude Code on the web | Access to [Claude Code on the web](/en/claude-code-on-the-web) must be enabled |27| Claude Code on the web | Access to [Claude Code on the web](/en/claude-code-on-the-web) must be enabled |

28| GitHub Account | Connected to Claude Code on the web with at least one repository authenticated |28| GitHub Account | Connected to Claude Code on the web with at least one repository authenticated |

29| Slack Authentication | Your Slack account linked to your Claude account via the Claude app |29| Slack Authentication | Your Slack account linked to your Claude account via the Claude app |

64 In Code + Chat mode, if Claude routes a message to Chat but you wanted a coding session, you can click "Retry as Code" to create a Claude Code session instead. Similarly, if it's routed to Code but you wanted a Chat session, you can choose that option in that thread.64 In Code + Chat mode, if Claude routes a message to Chat but you wanted a coding session, you can click "Retry as Code" to create a Claude Code session instead. Similarly, if it's routed to Code but you wanted a Chat session, you can choose that option in that thread.

65 </Note>65 </Note>

66 </Step>66 </Step>

68 <Step title="Add Claude to channels">

69 Claude is not automatically added to any channels after installation. To use Claude in a channel, invite it by typing `/invite @Claude` in that channel. Claude can only respond to @mentions in channels where it has been added.

70 </Step>

67</Steps>71</Steps>

68 72

69## How it works73## How it works

127| Repository Access | Users can only access repositories they've personally connected |131| Repository Access | Users can only access repositories they've personally connected |

128| Session History | Sessions appear in your Claude Code history on claude.ai/code |132| Session History | Sessions appear in your Claude Code history on claude.ai/code |

129 133

130### Workspace admin permissions134### Workspace-level access

135

136Slack workspace administrators control whether the Claude app is available in their workspace:

137

138| Control | Description |

139| :--------------------------- | :---------------------------------------------------------------------------------------------------------------- |

140| App installation | Workspace admins decide whether to install the Claude app from the Slack App Marketplace |

141| Enterprise Grid distribution | For Enterprise Grid organizations, organization admins can control which workspaces have access to the Claude app |

142| App removal | Removing the app from a workspace immediately revokes access for all users in that workspace |

131 143

132Slack workspace administrators control whether the Claude app can be installed in the workspace. Individual users then authenticate with their own Claude accounts to use the integration.144### Channel-based access control

145

146Claude is not automatically added to any channels after installation. Users must explicitly invite Claude to channels where they want to use it:

147

148* **Invite required**: Type `/invite @Claude` in any channel to add Claude to that channel

149* **Channel membership controls access**: Claude can only respond to @mentions in channels where it has been added

150* **Access gating through channels**: Admins can control who uses Claude Code by managing which channels Claude is invited to and who has access to those channels

151* **Private channel support**: Claude works in both public and private channels, giving teams flexibility in controlling visibility

152

153This channel-based model allows teams to restrict Claude Code usage to specific channels, providing an additional layer of access control beyond workspace-level permissions.

133 154

134## What's accessible where155## What's accessible where

135 156

137 158

138**On the web**: The complete Claude Code session with full conversation history, all code changes, file operations, and the ability to continue the session or create pull requests.159**On the web**: The complete Claude Code session with full conversation history, all code changes, file operations, and the ability to continue the session or create pull requests.

139 160

161For Enterprise and Teams accounts, sessions created from Claude in Slack are

162automatically visible to the organization. See [Claude Code on the Web sharing](/en/claude-code-on-the-web#sharing-sessions)

163for more details.

164

140## Best practices165## Best practices

141 166

142### Writing effective requests167### Writing effective requests

statusline.md +898 −165

Details

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt2> 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.3> Use this file to discover all available pages before exploring further.

4 4

~~5# Status line configuration~~5# Customize your status line

6 6

~~7> Create a custom status line for Claude Code to display contextual information~~7> Configure a custom status bar to monitor context window usage, costs, and git status in Claude Code

8 8

~~9Make Claude Code your own with a custom status line that displays at the bottom of the Claude Code interface, similar to how terminal prompts (PS1) work in shells like Oh-my-zsh.~~9The status line is a customizable bar at the bottom of Claude Code that runs any shell script you configure. It receives JSON session data on stdin and displays whatever your script prints, giving you a persistent, at-a-glance view of context usage, costs, git status, or anything else you want to track.

10 10

~~11## Create a custom status line~~11Status lines are useful when you:

12 12

~~13You can either:~~13* Want to monitor context window usage as you work

14* Need to track session costs

15* Work across multiple sessions and need to distinguish them

16* Want git branch and status always visible

14 17

15* Run `/statusline` to ask Claude Code to help you set up a custom status line. By default, it will try to reproduce your terminal's prompt, but you can provide additional instructions about the behavior you want to Claude Code, such as `/statusline show the model name in orange`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.

16 19

~~17* Directly add a `statusLine` command to your `.claude/settings.json`:~~20<Frame>

21 <img src="https://mintcdn.com/claude-code/nibzesLaJVh4ydOq/images/statusline-multiline.png?fit=max&auto=format&n=nibzesLaJVh4ydOq&q=85&s=60f11387658acc9ff75158ae85f2ac87" alt="A multi-line status line showing model name, directory, git branch on the first line, and a context usage progress bar with cost and duration on the second line" width="776" height="212" data-path="images/statusline-multiline.png" />

22</Frame>

24This page walks through [setting up a basic status line](#set-up-a-status-line), explains [how the data flows](#how-status-lines-work) from Claude Code to your script, lists [all the fields you can display](#available-data), and provides [ready-to-use examples](#examples) for common patterns like git status, cost tracking, and progress bars.

26## Set up a status line

28Use the [`/statusline` command](#use-the-statusline-command) to have Claude Code generate a script for you, or [manually create a script](#manually-configure-a-status-line) and add it to your settings.

30### Use the /statusline command

32The `/statusline` command accepts natural language instructions describing what you want displayed. Claude Code generates a script file in `~/.claude/` and updates your settings automatically:

34```text theme={null}

35/statusline show model name and context percentage with a progress bar

36```

38### Manually configure a status line

40Add a `statusLine` field to your user settings (`~/.claude/settings.json`, where `~` is your home directory) or [project settings](/en/settings#settings-files). Set `type` to `"command"` and point `command` to a script path or an inline shell command. For a full walkthrough of creating a script, see [Build a status line step by step](#build-a-status-line-step-by-step).

18 41

19```json theme={null}42```json theme={null}

20{43{

21 "statusLine": {44 "statusLine": {

22 "type": "command",45 "type": "command",

23 "command": "~/.claude/statusline.sh",46 "command": "~/.claude/statusline.sh",

~~24 "padding": 0 // Optional: set to 0 to let status line go to edge~~47 "padding": 2

25 }48 }

26}49}

27```50```

28 51

~~29## How it Works~~52The `command` field runs in a shell, so you can also use inline commands instead of a script file. This example uses `jq` to parse the JSON input and display the model name and context percentage:

30 53

~~31* The status line is updated when the conversation messages update~~54```json theme={null}

~~32* Updates run at most every 300 ms~~55{

~~33* The first line of stdout from your command becomes the status line text~~56 "statusLine": {

~~34* ANSI color codes are supported for styling your status line~~57 "type": "command",

~~35* Claude Code passes contextual information about the current session (model, directories, etc.) as JSON to your script via stdin~~58 "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'"

59 }

60}

61```

36 62

~~37## JSON Input Structure~~63The optional `padding` field adds extra horizontal spacing (in characters) to the status line content. Defaults to `0`. This padding is in addition to the interface's built-in spacing, so it controls relative indentation rather than absolute distance from the terminal edge.

38 64

~~39Your status line command receives structured data via stdin in JSON format:~~65### Disable the status line

40 66

~~41```json theme={null}~~67Run `/statusline` and ask it to remove or clear your status line (e.g., `/statusline delete`, `/statusline clear`, `/statusline remove it`). You can also manually delete the `statusLine` field from your settings.json.

~~42{~~68

~~43 "hook_event_name": "Status",~~69## Build a status line step by step

~~44 "session_id": "abc123...",~~70

~~45 "transcript_path": "/path/to/transcript.json",~~71This walkthrough shows what's happening under the hood by manually creating a status line that displays the current model, working directory, and context window usage percentage.

73<Note>Running [`/statusline`](#use-the-statusline-command) with a description of what you want configures all of this for you automatically.</Note>

75These examples use Bash scripts, which work on macOS and Linux. On Windows, see [Windows configuration](#windows-configuration) for PowerShell and Git Bash examples.

77<Frame>

78 <img src="https://mintcdn.com/claude-code/nibzesLaJVh4ydOq/images/statusline-quickstart.png?fit=max&auto=format&n=nibzesLaJVh4ydOq&q=85&s=696445e59ca0059213250651ad23db6b" alt="A status line showing model name, directory, and context percentage" width="726" height="164" data-path="images/statusline-quickstart.png" />

79</Frame>

81<Steps>

82 <Step title="Create a script that reads JSON and prints output">

83 Claude Code sends JSON data to your script via stdin. This script uses [`jq`](https://jqlang.github.io/jq/), a command-line JSON parser you may need to install, to extract the model name, directory, and context percentage, then prints a formatted line.

85 Save this to `~/.claude/statusline.sh` (where `~` is your home directory, such as `/Users/username` on macOS or `/home/username` on Linux):

87 ```bash theme={null}

88 #!/bin/bash

89 # Read JSON data that Claude Code sends to stdin

90 input=$(cat)

92 # Extract fields using jq

93 MODEL=$(echo "$input" | jq -r '.model.display_name')

94 DIR=$(echo "$input" | jq -r '.workspace.current_dir')

95 # The "// 0" provides a fallback if the field is null

96 PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)

98 # Output the status line - ${DIR##*/} extracts just the folder name

99 echo "[$MODEL] 📁 ${DIR##*/} | ${PCT}% context"

100 ```

101 </Step>

102

103 <Step title="Make it executable">

104 Mark the script as executable so your shell can run it:

105

106 ```bash theme={null}

107 chmod +x ~/.claude/statusline.sh

108 ```

109 </Step>

110

111 <Step title="Add to settings">

112 Tell Claude Code to run your script as the status line. Add this configuration to `~/.claude/settings.json`, which sets `type` to `"command"` (meaning "run this shell command") and points `command` to your script:

113

114 ```json theme={null}

115 {

116 "statusLine": {

117 "type": "command",

118 "command": "~/.claude/statusline.sh"

119 }

120 }

121 ```

122

123 Your status line appears at the bottom of the interface. Settings reload automatically, but changes won't appear until your next interaction with Claude Code.

124 </Step>

125</Steps>

126

127## How status lines work

128

129Claude Code runs your script and pipes [JSON session data](#available-data) to it via stdin. Your script reads the JSON, extracts what it needs, and prints text to stdout. Claude Code displays whatever your script prints.

130

131**When it updates**

132

133Your script runs after each new assistant message, when the permission mode changes, or when vim mode toggles. Updates are debounced at 300ms, meaning rapid changes batch together and your script runs once things settle. If a new update triggers while your script is still running, the in-flight execution is cancelled. If you edit your script, the changes won't appear until your next interaction with Claude Code triggers an update.

134

135**What your script can output**

136

137* **Multiple lines**: each `echo` or `print` statement displays as a separate row. See the [multi-line example](#display-multiple-lines).

138* **Colors**: use [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors) like `\033[32m` for green (terminal must support them). See the [git status example](#git-status-with-colors).

139* **Links**: use [OSC 8 escape sequences](https://en.wikipedia.org/wiki/ANSI_escape_code#OSC) to make text clickable (Cmd+click on macOS, Ctrl+click on Windows/Linux). Requires a terminal that supports hyperlinks like iTerm2, Kitty, or WezTerm. See the [clickable links example](#clickable-links).

140

141<Note>The status line runs locally and does not consume API tokens. It temporarily hides during certain UI interactions, including autocomplete suggestions, the help menu, and permission prompts.</Note>

142

143## Available data

144

145Claude Code sends the following JSON fields to your script via stdin:

146

147| Field | Description |

148| -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

149| `model.id`, `model.display_name` | Current model identifier and display name |

150| `cwd`, `workspace.current_dir` | Current working directory. Both fields contain the same value; `workspace.current_dir` is preferred for consistency with `workspace.project_dir`. |

151| `workspace.project_dir` | Directory where Claude Code was launched, which may differ from `cwd` if the working directory changes during a session |

152| `cost.total_cost_usd` | Total session cost in USD |

153| `cost.total_duration_ms` | Total wall-clock time since the session started, in milliseconds |

154| `cost.total_api_duration_ms` | Total time spent waiting for API responses in milliseconds |

155| `cost.total_lines_added`, `cost.total_lines_removed` | Lines of code changed |

156| `context_window.total_input_tokens`, `context_window.total_output_tokens` | Cumulative token counts across the session |

157| `context_window.context_window_size` | Maximum context window size in tokens. 200000 by default, or 1000000 for models with extended context. |

158| `context_window.used_percentage` | Pre-calculated percentage of context window used |

159| `context_window.remaining_percentage` | Pre-calculated percentage of context window remaining |

160| `context_window.current_usage` | Token counts from the last API call, described in [context window fields](#context-window-fields) |

161| `exceeds_200k_tokens` | Whether the total token count (input, cache, and output tokens combined) from the most recent API response exceeds 200k. This is a fixed threshold regardless of actual context window size. |

162| `rate_limits.five_hour.used_percentage`, `rate_limits.seven_day.used_percentage` | Percentage of the 5-hour or 7-day rate limit consumed, from 0 to 100 |

163| `rate_limits.five_hour.resets_at`, `rate_limits.seven_day.resets_at` | Unix epoch seconds when the 5-hour or 7-day rate limit window resets |

164| `session_id` | Unique session identifier |

165| `transcript_path` | Path to conversation transcript file |

166| `version` | Claude Code version |

167| `output_style.name` | Name of the current output style |

168| `vim.mode` | Current vim mode (`NORMAL` or `INSERT`) when [vim mode](/en/interactive-mode#vim-editor-mode) is enabled |

169| `agent.name` | Agent name when running with the `--agent` flag or agent settings configured |

170| `worktree.name` | Name of the active worktree. Present only during `--worktree` sessions |

171| `worktree.path` | Absolute path to the worktree directory |

172| `worktree.branch` | Git branch name for the worktree (for example, `"worktree-my-feature"`). Absent for hook-based worktrees |

173| `worktree.original_cwd` | The directory Claude was in before entering the worktree |

174| `worktree.original_branch` | Git branch checked out before entering the worktree. Absent for hook-based worktrees |

175

176<Accordion title="Full JSON schema">

177 Your status line command receives this JSON structure via stdin:

178

179 ```json theme={null}

180 {

46 "cwd": "/current/working/directory",181 "cwd": "/current/working/directory",

182 "session_id": "abc123...",

183 "transcript_path": "/path/to/transcript.jsonl",

47 "model": {184 "model": {

~~48 "id": "claude-opus-4-1",~~185 "id": "claude-opus-4-6",

49 "display_name": "Opus"186 "display_name": "Opus"

50 },187 },

51 "workspace": {188 "workspace": {

67 "total_input_tokens": 15234,204 "total_input_tokens": 15234,

68 "total_output_tokens": 4521,205 "total_output_tokens": 4521,

69 "context_window_size": 200000,206 "context_window_size": 200000,

~~70 "used_percentage": 42.5,~~207 "used_percentage": 8,

~~71 "remaining_percentage": 57.5,~~208 "remaining_percentage": 92,

72 "current_usage": {209 "current_usage": {

73 "input_tokens": 8500,210 "input_tokens": 8500,

74 "output_tokens": 1200,211 "output_tokens": 1200,

75 "cache_creation_input_tokens": 5000,212 "cache_creation_input_tokens": 5000,

76 "cache_read_input_tokens": 2000213 "cache_read_input_tokens": 2000

77 }214 }

215 },

216 "exceeds_200k_tokens": false,

217 "rate_limits": {

218 "five_hour": {

219 "used_percentage": 23.5,

220 "resets_at": 1738425600

221 },

222 "seven_day": {

223 "used_percentage": 41.2,

224 "resets_at": 1738857600

78 }225 }

~~79}~~226 },

~~80```~~227 "vim": {

228 "mode": "NORMAL"

229 },

230 "agent": {

231 "name": "security-reviewer"

232 },

233 "worktree": {

234 "name": "my-feature",

235 "path": "/path/to/.claude/worktrees/my-feature",

236 "branch": "worktree-my-feature",

237 "original_cwd": "/path/to/project",

238 "original_branch": "main"

239 }

240 }

241 ```

81 242

~~82## Example Scripts~~243 **Fields that may be absent** (not present in JSON):

83 244

~~84### Simple Status Line~~245 * `vim`: appears only when vim mode is enabled

246 * `agent`: appears only when running with the `--agent` flag or agent settings configured

247 * `worktree`: appears only during `--worktree` sessions. When present, `branch` and `original_branch` may also be absent for hook-based worktrees

248 * `rate_limits`: appears only for Claude.ai subscribers (Pro/Max) after the first API response in the session. Each window (`five_hour`, `seven_day`) may be independently absent. Use `jq -r '.rate_limits.five_hour.used_percentage // empty'` to handle absence gracefully.

85 249

~~86```bash theme={null}~~250 **Fields that may be `null`**:

~~87#!/bin/bash~~

~~88# Read JSON input from stdin~~

~~89input=$(cat)~~

90 251

~~91# Extract values using jq~~252 * `context_window.current_usage`: `null` before the first API call in a session

~~92MODEL_DISPLAY=$(echo "$input" | jq -r '.model.display_name')~~253 * `context_window.used_percentage`, `context_window.remaining_percentage`: may be `null` early in the session

~~93CURRENT_DIR=$(echo "$input" | jq -r '.workspace.current_dir')~~

94 254

~~95echo "[$MODEL_DISPLAY] 📁 ${CURRENT_DIR##*/}"~~255 Handle missing fields with conditional access and null values with fallback defaults in your scripts.

~~96```~~256</Accordion>

257

258### Context window fields

259

260The `context_window` object provides two ways to track context usage:

261

262* **Cumulative totals** (`total_input_tokens`, `total_output_tokens`): sum of all tokens across the entire session, useful for tracking total consumption

263* **Current usage** (`current_usage`): token counts from the most recent API call, use this for accurate context percentage since it reflects the actual context state

264

265The `current_usage` object contains:

266

267* `input_tokens`: input tokens in current context

268* `output_tokens`: output tokens generated

269* `cache_creation_input_tokens`: tokens written to cache

270* `cache_read_input_tokens`: tokens read from cache

271

272The `used_percentage` field is calculated from input tokens only: `input_tokens + cache_creation_input_tokens + cache_read_input_tokens`. It does not include `output_tokens`.

273

274If you calculate context percentage manually from `current_usage`, use the same input-only formula to match `used_percentage`.

275

276The `current_usage` object is `null` before the first API call in a session.

277

278## Examples

97 279

~~98### Git-Aware Status Line~~280These examples show common status line patterns. To use any example:

99 281

100```bash theme={null}2821. Save the script to a file like `~/.claude/statusline.sh` (or `.py`/`.js`)

101#!/bin/bash2832. Make it executable: `chmod +x ~/.claude/statusline.sh`

102# Read JSON input from stdin2843. Add the path to your [settings](#manually-configure-a-status-line)

103input=$(cat)

104 285

105# Extract values using jq286The Bash examples use [`jq`](https://jqlang.github.io/jq/) to parse JSON. Python and Node.js have built-in JSON parsing.

106MODEL_DISPLAY=$(echo "$input" | jq -r '.model.display_name')

107CURRENT_DIR=$(echo "$input" | jq -r '.workspace.current_dir')

108 287

109# Show git branch if in a git repo288### Context window usage

110GIT_BRANCH=""289

111if git rev-parse --git-dir > /dev/null 2>&1; then290Display the current model and context window usage with a visual progress bar. Each script reads JSON from stdin, extracts the `used_percentage` field, and builds a 10-character bar where filled blocks (▓) represent usage:

291

292<Frame>

293 <img src="https://mintcdn.com/claude-code/nibzesLaJVh4ydOq/images/statusline-context-window-usage.png?fit=max&auto=format&n=nibzesLaJVh4ydOq&q=85&s=15b58ab3602f036939145dde3165c6f7" alt="A status line showing model name and a progress bar with percentage" width="448" height="152" data-path="images/statusline-context-window-usage.png" />

294</Frame>

295

296<CodeGroup>

297 ```bash Bash theme={null}

298 #!/bin/bash

299 # Read all of stdin into a variable

300 input=$(cat)

301

302 # Extract fields with jq, "// 0" provides fallback for null

303 MODEL=$(echo "$input" | jq -r '.model.display_name')

304 PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)

305

306 # Build progress bar: printf -v creates a run of spaces, then

307 # ${var// /▓} replaces each space with a block character

308 BAR_WIDTH=10

309 FILLED=$((PCT * BAR_WIDTH / 100))

310 EMPTY=$((BAR_WIDTH - FILLED))

311 BAR=""

312 [ "$FILLED" -gt 0 ] && printf -v FILL "%${FILLED}s" && BAR="${FILL// /▓}"

313 [ "$EMPTY" -gt 0 ] && printf -v PAD "%${EMPTY}s" && BAR="${BAR}${PAD// /░}"

314

315 echo "[$MODEL] $BAR $PCT%"

316 ```

317

318 ```python Python theme={null}

319 #!/usr/bin/env python3

320 import json, sys

321

322 # json.load reads and parses stdin in one step

323 data = json.load(sys.stdin)

324 model = data['model']['display_name']

325 # "or 0" handles null values

326 pct = int(data.get('context_window', {}).get('used_percentage', 0) or 0)

327

328 # String multiplication builds the bar

329 filled = pct * 10 // 100

330 bar = '▓' * filled + '░' * (10 - filled)

331

332 print(f"[{model}] {bar} {pct}%")

333 ```

334

335 ```javascript Node.js theme={null}

336 #!/usr/bin/env node

337 // Node.js reads stdin asynchronously with events

338 let input = '';

339 process.stdin.on('data', chunk => input += chunk);

340 process.stdin.on('end', () => {

341 const data = JSON.parse(input);

342 const model = data.model.display_name;

343 // Optional chaining (?.) safely handles null fields

344 const pct = Math.floor(data.context_window?.used_percentage || 0);

345

346 // String.repeat() builds the bar

347 const filled = Math.floor(pct * 10 / 100);

348 const bar = '▓'.repeat(filled) + '░'.repeat(10 - filled);

349

350 console.log(`[${model}] ${bar} ${pct}%`);

351 });

352 ```

353</CodeGroup>

354

355### Git status with colors

356

357Show git branch with color-coded indicators for staged and modified files. This script uses [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors) for terminal colors: `\033[32m` is green, `\033[33m` is yellow, and `\033[0m` resets to default.

358

359<Frame>

360 <img src="https://mintcdn.com/claude-code/nibzesLaJVh4ydOq/images/statusline-git-context.png?fit=max&auto=format&n=nibzesLaJVh4ydOq&q=85&s=e656f34f90d1d9a1d0e220988914345f" alt="A status line showing model, directory, git branch, and colored indicators for staged and modified files" width="742" height="178" data-path="images/statusline-git-context.png" />

361</Frame>

362

363Each script checks if the current directory is a git repository, counts staged and modified files, and displays color-coded indicators:

364

365<CodeGroup>

366 ```bash Bash theme={null}

367 #!/bin/bash

368 input=$(cat)

369

370 MODEL=$(echo "$input" | jq -r '.model.display_name')

371 DIR=$(echo "$input" | jq -r '.workspace.current_dir')

372

373 GREEN='\033[32m'

374 YELLOW='\033[33m'

375 RESET='\033[0m'

376

377 if git rev-parse --git-dir > /dev/null 2>&1; then

112 BRANCH=$(git branch --show-current 2>/dev/null)378 BRANCH=$(git branch --show-current 2>/dev/null)

113 if [ -n "$BRANCH" ]; then379 STAGED=$(git diff --cached --numstat 2>/dev/null | wc -l | tr -d ' ')

114 GIT_BRANCH=" | 🌿 $BRANCH"380 MODIFIED=$(git diff --numstat 2>/dev/null | wc -l | tr -d ' ')

115 fi

116fi

117 381

118echo "[$MODEL_DISPLAY] 📁 ${CURRENT_DIR##*/}$GIT_BRANCH"382 GIT_STATUS=""

119```383 [ "$STAGED" -gt 0 ] && GIT_STATUS="${GREEN}+${STAGED}${RESET}"

384 [ "$MODIFIED" -gt 0 ] && GIT_STATUS="${GIT_STATUS}${YELLOW}~${MODIFIED}${RESET}"

120 385

121### Python Example386 echo -e "[$MODEL] 📁 ${DIR##*/} | 🌿 $BRANCH $GIT_STATUS"

387 else

388 echo "[$MODEL] 📁 ${DIR##*/}"

389 fi

390 ```

122 391

123```python theme={null}392 ```python Python theme={null}

124#!/usr/bin/env python3393 #!/usr/bin/env python3

125import json394 import json, sys, subprocess, os

126import sys

127import os

128 395

129# Read JSON from stdin396 data = json.load(sys.stdin)

130data = json.load(sys.stdin)397 model = data['model']['display_name']

398 directory = os.path.basename(data['workspace']['current_dir'])

131 399

132# Extract values400 GREEN, YELLOW, RESET = '\033[32m', '\033[33m', '\033[0m'

133model = data['model']['display_name']

134current_dir = os.path.basename(data['workspace']['current_dir'])

135 401

136# Check for git branch

137git_branch = ""

138if os.path.exists('.git'):

139 try:402 try:

140 with open('.git/HEAD', 'r') as f:403 subprocess.check_output(['git', 'rev-parse', '--git-dir'], stderr=subprocess.DEVNULL)

141 ref = f.read().strip()404 branch = subprocess.check_output(['git', 'branch', '--show-current'], text=True).strip()

142 if ref.startswith('ref: refs/heads/'):405 staged_output = subprocess.check_output(['git', 'diff', '--cached', '--numstat'], text=True).strip()

143 git_branch = f" | 🌿 {ref.replace('ref: refs/heads/', '')}"406 modified_output = subprocess.check_output(['git', 'diff', '--numstat'], text=True).strip()

407 staged = len(staged_output.split('\n')) if staged_output else 0

408 modified = len(modified_output.split('\n')) if modified_output else 0

409

410 git_status = f"{GREEN}+{staged}{RESET}" if staged else ""

411 git_status += f"{YELLOW}~{modified}{RESET}" if modified else ""

412

413 print(f"[{model}] 📁 {directory} | 🌿 {branch} {git_status}")

144 except:414 except:

145 pass415 print(f"[{model}] 📁 {directory}")

416 ```

146 417

147print(f"[{model}] 📁 {current_dir}{git_branch}")418 ```javascript Node.js theme={null}

148```419 #!/usr/bin/env node

420 const { execSync } = require('child_process');

421 const path = require('path');

422

423 let input = '';

424 process.stdin.on('data', chunk => input += chunk);

425 process.stdin.on('end', () => {

426 const data = JSON.parse(input);

427 const model = data.model.display_name;

428 const dir = path.basename(data.workspace.current_dir);

429

430 const GREEN = '\x1b[32m', YELLOW = '\x1b[33m', RESET = '\x1b[0m';

431

432 try {

433 execSync('git rev-parse --git-dir', { stdio: 'ignore' });

434 const branch = execSync('git branch --show-current', { encoding: 'utf8' }).trim();

435 const staged = execSync('git diff --cached --numstat', { encoding: 'utf8' }).trim().split('\n').filter(Boolean).length;

436 const modified = execSync('git diff --numstat', { encoding: 'utf8' }).trim().split('\n').filter(Boolean).length;

437

438 let gitStatus = staged ? `${GREEN}+${staged}${RESET}` : '';

439 gitStatus += modified ? `${YELLOW}~${modified}${RESET}` : '';

440

441 console.log(`[${model}] 📁 ${dir} | 🌿 ${branch} ${gitStatus}`);

442 } catch {

443 console.log(`[${model}] 📁 ${dir}`);

444 }

445 });

446 ```

447</CodeGroup>

448

449### Cost and duration tracking

450

451Track your session's API costs and elapsed time. The `cost.total_cost_usd` field accumulates the cost of all API calls in the current session. The `cost.total_duration_ms` field measures total elapsed time since the session started, while `cost.total_api_duration_ms` tracks only the time spent waiting for API responses.

452

453Each script formats cost as currency and converts milliseconds to minutes and seconds:

454

455<Frame>

456 <img src="https://mintcdn.com/claude-code/nibzesLaJVh4ydOq/images/statusline-cost-tracking.png?fit=max&auto=format&n=nibzesLaJVh4ydOq&q=85&s=e3444a51fe6f3440c134bd5f1f08ad29" alt="A status line showing model name, session cost, and duration" width="588" height="180" data-path="images/statusline-cost-tracking.png" />

457</Frame>

149 458

150### Node.js Example459<CodeGroup>

460 ```bash Bash theme={null}

461 #!/bin/bash

462 input=$(cat)

151 463

152```javascript theme={null}464 MODEL=$(echo "$input" | jq -r '.model.display_name')

153#!/usr/bin/env node465 COST=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')

466 DURATION_MS=$(echo "$input" | jq -r '.cost.total_duration_ms // 0')

154 467

155const fs = require('fs');468 COST_FMT=$(printf '$%.2f' "$COST")

156const path = require('path');469 DURATION_SEC=$((DURATION_MS / 1000))

470 MINS=$((DURATION_SEC / 60))

471 SECS=$((DURATION_SEC % 60))

157 472

158// Read JSON from stdin473 echo "[$MODEL] 💰 $COST_FMT | ⏱️ ${MINS}m ${SECS}s"

159let input = '';474 ```

160process.stdin.on('data', chunk => input += chunk);475

161process.stdin.on('end', () => {476 ```python Python theme={null}

477 #!/usr/bin/env python3

478 import json, sys

479

480 data = json.load(sys.stdin)

481 model = data['model']['display_name']

482 cost = data.get('cost', {}).get('total_cost_usd', 0) or 0

483 duration_ms = data.get('cost', {}).get('total_duration_ms', 0) or 0

484

485 duration_sec = duration_ms // 1000

486 mins, secs = duration_sec // 60, duration_sec % 60

487

488 print(f"[{model}] 💰 ${cost:.2f} | ⏱️ {mins}m {secs}s")

489 ```

490

491 ```javascript Node.js theme={null}

492 #!/usr/bin/env node

493 let input = '';

494 process.stdin.on('data', chunk => input += chunk);

495 process.stdin.on('end', () => {

162 const data = JSON.parse(input);496 const data = JSON.parse(input);

497 const model = data.model.display_name;

498 const cost = data.cost?.total_cost_usd || 0;

499 const durationMs = data.cost?.total_duration_ms || 0;

500

501 const durationSec = Math.floor(durationMs / 1000);

502 const mins = Math.floor(durationSec / 60);

503 const secs = durationSec % 60;

504

505 console.log(`[${model}] 💰 $${cost.toFixed(2)} | ⏱️ ${mins}m ${secs}s`);

506 });

507 ```

508</CodeGroup>

509

510### Display multiple lines

511

512Your script can output multiple lines to create a richer display. Each `echo` statement produces a separate row in the status area.

513

514<Frame>

515 <img src="https://mintcdn.com/claude-code/nibzesLaJVh4ydOq/images/statusline-multiline.png?fit=max&auto=format&n=nibzesLaJVh4ydOq&q=85&s=60f11387658acc9ff75158ae85f2ac87" alt="A multi-line status line showing model name, directory, git branch on the first line, and a context usage progress bar with cost and duration on the second line" width="776" height="212" data-path="images/statusline-multiline.png" />

516</Frame>

517

518This example combines several techniques: threshold-based colors (green under 70%, yellow 70-89%, red 90%+), a progress bar, and git branch info. Each `print` or `echo` statement creates a separate row:

519

520<CodeGroup>

521 ```bash Bash theme={null}

522 #!/bin/bash

523 input=$(cat)

524

525 MODEL=$(echo "$input" | jq -r '.model.display_name')

526 DIR=$(echo "$input" | jq -r '.workspace.current_dir')

527 COST=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')

528 PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)

529 DURATION_MS=$(echo "$input" | jq -r '.cost.total_duration_ms // 0')

163 530

164 // Extract values531 CYAN='\033[36m'; GREEN='\033[32m'; YELLOW='\033[33m'; RED='\033[31m'; RESET='\033[0m'

532

533 # Pick bar color based on context usage

534 if [ "$PCT" -ge 90 ]; then BAR_COLOR="$RED"

535 elif [ "$PCT" -ge 70 ]; then BAR_COLOR="$YELLOW"

536 else BAR_COLOR="$GREEN"; fi

537

538 FILLED=$((PCT / 10)); EMPTY=$((10 - FILLED))

539 printf -v FILL "%${FILLED}s"; printf -v PAD "%${EMPTY}s"

540 BAR="${FILL// /█}${PAD// /░}"

541

542 MINS=$((DURATION_MS / 60000)); SECS=$(((DURATION_MS % 60000) / 1000))

543

544 BRANCH=""

545 git rev-parse --git-dir > /dev/null 2>&1 && BRANCH=" | 🌿 $(git branch --show-current 2>/dev/null)"

546

547 echo -e "${CYAN}[$MODEL]${RESET} 📁 ${DIR##*/}$BRANCH"

548 COST_FMT=$(printf '$%.2f' "$COST")

549 echo -e "${BAR_COLOR}${BAR}${RESET} ${PCT}% | ${YELLOW}${COST_FMT}${RESET} | ⏱️ ${MINS}m ${SECS}s"

550 ```

551

552 ```python Python theme={null}

553 #!/usr/bin/env python3

554 import json, sys, subprocess, os

555

556 data = json.load(sys.stdin)

557 model = data['model']['display_name']

558 directory = os.path.basename(data['workspace']['current_dir'])

559 cost = data.get('cost', {}).get('total_cost_usd', 0) or 0

560 pct = int(data.get('context_window', {}).get('used_percentage', 0) or 0)

561 duration_ms = data.get('cost', {}).get('total_duration_ms', 0) or 0

562

563 CYAN, GREEN, YELLOW, RED, RESET = '\033[36m', '\033[32m', '\033[33m', '\033[31m', '\033[0m'

564

565 bar_color = RED if pct >= 90 else YELLOW if pct >= 70 else GREEN

566 filled = pct // 10

567 bar = '█' * filled + '░' * (10 - filled)

568

569 mins, secs = duration_ms // 60000, (duration_ms % 60000) // 1000

570

571 try:

572 branch = subprocess.check_output(['git', 'branch', '--show-current'], text=True, stderr=subprocess.DEVNULL).strip()

573 branch = f" | 🌿 {branch}" if branch else ""

574 except:

575 branch = ""

576

577 print(f"{CYAN}[{model}]{RESET} 📁 {directory}{branch}")

578 print(f"{bar_color}{bar}{RESET} {pct}% | {YELLOW}${cost:.2f}{RESET} | ⏱️ {mins}m {secs}s")

579 ```

580

581 ```javascript Node.js theme={null}

582 #!/usr/bin/env node

583 const { execSync } = require('child_process');

584 const path = require('path');

585

586 let input = '';

587 process.stdin.on('data', chunk => input += chunk);

588 process.stdin.on('end', () => {

589 const data = JSON.parse(input);

165 const model = data.model.display_name;590 const model = data.model.display_name;

166 const currentDir = path.basename(data.workspace.current_dir);591 const dir = path.basename(data.workspace.current_dir);

592 const cost = data.cost?.total_cost_usd || 0;

593 const pct = Math.floor(data.context_window?.used_percentage || 0);

594 const durationMs = data.cost?.total_duration_ms || 0;

595

596 const CYAN = '\x1b[36m', GREEN = '\x1b[32m', YELLOW = '\x1b[33m', RED = '\x1b[31m', RESET = '\x1b[0m';

597

598 const barColor = pct >= 90 ? RED : pct >= 70 ? YELLOW : GREEN;

599 const filled = Math.floor(pct / 10);

600 const bar = '█'.repeat(filled) + '░'.repeat(10 - filled);

167 601

168 // Check for git branch602 const mins = Math.floor(durationMs / 60000);

169 let gitBranch = '';603 const secs = Math.floor((durationMs % 60000) / 1000);

604

605 let branch = '';

170 try {606 try {

171 const headContent = fs.readFileSync('.git/HEAD', 'utf8').trim();607 branch = execSync('git branch --show-current', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'] }).trim();

172 if (headContent.startsWith('ref: refs/heads/')) {608 branch = branch ? ` | 🌿 ${branch}` : '';

173 gitBranch = ` | 🌿 ${headContent.replace('ref: refs/heads/', '')}`;609 } catch {}

610

611 console.log(`${CYAN}[${model}]${RESET} 📁 ${dir}${branch}`);

612 console.log(`${barColor}${bar}${RESET} ${pct}% | ${YELLOW}$${cost.toFixed(2)}${RESET} | ⏱️ ${mins}m ${secs}s`);

613 });

614 ```

615</CodeGroup>

616

617### Clickable links

618

619This example creates a clickable link to your GitHub repository. It reads the git remote URL, converts SSH format to HTTPS with `sed`, and wraps the repo name in OSC 8 escape codes. Hold Cmd (macOS) or Ctrl (Windows/Linux) and click to open the link in your browser.

620

621<Frame>

622 <img src="https://mintcdn.com/claude-code/nibzesLaJVh4ydOq/images/statusline-links.png?fit=max&auto=format&n=nibzesLaJVh4ydOq&q=85&s=4bcc6e7deb7cf52f41ab85a219b52661" alt="A status line showing a clickable link to a GitHub repository" width="726" height="198" data-path="images/statusline-links.png" />

623</Frame>

624

625Each script gets the git remote URL, converts SSH format to HTTPS, and wraps the repo name in OSC 8 escape codes. The Bash version uses `printf '%b'` which interprets backslash escapes more reliably than `echo -e` across different shells:

626

627<CodeGroup>

628 ```bash Bash theme={null}

629 #!/bin/bash

630 input=$(cat)

631

632 MODEL=$(echo "$input" | jq -r '.model.display_name')

633

634 # Convert git SSH URL to HTTPS

635 REMOTE=$(git remote get-url origin 2>/dev/null | sed 's/git@github.com:/https:\/\/github.com\//' | sed 's/\.git$//')

636

637 if [ -n "$REMOTE" ]; then

638 REPO_NAME=$(basename "$REMOTE")

639 # OSC 8 format: \e]8;;URL\a then TEXT then \e]8;;\a

640 # printf %b interprets escape sequences reliably across shells

641 printf '%b' "[$MODEL] 🔗 \e]8;;${REMOTE}\a${REPO_NAME}\e]8;;\a\n"

642 else

643 echo "[$MODEL]"

644 fi

645 ```

646

647 ```python Python theme={null}

648 #!/usr/bin/env python3

649 import json, sys, subprocess, re, os

650

651 data = json.load(sys.stdin)

652 model = data['model']['display_name']

653

654 # Get git remote URL

655 try:

656 remote = subprocess.check_output(

657 ['git', 'remote', 'get-url', 'origin'],

658 stderr=subprocess.DEVNULL, text=True

659 ).strip()

660 # Convert SSH to HTTPS format

661 remote = re.sub(r'^git@github\.com:', 'https://github.com/', remote)

662 remote = re.sub(r'\.git$', '', remote)

663 repo_name = os.path.basename(remote)

664 # OSC 8 escape sequences

665 link = f"\033]8;;{remote}\a{repo_name}\033]8;;\a"

666 print(f"[{model}] 🔗 {link}")

667 except:

668 print(f"[{model}]")

669 ```

670

671 ```javascript Node.js theme={null}

672 #!/usr/bin/env node

673 const { execSync } = require('child_process');

674 const path = require('path');

675

676 let input = '';

677 process.stdin.on('data', chunk => input += chunk);

678 process.stdin.on('end', () => {

679 const data = JSON.parse(input);

680 const model = data.model.display_name;

681

682 try {

683 let remote = execSync('git remote get-url origin', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'] }).trim();

684 // Convert SSH to HTTPS format

685 remote = remote.replace(/^git@github\.com:/, 'https://github.com/').replace(/\.git$/, '');

686 const repoName = path.basename(remote);

687 // OSC 8 escape sequences

688 const link = `\x1b]8;;${remote}\x07${repoName}\x1b]8;;\x07`;

689 console.log(`[${model}] 🔗 ${link}`);

690 } catch {

691 console.log(`[${model}]`);

174 }692 }

175 } catch (e) {693 });

176 // Not a git repo or can't read HEAD694 ```

695</CodeGroup>

696

697### Rate limit usage

698

699Display Claude.ai subscription rate limit usage in the status line. The `rate_limits` object contains `five_hour` (5-hour rolling window) and `seven_day` (weekly) windows. Each window provides `used_percentage` (0-100) and `resets_at` (Unix epoch seconds when the window resets).

700

701This field is only present for Claude.ai subscribers (Pro/Max) after the first API response. Each script handles the absent field gracefully:

702

703<CodeGroup>

704 ```bash Bash theme={null}

705 #!/bin/bash

706 input=$(cat)

707

708 MODEL=$(echo "$input" | jq -r '.model.display_name')

709 # "// empty" produces no output when rate_limits is absent

710 FIVE_H=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty')

711 WEEK=$(echo "$input" | jq -r '.rate_limits.seven_day.used_percentage // empty')

712

713 LIMITS=""

714 [ -n "$FIVE_H" ] && LIMITS="5h: $(printf '%.0f' "$FIVE_H")%"

715 [ -n "$WEEK" ] && LIMITS="${LIMITS:+$LIMITS }7d: $(printf '%.0f' "$WEEK")%"

716

717 [ -n "$LIMITS" ] && echo "[$MODEL] | $LIMITS" || echo "[$MODEL]"

718 ```

719

720 ```python Python theme={null}

721 #!/usr/bin/env python3

722 import json, sys

723

724 data = json.load(sys.stdin)

725 model = data['model']['display_name']

726

727 parts = []

728 rate = data.get('rate_limits', {})

729 five_h = rate.get('five_hour', {}).get('used_percentage')

730 week = rate.get('seven_day', {}).get('used_percentage')

731

732 if five_h is not None:

733 parts.append(f"5h: {five_h:.0f}%")

734 if week is not None:

735 parts.append(f"7d: {week:.0f}%")

736

737 if parts:

738 print(f"[{model}] | {' '.join(parts)}")

739 else:

740 print(f"[{model}]")

741 ```

742

743 ```javascript Node.js theme={null}

744 #!/usr/bin/env node

745 let input = '';

746 process.stdin.on('data', chunk => input += chunk);

747 process.stdin.on('end', () => {

748 const data = JSON.parse(input);

749 const model = data.model.display_name;

750

751 const parts = [];

752 const fiveH = data.rate_limits?.five_hour?.used_percentage;

753 const week = data.rate_limits?.seven_day?.used_percentage;

754

755 if (fiveH != null) parts.push(`5h: ${Math.round(fiveH)}%`);

756 if (week != null) parts.push(`7d: ${Math.round(week)}%`);

757

758 console.log(parts.length ? `[${model}] | ${parts.join(' ')}` : `[${model}]`);

759 });

760 ```

761</CodeGroup>

762

763### Cache expensive operations

764

765Your status line script runs frequently during active sessions. Commands like `git status` or `git diff` can be slow, especially in large repositories. This example caches git information to a temp file and only refreshes it every 5 seconds.

766

767Use a stable, fixed filename for the cache file like `/tmp/statusline-git-cache`. Each status line invocation runs as a new process, so process-based identifiers like `$$`, `os.getpid()`, or `process.pid` produce a different value every time and the cache is never reused.

768

769Each script checks if the cache file is missing or older than 5 seconds before running git commands:

770

771<CodeGroup>

772 ```bash Bash theme={null}

773 #!/bin/bash

774 input=$(cat)

775

776 MODEL=$(echo "$input" | jq -r '.model.display_name')

777 DIR=$(echo "$input" | jq -r '.workspace.current_dir')

778

779 CACHE_FILE="/tmp/statusline-git-cache"

780 CACHE_MAX_AGE=5 # seconds

781

782 cache_is_stale() {

783 [ ! -f "$CACHE_FILE" ] || \

784 # stat -f %m is macOS, stat -c %Y is Linux

785 [ $(($(date +%s) - $(stat -f %m "$CACHE_FILE" 2>/dev/null || stat -c %Y "$CACHE_FILE" 2>/dev/null || echo 0))) -gt $CACHE_MAX_AGE ]

177 }786 }

178 787

179 console.log(`[${model}] 📁 ${currentDir}${gitBranch}`);788 if cache_is_stale; then

180});789 if git rev-parse --git-dir > /dev/null 2>&1; then

181```790 BRANCH=$(git branch --show-current 2>/dev/null)

791 STAGED=$(git diff --cached --numstat 2>/dev/null | wc -l | tr -d ' ')

792 MODIFIED=$(git diff --numstat 2>/dev/null | wc -l | tr -d ' ')

793 echo "$BRANCH|$STAGED|$MODIFIED" > "$CACHE_FILE"

794 else

795 echo "||" > "$CACHE_FILE"

796 fi

797 fi

182 798

183### Helper Function Approach799 IFS='|' read -r BRANCH STAGED MODIFIED < "$CACHE_FILE"

~~184~~ 800

185For more complex bash scripts, you can create helper functions:801 if [ -n "$BRANCH" ]; then

~~186~~ 802 echo "[$MODEL] 📁 ${DIR##*/} | 🌿 $BRANCH +$STAGED ~$MODIFIED"

187```bash theme={null}803 else

188#!/bin/bash804 echo "[$MODEL] 📁 ${DIR##*/}"

189# Read JSON input once805 fi

190input=$(cat)806 ```

~~191~~

192# Helper functions for common extractions

193get_model_name() { echo "$input" | jq -r '.model.display_name'; }

194get_current_dir() { echo "$input" | jq -r '.workspace.current_dir'; }

195get_project_dir() { echo "$input" | jq -r '.workspace.project_dir'; }

196get_version() { echo "$input" | jq -r '.version'; }

197get_cost() { echo "$input" | jq -r '.cost.total_cost_usd'; }

198get_duration() { echo "$input" | jq -r '.cost.total_duration_ms'; }

199get_lines_added() { echo "$input" | jq -r '.cost.total_lines_added'; }

200get_lines_removed() { echo "$input" | jq -r '.cost.total_lines_removed'; }

201get_input_tokens() { echo "$input" | jq -r '.context_window.total_input_tokens'; }

202get_output_tokens() { echo "$input" | jq -r '.context_window.total_output_tokens'; }

203get_context_window_size() { echo "$input" | jq -r '.context_window.context_window_size'; }

~~204~~

205# Use the helpers

206MODEL=$(get_model_name)

207DIR=$(get_current_dir)

208echo "[$MODEL] 📁 ${DIR##*/}"

209```

210 807

211### Context Window Usage808 ```python Python theme={null}

809 #!/usr/bin/env python3

810 import json, sys, subprocess, os, time

212 811

213Display the percentage of context window consumed. The `context_window` object contains:812 data = json.load(sys.stdin)

813 model = data['model']['display_name']

814 directory = os.path.basename(data['workspace']['current_dir'])

214 815

215* `total_input_tokens` / `total_output_tokens`: Cumulative totals across the entire session816 CACHE_FILE = "/tmp/statusline-git-cache"

216* `used_percentage`: Pre-calculated percentage of context window used (0-100)817 CACHE_MAX_AGE = 5 # seconds

217* `remaining_percentage`: Pre-calculated percentage of context window remaining (0-100)

218* `current_usage`: Current context window usage from the last API call (may be `null` if no messages yet)

219 * `input_tokens`: Input tokens in current context

220 * `output_tokens`: Output tokens generated

221 * `cache_creation_input_tokens`: Tokens written to cache

222 * `cache_read_input_tokens`: Tokens read from cache

223 818

224You can use the pre-calculated `used_percentage` and `remaining_percentage` fields directly, or calculate from `current_usage` for more control.819 def cache_is_stale():

820 if not os.path.exists(CACHE_FILE):

821 return True

822 return time.time() - os.path.getmtime(CACHE_FILE) > CACHE_MAX_AGE

225 823

226**Simple approach using pre-calculated percentages:**824 if cache_is_stale():

825 try:

826 subprocess.check_output(['git', 'rev-parse', '--git-dir'], stderr=subprocess.DEVNULL)

827 branch = subprocess.check_output(['git', 'branch', '--show-current'], text=True).strip()

828 staged = subprocess.check_output(['git', 'diff', '--cached', '--numstat'], text=True).strip()

829 modified = subprocess.check_output(['git', 'diff', '--numstat'], text=True).strip()

830 staged_count = len(staged.split('\n')) if staged else 0

831 modified_count = len(modified.split('\n')) if modified else 0

832 with open(CACHE_FILE, 'w') as f:

833 f.write(f"{branch}|{staged_count}|{modified_count}")

834 except:

835 with open(CACHE_FILE, 'w') as f:

836 f.write("||")

837

838 with open(CACHE_FILE) as f:

839 branch, staged, modified = f.read().strip().split('|')

840

841 if branch:

842 print(f"[{model}] 📁 {directory} | 🌿 {branch} +{staged} ~{modified}")

843 else:

844 print(f"[{model}] 📁 {directory}")

845 ```

846

847 ```javascript Node.js theme={null}

848 #!/usr/bin/env node

849 const { execSync } = require('child_process');

850 const fs = require('fs');

851 const path = require('path');

852

853 let input = '';

854 process.stdin.on('data', chunk => input += chunk);

855 process.stdin.on('end', () => {

856 const data = JSON.parse(input);

857 const model = data.model.display_name;

858 const dir = path.basename(data.workspace.current_dir);

227 859

228```bash theme={null}860 const CACHE_FILE = '/tmp/statusline-git-cache';

229#!/bin/bash861 const CACHE_MAX_AGE = 5; // seconds

230input=$(cat)

231 862

232MODEL=$(echo "$input" | jq -r '.model.display_name')863 const cacheIsStale = () => {

233PERCENT_USED=$(echo "$input" | jq -r '.context_window.used_percentage // 0')864 if (!fs.existsSync(CACHE_FILE)) return true;

865 return (Date.now() / 1000) - fs.statSync(CACHE_FILE).mtimeMs / 1000 > CACHE_MAX_AGE;

866 };

234 867

235echo "[$MODEL] Context: ${PERCENT_USED}%"868 if (cacheIsStale()) {

236```869 try {

870 execSync('git rev-parse --git-dir', { stdio: 'ignore' });

871 const branch = execSync('git branch --show-current', { encoding: 'utf8' }).trim();

872 const staged = execSync('git diff --cached --numstat', { encoding: 'utf8' }).trim().split('\n').filter(Boolean).length;

873 const modified = execSync('git diff --numstat', { encoding: 'utf8' }).trim().split('\n').filter(Boolean).length;

874 fs.writeFileSync(CACHE_FILE, `${branch}|${staged}|${modified}`);

875 } catch {

876 fs.writeFileSync(CACHE_FILE, '||');

877 }

878 }

237 879

238**Advanced approach with manual calculation:**880 const [branch, staged, modified] = fs.readFileSync(CACHE_FILE, 'utf8').trim().split('|');

239 881

240```bash theme={null}882 if (branch) {

241#!/bin/bash883 console.log(`[${model}] 📁 ${dir} | 🌿 ${branch} +${staged} ~${modified}`);

242input=$(cat)884 } else {

885 console.log(`[${model}] 📁 ${dir}`);

886 }

887 });

888 ```

889</CodeGroup>

243 890

244MODEL=$(echo "$input" | jq -r '.model.display_name')891### Windows configuration

245CONTEXT_SIZE=$(echo "$input" | jq -r '.context_window.context_window_size')

246USAGE=$(echo "$input" | jq '.context_window.current_usage')

247 892

248if [ "$USAGE" != "null" ]; then893On Windows, Claude Code runs status line commands through Git Bash. You can invoke PowerShell from that shell:

249 # Calculate current context from current_usage fields894

250 CURRENT_TOKENS=$(echo "$USAGE" | jq '.input_tokens + .cache_creation_input_tokens + .cache_read_input_tokens')895<CodeGroup>

251 PERCENT_USED=$((CURRENT_TOKENS * 100 / CONTEXT_SIZE))896 ```json settings.json theme={null}

252 echo "[$MODEL] Context: ${PERCENT_USED}%"897 {

253else898 "statusLine": {

254 echo "[$MODEL] Context: 0%"899 "type": "command",

255fi900 "command": "powershell -NoProfile -File C:/Users/username/.claude/statusline.ps1"

256```901 }

902 }

903 ```

904

905 ```powershell statusline.ps1 theme={null}

906 $input_json = $input | Out-String | ConvertFrom-Json

907 $cwd = $input_json.cwd

908 $model = $input_json.model.display_name

909 $used = $input_json.context_window.used_percentage

910 $dirname = Split-Path $cwd -Leaf

911

912 if ($used) {

913 Write-Host "$dirname [$model] ctx: $used%"

914 } else {

915 Write-Host "$dirname [$model]"

916 }

917 ```

918</CodeGroup>

919

920Or run a Bash script directly:

921

922<CodeGroup>

923 ```json settings.json theme={null}

924 {

925 "statusLine": {

926 "type": "command",

927 "command": "~/.claude/statusline.sh"

928 }

929 }

930 ```

931

932 ```bash statusline.sh theme={null}

933 #!/usr/bin/env bash

934 input=$(cat)

935 cwd=$(echo "$input" | grep -o '"cwd":"[^"]*"' | cut -d'"' -f4)

936 model=$(echo "$input" | grep -o '"display_name":"[^"]*"' | cut -d'"' -f4)

937 dirname="${cwd##*[/\\]}"

938 echo "$dirname [$model]"

939 ```

940</CodeGroup>

257 941

258## Tips942## Tips

259 943

260* Keep your status line concise - it should fit on one line944* **Test with mock input**: `echo '{"model":{"display_name":"Opus"},"context_window":{"used_percentage":25}}' | ./statusline.sh`

261* Use emojis (if your terminal supports them) and colors to make information scannable945* **Keep output short**: the status bar has limited width, so long output may get truncated or wrap awkwardly

262* Use `jq` for JSON parsing in Bash (see examples above)946* **Cache slow operations**: your script runs frequently during active sessions, so commands like `git status` can cause lag. See the [caching example](#cache-expensive-operations) for how to handle this.

263* Test your script by running it manually with mock JSON input: `echo '{"model":{"display_name":"Test"},"workspace":{"current_dir":"/test"}}' | ./statusline.sh`947

264* Consider caching expensive operations (like git status) if needed948Community projects like [ccstatusline](https://github.com/sirmalloc/ccstatusline) and [starship-claude](https://github.com/martinemde/starship-claude) provide pre-built configurations with themes and additional features.

265 949

266## Troubleshooting950## Troubleshooting

267 951

268* If your status line doesn't appear, check that your script is executable (`chmod +x`)952**Status line not appearing**

269* Ensure your script outputs to stdout (not stderr)953

954* Verify your script is executable: `chmod +x ~/.claude/statusline.sh`

955* Check that your script outputs to stdout, not stderr

956* Run your script manually to verify it produces output

957* If `disableAllHooks` is set to `true` in your settings, the status line is also disabled. Remove this setting or set it to `false` to re-enable.

958* Run `claude --debug` to log the exit code and stderr from the first status line invocation in a session

959* Ask Claude to read your settings file and execute the `statusLine` command directly to surface errors

960

961**Status line shows `--` or empty values**

962

963* Fields may be `null` before the first API response completes

964* Handle null values in your script with fallbacks such as `// 0` in jq

965* Restart Claude Code if values remain empty after multiple messages

966

967**Context percentage shows unexpected values**

968

969* Use `used_percentage` for accurate context state rather than cumulative totals

970* The `total_input_tokens` and `total_output_tokens` are cumulative across the session and may exceed the context window size

971* Context percentage may differ from `/context` output due to when each is calculated

972

973**OSC 8 links not clickable**

974

975* Verify your terminal supports OSC 8 hyperlinks (iTerm2, Kitty, WezTerm)

976* Terminal.app does not support clickable links

977* SSH and tmux sessions may strip OSC sequences depending on configuration

978* If escape sequences appear as literal text like `\e]8;;`, use `printf '%b'` instead of `echo -e` for more reliable escape handling

979

980**Display glitches with escape sequences**

981

982* Complex escape sequences (ANSI colors, OSC 8 links) can occasionally cause garbled output if they overlap with other UI updates

983* If you see corrupted text, try simplifying your script to plain text output

984* Multi-line status lines with escape codes are more prone to rendering issues than single-line plain text

985

986**Workspace trust required**

987

988* The status line command only runs if you've accepted the workspace trust dialog for the current directory. Because `statusLine` executes a shell command, it requires the same trust acceptance as hooks and other shell-executing settings.

989* If trust isn't accepted, you'll see the notification `statusline skipped · restart to fix` instead of your status line output. Restart Claude Code and accept the trust prompt to enable it.

990

991**Script errors or hangs**

992

993* Scripts that exit with non-zero codes or produce no output cause the status line to go blank

994* Slow scripts block the status line from updating until they complete. Keep scripts fast to avoid stale output.

995* If a new update triggers while a slow script is running, the in-flight script is cancelled

996* Test your script independently with mock input before configuring it

997

998**Notifications share the status line row**

999

1000* System notifications like MCP server errors, auto-updates, and token warnings display on the right side of the same row as your status line

1001* Enabling verbose mode adds a token counter to this area

1002* On narrow terminals, these notifications may truncate your status line output

sub-agents.md +221 −37

Details

6 6

7> Create and use specialized AI subagents in Claude Code for task-specific workflows and improved context management.7> Create and use specialized AI subagents in Claude Code for task-specific workflows and improved context management.

8 8

9Subagents are specialized AI assistants that handle specific types of tasks. Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions. When Claude encounters a task that matches a subagent's description, it delegates to that subagent, which works independently and returns results.9Subagents are specialized AI assistants that handle specific types of tasks. Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions. When Claude encounters a task that matches a subagent's description, it delegates to that subagent, which works independently and returns results. To see the context savings in practice, the [context window visualization](/en/context-window) walks through a session where a subagent handles research in its own separate window.

11<Note>

12 If you need multiple agents working in parallel and communicating with each other, see [agent teams](/en/agent-teams) instead. Subagents work within a single session; agent teams coordinate across separate sessions.

13</Note>

10 14

11Subagents help you:15Subagents help you:

12 16

74 78

75Subagents are defined in Markdown files with YAML frontmatter. You can [create them manually](#write-subagent-files) or use the `/agents` command.79Subagents are defined in Markdown files with YAML frontmatter. You can [create them manually](#write-subagent-files) or use the `/agents` command.

76 80

~~77This walkthrough guides you through creating a user-level subagent with the `/agent` command. The subagent reviews code and suggests improvements for the codebase.~~81This walkthrough guides you through creating a user-level subagent with the `/agents` command. The subagent reviews code and suggests improvements for the codebase.

78 82

79<Steps>83<Steps>

80 <Step title="Open the subagents interface">84 <Step title="Open the subagents interface">

81 In Claude Code, run:85 In Claude Code, run:

82 86

~~83 ```~~87 ```text theme={null}

84 /agents88 /agents

85 ```89 ```

86 </Step>90 </Step>

87 91

~~88 <Step title="Create a new user-level agent">~~92 <Step title="Choose a location">

~~89 Select **Create new agent**, then choose **User-level**. This saves the subagent to `~/.claude/agents/` so it's available in all your projects.~~93 Select **Create new agent**, then choose **Personal**. This saves the subagent to `~/.claude/agents/` so it's available in all your projects.

90 </Step>94 </Step>

91 95

92 <Step title="Generate with Claude">96 <Step title="Generate with Claude">

93 Select **Generate with Claude**. When prompted, describe the subagent:97 Select **Generate with Claude**. When prompted, describe the subagent:

94 98

~~95 ```~~99 ```text theme={null}

96 A code improvement agent that scans files and suggests improvements100 A code improvement agent that scans files and suggests improvements

97 for readability, performance, and best practices. It should explain101 for readability, performance, and best practices. It should explain

98 each issue, show the current code, and provide an improved version.102 each issue, show the current code, and provide an improved version.

99 ```103 ```

100 104

101 Claude generates the system prompt and configuration. Press `e` to open it in your editor if you want to customize it.105 Claude generates the identifier, description, and system prompt for you.

102 </Step>106 </Step>

103 107

104 <Step title="Select tools">108 <Step title="Select tools">

113 Pick a background color for the subagent. This helps you identify which subagent is running in the UI.117 Pick a background color for the subagent. This helps you identify which subagent is running in the UI.

114 </Step>118 </Step>

115 119

120 <Step title="Configure memory">

121 Select **User scope** to give the subagent a [persistent memory directory](#enable-persistent-memory) at `~/.claude/agent-memory/`. The subagent uses this to accumulate insights across conversations, such as codebase patterns and recurring issues. Select **None** if you don't want the subagent to persist learnings.

122 </Step>

123

116 <Step title="Save and try it out">124 <Step title="Save and try it out">

117 Save the subagent. It's available immediately (no restart needed). Try it:125 Review the configuration summary. Press `s` or `Enter` to save, or press `e` to save and edit the file in your editor. The subagent is available immediately. Try it:

118 126

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

120 Use the code-improver agent to suggest improvements in this project128 Use the code-improver agent to suggest improvements in this project

121 ```129 ```

122 130

142 150

143This is the recommended way to create and manage subagents. For manual creation or automation, you can also add subagent files directly.151This is the recommended way to create and manage subagents. For manual creation or automation, you can also add subagent files directly.

144 152

153To list all configured subagents from the command line without starting an interactive session, run `claude agents`. This shows agents grouped by source and indicates which are overridden by higher-priority definitions.

154

145### Choose the subagent scope155### Choose the subagent scope

146 156

147Subagents are Markdown files with YAML frontmatter. Store them in different locations depending on scope. When multiple subagents share the same name, the higher-priority location wins.157Subagents are Markdown files with YAML frontmatter. Store them in different locations depending on scope. When multiple subagents share the same name, the higher-priority location wins.

157 167

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

159 169

160**CLI-defined subagents** are passed as JSON when launching Claude Code. They exist only for that session and aren't saved to disk, making them useful for quick testing or automation scripts:170**CLI-defined subagents** are passed as JSON when launching Claude Code. They exist only for that session and aren't saved to disk, making them useful for quick testing or automation scripts. You can define multiple subagents in a single `--agents` call:

161 171

162```bash theme={null}172```bash theme={null}

163claude --agents '{173claude --agents '{

166 "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",176 "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",

167 "tools": ["Read", "Grep", "Glob", "Bash"],177 "tools": ["Read", "Grep", "Glob", "Bash"],

168 "model": "sonnet"178 "model": "sonnet"

179 },

180 "debugger": {

181 "description": "Debugging specialist for errors and test failures.",

182 "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."

169 }183 }

170}'184}'

171```185```

172 186

173The `--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.187The `--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`, `initialPrompt`, `memory`, `effort`, `background`, and `isolation`. Use `prompt` for the system prompt, equivalent to the markdown body in file-based subagents.

174 188

175**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.189**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.

176 190

191<Note>

192 For security reasons, plugin subagents do not support the `hooks`, `mcpServers`, or `permissionMode` frontmatter fields. These fields are ignored when loading agents from a plugin. If you need them, copy the agent file into `.claude/agents/` or `~/.claude/agents/`. You can also add rules to [`permissions.allow`](/en/settings#permission-settings) in `settings.json` or `settings.local.json`, but these rules apply to the entire session, not just the plugin subagent.

193</Note>

194

177### Write subagent files195### Write subagent files

178 196

179Subagent files use YAML frontmatter for configuration, followed by the system prompt in Markdown:197Subagent files use YAML frontmatter for configuration, followed by the system prompt in Markdown:

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

202 220

204| :---------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |222| :---------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

205| `name` | Yes | Unique identifier using lowercase letters and hyphens |223| `name` | Yes | Unique identifier using lowercase letters and hyphens |

206| `description` | Yes | When Claude should delegate to this subagent |224| `description` | Yes | When Claude should delegate to this subagent |

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

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

209| `model` | No | [Model](#choose-a-model) to use: `sonnet`, `opus`, `haiku`, or `inherit`. Defaults to `inherit` |227| `model` | No | [Model](#choose-a-model) to use: `sonnet`, `opus`, `haiku`, a full model ID (for example, `claude-opus-4-6`), or `inherit`. Defaults to `inherit` |

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

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

211| `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 |230| `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 |

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

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

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

234| `background` | No | Set to `true` to always run this subagent as a [background task](#run-subagents-in-foreground-or-background). Default: `false` |

235| `effort` | No | Effort level when this subagent is active. Overrides the session effort level. Default: inherits from session. Options: `low`, `medium`, `high`, `max` (Opus 4.6 only) |

236| `isolation` | No | Set to `worktree` to run the subagent in a temporary [git worktree](/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees), giving it an isolated copy of the repository. The worktree is automatically cleaned up if the subagent makes no changes |

237| `initialPrompt` | No | Auto-submitted as the first user turn when this agent runs as the main session agent (via `--agent` or the `agent` setting). [Commands](/en/commands) and [skills](/en/skills) are processed. Prepended to any user-provided prompt |

213 238

214### Choose a model239### Choose a model

215 240

216The `model` field controls which [AI model](/en/model-config) the subagent uses:241The `model` field controls which [AI model](/en/model-config) the subagent uses:

217 242

218* **Model alias**: Use one of the available aliases: `sonnet`, `opus`, or `haiku`243* **Model alias**: Use one of the available aliases: `sonnet`, `opus`, or `haiku`

244* **Full model ID**: Use a full model ID such as `claude-opus-4-6` or `claude-sonnet-4-6`. Accepts the same values as the `--model` flag

219* **inherit**: Use the same model as the main conversation245* **inherit**: Use the same model as the main conversation

220* **Omitted**: If not specified, defaults to `inherit` (uses the same model as the main conversation)246* **Omitted**: If not specified, defaults to `inherit` (uses the same model as the main conversation)

221 247

248When Claude invokes a subagent, it can also pass a `model` parameter for that specific invocation. Claude Code resolves the subagent's model in this order:

249

2501. The [`CLAUDE_CODE_SUBAGENT_MODEL`](/en/model-config#environment-variables) environment variable, if set

2512. The per-invocation `model` parameter

2523. The subagent definition's `model` frontmatter

2534. The main conversation's model

254

222### Control subagent capabilities255### Control subagent capabilities

223 256

224You can control what subagents can do through tool access, permission modes, and conditional rules.257You can control what subagents can do through tool access, permission modes, and conditional rules.

225 258

226#### Available tools259#### Available tools

227 260

228Subagents can use any of Claude Code's [internal tools](/en/settings#tools-available-to-claude). By default, subagents inherit all tools from the main conversation, including MCP tools.261Subagents can use any of Claude Code's [internal tools](/en/tools-reference). By default, subagents inherit all tools from the main conversation, including MCP tools.

229 262

230To restrict tools, use the `tools` field (allowlist) or `disallowedTools` field (denylist):263To restrict tools, use either the `tools` field (allowlist) or the `disallowedTools` field (denylist). This example uses `tools` to exclusively allow Read, Grep, Glob, and Bash. The subagent can't edit files, write files, or use any MCP tools:

231 264

232```yaml theme={null}265```yaml theme={null}

233---266---

234name: safe-researcher267name: safe-researcher

235description: Research agent with restricted capabilities268description: Research agent with restricted capabilities

236tools: Read, Grep, Glob, Bash269tools: Read, Grep, Glob, Bash

270---

271```

272

273This example uses `disallowedTools` to inherit every tool from the main conversation except Write and Edit. The subagent keeps Bash, MCP tools, and everything else:

274

275```yaml theme={null}

276---

277name: no-writes

278description: Inherits every tool except file writes

237disallowedTools: Write, Edit279disallowedTools: Write, Edit

238---280---

239```281```

240 282

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

284

285#### Restrict which subagents can be spawned

286

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

288

289<Note>In version 2.1.63, the Task tool was renamed to Agent. Existing `Task(...)` references in settings and agent definitions still work as aliases.</Note>

290

291```yaml theme={null}

292---

293name: coordinator

294description: Coordinates work across specialized agents

295tools: Agent(worker, researcher), Read, Bash

296---

297```

298

299This 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.

300

301To allow spawning any subagent without restrictions, use `Agent` without parentheses:

302

303```yaml theme={null}

304tools: Agent, Read, Bash

305```

306

307If `Agent` 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 `Agent(agent_type)` has no effect in subagent definitions.

308

309#### Scope MCP servers to a subagent

310

311Use the `mcpServers` field to give a subagent access to [MCP](/en/mcp) servers that aren't available in the main conversation. Inline servers defined here are connected when the subagent starts and disconnected when it finishes. String references share the parent session's connection.

312

313Each entry in the list is either an inline server definition or a string referencing an MCP server already configured in your session:

314

315```yaml theme={null}

316---

317name: browser-tester

318description: Tests features in a real browser using Playwright

319mcpServers:

320 # Inline definition: scoped to this subagent only

321 - playwright:

322 type: stdio

323 command: npx

324 args: ["-y", "@playwright/mcp@latest"]

325 # Reference by name: reuses an already-configured server

326 - github

327---

328

329Use the Playwright tools to navigate, screenshot, and interact with pages.

330```

331

332Inline definitions use the same schema as `.mcp.json` server entries (`stdio`, `http`, `sse`, `ws`), keyed by the server name.

333

334To keep an MCP server out of the main conversation entirely and avoid its tool descriptions consuming context there, define it inline here rather than in `.mcp.json`. The subagent gets the tools; the parent conversation does not.

335

241#### Permission modes336#### Permission modes

242 337

243The `permissionMode` field controls how the subagent handles permission prompts. Subagents inherit the permission context from the main conversation but can override the mode.338The `permissionMode` field controls how the subagent handles permission prompts. Subagents inherit the permission context from the main conversation and can override the mode, except when the parent mode takes precedence as described below.

244 339

245| Mode | Behavior |340| Mode | Behavior |

246| :------------------ | :----------------------------------------------------------------- |341| :------------------ | :----------------------------------------------------------------- |

252 347

253<Warning>348<Warning>

254 Use `bypassPermissions` with caution. It skips all permission checks, allowing the subagent to execute any operation without approval.349 Use `bypassPermissions` with caution. It skips permission prompts, allowing the subagent to execute operations without approval. Writes to `.git`, `.claude`, `.vscode`, and `.idea` directories still prompt for confirmation, except for `.claude/commands`, `.claude/agents`, and `.claude/skills`. See [permission modes](/en/permission-modes#skip-all-checks-with-bypasspermissions-mode) for details.

255</Warning>350</Warning>

256 351

257If the parent uses `bypassPermissions`, this takes precedence and cannot be overridden.352If the parent uses `bypassPermissions`, this takes precedence and cannot be overridden. If the parent uses [auto mode](/en/permission-modes#eliminate-prompts-with-auto-mode), the subagent inherits auto mode and any `permissionMode` in its frontmatter is ignored: the classifier evaluates the subagent's tool calls with the same block and allow rules as the parent session.

258 353

259#### Preload skills into subagents354#### Preload skills into subagents

260 355

278 This is the inverse of [running a skill in a subagent](/en/skills#run-skills-in-a-subagent). With `skills` in a subagent, the subagent controls the system prompt and loads skill content. With `context: fork` in a skill, the skill content is injected into the agent you specify. Both use the same underlying system.373 This is the inverse of [running a skill in a subagent](/en/skills#run-skills-in-a-subagent). With `skills` in a subagent, the subagent controls the system prompt and loads skill content. With `context: fork` in a skill, the skill content is injected into the agent you specify. Both use the same underlying system.

279</Note>374</Note>

280 375

376#### Enable persistent memory

377

378The `memory` field gives the subagent a persistent directory that survives across conversations. The subagent uses this directory to build up knowledge over time, such as codebase patterns, debugging insights, and architectural decisions.

379

380```yaml theme={null}

381---

382name: code-reviewer

383description: Reviews code for quality and best practices

384memory: user

385---

386

387You are a code reviewer. As you review code, update your agent memory with

388patterns, conventions, and recurring issues you discover.

389```

390

391Choose a scope based on how broadly the memory should apply:

392

393| Scope | Location | Use when |

394| :-------- | :-------------------------------------------- | :------------------------------------------------------------------------------------------ |

395| `user` | `~/.claude/agent-memory/<name-of-agent>/` | the subagent should remember learnings across all projects |

396| `project` | `.claude/agent-memory/<name-of-agent>/` | the subagent's knowledge is project-specific and shareable via version control |

397| `local` | `.claude/agent-memory-local/<name-of-agent>/` | the subagent's knowledge is project-specific but should not be checked into version control |

398

399When memory is enabled:

400

401* The subagent's system prompt includes instructions for reading and writing to the memory directory.

402* The subagent's system prompt also includes the first 200 lines or 25KB of `MEMORY.md` in the memory directory, whichever comes first, with instructions to curate `MEMORY.md` if it exceeds that limit.

403* Read, Write, and Edit tools are automatically enabled so the subagent can manage its memory files.

404

405##### Persistent memory tips

406

407* `project` is the recommended default scope. It makes subagent knowledge shareable via version control. Use `user` when the subagent's knowledge is broadly applicable across projects, or `local` when the knowledge should not be checked into version control.

408* Ask the subagent to consult its memory before starting work: "Review this PR, and check your memory for patterns you've seen before."

409* Ask the subagent to update its memory after completing a task: "Now that you're done, save what you learned to your memory." Over time, this builds a knowledge base that makes the subagent more effective.

410* Include memory instructions directly in the subagent's markdown file so it proactively maintains its own knowledge base:

411

412 ```markdown theme={null}

413 Update your agent memory as you discover codepaths, patterns, library

414 locations, and key architectural decisions. This builds up institutional

415 knowledge across conversations. Write concise notes about what you found

416 and where.

417 ```

418

281#### Conditional rules with hooks419#### Conditional rules with hooks

282 420

283For more dynamic control over tool usage, use `PreToolUse` hooks to validate operations before they execute. This is useful when you need to allow some operations of a tool while blocking others.421For more dynamic control over tool usage, use `PreToolUse` hooks to validate operations before they execute. This is useful when you need to allow some operations of a tool while blocking others.

320 458

321#### Disable specific subagents459#### Disable specific subagents

322 460

323You can prevent Claude from using specific subagents by adding them to the `deny` array in your [settings](/en/settings#permission-settings). Use the format `Task(subagent-name)` where `subagent-name` matches the subagent's name field.461You can prevent Claude from using specific subagents by adding them to the `deny` array in your [settings](/en/settings#permission-settings). Use the format `Agent(subagent-name)` where `subagent-name` matches the subagent's name field.

324 462

325```json theme={null}463```json theme={null}

326{464{

327 "permissions": {465 "permissions": {

328 "deny": ["Task(Explore)", "Task(my-custom-agent)"]466 "deny": ["Agent(Explore)", "Agent(my-custom-agent)"]

329 }467 }

330}468}

331```469```

333This works for both built-in and custom subagents. You can also use the `--disallowedTools` CLI flag:471This works for both built-in and custom subagents. You can also use the `--disallowedTools` CLI flag:

334 472

335```bash theme={null}473```bash theme={null}

336claude --disallowedTools "Task(Explore)"474claude --disallowedTools "Agent(Explore)"

337```475```

338 476

339See [IAM documentation](/en/iam#tool-specific-permission-rules) for more details on permission rules.477See [Permissions documentation](/en/permissions#tool-specific-permission-rules) for more details on permission rules.

340 478

341### Define hooks for subagents479### Define hooks for subagents

342 480

387| :-------------- | :-------------- | :------------------------------- |525| :-------------- | :-------------- | :------------------------------- |

390 528

391`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:529Both 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:

392 530

393```json theme={null}531```json theme={null}

394{532{

420 558

421Claude automatically delegates tasks based on the task description in your request, the `description` field in subagent configurations, and current context. To encourage proactive delegation, include phrases like "use proactively" in your subagent's description field.559Claude automatically delegates tasks based on the task description in your request, the `description` field in subagent configurations, and current context. To encourage proactive delegation, include phrases like "use proactively" in your subagent's description field.

422 560

423You can also request a specific subagent explicitly:561### Invoke subagents explicitly

424 562

425```563When automatic delegation isn't enough, you can request a subagent yourself. Three patterns escalate from a one-off suggestion to a session-wide default:

564

565* **Natural language**: name the subagent in your prompt; Claude decides whether to delegate

566* **@-mention**: guarantees the subagent runs for one task

567* **Session-wide**: the whole session uses that subagent's system prompt, tool restrictions, and model via the `--agent` flag or the `agent` setting

568

569For natural language, there's no special syntax. Name the subagent and Claude typically delegates:

570

571```text theme={null}

426Use the test-runner subagent to fix failing tests572Use the test-runner subagent to fix failing tests

427Have the code-reviewer subagent look at my recent changes573Have the code-reviewer subagent look at my recent changes

428```574```

429 575

576**@-mention the subagent.** Type `@` and pick the subagent from the typeahead, the same way you @-mention files. This ensures that specific subagent runs rather than leaving the choice to Claude:

577

578```text theme={null}

579@"code-reviewer (agent)" look at the auth changes

580```

581

582Your full message still goes to Claude, which writes the subagent's task prompt based on what you asked. The @-mention controls which subagent Claude invokes, not what prompt it receives.

583

584Subagents provided by an enabled [plugin](/en/plugins) appear in the typeahead as `<plugin-name>:<agent-name>`. You can also type the mention manually without using the picker: `@agent-<name>` for local subagents, or `@agent-<plugin-name>:<agent-name>` for plugin subagents.

585

586**Run the whole session as a subagent.** Pass [`--agent <name>`](/en/cli-reference) to start a session where the main thread itself takes on that subagent's system prompt, tool restrictions, and model:

587

588```bash theme={null}

589claude --agent code-reviewer

590```

591

592The subagent's system prompt replaces the default Claude Code system prompt entirely, the same way [`--system-prompt`](/en/cli-reference) does. `CLAUDE.md` files and project memory still load through the normal message flow. The agent name appears as `@<name>` in the startup header so you can confirm it's active.

593

594This works with built-in and custom subagents, and the choice persists when you resume the session.

595

596For a plugin-provided subagent, pass the scoped name: `claude --agent <plugin-name>:<agent-name>`.

597

598To make it the default for every session in a project, set `agent` in `.claude/settings.json`:

599

600```json theme={null}

601{

602 "agent": "code-reviewer"

603}

604```

605

606The CLI flag overrides the setting if both are present.

607

430### Run subagents in foreground or background608### Run subagents in foreground or background

431 609

432Subagents can run in the foreground (blocking) or background (concurrent):610Subagents can run in the foreground (blocking) or background (concurrent):

433 611

434* **Foreground subagents** block the main conversation until complete. Permission prompts and clarifying questions (like [`AskUserQuestion`](/en/settings#tools-available-to-claude)) are passed through to you.612* **Foreground subagents** block the main conversation until complete. Permission prompts and clarifying questions (like [`AskUserQuestion`](/en/tools-reference)) are passed through to you.

435* **Background subagents** run concurrently while you continue working. Before launching, Claude Code prompts for any tool permissions the subagent will need, ensuring it has the necessary approvals upfront. Once running, the subagent inherits these permissions and auto-denies anything not pre-approved. If a background subagent needs to ask clarifying questions, that tool call fails but the subagent continues. MCP tools are not available in background subagents.613* **Background subagents** run concurrently while you continue working. Before launching, Claude Code prompts for any tool permissions the subagent will need, ensuring it has the necessary approvals upfront. Once running, the subagent inherits these permissions and auto-denies anything not pre-approved. If a background subagent needs to ask clarifying questions, that tool call fails but the subagent continues.

436 614

437If a background subagent fails due to missing permissions, you can [resume it](#resume-subagents) in the foreground to retry with interactive prompts.615If a background subagent fails due to missing permissions, you can start a new foreground subagent with the same task to retry with interactive prompts.

438 616

439Claude decides whether to run subagents in the foreground or background based on the task. You can also:617Claude decides whether to run subagents in the foreground or background based on the task. You can also:

440 618

441* Ask Claude to "run this in the background"619* Ask Claude to "run this in the background"

442* Press **Ctrl+B** to background a running task620* Press **Ctrl+B** to background a running task

443 621

444To disable all background task functionality, set the `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` environment variable to `1`. See [Environment variables](/en/settings#environment-variables).622To disable all background task functionality, set the `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` environment variable to `1`. See [Environment variables](/en/env-vars).

445 623

446### Common patterns624### Common patterns

447 625

449 627

450One of the most effective uses for subagents is isolating operations that produce large amounts of output. Running tests, fetching documentation, or processing log files can consume significant context. By delegating these to a subagent, the verbose output stays in the subagent's context while only the relevant summary returns to your main conversation.628One of the most effective uses for subagents is isolating operations that produce large amounts of output. Running tests, fetching documentation, or processing log files can consume significant context. By delegating these to a subagent, the verbose output stays in the subagent's context while only the relevant summary returns to your main conversation.

451 629

452```630```text theme={null}

453Use a subagent to run the test suite and report only the failing tests with their error messages631Use a subagent to run the test suite and report only the failing tests with their error messages

454```632```

455 633

457 635

458For independent investigations, spawn multiple subagents to work simultaneously:636For independent investigations, spawn multiple subagents to work simultaneously:

459 637

460```638```text theme={null}

461Research the authentication, database, and API modules in parallel using separate subagents639Research the authentication, database, and API modules in parallel using separate subagents

462```640```

463 641

467 When subagents complete, their results return to your main conversation. Running many subagents that each return detailed results can consume significant context.645 When subagents complete, their results return to your main conversation. Running many subagents that each return detailed results can consume significant context.

468</Warning>646</Warning>

469 647

648For tasks that need sustained parallelism or exceed your context window, [agent teams](/en/agent-teams) give each worker its own independent context.

649

470#### Chain subagents650#### Chain subagents

471 651

472For multi-step workflows, ask Claude to use subagents in sequence. Each subagent completes its task and returns results to Claude, which then passes relevant context to the next subagent.652For multi-step workflows, ask Claude to use subagents in sequence. Each subagent completes its task and returns results to Claude, which then passes relevant context to the next subagent.

473 653

474```654```text theme={null}

475Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them655Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

476```656```

477 657

492 672

493Consider [Skills](/en/skills) instead when you want reusable prompts or workflows that run in the main conversation context rather than isolated subagent context.673Consider [Skills](/en/skills) instead when you want reusable prompts or workflows that run in the main conversation context rather than isolated subagent context.

494 674

675For a quick question about something already in your conversation, use [`/btw`](/en/interactive-mode#side-questions-with-btw) instead of a subagent. It sees your full context but has no tool access, and the answer is discarded rather than added to history.

676

495<Note>677<Note>

496 Subagents cannot spawn other subagents. If your workflow requires nested delegation, use [Skills](/en/skills) or [chain subagents](#chain-subagents) from the main conversation.678 Subagents cannot spawn other subagents. If your workflow requires nested delegation, use [Skills](/en/skills) or [chain subagents](#chain-subagents) from the main conversation.

497</Note>679</Note>

504 686

505Resumed subagents retain their full conversation history, including all previous tool calls, results, and reasoning. The subagent picks up exactly where it stopped rather than starting fresh.687Resumed subagents retain their full conversation history, including all previous tool calls, results, and reasoning. The subagent picks up exactly where it stopped rather than starting fresh.

506 688

507When a subagent completes, Claude receives its agent ID. To resume a subagent, ask Claude to continue the previous work:689When a subagent completes, Claude receives its agent ID. Claude uses the `SendMessage` tool with the agent's ID as the `to` field to resume it. To resume a subagent, ask Claude to continue the previous work:

508 690

509```691```text theme={null}

510Use the code-reviewer subagent to review the authentication module692Use the code-reviewer subagent to review the authentication module

511[Agent completes]693[Agent completes]

512 694

514[Claude resumes the subagent with full context from previous conversation]696[Claude resumes the subagent with full context from previous conversation]

515```697```

516 698

699If a stopped subagent receives a `SendMessage`, it auto-resumes in the background without requiring a new `Agent` invocation.

700

517You can also ask Claude for the agent ID if you want to reference it explicitly, or find IDs in the transcript files at `~/.claude/projects/{project}/{sessionId}/subagents/`. Each transcript is stored as `agent-{agentId}.jsonl`.701You can also ask Claude for the agent ID if you want to reference it explicitly, or find IDs in the transcript files at `~/.claude/projects/{project}/{sessionId}/subagents/`. Each transcript is stored as `agent-{agentId}.jsonl`.

518 702

519Subagent transcripts persist independently of the main conversation:703Subagent transcripts persist independently of the main conversation:

524 708

525#### Auto-compaction709#### Auto-compaction

526 710

527Subagents support automatic compaction using the same logic as the main conversation. By default, auto-compaction triggers at approximately 95% capacity. To trigger compaction earlier, set `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` to a lower percentage (for example, `50`). See [environment variables](/en/settings#environment-variables) for details.711Subagents support automatic compaction using the same logic as the main conversation. By default, auto-compaction triggers at approximately 95% capacity. To trigger compaction earlier, set `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` to a lower percentage (for example, `50`). See [environment variables](/en/env-vars) for details.

528 712

529Compaction events are logged in subagent transcript files:713Compaction events are logged in subagent transcript files:

530 714

terminal-config.md +25 −12

Details

351. Open Settings → Profiles → Keyboard351. Open Settings → Profiles → Keyboard

362. Check "Use Option as Meta Key"362. Check "Use Option as Meta Key"

37 37

~~38**For iTerm2 and VS Code terminal:**~~38**For iTerm2:**

39 39

401. Open Settings → Profiles → Keys401. Open Settings → Profiles → Keys

412. Under General, set Left/Right Option key to "Esc+"412. Under General, set Left/Right Option key to "Esc+"

42 42

43**For VS Code terminal:**

45Set `"terminal.integrated.macOptionIsMeta": true` in VS Code settings.

43### Notification setup47### Notification setup

44 48

~~45Never miss when Claude completes a task with proper notification configuration:~~49When Claude finishes working and is waiting for your input, it fires a notification event. You can surface this event as a desktop notification through your terminal or run custom logic with [notification hooks](/en/hooks#notification).

51#### Terminal notifications

53Kitty and Ghostty support desktop notifications without additional configuration. iTerm 2 requires setup:

551. Open iTerm 2 Settings → Profiles → Terminal

562. Enable "Notification Center Alerts"

573. Click "Filter Alerts" and check "Send escape sequence-generated alerts"

59If notifications aren't appearing, verify that your terminal app has notification permissions in your OS settings.

46 60

~~47#### iTerm 2 system notifications~~61When running Claude Code inside tmux, notifications and the [terminal progress bar](/en/settings#global-config-settings) only reach the outer terminal, such as iTerm2, Kitty, or Ghostty, if you enable passthrough in your tmux configuration:

48 62

~~49For iTerm 2 alerts when tasks complete:~~63```

64set -g allow-passthrough on

65```

50 66

~~511. Open iTerm 2 Preferences~~67Without this setting, tmux intercepts the escape sequences and they do not reach the terminal application.

~~522. Navigate to Profiles → Terminal~~

~~533. Enable "Silence bell" and Filter Alerts → "Send escape sequence-generated alerts"~~

~~544. Set your preferred notification delay~~

55 68

~~56Note that these notifications are specific to iTerm 2 and not available in the default macOS Terminal.~~69Other terminals, including the default macOS Terminal, do not support native notifications. Use [notification hooks](/en/hooks#notification) instead.

57 70

~~58#### Custom notification hooks~~71#### Notification hooks

59 72

~~60For advanced notification handling, you can create [notification hooks](/en/hooks#notification) to run your own logic.~~73To add custom behavior when notifications fire, such as playing a sound or sending a message, configure a [notification hook](/en/hooks#notification). Hooks run alongside terminal notifications, not as a replacement.

61 74

62### Handling large inputs75### Handling large inputs

63 76

69 82

70### Vim Mode83### Vim Mode

71 84

~~72Claude Code supports a subset of Vim keybindings that can be enabled with `/vim` or configured via `/config`.~~85Claude Code supports a subset of Vim keybindings that can be enabled with `/vim` or configured via `/config`. To set the mode directly in your config file, set the [`editorMode`](/en/settings#global-config-settings) global config key to `"vim"` in `~/.claude.json`.

73 86

74The supported subset includes:87The supported subset includes:

75 88

third-party-integrations.md +13 −9

Details

44 44

45 <tr>45 <tr>

46 <td>Billing</td>46 <td>Billing</td>

~~47 <td>Teams: \$150/seat (Premium) with PAYG available Enterprise: <a href="https://claude.com/contact-sales">Contact Sales</a></td>~~47 <td>Teams: \$150/seat (Premium) with PAYG available Enterprise: <a href="https://claude.com/contact-sales?utm_source=claude_code&utm_medium=docs&utm_content=third_party_enterprise">Contact Sales</a></td>

48 <td>PAYG</td>48 <td>PAYG</td>

49 <td>PAYG through AWS</td>49 <td>PAYG through AWS</td>

50 <td>PAYG through GCP</td>50 <td>PAYG through GCP</td>

109 109

110Select a deployment option to view setup instructions:110Select a deployment option to view setup instructions:

111 111

112* [Claude for Teams or Enterprise](/en/iam#claude-for-teams-or-enterprise-recommended)112* [Claude for Teams or Enterprise](/en/authentication#claude-for-teams-or-enterprise)

113* [Anthropic Console](/en/iam#claude-console-authentication)113* [Anthropic Console](/en/authentication#claude-console-authentication)

114* [Amazon Bedrock](/en/amazon-bedrock)114* [Amazon Bedrock](/en/amazon-bedrock)

115* [Google Vertex AI](/en/google-vertex-ai)115* [Google Vertex AI](/en/google-vertex-ai)

116* [Microsoft Foundry](/en/microsoft-foundry)116* [Microsoft Foundry](/en/microsoft-foundry)

128 128

129<Tabs>129<Tabs>

130 <Tab title="Corporate proxy">130 <Tab title="Corporate proxy">

131 Route Bedrock traffic through your corporate proxy by setting the following [environment variables](/en/settings#environment-variables):131 Route Bedrock traffic through your corporate proxy by setting the following [environment variables](/en/env-vars):

132 132

133 ```bash theme={null}133 ```bash theme={null}

134 # Enable Bedrock134 # Enable Bedrock

141 </Tab>141 </Tab>

142 142

143 <Tab title="LLM Gateway">143 <Tab title="LLM Gateway">

144 Route Bedrock traffic through your LLM gateway by setting the following [environment variables](/en/settings#environment-variables):144 Route Bedrock traffic through your LLM gateway by setting the following [environment variables](/en/env-vars):

145 145

146 ```bash theme={null}146 ```bash theme={null}

147 # Enable Bedrock147 # Enable Bedrock

158 158

159<Tabs>159<Tabs>

160 <Tab title="Corporate proxy">160 <Tab title="Corporate proxy">

161 Route Foundry traffic through your corporate proxy by setting the following [environment variables](/en/settings#environment-variables):161 Route Foundry traffic through your corporate proxy by setting the following [environment variables](/en/env-vars):

162 162

163 ```bash theme={null}163 ```bash theme={null}

164 # Enable Microsoft Foundry164 # Enable Microsoft Foundry

172 </Tab>172 </Tab>

173 173

174 <Tab title="LLM Gateway">174 <Tab title="LLM Gateway">

175 Route Foundry traffic through your LLM gateway by setting the following [environment variables](/en/settings#environment-variables):175 Route Foundry traffic through your LLM gateway by setting the following [environment variables](/en/env-vars):

176 176

177 ```bash theme={null}177 ```bash theme={null}

178 # Enable Microsoft Foundry178 # Enable Microsoft Foundry

189 189

190<Tabs>190<Tabs>

191 <Tab title="Corporate proxy">191 <Tab title="Corporate proxy">

192 Route Vertex AI traffic through your corporate proxy by setting the following [environment variables](/en/settings#environment-variables):192 Route Vertex AI traffic through your corporate proxy by setting the following [environment variables](/en/env-vars):

193 193

194 ```bash theme={null}194 ```bash theme={null}

195 # Enable Vertex195 # Enable Vertex

203 </Tab>203 </Tab>

204 204

205 <Tab title="LLM Gateway">205 <Tab title="LLM Gateway">

206 Route Vertex AI traffic through your LLM gateway by setting the following [environment variables](/en/settings#environment-variables):206 Route Vertex AI traffic through your LLM gateway by setting the following [environment variables](/en/env-vars):

207 207

208 ```bash theme={null}208 ```bash theme={null}

209 # Enable Vertex209 # Enable Vertex

239 239

240Encourage new users to try Claude Code for codebase Q\&A, or on smaller bug fixes or feature requests. Ask Claude Code to make a plan. Check Claude's suggestions and give feedback if it's off-track. Over time, as users understand this new paradigm better, then they'll be more effective at letting Claude Code run more agentically.240Encourage new users to try Claude Code for codebase Q\&A, or on smaller bug fixes or feature requests. Ask Claude Code to make a plan. Check Claude's suggestions and give feedback if it's off-track. Over time, as users understand this new paradigm better, then they'll be more effective at letting Claude Code run more agentically.

241 241

242### Pin model versions for cloud providers

243

244If you deploy through [Bedrock](/en/amazon-bedrock), [Vertex AI](/en/google-vertex-ai), or [Foundry](/en/microsoft-foundry), pin specific model versions using `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL`. Without pinning, Claude Code aliases resolve to the latest version, which can break users when Anthropic releases a new model that isn't yet enabled in your account. See [Model configuration](/en/model-config#pin-models-for-third-party-deployments) for details.

245

242### Configure security policies246### Configure security policies

243 247

244Security teams can configure managed permissions for what Claude Code is and is not allowed to do, which cannot be overwritten by local configuration. [Learn more](/en/security).248Security teams can configure managed permissions for what Claude Code is and is not allowed to do, which cannot be overwritten by local configuration. [Learn more](/en/security).

tools-reference.md +96 −0 added

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# Tools reference

7> Complete reference for the tools Claude Code can use, including permission requirements.

9Claude Code has access to a set of tools that help it understand and modify your codebase. The tool names below are the exact strings you use in [permission rules](/en/permissions#tool-specific-permission-rules), [subagent tool lists](/en/sub-agents), and [hook matchers](/en/hooks).

11| Tool | Description | Permission Required |

12| :--------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------ |

13| `Agent` | Spawns a [subagent](/en/sub-agents) with its own context window to handle a task | No |

14| `AskUserQuestion` | Asks multiple-choice questions to gather requirements or clarify ambiguity | No |

15| `Bash` | Executes shell commands in your environment. See [Bash tool behavior](#bash-tool-behavior) | Yes |

16| `CronCreate` | Schedules a recurring or one-shot prompt within the current session (gone when Claude exits). See [scheduled tasks](/en/scheduled-tasks) | No |

17| `CronDelete` | Cancels a scheduled task by ID | No |

18| `CronList` | Lists all scheduled tasks in the session | No |

19| `Edit` | Makes targeted edits to specific files | Yes |

20| `EnterPlanMode` | Switches to plan mode to design an approach before coding | No |

21| `EnterWorktree` | Creates an isolated [git worktree](/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees) and switches into it | No |

22| `ExitPlanMode` | Presents a plan for approval and exits plan mode | Yes |

23| `ExitWorktree` | Exits a worktree session and returns to the original directory | No |

24| `Glob` | Finds files based on pattern matching | No |

25| `Grep` | Searches for patterns in file contents | No |

26| `ListMcpResourcesTool` | Lists resources exposed by connected [MCP servers](/en/mcp) | No |

27| `LSP` | Code intelligence via language servers. Reports type errors and warnings automatically after file edits. Also supports navigation operations: jump to definitions, find references, get type info, list symbols, find implementations, trace call hierarchies. Requires a [code intelligence plugin](/en/discover-plugins#code-intelligence) and its language server binary | No |

28| `NotebookEdit` | Modifies Jupyter notebook cells | Yes |

29| `PowerShell` | Executes PowerShell commands on Windows. Opt-in preview. See [PowerShell tool](#powershell-tool) | Yes |

30| `Read` | Reads the contents of files | No |

31| `ReadMcpResourceTool` | Reads a specific MCP resource by URI | No |

32| `Skill` | Executes a [skill](/en/skills#control-who-invokes-a-skill) within the main conversation | Yes |

33| `TaskCreate` | Creates a new task in the task list | No |

34| `TaskGet` | Retrieves full details for a specific task | No |

35| `TaskList` | Lists all tasks with their current status | No |

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

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

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

39| `TodoWrite` | Manages the session task checklist. Available in non-interactive mode and the [Agent SDK](/en/headless); interactive sessions use TaskCreate, TaskGet, TaskList, and TaskUpdate instead | No |

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

41| `WebFetch` | Fetches content from a specified URL | Yes |

42| `WebSearch` | Performs web searches | Yes |

43| `Write` | Creates or overwrites files | Yes |

45Permission rules can be configured using `/permissions` or in [permission settings](/en/settings#available-settings). Also see [Tool-specific permission rules](/en/permissions#tool-specific-permission-rules).

47## Bash tool behavior

49The Bash tool runs each command in a separate process with the following persistence behavior:

51* Working directory persists across commands. Set `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1` to reset to the project directory after each command.

52* Environment variables do not persist. An `export` in one command will not be available in the next.

54Activate your virtualenv or conda environment before launching Claude Code. To make environment variables persist across Bash commands, set [`CLAUDE_ENV_FILE`](/en/env-vars) to a shell script before launching Claude Code, or use a [SessionStart hook](/en/hooks#persist-environment-variables) to populate it dynamically.

56## PowerShell tool

58On Windows, Claude Code can run PowerShell commands natively instead of routing through Git Bash. This is an opt-in preview.

60### Enable the PowerShell tool

62Set `CLAUDE_CODE_USE_POWERSHELL_TOOL=1` in your environment or in `settings.json`:

64```json theme={null}

65{

66 "env": {

67 "CLAUDE_CODE_USE_POWERSHELL_TOOL": "1"

68 }

69}

70```

72Claude Code auto-detects `pwsh.exe` (PowerShell 7+) with a fallback to `powershell.exe` (PowerShell 5.1). The Bash tool remains registered alongside the PowerShell tool, so you may need to ask Claude to use PowerShell.

74### Shell selection in settings, hooks, and skills

76Three additional settings control where PowerShell is used:

78* `"defaultShell": "powershell"` in [`settings.json`](/en/settings#available-settings): routes interactive `!` commands through PowerShell. Requires the PowerShell tool to be enabled.

79* `"shell": "powershell"` on individual [command hooks](/en/hooks#command-hook-fields): runs that hook in PowerShell. Hooks spawn PowerShell directly, so this works regardless of `CLAUDE_CODE_USE_POWERSHELL_TOOL`.

80* `shell: powershell` in [skill frontmatter](/en/skills#frontmatter-reference): runs `` !`command` `` blocks in PowerShell. Requires the PowerShell tool to be enabled.

82### Preview limitations

84The PowerShell tool has the following known limitations during the preview:

86* Auto mode does not work with the PowerShell tool yet

87* PowerShell profiles are not loaded

88* Sandboxing is not supported

89* Only supported on native Windows, not WSL

90* Git Bash is still required to start Claude Code

92## See also

94* [Permissions](/en/permissions): permission system, rule syntax, and tool-specific patterns

95* [Subagents](/en/sub-agents): configure tool access for subagents

96* [Hooks](/en/hooks-guide): run custom commands before or after tool execution

troubleshooting.md +594 −112

Details

6 6

7> Discover solutions to common issues with Claude Code installation and usage.7> Discover solutions to common issues with Claude Code installation and usage.

8 8

9## Troubleshoot installation issues

11<Tip>

12 If you'd rather skip the terminal entirely, the [Claude Code Desktop app](/en/desktop-quickstart) lets you install and use Claude Code through a graphical interface. Download it for [macOS](https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code\&utm_medium=docs) or [Windows](https://claude.ai/api/desktop/win32/x64/exe/latest/redirect?utm_source=claude_code\&utm_medium=docs) and start coding without any command-line setup.

13</Tip>

15Find the error message or symptom you're seeing:

17| What you see | Solution |

18| :---------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------- |

19| `command not found: claude` or `'claude' is not recognized` | [Fix your PATH](#command-not-found-claude-after-installation) |

20| `syntax error near unexpected token '<'` | [Install script returns HTML](#install-script-returns-html-instead-of-a-shell-script) |

21| `curl: (56) Failure writing output to destination` | [Download script first, then run it](#curl-56-failure-writing-output-to-destination) |

22| `Killed` during install on Linux | [Add swap space for low-memory servers](#install-killed-on-low-memory-linux-servers) |

23| `TLS connect error` or `SSL/TLS secure channel` | [Update CA certificates](#tls-or-ssl-connection-errors) |

24| `Failed to fetch version` or can't reach download server | [Check network and proxy settings](#check-network-connectivity) |

25| `irm is not recognized` or `&& is not valid` | [Use the right command for your shell](#windows-irm-or--not-recognized) |

26| `Claude Code on Windows requires git-bash` | [Install or configure Git Bash](#windows-claude-code-on-windows-requires-git-bash) |

27| `Error loading shared library` | [Wrong binary variant for your system](#linux-wrong-binary-variant-installed-muslglibc-mismatch) |

28| `Illegal instruction` on Linux | [Architecture mismatch](#illegal-instruction-on-linux) |

29| `dyld: cannot load` or `Abort trap` on macOS | [Binary incompatibility](#dyld-cannot-load-on-macos) |

30| `Invoke-Expression: Missing argument in parameter list` | [Install script returns HTML](#install-script-returns-html-instead-of-a-shell-script) |

31| `App unavailable in region` | Claude Code is not available in your country. See [supported countries](https://www.anthropic.com/supported-countries). |

32| `unable to get local issuer certificate` | [Configure corporate CA certificates](#tls-or-ssl-connection-errors) |

33| `OAuth error` or `403 Forbidden` | [Fix authentication](#authentication-issues) |

35If your issue isn't listed, work through these diagnostic steps.

37## Debug installation problems

39### Check network connectivity

41The installer downloads from `storage.googleapis.com`. Verify you can reach it:

43```bash theme={null}

44curl -sI https://storage.googleapis.com

45```

47If this fails, your network may be blocking the connection. Common causes:

49* Corporate firewalls or proxies blocking Google Cloud Storage

50* Regional network restrictions: try a VPN or alternative network

51* TLS/SSL issues: update your system's CA certificates, or check if `HTTPS_PROXY` is configured

53If you're behind a corporate proxy, set `HTTPS_PROXY` and `HTTP_PROXY` to your proxy's address before installing. Ask your IT team for the proxy URL if you don't know it, or check your browser's proxy settings.

55This example sets both proxy variables, then runs the installer through your proxy:

57```bash theme={null}

58export HTTP_PROXY=http://proxy.example.com:8080

59export HTTPS_PROXY=http://proxy.example.com:8080

60curl -fsSL https://claude.ai/install.sh | bash

61```

63### Verify your PATH

65If installation succeeded but you get a `command not found` or `not recognized` error when running `claude`, the install directory isn't in your PATH. Your shell searches for programs in directories listed in PATH, and the installer places `claude` at `~/.local/bin/claude` on macOS/Linux or `%USERPROFILE%\.local\bin\claude.exe` on Windows.

67Check if the install directory is in your PATH by listing your PATH entries and filtering for `local/bin`:

69<Tabs>

70 <Tab title="macOS/Linux">

71 ```bash theme={null}

72 echo $PATH | tr ':' '\n' | grep local/bin

73 ```

75 If there's no output, the directory is missing. Add it to your shell configuration:

77 ```bash theme={null}

78 # Zsh (macOS default)

79 echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

80 source ~/.zshrc

82 # Bash (Linux default)

83 echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

84 source ~/.bashrc

85 ```

87 Alternatively, close and reopen your terminal.

89 Verify the fix worked:

91 ```bash theme={null}

92 claude --version

93 ```

94 </Tab>

96 <Tab title="Windows PowerShell">

97 ```powershell theme={null}

98 $env:PATH -split ';' | Select-String 'local\\bin'

99 ```

100

101 If there's no output, add the install directory to your User PATH:

102

103 ```powershell theme={null}

104 $currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')

105 [Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

106 ```

107

108 Restart your terminal for the change to take effect.

109

110 Verify the fix worked:

111

112 ```powershell theme={null}

113 claude --version

114 ```

115 </Tab>

116

117 <Tab title="Windows CMD">

118 ```batch theme={null}

119 echo %PATH% | findstr /i "local\bin"

120 ```

121

122 If there's no output, open System Settings, go to Environment Variables, and add `%USERPROFILE%\.local\bin` to your User PATH variable. Restart your terminal.

123

124 Verify the fix worked:

125

126 ```batch theme={null}

127 claude --version

128 ```

129 </Tab>

130</Tabs>

131

132### Check for conflicting installations

133

134Multiple Claude Code installations can cause version mismatches or unexpected behavior. Check what's installed:

135

136<Tabs>

137 <Tab title="macOS/Linux">

138 List all `claude` binaries found in your PATH:

139

140 ```bash theme={null}

141 which -a claude

142 ```

143

144 Check whether the native installer and npm versions are present:

145

146 ```bash theme={null}

147 ls -la ~/.local/bin/claude

148 ```

149

150 ```bash theme={null}

151 ls -la ~/.claude/local/

152 ```

153

154 ```bash theme={null}

155 npm -g ls @anthropic-ai/claude-code 2>/dev/null

156 ```

157 </Tab>

158

159 <Tab title="Windows PowerShell">

160 ```powershell theme={null}

161 where.exe claude

162 Test-Path "$env:LOCALAPPDATA\Claude Code\claude.exe"

163 ```

164 </Tab>

165</Tabs>

166

167If you find multiple installations, keep only one. The native install at `~/.local/bin/claude` is recommended. Remove any extra installations:

168

169Uninstall an npm global install:

170

171```bash theme={null}

172npm uninstall -g @anthropic-ai/claude-code

173```

174

175Remove a Homebrew install on macOS:

176

177```bash theme={null}

178brew uninstall --cask claude-code

179```

180

181### Check directory permissions

182

183The installer needs write access to `~/.local/bin/` and `~/.claude/`. If installation fails with permission errors, check whether these directories are writable:

184

185```bash theme={null}

186test -w ~/.local/bin && echo "writable" || echo "not writable"

187test -w ~/.claude && echo "writable" || echo "not writable"

188```

189

190If either directory isn't writable, create the install directory and set your user as the owner:

191

192```bash theme={null}

193sudo mkdir -p ~/.local/bin

194sudo chown -R $(whoami) ~/.local

195```

196

197### Verify the binary works

198

199If `claude` is installed but crashes or hangs on startup, run these checks to narrow down the cause.

200

201Confirm the binary exists and is executable:

202

203```bash theme={null}

204ls -la $(which claude)

205```

206

207On Linux, check for missing shared libraries. If `ldd` shows missing libraries, you may need to install system packages. On Alpine Linux and other musl-based distributions, see [Alpine Linux setup](/en/setup#alpine-linux-and-musl-based-distributions).

208

209```bash theme={null}

210ldd $(which claude) | grep "not found"

211```

212

213Run a quick sanity check that the binary can execute:

214

215```bash theme={null}

216claude --version

217```

218

9## Common installation issues219## Common installation issues

10 220

221These are the most frequently encountered installation problems and their solutions.

222

223### Install script returns HTML instead of a shell script

224

225When running the install command, you may see one of these errors:

226

227```text theme={null}

228bash: line 1: syntax error near unexpected token `<'

229bash: line 1: `<!DOCTYPE html>'

230```

231

232On PowerShell, the same problem appears as:

233

234```text theme={null}

235Invoke-Expression: Missing argument in parameter list.

236```

237

238This means the install URL returned an HTML page instead of the install script. If the HTML page says "App unavailable in region," Claude Code is not available in your country. See [supported countries](https://www.anthropic.com/supported-countries).

239

240Otherwise, this can happen due to network issues, regional routing, or a temporary service disruption.

241

242**Solutions:**

243

2441. **Use an alternative install method**:

245

246 On macOS or Linux, install via Homebrew:

247

248 ```bash theme={null}

249 brew install --cask claude-code

250 ```

251

252 On Windows, install via WinGet:

253

254 ```powershell theme={null}

255 winget install Anthropic.ClaudeCode

256 ```

257

2582. **Retry after a few minutes**: the issue is often temporary. Wait and try the original command again.

259

260### `command not found: claude` after installation

261

262The install finished but `claude` doesn't work. The exact error varies by platform:

263

264| Platform | Error message |

265| :---------- | :--------------------------------------------------------------------- |

266| macOS | `zsh: command not found: claude` |

267| Linux | `bash: claude: command not found` |

268| Windows CMD | `'claude' is not recognized as an internal or external command` |

269| PowerShell | `claude : The term 'claude' is not recognized as the name of a cmdlet` |

270

271This means the install directory isn't in your shell's search path. See [Verify your PATH](#verify-your-path) for the fix on each platform.

272

273### `curl: (56) Failure writing output to destination`

274

275The `curl ... | bash` command downloads the script and passes it directly to Bash for execution using a pipe (`|`). This error means the connection broke before the script finished downloading. Common causes include network interruptions, the download being blocked mid-stream, or system resource limits.

276

277**Solutions:**

278

2791. **Check network stability**: Claude Code binaries are hosted on Google Cloud Storage. Test that you can reach it:

280 ```bash theme={null}

281 curl -fsSL https://storage.googleapis.com -o /dev/null

282 ```

283 If the command completes silently, your connection is fine and the issue is likely intermittent. Retry the install command. If you see an error, your network may be blocking the download.

284

2852. **Try an alternative install method**:

286

287 On macOS or Linux:

288

289 ```bash theme={null}

290 brew install --cask claude-code

291 ```

292

293 On Windows:

294

295 ```powershell theme={null}

296 winget install Anthropic.ClaudeCode

297 ```

298

299### TLS or SSL connection errors

300

301Errors like `curl: (35) TLS connect error`, `schannel: next InitializeSecurityContext failed`, or PowerShell's `Could not establish trust relationship for the SSL/TLS secure channel` indicate TLS handshake failures.

302

303**Solutions:**

304

3051. **Update your system CA certificates**:

306

307 On Ubuntu/Debian:

308

309 ```bash theme={null}

310 sudo apt-get update && sudo apt-get install ca-certificates

311 ```

312

313 On macOS via Homebrew:

314

315 ```bash theme={null}

316 brew install ca-certificates

317 ```

318

3192. **On Windows, enable TLS 1.2** in PowerShell before running the installer:

320 ```powershell theme={null}

321 [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

322 irm https://claude.ai/install.ps1 | iex

323 ```

324

3253. **Check for proxy or firewall interference**: corporate proxies that perform TLS inspection can cause these errors, including `unable to get local issuer certificate`. Set `NODE_EXTRA_CA_CERTS` to your corporate CA certificate bundle:

326 ```bash theme={null}

327 export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem

328 ```

329 Ask your IT team for the certificate file if you don't have it. You can also try on a direct connection to confirm the proxy is the cause.

330

331### `Failed to fetch version from storage.googleapis.com`

332

333The installer couldn't reach the download server. This typically means `storage.googleapis.com` is blocked on your network.

334

335**Solutions:**

336

3371. **Test connectivity directly**:

338 ```bash theme={null}

339 curl -sI https://storage.googleapis.com

340 ```

341

3422. **If behind a proxy**, set `HTTPS_PROXY` so the installer can route through it. See [proxy configuration](/en/network-config#proxy-configuration) for details.

343 ```bash theme={null}

344 export HTTPS_PROXY=http://proxy.example.com:8080

345 curl -fsSL https://claude.ai/install.sh | bash

346 ```

347

3483. **If on a restricted network**, try a different network or VPN, or use an alternative install method:

349

350 On macOS or Linux:

351

352 ```bash theme={null}

353 brew install --cask claude-code

354 ```

355

356 On Windows:

357

358 ```powershell theme={null}

359 winget install Anthropic.ClaudeCode

360 ```

361

362### Windows: `irm` or `&&` not recognized

363

364If you see `'irm' is not recognized` or `The token '&&' is not valid`, you're running the wrong command for your shell.

365

366* **`irm` not recognized**: you're in CMD, not PowerShell. You have two options:

367

368 Open PowerShell by searching for "PowerShell" in the Start menu, then run the original install command:

369

370 ```powershell theme={null}

371 irm https://claude.ai/install.ps1 | iex

372 ```

373

374 Or stay in CMD and use the CMD installer instead:

375

376 ```batch theme={null}

377 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

378 ```

379

380* **`&&` not valid**: you're in PowerShell but ran the CMD installer command. Use the PowerShell installer:

381 ```powershell theme={null}

382 irm https://claude.ai/install.ps1 | iex

383 ```

384

385### Install killed on low-memory Linux servers

386

387If you see `Killed` during installation on a VPS or cloud instance:

388

389```text theme={null}

390Setting up Claude Code...

391Installing Claude Code native build latest...

392bash: line 142: 34803 Killed "$binary_path" install ${TARGET:+"$TARGET"}

393```

394

395The Linux OOM killer terminated the process because the system ran out of memory. Claude Code requires at least 4 GB of available RAM.

396

397**Solutions:**

398

3991. **Add swap space** if your server has limited RAM. Swap uses disk space as overflow memory, letting the install complete even with low physical RAM.

400

401 Create a 2 GB swap file and enable it:

402

403 ```bash theme={null}

404 sudo fallocate -l 2G /swapfile

405 sudo chmod 600 /swapfile

406 sudo mkswap /swapfile

407 sudo swapon /swapfile

408 ```

409

410 Then retry the installation:

411

412 ```bash theme={null}

413 curl -fsSL https://claude.ai/install.sh | bash

414 ```

415

4162. **Close other processes** to free memory before installing.

417

4183. **Use a larger instance** if possible. Claude Code requires at least 4 GB of RAM.

419

420### Install hangs in Docker

421

422When installing Claude Code in a Docker container, installing as root into `/` can cause hangs.

423

424**Solutions:**

425

4261. **Set a working directory** before running the installer. When run from `/`, the installer scans the entire filesystem, which causes excessive memory usage. Setting `WORKDIR` limits the scan to a small directory:

427 ```dockerfile theme={null}

428 WORKDIR /tmp

429 RUN curl -fsSL https://claude.ai/install.sh | bash

430 ```

431

4322. **Increase Docker memory limits** if using Docker Desktop:

433 ```bash theme={null}

434 docker build --memory=4g .

435 ```

436

437### Windows: Claude Desktop overrides `claude` CLI command

438

439If you installed an older version of Claude Desktop, it may register a `Claude.exe` in the `WindowsApps` directory that takes PATH priority over Claude Code CLI. Running `claude` opens the Desktop app instead of the CLI.

440

441Update Claude Desktop to the latest version to fix this issue.

442

443### Windows: "Claude Code on Windows requires git-bash"

444

445Claude Code on native Windows needs [Git for Windows](https://git-scm.com/downloads/win), which includes Git Bash.

446

447**If Git is not installed**, download and install it from [git-scm.com/downloads/win](https://git-scm.com/downloads/win). During setup, select "Add to PATH." Restart your terminal after installing.

448

449**If Git is already installed** but Claude Code still can't find it, set the path in your [settings.json file](/en/settings):

450

451```json theme={null}

452{

453 "env": {

454 "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"

455 }

456}

457```

458

459If your Git is installed somewhere else, find the path by running `where.exe git` in PowerShell and use the `bin\bash.exe` path from that directory.

460

461### Linux: wrong binary variant installed (musl/glibc mismatch)

462

463If you see errors about missing shared libraries like `libstdc++.so.6` or `libgcc_s.so.1` after installation, the installer may have downloaded the wrong binary variant for your system.

464

465```text theme={null}

466Error loading shared library libstdc++.so.6: No such file or directory

467```

468

469This can happen on glibc-based systems that have musl cross-compilation packages installed, causing the installer to misdetect the system as musl.

470

471**Solutions:**

472

4731. **Check which libc your system uses**:

474 ```bash theme={null}

475 ldd /bin/ls | head -1

476 ```

477 If it shows `linux-vdso.so` or references to `/lib/x86_64-linux-gnu/`, you're on glibc. If it shows `musl`, you're on musl.

478

4792. **If you're on glibc but got the musl binary**, remove the installation and reinstall. You can also manually download the correct binary from the GCS bucket at `https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases/{VERSION}/manifest.json`. File a [GitHub issue](https://github.com/anthropics/claude-code/issues) with the output of `ldd /bin/ls` and `ls /lib/libc.musl*`.

480

4813. **If you're actually on musl** (Alpine Linux), install the required packages:

482 ```bash theme={null}

483 apk add libgcc libstdc++ ripgrep

484 ```

485

486### `Illegal instruction` on Linux

487

488If the installer prints `Illegal instruction` instead of the OOM `Killed` message, the downloaded binary doesn't match your CPU architecture. This commonly happens on ARM servers that receive an x86 binary, or on older CPUs that lack required instruction sets.

489

490```text theme={null}

491bash: line 142: 2238232 Illegal instruction "$binary_path" install ${TARGET:+"$TARGET"}

492```

493

494**Solutions:**

495

4961. **Verify your architecture**:

497 ```bash theme={null}

498 uname -m

499 ```

500 `x86_64` means 64-bit Intel/AMD, `aarch64` means ARM64. If the binary doesn't match, [file a GitHub issue](https://github.com/anthropics/claude-code/issues) with the output.

501

5022. **Try an alternative install method** while the architecture issue is resolved:

503 ```bash theme={null}

504 brew install --cask claude-code

505 ```

506

507### `dyld: cannot load` on macOS

508

509If you see `dyld: cannot load` or `Abort trap: 6` during installation, the binary is incompatible with your macOS version or hardware.

510

511```text theme={null}

512dyld: cannot load 'claude-2.1.42-darwin-x64' (load command 0x80000034 is unknown)

513Abort trap: 6

514```

515

516**Solutions:**

517

5181. **Check your macOS version**: Claude Code requires macOS 13.0 or later. Open the Apple menu and select About This Mac to check your version.

519

5202. **Update macOS** if you're on an older version. The binary uses load commands that older macOS versions don't support.

521

5223. **Try Homebrew** as an alternative install method:

523 ```bash theme={null}

524 brew install --cask claude-code

525 ```

526

11### Windows installation issues: errors in WSL527### Windows installation issues: errors in WSL

12 528

13You might encounter the following issues in WSL:529You might encounter the following issues in WSL:

14 530

~~15**OS/platform detection issues**: If you receive an error during installation, WSL may be using Windows `npm`. Try:~~531**OS/platform detection issues**: if you receive an error during installation, WSL may be using Windows `npm`. Try:

16 532

17* Run `npm config set os linux` before installation533* Run `npm config set os linux` before installation

~~18* Install with `npm install -g @anthropic-ai/claude-code --force --no-os-check` (Do NOT use `sudo`)~~534* Install with `npm install -g @anthropic-ai/claude-code --force --no-os-check`. Do not use `sudo`.

19 535

20**Node not found errors**: If you see `exec: node: not found` when running `claude`, your WSL environment may be using a Windows installation of Node.js. You can confirm this with `which npm` and `which node`, which should point to Linux paths starting with `/usr/` rather than `/mnt/c/`. To fix this, try installing Node via your Linux distribution's package manager or via [`nvm`](https://github.com/nvm-sh/nvm).536**Node not found errors**: if you see `exec: node: not found` when running `claude`, your WSL environment may be using a Windows installation of Node.js. You can confirm this with `which npm` and `which node`, which should point to Linux paths starting with `/usr/` rather than `/mnt/c/`. To fix this, try installing Node via your Linux distribution's package manager or via [`nvm`](https://github.com/nvm-sh/nvm).

21 537

22**nvm version conflicts**: If you have nvm installed in both WSL and Windows, you may experience version conflicts when switching Node versions in WSL. This happens because WSL imports the Windows PATH by default, causing Windows nvm/npm to take priority over the WSL installation.538**nvm version conflicts**: if you have nvm installed in both WSL and Windows, you may experience version conflicts when switching Node versions in WSL. This happens because WSL imports the Windows PATH by default, causing Windows nvm/npm to take priority over the WSL installation.

23 539

24You can identify this issue by:540You can identify this issue by:

25 541

54```570```

55 571

56<Warning>572<Warning>

57 Avoid disabling Windows PATH importing (`appendWindowsPath = false`) as this breaks the ability to call Windows executables from WSL. Similarly, avoid uninstalling Node.js from Windows if you use it for Windows development.573 Avoid disabling Windows PATH importing via `appendWindowsPath = false` as this breaks the ability to call Windows executables from WSL. Similarly, avoid uninstalling Node.js from Windows if you use it for Windows development.

58</Warning>574</Warning>

59 575

60### WSL2 sandbox setup576### WSL2 sandbox setup

77 593

78WSL1 does not support sandboxing. If you see "Sandboxing requires WSL2", you need to upgrade to WSL2 or run Claude Code without sandboxing.594WSL1 does not support sandboxing. If you see "Sandboxing requires WSL2", you need to upgrade to WSL2 or run Claude Code without sandboxing.

79 595

~~80### Linux and Mac installation issues: permission or command not found errors~~596### Permission errors during installation

~~82When installing Claude Code with npm, `PATH` problems may prevent access to `claude`.~~

~~83You may also encounter permission errors if your npm global prefix is not user writable (for example, `/usr`, or `/usr/local`).~~

84 597

~~85#### Recommended solution: Native Claude Code installation~~598If the native installer fails with permission errors, the target directory may not be writable. See [Check directory permissions](#check-directory-permissions).

86 599

~~87Claude Code has a native installation that doesn't depend on npm or Node.js.~~600If you previously installed with npm and are hitting npm-specific permission errors, switch to the native installer:

~~89Use the following command to run the native installer.~~

~~91**macOS, Linux, WSL:**~~

92 601

93```bash theme={null}602```bash theme={null}

~~94# Install stable version (default)~~

95curl -fsSL https://claude.ai/install.sh | bash603curl -fsSL https://claude.ai/install.sh | bash

~~97# Install latest version~~

~~98curl -fsSL https://claude.ai/install.sh | bash -s latest~~

100# Install specific version number

101curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

102```604```

103 605

104**Windows PowerShell:**606## Permissions and authentication

105 607

106```powershell theme={null}608These sections address login failures, token issues, and permission prompt behavior.

107# Install stable version (default)

108irm https://claude.ai/install.ps1 | iex

109 609

110# Install latest version610### Repeated permission prompts

111& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) latest

112 611

113# Install specific version number612If you find yourself repeatedly approving the same commands, you can allow specific tools

114& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58613to run without approval using the `/permissions` command. See [Permissions docs](/en/permissions#manage-permissions).

115 614

116```615### Authentication issues

117 616

118This command installs the appropriate build of Claude Code for your operating system and architecture and adds a symlink to the installation at `~/.local/bin/claude` (or `%USERPROFILE%\.local\bin\claude.exe` on Windows).617If you're experiencing authentication problems:

119 618

120<Tip>6191. Run `/logout` to sign out completely

121 Make sure that you have the installation directory in your system PATH.6202. Close Claude Code

122</Tip>6213. Restart with `claude` and complete the authentication process again

123 622

124### Windows: "Claude Code on Windows requires git-bash"623If the browser doesn't open automatically during login, press `c` to copy the OAuth URL to your clipboard, then paste it into your browser manually.

125 624

126Claude Code on native Windows requires [Git for Windows](https://git-scm.com/downloads/win) which includes Git Bash. If Git is installed but not detected:625### OAuth error: Invalid code

127 626

1281. Set the path explicitly in PowerShell before running Claude:627If you see `OAuth error: Invalid code. Please make sure the full code was copied`, the login code expired or was truncated during copy-paste.

129 ```powershell theme={null}

130 $env:CLAUDE_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"

131 ```

132 628

1332. Or add it to your system environment variables permanently through System Properties → Environment Variables.629**Solutions:**

134 630

135If Git is installed in a non-standard location, adjust the path accordingly.631* Press Enter to retry and complete the login quickly after the browser opens

632* Type `c` to copy the full URL if the browser doesn't open automatically

633* If using a remote/SSH session, the browser may open on the wrong machine. Copy the URL displayed in the terminal and open it in your local browser instead.

136 634

137### Windows: "installMethod is native, but claude command not found"635### 403 Forbidden after login

138 636

139If you see this error after installation, the `claude` command isn't in your PATH. Add it manually:637If you see `API Error: 403 {"error":{"type":"forbidden","message":"Request not allowed"}}` after logging in:

140 638

141<Steps>639* **Claude Pro/Max users**: verify your subscription is active at [claude.ai/settings](https://claude.ai/settings)

142 <Step title="Open Environment Variables">640* **Console users**: confirm your account has the "Claude Code" or "Developer" role assigned by your admin

143 Press `Win + R`, type `sysdm.cpl`, and press Enter. Click **Advanced** → **Environment Variables**.641* **Behind a proxy**: corporate proxies can interfere with API requests. See [network configuration](/en/network-config) for proxy setup.

144 </Step>

145 642

146 <Step title="Edit User PATH">643### "This organization has been disabled" with an active subscription

147 Under "User variables", select **Path** and click **Edit**. Click **New** and add:

148 644

149 ```645If you see `API Error: 400 ... "This organization has been disabled"` despite having an active Claude subscription, an `ANTHROPIC_API_KEY` environment variable is overriding your subscription. This commonly happens when an old API key from a previous employer or project is still set in your shell profile.

150 %USERPROFILE%\.local\bin

151 ```

152 </Step>

153 646

154 <Step title="Restart your terminal">647When `ANTHROPIC_API_KEY` is present and you have approved it, Claude Code uses that key instead of your subscription's OAuth credentials. In non-interactive mode (`-p`), the key is always used when present. See [authentication precedence](/en/authentication#authentication-precedence) for the full resolution order.

155 Close and reopen PowerShell or CMD for changes to take effect.

156 </Step>

157</Steps>

158 648

159Verify installation:649To use your subscription instead, unset the environment variable and remove it from your shell profile:

160 650

161```bash theme={null}651```bash theme={null}

162claude doctor # Check installation health652unset ANTHROPIC_API_KEY

653claude

163```654```

164 655

165## Permissions and authentication656Check `~/.zshrc`, `~/.bashrc`, or `~/.profile` for `export ANTHROPIC_API_KEY=...` lines and remove them to make the change permanent. Run `/status` inside Claude Code to confirm which authentication method is active.

166 657

167### Repeated permission prompts658### OAuth login fails in WSL2

168 659

169If you find yourself repeatedly approving the same commands, you can allow specific tools660Browser-based login in WSL2 may fail if WSL can't open your Windows browser. Set the `BROWSER` environment variable:

170to run without approval using the `/permissions` command. See [Permissions docs](/en/iam#configuring-permissions).

~~171~~

172### Authentication issues

~~173~~

174If you're experiencing authentication problems:

~~175~~

1761. Run `/logout` to sign out completely

1772. Close Claude Code

1783. Restart with `claude` and complete the authentication process again

~~179~~

180If the browser doesn't open automatically during login, press `c` to copy the OAuth URL to your clipboard, then paste it into your browser manually.

~~181~~

182If problems persist, try:

183 661

184```bash theme={null}662```bash theme={null}

185rm -rf ~/.config/claude-code/auth.json663export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"

186claude664claude

187```665```

188 666

189This removes your stored authentication information and forces a clean login.667Or copy the URL manually: when the login prompt appears, press `c` to copy the OAuth URL, then paste it into your Windows browser.

668

669### "Not logged in" or token expired

670

671If Claude Code prompts you to log in again after a session, your OAuth token may have expired.

672

673Run `/login` to re-authenticate. If this happens frequently, check that your system clock is accurate, as token validation depends on correct timestamps.

190 674

191## Configuration file locations675## Configuration file locations

192 676

193Claude Code stores configuration in several locations:677Claude Code stores configuration in several locations:

194 678

195| File | Purpose |679| File | Purpose |

196| :---------------------------- | :------------------------------------------------------- |680| :---------------------------- | :----------------------------------------------------------------------------------------------------- |

202| `managed-settings.json` | [Managed settings](/en/settings#settings-files) |

687| Managed settings | [Managed settings](/en/settings#settings-files) (server-managed, MDM/OS-level policies, or file-based) |

204 688

205On Windows, `~` refers to your user home directory, such as `C:\Users\YourName`.689On Windows, `~` refers to your user home directory, such as `C:\Users\YourName`.

206 690

207**Managed file locations:**

~~208~~

209* macOS: `/Library/Application Support/ClaudeCode/`

210* Linux/WSL: `/etc/claude-code/`

211* Windows: `C:\Program Files\ClaudeCode\`

~~212~~

213For details on configuring these files, see [Settings](/en/settings) and [MCP](/en/mcp).691For details on configuring these files, see [Settings](/en/settings) and [MCP](/en/mcp).

214 692

215### Resetting configuration693### Resetting configuration

232 710

233## Performance and stability711## Performance and stability

234 712

713These sections cover issues related to resource usage, responsiveness, and search behavior.

714

235### High CPU or memory usage715### High CPU or memory usage

236 716

237Claude Code is designed to work with most development environments, but may consume significant resources when processing large codebases. If you're experiencing performance issues:717Claude Code is designed to work with most development environments, but may consume significant resources when processing large codebases. If you're experiencing performance issues:

268pacman -S ripgrep748pacman -S ripgrep

269```749```

270 750

271Then set `USE_BUILTIN_RIPGREP=0` in your [environment](/en/settings#environment-variables).751Then set `USE_BUILTIN_RIPGREP=0` in your [environment](/en/env-vars).

272 752

273### Slow or incomplete search results on WSL753### Slow or incomplete search results on WSL

274 754

275Disk read performance penalties when [working across file systems on WSL](https://learn.microsoft.com/en-us/windows/wsl/filesystems) may result in fewer-than-expected matches (but not a complete lack of search functionality) when using Claude Code on WSL.755Disk read performance penalties when [working across file systems on WSL](https://learn.microsoft.com/en-us/windows/wsl/filesystems) may result in fewer-than-expected matches when using Claude Code on WSL. Search still functions, but returns fewer results than on a native filesystem.

276 756

277<Note>757<Note>

278 `/doctor` will show Search as OK in this case.758 `/doctor` will show Search as OK in this case.

280 760

281**Solutions:**761**Solutions:**

282 762

2831. **Submit more specific searches**: Reduce the number of files searched by specifying directories or file types: "Search for JWT validation logic in the auth-service package" or "Find use of md5 hash in JS files".7631. **Submit more specific searches**: reduce the number of files searched by specifying directories or file types: "Search for JWT validation logic in the auth-service package" or "Find use of md5 hash in JS files".

284 764

2852. **Move project to Linux filesystem**: If possible, ensure your project is located on the Linux filesystem (`/home/`) rather than the Windows filesystem (`/mnt/c/`).7652. **Move project to Linux filesystem**: if possible, ensure your project is located on the Linux filesystem (`/home/`) rather than the Windows filesystem (`/mnt/c/`).

286 766

2873. **Use native Windows instead**: Consider running Claude Code natively on Windows instead of through WSL, for better file system performance.7673. **Use native Windows instead**: consider running Claude Code natively on Windows instead of through WSL, for better file system performance.

288 768

289## IDE integration issues769## IDE integration issues

290 770

771If Claude Code does not connect to your IDE or behaves unexpectedly within an IDE terminal, try the solutions below.

772

291### JetBrains IDE not detected on WSL2773### JetBrains IDE not detected on WSL2

292 774

293If you're using Claude Code on WSL2 with JetBrains IDEs and getting "No available IDEs detected" errors, this is likely due to WSL2's networking configuration or Windows Firewall blocking the connection.775If you're using Claude Code on WSL2 with JetBrains IDEs and getting "No available IDEs detected" errors, this is likely due to WSL2's networking configuration or Windows Firewall blocking the connection.

3011. Find your WSL2 IP address:7831. Find your WSL2 IP address:

302 ```bash theme={null}784 ```bash theme={null}

303 wsl hostname -I785 wsl hostname -I

304 # Example output: 172.21.123.456786 # Example output: 172.21.123.45

305 ```787 ```

306 788

3072. Open PowerShell as Administrator and create a firewall rule:7892. Open PowerShell as Administrator and create a firewall rule:

308 ```powershell theme={null}790 ```powershell theme={null}

309 New-NetFirewallRule -DisplayName "Allow WSL2 Internal Traffic" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16791 New-NetFirewallRule -DisplayName "Allow WSL2 Internal Traffic" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16

310 ```792 ```

311 (Adjust the IP range based on your WSL2 subnet from step 1)793 Adjust the IP range based on your WSL2 subnet from step 1.

312 794

3133. Restart both your IDE and Claude Code7953. Restart both your IDE and Claude Code

314 796

327 These networking issues only affect WSL2. WSL1 uses the host's network directly and doesn't require these configurations.809 These networking issues only affect WSL2. WSL1 uses the host's network directly and doesn't require these configurations.

328</Note>810</Note>

329 811

330For additional JetBrains configuration tips, see our [JetBrains IDE guide](/en/jetbrains#plugin-settings).812For additional JetBrains configuration tips, see the [JetBrains IDE guide](/en/jetbrains#plugin-settings).

331 813

332### Reporting Windows IDE integration issues (both native and WSL)814### Report Windows IDE integration issues

333 815

334If you're experiencing IDE integration problems on Windows, [create an issue](https://github.com/anthropics/claude-code/issues) with the following information:816If you're experiencing IDE integration problems on Windows, [create an issue](https://github.com/anthropics/claude-code/issues) with the following information:

335 817

336* Environment type: native Windows (Git Bash) or WSL1/WSL2818* Environment type: native Windows (Git Bash) or WSL1/WSL2

337* WSL networking mode (if applicable): NAT or mirrored819* WSL networking mode, if applicable: NAT or mirrored

338* IDE name and version820* IDE name and version

339* Claude Code extension/plugin version821* Claude Code extension/plugin version

340* Shell type: Bash, Zsh, PowerShell, etc.822* Shell type: Bash, Zsh, PowerShell, etc.

341 823

342### Escape key not working in JetBrains (IntelliJ, PyCharm, etc.) terminals824### Escape key not working in JetBrains IDE terminals

343 825

344If you're using Claude Code in JetBrains terminals and the `Esc` key doesn't interrupt the agent as expected, this is likely due to a keybinding clash with JetBrains' default shortcuts.826If you're using Claude Code in JetBrains terminals and the `Esc` key doesn't interrupt the agent as expected, this is likely due to a keybinding clash with JetBrains' default shortcuts.

345 827

366function example() {848function example() {

367 return "hello";849 return "hello";

368}850}

369```851```text

370````852````

371 853

372Instead of properly tagged blocks like:854Instead of properly tagged blocks like:

376function example() {858function example() {

377 return "hello";859 return "hello";

378}860}

379```861```text

380````862````

381 863

382**Solutions:**864**Solutions:**

383 865

3841. **Ask Claude to add language tags**: Request "Add appropriate language tags to all code blocks in this markdown file."8661. **Ask Claude to add language tags**: request "Add appropriate language tags to all code blocks in this markdown file."

385 867

3862. **Use post-processing hooks**: Set up automatic formatting hooks to detect and add missing language tags. See [Auto-format code after edits](/en/hooks-guide#auto-format-code-after-edits) for an example of a PostToolUse formatting hook.8682. **Use post-processing hooks**: set up automatic formatting hooks to detect and add missing language tags. See [Auto-format code after edits](/en/hooks-guide#auto-format-code-after-edits) for an example of a PostToolUse formatting hook.

387 869

3883. **Manual verification**: After generating markdown files, review them for proper code block formatting and request corrections if needed.8703. **Manual verification**: after generating markdown files, review them for proper code block formatting and request corrections if needed.

389 871

390### Inconsistent spacing and formatting872### Inconsistent spacing and formatting

391 873

393 875

394**Solutions:**876**Solutions:**

395 877

3961. **Request formatting corrections**: Ask Claude to "Fix spacing and formatting issues in this markdown file."8781. **Request formatting corrections**: ask Claude to "Fix spacing and formatting issues in this markdown file."

397 879

3982. **Use formatting tools**: Set up hooks to run markdown formatters like `prettier` or custom formatting scripts on generated markdown files.8802. **Use formatting tools**: set up hooks to run markdown formatters like `prettier` or custom formatting scripts on generated markdown files.

399 881

4003. **Specify formatting preferences**: Include formatting requirements in your prompts or project [memory](/en/memory) files.8823. **Specify formatting preferences**: include formatting requirements in your prompts or project [memory](/en/memory) files.

401 883

402### Best practices for markdown generation884### Reduce markdown formatting issues

403 885

404To minimize formatting issues:886To minimize formatting issues:

405 887

406* **Be explicit in requests**: Ask for "properly formatted markdown with language-tagged code blocks"888* **Be explicit in requests**: ask for "properly formatted markdown with language-tagged code blocks"

407* **Use project conventions**: Document your preferred markdown style in [`CLAUDE.md`](/en/memory)889* **Use project conventions**: document your preferred markdown style in [`CLAUDE.md`](/en/memory)

408* **Set up validation hooks**: Use post-processing hooks to automatically verify and fix common formatting issues890* **Set up validation hooks**: use post-processing hooks to automatically verify and fix common formatting issues

409 891

410## Getting more help892## Get more help

411 893

412If you're experiencing issues not covered here:894If you're experiencing issues not covered here:

413 895

4141. Use the `/bug` command within Claude Code to report problems directly to Anthropic8961. Use the `/feedback` command within Claude Code to report problems directly to Anthropic

4152. Check the [GitHub repository](https://github.com/anthropics/claude-code) for known issues8972. Check the [GitHub repository](https://github.com/anthropics/claude-code) for known issues

4163. Run `/doctor` to diagnose issues. It checks:8983. Run `/doctor` to diagnose issues. It checks:

417 * Installation type, version, and search functionality899 * Installation type, version, and search functionality

voice-dictation.md +138 −0 added

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# Voice dictation

7> Use push-to-talk voice dictation to speak your prompts instead of typing them in the Claude Code CLI.

9Hold a key and speak to dictate your prompts. Your speech is transcribed live into the prompt input, so you can mix voice and typing in the same message. Enable dictation with `/voice`. The default push-to-talk key is `Space`; [rebind to a modifier combination](#rebind-the-push-to-talk-key) to activate on the first keypress rather than after a brief hold.

11<Note>

12 Voice dictation requires Claude Code v2.1.69 or later. Check your version with `claude --version`.

13</Note>

15## Requirements

17Voice dictation uses a streaming speech-to-text service that is only available when you authenticate with a Claude.ai account. It is not available when Claude Code is configured to use an Anthropic API key directly, Amazon Bedrock, Google Vertex AI, or Microsoft Foundry.

19Voice dictation also needs local microphone access, so it does not work in remote environments such as [Claude Code on the web](/en/claude-code-on-the-web) or SSH sessions. In WSL, voice dictation requires WSLg for audio access, which is included with WSL2 on Windows 11. On Windows 10 or WSL1, run Claude Code in native Windows instead.

21Audio recording uses a built-in native module on macOS, Linux, and Windows. On Linux, if the native module cannot load, Claude Code falls back to `arecord` from ALSA utils or `rec` from SoX. If neither is available, `/voice` prints an install command for your package manager.

23## Enable voice dictation

25Run `/voice` to toggle voice dictation on. The first time you enable it, Claude Code runs a microphone check. On macOS, this triggers the system microphone permission prompt for your terminal if it has never been granted.

27```

28/voice

29Voice mode enabled. Hold Space to record. Dictation language: en (/config to change).

30```

32Voice dictation persists across sessions. Run `/voice` again to turn it off, or set it directly in your [user settings file](/en/settings):

34```json theme={null}

35{

36 "voiceEnabled": true

37}

38```

40While voice dictation is enabled, the input footer shows a `hold Space to speak` hint when the prompt is empty. The hint does not appear if you have a [custom status line](/en/statusline) configured.

42## Record a prompt

44Hold `Space` to start recording. Claude Code detects a held key by watching for rapid key-repeat events from your terminal, so there is a brief warmup before recording begins. The footer shows `keep holding…` during warmup, then switches to a live waveform once recording is active.

46The first couple of key-repeat characters type into the input during warmup and are removed automatically when recording activates. A single `Space` tap still types a space, since hold detection only triggers on rapid repeat.

48<Tip>

49 To skip the warmup, [rebind to a modifier combination](#rebind-the-push-to-talk-key) like `meta+k`. Modifier combos start recording on the first keypress.

50</Tip>

52Your speech appears in the prompt as you speak, dimmed until the transcript is finalized. Release `Space` to stop recording and finalize the text. The transcript is inserted at your cursor position and the cursor stays at the end of the inserted text, so you can mix typing and dictation in any order. Hold `Space` again to append another recording, or move the cursor first to insert speech elsewhere in the prompt:

54```

55> refactor the auth middleware to ▮

56 # hold Space, speak "use the new token validation helper"

57> refactor the auth middleware to use the new token validation helper▮

58```

60Transcription is tuned for coding vocabulary. Common development terms like `regex`, `OAuth`, `JSON`, and `localhost` are recognized correctly, and your current project name and git branch name are added as recognition hints automatically.

62## Change the dictation language

64Voice dictation uses the same [`language` setting](/en/settings) that controls Claude's response language. If that setting is empty, dictation defaults to English.

66<Accordion title="Supported dictation languages">

67 | Language | Code |

68 | :--------- | :--- |

69 | Czech | `cs` |

70 | Danish | `da` |

71 | Dutch | `nl` |

72 | English | `en` |

73 | French | `fr` |

74 | German | `de` |

75 | Greek | `el` |

76 | Hindi | `hi` |

77 | Indonesian | `id` |

78 | Italian | `it` |

79 | Japanese | `ja` |

80 | Korean | `ko` |

81 | Norwegian | `no` |

82 | Polish | `pl` |

83 | Portuguese | `pt` |

84 | Russian | `ru` |

85 | Spanish | `es` |

86 | Swedish | `sv` |

87 | Turkish | `tr` |

88 | Ukrainian | `uk` |

89</Accordion>

91Set the language in `/config` or directly in settings. You can use either the [BCP 47 language code](https://en.wikipedia.org/wiki/IETF_language_tag) or the language name:

93```json theme={null}

94{

95 "language": "japanese"

96}

97```

99If your `language` setting is not in the supported list, `/voice` warns you on enable and falls back to English for dictation. Claude's text responses are not affected by this fallback.

100

101## Rebind the push-to-talk key

102

103The push-to-talk key is bound to `voice:pushToTalk` in the `Chat` context and defaults to `Space`. Rebind it in [`~/.claude/keybindings.json`](/en/keybindings):

104

105```json theme={null}

106{

107 "bindings": [

108 {

109 "context": "Chat",

110 "bindings": {

111 "meta+k": "voice:pushToTalk",

112 "space": null

113 }

114 }

115 ]

116}

117```

118

119Setting `"space": null` removes the default binding. Omit it if you want both keys active.

120

121Because hold detection relies on key-repeat, avoid binding a bare letter key like `v` since it types into the prompt during warmup. Use `Space`, or use a modifier combination like `meta+k` to start recording on the first keypress with no warmup. See [customize keyboard shortcuts](/en/keybindings) for the full keybinding syntax.

122

123## Troubleshooting

124

125Common issues when voice dictation does not activate or record:

126

127* **`Voice mode requires a Claude.ai account`**: you are authenticated with an API key or a third-party provider. Run `/login` to sign in with a Claude.ai account.

128* **`Microphone access is denied`**: grant microphone permission to your terminal in system settings. On macOS, go to System Settings → Privacy & Security → Microphone. On Windows, go to Settings → Privacy → Microphone. Then run `/voice` again.

129* **`No audio recording tool found` on Linux**: the native audio module could not load and no fallback is installed. Install SoX with the command shown in the error message, for example `sudo apt-get install sox`.

130* **Nothing happens when holding `Space`**: watch the prompt input while you hold. If spaces keep accumulating, voice dictation is off; run `/voice` to enable it. If only one or two spaces appear and then nothing, voice dictation is on but hold detection is not triggering. Hold detection requires your terminal to send key-repeat events, so it cannot detect a held key if key-repeat is disabled at the OS level.

131* **Transcription is garbled or in the wrong language**: dictation defaults to English. If you are dictating in another language, set it in `/config` first. See [Change the dictation language](#change-the-dictation-language).

132

133## See also

134

135* [Customize keyboard shortcuts](/en/keybindings): rebind `voice:pushToTalk` and other CLI keyboard actions

136* [Configure settings](/en/settings): full reference for `voiceEnabled`, `language`, and other settings keys

137* [Interactive mode](/en/interactive-mode): keyboard shortcuts, input modes, and session controls

138* [Built-in commands](/en/commands): reference for `/voice`, `/config`, and all other commands

vs-code.md +104 −41

Details

6 6

7> Install and configure the Claude Code extension for VS Code. Get AI coding assistance with inline diffs, @-mentions, plan review, and keyboard shortcuts.7> Install and configure the Claude Code extension for VS Code. Get AI coding assistance with inline diffs, @-mentions, plan review, and keyboard shortcuts.

8 8

9<img src="https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=300652d5678c63905e6b0ea9e50835f8" alt="VS Code editor with the Claude Code extension panel open on the right side, showing a conversation with Claude" data-og-width="2500" width="2500" data-og-height="1155" height="1155" data-path="images/vs-code-extension-interface.jpg" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=280&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=87630c671517a3d52e9aee627041696e 280w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=560&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=716b093879204beec8d952649ef75292 560w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=840&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=c1525d1a01513acd9d83d8b5a8fe2fc8 840w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=1100&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=1d90021d58bbb51f871efec13af955c3 1100w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=1650&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=7babdd25440099886f193cfa99af88ae 1650w, https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?w=2500&fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=08c92eedfb56fe61a61e480fb63784b6 2500w" />9<img src="https://mintcdn.com/claude-code/-YhHHmtSxwr7W8gy/images/vs-code-extension-interface.jpg?fit=max&auto=format&n=-YhHHmtSxwr7W8gy&q=85&s=300652d5678c63905e6b0ea9e50835f8" alt="VS Code editor with the Claude Code extension panel open on the right side, showing a conversation with Claude" width="2500" height="1155" data-path="images/vs-code-extension-interface.jpg" />

10 10

11The VS Code extension provides a native graphical interface for Claude Code, integrated directly into your IDE. This is the recommended way to use Claude Code in VS Code.11The VS Code extension provides a native graphical interface for Claude Code, integrated directly into your IDE. This is the recommended way to use Claude Code in VS Code.

12 12

14 14

15## Prerequisites15## Prerequisites

16 16

17Before installing, make sure you have:

17* VS Code 1.98.0 or higher19* VS Code 1.98.0 or higher

18* An Anthropic account (you'll sign in when you first open the extension). If you're using a third-party provider like Amazon Bedrock or Google Vertex AI, see [Use third-party providers](#use-third-party-providers) instead.20* An Anthropic account (you'll sign in when you first open the extension). If you're using a third-party provider like Amazon Bedrock or Google Vertex AI, see [Use third-party providers](#use-third-party-providers) instead.

19 21

38 40

39<Steps>41<Steps>

40 <Step title="Open the Claude Code panel">42 <Step title="Open the Claude Code panel">

41 Throughout VS Code, the Spark icon indicates Claude Code: <img src="https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-spark-icon.svg?fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=a734d84e785140016672f08e0abb236c" alt="Spark icon" style={{display: "inline", height: "0.85em", verticalAlign: "middle"}} data-og-width="16" width="16" data-og-height="16" height="16" data-path="images/vs-code-spark-icon.svg" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-spark-icon.svg?w=280&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=9a45aad9a84b9fa1701ac99a1f9aa4e9 280w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-spark-icon.svg?w=560&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=3f4cb9254c4d4e93989c4b6bf9292f4b 560w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-spark-icon.svg?w=840&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=e75ccc9faa3e572db8f291ceb65bb264 840w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-spark-icon.svg?w=1100&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=f147bd81a381a62539a4ce361fac41c7 1100w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-spark-icon.svg?w=1650&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=78fe68efaee5d6e844bbacab1b442ed5 1650w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-spark-icon.svg?w=2500&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=efb8dbe1dfa722d094edc6ad2ad4bedb 2500w" />43 Throughout VS Code, the Spark icon indicates Claude Code: <img src="https://mintcdn.com/claude-code/c5r9_6tjPMzFdDDT/images/vs-code-spark-icon.svg?fit=max&auto=format&n=c5r9_6tjPMzFdDDT&q=85&s=3ca45e00deadec8c8f4b4f807da94505" alt="Spark icon" style={{display: "inline", height: "0.85em", verticalAlign: "middle"}} width="16" height="16" data-path="images/vs-code-spark-icon.svg" />

42 44

43 The quickest way to open Claude is to click the Spark icon in the **Editor Toolbar** (top-right corner of the editor). The icon only appears when you have a file open.45 The quickest way to open Claude is to click the Spark icon in the **Editor Toolbar** (top-right corner of the editor). The icon only appears when you have a file open.

44 46

45 <img src="https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-editor-icon.png?fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=eb4540325d94664c51776dbbfec4cf02" alt="VS Code editor showing the Spark icon in the Editor Toolbar" data-og-width="2796" width="2796" data-og-height="734" height="734" data-path="images/vs-code-editor-icon.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-editor-icon.png?w=280&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=56f218d5464359d6480cfe23f70a923e 280w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-editor-icon.png?w=560&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=344a8db024b196c795a80dc85cacb8d1 560w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-editor-icon.png?w=840&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=f30bf834ee0625b2a4a635d552d87163 840w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-editor-icon.png?w=1100&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=81fdf984840e43a9f08ae42729d1484d 1100w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-editor-icon.png?w=1650&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=8b60fb32de54717093d512afaa99785c 1650w, https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-editor-icon.png?w=2500&fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=893e6bda8f2e9d42c8a294d394f0b736 2500w" />47 <img src="https://mintcdn.com/claude-code/mfM-EyoZGnQv8JTc/images/vs-code-editor-icon.png?fit=max&auto=format&n=mfM-EyoZGnQv8JTc&q=85&s=eb4540325d94664c51776dbbfec4cf02" alt="VS Code editor showing the Spark icon in the Editor Toolbar" width="2796" height="734" data-path="images/vs-code-editor-icon.png" />

46 48

47 Other ways to open Claude Code:49 Other ways to open Claude Code:

48 50

51 * **Activity Bar**: click the Spark icon in the left sidebar to open the sessions list. Click any session to open it as a full editor tab, or start a new one. This icon is always visible in the Activity Bar.

49 * **Command Palette**: `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux), type "Claude Code", and select an option like "Open in New Tab"52 * **Command Palette**: `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux), type "Claude Code", and select an option like "Open in New Tab"

~~50 * **Status Bar**: Click **✱ Claude Code** in the bottom-right corner of the window. This works even when no file is open.~~53 * **Status Bar**: click **✱ Claude Code** in the bottom-right corner of the window. This works even when no file is open.

51 54

52 When you first open the panel, a **Learn Claude Code** checklist appears. Work through each item by clicking **Show me**, or dismiss it with the X. To reopen it later, uncheck **Hide Onboarding** in VS Code settings under Extensions → Claude Code.55 When you first open the panel, a **Learn Claude Code** checklist appears. Work through each item by clicking **Show me**, or dismiss it with the X. To reopen it later, uncheck **Hide Onboarding** in VS Code settings under Extensions → Claude Code.

53 56

61 64

62 Here's an example of asking about a particular line in a file:65 Here's an example of asking about a particular line in a file:

63 66

64 <img src="https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-send-prompt.png?fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=ede3ed8d8d5f940e01c5de636d009cfd" alt="VS Code editor with lines 2-3 selected in a Python file, and the Claude Code panel showing a question about those lines with an @-mention reference" data-og-width="3288" width="3288" data-og-height="1876" height="1876" data-path="images/vs-code-send-prompt.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-send-prompt.png?w=280&fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=f40bde7b2c245fe8f0f5b784e8106492 280w, https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-send-prompt.png?w=560&fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=fad66a27a9a6faa23b05370aa4f398b2 560w, https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-send-prompt.png?w=840&fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=4539c8a3823ca80a5c8771f6c088ce9e 840w, https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-send-prompt.png?w=1100&fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=fae8ebf300c7853409a562ffa46d9c71 1100w, https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-send-prompt.png?w=1650&fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=22e4462bb8cf0c0ca20f8102bc4c971a 1650w, https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-send-prompt.png?w=2500&fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=739bfd045f70fe7be1a109a53494590e 2500w" />67 <img src="https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-send-prompt.png?fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=ede3ed8d8d5f940e01c5de636d009cfd" alt="VS Code editor with lines 2-3 selected in a Python file, and the Claude Code panel showing a question about those lines with an @-mention reference" width="3288" height="1876" data-path="images/vs-code-send-prompt.png" />

65 </Step>68 </Step>

66 69

67 <Step title="Review changes">70 <Step title="Review changes">

68 When Claude wants to edit a file, it shows a side-by-side comparison of the original and proposed changes, then asks for permission. You can accept, reject, or tell Claude what to do instead.71 When Claude wants to edit a file, it shows a side-by-side comparison of the original and proposed changes, then asks for permission. You can accept, reject, or tell Claude what to do instead.

69 72

70 <img src="https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-edits.png?fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=e005f9b41c541c5c7c59c082f7c4841c" alt="VS Code showing a diff of Claude's proposed changes with a permission prompt asking whether to make the edit" data-og-width="3292" width="3292" data-og-height="1876" height="1876" data-path="images/vs-code-edits.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-edits.png?w=280&fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=cb5d41b81087f79b842a56b5a3304660 280w, https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-edits.png?w=560&fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=90bb691960decdc06393c3c21cd62c75 560w, https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-edits.png?w=840&fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=9a11bf878ba619e850380904ff4f38e8 840w, https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-edits.png?w=1100&fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=6dddbf596b4f69ec6245bdc5eb6dd487 1100w, https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-edits.png?w=1650&fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=ef2713b8cbfd2cee97af817d813d64c7 1650w, https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-edits.png?w=2500&fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=1f7e1c52919cdfddf295f32a2ec7ae59 2500w" />73 <img src="https://mintcdn.com/claude-code/FVYz38sRY-VuoGHA/images/vs-code-edits.png?fit=max&auto=format&n=FVYz38sRY-VuoGHA&q=85&s=e005f9b41c541c5c7c59c082f7c4841c" alt="VS Code showing a diff of Claude's proposed changes with a permission prompt asking whether to make the edit" width="3292" height="1876" data-path="images/vs-code-edits.png" />

71 </Step>74 </Step>

72</Steps>75</Steps>

73 76

81 84

82The prompt box supports several features:85The prompt box supports several features:

83 86

84* **Permission modes**: Click the mode indicator at the bottom of the prompt box to switch modes. In normal mode, Claude asks permission before each action. In Plan mode, Claude describes what it will do and waits for approval before making changes. In auto-accept mode, Claude makes edits without asking. Set the default in VS Code settings under `claudeCode.initialPermissionMode`.87* **Permission modes**: click the mode indicator at the bottom of the prompt box to switch modes. In normal mode, Claude asks permission before each action. In Plan mode, Claude describes what it will do and waits for approval before making changes. VS Code automatically opens the plan as a full markdown document where you can add inline comments to give feedback before Claude begins. In auto-accept mode, Claude makes edits without asking. Set the default in VS Code settings under `claudeCode.initialPermissionMode`.

85* **Command menu**: Click `/` or type `/` to open the command menu. Options include attaching files, switching models, toggling extended thinking, and viewing plan usage (`/usage`). The Customize section provides access to MCP servers, hooks, memory, permissions, and plugins. Items with a terminal icon open in the integrated terminal.88* **Command menu**: click `/` or type `/` to open the command menu. Options include attaching files, switching models, toggling extended thinking, viewing plan usage (`/usage`), and starting a [Remote Control](/en/remote-control) session (`/remote-control`). The Customize section provides access to MCP servers, hooks, memory, permissions, and plugins. Items with a terminal icon open in the integrated terminal.

~~86* **Context indicator**: The prompt box shows how much of Claude's context window you're using. Claude automatically compacts when needed, or you can run `/compact` manually.~~89* **Context indicator**: the prompt box shows how much of Claude's context window you're using. Claude automatically compacts when needed, or you can run `/compact` manually.

87* **Extended thinking**: Lets Claude spend more time reasoning through complex problems. Toggle it on via the command menu (`/`). See [Extended thinking](/en/common-workflows#use-extended-thinking-thinking-mode) for details.90* **Extended thinking**: lets Claude spend more time reasoning through complex problems. Toggle it on via the command menu (`/`). See [Extended thinking](/en/common-workflows#use-extended-thinking-thinking-mode) for details.

~~88* **Multi-line input**: Press `Shift+Enter` to add a new line without sending.~~91* **Multi-line input**: press `Shift+Enter` to add a new line without sending. This also works in the "Other" free-text input of question dialogs.

89 92

90### Reference files and folders93### Reference files and folders

91 94

92Use @-mentions to give Claude context about specific files or folders. When you type `@` followed by a file or folder name, Claude reads that content and can answer questions about it or make changes to it. Claude Code supports fuzzy matching, so you can type partial names to find what you need:95Use @-mentions to give Claude context about specific files or folders. When you type `@` followed by a file or folder name, Claude reads that content and can answer questions about it or make changes to it. Claude Code supports fuzzy matching, so you can type partial names to find what you need:

93 96

~~94```~~97```text theme={null}

95> Explain the logic in @auth (fuzzy matches auth.js, AuthService.ts, etc.)98> Explain the logic in @auth (fuzzy matches auth.js, AuthService.ts, etc.)

96> What's in @src/components/ (include a trailing slash for folders)99> What's in @src/components/ (include a trailing slash for folders)

97```100```

98 101

102For large PDFs, you can ask Claude to read specific pages instead of the whole file: a single page, a range like pages 1-10, or an open-ended range like page 3 onward.

103

99When you select text in the editor, Claude can see your highlighted code automatically. The prompt box footer shows how many lines are selected. Press `Option+K` (Mac) / `Alt+K` (Windows/Linux) to insert an @-mention with the file path and line numbers (e.g., `@app.ts#5-10`). Click the selection indicator to toggle whether Claude can see your highlighted text - the eye-slash icon means the selection is hidden from Claude.104When you select text in the editor, Claude can see your highlighted code automatically. The prompt box footer shows how many lines are selected. Press `Option+K` (Mac) / `Alt+K` (Windows/Linux) to insert an @-mention with the file path and line numbers (e.g., `@app.ts#5-10`). Click the selection indicator to toggle whether Claude can see your highlighted text - the eye-slash icon means the selection is hidden from Claude.

100 105

101You can also hold `Shift` while dragging files into the prompt box to add them as attachments. Click the X on any attachment to remove it from context.106You can also hold `Shift` while dragging files into the prompt box to add them as attachments. Click the X on any attachment to remove it from context.

102 107

103### Resume past conversations108### Resume past conversations

104 109

105Click the dropdown at the top of the Claude Code panel to access your conversation history. You can search by keyword or browse by time (Today, Yesterday, Last 7 days, etc.). Click any conversation to resume it with the full message history. For more on resuming sessions, see [Common workflows](/en/common-workflows#resume-previous-conversations).110Click the dropdown at the top of the Claude Code panel to access your conversation history. You can search by keyword or browse by time (Today, Yesterday, Last 7 days, etc.). Click any conversation to resume it with the full message history. New sessions receive AI-generated titles based on your first message. Hover over a session to reveal rename and remove actions: rename to give it a descriptive title, or remove to delete it from the list. For more on resuming sessions, see [Common workflows](/en/common-workflows#resume-previous-conversations).

106 111

107### Resume remote sessions from Claude.ai112### Resume remote sessions from Claude.ai

108 113

134 139

135You can drag the Claude panel to reposition it anywhere in VS Code. Grab the panel's tab or title bar and drag it to:140You can drag the Claude panel to reposition it anywhere in VS Code. Grab the panel's tab or title bar and drag it to:

136 141

137* **Secondary sidebar**: The right side of the window. Keeps Claude visible while you code.142* **Secondary sidebar**: the right side of the window. Keeps Claude visible while you code.

138* **Primary sidebar**: The left sidebar with icons for Explorer, Search, etc.143* **Primary sidebar**: the left sidebar with icons for Explorer, Search, etc.

139* **Editor area**: Opens Claude as a tab alongside your files. Useful for side tasks.144* **Editor area**: opens Claude as a tab alongside your files. Useful for side tasks.

140 145

141<Tip>146<Tip>

142 Use the sidebar for your main Claude session and open additional tabs for side tasks. Claude remembers your preferred location. Note that the Spark icon only appears in the Activity Bar when the Claude panel is docked to the left. Since Claude defaults to the right side, use the Editor Toolbar icon to open Claude.147 Use the sidebar for your main Claude session and open additional tabs for side tasks. Claude remembers your preferred location. The Activity Bar sessions list icon is separate from the Claude panel: the sessions list is always visible in the Activity Bar, while the Claude panel icon only appears there when the panel is docked to the left sidebar.

143</Tip>148</Tip>

144 149

145### Run multiple conversations150### Run multiple conversations

171 176

172When you install a plugin, choose the installation scope:177When you install a plugin, choose the installation scope:

173 178

174* **Install for you**: Available in all your projects (user scope)179* **Install for you**: available in all your projects (user scope)

175* **Install for this project**: Shared with project collaborators (project scope)180* **Install for this project**: shared with project collaborators (project scope)

176* **Install locally**: Only for you, only in this repository (local scope)181* **Install locally**: only for you, only in this repository (local scope)

177 182

178### Manage marketplaces183### Manage marketplaces

179 184

191 196

192For more about the plugin system, see [Plugins](/en/plugins) and [Plugin marketplaces](/en/plugin-marketplaces).197For more about the plugin system, see [Plugins](/en/plugins) and [Plugin marketplaces](/en/plugin-marketplaces).

193 198

199## Automate browser tasks with Chrome

200

201Connect Claude to your Chrome browser to test web apps, debug with console logs, and automate browser workflows without leaving VS Code. This requires the [Claude in Chrome extension](https://chromewebstore.google.com/detail/claude/fcoeoabgfenejglbffodgkkbkcdhcgfn) version 1.0.36 or higher.

202

203Type `@browser` in the prompt box followed by what you want Claude to do:

204

205```text theme={null}

206@browser go to localhost:3000 and check the console for errors

207```

208

209You can also open the attachment menu to select specific browser tools like opening a new tab or reading page content.

210

211Claude opens new tabs for browser tasks and shares your browser's login state, so it can access any site you're already signed into.

212

213For setup instructions, the full list of capabilities, and troubleshooting, see [Use Claude Code with Chrome](/en/chrome).

214

194## VS Code commands and shortcuts215## VS Code commands and shortcuts

195 216

196Open the Command Palette (`Cmd+Shift+P` on Mac or `Ctrl+Shift+P` on Windows/Linux) and type "Claude Code" to see all available VS Code commands for the Claude Code extension.217Open the Command Palette (`Cmd+Shift+P` on Mac or `Ctrl+Shift+P` on Windows/Linux) and type "Claude Code" to see all available VS Code commands for the Claude Code extension.

213| Show Logs | - | View extension debug logs |234| Show Logs | - | View extension debug logs |

214| Logout | - | Sign out of your Anthropic account |235| Logout | - | Sign out of your Anthropic account |

215 236

237### Launch a VS Code tab from other tools

238

239The extension registers a URI handler at `vscode://anthropic.claude-code/open`. Use it to open a new Claude Code tab from your own tooling: a shell alias, a browser bookmarklet, or any script that can open a URL. If VS Code isn't already running, opening the URL launches it first. If VS Code is already running, the URL opens in whichever window is currently focused.

240

241Invoke the handler with your operating system's URL opener. On macOS:

242

243```bash theme={null}

244open "vscode://anthropic.claude-code/open"

245```

246

247Use `xdg-open` on Linux or `start` on Windows.

248

249The handler accepts two optional query parameters:

250

251| Parameter | Description |

252| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

253| `prompt` | Text to pre-fill in the prompt box. Must be URL-encoded. The prompt is pre-filled but not submitted automatically. |

254| `session` | A session ID to resume instead of starting a new conversation. The session must belong to the workspace currently open in VS Code. If the session isn't found, a fresh conversation starts instead. If the session is already open in a tab, that tab is focused. To capture a session ID programmatically, see [Continue conversations](/en/headless#continue-conversations). |

255

256For example, to open a tab pre-filled with "review my changes":

257

258```text theme={null}

259vscode://anthropic.claude-code/open?prompt=review%20my%20changes

260```

261

216## Configure settings262## Configure settings

217 263

218The extension has two types of settings:264The extension has two types of settings:

219 265

220* **Extension settings** in VS Code: Control the extension's behavior within VS Code. Open with `Cmd+,` (Mac) or `Ctrl+,` (Windows/Linux), then go to Extensions → Claude Code. You can also type `/` and select **General Config** to open settings.266* **Extension settings** in VS Code: control the extension's behavior within VS Code. Open with `Cmd+,` (Mac) or `Ctrl+,` (Windows/Linux), then go to Extensions → Claude Code. You can also type `/` and select **General Config** to open settings.

221* **Claude Code settings** in `~/.claude/settings.json`: Shared between the extension and CLI. Use for allowed commands, environment variables, hooks, and MCP servers. See [Settings](/en/settings) for details.267* **Claude Code settings** in `~/.claude/settings.json`: shared between the extension and CLI. Use for allowed commands, environment variables, hooks, and MCP servers. See [Settings](/en/settings) for details.

222 268

223<Tip>269<Tip>

224 Add `"$schema": "https://json.schemastore.org/claude-code-settings.json"` to your `settings.json` to get autocomplete and inline validation for all available settings directly in VS Code.270 Add `"$schema": "https://json.schemastore.org/claude-code-settings.json"` to your `settings.json` to get autocomplete and inline validation for all available settings directly in VS Code.

227### Extension settings273### Extension settings

228 274

230| --------------------------------- | --------- | ----------------------------------------------------------------------------------------------------- |276| --------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

233| `initialPermissionMode` | `default` | Controls approval prompts: `default` (ask each time), `plan`, `acceptEdits`, or `bypassPermissions` |279| `initialPermissionMode` | `default` | Controls approval prompts for new conversations: `default`, `plan`, `acceptEdits`, `auto`, or `bypassPermissions`. See [permission modes](/en/permission-modes). |

240| `environmentVariables` | `[]` | Set environment variables for the Claude process. Use Claude Code settings instead for shared config. |286| `environmentVariables` | `[]` | Set environment variables for the Claude process. Use Claude Code settings instead for shared config. |

242| `allowDangerouslySkipPermissions` | `false` | Bypass all permission prompts. **Use with extreme caution.** |288| `allowDangerouslySkipPermissions` | `false` | Adds [Auto](/en/permission-modes#eliminate-prompts-with-auto-mode) and Bypass permissions to the mode selector. Auto requires a Team plan and Claude Sonnet 4.6 or Opus 4.6, so the option may remain unavailable even with this toggle on. Use Bypass permissions only in sandboxes with no internet access. |

243| `claudeProcessWrapper` | - | Executable path used to launch the Claude process |289| `claudeProcessWrapper` | - | Executable path used to launch the Claude process |

244 290

245## VS Code extension vs. Claude Code CLI291## VS Code extension vs. Claude Code CLI

247Claude Code is available as both a VS Code extension (graphical panel) and a CLI (command-line interface in the terminal). Some features are only available in the CLI. If you need a CLI-only feature, run `claude` in VS Code's integrated terminal.293Claude Code is available as both a VS Code extension (graphical panel) and a CLI (command-line interface in the terminal). Some features are only available in the CLI. If you need a CLI-only feature, run `claude` in VS Code's integrated terminal.

248 294

249| Feature | CLI | VS Code Extension |295| Feature | CLI | VS Code Extension |

250| ------------------- | --------------------------------------------- | ---------------------------------------- |296| ------------------- | ------------------- | ------------------------------------------------------------------------------------ |

252| MCP server config | Yes | No (configure via CLI, use in extension) |298| MCP server config | Yes | Partial (add servers via CLI; manage existing servers with `/mcp` in the chat panel) |

253| Checkpoints | Yes | Yes |299| Checkpoints | Yes | Yes |

254| `!` bash shortcut | Yes | No |300| `!` bash shortcut | Yes | No |

255| Tab completion | Yes | No |301| Tab completion | Yes | No |

284 330

285### Connect to external tools with MCP331### Connect to external tools with MCP

286 332

287MCP (Model Context Protocol) servers give Claude access to external tools, databases, and APIs. Configure them via CLI, then use them in both extension and CLI.333MCP (Model Context Protocol) servers give Claude access to external tools, databases, and APIs.

288 334

289To add an MCP server, open the integrated terminal (`` Ctrl+` `` or `` Cmd+` ``) and run:335To add an MCP server, open the integrated terminal (`` Ctrl+` `` or `` Cmd+` ``) and run:

290 336

292claude mcp add --transport http github https://api.githubcopilot.com/mcp/338claude mcp add --transport http github https://api.githubcopilot.com/mcp/

293```339```

294 340

295Once configured, ask Claude to use the tools (e.g., "Review PR #456"). Some servers require authentication: run `claude` in the terminal, then type `/mcp` to authenticate. See the [MCP documentation](/en/mcp) for available servers.341Once configured, ask Claude to use the tools (e.g., "Review PR #456").

342

343To manage MCP servers without leaving VS Code, type `/mcp` in the chat panel. The MCP management dialog lets you enable or disable servers, reconnect to a server, and manage OAuth authentication. See the [MCP documentation](/en/mcp) for available servers.

296 344

297## Work with git345## Work with git

298 346

302 350

303Claude can stage changes, write commit messages, and create pull requests based on your work:351Claude can stage changes, write commit messages, and create pull requests based on your work:

304 352

305```353```text theme={null}

306> commit my changes with a descriptive message354> commit my changes with a descriptive message

307> create a pr for this feature355> create a pr for this feature

308> summarize the changes I've made to the auth module356> summarize the changes I've made to the auth module

312 360

313### Use git worktrees for parallel tasks361### Use git worktrees for parallel tasks

314 362

315Git worktrees allow multiple Claude Code sessions to work on separate branches simultaneously, each with isolated files:363Use the `--worktree` (`-w`) flag to start Claude in an isolated worktree with its own files and branch:

316 364

317```bash theme={null}365```bash theme={null}

318# Create a worktree for a new feature366claude --worktree feature-auth

319git worktree add ../project-feature-a -b feature-a

~~320~~

321# Run Claude Code in each worktree

322cd ../project-feature-a && claude

323```367```

324 368

325Each worktree maintains independent file state while sharing git history. This prevents Claude instances from interfering with each other when working on different tasks.369Each worktree maintains independent file state while sharing git history. This prevents Claude instances from interfering with each other when working on different tasks. For more details, see [Run parallel sessions with Git worktrees](/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees).

~~326~~

327For detailed git workflows including PR reviews and branch management, see [Common workflows](/en/common-workflows#create-pull-requests).

328 370

329## Use third-party providers371## Use third-party providers

330 372

358* Use manual approval mode instead of auto-accept for edits400* Use manual approval mode instead of auto-accept for edits

359* Review changes carefully before accepting them401* Review changes carefully before accepting them

360 402

403### The built-in IDE MCP server

404

405When the extension is active, it runs a local MCP server that the CLI connects to automatically. This is how the CLI opens diffs in VS Code's native diff viewer, reads your current selection for `@`-mentions, and — when you're working in a Jupyter notebook — asks VS Code to execute cells.

406

407The server is named `ide` and is hidden from `/mcp` because there's nothing to configure. If your organization uses a `PreToolUse` hook to allowlist MCP tools, though, you'll need to know it exists.

408

409**Transport and authentication.** The server binds to `127.0.0.1` on a random high port and is not reachable from other machines. Each extension activation generates a fresh random auth token that the CLI must present to connect. The token is written to a lock file under `~/.claude/ide/` with `0600` permissions in a `0700` directory, so only the user running VS Code can read it.

410

411**Tools exposed to the model.** The server hosts a dozen tools, but only two are visible to the model. The rest are internal RPC the CLI uses for its own UI — opening diffs, reading selections, saving files — and are filtered out before the tool list reaches Claude.

412

413| Tool name (as seen by hooks) | What it does | Writes? |

414| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------- |

415| `mcp__ide__getDiagnostics` | Returns language-server diagnostics — the errors and warnings in VS Code's Problems panel. Optionally scoped to one file. | No |

416| `mcp__ide__executeCode` | Runs Python code in the active Jupyter notebook's kernel. See confirmation flow below. | Yes |

417

418**Jupyter execution always asks first.** `mcp__ide__executeCode` can't run anything silently. On each call, the code is inserted as a new cell at the end of the active notebook, VS Code scrolls it into view, and a native Quick Pick asks you to **Execute** or **Cancel**. Cancelling — or dismissing the picker with `Esc` — returns an error to Claude and nothing runs. The tool also refuses outright when there's no active notebook, when the Jupyter extension (`ms-toolsai.jupyter`) isn't installed, or when the kernel isn't Python.

419

420<Note>

421 The Quick Pick confirmation is separate from `PreToolUse` hooks. An allowlist entry for `mcp__ide__executeCode` lets Claude *propose* running a cell; the Quick Pick inside VS Code is what lets it *actually* run.

422</Note>

423

361## Fix common issues424## Fix common issues

362 425

363### Extension won't install426### Extension won't install

409Now that you have Claude Code set up in VS Code:472Now that you have Claude Code set up in VS Code:

410 473

411* [Explore common workflows](/en/common-workflows) to get the most out of Claude Code474* [Explore common workflows](/en/common-workflows) to get the most out of Claude Code

412* [Set up MCP servers](/en/mcp) to extend Claude's capabilities with external tools. Configure servers using the CLI, then use them in the extension.475* [Set up MCP servers](/en/mcp) to extend Claude's capabilities with external tools. Add servers using the CLI, then manage them with `/mcp` in the chat panel.

413* [Configure Claude Code settings](/en/settings) to customize allowed commands, hooks, and more. These settings are shared between the extension and CLI.476* [Configure Claude Code settings](/en/settings) to customize allowed commands, hooks, and more. These settings are shared between the extension and CLI.

web-scheduled-tasks.md +154 −0 added

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# Schedule tasks on the web

7> Automate recurring work with cloud scheduled tasks

9A scheduled task runs a prompt on a recurring cadence using Anthropic-managed infrastructure. Tasks keep working even when your computer is off.

11A few examples of recurring work you can automate:

13* Reviewing open pull requests each morning

14* Analyzing CI failures overnight and surfacing summaries

15* Syncing documentation after PRs merge

16* Running dependency audits every week

18Scheduled tasks are available to all Claude Code on the web users, including Pro, Max, Team, and Enterprise.

20## Compare scheduling options

22Claude Code offers three ways to schedule recurring work:

25| :------------------------- | :------------------------------- | :---------------------------------------------- | :----------------------------- |

27| Requires machine on | No | Yes | Yes |

28| Requires open session | No | No | Yes |

29| Persistent across restarts | Yes | Yes | No (session-scoped) |

30| Access to local files | No (fresh clone) | Yes | Yes |

33| Customizable schedule | Via `/schedule` in the CLI | Yes | Yes |

36<Tip>

37 Use **cloud tasks** for work that should run reliably without your machine. Use **Desktop tasks** when you need access to local files and tools. Use **`/loop`** for quick polling during a session.

38</Tip>

40## Create a scheduled task

42You can create a scheduled task from three places:

44* **Web**: visit [claude.ai/code/scheduled](https://claude.ai/code/scheduled) and click **New scheduled task**

45* **Desktop app**: open the **Schedule** page, click **New task**, and choose **New remote task**. See [Desktop scheduled tasks](/en/desktop#schedule-recurring-tasks) for details.

46* **CLI**: run `/schedule` in any session. Claude walks you through the setup conversationally. You can also pass a description directly, like `/schedule daily PR review at 9am`.

48The web and Desktop entry points open a form. The CLI collects the same information through a guided conversation.

50The steps below walk through the web interface.

52<Steps>

53 <Step title="Open the creation form">

54 Visit [claude.ai/code/scheduled](https://claude.ai/code/scheduled) and click **New scheduled task**.

55 </Step>

57 <Step title="Name the task and write the prompt">

58 Give the task a descriptive name and write the prompt Claude runs each time. The prompt is the most important part: the task runs autonomously, so the prompt must be self-contained and explicit about what to do and what success looks like.

60 The prompt input includes a model selector. Claude uses this model for each run of the task.

61 </Step>

63 <Step title="Select repositories">

64 Add one or more GitHub repositories for Claude to work in. Each repository is cloned at the start of a run, starting from the default branch. Claude creates `claude/`-prefixed branches for its changes. To allow pushes to any branch, enable **Allow unrestricted branch pushes** for that repository.

65 </Step>

67 <Step title="Select an environment">

68 Select a [cloud environment](/en/claude-code-on-the-web#cloud-environment) for the task. Environments control what the cloud session has access to:

70 * **Network access**: set the level of internet access available during each run

71 * **Environment variables**: provide API keys, tokens, or other secrets Claude can use

72 * **Setup script**: run install commands before each session starts, like installing dependencies or configuring tools

74 A **Default** environment is available out of the box. To use a custom environment, [create one](/en/claude-code-on-the-web#cloud-environment) before creating the task.

75 </Step>

77 <Step title="Choose a schedule">

78 Pick how often the task runs from the [frequency options](#frequency-options). The default is daily at 9:00 AM in your local time zone. Tasks may run a few minutes after their scheduled time due to stagger.

80 If the preset options don't fit your needs, pick the closest one and update the schedule from the CLI with `/schedule update` to set a specific schedule.

81 </Step>

83 <Step title="Review connectors">

84 All of your connected [MCP connectors](/en/mcp) are included by default. Remove any that the task doesn't need. Connectors give Claude access to external services like Slack, Linear, or Google Drive during each run.

85 </Step>

87 <Step title="Create the task">

88 Click **Create**. The task appears in the scheduled tasks list and runs automatically at the next scheduled time. Each run creates a new session alongside your other sessions, where you can see what Claude did, review changes, and create a pull request. To trigger a run immediately, click **Run now** from the task's detail page.

89 </Step>

90</Steps>

92### Frequency options

94The schedule picker offers preset frequencies that handle time zone conversion for you. Pick a time in your local zone and the task runs at that wall-clock time regardless of where the cloud infrastructure is located.

96<Note>

97 Tasks may run a few minutes after their scheduled time. The offset is consistent for each task.

98</Note>

100| Frequency | Description |

101| :-------- | :------------------------------------------------------------------------- |

102| Hourly | Runs every hour. |

103| Daily | Runs once per day at the time you specify. Defaults to 9:00 AM local time. |

104| Weekdays | Same as Daily but skips Saturday and Sunday. |

105| Weekly | Runs once per week on the day and time you specify. |

106

107For custom intervals like every 2 hours or first of each month, pick the closest preset and update the schedule from the CLI with `/schedule update` to set a specific schedule.

108

109### Repositories and branch permissions

110

111Each repository you add is cloned on every run. Claude starts from the repository's default branch unless your prompt specifies otherwise.

112

113By default, Claude can only push to branches prefixed with `claude/`. This prevents scheduled tasks from accidentally modifying protected or long-lived branches.

114

115To remove this restriction for a specific repository, enable **Allow unrestricted branch pushes** for that repository when creating or editing the task.

116

117### Connectors

118

119Scheduled tasks can use your connected MCP connectors to read from and write to external services during each run. For example, a task that triages support requests might read from a Slack channel and create issues in Linear.

120

121When you create a task, all of your currently connected connectors are included by default. Remove any that aren't needed to limit which tools Claude has access to during the run. You can also add connectors directly from the task form.

122

123To manage or add connectors outside of the task form, visit **Settings > Connectors** on claude.ai or use `/schedule update` in the CLI.

124

125### Environments

126

127Each task runs in a [cloud environment](/en/claude-code-on-the-web#cloud-environment) that controls network access, environment variables, and setup scripts. Configure environments before creating a task to give Claude access to APIs, install dependencies, or restrict network scope. See [cloud environment](/en/claude-code-on-the-web#cloud-environment) for the full setup guide.

128

129## Manage scheduled tasks

130

131Click a task in the **Scheduled** list to open its detail page. The detail page shows the task's repositories, connectors, prompt, schedule, and a list of past runs.

132

133### View and interact with runs

134

135Click any run to open it as a full session. From there you can see what Claude did, review changes, create a pull request, or continue the conversation. Each run session works like any other session: use the dropdown menu next to the session title to rename, archive, or delete it.

136

137### Edit and control tasks

138

139From the task detail page you can:

140

141* Click **Run now** to start a run immediately without waiting for the next scheduled time.

142* Use the toggle in the **Repeats** section to pause or resume the schedule. Paused tasks keep their configuration but don't run until you re-enable them.

143* Click the edit icon to change the name, prompt, schedule, repositories, environment, or connectors.

144* Click the delete icon to remove the task. Past sessions created by the task remain in your session list.

145

146You can also manage tasks from the CLI with `/schedule`. Run `/schedule list` to see all tasks, `/schedule update` to change a task, or `/schedule run` to trigger one immediately.

147

148## Related resources

149

150* [Desktop scheduled tasks](/en/desktop#schedule-recurring-tasks): schedule tasks that run on your machine with access to local files. The Desktop app's **Schedule** page shows both local and remote tasks in the same grid.

151* [`/loop` and CLI scheduled tasks](/en/scheduled-tasks): lightweight scheduling within a CLI session

152* [Cloud environment](/en/claude-code-on-the-web#cloud-environment): configure the runtime environment for cloud tasks

153* [MCP connectors](/en/mcp): connect external services like Slack, Linear, and Google Drive

154* [GitHub Actions](/en/github-actions): run Claude in your CI pipeline on repo events

zero-data-retention.md +66 −0 added

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# Zero data retention

7> Learn about Zero Data Retention (ZDR) for Claude Code on Claude for Enterprise, including scope, disabled features, and how to request enablement.

9Zero Data Retention (ZDR) is available for Claude Code when used through Claude for Enterprise. When ZDR is enabled, prompts and model responses generated during Claude Code sessions are processed in real time and not stored by Anthropic after the response is returned, except where needed to comply with law or combat misuse.

11ZDR on Claude for Enterprise gives enterprise customers the ability to use Claude Code with zero data retention and access administrative capabilities:

13* Cost controls per user

14* [Analytics](/en/analytics) dashboard

15* [Server-managed settings](/en/server-managed-settings)

16* Audit logs

18ZDR for Claude Code on Claude for Enterprise applies only to Anthropic's direct platform. For Claude deployments on AWS Bedrock, Google Vertex AI, or Microsoft Foundry, refer to those platforms' data retention policies.

20## ZDR scope

22ZDR covers Claude Code inference on Claude for Enterprise.

24<Warning>

25 ZDR is enabled on a per-organization basis. Each new organization requires ZDR to be enabled separately by your Anthropic account team. ZDR does not automatically apply to new organizations created under the same account. Contact your account team to enable ZDR for any new organizations.

26</Warning>

28### What ZDR covers

30ZDR covers model inference calls made through Claude Code on Claude for Enterprise. When you use Claude Code in your terminal, the prompts you send and the responses Claude generates are not retained by Anthropic. This applies regardless of which Claude model is used.

32### What ZDR does not cover

34ZDR does not extend to the following, even for organizations with ZDR enabled. These features follow [standard data retention policies](/en/data-usage#data-retention):

36| Feature | Details |

37| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

38| Chat on claude.ai | Chat conversations through the Claude for Enterprise web interface are not covered by ZDR. |

39| Cowork | Cowork sessions are not covered by ZDR. |

40| Claude Code Analytics | Does not store prompts or model responses, but collects productivity metadata such as account emails and usage statistics. Contribution metrics are not available for ZDR organizations; the [analytics dashboard](/en/analytics) shows usage metrics only. |

41| User and seat management | Administrative data such as account emails and seat assignments is retained under standard policies. |

42| Third-party integrations | Data processed by third-party tools, MCP servers, or other external integrations is not covered by ZDR. Review those services' data handling practices independently. |

44## Features disabled under ZDR

46When ZDR is enabled for a Claude Code organization on Claude for Enterprise, certain features that require storing prompts or completions are automatically disabled at the backend level:

48| Feature | Reason |

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

50| [Claude Code on the Web](/en/claude-code-on-the-web) | Requires server-side storage of conversation history. |

51| [Remote sessions](/en/desktop#remote-sessions) from the Desktop app | Requires persistent session data that includes prompts and completions. |

52| Feedback submission (`/feedback`) | Submitting feedback sends conversation data to Anthropic. |

54These features are blocked in the backend regardless of client-side display. If you see a disabled feature in the Claude Code terminal during startup, attempting to use it returns an error indicating the organization's policies do not allow that action.

56Future features may also be disabled if they require storing prompts or completions.

58## Data retention for policy violations

60Even with ZDR enabled, Anthropic may retain data where required by law or to address Usage Policy violations. If a session is flagged for a policy violation, Anthropic may retain the associated inputs and outputs for up to 2 years, consistent with Anthropic's standard ZDR policy.

62## Request ZDR

64To request ZDR for Claude Code on Claude for Enterprise, contact your Anthropic account team. Your account team will submit the request internally, and Anthropic will review and enable ZDR on your organization after confirming eligibility. All enablement actions are audit-logged.

66If you are currently using ZDR for Claude Code via pay-as-you-go API keys, you can transition to Claude for Enterprise to gain access to administrative features while maintaining ZDR for Claude Code. Contact your account team to coordinate the migration.

Anthropic - Claude Code Docs Changes 2026-02-01 21:03 UTC → 2026-03-28 18:04 UTC