Anthropic - Claude Code Docs Changes 2025-11-24 21:01 UTC → 2026-01-27 06:02 UTC

1> ## Documentation Index

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

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

4 

1# Claude Code on Amazon Bedrock5# Claude Code on Amazon Bedrock

2 6 

3> Learn about configuring Claude Code through Amazon Bedrock, including setup, IAM configuration, and troubleshooting.7> Learn about configuring Claude Code through Amazon Bedrock, including setup, IAM configuration, and troubleshooting.

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

8 12 

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

10* Access to desired Claude models (e.g., Claude Sonnet 4.5) in Bedrock14* Access to desired Claude models (for example, Claude Sonnet 4.5) in Bedrock

11* 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)

12* Appropriate IAM permissions16* Appropriate IAM permissions

13 17 

48export AWS_PROFILE=your-profile-name52export AWS_PROFILE=your-profile-name

49```53```

50 54 

51**Option D: Bedrock API keys**55**Option D: AWS Management Console credentials**

56 

57```bash theme={null}

58aws login

59```

60 

61[Learn more](https://docs.aws.amazon.com/signin/latest/userguide/command-line-sign-in.html) about `aws login`.

62 

63**Option E: Bedrock API keys**

52 64 

53```bash theme={null}65```bash theme={null}

54export AWS_BEARER_TOKEN_BEDROCK=your-bedrock-api-key66export AWS_BEARER_TOKEN_BEDROCK=your-bedrock-api-key

75 87 

76##### Configuration settings explained88##### Configuration settings explained

77 89 

78**`awsAuthRefresh`**: Use this for commands that modify the `.aws` directory (e.g., updating credentials, SSO cache, or config files). Output is shown to the user (but user input is not supported), making it suitable for browser-based authentication flows where the CLI displays a code to enter in the browser.90**`awsAuthRefresh`**: Use this for commands that modify the `.aws` directory, such as updating credentials, SSO cache, or config files. The command's output is displayed to the user, but interactive input isn't supported. This works well for browser-based SSO flows where the CLI displays a URL or code and you complete authentication in the browser.

79 91 

80**`awsCredentialExport`**: Only use this if you cannot modify `.aws` and must directly return credentials. Output is captured silently (not shown to the user). The command must output JSON in this format:92**`awsCredentialExport`**: Only use this if you can't modify `.aws` and must directly return credentials. Output is captured silently and not shown to the user. The command must output JSON in this format:

81 93 

82```json theme={null}94```json theme={null}

83{95{

102export ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION=us-west-2114export ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION=us-west-2

103```115```

104 116 

105**For VS Code Extension users**: Configure environment variables in the VS Code extension settings instead of exporting them in your shell. See [Using Third-Party Providers in VS Code](/en/vs-code#using-third-party-providers-vertex-and-bedrock) for detailed instructions. All environment variables shown in this guide should work when configured through the VS Code extension settings.

106 

107When enabling Bedrock for Claude Code, keep the following in mind:117When enabling Bedrock for Claude Code, keep the following in mind:

108 118 

109* `AWS_REGION` is a required environment variable. Claude Code does not read from the `.aws` config file for this setting.119* `AWS_REGION` is a required environment variable. Claude Code does not read from the `.aws` config file for this setting.

120| Small/fast model | `us.anthropic.claude-haiku-4-5-20251001-v1:0` |130| Small/fast model | `us.anthropic.claude-haiku-4-5-20251001-v1:0` |

121 131 

122<Note>132<Note>

123 For Bedrock 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 (e.g., `us.anthropic.claude-haiku-4-5-20251001-v1:0`).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`).

124</Note>134</Note>

125 135 

126To customize models, use one of these methods:136To customize models, use one of these methods:

137export DISABLE_PROMPT_CACHING=1147export DISABLE_PROMPT_CACHING=1

138```148```

139 149 

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

141 [Prompt caching](https://docs.claude.com/en/docs/build-with-claude/prompt-caching) may not be available in all regions

142</Note>

143 151 

144### 5. Output token configuration152### 5. Output token configuration

145 153 

146When using Claude Code with Amazon Bedrock, we recommend the following token settings:154These are the recommended token settings for Claude Code with Amazon Bedrock:

147 155 

148```bash theme={null}156```bash theme={null}

149# Recommended output token settings for Bedrock157# Recommended output token settings for Bedrock

153 161 

154**Why these values:**162**Why these values:**

155 163 

156* **`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.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.

157 165 

158* **`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.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.

159 167 

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

206</Note>214</Note>

207 215 

216## AWS Guardrails

217 

218[Amazon Bedrock Guardrails](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html) let you implement content filtering for Claude Code. Create a Guardrail in the [Amazon Bedrock console](https://console.aws.amazon.com/bedrock/), publish a version, then add the Guardrail headers to your [settings file](/en/settings). Enable Cross-Region inference on your Guardrail if you're using cross-region inference profiles.

219 

220Example configuration:

221 

222```json theme={null}

223{

224 "env": {

225 "ANTHROPIC_CUSTOM_HEADERS": "X-Amzn-Bedrock-GuardrailIdentifier: your-guardrail-id\nX-Amzn-Bedrock-GuardrailVersion: 1"

226 }

227}

228```

229 

208## Troubleshooting230## Troubleshooting

209 231 

210If you encounter region issues:232If you encounter region issues:

1> ## Documentation Index

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

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

4 

1# Analytics5# Analytics

2 6 

3> View detailed usage insights and productivity metrics for your organization's Claude Code deployment.7> View detailed usage insights and productivity metrics for your organization's Claude Code deployment.

1> ## Documentation Index

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

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

4 

5# Best Practices for Claude Code

6 

7> Tips and patterns for getting the most out of Claude Code, from configuring your environment to scaling across parallel sessions.

8 

9Claude Code is an agentic coding environment. Unlike a chatbot that answers questions and waits, Claude Code can read your files, run commands, make changes, and autonomously work through problems while you watch, redirect, or step away entirely.

10 

11This changes how you work. Instead of writing code yourself and asking Claude to review it, you describe what you want and Claude figures out how to build it. Claude explores, plans, and implements.

12 

13But this autonomy still comes with a learning curve. Claude works within certain constraints you need to understand.

14 

15This guide covers patterns that have proven effective across Anthropic's internal teams and for engineers using Claude Code across various codebases, languages, and environments. For how the agentic loop works under the hood, see [How Claude Code works](/en/how-claude-code-works).

16 

17***

18 

19Most best practices are based on one constraint: Claude's context window fills up fast, and performance degrades as it fills.

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.

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

24 

25***

26 

27## Give Claude a way to verify its work

28 

29<Tip>

30 Include tests, screenshots, or expected outputs so Claude can check itself. This is the single highest-leverage thing you can do.

31</Tip>

32 

33Claude performs dramatically better when it can verify its own work, like run tests, compare screenshots, and validate outputs.

34 

35Without clear success criteria, it might produce something that looks right but actually doesn't work. You become the only feedback loop, and every mistake requires your attention.

36 

37| Strategy | Before | After |

38| ------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

39| **Provide verification criteria** | *"implement a function that validates email addresses"* | *"write a validateEmail function. example test cases: [user@example.com](mailto:user@example.com) is true, invalid is false, [user@.com](mailto:user@.com) is false. run the tests after implementing"* |

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"* |

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.

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.

46 

47***

48 

49## Explore first, then plan, then code

50 

51<Tip>

52 Separate research and planning from implementation to avoid solving the wrong problem.

53</Tip>

54 

55Letting Claude jump straight to coding can produce code that solves the wrong problem. Use [Plan Mode](/en/common-workflows#use-plan-mode-for-safe-code-analysis) to separate exploration from execution.

56 

57The recommended workflow has four phases:

58 

59<Steps>

60 <Step title="Explore">

61 Enter Plan Mode. Claude reads files and answers questions without making changes.

62 

63 ```txt claude (Plan Mode) theme={null}

64 read /src/auth and understand how we handle sessions and login.

65 also look at how we manage environment variables for secrets.

66 ```

67 </Step>

68 

69 <Step title="Plan">

70 Ask Claude to create a detailed implementation plan.

71 

72 ```txt claude (Plan Mode) theme={null}

73 I want to add Google OAuth. What files need to change?

74 What's the session flow? Create a plan.

75 ```

76 

77 Press `Ctrl+G` to open the plan in your text editor for direct editing before Claude proceeds.

78 </Step>

79 

80 <Step title="Implement">

81 Switch back to Normal Mode and let Claude code, verifying against its plan.

82 

83 ```txt claude (Normal Mode) theme={null}

84 implement the OAuth flow from your plan. write tests for the

85 callback handler, run the test suite and fix any failures.

86 ```

87 </Step>

88 

89 <Step title="Commit">

90 Ask Claude to commit with a descriptive message and create a PR.

91 

92 ```txt claude (Normal Mode) theme={null}

93 commit with a descriptive message and open a PR

94 ```

95 </Step>

96</Steps>

97 

98<Callout>

99 Plan Mode is useful, but also adds overhead.

100 

101 For tasks where the scope is clear and the fix is small (like fixing a typo, adding a log line, or renaming a variable) ask Claude to do it directly.

102 

103 Planning is most useful when you're uncertain about the approach, when the change modifies multiple files, or when you're unfamiliar with the code being modified. If you could describe the diff in one sentence, skip the plan.

104</Callout>

105 

106***

107 

108## Provide specific context in your prompts

109 

110<Tip>

111 The more precise your instructions, the fewer corrections you'll need.

112</Tip>

113 

114Claude can infer intent, but it can't read your mind. Reference specific files, mention constraints, and point to example patterns.

115 

116| Strategy | Before | After |

117| ------------------------------------------------------------------------------------------------ | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

118| **Scope the task.** Specify which file, what scenario, and testing preferences. | *"add tests for foo.py"* | *"write a test for foo.py covering the edge case where the user is logged out. avoid mocks."* |

119| **Point to sources.** Direct Claude to the source that can answer a question. | *"why does ExecutionFactory have such a weird api?"* | *"look through ExecutionFactory's git history and summarize how its api came to be"* |

120| **Reference existing patterns.** Point Claude to patterns in your codebase. | *"add a calendar widget"* | *"look at how existing widgets are implemented on the home page to understand the patterns. HotDogWidget.php is a good example. follow the pattern to implement a new calendar widget that lets the user select a month and paginate forwards/backwards to pick a year. build from scratch without libraries other than the ones already used in the codebase."* |

121| **Describe the symptom.** Provide the symptom, the likely location, and what "fixed" looks like. | *"fix the login bug"* | *"users report that login fails after session timeout. check the auth flow in src/auth/, especially token refresh. write a failing test that reproduces the issue, then fix it"* |

122 

123Vague prompts can be useful when you're exploring and can afford to course-correct. A prompt like `"what would you improve in this file?"` can surface things you wouldn't have thought to ask about.

124 

125### Provide rich content

126 

127<Tip>

128 Use `@` to reference files, paste screenshots/images, or pipe data directly.

129</Tip>

130 

131You can provide rich data to Claude in several ways:

132 

133* **Reference files with `@`** instead of describing where code lives. Claude reads the file before responding.

134* **Paste images directly**. Copy/paste or drag and drop images into the prompt.

135* **Give URLs** for documentation and API references. Use `/permissions` to allowlist frequently-used domains.

136* **Pipe in data** by running `cat error.log | claude` to send file contents directly.

137* **Let Claude fetch what it needs**. Tell Claude to pull context itself using Bash commands, MCP tools, or by reading files.

138 

139***

140 

141## Configure your environment

142 

143A few setup steps make Claude Code significantly more effective across all your sessions. For a full overview of extension features and when to use each one, see [Extend Claude Code](/en/features-overview).

144 

145### Write an effective CLAUDE.md

146 

147<Tip>

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

149</Tip>

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

152 

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

154 

155There's no required format for CLAUDE.md files, but keep it short and human-readable. For example:

156 

157```markdown CLAUDE.md theme={null}

158# Code style

159- Use ES modules (import/export) syntax, not CommonJS (require)

160- Destructure imports when possible (eg. import { foo } from 'bar')

161 

162# Workflow

163- Be sure to typecheck when you're done making a series of code changes

164- Prefer running single tests, and not the whole test suite, for performance

165```

166 

167CLAUDE.md is loaded every session, so only include things that apply broadly. For domain knowledge or workflows that are only relevant sometimes, use [skills](/en/skills) instead. Claude loads them on demand without bloating every conversation.

168 

169Keep it concise. For each line, ask: *"Would removing this cause Claude to make mistakes?"* If not, cut it. Bloated CLAUDE.md files cause Claude to ignore your actual instructions!

170 

171| ✅ Include | ❌ Exclude |

172| ---------------------------------------------------- | -------------------------------------------------- |

173| Bash commands Claude can't guess | Anything Claude can figure out by reading code |

174| Code style rules that differ from defaults | Standard language conventions Claude already knows |

175| Testing instructions and preferred test runners | Detailed API documentation (link to docs instead) |

176| Repository etiquette (branch naming, PR conventions) | Information that changes frequently |

177| Architectural decisions specific to your project | Long explanations or tutorials |

178| Developer environment quirks (required env vars) | File-by-file descriptions of the codebase |

179| Common gotchas or non-obvious behaviors | Self-evident practices like "write clean code" |

180 

181If Claude keeps doing something you don't want despite having a rule against it, the file is probably too long and the rule is getting lost. If Claude asks you questions that are answered in CLAUDE.md, the phrasing might be ambiguous. Treat CLAUDE.md like code: review it when things go wrong, prune it regularly, and test changes by observing whether Claude's behavior actually shifts.

182 

183You can tune instructions by adding emphasis (e.g., "IMPORTANT" or "YOU MUST") to improve adherence. Check CLAUDE.md into git so your team can contribute. The file compounds in value over time.

184 

185CLAUDE.md files can import additional files using `@path/to/import` syntax:

186 

187```markdown CLAUDE.md theme={null}

188See @README.md for project overview and @package.json for available npm commands.

189 

190# Additional Instructions

191- Git workflow: @docs/git-instructions.md

192- Personal overrides: @~/.claude/my-project-instructions.md

193```

194 

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

196 

197* **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` it

199* **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 directories

201 

202### Configure permissions

203 

204<Tip>

205 Use `/permissions` to allowlist safe commands or `/sandbox` for OS-level isolation. This reduces interruptions while keeping you in control.

206</Tip>

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:

209 

210* **Permission allowlists**: Permit specific tools you know are safe (like `npm run lint` or `git commit`)

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

212 

213Alternatively, use `--dangerously-skip-permissions` to bypass all permission checks for contained workflows like fixing lint errors or generating boilerplate.

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 

221### Use CLI tools

222 

223<Tip>

224 Tell Claude Code to use CLI tools like `gh`, `aws`, `gcloud`, and `sentry-cli` when interacting with external services.

225</Tip>

226 

227CLI tools are the most context-efficient way to interact with external services. If you use GitHub, install the `gh` CLI. Claude knows how to use it for creating issues, opening pull requests, and reading comments. Without `gh`, Claude can still use the GitHub API, but unauthenticated requests often hit rate limits.

228 

229Claude is also effective at learning CLI tools it doesn't already know. Try prompts like `Use 'foo-cli-tool --help' to learn about foo tool, then use it to solve A, B, C.`

230 

231### Connect MCP servers

232 

233<Tip>

234 Run `claude mcp add` to connect external tools like Notion, Figma, or your database.

235</Tip>

236 

237With [MCP servers](/en/mcp), you can ask Claude to implement features from issue trackers, query databases, analyze monitoring data, integrate designs from Figma, and automate workflows.

238 

239### Set up hooks

240 

241<Tip>

242 Use hooks for actions that must happen every time with zero exceptions.

243</Tip>

244 

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.

246 

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.

248 

249### Create skills

250 

251<Tip>

252 Create `SKILL.md` files in `.claude/skills/` to give Claude domain knowledge and reusable workflows.

253</Tip>

254 

255[Skills](/en/skills) extend Claude's knowledge with information specific to your project, team, or domain. Claude applies them automatically when relevant, or you can invoke them directly with `/skill-name`.

256 

257Create a skill by adding a directory with a `SKILL.md` to `.claude/skills/`:

258 

259```markdown .claude/skills/api-conventions/SKILL.md theme={null}

260---

261name: api-conventions

262description: REST API design conventions for our services

263---

264# API Conventions

265- Use kebab-case for URL paths

266- Use camelCase for JSON properties

267- Always include pagination for list endpoints

268- Version APIs in the URL path (/v1/, /v2/)

269```

270 

271Skills can also define repeatable workflows you invoke directly:

272 

273```markdown .claude/skills/fix-issue/SKILL.md theme={null}

274---

275name: fix-issue

276description: Fix a GitHub issue

277disable-model-invocation: true

278---

279Analyze and fix the GitHub issue: $ARGUMENTS.

280 

2811. Use `gh issue view` to get the issue details

2822. Understand the problem described in the issue

2833. Search the codebase for relevant files

2844. Implement the necessary changes to fix the issue

2855. Write and run tests to verify the fix

2866. Ensure code passes linting and type checking

2877. Create a descriptive commit message

2888. Push and create a PR

289```

290 

291Run `/fix-issue 1234` to invoke it. Use `disable-model-invocation: true` for workflows with side effects that you want to trigger manually.

292 

293### Create custom subagents

294 

295<Tip>

296 Define specialized assistants in `.claude/agents/` that Claude can delegate to for isolated tasks.

297</Tip>

298 

299[Subagents](/en/sub-agents) run in their own context with their own set of allowed tools. They're useful for tasks that read many files or need specialized focus without cluttering your main conversation.

300 

301```markdown .claude/agents/security-reviewer.md theme={null}

302---

303name: security-reviewer

304description: Reviews code for security vulnerabilities

305tools: Read, Grep, Glob, Bash

306model: opus

307---

308You are a senior security engineer. Review code for:

309- Injection vulnerabilities (SQL, XSS, command injection)

310- Authentication and authorization flaws

311- Secrets or credentials in code

312- Insecure data handling

313 

314Provide specific line references and suggested fixes.

315```

316 

317Tell Claude to use subagents explicitly: *"Use a subagent to review this code for security issues."*

318 

319### Install plugins

320 

321<Tip>

322 Run `/plugin` to browse the marketplace. Plugins add skills, tools, and integrations without configuration.

323</Tip>

324 

325[Plugins](/en/plugins) bundle skills, hooks, subagents, and MCP servers into a single installable unit from the community and Anthropic. If you work with a typed language, install a [code intelligence plugin](/en/discover-plugins#code-intelligence) to give Claude precise symbol navigation and automatic error detection after edits.

326 

327For guidance on choosing between skills, subagents, hooks, and MCP, see [Extend Claude Code](/en/features-overview#match-features-to-your-goal).

328 

329***

330 

331## Communicate effectively

332 

333The way you communicate with Claude Code significantly impacts the quality of results.

334 

335### Ask codebase questions

336 

337<Tip>

338 Ask Claude questions you'd ask a senior engineer.

339</Tip>

340 

341When onboarding to a new codebase, use Claude Code for learning and exploration. You can ask Claude the same sorts of questions you would ask another engineer:

342 

343* How does logging work?

344* How do I make a new API endpoint?

345* What does `async move { ... }` do on line 134 of `foo.rs`?

346* What edge cases does `CustomerOnboardingFlowImpl` handle?

347* Why does this code call `foo()` instead of `bar()` on line 333?

348 

349Using Claude Code this way is an effective onboarding workflow, improving ramp-up time and reducing load on other engineers. No special prompting required: ask questions directly.

350 

351### Let Claude interview you

352 

353<Tip>

354 For larger features, have Claude interview you first. Start with a minimal prompt and ask Claude to interview you using the `AskUserQuestion` tool.

355</Tip>

356 

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

358 

359```

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

361 

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.

363 

364Keep interviewing until we've covered everything, then write a complete spec to SPEC.md.

365```

366 

367Once the spec is complete, start a fresh session to execute it. The new session has clean context focused entirely on implementation, and you have a written spec to reference.

368 

369***

370 

371## Manage your session

372 

373Conversations are persistent and reversible. Use this to your advantage!

374 

375### Course-correct early and often

376 

377<Tip>

378 Correct Claude as soon as you notice it going off track.

379</Tip>

380 

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.

382 

383* **`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.

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

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

387 

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.

389 

390### Manage context aggressively

391 

392<Tip>

393 Run `/clear` between unrelated tasks to reset context.

394</Tip>

395 

396Claude Code automatically compacts conversation history when you approach context limits, which preserves important code and decisions while freeing space.

397 

398During long sessions, Claude's context window can fill with irrelevant conversation, file contents, and commands. This can reduce performance and sometimes distract Claude.

399 

400* 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 decisions

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

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 summarization

404 

405### Use subagents for investigation

406 

407<Tip>

408 Delegate research with `"use subagents to investigate X"`. They explore in a separate context, keeping your main conversation clean for implementation.

409</Tip>

410 

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:

412 

413```

414Use subagents to investigate how our authentication system handles token

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

416```

417 

418The subagent explores the codebase, reads relevant files, and reports back with findings, all without cluttering your main conversation.

419 

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

421 

422```

423use a subagent to review this code for edge cases

424```

425 

426### Rewind with checkpoints

427 

428<Tip>

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

430</Tip>

431 

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.

433 

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.

435 

436<Warning>

437 Checkpoints only track changes made *by Claude*, not external processes. This isn't a replacement for git.

438</Warning>

439 

440### Resume conversations

441 

442<Tip>

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

444</Tip>

445 

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:

447 

448```bash theme={null}

449claude --continue # Resume the most recent conversation

450claude --resume # Select from recent conversations

451```

452 

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.

454 

455***

456 

457## Automate and scale

458 

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

460 

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.

462 

463### Run headless mode

464 

465<Tip>

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

467</Tip>

468 

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.

470 

471```bash theme={null}

472# One-off queries

473claude -p "Explain what this project does"

474 

475# Structured output for scripts

476claude -p "List all API endpoints" --output-format json

477 

478# Streaming for real-time processing

479claude -p "Analyze this log file" --output-format stream-json

480```

481 

482### Run multiple Claude sessions

483 

484<Tip>

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

486</Tip>

487 

488There are two main ways to run parallel sessions:

489 

490* [Claude Desktop](/en/desktop): 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.

492 

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.

494 

495For example, use a Writer/Reviewer pattern:

496 

497| Session A (Writer) | Session B (Reviewer) |

498| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

499| `Implement a rate limiter for our API endpoints` | |

500| | `Review the rate limiter implementation in @src/middleware/rateLimiter.ts. Look for edge cases, race conditions, and consistency with our existing middleware patterns.` |

501| `Here's the review feedback: [Session B output]. Address these issues.` | |

502 

503You can do something similar with tests: have one Claude write tests, then another write code to pass them.

504 

505### Fan out across files

506 

507<Tip>

508 Loop through tasks calling `claude -p` for each. Use `--allowedTools` to scope permissions for batch operations.

509</Tip>

510 

511For large migrations or analyses, you can distribute work across many parallel Claude invocations:

512 

513<Steps>

514 <Step title="Generate a task list">

515 Have Claude list all files that need migrating (e.g., `list all 2,000 Python files that need migrating`)

516 </Step>

517 

518 <Step title="Write a script to loop through the list">

519 ```bash theme={null}

520 for file in $(cat files.txt); do

521 claude -p "Migrate $file from React to Vue. Return OK or FAIL." \

522 --allowedTools "Edit,Bash(git commit:*)"

523 done

524 ```

525 </Step>

526 

527 <Step title="Test on a few files, then run at scale">

528 Refine your prompt based on what goes wrong with the first 2-3 files, then run on the full set. The `--allowedTools` flag restricts what Claude can do, which matters when you're running unattended.

529 </Step>

530</Steps>

531 

532You can also integrate Claude into existing data/processing pipelines:

533 

534```bash theme={null}

535claude -p "<your prompt>" --output-format json | your_command

536```

537 

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

539 

540### Safe Autonomous Mode

541 

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.

543 

544<Warning>

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.

546 

547 With sandboxing enabled (`/sandbox`), you get similar autonomy with better security. Sandbox defines upfront boundaries rather than bypassing all checks.

548</Warning>

549 

550***

551 

552## Avoid common failure patterns

553 

554These are common mistakes. Recognizing them early saves time:

555 

556* **The kitchen sink session.** You start with one task, then ask Claude something unrelated, then go back to the first task. Context is full of irrelevant information.

557 > **Fix**: `/clear` between unrelated tasks.

558* **Correcting over and over.** Claude does something wrong, you correct it, it's still wrong, you correct again. Context is polluted with failed approaches.

559 > **Fix**: After two failed corrections, `/clear` and write a better initial prompt incorporating what you learned.

560* **The over-specified CLAUDE.md.** If your CLAUDE.md is too long, Claude ignores half of it because important rules get lost in the noise.

561 > **Fix**: Ruthlessly prune. If Claude already does something correctly without the instruction, delete it or convert it to a hook.

562* **The trust-then-verify gap.** Claude produces a plausible-looking implementation that doesn't handle edge cases.

563 > **Fix**: Always provide verification (tests, scripts, screenshots). If you can't verify it, don't ship it.

564* **The infinite exploration.** You ask Claude to "investigate" something without scoping it. Claude reads hundreds of files, filling the context.

565 > **Fix**: Scope investigations narrowly or use subagents so the exploration doesn't consume your main context.

566 

567***

568 

569## Develop your intuition

570 

571The patterns in this guide aren't set in stone. They're starting points that work well in general, but might not be optimal for every situation.

572 

573Sometimes you *should* let context accumulate because you're deep in one complex problem and the history is valuable. Sometimes you should skip planning and let Claude figure it out because the task is exploratory. Sometimes a vague prompt is exactly right because you want to see how Claude interprets the problem before constraining it.

574 

575Pay attention to what works. When Claude produces great output, notice what you did: the prompt structure, the context you provided, the mode you were in. When Claude struggles, ask why. Was the context too noisy? The prompt too vague? The task too big for one pass?

576 

577Over time, you'll develop intuition that no guide can capture. You'll know when to be specific and when to be open-ended, when to plan and when to explore, when to clear context and when to let it accumulate.

578 

579## Related resources

580 

581<CardGroup cols={2}>

582 <Card title="How Claude Code works" icon="gear" href="/en/how-claude-code-works">

583 Understand the agentic loop, tools, and context management

584 </Card>

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>

1> ## Documentation Index

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

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

4 

1# Checkpointing5# Checkpointing

2 6 

3> Automatically track and rewind Claude's edits to quickly recover from unwanted changes.7> Automatically track and rewind Claude's edits to quickly recover from unwanted changes.

61## See also65## See also

62 66 

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

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

65* [CLI reference](/en/cli-reference) - Command-line options69* [CLI reference](/en/cli-reference) - Command-line options

1> ## Documentation Index

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

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

4 

5# Use Claude Code with Chrome (beta)

6 

7> Connect Claude Code to your browser to test web apps, debug with console logs, and automate browser tasks.

8 

9<Note>

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 

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.

14 

15## What the integration enables

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.

18 

19Key capabilities include:

20 

21* **Live debugging**: Claude reads console errors and DOM state directly, then fixes 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

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

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

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

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

28 

29## Prerequisites

30 

31Before using Claude Code with Chrome, you need:

32 

33* [Google Chrome](https://www.google.com/chrome/) browser

34* [Claude in Chrome extension](https://chromewebstore.google.com/detail/claude/fcoeoabgfenejglbffodgkkbkcdhcgfn) version 1.0.36 or higher

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

36* A paid Claude plan (Pro, Team, or Enterprise)

37 

38## How the integration works

39 

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.

41 

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.

43 

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 

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

48</Note>

49 

50## Set up the integration

51 

52<Steps>

53 <Step title="Update Claude Code">

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:

55 

56 ```bash theme={null}

57 claude update

58 ```

59 </Step>

60 

61 <Step title="Start Claude Code with Chrome enabled">

62 Launch Claude Code with the `--chrome` flag:

63 

64 ```bash theme={null}

65 claude --chrome

66 ```

67 </Step>

68 

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>

73 

74You can also enable Chrome integration from within an existing session using the `/chrome` command.

75 

76## Try it out

77 

78Once connected, type this into Claude to see the integration in action:

79 

80```

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

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

83```

84 

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.

86 

87## Example workflows

88 

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.

90 

91The following examples show common patterns for browser automation.

92 

93### Test a local web application

94 

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

96 

97```

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

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

100messages appear correctly?

101```

102 

103Claude navigates to your local server, interacts with the form, and reports what it observes.

104 

105### Debug with console logs

106 

107If your app has issues, Claude can read console output to help diagnose problems:

108 

109```

110Open the dashboard page and check the console for any errors when

111the page loads.

112```

113 

114Claude reads the console messages and can filter for specific patterns or error types.

115 

116### Automate form filling

117 

118Speed up repetitive data entry tasks:

119 

120```

121I 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 the

123name, email, and phone fields.

124```

125 

126Claude reads your local file, navigates the web interface, and enters the data for each record.

127 

128### Draft content in Google Docs

129 

130Use Claude to write directly in your documents without API setup:

131 

132```

133Draft a project update based on our recent commits and add it to my

134Google Doc at docs.google.com/document/d/abc123

135```

136 

137Claude opens the document, clicks into the editor, and types the content. This works with any web app you're logged into: Gmail, Notion, Sheets, and more.

138 

139### Extract data from web pages

140 

141Pull structured information from websites:

142 

143```

144Go to the product listings page and extract the name, price, and

145availability for each item. Save the results as a CSV file.

146```

147 

148Claude navigates to the page, reads the content, and compiles the data into a structured format.

149 

150### Run multi-site workflows

151 

152Coordinate tasks across multiple websites:

153 

154```

155Check my calendar for meetings tomorrow, then for each meeting with

156an external attendee, look up their company on LinkedIn and add a

157note about what they do.

158```

159 

160Claude works across tabs to gather information and complete the workflow.

161 

162### Record a demo GIF

163 

164Create shareable recordings of browser interactions:

165 

166```

167Record a GIF showing how to complete the checkout flow, from adding

168an item to the cart through to the confirmation page.

169```

170 

171Claude records the interaction sequence and saves it as a GIF file.

172 

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

182 

183### Extension not detected

184 

185If Claude Code shows "Chrome extension not detected":

186 

1871. Verify the Chrome extension (version 1.0.36 or higher) is installed

1882. Verify Claude Code is version 2.0.73 or higher by running `claude --version`

1893. Check that Chrome is running

1904. Run `/chrome` and select "Reconnect extension" to re-establish the connection

1915. If the issue persists, restart both Claude Code and Chrome

192 

193### Browser not responding

194 

195If Claude's browser commands stop working:

196 

1971. Check if a modal dialog (alert, confirm, prompt) is blocking the page

1982. Ask Claude to create a new tab and try again

1993. Restart the Chrome extension by disabling and re-enabling it

200 

201### First-time setup

202 

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.

204 

205## Enable by default

206 

207Chrome integration requires the `--chrome` flag each time you start Claude Code. To enable it by default, run `/chrome` and select "Enabled by default".

208 

209<Note>

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.

211</Note>

212 

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.

214 

215## See also

216 

217* [CLI reference](/en/cli-reference) - Command-line flags including `--chrome`

218* [Common workflows](/en/common-workflows) - More ways to use Claude Code

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 permissions

1> ## Documentation Index

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

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

4 

1# Claude Code on the web5# Claude Code on the web

2 6 

3> Run Claude Code tasks asynchronously on secure cloud infrastructure7> Run Claude Code tasks asynchronously on secure cloud infrastructure

11Claude Code on the web lets developers kick off Claude Code from the Claude app. This is perfect for:15Claude Code on the web lets developers kick off Claude Code from the Claude app. This is perfect for:

12 16 

13* **Answering questions**: Ask about code architecture and how features are implemented17* **Answering questions**: Ask about code architecture and how features are implemented

14* **Bugfixes and routine tasks**: Well-defined tasks that don't require frequent steering18* **Bug fixes and routine tasks**: Well-defined tasks that don't require frequent steering

15* **Parallel work**: Tackle multiple bug fixes in parallel19* **Parallel work**: Tackle multiple bug fixes in parallel

16* **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

17* **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

18 22 

19Claude Code is also available on the Claude iOS app. This is perfect for:23Claude Code is also available on the Claude iOS app for kicking off tasks on the go and monitoring work in progress.

20 

21* **On the go**: Kick off tasks while commuting or away from laptop

22* **Monitoring**: Watch the trajectory and steer the agent's work

23 24 

24Developers can also move Claude Code sessions from the Claude app to their terminal to continue tasks locally.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.

25 26 

26## Who can use Claude Code on the web?27## Who can use Claude Code on the web?

27 28 

393. Install the Claude GitHub app in your repositories403. Install the Claude GitHub app in your repositories

404. Select your default environment414. Select your default environment

415. Submit your coding task425. Submit your coding task

426. Review changes and create a pull request in GitHub436. Review changes in diff view, iterate with comments, then create a pull request

43 44 

44## How it works45## How it works

45 46 

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

536. **Results**: Changes are pushed to a branch, ready for pull request creation546. **Results**: Changes are pushed to a branch, ready for pull request creation

54 55 

56## Review changes with diff view

57 

58Diff view lets you see exactly what Claude changed before creating a pull request. Instead of clicking "Create PR" to review changes in GitHub, view the diff directly in the app and iterate with Claude until the changes are ready.

59 

60When Claude makes changes to files, a diff stats indicator appears showing the number of lines added and removed (for example, `+12 -1`). Select this indicator to open the diff viewer, which displays a file list on the left and the changes for each file on the right.

61 

62From the diff view, you can:

63 

64* Review changes file by file

65* Comment on specific changes to request modifications

66* Continue iterating with Claude based on what you see

67 

68This lets you refine changes through multiple rounds of feedback without creating draft PRs or switching to GitHub.

69 

55## Moving tasks between web and terminal70## Moving tasks between web and terminal

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

73 

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.

76</Note>

77 

78### From terminal to web

79 

80Start a message with `&` inside Claude Code to send a task to run on the web:

81 

82```

83& Fix the authentication bug in src/auth/login.ts

84```

85 

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.

87 

88You can also start a web session directly from the command line:

89 

90```bash theme={null}

91claude --remote "Fix the authentication bug in src/auth/login.ts"

92```

93 

94#### Tips for background tasks

95 

96**Plan locally, execute remotely**: For complex tasks, start Claude in plan mode to collaborate on the approach before sending work to the web:

97 

98```bash theme={null}

99claude --permission-mode plan

100```

101 

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:

103 

104```

105& Execute the migration plan we discussed

106```

107 

108This pattern gives you control over the strategy while letting Claude execute autonomously in the cloud.

109 

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:

111 

112```

113& Fix the flaky test in auth.spec.ts

114& Update the API documentation

115& Refactor the logger to use structured output

116```

117 

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.

119 

57### From web to terminal120### From web to terminal

58 121 

59After starting a task on the web:122There are several ways to pull a web session into your terminal:

123 

124* **Using `/teleport`**: From within Claude Code, run `/teleport` (or `/tp`) to see an interactive picker of your web sessions. If you have uncommitted changes, you'll be prompted to stash them first.

125* **Using `--teleport`**: From the command line, run `claude --teleport` for an interactive session picker, or `claude --teleport <session-id>` to resume a specific session directly.

126* **From `/tasks`**: Run `/tasks` to see your background sessions, then press `t` to teleport into one

127* **From the web interface**: Click "Open in CLI" to copy a command you can paste into your terminal

128 

129When you teleport a session, Claude verifies you're in the correct repository, fetches and checks out the branch from the remote session, and loads the full conversation history into your terminal.

60 130 

611. Click the "Open in CLI" button131#### Requirements for teleporting

622. Paste and run the command in your terminal in a checkout of the repo132 

633. Any existing local changes will be stashed, and the remote session will be loaded133Teleport checks these requirements before resuming a session. If any requirement isn't met, you'll see an error or be prompted to resolve the issue.

644. Continue working locally134 

135| Requirement | Details |

136| ------------------ | ---------------------------------------------------------------------------------------------------------------------- |

137| Clean git state | Your working directory must have no uncommitted changes. Teleport prompts you to stash changes if needed. |

138| Correct repository | You must run `--teleport` from a checkout of the same repository, not a fork. |

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

65 141 

66## Cloud environment142## Cloud environment

67 143 

127 203 

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

129 205 

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.

207 

130<Note>208<Note>

131 Environment variables must be specified as key-value pairs, in [`.env` format](https://www.dotenv.org/). For example:209 Environment variables must be specified as key-value pairs, in [`.env` format](https://www.dotenv.org/). For example:

132 210 

223 301 

224* api.anthropic.com302* api.anthropic.com

225* statsig.anthropic.com303* statsig.anthropic.com

304* docs.claude.com

305* code.claude.com

226* claude.ai306* claude.ai

227 307 

228#### Version Control308#### Version Control

230* github.com310* github.com

231* [www.github.com](http://www.github.com)311* [www.github.com](http://www.github.com)

232* api.github.com312* api.github.com

313* npm.pkg.github.com

233* raw\.githubusercontent.com314* raw\.githubusercontent.com

315* pkg-npm.githubusercontent.com

234* objects.githubusercontent.com316* objects.githubusercontent.com

235* codeload.github.com317* codeload.github.com

236* avatars.githubusercontent.com318* avatars.githubusercontent.com

252* [www.docker.com](http://www.docker.com)334* [www.docker.com](http://www.docker.com)

253* production.cloudflare.docker.com335* production.cloudflare.docker.com

254* download.docker.com336* download.docker.com

337* gcr.io

255* \*.gcr.io338* \*.gcr.io

256* ghcr.io339* ghcr.io

257* mcr.microsoft.com340* mcr.microsoft.com

258* \*.data.mcr.microsoft.com341* \*.data.mcr.microsoft.com

342* public.ecr.aws

259 343 

260#### Cloud Platforms344#### Cloud Platforms

261 345 

276* dot.net360* dot.net

277* visualstudio.com361* visualstudio.com

278* dev.azure.com362* dev.azure.com

363* \*.amazonaws.com

364* \*.api.aws

279* oracle.com365* oracle.com

280* [www.oracle.com](http://www.oracle.com)366* [www.oracle.com](http://www.oracle.com)

281* java.com367* java.com

325 411 

326* crates.io412* crates.io

327* [www.crates.io](http://www.crates.io)413* [www.crates.io](http://www.crates.io)

414* index.crates.io

328* static.crates.io415* static.crates.io

329* rustup.rs416* rustup.rs

330* static.rust-lang.org417* static.rust-lang.org

423* statsig.com510* statsig.com

424* [www.statsig.com](http://www.statsig.com)511* [www.statsig.com](http://www.statsig.com)

425* api.statsig.com512* api.statsig.com

513* sentry.io

426* \*.sentry.io514* \*.sentry.io

515* http-intake.logs.datadoghq.com

516* \*.datadoghq.com

517* \*.datadoghq.eu

427 518 

428#### Content Delivery & Mirrors519#### Content Delivery & Mirrors

429 520 

521* sourceforge.net

430* \*.sourceforge.net522* \*.sourceforge.net

431* packagecloud.io523* packagecloud.io

432* \*.packagecloud.io524* \*.packagecloud.io

438* json.schemastore.org530* json.schemastore.org

439* [www.schemastore.org](http://www.schemastore.org)531* [www.schemastore.org](http://www.schemastore.org)

440 532 

533#### Model Context Protocol

534 

535* \*.modelcontextprotocol.io

536 

441<Note>537<Note>

442 Domains marked with `*` indicate wildcard subdomain matching. For example, `*.gcr.io` allows access to any subdomain of `gcr.io`.538 Domains marked with `*` indicate wildcard subdomain matching. For example, `*.gcr.io` allows access to any subdomain of `gcr.io`.

443</Note>539</Note>

473 569 

474## Best practices570## Best practices

475 571 

4761. **Use Claude Code hooks**: Configure [sessionStart hooks](/en/hooks#sessionstart) to automate environment setup and dependency installation.5721. **Use Claude Code hooks**: Configure [SessionStart hooks](/en/hooks#sessionstart) to automate environment setup and dependency installation.

4772. **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.5732. **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.

478 574 

479## Related resources575## Related resources

1> ## Documentation Index

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

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

4 

1# CLI reference5# CLI reference

2 6 

3> Complete reference for Claude Code command-line interface, including commands and flags.7> Complete reference for Claude Code command-line interface, including commands and flags.

5## CLI commands9## CLI commands

6 10 

7| Command | Description | Example |11| Command | Description | Example |

8| :--------------------------------- | :--------------------------------------------- | :------------------------------------------------ |12| :------------------------------ | :----------------------------------------------------- | :------------------------------------------------ |

9| `claude` | Start interactive REPL | `claude` |13| `claude` | Start interactive REPL | `claude` |

10| `claude "query"` | Start REPL with initial prompt | `claude "explain this project"` |14| `claude "query"` | Start REPL with initial prompt | `claude "explain this project"` |

11| `claude -p "query"` | Query via SDK, then exit | `claude -p "explain this function"` |15| `claude -p "query"` | Query via SDK, then exit | `claude -p "explain this function"` |

12| `cat file \| claude -p "query"` | Process piped content | `cat logs.txt \| claude -p "explain"` |16| `cat file \| claude -p "query"` | Process piped content | `cat logs.txt \| claude -p "explain"` |

13| `claude -c` | Continue most recent conversation | `claude -c` |17| `claude -c` | Continue most recent conversation in current directory | `claude -c` |

14| `claude -c -p "query"` | Continue via SDK | `claude -c -p "Check for type errors"` |18| `claude -c -p "query"` | Continue via SDK | `claude -c -p "Check for type errors"` |

15| `claude -r "<session-id>" "query"` | Resume session by ID | `claude -r "abc123" "Finish this PR"` |19| `claude -r "<session>" "query"` | Resume session by ID or name | `claude -r "auth-refactor" "Finish this PR"` |

16| `claude update` | Update to latest version | `claude update` |20| `claude update` | Update to latest version | `claude update` |

17| `claude mcp` | Configure Model Context Protocol (MCP) servers | See the [Claude Code MCP documentation](/en/mcp). |21| `claude mcp` | Configure Model Context Protocol (MCP) servers | See the [Claude Code MCP documentation](/en/mcp). |

18 22 

21Customize Claude Code's behavior with these command-line flags:25Customize Claude Code's behavior with these command-line flags:

22 26 

23| Flag | Description | Example |27| Flag | Description | Example |

24| :------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------- |28| :------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------- |

25| `--add-dir` | Add additional working directories for Claude to access (validates each path exists as a directory) | `claude --add-dir ../apps ../lib` |29| `--add-dir` | Add additional working directories for Claude to access (validates each path exists as a directory) | `claude --add-dir ../apps ../lib` |

30| `--agent` | Specify an agent for the current session (overrides the `agent` setting) | `claude --agent my-custom-agent` |

26| `--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"}}'` |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"}}'` |

27| `--allowedTools` | A list of tools that should be allowed without prompting the user for permission, in addition to [settings.json files](/en/settings) | `"Bash(git log:*)" "Bash(git diff:*)" "Read"` |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` |

28| `--disallowedTools` | A list of tools that should be disallowed without prompting the user for permission, in addition to [settings.json files](/en/settings) | `"Bash(git log:*)" "Bash(git diff:*)" "Edit"` |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"` |

29| `--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"` |34| `--append-system-prompt` | Append custom text to the end of the default system prompt (works in both interactive and print modes) | `claude --append-system-prompt "Always use TypeScript"` |

30| `--system-prompt` | Replace the entire system prompt with custom text (works in both interactive and print modes; added in v2.0.14) | `claude --system-prompt "You are a Python expert"` |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"` |

31| `--system-prompt-file` | Load system prompt from a file, replacing the default prompt (print mode only; added in v1.0.54) | `claude -p --system-prompt-file ./custom-prompt.txt "query"` |36| `--betas` | Beta headers to include in API requests (API key users only) | `claude --betas interleaved-thinking` |

32| `--append-system-prompt` | Append custom text to the end of the default system prompt (works in both interactive and print modes; added in v1.0.55) | `claude --append-system-prompt "Always use TypeScript"` |37| `--chrome` | Enable [Chrome browser integration](/en/chrome) for web automation and testing | `claude --chrome` |

33| `--output-format` | Specify output format for print mode (options: `text`, `json`, `stream-json`) | `claude -p "query" --output-format json` |38| `--continue`, `-c` | Load the most recent conversation in the current directory | `claude --continue` |

39| `--dangerously-skip-permissions` | Skip all permission prompts (use with caution) | `claude --dangerously-skip-permissions` |

40| `--debug` | Enable debug mode with optional category filtering (for example, `"api,hooks"` or `"!statsig,!file"`) | `claude --debug "api,mcp"` |

41| `--disable-slash-commands` | Disable all skills and slash commands for this session | `claude --disable-slash-commands` |

42| `--disallowedTools` | Tools that are removed from the model's context and cannot be used | `"Bash(git log:*)" "Bash(git diff:*)" "Edit"` |

43| `--fallback-model` | Enable automatic fallback to specified model when default model is overloaded (print mode only) | `claude -p --fallback-model sonnet "query"` |

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

45| `--ide` | Automatically connect to IDE on startup if exactly one valid IDE is available | `claude --ide` |

46| `--init` | Run [Setup hooks](/en/hooks#setup) and start interactive mode | `claude --init` |

47| `--init-only` | Run [Setup hooks](/en/hooks#setup) and exit (no interactive session) | `claude --init-only` |

48| `--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"` |

34| `--input-format` | Specify input format for print mode (options: `text`, `stream-json`) | `claude -p --output-format json --input-format stream-json` |49| `--input-format` | Specify input format for print mode (options: `text`, `stream-json`) | `claude -p --output-format json --input-format stream-json` |

35| `--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"` |50| `--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"` |

36| `--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| `--maintenance` | Run [Setup hooks](/en/hooks#setup) with maintenance trigger and exit | `claude --maintenance` |

37| `--verbose` | Enable verbose logging, shows full turn-by-turn output (helpful for debugging in both print and interactive modes) | `claude --verbose` |52| `--max-budget-usd` | Maximum dollar amount to spend on API calls before stopping (print mode only) | `claude -p --max-budget-usd 5.00 "query"` |

38| `--max-turns` | Limit the number of agentic turns in non-interactive mode | `claude -p --max-turns 3 "query"` |53| `--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"` |

54| `--mcp-config` | Load MCP servers from JSON files or strings (space-separated) | `claude --mcp-config ./mcp.json` |

39| `--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` |55| `--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` |

56| `--no-chrome` | Disable [Chrome browser integration](/en/chrome) for this session | `claude --no-chrome` |

57| `--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"` |

58| `--output-format` | Specify output format for print mode (options: `text`, `json`, `stream-json`) | `claude -p "query" --output-format json` |

40| `--permission-mode` | Begin in a specified [permission mode](/en/iam#permission-modes) | `claude --permission-mode plan` |59| `--permission-mode` | Begin in a specified [permission mode](/en/iam#permission-modes) | `claude --permission-mode plan` |

41| `--permission-prompt-tool` | Specify an MCP tool to handle permission prompts in non-interactive mode | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |60| `--permission-prompt-tool` | Specify an MCP tool to handle permission prompts in non-interactive mode | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |

42| `--resume` | Resume a specific session by ID, or by choosing in interactive mode | `claude --resume abc123 "query"` |61| `--plugin-dir` | Load plugins from directories for this session only (repeatable) | `claude --plugin-dir ./my-plugins` |

43| `--continue` | Load the most recent conversation in the current directory | `claude --continue` |62| `--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"` |

44| `--dangerously-skip-permissions` | Skip permission prompts (use with caution) | `claude --dangerously-skip-permissions` |63| `--remote` | Create a new [web session](/en/claude-code-on-the-web) on claude.ai with the provided task description | `claude --remote "Fix the login bug"` |

64| `--resume`, `-r` | Resume a specific session by ID or name, or show an interactive picker to choose a session | `claude --resume auth-refactor` |

65| `--session-id` | Use a specific session ID for the conversation (must be a valid UUID) | `claude --session-id "550e8400-e29b-41d4-a716-446655440000"` |

66| `--setting-sources` | Comma-separated list of setting sources to load (`user`, `project`, `local`) | `claude --setting-sources user,project` |

67| `--settings` | Path to a settings JSON file or a JSON string to load additional settings from | `claude --settings ./settings.json` |

68| `--strict-mcp-config` | Only use MCP servers from `--mcp-config`, ignoring all other MCP configurations | `claude --strict-mcp-config --mcp-config ./mcp.json` |

69| `--system-prompt` | Replace the entire system prompt with custom text (works in both interactive and print modes) | `claude --system-prompt "You are a Python expert"` |

70| `--system-prompt-file` | Load system prompt from a file, replacing the default prompt (print mode only) | `claude -p --system-prompt-file ./custom-prompt.txt "query"` |

71| `--teleport` | Resume a [web session](/en/claude-code-on-the-web) in your local terminal | `claude --teleport` |

72| `--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"` |

73| `--verbose` | Enable verbose logging, shows full turn-by-turn output (helpful for debugging in both print and interactive modes) | `claude --verbose` |

74| `--version`, `-v` | Output the version number | `claude -v` |

45 75 

46<Tip>76<Tip>

47 The `--output-format json` flag is particularly useful for scripting and77 The `--output-format json` flag is particularly useful for scripting and

53The `--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:83The `--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:

54 84 

55| Field | Required | Description |85| Field | Required | Description |

56| :------------ | :------- | :-------------------------------------------------------------------------------------------------------------- |86| :------------ | :------- | :---------------------------------------------------------------------------------------------------------------------------------- |

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

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

59| `tools` | No | Array of specific tools the subagent can use (e.g., `["Read", "Edit", "Bash"]`). If omitted, inherits all tools |89| `tools` | No | Array of specific tools the subagent can use (for example, `["Read", "Edit", "Bash"]`). If omitted, inherits all tools |

60| `model` | No | Model alias to use: `sonnet`, `opus`, or `haiku`. If omitted, uses the default subagent model |90| `model` | No | Model alias to use: `sonnet`, `opus`, `haiku`, or `inherit`. If omitted, defaults to `inherit` (uses the main conversation's model) |

61 91 

62Example:92Example:

63 93 

80 110 

81### System prompt flags111### System prompt flags

82 112 

83Claude Code provides three flags for customizing the system prompt, each serving a different purpose:113Claude Code provides four flags for customizing the system prompt, each serving a different purpose:

84 114 

85| Flag | Behavior | Modes | Use Case |115| Flag | Behavior | Modes | Use Case |

86| :----------------------- | :--------------------------------- | :------------------ | :------------------------------------------------------------------- |116| :---------------------------- | :------------------------------------------ | :------------------ | :------------------------------------------------------------------- |

87| `--system-prompt` | **Replaces** entire default prompt | Interactive + Print | Complete control over Claude's behavior and instructions |117| `--system-prompt` | **Replaces** entire default prompt | Interactive + Print | Complete control over Claude's behavior and instructions |

88| `--system-prompt-file` | **Replaces** with file contents | Print only | Load prompts from files for reproducibility and version control |118| `--system-prompt-file` | **Replaces** with file contents | Print only | Load prompts from files for reproducibility and version control |

89| `--append-system-prompt` | **Appends** to default prompt | Interactive + Print | Add specific instructions while keeping default Claude Code behavior |119| `--append-system-prompt` | **Appends** to default prompt | Interactive + Print | Add specific instructions while keeping default Claude Code behavior |

120| `--append-system-prompt-file` | **Appends** file contents to default prompt | Print only | Load additional instructions from files while keeping defaults |

90 121 

91**When to use each:**122**When to use each:**

92 123 

105 claude --append-system-prompt "Always use TypeScript and include JSDoc comments"136 claude --append-system-prompt "Always use TypeScript and include JSDoc comments"

106 ```137 ```

107 138 

108<Note>139* **`--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.

109 `--system-prompt` and `--system-prompt-file` are mutually exclusive. You cannot use both flags simultaneously.140 ```bash theme={null}

110</Note>141 claude -p --append-system-prompt-file ./prompts/style-rules.txt "Review this PR"

142 ```

111 143 

112<Tip>144`--system-prompt` and `--system-prompt-file` are mutually exclusive. The append flags can be used together with either replacement flag.

113 For most use cases, `--append-system-prompt` is recommended as it preserves 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.

114</Tip>

115 145 

116For detailed information about print mode (`-p`) including output formats,146For 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.

117streaming, verbose logging, and programmatic usage, see the

118[SDK documentation](https://docs.claude.com/en/docs/agent-sdk).

119 147 

120## See also148## See also

121 149 

150* [Chrome extension](/en/chrome) - Browser automation and web testing

122* [Interactive mode](/en/interactive-mode) - Shortcuts, input modes, and interactive features151* [Interactive mode](/en/interactive-mode) - Shortcuts, input modes, and interactive features

123* [Slash commands](/en/slash-commands) - Interactive session commands

124* [Quickstart guide](/en/quickstart) - Getting started with Claude Code152* [Quickstart guide](/en/quickstart) - Getting started with Claude Code

125* [Common workflows](/en/common-workflows) - Advanced workflows and patterns153* [Common workflows](/en/common-workflows) - Advanced workflows and patterns

126* [Settings](/en/settings) - Configuration options154* [Settings](/en/settings) - Configuration options

1> ## Documentation Index

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

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

4 

1# Common workflows5# Common workflows

2 6 

3> Learn about common workflows with Claude Code.7> Step-by-step guides for exploring codebases, fixing bugs, refactoring, testing, and other everyday tasks with Claude Code.

4 8 

5Each task in this document includes clear instructions, example commands, and best practices to help you get the most from Claude Code.9This page covers practical workflows for everyday development: exploring unfamiliar code, debugging, refactoring, writing tests, creating PRs, and managing sessions. Each section includes example prompts you can adapt to your own projects. For higher-level patterns and tips, see [Best practices](/en/best-practices).

6 10 

7## Understand new codebases11## Understand new codebases

8 12 

81 85 

82 * Be specific about what you're looking for86 * Be specific about what you're looking for

83 * Use domain language from the project87 * Use domain language from the project

88 * Install a [code intelligence plugin](/en/discover-plugins#code-intelligence) for your language to give Claude precise "go to definition" and "find references" navigation

84</Tip>89</Tip>

85 90 

86***91***

173 </Step>178 </Step>

174 179 

175 <Step title="Use subagents automatically">180 <Step title="Use subagents automatically">

176 Claude Code will automatically delegate appropriate tasks to specialized subagents:181 Claude Code automatically delegates appropriate tasks to specialized subagents:

177 182 

178 ```183 ```

179 > review my recent code changes for security issues184 > review my recent code changes for security issues

201 206 

202 Then select "Create New subagent" and follow the prompts to define:207 Then select "Create New subagent" and follow the prompts to define:

203 208 

204 * Subagent type (e.g., `api-designer`, `performance-optimizer`)209 * A unique identifier that describes the subagent's purpose (for example, `code-reviewer`, `api-designer`).

205 * When to use it210 * When Claude should use this agent

206 * Which tools it can access211 * Which tools it can access

207 * Its specialized system prompt212 * A system prompt describing the agent's role and behavior

208 </Step>213 </Step>

209</Steps>214</Steps>

210 215 

221 226 

222## Use Plan Mode for safe code analysis227## Use Plan Mode for safe code analysis

223 228 

224Plan 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.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.

225 230 

226### When to use Plan Mode231### When to use Plan Mode

227 232 

235 240 

236You can switch into Plan Mode during a session using **Shift+Tab** to cycle through permission modes.241You can switch into Plan Mode during a session using **Shift+Tab** to cycle through permission modes.

237 242 

238If you are in Normal Mode, **Shift+Tab** will first switch into Auto-Accept Mode, indicated by `⏵⏵ accept edits on` at the bottom of the terminal. A subsequent **Shift+Tab** will switch into Plan Mode, indicated by `⏸ plan mode on`.243If you are in Normal Mode, **Shift+Tab** first switches into Auto-Accept Mode, indicated by `⏵⏵ accept edits on` at the bottom of the terminal. A subsequent **Shift+Tab** will switch into Plan Mode, indicated by `⏸ plan mode on`.

239 244 

240**Start a new session in Plan Mode**245**Start a new session in Plan Mode**

241 246 

247 252 

248**Run "headless" queries in Plan Mode**253**Run "headless" queries in Plan Mode**

249 254 

250You can also run a query in Plan Mode directly with `-p` (i.e., in ["headless mode"](/en/headless)):255You can also run a query in Plan Mode directly with `-p` (that is, in ["headless mode"](/en/headless)):

251 256 

252```bash theme={null}257```bash theme={null}

253claude --permission-mode plan -p "Analyze the authentication system and suggest improvements"258claude --permission-mode plan -p "Analyze the authentication system and suggest improvements"

263> I need to refactor our authentication system to use OAuth2. Create a detailed migration plan.268> I need to refactor our authentication system to use OAuth2. Create a detailed migration plan.

264```269```

265 270 

266Claude will analyze 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:

267 272 

268```273```

269> What about backward compatibility?274> What about backward compatibility?

270> How should we handle database migration?275> How should we handle database migration?

271```276```

272 277 

278<Tip>Press `Ctrl+G` to open the plan in your default text editor, where you can edit it directly before Claude proceeds.</Tip>

279 

273### Configure Plan Mode as default280### Configure Plan Mode as default

274 281 

275```json theme={null}282```json theme={null}

315 </Step>322 </Step>

316</Steps>323</Steps>

317 324 

318<Tip>325Claude can generate tests that follow your project's existing patterns and conventions. When asking for tests, be specific about what behavior you want to verify. Claude examines your existing test files to match the style, frameworks, and assertion patterns already in use.

319 Tips:

320 326 

321 * Ask for tests that cover edge cases and error conditions327For comprehensive coverage, ask Claude to identify edge cases you might have missed. Claude can analyze your code paths and suggest tests for error conditions, boundary values, and unexpected inputs that are easy to overlook.

322 * Request both unit and integration tests when appropriate

323 * Have Claude explain the testing strategy

324</Tip>

325 328 

326***329***

327 330 

336 ```339 ```

337 </Step>340 </Step>

338 341 

339 <Step title="Generate a PR with Claude">342 <Step title="Generate a pull request with Claude">

340 ```343 ```

341 > create a pr 344 > create a pr

342 ```345 ```

458 * Include screenshots of errors, UI designs, or diagrams for better context461 * Include screenshots of errors, UI designs, or diagrams for better context

459 * You can work with multiple images in a conversation462 * You can work with multiple images in a conversation

460 * Image analysis works with diagrams, screenshots, mockups, and more463 * Image analysis works with diagrams, screenshots, mockups, and more

464 * When Claude references images (for example, `[Image #1]`), `Cmd+Click` (Mac) or `Ctrl+Click` (Windows/Linux) the link to open the image in your default viewer

461</Tip>465</Tip>

462 466 

463***467***

496 Tips:500 Tips:

497 501 

498 * File paths can be relative or absolute502 * File paths can be relative or absolute

499 * @ file references add CLAUDE.md in the file's directory and parent directories to context503 * @ file references add `CLAUDE.md` in the file's directory and parent directories to context

500 * Directory references show file listings, not contents504 * Directory references show file listings, not contents

501 * You can reference multiple files in a single message (e.g., "@file1.js and @file2.js")505 * You can reference multiple files in a single message (for example, "@file1.js and @file2.js")

502</Tip>506</Tip>

503 507 

504***508***

505 509 

506## Use extended thinking510## Use extended thinking (thinking mode)

511 

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

507 513 

508Suppose you're working on complex architectural decisions, challenging bugs, or planning multi-step implementations that require deep reasoning.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.

509 515 

510<Note>516<Note>

511 [Extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) is disabled by default in Claude Code. You can enable it on-demand by using `Tab` to toggle Thinking on, or by using prompts like "think" or "think hard". You can also enable it permanently by setting the [`MAX_THINKING_TOKENS` environment variable](/en/settings#environment-variables) in your settings.517 Phrases like "think", "think hard", "ultrathink", and "think more" are interpreted as regular prompt instructions and don't allocate thinking tokens.

512</Note>518</Note>

513 519 

514<Steps>520### Configure thinking mode

515 <Step title="Provide context and ask Claude to think">

516 ```

517 > I need to implement a new authentication system using OAuth2 for our API. Think deeply about the best approach for implementing this in our codebase.

518 ```

519 521 

520 Claude will gather relevant information from your codebase and522Thinking is enabled by default, but you can adjust or disable it.

521 use extended thinking, which will be visible in the interface.

522 </Step>

523 523 

524 <Step title="Refine the thinking with follow-up prompts">524| Scope | How to configure | Details |

525 ```525| ---------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |

526 > think about potential security vulnerabilities in this approach 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 |

527 ```527| **Global default** | Use `/config` to toggle thinking mode | Sets your default across all projects.<br />Saved as `alwaysThinkingEnabled` in `~/.claude/settings.json` |

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

528 529 

529 ```530To view Claude's thinking process, press `Ctrl+O` to toggle verbose mode and see the internal reasoning displayed as gray italic text.

530 > think hard about edge cases we should handle

531 ```

532 </Step>

533</Steps>

534 531 

535<Tip>532### How extended thinking token budgets work

536 Tips to get the most value out of extended thinking:

537 533 

538 [Extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) is most valuable for complex tasks such as:534Extended thinking uses a **token budget** that controls how much internal reasoning Claude can perform before responding.

539 535 

540 * Planning complex architectural changes536A larger thinking token budget provides:

541 * Debugging intricate issues

542 * Creating implementation plans for new features

543 * Understanding complex codebases

544 * Evaluating tradeoffs between different approaches

545 537 

546 Use `Tab` to toggle Thinking on and off during a session.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

547 541 

548 The way you prompt for thinking results in varying levels of thinking depth:542Token budgets for thinking mode:

549 543 

550 * "think" triggers basic extended thinking544* When thinking is **enabled**, Claude can use up to **31,999 tokens** from your output budget for internal reasoning

551 * intensifying phrases such as "keep hard", "think more", "think a lot", or "think longer" triggers deeper thinking545* When thinking is **disabled** (via toggle or `/config`), Claude uses **0 tokens** for thinking

552 546 

553 For more extended thinking prompting tips, see [Extended thinking tips](https://docs.claude.com/en/docs/build-with-claude/prompt-engineering/extended-thinking-tips).547**Limit the thinking budget:**

554</Tip>

555 548 

556<Note>549* Use the [`MAX_THINKING_TOKENS` environment variable](/en/settings#environment-variables) to cap the thinking budget

557 Claude will display its thinking process as italic gray text above the550* When set, this value limits the maximum tokens Claude can use for thinking

558 response.551* See the [extended thinking documentation](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for valid token ranges

559</Note>552 

553<Warning>

554 You're charged for all thinking tokens used, even though Claude 4 models show summarized thinking