mirrors/claude-code-sandbox
1
0
Fork 0
mirror of https://github.com/textcortex/claude-code-sandbox.git synced 2025-08-04 10:59:28 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

First commit

Browse source
This commit is contained in:
Onur Solmaz 2025-05-26 00:05:29 +02:00
commit c33adb29ec
17 changed files with 2407 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

97
docs/2025-05-25-first-design.md Normal file
View file

@ -0,0 +1,97 @@
## Claude Sandbox Requirements Summary
### Core Concept
Claude-sandbox is a tool that runs Claude Code as an interactive agent inside Docker containers, providing a sandboxed environment for autonomous coding with git integration.
### Key Functional Requirements
#### 1. **Launch Behavior**
- Simple command: just type `claude-sandbox` in any git repository
- No pre-specified task - users interact with Claude directly after launch
- Claude Code runs as an interactive REPL (like a smart terminal)
- Maintains persistent context throughout the session (never exits)
#### 2. **Sandboxing**
- Runs inside Docker container for complete isolation
- Claude has full permissions to run any command (since it's sandboxed)
- No permission prompts - everything is auto-allowed
- Environment can be customized via Dockerfile configuration
#### 3. **Credential Management**
- Automatically discovers and forwards Claude credentials from host:
- Claude Max OAuth tokens
- Anthropic API keys
- AWS Bedrock credentials
- Automatically forwards GitHub credentials:
- GitHub CLI authentication
- SSH keys
- Git configuration
#### 4. **Git Workflow**
- Container automatically starts on a new branch (never on main)
- Branch naming: `claude/[timestamp]`
- Claude can make commits but cannot switch branches
- Git wrapper prevents branch switching operations
#### 5. **Change Detection & Review**
- Real-time monitoring for new commits
- When commit detected:
- User gets notification
- Can detach from Claude session
- Review full diffs with syntax highlighting
- See commit statistics
- Interactive review options:
- Do nothing (continue working)
- Push branch to remote
- Push branch and create PR
- Exit
#### 6. **Asynchronous Operation**
- Multiple containers can run simultaneously
- Each gets its own branch and isolated environment
- Fire-and-forget model for parallel work
### Technical Implementation Details
#### Docker Container Setup
- Base image with all necessary tools (git, gh CLI, build tools)
- Claude Code installed globally
- SSH configured for GitHub
- Auto-permission wrapper to bypass all prompts
#### Monitoring System
- Watches for file changes
- Detects git commits
- Tracks Claude's activity state
- Determines when tasks are complete
#### User Experience Flow
1. Run `claude-sandbox` in repo
2. System creates new branch
3. Docker container starts with Claude Code
4. User chats with Claude naturally
5. Claude works, makes changes, commits
6. User sees commit notifications
7. Can detach anytime to review changes
8. Choose to push/PR after review
### Design Principles
- **Zero configuration** - works out of the box
- **Natural interaction** - chat with Claude like normal
- **Full visibility** - see all changes before they leave the machine
- **Safe by default** - everything happens in isolated branches
- **Credential security** - read-only mounts, no credential exposure
This creates an experience where Claude Code becomes a powerful local development companion that can work autonomously while maintaining full user control over what gets pushed to the repository.
---
## Original Requirements
Look into Claude Code documentation. I want to be able to run it locally as an asynchronous agent inside Docker containers. So basically I will go into a repo, and then I just want to be able to fire off a command line tool. This command will automatically start a Docker container and fire off Claude code. The thing with Cohort code is it's the terminal utility/agent that can run commands, and the point of firing it in a Docker container is to provide a sandbox to it. The sandbox should automatically notice when Claude Code makes a change to the code. First, it should detect if Claude Code is finished with his job. And when it stops responding, and it detects that Claude code has made some line changes. It should push those changes to a new branch in the GitHub repo which it was started in. Since Claude code will be running inside a sandbox, it should be started with the mode which lets it run any command at once because it won't have access to the outside thing. So it should also be able to change the code however it likes or run any command that is available in the environment. Because it will stay inside the container and will not reach outside the container. The tool should furthermore have configuration like where the user is able to specify the environment setup possibly through a Dockerfile configuration or something like that. The basic function of this utility is to let you run fire off agents locally and work on them asynchronously, like OpenAI Codex or Google Jules. First of all, do some research on Claude Code, the most recent publishing and documentations on Anthropic website. Then, clean up this writing, make it concise and comprehensive, and outline how this thing could be implemented. You get the idea. If there are any missing points, fill in the gaps.
One thing, Claude shouldn't exit. If it exits, then the context is lost. There should be a way to figure out that it's done without making it quit. Also, this tool should automatically get the credential from the "outside" claude code is using (whether that is local bearer tokens to an account with claude max plan or an anthropic api key) and use it in the container. Also, it should be able to run all the tools/commands without permission, since this is a sandbox.
It should also get the outside github credential, to be able to push a new branch and create a new PR. In fact, the container should start with a new branch. Then, Claude Code should be able to make a commit (but not switch to a different branch. It has to stay in the current branch). As soon as a commit is made, the tool should detect it. The tool should then let the user review the diffs, line of diffs of the code. After reviewing, it should let the user do a) do nothing, b) push the branch, or c) push the branch and create a PR.
This tool should be called claude-sandbox. You should just be able to fire it without running a command. Claude code is like a very smart repl that just does stuff for you. So most people would directly type the command after claude starts, not in the terminal. Make sure your implementation matches the most recent claude code interface/api, allowed tools, etc. Look at the most recent documentation. Claude code github actions can be your reference: https://github.com/anthropics/claude-code-base-action https://github.com/anthropics/claude-code-action

180
docs/claude-code-docs/Bedrock, Vertex, and proxies.md Normal file
View file

@ -0,0 +1,180 @@
---
title: "Bedrock, Vertex, and proxies"
source: "https://docs.anthropic.com/en/docs/claude-code/bedrock-vertex-proxies"
author:
- "[[Anthropic]]"
published:
created: 2025-05-25
description: "Configure Claude Code to work with Amazon Bedrock and Google Vertex AI, and connect through proxies."
tags:
- "clippings"
---
## Model configuration
Claude Code uses the following defaults:
| Provider | Default Model |
| --- | --- |
| Anthropic Console | `claude-sonnet-4-20250514` |
| Claude Max | `claude-opus-4-20250514` or `claude-sonnet-4-20250514` based on Max usage limits |
| Amazon Bedrock | `claude-3-7-sonnet-20250219` |
| Google Vertex AI | `claude-sonnet-4-20250514` |
The default values can be overridden in several ways based on the following precedence from top to bottom:
- `--model` CLI flag. Applies within the session only.
- `ANTHROPIC_MODEL` environment variable. Applies within the session only.
- User Settings `~/.claude/settings.json`: Persists across sessions.
You can supply a full model name, the alias `sonnet` for the latest Claude Sonnet model for your provider, or the alias `opus` for the latest Claude Opus model for your provider.
See our [model names reference](https://docs.anthropic.com/en/docs/about-claude/models/all-models#model-names) for all available models across different providers.
## Use with third-party APIs
Claude Code requires access to both Claude Sonnet 3.7 and Claude Haiku 3.5 models, regardless of which API provider you use.
### Connect to Amazon Bedrock
```bash
CLAUDE_CODE_USE_BEDROCK=1
```
If you don’t have prompt caching enabled, also set:
```bash
DISABLE_PROMPT_CACHING=1
```
Contact Amazon Bedrock for prompt caching for reduced costs and higher rate limits.
Requires standard AWS SDK credentials (e.g., `~/.aws/credentials` or relevant environment variables like `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`). To set up AWS credentials, run:
If you’d like to access Claude Code via proxy, you can use the `ANTHROPIC_BEDROCK_BASE_URL` environment variable:
```bash
ANTHROPIC_BEDROCK_BASE_URL='https://your-proxy-url'
```
If your proxy maintains its own AWS credentials, you can use the `CLAUDE_CODE_SKIP_BEDROCK_AUTH` environment variable to remove Claude Code’s requirement for AWS credentials.
```bash
CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
```
Users will need access to both Claude Sonnet 3.7 and Claude Haiku 3.5 models in their AWS account. If you have a model access role, you may need to request access to these models if they’re not already available. Access to Bedrock in each region is necessary because inference profiles require cross-region capability.
### Connect to Google Vertex AI
If you don’t have prompt caching enabled, also set:
```bash
DISABLE_PROMPT_CACHING=1
```
Claude Code on Vertex AI currently only supports the `us-east5` region. Make sure your project has quota allocated in this specific region.
Users will need access to both Claude Sonnet 3.7 and Claude Haiku 3.5 models in their Vertex AI project.
Requires standard GCP credentials configured through google-auth-library. To set up GCP credentials, run:
If you’d like to access Claude Code via proxy, you can use the `ANTHROPIC_VERTEX_BASE_URL` environment variable:
```bash
ANTHROPIC_VERTEX_BASE_URL='https://your-proxy-url'
```
If your proxy maintains its own GCP credentials, you can use the `CLAUDE_CODE_SKIP_VERTEX_AUTH` environment variable to remove Claude Code’s requirement for GCP credentials.
```bash
CLAUDE_CODE_SKIP_VERTEX_AUTH=1
```
For the best experience, contact Google for heightened rate limits.
## Connect through a proxy
When using Claude Code with an LLM proxy, you can control authentication behavior using the following environment variables and configs. Note that you can mix and match these with Bedrock and Vertex-specific settings.
### Settings
Claude Code supports a number of settings controlled via environment variables to configure usage with Bedrock and Vertex. See [Environment variables](https://docs.anthropic.com/en/docs/claude-code/settings#environment-variables) for a complete reference.
If you prefer to configure via a file instead of environment variables, you can add any of these settings to the `env` object in your [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings#available-settings) files.
You can also configure the `apiKeyHelper` setting, to set a custom shell script to get an API key (invoked once at startup, and cached for the duration of each session, or until `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` elapses).
### LiteLLM
LiteLLM is a third-party proxy service. Anthropic doesn’t endorse, maintain, or audit LiteLLM’s security or functionality. This guide is provided for informational purposes and may become outdated. Use at your own discretion.
This section shows configuration of Claude Code with LiteLLM Proxy Server, a third-party LLM proxy which offers usage and spend tracking, centralized authentication, per-user budgeting, and more.
#### Step 1: Prerequisites
- Claude Code updated to the latest version
- LiteLLM Proxy Server running and network-accessible to Claude Code
- Your LiteLLM proxy key
#### Step 2: Set up proxy authentication
Choose one of these authentication methods:
**Option A: Static proxy key** Set your proxy key as an environment variable:
```bash
ANTHROPIC_AUTH_TOKEN=your-proxy-key
```
**Option B: Dynamic proxy key** If your organization uses rotating keys or dynamic authentication:
1. Do not set the `ANTHROPIC_AUTH_TOKEN` environment variable
2. Author a key helper script to provide authentication tokens
3. Register the script under `apiKeyHelper` configuration in your Claude Code settings
4. Set the token lifetime to enable automatic refresh:
```bash
CLAUDE_CODE_API_KEY_HELPER_TTL_MS=3600000
```
Set this to the lifetime (in milliseconds) of tokens returned by your `apiKeyHelper`.
#### Step 3: Configure your deployment
Choose which Claude deployment you want to use through LiteLLM:
- **Anthropic API**: Direct connection to Anthropic’s API
- **Bedrock**: Amazon Bedrock with Claude models
- **Vertex AI**: Google Cloud Vertex AI with Claude models
##### Option A: Anthropic API through LiteLLM
1. Configure the LiteLLM endpoint:
```bash
ANTHROPIC_BASE_URL=https://litellm-url:4000/anthropic
```
##### Option B: Bedrock through LiteLLM
1. Configure Bedrock settings:
##### Option C: Vertex AI through LiteLLM
**Recommended: Proxy-specified credentials**
1. Configure Vertex settings:
**Alternative: Client-specified credentials**
If you prefer to use local GCP credentials:
1. Authenticate with GCP locally:
2. Configure Vertex settings:
3. Update LiteLLM header configuration:
Ensure your LiteLLM config has `general_settings.litellm_key_header_name` set to `Proxy-Authorization`, since the pass-through GCP token will be located on the `Authorization` header.
#### Step 4. Selecting a model
By default, the models will use those specified in [Model configuration](https://docs.anthropic.com/en/docs/claude-code/bedrock-vertex-proxies#model-configuration).
If you have configured custom model names in LiteLLM, set the aforementioned environment variables to those custom names.
For more detailed information, refer to the [LiteLLM documentation](https://docs.litellm.ai/).

115
docs/claude-code-docs/CLI usage and controls.md Normal file
View file

@ -0,0 +1,115 @@
---
title: "CLI usage and controls"
source: "https://docs.anthropic.com/en/docs/claude-code/cli-usage"
author:
- "[[Anthropic]]"
published:
created: 2025-05-25
description: "Learn how to use Claude Code from the command line, including CLI commands, flags, and slash commands."
tags:
- "clippings"
---
## Getting started
Claude Code provides two main ways to interact:
- **Interactive mode**: Run `claude` to start a REPL session
- **One-shot mode**: Use `claude -p "query"` for quick commands
## CLI commands
| Command | Description | Example |
| --- | --- | --- |
| `claude` | Start interactive REPL | `claude` |
| `claude "query"` | Start REPL with initial prompt | `claude "explain this project"` |
| `claude -p "query"` | Run one-off query, then exit | `claude -p "explain this function"` |
| `cat file \| claude -p "query"` | Process piped content | `cat logs.txt \| claude -p "explain"` |
| `claude -c` | Continue most recent conversation | `claude -c` |
| `claude -c -p "query"` | Continue in print mode | `claude -c -p "Check for type errors"` |
| `claude -r "<session-id>" "query"` | Resume session by ID | `claude -r "abc123" "Finish this PR"` |
| `claude config` | Configure settings | `claude config set --global theme dark` |
| `claude update` | Update to latest version | `claude update` |
| `claude mcp` | Configure Model Context Protocol servers | [See MCP section in tutorials](https://docs.anthropic.com/en/docs/claude-code/tutorials#set-up-model-context-protocol-mcp) |
## CLI flags
Customize Claude Code’s behavior with these command-line flags:
| Flag | Description | Example |
| --- | --- | --- |
| `--print`, `-p` | Print response without interactive mode (see [SDK documentation](https://docs.anthropic.com/en/docs/claude-code/sdk) for programmatic usage details) | `claude -p "query"` |
| `--output-format` | Specify output format for print mode (options: `text`, `json`, `stream-json`) | `claude -p "query" --output-format json` |
| `--verbose` | Enable verbose logging, shows full turn-by-turn output (helpful for debugging in both print and interactive modes) | `claude --verbose` |
| `--max-turns` | Limit the number of agentic turns in non-interactive mode | `claude -p --max-turns 3 "query"` |
| `--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-20250514` |
| `--permission-prompt-tool` | Specify an MCP tool to handle permission prompts in non-interactive mode | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |
| `--resume` | Resume a specific session by ID, or by choosing in interactive mode | `claude --resume abc123 "query"` |
| `--continue` | Load the most recent conversation in the current directory | `claude --continue` |
| `--dangerously-skip-permissions` | Skip permission prompts (use with caution) | `claude --dangerously-skip-permissions` |
For detailed information about print mode (`-p`) including output formats, streaming, verbose logging, and programmatic usage, see the [SDK documentation](https://docs.anthropic.com/en/docs/claude-code/sdk).
## Slash commands
Control Claude’s behavior during an interactive session:
| Command | Purpose |
| --- | --- |
| `/bug` | Report bugs (sends conversation to Anthropic) |
| `/clear` | Clear conversation history |
| `/compact [instructions]` | Compact conversation with optional focus instructions |
| `/config` | View/modify configuration |
| `/cost` | Show token usage statistics |
| `/doctor` | Checks the health of your Claude Code installation |
| `/help` | Get usage help |
| `/init` | Initialize project with CLAUDE.md guide |
| `/login` | Switch Anthropic accounts |
| `/logout` | Sign out from your Anthropic account |
| `/memory` | Edit CLAUDE.md memory files |
| `/model` | Select or change the AI model |
| `/pr_comments` | View pull request comments |
| `/review` | Request code review |
| `/status` | View account and system statuses |
| `/terminal-setup` | Install Shift+Enter key binding for newlines (iTerm2 and VSCode only) |
| `/vim` | Enter vim mode for alternating insert and command modes |
## Special shortcuts
### Quick memory with #
Add memories instantly by starting your input with `#`:
You’ll be prompted to select which memory file to store this in.
### Line breaks in terminal
Enter multiline commands using:
- **Quick escape**: Type `\` followed by Enter
- **Keyboard shortcut**: Option+Enter (or Shift+Enter if configured)
To set up Option+Enter in your terminal:
**For Mac Terminal.app:**
1. Open Settings → Profiles → Keyboard
2. Check “Use Option as Meta Key”
**For iTerm2 and VSCode terminal:**
1. Open Settings → Profiles → Keys
2. Under General, set Left/Right Option key to “Esc+”
**Tip for iTerm2 and VSCode users**: Run `/terminal-setup` within Claude Code to automatically configure Shift+Enter as a more intuitive alternative.
See [terminal setup in settings](https://docs.anthropic.com/en/docs/claude-code/settings#line-breaks) for configuration details.
## Vim Mode
Claude Code supports a subset of Vim keybindings that can be enabled with `/vim` or configured via `/config`.
The supported subset includes:
- Mode switching: `Esc` (to NORMAL), `i` / `I`, `a` / `A`, `o` / `O` (to INSERT)
- Navigation: `h` / `j` / `k` / `l`, `w` / `e` / `b`, `0` / `$` / `^`, `gg` / `G`
- Editing: `x`, `dw` / `de` / `db` / `dd` / `D`, `cw` / `ce` / `cb` / `cc` / `C`, `.` (repeat)

108
docs/claude-code-docs/Claude Code overview.md Normal file
View file

@ -0,0 +1,108 @@
---
title: "Claude Code overview"
source: "https://docs.anthropic.com/en/docs/claude-code/overview"
author:
- "[[Anthropic]]"
published:
created: 2025-05-25
description: "Learn about Claude Code, an agentic coding tool made by Anthropic."
tags:
- "clippings"
---
Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster through natural language commands. By integrating directly with your development environment, Claude Code streamlines your workflow without requiring additional servers or complex setup.
Claude Code’s key capabilities include:
- Editing files and fixing bugs across your codebase
- Answering questions about your code’s architecture and logic
- Executing and fixing tests, linting, and other commands
- Searching through git history, resolving merge conflicts, and creating commits and PRs
- Browsing documentation and resources from the internet using web search
- Works with [Amazon Bedrock and Google Vertex AI](https://docs.anthropic.com/en/docs/claude-code/bedrock-vertex-proxies) for enterprise deployments
## Why Claude Code?
Claude Code operates directly in your terminal, understanding your project context and taking real actions. No need to manually add files to context - Claude will explore your codebase as needed.
### Enterprise integration
Claude Code seamlessly integrates with enterprise AI platforms. You can connect to [Amazon Bedrock or Google Vertex AI](https://docs.anthropic.com/en/docs/claude-code/bedrock-vertex-proxies) for secure, compliant deployments that meet your organization’s requirements.
### Security and privacy by design
Your code’s security is paramount. Claude Code’s architecture ensures:
- **Direct API connection**: Your queries go straight to Anthropic’s API without intermediate servers
- **Works where you work**: Operates directly in your terminal
- **Understands context**: Maintains awareness of your entire project structure
- **Takes action**: Performs real operations like editing files and creating commits
## Getting started
To get started with Claude Code, follow our [installation guide](https://docs.anthropic.com/en/docs/claude-code/getting-started) which covers system requirements, installation steps, and authentication process.
## Quick tour
Here’s what you can accomplish with Claude Code:
### From questions to solutions in seconds
### Understand unfamiliar code
### Automate Git operations## [Getting started](https://docs.anthropic.com/en/docs/claude-code/getting-started)
[
Install Claude Code and get up and running
](https://docs.anthropic.com/en/docs/claude-code/getting-started)Core features
Explore what Claude Code can do for you
[View original](https://docs.anthropic.com/en/docs/claude-code/common-tasks)Commands
Learn about CLI commands and controls
[View original](https://docs.anthropic.com/en/docs/claude-code/cli-usage)Configuration
Customize Claude Code for your workflow
[View original](https://docs.anthropic.com/en/docs/claude-code/settings)
## Additional resources## [Claude Code tutorials](https://docs.anthropic.com/en/docs/claude-code/tutorials)
[
Step-by-step guides for common tasks
](https://docs.anthropic.com/en/docs/claude-code/tutorials)Troubleshooting
Solutions for common issues with Claude Code
[View original](https://docs.anthropic.com/en/docs/claude-code/troubleshooting)Bedrock & Vertex integrations
Configure Claude Code with Amazon Bedrock or Google Vertex AI
[View original](https://docs.anthropic.com/en/docs/claude-code/bedrock-vertex-proxies)Reference implementation
Clone our development container reference implementation.
[View original](https://github.com/anthropics/claude-code/tree/main/.devcontainer)
Claude Code is provided under Anthropic’s [Commercial Terms of Service](https://www.anthropic.com/legal/commercial-terms).
### How we use your data
We aim to be fully transparent about how we use your data. We may use feedback to improve our products and services, but we will not train generative models using your feedback from Claude Code. Given their potentially sensitive nature, we store user feedback transcripts for only 30 days.
If you choose to send us feedback about Claude Code, such as transcripts of your usage, Anthropic may use that feedback to debug related issues and improve Claude Code’s functionality (e.g., to reduce the risk of similar bugs occurring in the future). We will not train generative models using this feedback.
### Privacy safeguards
We have implemented several safeguards to protect your data, including limited retention periods for sensitive information, restricted access to user session data, and clear policies against using feedback for model training.
For full details, please review our [Commercial Terms of Service](https://www.anthropic.com/legal/commercial-terms) and [Privacy Policy](https://www.anthropic.com/legal/privacy).
### License
© Anthropic PBC. All rights reserved. Use is subject to Anthropic’s [Commercial Terms of Service](https://www.anthropic.com/legal/commercial-terms).

248
docs/claude-code-docs/Claude Code settings.md Normal file
View file

@ -0,0 +1,248 @@
---
title: "Claude Code settings"
source: "https://docs.anthropic.com/en/docs/claude-code/settings"
author:
- "[[Anthropic]]"
published:
created: 2025-05-25
description: "Learn how to configure Claude Code with global and project-level settings, themes, and environment variables."
tags:
- "clippings"
---
Claude Code offers a variety of settings to configure its behavior to meet your needs. You can configure Claude Code by running `claude config` in your terminal, or the `/config` command when using the interactive REPL.
## Configuration hierarchy
The new `settings.json` file is our official mechanism for configuring Claude Code through hierarchical settings:
- **User settings** are defined in `~/.claude/settings.json` and apply to all projects.
- **Project settings** are saved in your project directory under`.claude/settings.json` for shared settings, and `.claude/settings.local.json` for local project settings. Claude Code will configure git to ignore`.claude/settings.local.json` when it is created.
- For enterprise deployments of Claude Code, we also support **enterprise managed policy settings**. These take precedence over user and project settings. System administrators can deploy policies to `/Library/Application Support/ClaudeCode/policies.json` on macOS and `/etc/claude-code/policies.json` on Linux and Windows via WSL.
Example settings.json
### Available settings
`settings.json` supports a number of options:
| Key | Description | Example |
| --- | --- | --- |
| `apiKeyHelper` | Custom script to generate an Anthropic API key | `/bin/generate_temp_api_key.sh` |
| `cleanupPeriodDays` | How long to locally retain chat transcripts (default: 30 days) | `20` |
| `env` | Environment variables that will be applied to every session | `{"FOO": "bar"}` |
| `includeCoAuthoredBy` | Whether to include the `co-authored-by Claude` byline in git commits and pull requests (default: `true`) | `false` |
### Settings precedence
Settings are applied in order of precedence:
1. Enterprise policies
2. Command line arguments
3. Local project settings
4. Shared project settings
5. User settings
## Configuration options
Claude Code supports global and project-level configuration.
To manage your configurations, use the following commands:
- List settings: `claude config list`
- See a setting: `claude config get <key>`
- Change a setting: `claude config set <key> <value>`
- Push to a setting (for lists): `claude config add <key> <value>`
- Remove from a setting (for lists): `claude config remove <key> <value>`
By default `config` changes your project configuration. To manage your global configuration, use the `--global` (or `-g`) flag.
### Global configuration
To set a global configuration, use `claude config set -g <key> <value>`:
| Key | Description | Example |
| --- | --- | --- |
| `autoUpdaterStatus` | Enable or disable the auto-updater (default: `enabled`) | `disabled` |
| `preferredNotifChannel` | Where you want to receive notifications (default: `iterm2`) | `iterm2`, `iterm2_with_bell`, `terminal_bell`, or `notifications_disabled` |
| `theme` | Color theme | `dark`, `light`, `light-daltonized`, or `dark-daltonized` |
| `verbose` | Whether to show full bash and command outputs (default: `false`) | `true` |
We are in the process of migration global configuration to `settings.json`.
## Permissions
You can manage Claude Code’s tool permissions with `/allowed-tools`. This UI lists all permission rules and the settings.json file they are sourced from.
- **Allow** rules will allow Claude Code to use the specified tool without further manual approval.
- **Deny** rules will prevent Claude Code from using the specified tool. Deny rules take precedence over allow rules.
Permission rules use the format: `Tool(optional-specifier)`.
For example, adding `WebFetch` to the list of allow rules would allow any use of the web fetch tool without requiring user approval. See the list of [tools available to Claude](https://docs.anthropic.com/en/docs/claude-code/security#tools-available-to-claude) (use the name in parentheses when provided.)
Some tools use the optional specifier for more fine-grained permission controls. For example, an allow rule with `WebFetch(domain:example.com)` would allow fetches to example.com but not other URLs.
Bash rules can be exact matches like `Bash(npm run build)`, or prefix matches when they end with `:*` like `Bash(npm run test:*)`
`Read()` and `Edit()` rules follow the [gitignore](https://git-scm.com/docs/gitignore) specification. Patterns are resolved relative to the directory containing `.claude/settings.json`. To reference an absolute path, use `//`. For a path relative to your home directory, use `~/`. For example `Read(//tmp/build_cache)` or `Edit(~/.zshrc)`. Claude will also make a best-effort attempt to apply Read and Edit rules to other file-related tools like Grep, Glob, and LS.
MCP tool names follow the format: `mcp__server_name__tool_name` where:
- `server_name` is the name of the MCP server as configured in Claude Code
- `tool_name` is the specific tool provided by that server
More examples:
| Rule | Description |
| --- | --- |
| `Bash(npm run build)` | Matches the exact Bash command `npm run build`. |
| `Bash(npm run test:*)` | Matches Bash commands starting with `npm run test`. See note below about command separator handling. |
| `Edit(~/.zshrc)` | Matches the `~/.zshrc` file. |
| `Read(node_modules/**)` | Matches any `node_modules` directory. |
| `mcp__puppeteer__puppeteer_navigate` | Matches the `puppeteer_navigate` tool from the `puppeteer` MCP server. |
| `WebFetch(domain:example.com)` | Matches fetch requests to example.com |
Claude Code is aware of command separators (like `&&`) so a prefix match rule like `Bash(safe-cmd:*)` won’t give it permission to run the command `safe-cmd && other-cmd`
When Claude Code detects that it doesn’t have sufficient permissions to write to your global npm prefix directory (required for automatic updates), you’ll see a warning that points to this documentation page. For detailed solutions to auto-updater issues, see the [troubleshooting guide](https://docs.anthropic.com/en/docs/claude-code/troubleshooting#auto-updater-issues).
```bash
# First, save a list of your existing global packages for later migration
npm list -g --depth=0 > ~/npm-global-packages.txt
# Create a directory for your global packages
mkdir -p ~/.npm-global
# Configure npm to use the new directory path
npm config set prefix ~/.npm-global
# Note: Replace ~/.bashrc with ~/.zshrc, ~/.profile, or other appropriate file for your shell
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
# Apply the new PATH setting
source ~/.bashrc
# Now reinstall Claude Code in the new location
npm install -g @anthropic-ai/claude-code
# Optional: Reinstall your previous global packages in the new location
# Look at ~/npm-global-packages.txt and install packages you want to keep
# npm install -g package1 package2 package3...
```
**Why we recommend this option:**
- Avoids modifying system directory permissions
- Creates a clean, dedicated location for your global npm packages
- Follows security best practices
Since Claude Code is actively developing, we recommend setting up auto-updates using the recommended option above.
### Disabling the auto-updater
If you prefer to disable the auto-updater instead of fixing permissions, you can use:
## Optimize your terminal setup
Claude Code works best when your terminal is properly configured. Follow these guidelines to optimize your experience.
**Supported shells**:
- Bash
- Zsh
- Fish
### Themes and appearance
Claude cannot control the theme of your terminal. That’s handled by your terminal application. You can match Claude Code’s theme to your terminal during onboarding or any time via the `/config` command
### Line breaks
You have several options for entering linebreaks into Claude Code:
- **Quick escape**: Type `\` followed by Enter to create a newline
- **Keyboard shortcut**: Press Option+Enter (Meta+Enter) with proper configuration
To set up Option+Enter in your terminal:
**For Mac Terminal.app:**
1. Open Settings → Profiles → Keyboard
2. Check “Use Option as Meta Key”
**For iTerm2 and VSCode terminal:**
1. Open Settings → Profiles → Keys
2. Under General, set Left/Right Option key to “Esc+”
**Tip for iTerm2 and VSCode users**: Run `/terminal-setup` within Claude Code to automatically configure Shift+Enter as a more intuitive alternative.
### Notification setup
Never miss when Claude completes a task with proper notification configuration:
#### Terminal bell notifications
Enable sound alerts when tasks complete:
**For macOS users**: Don’t forget to enable notification permissions in System Settings → Notifications → \[Your Terminal App\].
#### iTerm 2 system notifications
For iTerm 2 alerts when tasks complete:
1. Open iTerm 2 Preferences
2. Navigate to Profiles → Terminal
3. Enable “Silence bell” and Filter Alerts → “Send escape sequence-generated alerts”
4. Set your preferred notification delay
Note that these notifications are specific to iTerm 2 and not available in the default macOS Terminal.
### Handling large inputs
When working with extensive code or long instructions:
- **Avoid direct pasting**: Claude Code may struggle with very long pasted content
- **Use file-based workflows**: Write content to a file and ask Claude to read it
- **Be aware of VS Code limitations**: The VS Code terminal is particularly prone to truncating long pastes
### Vim Mode
Claude Code supports a subset of Vim keybindings that can be enabled with `/vim` or configured via `/config`.
The supported subset includes:
- Mode switching: `Esc` (to NORMAL), `i` / `I`, `a` / `A`, `o` / `O` (to INSERT)
- Navigation: `h` / `j` / `k` / `l`, `w` / `e` / `b`, `0` / `$` / `^`, `gg` / `G`
- Editing: `x`, `dw` / `de` / `db` / `dd` / `D`, `cw` / `ce` / `cb` / `cc` / `C`, `.` (repeat)
## Environment variables
Claude Code supports the following environment variables to control its behavior:
All environment variables can also be configured in [`settings.json`](https://docs.anthropic.com/en/docs/claude-code/settings#available-settings). This is useful as a way to automatically set environment variables for each session, or to roll out a set of environment variables for your whole team or organization.
| Variable | Purpose |
| --- | --- |
| `ANTHROPIC_AUTH_TOKEN` | Custom value for the `Authorization` and `Proxy-Authorization` headers (the value you set here will be prefixed with `Bearer `) |
| `ANTHROPIC_CUSTOM_HEADERS` | Custom headers you want to add to the request (in `Name: Value` format) |
| `ANTHROPIC_MODEL` | Name of custom model to use (see [Model Configuration](https://docs.anthropic.com/en/docs/claude-code/bedrock-vertex-proxies#model-configuration)) |
| `ANTHROPIC_SMALL_FAST_MODEL` | Name of [Haiku-class model for background tasks](https://docs.anthropic.com/en/docs/claude-code/costs) |
| `BASH_DEFAULT_TIMEOUT_MS` | Default timeout for long-running bash commands |
| `BASH_MAX_TIMEOUT_MS` | Maximum timeout the model can set for long-running bash commands |
| `BASH_MAX_OUTPUT_LENGTH` | Maximum number of characters in bash outputs before they are middle-truncated |
| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` | Interval at which credentials should be refreshed (when using `apiKeyHelper`) |
| `CLAUDE_CODE_USE_BEDROCK` | Use Bedrock (see [Bedrock & Vertex](https://docs.anthropic.com/en/docs/claude-code/bedrock-vertex-proxies)) |
| `CLAUDE_CODE_USE_VERTEX` | Use Vertex (see [Bedrock & Vertex](https://docs.anthropic.com/en/docs/claude-code/bedrock-vertex-proxies)) |
| `CLAUDE_CODE_SKIP_VERTEX_AUTH` | Skip Google authentication for Vertex (eg. when using a proxy) |
| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | Equivalent of setting `DISABLE_AUTOUPDATER`, `DISABLE_BUG_COMMAND`, `DISABLE_ERROR_REPORTING`, and `DISABLE_TELEMETRY` |
| `DISABLE_AUTOUPDATER` | Set to `1` to disable the automatic updater |
| `DISABLE_BUG_COMMAND` | Set to `1` to disable the `/bug` command |
| `DISABLE_COST_WARNINGS` | Set to `1` to disable cost warning messages |
| `DISABLE_ERROR_REPORTING` | Set to `1` to opt out of Sentry error reporting |
| `DISABLE_TELEMETRY` | Set to `1` to opt out of Statsig telemetry (note that Statsig events do not include user data like code, file paths, or bash commands) |
| `HTTP_PROXY` | Specify HTTP proxy server for network connections |
| `HTTPS_PROXY` | Specify HTTPS proxy server for network connections |
| `MAX_THINKING_TOKENS` | Force a thinking for the model budget |
| `MCP_TIMEOUT` | Timeout in milliseconds for MCP server startup |
| `MCP_TOOL_TIMEOUT` | Timeout in milliseconds for MCP tool execution |

38
docs/claude-code-docs/Core tasks and workflows.md Normal file
View file

@ -0,0 +1,38 @@
---
title: "Core tasks and workflows"
source: "https://docs.anthropic.com/en/docs/claude-code/common-tasks"
author:
- "[[Anthropic]]"
published:
created: 2025-05-25
description: "Explore Claude Code's powerful features for editing, searching, testing, and automating your development workflow."
tags:
- "clippings"
---
Claude Code operates directly in your terminal, understanding your project context and taking real actions. No need to manually add files to context - Claude will explore your codebase as needed.
## Understand unfamiliar code
## Automate Git operations
## Edit code intelligently
## Test and debug your code
## Encourage deeper thinking
For complex problems, explicitly ask Claude to think more deeply:
Claude Code will show when the model is using extended thinking. You can proactively prompt Claude to “think” or “think deeply” for more planning-intensive tasks. We suggest that you first tell Claude about your task and let it gather context from your project. Then, ask it to “think” to create a plan.
Claude will think more based on the words you use. For example, “think hard” will trigger more extended thinking than saying “think” alone.
For more tips, see [Extended thinking tips](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/extended-thinking-tips).
## Automate CI and infra workflows
Claude Code comes with a non-interactive mode for headless execution. This is especially useful for running Claude Code in non-interactive contexts like scripts, pipelines, and Github Actions.
Use `--print` (`-p`) to run Claude in non-interactive mode. In this mode, you can set the `ANTHROPIC_API_KEY` environment variable to provide a custom API key.
Non-interactive mode is especially useful when you pre-configure the set of commands Claude is allowed to use:

39
docs/claude-code-docs/Getting started with Claude Code.md Normal file
View file

@ -0,0 +1,39 @@
---
title: "Getting started with Claude Code"
source: "https://docs.anthropic.com/en/docs/claude-code/getting-started"
author:
- "[[Anthropic]]"
published:
created: 2025-05-25
description: "Learn how to install, authenticate, and start using Claude Code."
tags:
- "clippings"
---
## Check system requirements
- **Operating Systems**: macOS 10.15+, Ubuntu 20.04+/Debian 10+, or Windows via WSL
- **Hardware**: 4GB RAM minimum
- **Software**:
- Node.js 18+
- [git](https://git-scm.com/downloads) 2.23+ (optional)
- [GitHub](https://cli.github.com/) or [GitLab](https://gitlab.com/gitlab-org/cli) CLI for PR workflows (optional)
- [ripgrep](https://github.com/BurntSushi/ripgrep?tab=readme-ov-file#installation) (rg) for enhanced file search (optional)
- **Network**: Internet connection required for authentication and AI processing
- **Location**: Available only in [supported countries](https://www.anthropic.com/supported-countries)
**Troubleshooting WSL installation**
Currently, Claude Code does not run directly in Windows, and instead requires WSL. If you encounter issues in WSL:
1. **OS/platform detection issues**: If you receive an error during installation, WSL may be using Windows `npm`. Try:
- Run `npm config set os linux` before installation
- Install with `npm install -g @anthropic-ai/claude-code --force --no-os-check` (Do NOT use `sudo`)
2. **Node not found errors**: If you see `exec: node: not found` when running `claude`, your WSL environment may be using a Windows installation of Node.js. You can confirm this with `which npm` and `which node`, which should point to Linux paths starting with `/usr/` rather than `/mnt/c/`. To fix this, try installing Node via your Linux distribution’s package manager or via [`nvm`](https://github.com/nvm-sh/nvm).
## Install and authenticate
## Initialize your project
For first-time users, we recommend:
Getting started with Claude Code - Anthropic

288
docs/claude-code-docs/GitHub Actions.md Normal file
View file

@ -0,0 +1,288 @@
---
title: "GitHub Actions"
source: "https://docs.anthropic.com/en/docs/claude-code/github-actions"
author:
- "[[Anthropic]]"
published:
created: 2025-05-26
description: "Integrate Claude Code with your GitHub workflows for automated code review, PR management, and issue triage."
tags:
- "clippings"
---
Claude Code GitHub Actions brings AI-powered automation to your GitHub workflow. With a simple `@claude` mention in any PR or issue, Claude can analyze your code, create pull requests, implement features, and fix bugs - all while following your project’s standards.
Claude Code GitHub Actions is currently in beta. Features and functionality may evolve as we refine the experience.
Claude Code GitHub Actions is built on top of the [Claude Code SDK](https://docs.anthropic.com/en/docs/claude-code/sdk), which enables programmatic integration of Claude Code into your applications. You can use the SDK to build custom automation workflows beyond GitHub Actions.
## Why use Claude Code GitHub Actions?
- **Instant PR creation**: Describe what you need, and Claude creates a complete PR with all necessary changes
- **Automated code implementation**: Turn issues into working code with a single command
- **Follows your standards**: Claude respects your `CLAUDE.md` guidelines and existing code patterns
- **Simple setup**: Get started in minutes with our installer and API key
- **Secure by default**: Your code stays on Github’s runners
## What can Claude do?
Claude Code provides powerful GitHub Actions that transform how you work with code:
### Claude Code Action
This GitHub Action allows you to run Claude Code within your GitHub Actions workflows. You can use this to build any custom workflow on top of Claude Code.
[View repository →](https://github.com/anthropics/claude-code-action)
### Claude Code Action (Base)
The foundation for building custom GitHub workflows with Claude. This extensible framework gives you full access to Claude’s capabilities for creating tailored automation.
[View repository →](https://github.com/anthropics/claude-code-base-action)
## Quick start
The easiest way to set up this action is through Claude Code in the terminal. Just open claude and run `/install-github-app`.
This command will guide you through setting up the GitHub app and required secrets.
- You must be a repository admin to install the GitHub app and add secrets
- This quickstart method is only available for direct Anthropic API users. If you’re using AWS Bedrock or Google Vertex AI, please see the [Using with AWS Bedrock & Google Vertex AI](https://docs.anthropic.com/en/docs/claude-code/github-actions#using-with-aws-bedrock-%26-google-vertex-ai) section.
### If the setup script fails
If the `/install-github-app` command fails or you prefer manual setup, please follow these manual setup instructions:
1. **Install the Claude GitHub app** to your repository: [https://github.com/apps/claude](https://github.com/apps/claude)
2. **Add ANTHROPIC\_API\_KEY** to your repository secrets ([Learn how to use secrets in GitHub Actions](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions))
3. **Copy the workflow file** from [examples/claude.yml](https://github.com/anthropics/claude-code-action/blob/main/examples/claude.yml) into your repository’s `.github/workflows/`
## Example use cases
Claude Code GitHub Actions can help you with a variety of tasks, including:
### Turn issues into PRs
Claude will analyze the issue, write the code, and create a PR for review.
### Get implementation help
Claude will analyze your code and provide specific implementation guidance.
### Fix bugs quickly
Claude will locate the bug, implement a fix, and create a PR.
## Best practices
### CLAUDE.md configuration
Create a `CLAUDE.md` file in your repository root to define code style guidelines, review criteria, project-specific rules, and preferred patterns. This file guides Claude’s understanding of your project standards.
### Security considerations
**⚠️ IMPORTANT: Never commit API keys directly to your repository!**
Always use GitHub Secrets for API keys:
- Add your API key as a repository secret named `ANTHROPIC_API_KEY`
- Reference it in workflows: `anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}`
- Limit action permissions to only what’s necessary
- Review Claude’s suggestions before merging
**Use explicit tools for better security:**
When configuring `allowed_tools`, avoid wildcard patterns and instead explicitly list the specific commands Claude can use:
This approach ensures Claude can only execute the specific commands you’ve authorized, reducing potential security risks.
### Optimizing performance
Use issue templates to provide context, keep your `CLAUDE.md` concise and focused, and configure appropriate timeouts for your workflows.
### CI costs
When using Claude Code GitHub Actions, be aware of the associated costs:
**GitHub Actions costs:**
- Claude Code runs on GitHub-hosted runners, which consume your GitHub Actions minutes
- See [GitHub’s billing documentation](https://docs.github.com/en/billing/managing-billing-for-your-products/managing-billing-for-github-actions/about-billing-for-github-actions) for detailed pricing and minute limits
**API costs:**
- Each Claude interaction consumes API tokens based on the length of prompts and responses
- Token usage varies by task complexity and codebase size
- See [Claude’s pricing page](https://www.anthropic.com/api) for current token rates
**Cost optimization tips:**
- Use specific `@claude` commands to reduce unnecessary API calls
- Configure appropriate `max_turns` limits to prevent excessive iterations
- Set reasonable `timeout_minutes` to avoid runaway workflows
- Consider using GitHub’s concurrency controls to limit parallel runs
## Configuration examples
This section provides ready-to-use workflow configurations for different use cases:
- [Basic workflow setup](https://docs.anthropic.com/en/docs/claude-code/github-actions#basic-workflow-setup) - The default configuration for issue and PR comments
- [Code review on pull requests](https://docs.anthropic.com/en/docs/claude-code/github-actions#code-review-on-pull-requests) - Automated code reviews on new PRs
### Basic workflow setup
This is the default workflow created by the installer. It enables Claude to respond to `@claude` mentions in issues and PR comments:
```yaml
name: Claude PR Creation
on:
issue_comment:
types: [created] # Triggers when someone comments on an issue or PR
jobs:
create-pr:
# Only run if the comment mentions @claude
if: contains(github.event.comment.body, '@claude')
runs-on: ubuntu-latest
steps:
- uses: anthropics/claude-code-action@beta
with:
# Pass the comment text as the prompt
prompt: "${{ github.event.comment.body }}"
# Define which tools Claude can use
allowed_tools: [
# Git inspection commands (read-only)
"Bash(git status)",
"Bash(git log)",
"Bash(git show)",
"Bash(git blame)",
"Bash(git reflog)",
"Bash(git stash list)",
"Bash(git ls-files)",
"Bash(git branch)",
"Bash(git tag)",
"Bash(git diff)",
# File exploration tools
"View", # Read file contents
"GlobTool", # Find files by pattern
"GrepTool", # Search file contents
"BatchTool" # Run multiple tools in parallel
]
# Your Anthropic API key (stored as a GitHub secret)
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
```
### Code review on pull requests
This workflow automatically reviews code changes when a PR is opened or updated:
```yaml
name: Claude Code Review
on:
pull_request:
types: [opened, synchronize] # Runs on new PRs and updates
jobs:
code-review:
runs-on: ubuntu-latest
steps:
# Check out the code to allow git diff operations
- name: Checkout code
uses: actions/checkout@v4
with:
fetch-depth: 0 # Fetch full history for accurate diffs
- name: Run Code Review with Claude
id: code-review
uses: anthropics/claude-code-action@beta
with:
# Define the review focus areas
prompt: "Review the PR changes. Focus on code quality, potential bugs, and performance issues. Suggest improvements where appropriate."
# Limited tools for safer review operations
allowed_tools: [
"Bash(git diff --name-only HEAD~1)", # List changed files
"Bash(git diff HEAD~1)", # See actual changes
"View", # Read file contents
"GlobTool", # Find related files
"GrepTool" # Search for patterns
]
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
```
For more focused reviews, customize the prompt to check specific aspects like security, performance, or compliance with your coding standards.
## Using with AWS Bedrock & Google Vertex AI
For enterprise environments, you can use Claude Code GitHub Actions with your own cloud infrastructure. This approach gives you control over data residency and billing while maintaining the same functionality.
### Prerequisites
Before setting up Claude Code GitHub Actions with cloud providers, you need:
#### For Google Cloud Vertex AI:
1. A Google Cloud Project with Vertex AI enabled
2. Workload Identity Federation configured for GitHub Actions
3. A service account with the required permissions
4. A GitHub App (recommended) or use the default GITHUB\_TOKEN
#### For AWS Bedrock:
1. An AWS account with Amazon Bedrock enabled
2. GitHub OIDC Identity Provider configured in AWS
3. An IAM role with Bedrock permissions
4. A GitHub App (recommended) or use the default GITHUB\_TOKEN
## Troubleshooting
### Claude not responding to @claude commands
Verify the GitHub App is installed correctly, check that workflows are enabled, ensure API key is set in repository secrets, and confirm the comment contains `@claude` (not `/claude`).
### CI not running on Claude’s commits
Ensure you’re using the GitHub App or custom app (not Actions user), check workflow triggers include the necessary events, and verify app permissions include CI triggers.
Confirm API key is valid and has sufficient permissions. For Bedrock/Vertex, check credentials configuration and ensure secrets are named correctly in workflows.
## Advanced configuration
### Action parameters
The Claude Code Action supports these key parameters:
| Parameter | Description | Required |
| --- | --- | --- |
| `prompt` | The prompt to send to Claude | Yes\* |
| `prompt_file` | Path to file containing prompt | Yes\* |
| `allowed_tools` | Array of allowed tools | No |
| `anthropic_api_key` | Anthropic API key | Yes\*\* |
| `max_turns` | Maximum conversation turns | No |
| `timeout_minutes` | Execution timeout | No |
\*Either `prompt` or `prompt_file` required
\*\*Required for direct Anthropic API, not for Bedrock/Vertex
### Alternative integration methods
While the `/install-github-app` command is the recommended approach, you can also:
- **Custom GitHub App**: For organizations needing branded usernames or custom authentication flows. Create your own GitHub App with required permissions (contents, issues, pull requests) and use the actions/create-github-app-token action to generate tokens in your workflows.
- **Manual GitHub Actions**: Direct workflow configuration for maximum flexibility
- **MCP Configuration**: Dynamic loading of Model Context Protocol servers
See the [Claude Code Action repository](https://github.com/anthropics/claude-code-action) for detailed documentation.
### Customizing Claude’s behavior
You can configure Claude’s behavior in two ways:
1. **CLAUDE.md**: Define coding standards, review criteria, and project-specific rules in a `CLAUDE.md` file at the root of your repository. Claude will follow these guidelines when creating PRs and responding to requests. Check out our [Memory documentation](https://docs.anthropic.com/en/docs/claude-code/memory) for more details.
2. **Custom prompts**: Use the `prompt` parameter in the workflow file to provide workflow-specific instructions. This allows you to customize Claude’s behavior for different workflows or tasks.
Claude will follow these guidelines when creating PRs and responding to requests.

81
docs/claude-code-docs/IDE integrations.md Normal file
View file

@ -0,0 +1,81 @@
---
title: "IDE integrations"
source: "https://docs.anthropic.com/en/docs/claude-code/ide-integrations"
author:
- "[[Anthropic]]"
published:
created: 2025-05-25
description: "Integrate Claude Code with your favorite development environments"
tags:
- "clippings"
---
Claude Code seamlessly integrates with popular Integrated Development Environments (IDEs) to enhance your coding workflow. This integration allows you to leverage Claude’s capabilities directly within your preferred development environment.
## Supported IDEs
Claude Code currently supports two major IDE families:
- **Visual Studio Code** (including popular forks like Cursor and Windsurf)
- **JetBrains IDEs** (including PyCharm, WebStorm, IntelliJ, and GoLand)
## Features
- **Quick launch**: Use `Cmd+Esc` (Mac) or `Ctrl+Esc` (Windows/Linux) to open Claude Code directly from your editor, or click the Claude Code button in the UI
- **Diff viewing**: Code changes can be displayed directly in the IDE diff viewer instead of the terminal. You can configure this in `/config`
- **Selection context**: The current selection/tab in the IDE is automatically shared with Claude Code
- **File reference shortcuts**: Use `Cmd+Option+K` (Mac) or `Alt+Ctrl+K` (Linux/Windows) to insert file references (e.g., @File#L1-99)
- **Diagnostic sharing**: Diagnostic errors (lint, syntax, etc.) from the IDE are automatically shared with Claude as you work
## Installation
### VS Code
1. Open VSCode
2. Open the integrated terminal
3. Run `claude` - the extension will auto-install
Going forward you can also use the `/ide` command in any external terminal to connect to the IDE.
These installation instructions also apply to VS Code forks like Cursor and Windsurf.
### JetBrains IDEs
Install the [Claude Code plugin](https://docs.anthropic.com/s/claude-code-jetbrains) from the marketplace and restart your IDE.
The plugin may also be auto-installed when you run `claude` in the integrated terminal. The IDE must be restarted completely to take effect.
**Remote Development Limitations**: When using JetBrains Remote Development, you must install the plugin in the remote host via `Settings > Plugin (Host)`.
## Configuration
Both integrations work with Claude Code’s configuration system. To enable IDE-specific features:
1. Connect Claude Code to your IDE by running `claude` in the built-in terminal
2. Run the `/config` command
3. Set the diff tool to `auto` for automatic IDE detection
4. Claude Code will automatically use the appropriate viewer based on your IDE
If you’re using an external terminal (not the IDE’s built-in terminal), you can still connect to your IDE by using the `/ide` command after launching Claude Code. This allows you to benefit from IDE integration features even when running Claude from a separate terminal application. This works for both VS Code and JetBrains IDEs.
When using an external terminal, to ensure Claude has default access to the same files as your IDE, start Claude from the same directory as your IDE project root.
## Troubleshooting
### VS Code extension not installing
- Ensure you’re running Claude Code from VS Code’s integrated terminal
- Ensure that the CLI corresponding to your IDE is installed:
- For VS Code: `code` command should be available
- For Cursor: `cursor` command should be available
- For Windsurf: `windsurf` command should be available
- If not installed, use `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux) and search for “Shell Command: Install ‘code’ command in PATH” (or the equivalent for your IDE)
- Check that VS Code has permission to install extensions
### JetBrains plugin not working
- Ensure you’re running Claude Code from the project root directory
- Check that the JetBrains plugin is enabled in the IDE settings
- Completely restart the IDE. You may need to do this multiple times
- For JetBrains Remote Development, ensure that the Claude Code plugin is installed in the remote host and not locally on the client
For additional help, refer to our [troubleshooting guide](https://docs.anthropic.com/docs/claude-code/troubleshooting) or reach out to support.

56
docs/claude-code-docs/Manage Claude's memory.md Normal file
View file

@ -0,0 +1,56 @@
---
title: "Manage Claude's memory"
source: "https://docs.anthropic.com/en/docs/claude-code/memory"
author:
- "[[Anthropic]]"
published:
created: 2025-05-25
description: "Learn how to manage Claude Code's memory across sessions with different memory locations and best practices."
tags:
- "clippings"
---
Claude Code can remember your preferences across sessions, like style guidelines and common commands in your workflow.
## Determine memory type
Claude Code offers three memory locations, each serving a different purpose:
| Memory Type | Location | Purpose | Use Case Examples |
| --- | --- | --- | --- |
| **Project memory** | `./CLAUDE.md` | Team-shared instructions for the project | Project architecture, coding standards, common workflows |
| **User memory** | `~/.claude/CLAUDE.md` | Personal preferences for all projects | Code styling preferences, personal tooling shortcuts |
| **Project memory (local)** | `./CLAUDE.local.md` | Personal project-specific preferences | *(Deprecated, see below)* Your sandbox URLs, preferred test data |
All memory files are automatically loaded into Claude Code’s context when launched.
## CLAUDE.md imports
CLAUDE.md files can import additional files using `@path/to/import` syntax. The following example imports 3 files:
Both relative and absolute paths are allowed. In particular, importing files in user’s home dir is a convenient way for your team members to provide individual instructions that are not checked into the repository. Previously CLAUDE.local.md served a similar purpose, but is now deprecated in favor of imports since they work better across multiple git worktrees.
To avoid potential collisions, imports are not evaluated inside markdown code spans and code blocks.
Imported files can recursively import additional files, with a max-depth of 5 hops. You can see what memory files are loaded by running `/memory` command.
## How Claude looks up memories
Claude Code reads memories recursively: starting in the cwd, Claude Code recurses up to */* and reads any CLAUDE.md or CLAUDE.local.md files it finds. This is especially convenient when working in large repositories where you run Claude Code in *foo/bar/*, and have memories in both *foo/CLAUDE.md* and *foo/bar/CLAUDE.md*.
Claude will also discover CLAUDE.md nested in subtrees under your current working directory. Instead of loading them at launch, they are only included when Claude reads files in those subtrees.
## Quickly add memories with the # shortcut
The fastest way to add a memory is to start your input with the `#` character:
You’ll be prompted to select which memory file to store this in.
## Directly edit memories with /memory
Use the `/memory` slash command during a session to open any memory file in your system editor for more extensive additions or organization.
## Memory best practices
- **Be specific**: “Use 2-space indentation” is better than “Format code properly”.
- **Use structure to organize**: Format each individual memory as a bullet point and group related memories under descriptive markdown headings.
- **Review periodically**: Update memories as your project evolves to ensure Claude is always using the most up to date information and context.

53
docs/claude-code-docs/Manage costs effectively.md Normal file
View file

@ -0,0 +1,53 @@
---
title: "Manage costs effectively"
source: "https://docs.anthropic.com/en/docs/claude-code/costs"
author:
- "[[Anthropic]]"
published:
created: 2025-05-25
description: "Learn how to track and optimize token usage and costs when using Claude Code."
tags:
- "clippings"
---
Claude Code consumes tokens for each interaction. The average cost is $6 per developer per day, with daily costs remaining below $12 for 90% of users.
## Track your costs
- Use `/cost` to see current session usage
- **Anthropic Console users**:
- Check [historical usage](https://support.anthropic.com/en/articles/9534590-cost-and-usage-reporting-in-console) in the Anthropic Console (requires Admin or Billing role)
- Set [workspace spend limits](https://support.anthropic.com/en/articles/9796807-creating-and-managing-workspaces) for the Claude Code workspace (requires Admin role)
- **Max plan users**: Usage is included in your Max plan subscription
## Reduce token usage
- **Compact conversations:**
- Claude uses auto-compact by default when context exceeds 95% capacity
- Toggle auto-compact: Run `/config` and navigate to “Auto-compact enabled”
- Use `/compact` manually when context gets large
- Add custom instructions: `/compact Focus on code samples and API usage`
- Customize compaction by adding to CLAUDE.md:
- **Write specific queries:** Avoid vague requests that trigger unnecessary scanning
- **Break down complex tasks:** Split large tasks into focused interactions
- **Clear history between tasks:** Use `/clear` to reset context
Costs can vary significantly based on:
- Size of codebase being analyzed
- Complexity of queries
- Number of files being searched or modified
- Length of conversation history
- Frequency of compacting conversations
- Background processes (haiku generation, conversation summarization)
## Background token usage
Claude Code uses tokens for some background functionality even when idle:
- **Haiku generation**: Small creative messages that appear while you type (approximately 1 cent per day)
- **Conversation summarization**: Background jobs that summarize previous conversations for the `claude --resume` feature
- **Command processing**: Some commands like `/cost` may generate requests to check status
These background processes consume a small amount of tokens (typically under $0.04 per session) even without active interaction.
For team deployments, we recommend starting with a small pilot group to establish usage patterns before wider rollout.

116
docs/claude-code-docs/Manage permissions and security.md Normal file
View file

@ -0,0 +1,116 @@
---
title: "Manage permissions and security"
source: "https://docs.anthropic.com/en/docs/claude-code/security"
author:
- "[[Anthropic]]"
published:
created: 2025-05-25
description: "Learn about Claude Code's permission system, tools access, and security safeguards."
tags:
- "clippings"
---
Claude Code uses a tiered permission system to balance power and safety:
| Tool Type | Example | Approval Required | ”Yes, don’t ask again” Behavior |
| --- | --- | --- | --- |
| Read-only | File reads, LS, Grep | No | N/A |
| Bash Commands | Shell execution | Yes | Permanently per project directory and command |
| File Modification | Edit/write files | Yes | Until session end |
## Tools available to Claude
Claude Code has access to a set of powerful tools that help it understand and modify your codebase:
| Tool | Description | Permission Required |
| --- | --- | --- |
| **Agent** | Runs a sub-agent to handle complex, multi-step tasks | No |
| **Bash** | Executes shell commands in your environment | Yes |
| **Glob** | Finds files based on pattern matching | No |
| **Grep** | Searches for patterns in file contents | No |
| **LS** | Lists files and directories | No |
| **Read** | Reads the contents of files | No |
| **Edit** | Makes targeted edits to specific files | Yes |
| **Write** | Creates or overwrites files | Yes |
| **NotebookEdit** | Modifies Jupyter notebook cells | Yes |
| **NotebookRead** | Reads and displays Jupyter notebook contents | No |
| **WebFetch** | Fetches content from a specified URL | Yes |
Permission rules can be configured using `/allowed-tools` or in [permission settings](https://docs.anthropic.com/en/docs/claude-code/settings#permissions).
## Protect against prompt injection
Prompt injection is a technique where an attacker attempts to override or manipulate an AI assistant’s instructions by inserting malicious text. Claude Code includes several safeguards against these attacks:
- **Permission system**: Sensitive operations require explicit approval
- **Context-aware analysis**: Detects potentially harmful instructions by analyzing the full request
- **Input sanitization**: Prevents command injection by processing user inputs
- **Command blocklist**: Blocks risky commands that fetch arbitrary content from the web like `curl` and `wget`
**Best practices for working with untrusted content**:
1. Review suggested commands before approval
2. Avoid piping untrusted content directly to Claude
3. Verify proposed changes to critical files
4. Report suspicious behavior with `/bug`
While these protections significantly reduce risk, no system is completely immune to all attacks. Always maintain good security practices when working with any AI tool.
## Configure network access
Claude Code requires access to:
- api.anthropic.com
- statsig.anthropic.com
- sentry.io
Allowlist these URLs when using Claude Code in containerized environments.
## Development container reference implementation
Claude Code provides a development container configuration for teams that need consistent, secure environments. This preconfigured [devcontainer setup](https://code.visualstudio.com/docs/devcontainers/containers) works seamlessly with VS Code’s Remote - Containers extension and similar tools.
The container’s enhanced security measures (isolation and firewall rules) allow you to run `claude --dangerously-skip-permissions` to bypass permission prompts for unattended operation. We’ve included a [reference implementation](https://github.com/anthropics/claude-code/tree/main/.devcontainer) that you can customize for your needs.
While the devcontainer provides substantial protections, no system is completely immune to all attacks. Always maintain good security practices and monitor Claude’s activities.
### Key features
- **Production-ready Node.js**: Built on Node.js 20 with essential development dependencies
- **Security by design**: Custom firewall restricting network access to only necessary services
- **Developer-friendly tools**: Includes git, ZSH with productivity enhancements, fzf, and more
- **Seamless VS Code integration**: Pre-configured extensions and optimized settings
- **Session persistence**: Preserves command history and configurations between container restarts
- **Works everywhere**: Compatible with macOS, Windows, and Linux development environments
### Getting started in 4 steps
1. Install VS Code and the Remote - Containers extension
2. Clone the [Claude Code reference implementation](https://github.com/anthropics/claude-code/tree/main/.devcontainer) repository
3. Open the repository in VS Code
4. When prompted, click “Reopen in Container” (or use Command Palette: Cmd+Shift+P → “Remote-Containers: Reopen in Container”)
### Configuration breakdown
The devcontainer setup consists of three primary components:
- [**devcontainer.json**](https://github.com/anthropics/claude-code/blob/main/.devcontainer/devcontainer.json): Controls container settings, extensions, and volume mounts
- [**Dockerfile**](https://github.com/anthropics/claude-code/blob/main/.devcontainer/Dockerfile): Defines the container image and installed tools
- [**init-firewall.sh**](https://github.com/anthropics/claude-code/blob/main/.devcontainer/init-firewall.sh): Establishes network security rules
### Security features
The container implements a multi-layered security approach with its firewall configuration:
- **Precise access control**: Restricts outbound connections to whitelisted domains only (npm registry, GitHub, Anthropic API, etc.)
- **Default-deny policy**: Blocks all other external network access
- **Startup verification**: Validates firewall rules when the container initializes
- **Isolation**: Creates a secure development environment separated from your main system
### Customization options
The devcontainer configuration is designed to be adaptable to your needs:
- Add or remove VS Code extensions based on your workflow
- Modify resource allocations for different hardware environments
- Adjust network access permissions
- Customize shell configurations and developer tooling

175
docs/claude-code-docs/Monitoring usage.md Normal file
View file

@ -0,0 +1,175 @@
---
title: "Monitoring usage"
source: "https://docs.anthropic.com/en/docs/claude-code/monitoring-usage"
author:
- "[[Anthropic]]"
published:
created: 2025-05-25
description: "Monitor Claude Code usage with OpenTelemetry metrics"
tags:
- "clippings"
---
OpenTelemetry support is currently in beta and details are subject to change.
## OpenTelemetry in Claude Code
Claude Code supports OpenTelemetry (OTel) metrics for monitoring and observability. This document explains how to enable and configure OTel for Claude Code.
All metrics are time series data exported via OpenTelemetry’s standard metrics protocol. It is the user’s responsibility to ensure their metrics backend is properly configured and that the aggregation granularity meets their monitoring requirements.
## Quick Start
Configure OpenTelemetry using environment variables:
The default export interval is 10 minutes. During setup, you may want to use a shorter interval for debugging purposes. Remember to reset this for production use.
For full configuration options, see the [OpenTelemetry specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md#configuration-options).
## Administrator Configuration
Administrators can configure OpenTelemetry settings for all users through the managed settings file. This allows for centralized control of telemetry settings across an organization. See the [configuration hierarchy](https://docs.anthropic.com/en/docs/claude-code/settings#configuration-hierarchy) for more information about how settings are applied.
The managed settings file is located at:
- macOS: `/Library/Application Support/ClaudeCode/managed-settings.json`
- Linux: `/etc/claude-code/managed-settings.json`
Example managed settings configuration:
Managed settings can be distributed via MDM (Mobile Device Management) or other device management solutions. Environment variables defined in the managed settings file have high precedence and cannot be overridden by users.
## Configuration Details
### Common Configuration Variables
| Environment Variable | Description | Example Values |
| --- | --- | --- |
| `CLAUDE_CODE_ENABLE_TELEMETRY` | Enables telemetry collection (required) | `1` |
| `OTEL_METRICS_EXPORTER` | Exporter type(s) to use (comma-separated) | `console`, `otlp`, `prometheus` |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | Protocol for OTLP exporter | `grpc`, `http/json`, `http/protobuf` |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP collector endpoint | `http://localhost:4317` |
| `OTEL_EXPORTER_OTLP_HEADERS` | Authentication headers for OTLP | `Authorization=Bearer token` |
| `OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY` | Client key for mTLS authentication | Path to client key file |
| `OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATE` | Client certificate for mTLS authentication | Path to client cert file |
| `OTEL_METRIC_EXPORT_INTERVAL` | Export interval in milliseconds (default: 10000) | `5000`, `60000` |
### Metrics Cardinality Control
The following environment variables control which attributes are included in metrics to manage cardinality:
| Environment Variable | Description | Default Value | Example to Disable |
| --- | --- | --- | --- |
| `OTEL_METRICS_INCLUDE_SESSION_ID` | Include session.id attribute in metrics | `true` | `false` |
| `OTEL_METRICS_INCLUDE_VERSION` | Include app.version attribute in metrics | `false` | `true` |
| `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` | Include user.account\_uuid attribute in metrics | `true` | `false` |
These variables help control the cardinality of metrics, which affects storage requirements and query performance in your metrics backend. Lower cardinality generally means better performance and lower storage costs but less granular data for analysis.
### Example Configurations
## Available Metrics
Claude Code exports the following metrics:
| Metric Name | Description | Unit |
| --- | --- | --- |
| `claude_code.session.count` | Count of CLI sessions started | count |
| `claude_code.lines_of_code.count` | Count of lines of code modified | count |
| `claude_code.pull_request.count` | Number of pull requests created | count |
| `claude_code.commit.count` | Number of git commits created | count |
| `claude_code.cost.usage` | Cost of the Claude Code session | USD |
| `claude_code.token.usage` | Number of tokens used | tokens |
### Metric Details
All metrics share these standard attributes:
- `session.id`: Unique session identifier (controlled by `OTEL_METRICS_INCLUDE_SESSION_ID`)
- `app.version`: Current Claude Code version (controlled by `OTEL_METRICS_INCLUDE_VERSION`)
- `organization.id`: Organization UUID (when authenticated)
- `user.account_uuid`: Account UUID (when authenticated, controlled by `OTEL_METRICS_INCLUDE_ACCOUNT_UUID`)
#### 1\. Session Counter
Emitted at the start of each session.
#### 2\. Lines of Code Counter
Emitted when code is added or removed.
- Additional attribute: `type` (`"added"` or `"removed"`)
#### 3\. Pull Request Counter
Emitted when creating pull requests via Claude Code.
#### 4\. Commit Counter
Emitted when creating git commits via Claude Code.
#### 5\. Cost Counter
Emitted after each API request.
- Additional attribute: `model`
#### 6\. Token Counter
Emitted after each API request.
- Additional attributes: `type` (`"input"`, `"output"`, `"cacheRead"`, `"cacheCreation"`) and `model`
## Interpreting Metrics Data
These metrics provide insights into usage patterns, productivity, and costs:
### Usage Monitoring
| Metric | Analysis Opportunity |
| --- | --- |
| `claude_code.token.usage` | Break down by `type` (input/output), user, team, or model |
| `claude_code.session.count` | Track adoption and engagement over time |
| `claude_code.lines_of_code.count` | Measure productivity by tracking code additions/removals |
| `claude_code.commit.count` & `claude_code.pull_request.count` | Understand impact on development workflows |
### Cost Monitoring
The `claude_code.cost.usage` metric helps with:
- Tracking usage trends across teams or individuals
- Identifying high-usage sessions for optimization
Cost metrics are approximations. For official billing data, refer to your API provider (Anthropic Console, AWS Bedrock, or Google Cloud Vertex).
### Alerting and Segmentation
Common alerts to consider:
- Cost spikes
- Unusual token consumption
- High session volume from specific users
All metrics can be segmented by `user.account_uuid`, `organization.id`, `session.id`, `model`, and `app.version`.
## Backend Considerations
| Backend Type | Best For |
| --- | --- |
| Time series databases (Prometheus) | Rate calculations, aggregated metrics |
| Columnar stores (ClickHouse) | Complex queries, unique user analysis |
| Observability platforms (Honeycomb, Datadog) | Advanced querying, visualization, alerting |
For DAU/WAU/MAU metrics, choose backends that support efficient unique value queries.
## Service Information
All metrics are exported with:
- Service Name: `claude-code`
- Service Version: Current Claude Code version
- Meter Name: `com.anthropic.claude_code`
## Security Considerations
- Telemetry is opt-in and requires explicit configuration
- Sensitive information like API keys or file contents are never included in metrics

170
docs/claude-code-docs/SDK.md Normal file
View file

@ -0,0 +1,170 @@
---
title: "SDK"
source: "https://docs.anthropic.com/en/docs/claude-code/sdk"
author:
- "[[Anthropic]]"
published:
created: 2025-05-26
description: "Programmatically integrate Claude Code into your applications using the SDK."
tags:
- "clippings"
---
The Claude Code SDK allows developers to programmatically integrate Claude Code into their applications. It enables running Claude Code as a subprocess, providing a way to build AI-powered coding assistants and tools that leverage Claude’s capabilities.
The SDK currently support command line usage. TypeScript and Python SDKs are coming soon.
## Basic SDK usage
The Claude Code SDK allows you to use Claude Code in non-interactive mode from your applications. Here’s a basic example:
## Advanced usage
### Multi-turn conversations
For multi-turn conversations, you can resume conversations or continue from the most recent session:
### Custom system prompts
You can provide custom system prompts to guide Claude’s behavior:
You can also append instructions to the default system prompt:
### MCP Configuration
The Model Context Protocol (MCP) allows you to extend Claude Code with additional tools and resources from external servers. Using the `--mcp-config` flag, you can load MCP servers that provide specialized capabilities like database access, API integrations, or custom tooling.
Create a JSON configuration file with your MCP servers:
Then use it with Claude Code:
Note: When using MCP tools, you must explicitly allow them using the `--allowedTools` flag. MCP tool names follow the pattern `mcp__<serverName>__<toolName>` where:
- `serverName` is the key from your MCP configuration file
- `toolName` is the specific tool provided by that server
This security measure ensures that MCP tools are only used when explicitly permitted.
## Available CLI options
The SDK leverages all the CLI options available in Claude Code. Here are the key ones for SDK usage:
| Flag | Description | Example |
| --- | --- | --- |
| `--print`, `-p` | Run in non-interactive mode | `claude -p "query"` |
| `--output-format` | Specify output format (`text`, `json`, `stream-json`) | `claude -p --output-format json` |
| `--resume`, `-r` | Resume a conversation by session ID | `claude --resume abc123` |
| `--continue`, `-c` | Continue the most recent conversation | `claude --continue` |
| `--verbose` | Enable verbose logging | `claude --verbose` |
| `--max-turns` | Limit agentic turns in non-interactive mode | `claude --max-turns 3` |
| `--system-prompt` | Override system prompt (only with `--print`) | `claude --system-prompt "Custom instruction"` |
| `--append-system-prompt` | Append to system prompt (only with `--print`) | `claude --append-system-prompt "Custom instruction"` |
| `--allowedTools` | Comma/space-separated list of allowed tools (includes MCP tools) | `claude --allowedTools "Bash(npm install),mcp__filesystem__*"` |
| `--disallowedTools` | Comma/space-separated list of denied tools | `claude --disallowedTools "Bash(git commit),mcp__github__*"` |
| `--mcp-config` | Load MCP servers from a JSON file | `claude --mcp-config servers.json` |
| `--permission-prompt-tool` | MCP tool for handling permission prompts (only with `--print`) | `claude --permission-prompt-tool mcp__auth__prompt` |
For a complete list of CLI options and features, see the [CLI usage](https://docs.anthropic.com/en/docs/claude-code/cli-usage) documentation.
## Output formats
The SDK supports multiple output formats:
### Text output (default)
Returns just the response text:
### JSON output
Returns structured data including metadata:
Response format:
### Streaming JSON output
Streams each message as it is received:
Each conversation begins with an initial `init` system message, followed by a list of user and assistant messages, followed by a final `result` system message with stats. Each message is emitted as a separate JSON object.
## Message schema
Messages returned from the JSON API are strictly typed according to the following schema:
```ts
type Message =
// An assistant message
| {
type: "assistant";
message: APIAssistantMessage; // from Anthropic SDK
session_id: string;
}
// A user message
| {
type: "user";
message: APIUserMessage; // from Anthropic SDK
session_id: string;
}
// Emitted as the last message
| {
type: "result";
subtype: "success";
cost_usd: float;
duration_ms: float;
duration_api_ms: float;
is_error: boolean;
num_turns: int;
result: string;
session_id: string;
}
// Emitted as the last message, when we've reached the maximum number of turns
| {
type: "result";
subtype: "error_max_turns";
cost_usd: float;
duration_ms: float;
duration_api_ms: float;
is_error: boolean;
num_turns: int;
session_id: string;
}
// Emitted as the first message at the start of a conversation
| {
type: "system";
subtype: "init";
session_id: string;
tools: string[];
mcp_servers: {
name: string;
status: string;
}[];
};
```
We will soon publish these types in a JSONSchema-compatible format. We use semantic versioning for the main Claude Code package to communicate breaking changes to this format.
## Examples
### Simple script integration
### Processing files with Claude
### Session management
## Best practices
1. **Use JSON output format** for programmatic parsing of responses:
2. **Handle errors gracefully** - check exit codes and stderr:
3. **Use session management** for maintaining context in multi-turn conversations
4. **Consider timeouts** for long-running operations:
5. **Respect rate limits** when making multiple requests by adding delays between calls
## Real-world applications
The Claude Code SDK enables powerful integrations with your development workflow. One notable example is the [Claude Code GitHub Actions](https://docs.anthropic.com/en/docs/claude-code/github-actions), which uses the SDK to provide automated code review, PR creation, and issue triage capabilities directly in your GitHub workflow.
- [CLI usage and controls](https://docs.anthropic.com/en/docs/claude-code/cli-usage) - Complete CLI documentation
- [GitHub Actions integration](https://docs.anthropic.com/en/docs/claude-code/github-actions) - Automate your GitHub workflow with Claude
- [Tutorials](https://docs.anthropic.com/en/docs/claude-code/tutorials) - Step-by-step guides for common use cases

143
docs/claude-code-docs/Team setup.md Normal file
View file

@ -0,0 +1,143 @@
---
title: "Team setup"
source: "https://docs.anthropic.com/en/docs/claude-code/team"
author:
- "[[Anthropic]]"
published:
created: 2025-05-25
description: "Learn how to onboard your team to Claude Code, including user management, security, and best practices."
tags:
- "clippings"
---
## User management
Setting up Claude Code requires access to Anthropic models. For teams, you can set up Claude Code access in one of three ways:
- Anthropic API via the Anthropic Console
- Amazon Bedrock
- Google Vertex AI
**To set up Claude Code access for your team via Anthropic API:**
1. Use your existing Anthropic Console account or create a new Anthropic Console account
2. You can add users through either method below:
- Bulk invite users from within the Console (Console -> Settings -> Members -> Invite)
- [Set up SSO](https://support.anthropic.com/en/articles/10280258-setting-up-single-sign-on-on-the-api-console)
3. When inviting users, they need one of the following roles:
- “Claude Code” role means users can only create Claude Code API keys
- “Developer” role means users can create any kind of API key
4. Each invited user needs to complete these steps:
- Accept the Console invite
- [Check system requirements](https://docs.anthropic.com/en/docs/claude-code/getting-started#check-system-requirements)
- [Install Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview#install-and-authenticate)
- Login with Console account credentials
**To set up Claude Code access for your team via Bedrock or Vertex:**
1. Follow the [Bedrock docs](https://docs.anthropic.com/en/docs/claude-code/bedrock-vertex-proxies#connect-to-amazon-bedrock) or [Vertex docs](https://docs.anthropic.com/en/docs/claude-code/bedrock-vertex-proxies#connect-to-google-vertex-ai)
2. Distribute the environment variables and instructions for generating cloud credentials to your users. Read more about how to [manage configuration here](https://docs.anthropic.com/en/docs/claude-code/settings#configuration-hierarchy).
3. Users can [install Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview#install-and-authenticate)
## How we approach security
Your code’s security is paramount. Claude Code is built with security at its core. We’ve developed Claude Code, as we develop all of our applications and services, according to the requirements of Anthropic’s comprehensive security program. You can read more about our program and request access to resources (such as our SOC 2 Type 2 report, ISO 27001 certificate, etc.) at [Anthropic Trust Center](https://trust.anthropic.com/).
We’ve designed Claude Code to have strict read-only permissions by default, including reading files in the current working directory, and specific bash commands such as `date`, `pwd`, and `whoami`. As Claude Code requests to perform additional actions (such as to edit files, run tests, and execute bash commands), it will ask users for permission. When Claude Code requests permission, users can approve it just for that instance or allow it to run that command automatically going forward. We support fine-grained permissions so that you’re able to specify exactly what the agent is allowed to do (e.g. run tests, run linter) and what it is not allowed to do (e.g. update cloud infrastructure). These permission settings can be checked into version control and distributed to all developers in your organization, as well as customized by individual developers.
For enterprise deployments of Claude Code, we also support enterprise managed policy settings. These take precedence over user and project settings, allowing system administrators to enforce security policies that users cannot override. [Learn how to configure enterprise managed policy settings](https://docs.anthropic.com/en/docs/claude-code/settings#configuration-hierarchy).
We designed Claude Code to be transparent and secure. For example, we allow the model to suggest `git` commands before executing them, thus giving control to the user to grant or deny permission. This enables users and organizations to configure their own permissions directly rather than trying to monitor all possible workarounds.
Agentic systems are fundamentally different from AI chat experiences since agents are able to call tools that interact with the real world and act for longer periods of time. Agentic systems are non-deterministic and we have a number of built in protections to mitigate risks for users.
1. **Prompt injection** is when model inputs alter model behavior in an undesired way. To reduce the risk of this happening, we’ve added a few in-product mitigations:
- Tools that make network requests require user approval by default
- Web fetch uses a separate context window, to avoid injecting potentially malicious prompts into the main context window
- The first time you run Claude Code in a new codebase, we will prompt you to verify that you trust the code
- The first time you see new MCP servers (configured via `.mcp.json`), we will prompt you to verify that you trust the servers
- When we detect a bash command with potential command injection (as a result of prompt injection), we will ask users to manually approve the command even if they have allowlisted it
- If we cannot reliably match a bash command to an allowlisted permission, we fail closed and prompt users for manual approval
- When the model generates complex bash commands, we generate natural language descriptions for users, so that they understand what the command does
2. **Prompt fatigue.** We support allowlisting frequently used safe commands per-user, per-codebase, or per-organization. We also let you switch into Accept Edits mode to accept many edits at a time, focusing permission prompts on tools that may have side effects (eg. bash)
Ultimately, Claude Code only has as many permissions as the user who is guiding it, and users are responsible for making sure the proposed code and commands are safe.
**MCP security**
Claude Code allows users to configure Model Control Protocol (MCP) servers. The list of allowed MCP servers is configured in your source code, as part of Claude Code settings engineers check into source control.
We encourage either writing your own MCP servers or using MCP servers from providers that you trust. You are able to configure Claude Code permissions for MCP servers. Anthropic does not manage or audit any MCP servers.
## Data flow and dependencies
![Claude Code data flow diagram](https://mintlify.s3.us-west-1.amazonaws.com/anthropic/images/claude-code-data-flow.png)
Claude Code data flow diagram
Claude Code is installed from [NPM](https://www.npmjs.com/package/@anthropic-ai/claude-code). Claude Code runs locally. In order to interact with the LLM, Claude Code sends data over the network. This data includes all user prompts and model outputs. The data is encrypted in transit via TLS and is not encrypted at rest. Claude Code is compatible with most popular VPNs and LLM proxies.
Claude Code is built on Anthropic’s APIs. For details regarding our API’s security controls, including our API logging procedures, please refer to compliance artifacts offered in the [Anthropic Trust Center](https://trust.anthropic.com/).
Claude Code supports authentication via Claude.ai credentials, Anthropic API credentials, Bedrock Auth, and Vertex Auth. On MacOS, the API keys, OAuth tokens, and other credentials are stored on encrypted macOS Keychain. We also support `apiKeyHelper` to read from an alternative keychain. By default, this helper is called after 5 minutes or on HTTP 401 response; specifying `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` allows for a custom refresh interval.
Claude Code connects from users’ machines to the Statsig service to log operational metrics such as latency, reliability, and usage patterns. This logging does not include any code or file paths. Data is encrypted in transit using TLS and at rest using 256-bit AES encryption. Read more in the [Statsig security documentation](https://www.statsig.com/trust/security). To opt out of Statsig telemetry, set the `DISABLE_TELEMETRY` environment variable.
Claude Code connects from users’ machines to Sentry for operational error logging. The data is encrypted in transit using TLS and at rest using 256-bit AES encryption. Read more in the [Sentry security documentation](https://sentry.io/security/). To opt out of error logging, set the `DISABLE_ERROR_REPORTING` environment variable.
When users run the `/bug` command, a copy of their full conversation history including code is sent to Anthropic. The data is encrypted in transit and at rest. Optionally, a Github issue is created in our public repository. To opt out of bug reporting, set the `DISABLE_BUG_COMMAND` environment variable.
By default, we disable all non-essential traffic (including error reporting, telemetry, and bug reporting functionality) when using Bedrock or Vertex. You can also opt out of all of these at once by setting the `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` environment variable. Here are the full default behaviors:
| Service | Anthropic API | Vertex API | Bedrock API |
| --- | --- | --- | --- |
| **Statsig (Metrics)** | Default on. `DISABLE_TELEMETRY=1` to disable. | Default off. `CLAUDE_CODE_USE_VERTEX` must be 1. | Default off. `CLAUDE_CODE_USE_BEDROCK` must be 1. |
| **Sentry (Errors)** | Default on. `DISABLE_ERROR_REPORTING=1` to disable. | Default off. `CLAUDE_CODE_USE_VERTEX` must be 1. | Default off. `CLAUDE_CODE_USE_BEDROCK` must be 1. |
| **Anthropic API (`/bug` reports)** | Default on. `DISABLE_BUG_COMMAND=1` to disable. | Default off. `CLAUDE_CODE_USE_VERTEX` must be 1. | Default off. `CLAUDE_CODE_USE_BEDROCK` must be 1. |
All environment variables can be checked into `settings.json` ([read more](https://docs.anthropic.com/en/docs/claude-code/settings#configuration-hierarchy)).
Claude Code stores conversation history locally, in plain text, so that users can resume prior conversations. Conversations are retained for 30 days, and they can delete them earlier by running `rm -r ~/.claude/projects/*/`. The retention period can be customized using the `cleanupPeriodDays` setting; like other settings, you can check this setting into your repository, set it globally so that it applies across all repositories, or manage it for all employees using your enterprise policy. Uninstalling `claude` does not delete history.
## Managing costs
When using Anthropic API, you can limit the total Claude Code workspace spend. To configure, [follow these instructions](https://support.anthropic.com/en/articles/9796807-creating-and-managing-workspaces). Admins can view cost and usage reporting by [following these instructions](https://support.anthropic.com/en/articles/9534590-cost-and-usage-reporting-in-console).
On Bedrock and Vertex, Claude Code does not send metrics from your cloud. In order to get cost metrics, several large enterprises reported using [LiteLLM](https://docs.anthropic.com/en/docs/claude-code/bedrock-vertex-proxies#litellm), which is an open-source tool that helps companies [track spend by key](https://docs.litellm.ai/docs/proxy/virtual_keys#tracking-spend). This project is unaffiliated with Anthropic and we have not audited its security.
For team usage, Claude Code charges by API token consumption. On average, Claude Code costs ~$50-60/developer per month with Sonnet 3.7 though there is large variance depending on how many instances users are running and whether they’re using it in automation.
## Best practices for organizations
1. We strongly recommend investing in documentation so that Claude Code understands your codebase. Many organizations make a `CLAUDE.md` file (which we also refer to as memory) in the root of the repository that contains the system architecture, how to run tests and other common commands, and best practices for contributing to the codebase. This file is typically checked into source control so that all users can benefit from it. [Learn more](https://docs.anthropic.com/en/docs/claude-code/memory).
2. If you have a custom development environment, we find that creating a “one click” way to install Claude Code is key to growing adoption across an organization.
3. Encourage new users to try Claude Code for codebase Q&A, or on smaller bug fixes or feature requests. Ask Claude Code to make a plan. Check Claude’s suggestions and give feedback if it’s off-track. Over time, as users understand this new paradigm better, then they’ll be more effective at letting Claude Code run more agentically.
4. Security teams can configure managed permissions for what Claude Code is and is not allowed to do, which cannot be overwritten by local configuration. [Learn more](https://docs.anthropic.com/en/docs/claude-code/overview#permission-rules).
5. MCP is a great way to give Claude Code more information, such as connecting to ticket management systems or error logs. We recommend that one central team configures MCP servers and checks a `.mcp.json` configuration into the codebase so that all users benefit. [Learn more](https://docs.anthropic.com/en/docs/claude-code/tutorials#set-up-model-context-protocol-mcp).
At Anthropic, we trust Claude Code to power development across every Anthropic codebase. We hope you enjoy using Claude Code as much as we do!
## FAQ
**Q: Does my existing commercial agreement apply?**
Whether you’re using Anthropic’s API directly (1P) or accessing it through AWS Bedrock or Google Vertex (3P), your existing commercial agreement will apply to Claude Code usage, unless we’ve mutually agreed otherwise.
**Q: Does Claude Code train on user content?**
By default, Anthropic does not train generative models using code or prompts that are sent to Claude Code.
If you explicitly opt in to methods to provide us with materials to train on, such as via the [Development Partner Program](https://support.anthropic.com/en/articles/11174108-about-the-development-partner-program), we may use those materials provided to train our models. An organization admin can expressly opt-in to the Development Partner Program for their organization. Note that this program is available only for Anthropic first-party API, and not for Bedrock or Vertex users.
More details can be found in our [Commercial Terms of Service](https://www.anthropic.com/legal/commercial-terms) and [Privacy Policy](https://www.anthropic.com/legal/privacy).
**Q: Can I use a zero data retention key?**
Yes, you can use an API key from a zero data retention organization. When doing so, Claude Code will not retain your chat transcripts on our servers. Users’ local Claude Code clients may store sessions locally for up to 30 days so that users can resume them. This behavior is configurable.
**Q: Where can I learn more about trust and safety at Anthropic?**
You can find more information in the [Anthropic Trust Center](https://trust.anthropic.com/) and [Transparency Hub](https://www.anthropic.com/transparency).
**Q: How can I report security vulnerabilities?**
Anthropic manages our security program through HackerOne. [Use this form to report vulnerabilities](https://hackerone.com/anthropic-vdp/reports/new?type=team&report_type=vulnerability). You can also email us at [security@anthropic.com](https://docs.anthropic.com/en/docs/claude-code/).

136
docs/claude-code-docs/Troubleshooting.md Normal file
View file

@ -0,0 +1,136 @@
---
title: "Troubleshooting"
source: "https://docs.anthropic.com/en/docs/claude-code/troubleshooting"
author:
- "[[Anthropic]]"
published:
created: 2025-05-26
description: "Solutions for common issues with Claude Code installation and usage."
tags:
- "clippings"
---
## Common installation issues
When installing Claude Code with npm, you may encounter permission errors if your npm global prefix is not user writable (eg. `/usr`, or `/use/local`).
The safest approach is to configure npm to use a directory within your home folder:
```bash
# First, save a list of your existing global packages for later migration
npm list -g --depth=0 > ~/npm-global-packages.txt
# Create a directory for your global packages
mkdir -p ~/.npm-global
# Configure npm to use the new directory path
npm config set prefix ~/.npm-global
# Note: Replace ~/.bashrc with ~/.zshrc, ~/.profile, or other appropriate file for your shell
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
# Apply the new PATH setting
source ~/.bashrc
# Now reinstall Claude Code in the new location
npm install -g @anthropic-ai/claude-code
# Optional: Reinstall your previous global packages in the new location
# Look at ~/npm-global-packages.txt and install packages you want to keep
```
This solution is recommended because it:
- Avoids modifying system directory permissions
- Creates a clean, dedicated location for your global npm packages
- Follows security best practices
#### System Recovery: If you have run commands that change ownership and permissions of system files or similar
If you’ve already run a command that changed system directory permissions (such as `sudo chown -R $USER:$(id -gn) /usr && sudo chmod -R u+w /usr`) and your system is now broken (for example, if you see `sudo: /usr/bin/sudo must be owned by uid 0 and have the setuid bit set`), you’ll need to perform recovery steps.
##### Ubuntu/Debian Recovery Method:
1. While rebooting, hold **SHIFT** to access the GRUB menu
2. Select “Advanced options for Ubuntu/Debian”
3. Choose the recovery mode option
4. Select “Drop to root shell prompt”
5. Remount the filesystem as writable:
6. Fix permissions:
7. Reinstall affected packages (optional but recommended):
8. Reboot:
```bash
reboot
```
##### Alternative Live USB Recovery Method:
If the recovery mode doesn’t work, you can use a live USB:
1. Boot from a live USB (Ubuntu, Debian, or any Linux distribution)
2. Find your system partition:
```bash
lsblk
```
3. Mount your system partition:
4. If you have a separate boot partition, mount it too:
5. Chroot into your system:
6. Follow steps 6-8 from the Ubuntu/Debian recovery method above
After restoring your system, follow the recommended solution above to set up a user-writable npm prefix.
## Auto-updater issues
If Claude Code can’t update automatically, it may be due to permission issues with your npm global prefix directory. Follow the [recommended solution](https://docs.anthropic.com/en/docs/claude-code/troubleshooting#recommended-solution-create-a-user-writable-npm-prefix) above to fix this.
If you prefer to disable the auto-updater instead, you can use:
## Permissions and authentication
If you find yourself repeatedly approving the same commands, you can allow specific tools to run without approval:
### Authentication issues
If you’re experiencing authentication problems:
1. Run `/logout` to sign out completely
2. Close Claude Code
3. Restart with `claude` and complete the authentication process again
If problems persist, try:
This removes your stored authentication information and forces a clean login.
## Performance and stability
### High CPU or memory usage
Claude Code is designed to work with most development environments, but may consume significant resources when processing large codebases. If you’re experiencing performance issues:
1. Use `/compact` regularly to reduce context size
2. Close and restart Claude Code between major tasks
3. Consider adding large build directories to your `.gitignore` file
### Command hangs or freezes
If Claude Code seems unresponsive:
1. Press Ctrl+C to attempt to cancel the current operation
2. If unresponsive, you may need to close the terminal and restart
### ESC key not working in JetBrains (IntelliJ, PyCharm, etc.) terminals
If you’re using Claude Code in JetBrains terminals and the ESC key doesn’t interrupt the agent as expected, this is likely due to a keybinding clash with JetBrains’ default shortcuts.
To fix this issue:
1. Go to Settings → Tools → Terminal
2. Click the “Configure terminal keybindings” hyperlink next to “Override IDE Shortcuts”
3. Within the terminal keybindings, scroll down to “Switch focus to Editor” and delete that shortcut
This will allow the ESC key to properly function for canceling Claude Code operations instead of being captured by PyCharm’s “Switch focus to Editor” action.
If you’re experiencing issues not covered here:
1. Use the `/bug` command within Claude Code to report problems directly to Anthropic
2. Check the [GitHub repository](https://github.com/anthropics/claude-code) for known issues
3. Run `/doctor` to check the health of your Claude Code installation

364
docs/claude-code-docs/Tutorials.md Normal file
View file

@ -0,0 +1,364 @@
---
title: "Tutorials"
source: "https://docs.anthropic.com/en/docs/claude-code/tutorials"
author:
- "[[Anthropic]]"
published:
created: 2025-05-26
description: "Practical examples and patterns for effectively using Claude Code in your development workflow."
tags:
- "clippings"
---
This guide provides step-by-step tutorials for common workflows with Claude Code. Each tutorial includes clear instructions, example commands, and best practices to help you get the most from Claude Code.
- [Resume previous conversations](https://docs.anthropic.com/en/docs/claude-code/tutorials#resume-previous-conversations)
- [Understand new codebases](https://docs.anthropic.com/en/docs/claude-code/tutorials#understand-new-codebases)
- [Fix bugs efficiently](https://docs.anthropic.com/en/docs/claude-code/tutorials#fix-bugs-efficiently)
- [Refactor code](https://docs.anthropic.com/en/docs/claude-code/tutorials#refactor-code)
- [Work with tests](https://docs.anthropic.com/en/docs/claude-code/tutorials#work-with-tests)
- [Create pull requests](https://docs.anthropic.com/en/docs/claude-code/tutorials#create-pull-requests)
- [Handle documentation](https://docs.anthropic.com/en/docs/claude-code/tutorials#handle-documentation)
- [Work with images](https://docs.anthropic.com/en/docs/claude-code/tutorials#work-with-images)
- [Use extended thinking](https://docs.anthropic.com/en/docs/claude-code/tutorials#use-extended-thinking)
- [Set up project memory](https://docs.anthropic.com/en/docs/claude-code/tutorials#set-up-project-memory)
- [Set up Model Context Protocol (MCP)](https://docs.anthropic.com/en/docs/claude-code/tutorials#set-up-model-context-protocol-mcp)
- [Use Claude as a unix-style utility](https://docs.anthropic.com/en/docs/claude-code/tutorials#use-claude-as-a-unix-style-utility)
- [Create custom slash commands](https://docs.anthropic.com/en/docs/claude-code/tutorials#create-custom-slash-commands)
- [Run parallel Claude Code sessions with Git worktrees](https://docs.anthropic.com/en/docs/claude-code/tutorials#run-parallel-claude-code-sessions-with-git-worktrees)
## Resume previous conversations
### Continue your work seamlessly
**When to use:** You’ve been working on a task with Claude Code and need to continue where you left off in a later session.
Claude Code provides two options for resuming previous conversations:
- `--continue` to automatically continue the most recent conversation
- `--resume` to display a conversation picker
**How it works:**
1. **Conversation Storage**: All conversations are automatically saved locally with their full message history
2. **Message Deserialization**: When resuming, the entire message history is restored to maintain context
3. **Tool State**: Tool usage and results from the previous conversation are preserved
4. **Context Restoration**: The conversation resumes with all previous context intact
**Tips:**
- Conversation history is stored locally on your machine
- Use `--continue` for quick access to your most recent conversation
- Use `--resume` when you need to select a specific past conversation
- When resuming, you’ll see the entire conversation history before continuing
- The resumed conversation starts with the same model and configuration as the original
**Examples:**
## Understand new codebases
### Get a quick codebase overview
**When to use:** You’ve just joined a new project and need to understand its structure quickly.
**Tips:**
- Start with broad questions, then narrow down to specific areas
- Ask about coding conventions and patterns used in the project
- Request a glossary of project-specific terms
**When to use:** You need to locate code related to a specific feature or functionality.
**Tips:**
- Be specific about what you’re looking for
- Use domain language from the project
---
## Fix bugs efficiently
**When to use:** You’ve encountered an error message and need to find and fix its source.
**Tips:**
- Tell Claude the command to reproduce the issue and get a stack trace
- Mention any steps to reproduce the error
- Let Claude know if the error is intermittent or consistent
---
## Refactor code
### Modernize legacy code
**When to use:** You need to update old code to use modern patterns and practices.
**Tips:**
- Ask Claude to explain the benefits of the modern approach
- Request that changes maintain backward compatibility when needed
- Do refactoring in small, testable increments
---
## Work with tests
### Add test coverage
**When to use:** You need to add tests for uncovered code.
**Tips:**
- Ask for tests that cover edge cases and error conditions
- Request both unit and integration tests when appropriate
- Have Claude explain the testing strategy
---
## Create pull requests
### Generate comprehensive PRs
**When to use:** You need to create a well-documented pull request for your changes.
**Tips:**
- Ask Claude directly to make a PR for you
- Review Claude’s generated PR before submitting
- Ask Claude to highlight potential risks or considerations
## Handle documentation
### Generate code documentation
**When to use:** You need to add or update documentation for your code.
**Tips:**
- Specify the documentation style you want (JSDoc, docstrings, etc.)
- Ask for examples in the documentation
- Request documentation for public APIs, interfaces, and complex logic
## Work with images
### Analyze images and screenshots
**When to use:** You need to work with images in your codebase or get Claude’s help analyzing image content.
**Tips:**
- Use images when text descriptions would be unclear or cumbersome
- Include screenshots of errors, UI designs, or diagrams for better context
- You can work with multiple images in a conversation
- Image analysis works with diagrams, screenshots, mockups, and more
---
## Use extended thinking
### Leverage Claude’s extended thinking for complex tasks
**When to use:** When working on complex architectural decisions, challenging bugs, or planning multi-step implementations that require deep reasoning.
**Tips to get the most value out of extended thinking:**
Extended thinking is most valuable for complex tasks such as:
- Planning complex architectural changes
- Debugging intricate issues
- Creating implementation plans for new features
- Understanding complex codebases
- Evaluating tradeoffs between different approaches
The way you prompt for thinking results in varying levels of thinking depth:
- “think” triggers basic extended thinking
- intensifying phrases such as “think more”, “think a lot”, “think harder”, or “think longer” triggers deeper thinking
For more extended thinking prompting tips, see [Extended thinking tips](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/extended-thinking-tips).
Claude will display its thinking process as italic gray text above the response.
---
## Set up project memory
### Create an effective CLAUDE.md file
**When to use:** You want to set up a CLAUDE.md file to store important project information, conventions, and frequently used commands.
**Tips:**
- Include frequently used commands (build, test, lint) to avoid repeated searches
- Document code style preferences and naming conventions
- Add important architectural patterns specific to your project
- CLAUDE.md memories can be used for both instructions shared with your team and for your individual preferences. For more details, see [Managing Claude’s memory](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview#manage-claudes-memory).
---
## Set up Model Context Protocol (MCP)
Model Context Protocol (MCP) is an open protocol that enables LLMs to access external tools and data sources. For more details, see the [MCP documentation](https://modelcontextprotocol.io/introduction).
Use third party MCP servers at your own risk. Make sure you trust the MCP servers, and be especially careful when using MCP servers that talk to the internet, as these can expose you to prompt injection risk.
### Configure MCP servers
**When to use:** You want to enhance Claude’s capabilities by connecting it to specialized tools and external servers using the Model Context Protocol.
**Tips:**
- Use the `-s` or `--scope` flag to specify where the configuration is stored:
- `local` (default): Available only to you in the current project (was called `project` in older versions)
- `project`: Shared with everyone in the project via `.mcp.json` file
- `user`: Available to you across all projects (was called `global` in older versions)
- Set environment variables with `-e` or `--env` flags (e.g., `-e KEY=value`)
- Configure MCP server startup timeout using the MCP\_TIMEOUT environment variable (e.g., `MCP_TIMEOUT=10000 claude` sets a 10-second timeout)
- Check MCP server status any time using the `/mcp` command within Claude Code
- MCP follows a client-server architecture where Claude Code (the client) can connect to multiple specialized servers
### Understanding MCP server scopes
**When to use:** You want to understand how different MCP scopes work and how to share servers with your team.
**Tips:**
- Local-scoped servers take precedence over project-scoped and user-scoped servers with the same name
- Project-scoped servers (in `.mcp.json`) take precedence over user-scoped servers with the same name
- Before using project-scoped servers from `.mcp.json`, Claude Code will prompt you to approve them for security
- The `.mcp.json` file is intended to be checked into version control to share MCP servers with your team
- Project-scoped servers make it easy to ensure everyone on your team has access to the same MCP tools
- If you need to reset your choices for which project-scoped servers are enabled or disabled, use the `claude mcp reset-project-choices` command
### Connect to a Postgres MCP server
**When to use:** You want to give Claude read-only access to a PostgreSQL database for querying and schema inspection.
**Tips:**
- The Postgres MCP server provides read-only access for safety
- Claude can help you explore database structure and run analytical queries
- You can use this to quickly understand database schemas in unfamiliar projects
- Make sure your connection string uses appropriate credentials with minimum required permissions
### Add MCP servers from JSON configuration
**When to use:** You have a JSON configuration for a single MCP server that you want to add to Claude Code.
**Tips:**
- Make sure the JSON is properly escaped in your shell
- The JSON must conform to the MCP server configuration schema
- You can use `-s global` to add the server to your global configuration instead of the project-specific one
### Import MCP servers from Claude Desktop
**When to use:** You have already configured MCP servers in Claude Desktop and want to use the same servers in Claude Code without manually reconfiguring them.
**Tips:**
- This feature only works on macOS and Windows Subsystem for Linux (WSL)
- It reads the Claude Desktop configuration file from its standard location on those platforms
- Use the `-s global` flag to add servers to your global configuration
- Imported servers will have the same names as in Claude Desktop
- If servers with the same names already exist, they will get a numerical suffix (e.g., `server_1`)
### Use Claude Code as an MCP server
**When to use:** You want to use Claude Code itself as an MCP server that other applications can connect to, providing them with Claude’s tools and capabilities.
**Tips:**
- The server provides access to Claude’s tools like View, Edit, LS, etc.
- In Claude Desktop, try asking Claude to read files in a directory, make edits, and more.
- Note that this MCP server is simply exposing Claude Code’s tools to your MCP client, so your own client is responsible for implementing user confirmation for individual tool calls.
---
## Use Claude as a unix-style utility
### Add Claude to your verification process
**When to use:** You want to use Claude Code as a linter or code reviewer.
**Steps:**
### Pipe in, pipe out
**When to use:** You want to pipe data into Claude, and get back data in a structured format.
### Control output format
**When to use:** You need Claude’s output in a specific format, especially when integrating Claude Code into scripts or other tools.
**Tips:**
- Use `--output-format text` for simple integrations where you just need Claude’s response
- Use `--output-format json` when you need the full conversation log
- Use `--output-format stream-json` for real-time output of each conversation turn
---
## Create custom slash commands
Claude Code supports custom slash commands that you can create to quickly execute specific prompts or tasks.
### Create project-specific commands
**When to use:** You want to create reusable slash commands for your project that all team members can use.
**Tips:**
- Command names are derived from the filename (e.g., `optimize.md` becomes `/project:optimize`)
- You can organize commands in subdirectories (e.g., `.claude/commands/frontend/component.md` becomes `/project:frontend:component`)
- Project commands are available to everyone who clones the repository
- The Markdown file content becomes the prompt sent to Claude when the command is invoked
### Add command arguments with $ARGUMENTS
**When to use:** You want to create flexible slash commands that can accept additional input from users.
**Tips:**
- The $ARGUMENTS placeholder is replaced with any text that follows the command
- You can position $ARGUMENTS anywhere in your command template
- Other useful applications: generating test cases for specific functions, creating documentation for components, reviewing code in particular files, or translating content to specified languages
### Create personal slash commands
**When to use:** You want to create personal slash commands that work across all your projects.
**Tips:**
- Personal commands are prefixed with `/user:` instead of `/project:`
- Personal commands are only available to you and not shared with your team
- Personal commands work across all your projects
- You can use these for consistent workflows across different codebases
---
## Run parallel Claude Code sessions with Git worktrees
### Use worktrees for isolated coding environments
**When to use:** You need to work on multiple tasks simultaneously with complete code isolation between Claude Code instances.
**Tips:**
- Each worktree has its own independent file state, making it perfect for parallel Claude Code sessions
- Changes made in one worktree won’t affect others, preventing Claude instances from interfering with each other
- All worktrees share the same Git history and remote connections
- For long-running tasks, you can have Claude working in one worktree while you continue development in another
- Use descriptive directory names to easily identify which task each worktree is for
- Remember to initialize your development environment in each new worktree according to your project’s setup. Depending on your stack, this might include:
- JavaScript projects: Running dependency installation (`npm install`, `yarn`)
- Python projects: Setting up virtual environments or installing with package managers
- Other languages: Following your project’s standard setup process
---
Claude Code reference implementation
Clone our development container reference implementation.
[View original](https://github.com/anthropics/claude-code/tree/main/.devcontainer)