The interactive explorer works best on a larger screen. See the file reference table below, or .
}
{}
{}
;
};
Claude Code reads instructions, settings, skills, subagents, and memory from your project directory and from `~/.claude` in your home directory. Commit project files to git to share them with your team; files in `~/.claude` are personal configuration that applies across all your projects.
On Windows, `~/.claude` resolves to `%USERPROFILE%\.claude`. If you set [`CLAUDE_CONFIG_DIR`](env-vars-5c624d392b.md), every `~/.claude` path on this page lives under that directory instead.
Most users only edit `CLAUDE.md` and `settings.json`. The rest of the directory is optional: add skills, rules, or subagents as you need them.
## Explore the directory
Click files in the tree to see what each one does, when it loads, and an example.
{['project', 'global'].map(root => )}
{tree.children.map(node => renderNode(node, 0))}
{selected.label} selected
{}
}
{}
{selected.description &&
}
{}
{selected.tips && selected.tips.length > 0 &&
}
{}
{selected.example &&
}
{selected.path.map((seg, i) =>
{seg.replace(/\/$/, '')}
{i < selected.path.length - 1 && / }
)}
{}
{renderIcon(selected.icon, selected.color, 24)}
{}
{selected.note && {selected.label}
{selected.oneLiner && {selected.oneLiner}
}
{[selected.autogen && 'autogen', selected.badge].filter(Boolean).map(k => {
const s = BADGE_STYLES[k];
if (!s) return null;
return {s.label};
})}
{selected.note}
}
{}
{selected.when && When it loads
{selected.when}
{Array.isArray(selected.description) ? selected.description.map((para, i) =>
}
{}
{selected.contains && selected.contains.length > 0 && {para}
) : selected.description}
Common keys
{selected.contains.map((item, i) =>
●
{item}
)}
Tips
{selected.tips.map((tip, i) =>
●
{tip}
)}
{selected.exampleIntro &&
}
{}
{selected.docsLink && Full docs →}
{}
{selected.children && selected.children.length > 0 &&
{selected.exampleIntro}
}
{selected.label}
{selected.example}
Contents
{selected.children.map(child => )}
[`/rename`](built-in-commands-claude-code-docs.md) changes the name mid-session and also shows it on the prompt bar | `claude -n "my-feature-work"` | | `--no-chrome` | Disable [Chrome browser integration](../03-IDE-Integrations/use-claude-code-with-chrome-beta-claude-code-docs-4f2f5a5a96.md) for this session | `claude --no-chrome` | | `--no-session-persistence` | Disable session persistence so sessions are not saved to disk and cannot be resumed (print mode only) | `claude -p --no-session-persistence "query"` | | `--output-format` | Specify output format for print mode (options: `text`, `json`, `stream-json`) | `claude -p "query" --output-format json` | | `--permission-mode` | Begin in a specified [permission mode](permission-modes-c83d6eff7e.md). Accepts `default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, or `bypassPermissions`. Overrides `defaultMode` from settings files | `claude --permission-mode plan` | | `--permission-prompt-tool` | Specify an MCP tool to handle permission prompts in non-interactive mode | `claude -p --permission-prompt-tool mcp_auth_tool "query"` | | `--plugin-dir` | Load plugins from a directory for this session only. Each flag takes one path. Repeat the flag for multiple directories: `--plugin-dir A --plugin-dir B` | `claude --plugin-dir ./my-plugins` | | `--print`, `-p` | Print response without interactive mode (see [Agent SDK documentation](/en/agent-sdk/overview) for programmatic usage details) | `claude -p "query"` | | `--remote` | Create a new [web session](claude-code-on-the-web-69d53821d4.md) on claude.ai with the provided task description | `claude --remote "Fix the login bug"` | | `--remote-control`, `--rc` | Start an interactive session with [Remote Control](/en/remote-control#start-a-remote-control-session) enabled so you can also control it from claude.ai or the Claude app. Optionally pass a name for the session | `claude --remote-control "My Project"` | | `--remote-control-session-name-prefix
Showing {visibleCount} of {totalCount} clients
{hasFilters && }
filterStore.setState({
searchText: e.target.value
})} className="w-full px-3 py-2 border border-gray-300 dark:border-gray-600 rounded-lg bg-white dark:bg-gray-800 text-gray-900 dark:text-gray-100 placeholder-gray-500 dark:placeholder-gray-400 focus:outline-none focus:ring-2 focus:ring-primary focus:border-transparent" />
Filter by features:
{FEATURES.map(feature => )}
{supports &&
{children}
{hasOverflow && }
Saved as `alwaysThinkingEnabled` in `~/.claude/settings.json` | | **Limit token budget** | Set [`MAX_THINKING_TOKENS`](env-vars-5c624d392b.md) environment variable | Limit the thinking budget to a specific number of tokens. On models with adaptive reasoning, only `0` applies unless adaptive reasoning is disabled. Example: `export MAX_THINKING_TOKENS=10000` | To view Claude's thinking process, press `Ctrl+O` to toggle verbose mode and see the internal reasoning displayed as gray italic text. ### How extended thinking works Extended thinking controls how much internal reasoning Claude performs before responding. More thinking provides more space to explore solutions, analyze edge cases, and self-correct mistakes. On [models that support effort](/en/model-config#adjust-effort-level), thinking uses adaptive reasoning: the model dynamically allocates thinking tokens based on the effort level you select. This is the recommended way to tune the tradeoff between speed and reasoning depth. If you want Claude to think more or less often than your effort level would otherwise produce, you can also say so directly in your prompt or in `CLAUDE.md`. With older models, thinking uses a fixed token budget drawn from your output allocation. The budget varies by model; see [`MAX_THINKING_TOKENS`](env-vars-5c624d392b.md) for per-model ceilings. You can limit the budget with that environment variable, or disable thinking entirely via `/config` or the `Option+T`/`Alt+T` toggle. On models with adaptive reasoning, `MAX_THINKING_TOKENS` only applies when set to `0` to disable thinking, or when `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` reverts the model to the fixed budget. `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` applies to Opus 4.6 and Sonnet 4.6 only. Opus 4.7 always uses adaptive reasoning and does not support a fixed thinking budget. See [environment variables](env-vars-5c624d392b.md).
{part} : part);
if (!mounted) return null;
return <>
This interactive timeline works best on a larger screen. See the written breakdown below for the same concepts.
setHasInteracted(true)} style={isFullscreen ? {
height: '100vh',
borderRadius: 0,
display: 'flex',
flexDirection: 'column'
} : {}}>
{}
{}
{Math.round(time * 100)}%
;
};
Claude Code's context window holds everything Claude knows about your session: your instructions, the files it reads, its own responses, and content that never appears in your terminal. The timeline below walks through what loads and when. See [the written breakdown](#what-the-timeline-shows) for the same content as a list.
>
> Use this file to discover all available pages before exploring further.
Remote Control is in research preview and available on all plans. On Team and Enterprise, it is off by default until an admin enables the Remote Control toggle in [Claude Code admin settings](https://claude.ai/admin-settings/claude-code).
Remote Control connects [claude.ai/code](https://claude.ai/code) or the Claude app for [iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) and [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude) to a Claude Code session running on your machine. Start a task at your desk, then pick it up from your phone on the couch or a browser on another computer. When you start a Remote Control session on your machine, Claude keeps running locally the entire time, so nothing moves to the cloud. With Remote Control you can:
- **Use your full local environment remotely**: your filesystem, [MCP servers](/docs/en/mcp), tools, and project configuration all stay available, and typing `@` autocompletes file paths from your local project
- **Work from both surfaces at once**: the conversation stays in sync across all connected devices, so you can send messages from your terminal, browser, and phone interchangeably
- **Survive interruptions**: if your laptop sleeps or your network drops, the session reconnects automatically when your machine comes back online
Unlike [Claude Code on the web](/docs/en/claude-code-on-the-web), which runs on cloud infrastructure, Remote Control sessions run directly on your machine and interact with your local filesystem. The web and mobile interfaces are just a window into that local session.
Remote Control requires Claude Code v2.1.51 or later. Check your version with `claude --version`.
This page covers setup, how to start and connect to sessions, and how Remote Control compares to Claude Code on the web.
Requirements
Before using Remote Control, confirm that your environment meets these conditions:
- **Subscription**: available on Pro, Max, Team, and Enterprise plans. API keys are not supported. On Team and Enterprise, an admin must first enable the Remote Control toggle in [Claude Code admin settings](https://claude.ai/admin-settings/claude-code).
- **Authentication**: run `claude` and use `/login` to sign in through claude.ai if you haven’t already.
- **Workspace trust**: run `claude` in your project directory at least once to accept the workspace trust dialog.
Start a Remote Control session
You can start a Remote Control session from the CLI or the VS Code extension. The CLI offers three invocation modes; VS Code uses the `/remote-control` command.
- Server mode
- Interactive session
- From an existing session
- VS Code
Navigate to your project directory and run:
```python
claude remote-control
```
The process stays running in your terminal in server mode, waiting for remote connections. It displays a session URL you can use to [connect from another device](#connect-from-another-device), and you can press spacebar to show a QR code for quick access from your phone. While a remote session is active, the terminal shows connection status and tool activity.Available flags:
[TABLE]
To start a normal interactive Claude Code session with Remote Control enabled, use the `--remote-control` flag (or `--rc`):
```python
claude --remote-control
```
Optionally pass a name for the session:
```python
claude --remote-control "My Project"
```
This gives you a full interactive session in your terminal that you can also control from claude.ai or the Claude app. Unlike `claude remote-control` (server mode), you can type messages locally while the session is also available remotely.
If you’re already in a Claude Code session and want to continue it remotely, use the `/remote-control` (or `/rc`) command:
```python
/remote-control
```
Pass a name as an argument to set a custom session title:
```python
/remote-control My Project
```
This starts a Remote Control session that carries over your current conversation history and displays a session URL and QR code you can use to [connect from another device](#connect-from-another-device). The `--verbose`, `--sandbox`, and `--no-sandbox` flags are not available with this command.
In the [Claude Code VS Code extension](/docs/en/vs-code), type `/remote-control` or `/rc` in the prompt box, or open the command menu with `/` and select it. Requires Claude Code v2.1.79 or later.
```python
/remote-control
```
A banner appears above the prompt box showing connection status. Once connected, click **Open in browser** in the banner to go directly to the session, or find it in the session list at [claude.ai/code](https://claude.ai/code). The session URL is also posted in the conversation.To disconnect, click the close icon on the banner or run `/remote-control` again.Unlike the CLI, the VS Code command does not accept a name argument or display a QR code. The session title is derived from your conversation history or first prompt.
Connect from another device
Once a Remote Control session is active, you have a few ways to connect from another device:
- **Open the session URL** in any browser to go directly to the session on [claude.ai/code](https://claude.ai/code).
- **Scan the QR code** shown alongside the session URL to open it directly in the Claude app. With `claude remote-control`, press spacebar to toggle the QR code display.
- **Open [claude.ai/code](https://claude.ai/code) or the Claude app** and find the session by name in the session list. In the Claude mobile app, tap **Code** in the navigation to reach the session list. Remote Control sessions show a computer icon with a green status dot when online.
The remote session title is chosen in this order:
1. The name you passed to `--name`, `--remote-control`, or `/remote-control`
2. The title you set with `/rename`
3. The last meaningful message in existing conversation history
4. An auto-generated name like `myhost-graceful-unicorn`, where `myhost` is your machine’s hostname or the prefix you set with `--remote-control-session-name-prefix`
If you didn’t set an explicit name, the title updates to reflect your prompt once you send one. If the environment already has an active session, you’ll be asked whether to continue it or start a new one. If you don’t have the Claude app yet, use the `/mobile` command inside Claude Code to display a download QR code for [iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) or [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude).
Enable Remote Control for all sessions
By default, Remote Control only activates when you explicitly run `claude remote-control`, `claude --remote-control`, or `/remote-control`. To enable it automatically for every interactive session, run `/config` inside Claude Code and set **Enable Remote Control for all sessions** to `true`. Set it back to `false` to disable. In the Desktop app, you can also toggle this from **Settings → Claude Code → Enable remote control by default**. With this setting on, each interactive Claude Code process registers one remote session. If you run multiple instances, each one gets its own environment and session. To run multiple concurrent sessions from a single process, use [server mode](#start-a-remote-control-session) instead.
Connection and security
Your local Claude Code session makes outbound HTTPS requests only and never opens inbound ports on your machine. When you start Remote Control, it registers with the Anthropic API and polls for work. When you connect from another device, the server routes messages between the web or mobile client and your local session over a streaming connection. All traffic travels through the Anthropic API over TLS, the same transport security as any Claude Code session. The connection uses multiple short-lived credentials, each scoped to a single purpose and expiring independently.
Remote Control vs Claude Code on the web
Remote Control and [Claude Code on the web](/docs/en/claude-code-on-the-web) both use the claude.ai/code interface. The key difference is where the session runs: Remote Control executes on your machine, so your local MCP servers, tools, and project configuration stay available. Claude Code on the web executes in Anthropic-managed cloud infrastructure. Use Remote Control when you’re in the middle of local work and want to keep going from another device. Use Claude Code on the web when you want to kick off a task without any local setup, work on a repo you don’t have cloned, or run multiple tasks in parallel.
Mobile push notifications
When Remote Control is active, Claude can send push notifications to your phone. Claude decides when to push. It typically sends one when a long-running task finishes or when it needs a decision from you to continue. You can also request a push in your prompt, for example `notify me when the tests finish`. Beyond the on/off toggle below, there is no per-event configuration.
Mobile push notifications require Claude Code v2.1.110 or later.
To set up mobile push notifications:
1
Install the Claude mobile app
Download the Claude app for [iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) or [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude).
2
Sign in with your Claude Code account
Use the same account and organization you use for Claude Code in the terminal.
3
Allow notifications
Accept the notification permission prompt from the operating system.
4
Enable push in Claude Code
In your terminal, run `/config` and enable **Push when Claude decides**.
If notifications don’t arrive:
- If `/config` shows **No mobile registered**, open the Claude app on your phone so it can refresh its push token. The warning clears the next time Remote Control connects.
- On iOS, Focus modes and notification summaries can suppress or delay pushes. Check Settings → Notifications → Claude.
- On Android, aggressive battery optimization can delay delivery. Exempt the Claude app from battery optimization in system settings.
Limitations
- **One remote session per interactive process**: outside of server mode, each Claude Code instance supports one remote session at a time. Use [server mode](#start-a-remote-control-session) to run multiple concurrent sessions from a single process.
- **Local process must keep running**: Remote Control runs as a local process. If you close the terminal, quit VS Code, or otherwise stop the `claude` process, the session ends.
- **Extended network outage**: if your machine is awake but unable to reach the network for more than roughly 10 minutes, the session times out and the process exits. Run `claude remote-control` again to start a new session.
- **Ultraplan disconnects Remote Control**: starting an [ultraplan](/docs/en/ultraplan) session disconnects any active Remote Control session because both features occupy the claude.ai/code interface and only one can be connected at a time.
- **Some commands are local-only**: commands that open an interactive picker in the terminal, such as `/mcp`, `/plugin`, or `/resume`, work only from the local CLI. Commands that produce text output, including `/compact`, `/clear`, `/context`, `/usage`, `/exit`, `/usage-credits`, `/recap`, and `/reload-plugins`, work from mobile and web.
Troubleshooting
”Remote Control requires a claude.ai subscription”
You’re not authenticated with a claude.ai account. Run `claude auth login` and choose the claude.ai option. If `ANTHROPIC_API_KEY` is set in your environment, unset it first.
”Remote Control requires a full-scope login token”
You’re authenticated with a long-lived token from `claude setup-token` or the `CLAUDE_CODE_OAUTH_TOKEN` environment variable. These tokens are limited to inference-only and cannot establish Remote Control sessions. Run `claude auth login` to authenticate with a full-scope session token instead.
”Unable to determine your organization for Remote Control eligibility”
Your cached account information is stale or incomplete. Run `claude auth login` to refresh it.
”Remote Control is not yet enabled for your account”
The eligibility check can fail with certain environment variables present:
- `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` or `DISABLE_TELEMETRY`: unset them and try again.
- `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, or `CLAUDE_CODE_USE_FOUNDRY`: Remote Control requires claude.ai authentication and does not work with third-party providers.
If none of these are set, run `/logout` then `/login` to refresh.
”Remote Control is disabled by your organization’s policy”
This error has four distinct causes. Run `/status` first to see which login method and subscription you’re using.
- **You’re authenticated with an API key or Console account**: Remote Control requires claude.ai OAuth. Run `/login` and choose the claude.ai option. If `ANTHROPIC_API_KEY` is set in your environment, unset it.
- **Your Team or Enterprise admin hasn’t enabled it**: Remote Control is off by default on these plans. An admin can enable it at [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) by turning on the **Remote Control** toggle. This toggle is a server-side organization setting.
- **The admin toggle is grayed out**: your organization has a data retention or compliance configuration that is incompatible with Remote Control. This cannot be changed from the admin panel. Contact Anthropic support to discuss options.
- **The error mentions `disableRemoteControl`**: your IT administrator has disabled Remote Control on this device through [managed settings](/docs/en/settings#settings-files), independent of the organization-wide toggle.
”Remote credentials fetch failed”
Claude Code could not obtain a short-lived credential from the Anthropic API to establish the connection. Re-run with `--verbose` to see the full error:
```python
claude remote-control --verbose
```
Common causes:
- Not signed in: run `claude` and use `/login` to authenticate with your claude.ai account. API key authentication is not supported for Remote Control.
- Network or proxy issue: a firewall or proxy may be blocking the outbound HTTPS request. Remote Control requires access to the Anthropic API on port 443.
- Session creation failed: if you also see `Session creation failed — see debug log`, the failure happened earlier in setup. Check that your subscription is active.
Choose the right approach
Claude Code offers several ways to work when you’re not at your terminal. They differ in what triggers the work, where Claude runs, and how much you need to set up.
| | Trigger | Claude runs on | Setup | Best for |
|:----------------------------------------------------|:-----------------------------------------------------------------------------------------------|:------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------|
| [Dispatch](/docs/en/desktop#sessions-from-dispatch) | Message a task from the Claude mobile app | Your machine (Desktop) | [Pair the mobile app with Desktop](https://support.claude.com/en/articles/13947068) | Delegating work while you’re away, minimal setup |
| [Remote Control](/docs/en/remote-control) | Drive a running session from [claude.ai/code](https://claude.ai/code) or the Claude mobile app | Your machine (CLI or VS Code) | Run `claude remote-control` | Steering in-progress work from another device |
| [Channels](/docs/en/channels) | Push events from a chat app like Telegram or Discord, or your own server | Your machine (CLI) | [Install a channel plugin](/docs/en/channels#quickstart) or [build your own](/docs/en/channels-reference) | Reacting to external events like CI failures or chat messages |
| [Slack](/docs/en/slack) | Mention `@Claude` in a team channel | Anthropic cloud | [Install the Slack app](/docs/en/slack#setting-up-claude-code-in-slack) with [Claude Code on the web](/docs/en/claude-code-on-the-web) enabled | PRs and reviews from team chat |
| [Scheduled tasks](/docs/en/scheduled-tasks) | Set a schedule | [CLI](/docs/en/scheduled-tasks), [Desktop](/docs/en/desktop-scheduled-tasks), or [cloud](/docs/en/routines) | Pick a frequency | Recurring automation like daily reviews |
Related resources
- [Claude Code on the web](/docs/en/claude-code-on-the-web): run sessions in Anthropic-managed cloud environments instead of on your machine
- [Ultraplan](/docs/en/ultraplan): launch a cloud planning session from your terminal and review the plan in your browser
- [Channels](/docs/en/channels): forward Telegram, Discord, or iMessage into a session so Claude reacts to messages while you’re away
- [Dispatch](/docs/en/desktop#sessions-from-dispatch): message a task from your phone and it can spawn a Desktop session to handle it
- [Authentication](/docs/en/authentication): set up `/login` and manage credentials for claude.ai
- [CLI reference](/docs/en/cli-reference): full list of flags and commands including `claude remote-control`
- [Security](/docs/en/security): how Remote Control sessions fit into the Claude Code security model
- [Data usage](/docs/en/data-usage): what data flows through the Anthropic API during local and remote sessions
---
## costs-32f91ab9ba.md
> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Manage costs effectively
> Track token usage, set team spend limits, and reduce Claude Code costs with context management, model selection, extended thinking settings, and preprocessing hooks.
Claude Code charges by API token consumption. For subscription plan pricing (Pro, Max, Team, Enterprise), see [claude.com/pricing](https://claude.com/pricing). Per-developer costs vary widely based on model selection, codebase size, and usage patterns such as running multiple instances or automation.
Across enterprise deployments, the average cost is around \$13 per developer per active day and \$150-250 per developer per month, with costs remaining below \$30 per active day for 90% of users. To estimate spend for your own team, start with a small pilot group and use the tracking tools below to establish a baseline before wider rollout.
This page covers how to [track your costs](#track-your-costs), [manage costs for teams](#managing-costs-for-teams), and [reduce token usage](#reduce-token-usage).
## Track your costs
### Using the `/usage` command
The Session block in `/usage` shows API token usage and is intended for API users. Claude Max and Pro subscribers have usage included in their subscription, so the session cost figure isn't relevant for billing purposes. Subscribers see plan usage bars and activity stats on the same screen.
The `/usage` command provides detailed token usage statistics for your current session. The dollar figure is an estimate computed locally from token counts and may differ from your actual bill. For authoritative billing, see the Usage page in the [Claude Console](https://platform.claude.com/usage).
```text theme={null}
Total cost: $0.55
Total duration (API): 6m 19.7s
Total duration (wall): 6h 33m 10.2s
Total code changes: 0 lines added, 0 lines removed
```
## Managing costs for teams
When using Claude API, you can [set workspace spend limits](../04-API-Reference/Guides/build-with-claude-workspaces-12135e8f23.md#workspace-limits) on the total Claude Code workspace spend. Admins can [view cost and usage reporting](../04-API-Reference/Guides/build-with-claude-workspaces-12135e8f23.md#usage-and-cost-tracking) in the Console.
When you first authenticate Claude Code with your Claude Console account, a workspace called "Claude Code" is automatically created for you. This workspace provides centralized cost tracking and management for all Claude Code usage in your organization. You cannot create API keys for this workspace; it is exclusively for Claude Code authentication and usage.
For organizations with custom rate limits, Claude Code traffic in this workspace counts toward your organization's overall API rate limits. You can set a [workspace rate limit](../04-API-Reference/Other/api-rate-limits-28d3302987.md#setting-lower-limits-for-workspaces) on this workspace's Limits page in the Claude Console to cap Claude Code's share and protect other production workloads.
On Bedrock, Vertex, and Foundry, Claude Code does not send metrics from your cloud. To get cost metrics, several large enterprises reported using [LiteLLM](/en/llm-gateway#litellm-configuration), which is an open-source tool that helps companies [track spend by key](https://docs.litellm.ai/docs/proxy/virtual_keys#tracking-spend). This project is unaffiliated with Anthropic and has not been audited for security.
### Rate limit recommendations
When setting up Claude Code for teams, consider these Token Per Minute (TPM) and Request Per Minute (RPM) per-user recommendations based on your organization size:
| Team size | TPM per user | RPM per user |
| ------------- | ------------ | ------------ |
| 1-5 users | 200k-300k | 5-7 |
| 5-20 users | 100k-150k | 2.5-3.5 |
| 20-50 users | 50k-75k | 1.25-1.75 |
| 50-100 users | 25k-35k | 0.62-0.87 |
| 100-500 users | 15k-20k | 0.37-0.47 |
| 500+ users | 10k-15k | 0.25-0.35 |
For example, if you have 200 users, you might request 20k TPM for each user, or 4 million total TPM (200\*20,000 = 4 million).
The TPM per user decreases as team size grows because fewer users tend to use Claude Code concurrently in larger organizations. These rate limits apply at the organization level, not per individual user, which means individual users can temporarily consume more than their calculated share when others aren't actively using the service.
If you anticipate scenarios with unusually high concurrent usage (such as live training sessions with large groups), you may need higher TPM allocations per user.
### Agent team token costs
[Agent teams](../09-Agents-Patterns/agent-teams-e29da6ed1b.md) spawn multiple Claude Code instances, each with its own context window. Token usage scales with the number of active teammates and how long each one runs.
To keep agent team costs manageable:
* Use Sonnet for teammates. It balances capability and cost for coordination tasks.
* Keep teams small. Each teammate runs its own context window, so token usage is roughly proportional to team size.
* Keep spawn prompts focused. Teammates load CLAUDE.md, MCP servers, and skills automatically, but everything in the spawn prompt adds to their context from the start.
* Clean up teams when work is done. Active teammates continue consuming tokens even if idle.
* Agent teams are disabled by default. Set `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in your [settings.json](claude-code-settings-claude-code-docs-d4420b4b52.md) or environment to enable them. See [enable agent teams](/en/agent-teams#enable-agent-teams).
## Reduce token usage
Token costs scale with context size: the more context Claude processes, the more tokens you use. Claude Code automatically optimizes costs through prompt caching (which reduces costs for repeated content like system prompts) and auto-compaction (which summarizes conversation history when approaching context limits).
The following strategies help you keep context small and reduce per-message costs.
### Manage context proactively
Use `/usage` to check your current token usage, or [configure your status line](/en/statusline#context-window-usage) to display it continuously.
* **Clear between tasks**: Use `/clear` to start fresh when switching to unrelated work. Stale context wastes tokens on every subsequent message. Use `/rename` before clearing so you can easily find the session later, then `/resume` to return to it.
* **Add custom compaction instructions**: `/compact Focus on code samples and API usage` tells Claude what to preserve during summarization.
You can also customize compaction behavior in your CLAUDE.md:
```markdown theme={null}
# Compact instructions
When you are using compact, please focus on test output and code changes
```
### Choose the right model
Sonnet handles most coding tasks well and costs less than Opus. Reserve Opus for complex architectural decisions or multi-step reasoning. Use `/model` to switch models mid-session, or set a default in `/config`. For simple subagent tasks, specify `model: haiku` in your [subagent configuration](/en/sub-agents#choose-a-model).
### Reduce MCP server overhead
MCP tool definitions are [deferred by default](/en/mcp#scale-with-mcp-tool-search), so only tool names enter context until Claude uses a specific tool. Run `/context` to see what's consuming space.
* **Prefer CLI tools when available**: Tools like `gh`, `aws`, `gcloud`, and `sentry-cli` are still more context-efficient than MCP servers because they don't add any per-tool listing. Claude can run CLI commands directly.
* **Disable unused servers**: Run `/mcp` to see configured servers and disable any you're not actively using.
### Install code intelligence plugins for typed languages
[Code intelligence plugins](/en/discover-plugins#code-intelligence) give Claude precise symbol navigation instead of text-based search, reducing unnecessary file reads when exploring unfamiliar code. A single "go to definition" call replaces what might otherwise be a grep followed by reading multiple candidate files. Installed language servers also report type errors automatically after edits, so Claude catches mistakes without running a compiler.
### Offload processing to hooks and skills
Custom [hooks](../07-Hooks/hooks-9168ed62a4.md) can preprocess data before Claude sees it. Instead of Claude reading a 10,000-line log file to find errors, a hook can grep for `ERROR` and return only matching lines, reducing context from tens of thousands of tokens to hundreds.
A [skill](../08-Plugins-Skills/extend-claude-with-skills-claude-code-docs.md) can give Claude domain knowledge so it doesn't have to explore. For example, a "codebase-overview" skill could describe your project's architecture, key directories, and naming conventions. When Claude invokes the skill, it gets this context immediately instead of spending tokens reading multiple files to understand the structure.
For example, this PreToolUse hook filters test output to show only failures:
Add this to your [settings.json](/en/settings#settings-files) to run the hook before every Bash command:
```json theme={null}
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "~/.claude/hooks/filter-test-output.sh"
}
]
}
]
}
}
```
The hook calls this script, which checks if the command is a test runner and modifies it to show only failures:
```bash theme={null}
#!/bin/bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command')
# If running tests, filter to show only failures
if [[ "$cmd" =~ ^(npm test|pytest|go test) ]]; then
filtered_cmd="$cmd 2>&1 | grep -A 5 -E '(FAIL|ERROR|error:)' | head -100"
echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\",\"updatedInput\":{\"command\":\"$filtered_cmd\"}}}"
else
echo "{}"
fi
```
### Move instructions from CLAUDE.md to skills
Your [CLAUDE.md](how-claude-remembers-your-project-claude-code-docs-f1c064262d.md) file is loaded into context at session start. If it contains detailed instructions for specific workflows (like PR reviews or database migrations), those tokens are present even when you're doing unrelated work. [Skills](../08-Plugins-Skills/extend-claude-with-skills-claude-code-docs.md) load on-demand only when invoked, so moving specialized instructions into skills keeps your base context smaller. Aim to keep CLAUDE.md under 200 lines by including only essentials.
### Adjust extended thinking
Extended thinking is enabled by default because it significantly improves performance on complex planning and reasoning tasks. Thinking tokens are billed as output tokens, and the default budget can be tens of thousands of tokens per request depending on the model. For simpler tasks where deep reasoning isn't needed, you can reduce costs by lowering the [effort level](/en/model-config#adjust-effort-level) with `/effort` or in `/model`, disabling thinking in `/config`, or lowering the budget with `MAX_THINKING_TOKENS=8000`.
### Delegate verbose operations to subagents
Running tests, fetching documentation, or processing log files can consume significant context. Delegate these to [subagents](/en/sub-agents#isolate-high-volume-operations) so the verbose output stays in the subagent's context while only a summary returns to your main conversation.
### Manage agent team costs
Agent teams use approximately 7x more tokens than standard sessions when teammates run in plan mode, because each teammate maintains its own context window and runs as a separate Claude instance. Keep team tasks small and self-contained to limit per-teammate token usage. See [agent teams](../09-Agents-Patterns/agent-teams-e29da6ed1b.md) for details.
### Write specific prompts
Vague requests like "improve this codebase" trigger broad scanning. Specific requests like "add input validation to the login function in auth.ts" let Claude work efficiently with minimal file reads.
### Work efficiently on complex tasks
For longer or more complex work, these habits help avoid wasted tokens from going down the wrong path:
* **Use plan mode for complex tasks**: Press Shift+Tab to enter [plan mode](/en/common-workflows#use-plan-mode-for-safe-code-analysis) before implementation. Claude explores the codebase and proposes an approach for your approval, preventing expensive re-work when the initial direction is wrong.
* **Course-correct early**: If Claude starts heading the wrong direction, press Escape to stop immediately. Use `/rewind` or double-tap Escape to restore conversation and code to a previous checkpoint.
* **Give verification targets**: Include test cases, paste screenshots, or define expected output in your prompt. When Claude can verify its own work, it catches issues before you need to request fixes.
* **Test incrementally**: Write one file, test it, then continue. This catches issues early when they're cheap to fix.
## Background token usage
Claude Code uses tokens for some background functionality even when idle:
* **Conversation summarization**: Background jobs that summarize previous conversations for the `claude --resume` feature
* **Command processing**: Some commands like `/usage` 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.
## Understanding changes in Claude Code behavior
Claude Code regularly receives updates that may change how features work, including cost reporting. Run `claude --version` to check your current version. For specific billing questions, contact Anthropic support through your [Console account](https://platform.claude.com/login).
---
## costs.md
# Manage costs effectively
Track token usage, set team spend limits, and reduce Claude Code costs with context management, model selection, extended thinking settings, and preprocessing hooks.
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. On average, Claude Code costs ~$100-200/developer per month with Sonnet 4.6.
## Track your costs
### Using the `/cost` command
> The `/cost` command shows API token usage and is intended for API users. Claude Max and Pro subscribers have usage included in their subscription, so `/cost` data isn't relevant for billing purposes. Subscribers can use `/stats` to view usage patterns.
```
Total cost: $0.55
Total duration (API): 6m 19.7s
Total duration (wall): 6h 33m 10.2s
Total code changes: 0 lines added, 0 lines removed
```
## Managing costs for teams
Set workspace spend limits on the total Claude Code workspace spend. Admins can view cost and usage reporting in the Console.
### Rate limit recommendations
| Team size | TPM per user | RPM per user |
| ------------- | ------------ | ------------ |
| 1-5 users | 200k-300k | 5-7 |
| 5-20 users | 100k-150k | 2.5-3.5 |
| 20-50 users | 50k-75k | 1.25-1.75 |
| 50-100 users | 25k-35k | 0.62-0.87 |
| 100-500 users | 15k-20k | 0.37-0.47 |
| 500+ users | 10k-15k | 0.25-0.35 |
### Agent team token costs
Agent teams spawn multiple Claude Code instances. Token usage scales with the number of active teammates.
- Use Sonnet for teammates
- Keep teams small (3-5)
- Keep spawn prompts focused
- Clean up teams when done
## Reduce token usage
### Manage context proactively
- Use `/clear` between tasks
- Use `/compact Focus on code samples and API usage` for custom compaction
- Customize compaction in CLAUDE.md
### Choose the right model
Sonnet handles most coding tasks well and costs less than Opus. Reserve Opus for complex architectural decisions. Use `/model` to switch mid-session.
### Reduce MCP server overhead
MCP tool definitions are deferred by default. Run `/context` to see what's consuming space. Prefer CLI tools (`gh`, `aws`) when available. Disable unused servers via `/mcp`.
### Install code intelligence plugins
Code intelligence plugins give Claude precise symbol navigation, reducing unnecessary file reads.
### Move instructions from CLAUDE.md to skills
Skills load on-demand only when invoked. Keep CLAUDE.md under 200 lines.
### Adjust extended thinking
Extended thinking is enabled by default. For simpler tasks, reduce with `/effort`, disable in `/config`, or lower the budget with `MAX_THINKING_TOKENS=8000`.
### Delegate verbose operations to subagents
Running tests, fetching docs, or processing logs can consume context. Delegate to subagents so verbose output stays in the subagent's context.
### Write specific prompts
Vague requests trigger broad scanning. Specific requests let Claude work efficiently with minimal file reads.
### Work efficiently on complex tasks
- Use plan mode (Shift+Tab) for complex tasks
- Course-correct early with Escape
- Give verification targets (test cases, screenshots)
- Test incrementally
## Background token usage
Claude Code uses tokens for background functionality even when idle:
- Conversation summarization for `claude --resume`
- Command processing for status checks
Typically under $0.04 per session.
## See Also
- [Agent teams](../09-Agents-Patterns/agent-teams.md)
- [Subagents](../09-Agents-Patterns/create-custom-subagents-claude-code-docs-7dc93e85c0.md)
- [Model configuration](model-config-ca429e15da.md)
---
## cowork-protocol-spec.md
# Claude Code CoWork Protocol Specification
Reverse-engineered from claude binaries 2.1.74-2.1.75 (2026-03-11 to 2026-03-14).
Source: `2.1.75_bunfs_extracted/src/entrypoints/cli.js` (14,697 lines)
## Table of Contents
1. [Architecture Overview](#architecture-overview)
2. [Client Type Identification](#client-type-identification)
3. [OAuth Configuration](#oauth-configuration)
4. [CLI Spawning — Flags & Environment](#cli-spawning)
5. [stdin Protocol (Caller → CLI)](#stdin-protocol)
6. [stdout Protocol (CLI → Caller)](#stdout-protocol)
7. [Session JSONL Format](#session-jsonl-format)
8. [Sessions API](#sessions-api)
9. [WebSocket Subscription](#websocket-subscription)
10. [CoWork-Specific Behavior](#cowork-specific-behavior)
11. [Agent Teams (Teammate Mode)](#agent-teams)
12. [Session Resume Paths](#session-resume-paths)
13. [sdkUrl & Session Ingress Transport](#sdkurl-session-ingress-transport)
14. [Session Creation API](#session-creation-api)
15. [Bridge Orchestrator](#bridge-orchestrator)
16. [Remaining Unknowns](#remaining-unknowns)
---
## Architecture Overview
All three interfaces (CLI terminal, Claude Desktop, claude.ai web) run the **same `claude` binary**.
Differences are purely in:
- How the process is spawned (TTY vs child_process with piped stdio)
- Which env vars are set (entrypoint, auth mechanism, persistence flags)
- Whether stdin/stdout uses interactive Ink/React rendering vs stream-json protocol
- Whether persistence is local-only or dual-write to Sessions API
```
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Claude │ │ Claude Code │ │ claude.ai │
│ Desktop │ │ CLI │ │ Web │
│ (Electron) │ │ (Terminal) │ │ (Browser) │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
│ │ │
│ ENTRYPOINT= │ (unset→"cli") │ ENVIRONMENT_KIND=
│ "claude-desktop" │ │ "bridge"
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ claude CLI │ │ claude CLI │ │ Bridge │
│ (child proc) │ │ (direct) │ │ (spawner) │
│ stdin/stdout │ │ TTY I/O │ │ Yz8() │
│ stream-json │ │ interactive │ └──────┬───────┘
└──────┬───────┘ └──────┬───────┘ │
│ │ ┌──────▼───────┐
│ │ │ claude CLI │
│ │ │ --print │
│ │ │ stdin/stdout │
│ │ │ stream-json │
│ │ └──────┬───────┘
▼ ▼ ▼
┌─────────────────────────────────────────────────┐
│ Anthropic API │
│ /v1/messages (Claude model) │
└────────────────────┬────────────────────────────┘
│
┌────────────────────▼────────────────────────────┐
│ Sessions API │
│ /v1/sessions/ (CRUD) │
│ /v1/sessions//events (event log) │
│ /v1/sessions/ws//subscribe (WebSocket) │
│ /v1/code/sessions//teleport-events │
│ /v1/session_ingress/session/ (legacy) │
└─────────────────────────────────────────────────┘
```
---
## Client Type Identification
Determined at startup from `CLAUDE_CODE_ENTRYPOINT`:
| CLAUDE_CODE_ENTRYPOINT | clientType | Context |
|------------------------|-----------------|--------------------------------|
| `"sdk-cli"` | `"sdk-cli"` | Agent SDK invocation |
| `"claude-vscode"` | `"claude-vscode"` | VS Code extension |
| `"local-agent"` | `"local-agent"` | Desktop app local agent mode |
| `"claude-desktop"` | `"claude-desktop"` | Claude Desktop (Electron) |
| `"remote"` (or token present) | `"remote"` | Remote / web session |
| (unset) | `"cli"` | Bare terminal |
Additional identity in API User-Agent:
```
CLAUDE_AGENT_SDK_VERSION → "agent-sdk/X.Y.Z"
CLAUDE_AGENT_SDK_CLIENT_APP → "client-app/"
User-Agent: "claude-code/2.1.74 (sdk-cli, agent-sdk/1.0.0, client-app/myapp)"
```
When `CLAUDE_CODE_ENVIRONMENT_KIND=bridge`, session source is set to `"remote-control"`.
---
## OAuth Configuration
### Production Endpoints (s_L)
```
BASE_API_URL: https://api.anthropic.com
CLAUDE_AI_AUTHORIZE_URL: https://claude.ai/oauth/authorize
CONSOLE_AUTHORIZE_URL: https://platform.claude.com/oauth/authorize
TOKEN_URL: https://platform.claude.com/v1/oauth/token
API_KEY_URL: https://api.anthropic.com/api/oauth/claude_cli/create_api_key
ROLES_URL: https://api.anthropic.com/api/oauth/claude_cli/roles
CONSOLE_SUCCESS_URL: https://platform.claude.com/buy_credits?returnUrl=/oauth/code/success%3Fapp%3Dclaude-code
CLAUDEAI_SUCCESS_URL: https://platform.claude.com/oauth/code/success?app=claude-code
MANUAL_REDIRECT_URL: https://platform.claude.com/oauth/code/callback
CLIENT_ID: 9d1c250a-e61b-44d9-88ed-5944d1962f5e
MCP_PROXY_URL: https://mcp-proxy.anthropic.com
MCP_PROXY_PATH: /v1/mcp/{server_id}
```
Overridable via:
- `CLAUDE_CODE_CUSTOM_OAUTH_URL` — replaces all URLs with custom base
- `CLAUDE_CODE_OAUTH_CLIENT_ID` — replaces CLIENT_ID
### Scopes
```
Claude.ai flow (eH$):
user:profile
user:inference
user:sessions:claude_code
user:mcp_servers
Console flow (HML):
org:create_api_key
user:profile
```
### Token Exchange
```http
POST https://platform.claude.com/v1/oauth/token
Content-Type: application/json
{
"grant_type": "authorization_code",
"redirect_uri": "http://localhost:/callback" | MANUAL_REDIRECT_URL,
"client_id": "9d1c250a-e61b-44d9-88ed-5944d1962f5e",
"code_verifier": "",
"state": ""
}
```
### Token Refresh
```http
POST https://platform.claude.com/v1/oauth/token
Content-Type: application/json
{
"grant_type": "refresh_token",
"refresh_token": "",
"client_id": "9d1c250a-e61b-44d9-88ed-5944d1962f5e",
"scope": "user:profile user:inference user:sessions:claude_code user:mcp_servers"
}
```
Beta header for all Sessions API calls: `anthropic-beta: oauth-2025-04-20`
### Desktop App Auth
Desktop uses file descriptor auth instead of env vars:
```
CLAUDE_CODE_WEBSOCKET_AUTH_FILE_DESCRIPTOR=
```
Token read from `/proc/self/fd/` (inherited FD from parent Electron process).
---
## CLI Spawning
### Flags for Non-Interactive (Print) Mode
```bash
claude --print \
--session-id \
--input-format stream-json \
--output-format stream-json \
--replay-user-messages \
[--sdk-url ] \
[--verbose] \
[--debug-file ] \
[--permission-mode ]
```
### Environment Variables Set by Bridge
```bash
CLAUDE_CODE_ENVIRONMENT_KIND=bridge # identifies runtime context
CLAUDE_CODE_SESSION_ACCESS_TOKEN= # OAuth bearer for API
CLAUDE_CODE_POST_FOR_SESSION_INGRESS_V2=1 # enable remote persistence
CLAUDE_CODE_OAUTH_TOKEN= # explicitly cleared
CLAUDE_CODE_FORCE_SANDBOX=1 # if sandbox enabled
CLAUDE_CODE_USE_CCR_V2=1 # if using CCR v2
CLAUDE_CODE_WORKER_EPOCH= # worker generation counter
```
### CoWork Tab Additional Vars
```bash
CLAUDE_CODE_IS_COWORK=1 # eager flush at every turn
CLAUDE_CODE_USE_COWORK_PLUGINS=1 # cowork_plugins/ + cowork_settings.json
```
### All Relevant Environment Variables
| Variable | Purpose |
|----------|---------|
| `CLAUDE_CODE_ENTRYPOINT` | Client identity: sdk-cli, claude-vscode, local-agent, claude-desktop, remote |
| `CLAUDE_CODE_ENVIRONMENT_KIND` | Runtime context: bridge, byoc, anthropic_cloud |
| `CLAUDE_CODE_IS_COWORK` | Eager session flush at every turn boundary |
| `CLAUDE_CODE_USE_COWORK_PLUGINS` | Plugin dir → cowork_plugins/, settings → cowork_settings.json |
| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | OAuth token for Sessions API (refreshable via stdin) |
| `CLAUDE_CODE_POST_FOR_SESSION_INGRESS_V2` | Enable dual-write: local JSONL + remote Sessions API |
| `CLAUDE_CODE_USE_CCR_V2` | CCR v2 protocol |
| `CLAUDE_CODE_WORKER_EPOCH` | Worker generation counter for CCR v2 |
| `CLAUDE_CODE_FORCE_SANDBOX` | Force sandbox mode |
| `CLAUDE_CODE_EAGER_FLUSH` | Force eager session flush (same effect as IS_COWORK for flushing) |
| `CLAUDE_COWORK_MEMORY_PATH_OVERRIDE` | Override auto-memory directory (shared memory path) |
| `CLAUDE_CODE_REMOTE` | Remote mode flag |
| `CLAUDE_CODE_REMOTE_MEMORY_DIR` | Memory dir in remote mode |
| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | Enable agent-teams feature |
| `CLAUDE_CODE_PLAN_MODE_REQUIRED` | Force plan-before-act for teammates |
| `CLAUDE_CODE_WEBSOCKET_AUTH_FILE_DESCRIPTOR` | FD-based auth for Desktop app |
| `CLAUDE_AGENT_SDK_VERSION` | SDK version for User-Agent |
| `CLAUDE_AGENT_SDK_CLIENT_APP` | Client app name for User-Agent |
| `CLAUDE_CODE_CUSTOM_OAUTH_URL` | Override OAuth endpoints |
| `CLAUDE_CODE_OAUTH_CLIENT_ID` | Override OAuth client ID |
| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | Disable auto-memory |
| `CLAUDE_CODE_SESSION_SOURCE` | Session source identifier |
| `CLAUDE_CODE_SIMPLE` | Disable skills, CLAUDE.md, file attachments |
| `CLAUDE_CODE_QUESTION_PREVIEW_FORMAT` | "markdown" or "html" |
---
## stdin Protocol
Each line is a JSON object terminated by `\n`. Parsed by `XoH.processLine()`.
### User Message
```json
{
"type": "user",
"message": { "content": "fix the auth bug in login.ts" },
"parent_tool_use_id": null,
"isSynthetic": false,
"isReplay": false
}
```
### Keep-Alive
```json
{ "type": "keep_alive" }
```
### Environment Variable Update
```json
{
"type": "update_environment_variables",
"variables": {
"CLAUDE_CODE_SESSION_ACCESS_TOKEN": "new-token-value"
}
}
```
### Permission Response (Approve)
```json
{
"type": "control_response",
"response": {
"request_id": "abc-123",
"subtype": "success",
"response": {
"behavior": "allow",
"updatedInput": {}
}
}
}
```
### Permission Response (Deny)
```json
{
"type": "control_response",
"response": {
"request_id": "abc-123",
"subtype": "success",
"response": {
"behavior": "deny"
}
}
}
```
### Permission Cancel
```json
{
"type": "control_cancel_request",
"request_id": "abc-123"
}
```
Note: `Nm$()` normalizes `requestId` → `request_id` for camelCase compat.
---
## stdout Protocol
Each line is a JSON object terminated by `\n`. Parsed by `fA_()`.
### Assistant Message
```json
{
"type": "assistant",
"message": {
"content": [
{ "type": "text", "text": "I'll fix that..." },
{ "type": "tool_use", "id": "tu_123", "name": "Read",
"input": { "file_path": "/src/login.ts" } }
]
},
"uuid": "msg-uuid",
"session_id": "session-uuid"
}
```
### Permission Request
```json
{
"type": "control_request",
"request_id": "req-uuid",
"request": {
"subtype": "can_use_tool",
"tool_name": "Bash",
"tool_use_id": "tu_456",
"input": { "command": "rm -rf /tmp/old" }
}
}
```
### Result (Success)
```json
{
"type": "result",
"subtype": "success",
"is_error": false,
"duration_ms": 45230,
"duration_api_ms": 38100,
"num_turns": 7,
"result": "Fixed the auth bug by...",
"stop_reason": null,
"session_id": "session-uuid",
"total_cost_usd": 0.0342,
"usage": {
"input_tokens": 15420,
"output_tokens": 3200,
"cache_read_input_tokens": 8000,
"cache_creation_input_tokens": 0
},
"modelUsage": {},
"permission_denials": [],
"fast_mode_state": {},
"uuid": "result-uuid"
}
```
### Result Subtypes
| subtype | Meaning |
|---------|---------|
| `"success"` | Normal completion |
| `"error_max_turns"` | Hit max turns limit |
| `"error_max_budget_usd"` | Hit cost budget |
| `"error_during_execution"` | Runtime error |
| `"error_max_structured_output_retries"` | Structured output validation failed repeatedly |
---
## Session JSONL Format
### File Path
```
~/.claude/projects//.jsonl
```
Where `PI()` hashes the absolute project path. Subagent sessions:
```
~/.claude/projects///subagents/agent-.jsonl
```
### Message Entry Shape
Each line is a JSON object. Messages pass the `RQ()` filter:
```js
RQ(H) = H.type === "user" || "assistant" || "attachment" || "system" || "progress"
```
```json
{
"type": "user|assistant|system|progress|attachment",
"uuid": "",
"timestamp": "2026-03-14T...",
"message": { "role": "user|assistant", "content": "..." },
"parentUuid": " | null",
"logicalParentUuid": " | undefined",
"isSidechain": false,
"sessionId": "",
"version": "1",
"cwd": "/path/to/project",
"gitBranch": "main",
"slug": "claude-sonnet-4-6",
"userType": "external",
"agentId": " | undefined",
"agentName": " | undefined",
"teamName": " | undefined",
"promptId": " | undefined",
"isMeta": false,
"toolUseResult": false,
"isCompactSummary": false,
"sourceToolAssistantUUID": ""
}
```
System messages with `"subtype": "compact_boundary"` mark compaction points.
### Metadata Entries (Non-Message Lines)
```json
{"type":"custom-title","customTitle":"Fix auth bug","sessionId":"..."}
{"type":"ai-title","aiTitle":"Auth module refactor","sessionId":"..."}
{"type":"tag","tag":"bugfix","sessionId":"..."}
{"type":"summary","leafUuid":"...","summary":"..."}
{"type":"agent-name","agentName":"researcher","sessionId":"..."}
{"type":"agent-color","agentColor":"#ff6b6b","sessionId":"..."}
{"type":"agent-setting","agentSetting":"explorer","sessionId":"..."}
{"type":"mode","mode":"plan","sessionId":"..."}
{"type":"pr-link","prNumber":42,"prUrl":"...","prRepository":"...","sessionId":"...","timestamp":"..."}
{"type":"last-prompt","lastPrompt":"fix the auth bug","sessionId":"..."}
{"type":"file-history-snapshot","messageId":"...","snapshot":{}}
{"type":"queue-operation","operation":{}}
```
### Session File Writer
`dT(path, entry)` — synchronous append, mode 0600:
```js
fs.appendFileSync(path, JSON.stringify(entry) + "\n", { mode: 0o600 })
```
`Jq()` singleton manages batched writes (100ms flush interval), with eager flush
when `CLAUDE_CODE_IS_COWORK` or `CLAUDE_CODE_EAGER_FLUSH` is set.
---
## Sessions API
All calls require:
```http
Authorization: Bearer
anthropic-beta: ccr-byoc-2025-07-29
x-organization-uuid:
```
### List Sessions
```http
GET https://api.anthropic.com/v1/sessions
```
Response: `{ data: [{ id, title, session_status, session_context, created_at, updated_at }] }`
### Get Session
```http
GET https://api.anthropic.com/v1/sessions/
```
### Update Session Title
```http
PATCH https://api.anthropic.com/v1/sessions/
Content-Type: application/json
{ "title": "New Title" }
```
### Post Events (Single Message)
```http
POST https://api.anthropic.com/v1/sessions//events
Content-Type: application/json
{
"events": [{
"uuid": "",
"session_id": "",
"type": "user",
"parent_tool_use_id": null,
"message": { "role": "user", "content": "message text" }
}]
}
```
### Post Events (Batch)
Same endpoint, up to 100 events per batch (`kN$ = 100`).
### Fetch Teleport Events (Paginated)
```http
GET https://api.anthropic.com/v1/code/sessions//teleport-events
?limit=1000
&cursor=
```
### Legacy Ingress Fetch
```http
GET https://api.anthropic.com/v1/session_ingress/session/
```
### Archive Session
```http
POST https://api.anthropic.com/v1/sessions//archive
```
---
## WebSocket Subscription
### Connection
```
wss://api.anthropic.com/v1/sessions/ws//subscribe
?organization_uuid=
Headers:
Authorization: Bearer
anthropic-version: 2023-06-01
```
### Message Handling
Validator `fW6()` accepts any object with a string `type` field:
```js
function fW6(H) {
if (typeof H !== "object" || H === null || !("type" in H)) return false;
return typeof H.type === "string";
}
```
Events are forwarded to `callbacks.onMessage(parsedEvent)`.
Reconnection: up to `Abf` attempts with `AW6` ms delay.
Permanent close codes in `DW6` set prevent reconnection.
Ping interval: `LW6` ms.
### Control Messages (via WebSocket)
```json
{
"type": "control_request",
"request_id": "",
"request": {
"subtype": "can_use_tool",
"tool_name": "Bash",
"tool_use_id": "...",
"input": {}
}
}
```
---
## CoWork-Specific Behavior
### Plugin Isolation
When `CLAUDE_CODE_USE_COWORK_PLUGINS=1` or `--cowork` flag:
- Plugin directory: `~/.claude/cowork_plugins/` (instead of `~/.claude/plugins/`)
- Settings file: `~/.claude/cowork_settings.json` (instead of `~/.claude/settings.json`)
- Function `ae6()` returns `"cowork_settings.json"` when `BkH()` or env var is truthy
- Function `L$_()` returns `"cowork_plugins"` instead of `"plugins"`
### Eager Flush
When `CLAUDE_CODE_IS_COWORK=1` or `CLAUDE_CODE_EAGER_FLUSH=1`:
- `RB()` (= `Jq().flush()`) called at every turn boundary
- `RB()` called at every result exit point (success, error_max_turns, etc.)
- Ensures remote Sessions API receives events in near-real-time
### Shared Memory (CoWork Teams)
`CLAUDE_COWORK_MEMORY_PATH_OVERRIDE=/path/to/shared/memory`
- Overrides the per-project memory directory
- All teammates in a CoWork session share the same MEMORY.md
- `mM$()` returns true when override is active
- `SHD()` reads the env var, `o3()` uses it as first priority
---
## Agent Teams
Agent Teams (teammate mode) is separate from CoWork. Enabled by:
```
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=true OR --agent-teams flag
AND tengu_amber_flint feature flag = true
```
### Teammate Spawning (tmux mode)
The lead constructs a claude command:
```bash
cd /project && claude \
--agent-id \
--agent-name \
--team-name \
--agent-color \
--parent-session-id \
[--plan-mode-required] \
[--agent-type ]
```
### Teammate Modes
| Mode | Mechanism |
|------|-----------|
| `"tmux"` | Separate claude process in tmux pane |
| `"in-process"` | AsyncLocalStorage context in same Node process |
| `"auto"` | Chooses based on terminal (iTerm2 native panes → tmux → in-process) |
Configurable via settings `teammateMode` or `--teammate-mode `.
### Team State Storage
```
~/.claude/teams//config.json
~/.claude/tasks//
```
Config contains `members[]` with agentId, name, agentType, model, prompt, color,
planModeRequired, joinedAt, tmuxPaneId, cwd, subscriptions, backendType.
### SendMessage Tool Schema
Types: `message`, `broadcast`, `shutdown_request`, `shutdown_response`, `plan_approval_response`
```json
{"type":"message","recipient":"researcher","content":"...","summary":"Brief preview"}
{"type":"broadcast","content":"...","summary":"Critical announcement"}
{"type":"shutdown_request","recipient":"researcher","content":"Task complete"}
{"type":"shutdown_response","request_id":"abc","approve":true}
{"type":"plan_approval_response","request_id":"abc","recipient":"researcher","approve":true}
```
### Teammate System Prompt Addendum
```
# Agent Teammate Communication
IMPORTANT: You are running as an agent in a team. To communicate with anyone on your team:
- Use the SendMessage tool with type `message` to send messages to specific teammates
- Use the SendMessage tool with type `broadcast` sparingly for team-wide announcements
Just writing a response in text is not visible to others on your team
- you MUST use the SendMessage tool.
The user interacts primarily with the team lead. Your work is coordinated
through the task system and teammate messaging.
```
---
## Session Resume Paths
### Local Resume
| Flag | Mechanism |
|------|-----------|
| `--continue` | Loads most recent session via `FbA(0)` |
| `--resume ` | Loads `.jsonl` via `eQH(sessionId)` |
| `--resume ` | Fuzzy matches title via `UB(query, {exact:true})` |
| `--fork-session` | Creates new session ID, copies messages |
| `--resume-session-at ` | Truncates at message UUID |
| `--rewind-files ` | Restores files to snapshot, exits |
| `--from-pr [number]` | Sessions linked to PR |
### Remote Resume
| Flag | Mechanism |
|------|-----------|
| `--teleport ` | `GET /v1/code/sessions//teleport-events` (paginated, 1000/page) |
| (fallback) | `GET /v1/session_ingress/session/` |
### Session Loader Flow (ae())
1. Read JSONL → parse via `HqH()` → maps of messages, summaries, titles, tags, snapshots
2. Find leaf UUID (most recent non-sidechain message)
3. Walk `parentUuid` chain via `GrH()` to reconstruct conversation tree
4. Slice at `compact_boundary` via `Ly()` if present
5. Restore fileHistorySnapshots, attributionSnapshots, contentReplacements
6. Run `SessionStart:resume` hooks
7. Return `{messages, turnInterruptionState, agentSetting, ...}` to React app
### Hydration (Remote → Local)
`ZnA(sessionId, ingressUrl)`:
1. Fetch events from remote ingress URL
2. Write to local `.jsonl`
3. Set remote ingress URL on session writer for future dual-write
---
## sdkUrl & Session Ingress Transport
**Gap 1 RESOLVED**: `--sdk-url` is NOT an HTTP endpoint. It is a **WebSocket URL** for
session ingress. The CLI opens a persistent WebSocket to it and pipes stream-json
bidirectionally.
### How sdkUrl Works
When `--sdk-url ` is passed, the CLI creates a `Yp$` transport (class extending `goH`):
```
┌────────────────────────────┐
│ Bridge Daemon (T38) │
│ polls /work/poll │
│ gets work_secret with │
│ session_ingress_token │
└─────────┬──────────────────┘
│ spawns:
│ claude --print --sdk-url --session-id ...
▼
┌────────────────────────────┐ ┌──────────────────────────┐
│ CLI child process │ │ Anthropic API │
│ Yp$ class │◄──WS───►│ session_ingress/ws/ │
│ ├─ WebSocket transport │ └──────────────────────────┘
│ │ (doH / FoH / mqH) │
│ ├─ stdin ← WS messages │
│ ├─ stdout → WS write() │
│ └─ keep_alive interval │
└────────────────────────────┘
```
### Transport Selection (`d08()`)
```
d08(url, headers, sessionId, refreshHeaders):
if CLAUDE_CODE_USE_CCR_V2:
→ convert ws→http, append /worker/events/stream
→ return SSETransport (mqH)
else if ws:// or wss://:
if CLAUDE_CODE_POST_FOR_SESSION_INGRESS_V2:
→ return HybridTransport (FoH) — WebSocket + POST fallback
else:
→ return WebSocketTransport (doH)
else:
→ Error: unsupported protocol
```
### Session Ingress WebSocket URL
Built by `Wm$()`:
```
wss://{api_host}/v1/session_ingress/ws/{sessionId}
```
For localhost: `ws://` and `/v2/` path prefix.
### HybridTransport POST Fallback
`FoH` extends `doH` (WebSocketTransport), adding:
- Batched POST uploads to `{url}/session/{sessionId}/events` (URL transform via `L1_()`)
- Auth: `Authorization: Bearer {MJ()}` — uses `MJ()` (see session token section)
- Content-Type: `application/json`
- Body: `{ events: [...messages] }`
- Batch size: 500, queue size: 100k, retry with exponential backoff
### CCR v2 Path
When `CLAUDE_CODE_USE_CCR_V2=1`:
- Worker registration: `POST {api}/v1/code/sessions/{id}/worker/register`
- Stream: SSE at `{api}/v1/code/sessions/{id}/worker/events/stream`
- Internal events read/write via `QoH` (CCRClient)
- State reporting: permission_mode, tool activity, metadata
### Key Implication for Local Client
**sdkUrl is optional for local implementations.** When omitted, the CLI uses `goH` (local
stdin/stdout passthrough). The `Yp$` class is only needed when the CLI must talk to a
remote bridge over WebSocket. A local CoWork client can:
1. Spawn CLI with piped stdin/stdout (no `--sdk-url`)
2. Separately dual-write events via `POST /v1/sessions/{id}/events`
3. Subscribe to remote updates via WebSocket subscription
---
## Session Creation API
**Gap 2 RESOLVED**: Full `POST /v1/sessions` schema extracted.
### Create Session (Web/CLI Path)
```http
POST https://api.anthropic.com/v1/sessions
Authorization: Bearer
Content-Type: application/json
anthropic-version: 2023-06-01
anthropic-beta: ccr-byoc-2025-07-29
x-organization-uuid:
```
Request Body:
```json
{
"title": "Fix auth bug in login.ts",
"events": [
{
"type": "event",
"data": {
"uuid": "",
"session_id": "",
"type": "user",
"parent_tool_use_id": null,
"message": {
"role": "user",
"content": "fix the auth bug in login.ts"
}
}
}
],
"session_context": {
"sources": [
{
"type": "git_repository",
"git_info": {
"type": "github",
"repo": "owner/repo"
}
}
],
"outcomes": [
{
"type": "git_repository",
"git_info": {
"type": "github",
"repo": "owner/repo",
"branches": ["claude/task"]
}
}
],
"model": "claude-sonnet-4-6"
},
"environment_id": ""
}
```
Response:
```json
{
"id": "cse_abc123...",
"title": "Fix auth bug in login.ts"
}
```
### Create Session (Bridge/Remote Control Path)
Same endpoint, but additional fields:
```json
{
"title": "optional",
"events": [],
"session_context": {
"sources": [{"type": "git_repository", "git_info": {...}}],
"outcomes": [{"type": "git_repository", "git_info": {...}}],
"model": "claude-sonnet-4-6"
},
"environment_id": "",
"source": "remote-control",
"permission_mode": "plan"
}
```
### Fetch Session Details
```http
GET https://api.anthropic.com/v1/sessions/
```
Response includes `session_context.sources[]` with:
- `type: "git_repository"` — `url`, `git_info.type`, `git_info.repo`
- `type: "directory"` — path info
### List Code Sessions (with context)
```http
GET https://api.anthropic.com/v1/sessions
```
Response: `{ data: [{ id, title, session_status, session_context, created_at, updated_at }] }`
### Share Transcript
```http
POST https://api.anthropic.com/api/claude_code_shared_session_transcripts
Content-Type: application/json
User-Agent: claude-code/2.1.75
{
"content": "",
"appearance_id": ""
}
```
Response: `{ transcript_id: "..." }`
---
## WebSocket Event Types
**Gap 3 RESOLVED**: The WebSocket carries the **same stream-json protocol** as stdin/stdout.
All message types listed below are valid over both WebSocket and piped stdio.
### Full Message Type Taxonomy
Messages pass through `Lf_()` filter (passes everything except control_request/control_response)
and `QZH()` adapter:
| Type | Subtypes | Direction | Purpose |
|------|----------|-----------|---------|
| `user` | — | client→server | User message |
| `assistant` | — | server→client | Model response (text, tool_use) |
| `system` | `init`, `status`, `compact_boundary`, `informational` | server→client | System events |
| `result` | `success`, `error_max_turns`, `error_max_budget_usd`, `error_during_execution` | server→client | Turn completion |
| `tool_progress` | — | server→client | Long-running tool status |
| `stream_event` | — | server→client | Streaming delta (text, tool input) |
| `auth_status` | — | server→client | Auth state changes |
| `tool_use_summary` | — | server→client | Tool use digest |
| `rate_limit_event` | — | server→client | Rate limiting info |
| `control_request` | `can_use_tool`, `interrupt`, `hook_callback`, `elicitation`, `mcp_message`, `set_permission_mode` | bidirectional | Permission/control flow |
| `control_response` | `success`, `error` | bidirectional | Response to control_request |
| `control_cancel_request` | — | client→server | Cancel pending request |
| `keep_alive` | — | bidirectional | Connection heartbeat |
| `streamlined_text` | — | server→client | Streamlined text output |
| `streamlined_tool_use_summary` | — | server→client | Streamlined tool digest |
| `update_environment_variables` | — | client→server | Token refresh |
### system.init Event
Sent when session starts:
```json
{
"type": "system",
"subtype": "init",
"slash_commands": ["commit", "compact", "help", ...],
"timestamp": "..."
}
```
### stream_event Event
Real-time streaming deltas:
```json
{
"type": "stream_event",
"event": {
"type": "content_block_delta",
"delta": {"type": "text_delta", "text": "partial..."}
}
}
```
### control_request Subtypes (Full)
| Subtype | Purpose | Fields |
|---------|---------|--------|
| `can_use_tool` | Permission check | `tool_name`, `input`, `tool_use_id`, `permission_suggestions`, `blocked_path`, `decision_reason`, `description`, `agent_id` |
| `interrupt` | Abort current operation | — |
| `hook_callback` | Execute hook | `callback_id`, `input`, `tool_use_id` |
| `elicitation` | MCP elicitation | `mcp_server_name`, `message`, `mode`, `url`, `elicitation_id`, `requested_schema` |
| `mcp_message` | MCP passthrough | `server_name`, `message` |
| `set_permission_mode` | Change permission level | `mode` |
---
## Session Token Architecture
**Gap 4 RESOLVED**: Complete token chain traced.
### Token Hierarchy
```
OAuth accessToken (long-lived, from PKCE flow)
├─ Used for: Sessions API CRUD, session listing, teleport, archive
├─ Stored: ~/.claude/.credentials.json
└─ Header: Authorization: Bearer
session_ingress_token (session-scoped, from work secret)
├─ Used for: WebSocket ingress, event POST to session, bridge heartbeats
├─ Source: pollForWork response → work_secret (base64url JSON)
└─ Header: Authorization: Bearer
```
### MJ() — Session Token Getter
Priority chain:
1. `process.env.CLAUDE_CODE_SESSION_ACCESS_TOKEN` — highest priority
2. `CI1()` — reads from file descriptor via `CLAUDE_CODE_WEBSOCKET_AUTH_FILE_DESCRIPTOR`
- Reads `/proc/self/fd/` (inherited from Desktop Electron parent)
- Cached after first read
### fIH() — Auth Headers Builder
```js
// For sessionKey tokens (sk-ant-sid*)
{ Cookie: "sessionKey=", "X-Organization-Uuid": "" }
// For bearer tokens (everything else)
{ Authorization: "Bearer " }
```
### Rw() — OAuth Headers Builder
Used for all Sessions API calls:
```js
{
Authorization: "Bearer ",
"Content-Type": "application/json",
"anthropic-version": "2023-06-01"
}
```
Plus per-request additions:
```
anthropic-beta: ccr-byoc-2025-07-29
x-organization-uuid:
```
### Work Secret Structure
The `pollForWork` response includes a `secret` field. Decoded by `Em$()`:
```json
{
"version": 1,
"session_ingress_token": "string (required)",
"api_base_url": "string (required)",
"use_code_sessions": true
}
```
The `session_ingress_token` is:
- Passed to child process via `CLAUDE_CODE_SESSION_ACCESS_TOKEN` env var
- Used as `accessToken` parameter in bridge session spawn
- Refreshable via token rotation during long sessions
- Bridge updates running sessions via `updateAccessToken()` when new work arrives
### Token Refresh for Running Sessions
The bridge daemon can receive updated tokens for existing sessions:
```js
// In poll loop, when session already exists:
if (existingSession) {
existingSession.updateAccessToken(workSecret.session_ingress_token);
// Also schedules token rotation
}
```
---
## Bridge Orchestrator
**Gap 5 RESOLVED**: Full bridge lifecycle traced.
### Entry Point
The bridge is started via `claude remote-control` or `/remote-control` command, which
calls `T38()` — the main bridge poll loop.
### Bridge API Client
Created by `zm$()`, provides these endpoints:
```
┌─────────────────────────────────────────────────────────────────┐
│ Bridge API Surface │
│ │
│ POST /v1/environments/bridge │
│ → registerBridgeEnvironment(machineName, dir, branch, │
│ gitRepoUrl, maxSessions, workerType, reuseEnvironmentId) │
│ ← { environment_id: string } │
│ │
│ GET /v1/environments/{envId}/work/poll?ack=true │
│ → pollForWork(environmentId, accessToken, abortSignal) │
│ ← { id: workId, data: { type: "session"|"healthcheck", │
│ id: sessionId }, secret: base64url_work_secret } │
│ ← null (no work available) │
│ │
│ POST /v1/environments/{envId}/work/{workId}/ack │
│ → acknowledgeWork(environmentId, workId, accessToken) │
│ │
│ POST /v1/environments/{envId}/work/{workId}/stop │
│ → stopWork(environmentId, workId, force) │
│ │
│ POST /v1/environments/{envId}/work/{workId}/heartbeat │
│ → heartbeatWork(environmentId, workId, accessToken) │
│ ← { lease_extended: bool, state: string } │
│ │
│ POST /v1/environments/{envId}/bridge/reconnect │
│ → reconnectSession(environmentId, sessionId) │
│ │
│ DELETE /v1/environments/bridge/{envId} │
│ → deregisterEnvironment(environmentId) │
│ │
│ POST /v1/sessions/{id}/archive │
│ → archiveSession(sessionId) │
│ │
│ POST /v1/sessions/{id}/events │
│ → sendPermissionResponseEvent(sessionId, event, token) │
│ │
│ Beta header: anthropic-beta: environments-2025-11-01 │
└─────────────────────────────────────────────────────────────────┘
```
### Bridge Lifecycle (T38)
```
1. REGISTER
POST /v1/environments/bridge
Body: { machine_name, directory, branch, git_repo_url,
max_sessions, metadata: { worker_type } }
← environment_id
2. POLL LOOP (infinite)
GET /v1/environments/{envId}/work/poll?ack=true
← null → sleep(poll_interval), retry
← { data.type: "healthcheck" } → log, continue
← { data.type: "session", data.id: sessionId, secret: ... } → SPAWN
3. SPAWN SESSION
a. Decode work secret: Em$(secret) → { session_ingress_token, api_base_url, ... }
b. Build ingress URL: Wm$(api_base_url, sessionId)
→ wss://{host}/v1/session_ingress/ws/{sessionId}
c. (Optional CCR v2) Register worker:
POST {api}/v1/code/sessions/{id}/worker/register
d. Spawn child:
claude --print --sdk-url --session-id
--input-format stream-json --output-format stream-json
--replay-user-messages [--verbose] [--debug-file ]
[--permission-mode ]
Env: CLAUDE_CODE_SESSION_ACCESS_TOKEN=
CLAUDE_CODE_ENVIRONMENT_KIND=bridge
CLAUDE_CODE_WORKER_EPOCH=
[CLAUDE_CODE_USE_CCR_V2=1]
4. SESSION MONITORING
- Track active sessions in Map
- Heartbeat: POST /v1/environments/{envId}/work/{workId}/heartbeat
- Timeout: configurable per session (sessionTimeoutMs)
- Token rotation: update child tokens when new work arrives for same session
5. SESSION COMPLETE
- Archive: POST /v1/sessions/{id}/archive
- Worktree cleanup (if spawn mode = worktree)
- Acknowledge work completion
- Return to poll loop
6. DEREGISTER (on shutdown)
DELETE /v1/environments/bridge/{envId}
```
### Spawn Modes
| Mode | Mechanism |
|------|-----------|
| `same-dir` | Child process in same directory |
| `worktree` | git worktree created per session |
| `session` | Isolated session directory |
| `single-session` | One session at a time, exit after completion |
### Capacity Management
- `maxSessions` configurable (passed during registration)
- At capacity: enters heartbeat mode (heartbeat_interval_ms)
- Multisession polling: `multisession_poll_interval_ms_at_capacity`
- Session count tracked and reported via status display
### Error Handling
`YE` (BridgeFatalError) class with status codes:
- 401: Authentication failed
- 403: Access denied / session expired
- 404: Not found (Remote Control may not be available)
- 410: Session expired
- 429: Rate limited (polling too frequently)
---
## Remaining Unknowns
The 5 original gaps are now resolved. Remaining minor unknowns:
1. **Exact event schemas for all stream_event subtypes** — the content_block_delta
structure follows the Anthropic Messages API spec, but edge cases may exist.
2. **session_context full taxonomy** — `sources[]` and `outcomes[]` types beyond
`git_repository` and `directory` are not fully enumerated.
3. **CCR v2 worker event stream format** — the SSE transport (`mqH`) uses a different
wire format than the WebSocket path. Not fully traced.
4. **Bridge poll interval config** — `o$H()` returns configurable intervals
(`poll_interval_ms_not_at_capacity`, `heartbeat_interval_ms`,
`multisession_poll_interval_ms_at_capacity`, `session_keepalive_interval_ms`)
but the defaults and server-side config source are unknown.
5. **Token rotation scheduling** — `Y38()` schedules periodic token refresh for
bridge sessions but the exact interval logic is not fully traced.
These are implementation details, not blocking for a Linux CoWork client.
---
## Building a Linux CoWork Client
### Architecture Decision
Two viable approaches based on findings:
**Approach A: Local Pipe (Simplest)**
- Spawn CLI with piped stdin/stdout, no `--sdk-url`
- Dual-write events via `POST /v1/sessions/{id}/events`
- Subscribe via WebSocket for remote sync
**Approach B: Full Bridge (Production)**
- Register environment via bridge API
- Poll for work, get session_ingress_token
- Spawn CLI with `--sdk-url` pointing to session ingress WebSocket
- Full lifecycle management like claude.ai
### Implementation (Approach A)
```python
import subprocess, json, uuid, threading, time, webbrowser
from http.server import HTTPServer, BaseHTTPRequestHandler
from urllib.parse import urlencode, parse_qs, urlparse
import hashlib, base64, secrets, requests
# ── 1. OAuth PKCE Login ──
CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e"
TOKEN_URL = "https://platform.claude.com/v1/oauth/token"
AUTHORIZE_URL = "https://claude.ai/oauth/authorize"
SCOPES = "user:profile user:inference user:sessions:claude_code user:mcp_servers"
BASE_API = "https://api.anthropic.com"
BETA_HEADER = "ccr-byoc-2025-07-29"
def pkce_pair():
verifier = secrets.token_urlsafe(64)
digest = hashlib.sha256(verifier.encode()).digest()
challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode()
return verifier, challenge
def oauth_login():
verifier, challenge = pkce_pair()
state = secrets.token_urlsafe(32)
port = 9876
auth_code = [None]
class Handler(BaseHTTPRequestHandler):
def do_GET(self):
qs = parse_qs(urlparse(self.path).query)
if "code" in qs:
auth_code[0] = qs["code"][0]
self.send_response(200)
self.end_headers()
self.wfile.write(b"Login successful. Return to terminal.")
self.server.shutdown_request(self.request)
def log_message(self, *a): pass
server = HTTPServer(("127.0.0.1", port), Handler)
redirect_uri = f"http://localhost:{port}/callback"
url = f"{AUTHORIZE_URL}?" + urlencode({
"response_type": "code",
"client_id": CLIENT_ID,
"redirect_uri": redirect_uri,
"scope": SCOPES,
"state": state,
"code_challenge": challenge,
"code_challenge_method": "S256",
})
webbrowser.open(url)
server.handle_request()
resp = requests.post(TOKEN_URL, json={
"grant_type": "authorization_code",
"client_id": CLIENT_ID,
"redirect_uri": redirect_uri,
"code_verifier": verifier,
"code": auth_code[0],
})
tokens = resp.json()
return tokens["access_token"], tokens.get("refresh_token")
# ── 2. Session Management ──
def api_headers(token, org_uuid):
return {
"Authorization": f"Bearer {token}",
"Content-Type": "application/json",
"anthropic-version": "2023-06-01",
"anthropic-beta": BETA_HEADER,
"x-organization-uuid": org_uuid,
}
def create_session(token, org_uuid, title, initial_prompt=None, env_id=None):
events = []
if initial_prompt:
events.append({
"type": "event",
"data": {
"uuid": str(uuid.uuid4()),
"session_id": "",
"type": "user",
"parent_tool_use_id": None,
"message": {"role": "user", "content": initial_prompt}
}
})
body = {
"title": title,
"events": events,
"session_context": {"sources": [], "outcomes": [], "model": "claude-sonnet-4-6"},
}
if env_id:
body["environment_id"] = env_id
resp = requests.post(f"{BASE_API}/v1/sessions",
json=body, headers=api_headers(token, org_uuid))
resp.raise_for_status()
return resp.json()["id"]
def send_event(token, org_uuid, session_id, content, msg_uuid=None):
body = {"events": [{
"uuid": msg_uuid or str(uuid.uuid4()),
"session_id": session_id,
"type": "user",
"parent_tool_use_id": None,
"message": {"role": "user", "content": content}
}]}
resp = requests.post(f"{BASE_API}/v1/sessions/{session_id}/events",
json=body, headers=api_headers(token, org_uuid))
return resp.status_code in (200, 201)
# ── 3. Spawn CLI ──
def spawn_cli(session_id, access_token):
import os
env = {
**os.environ,
"CLAUDE_CODE_SESSION_ACCESS_TOKEN": access_token,
"CLAUDE_CODE_POST_FOR_SESSION_INGRESS_V2": "1",
"CLAUDE_CODE_IS_COWORK": "1",
"CLAUDE_CODE_USE_COWORK_PLUGINS": "1",
"CLAUDE_CODE_ENVIRONMENT_KIND": "bridge",
"CLAUDE_CODE_ENTRYPOINT": "claude-desktop",
}
return subprocess.Popen(
["claude", "--print",
"--session-id", session_id,
"--input-format", "stream-json",
"--output-format", "stream-json",
"--replay-user-messages"],
stdin=subprocess.PIPE,
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
env=env,
)
# ── 4. Stream Protocol ──
def send_message(proc, content):
msg = json.dumps({
"type": "user",
"message": {"content": content},
"parent_tool_use_id": None,
}) + "\n"
proc.stdin.write(msg.encode())
proc.stdin.flush()
def send_control_response(proc, request_id, behavior="allow", updated_input=None):
resp = {
"type": "control_response",
"response": {
"request_id": request_id,
"subtype": "success",
"response": {"behavior": behavior}
}
}
if behavior == "allow" and updated_input:
resp["response"]["response"]["updatedInput"] = updated_input
proc.stdin.write((json.dumps(resp) + "\n").encode())
proc.stdin.flush()
def refresh_token(proc, new_token):
msg = json.dumps({
"type": "update_environment_variables",
"variables": {"CLAUDE_CODE_SESSION_ACCESS_TOKEN": new_token}
}) + "\n"
proc.stdin.write(msg.encode())
proc.stdin.flush()
def read_events(proc, on_assistant, on_permission, on_result):
for line in proc.stdout:
try:
event = json.loads(line)
except json.JSONDecodeError:
continue
t = event.get("type")
if t == "assistant":
on_assistant(event)
elif t == "control_request":
on_permission(event)
elif t == "result":
on_result(event)
if event.get("subtype") == "success":
break
elif t == "system" and event.get("subtype") == "init":
pass # Session initialized
elif t == "keep_alive":
pass # Ignore heartbeats
# ── 5. Resume Session ──
# Option A: Local resume
# claude --resume
#
# Option B: Remote teleport
# GET /v1/code/sessions//teleport-events?limit=1000&cursor=
#
# Option C: WebSocket subscription for live sync
# wss://api.anthropic.com/v1/sessions/ws//subscribe
# ?organization_uuid=
# Headers: Authorization: Bearer
# anthropic-version: 2023-06-01
```
---
## creating-custom-skills.md
# How to create custom Skills
Skills are available for users on free, Pro, Max, Team, and Enterprise plans. This feature requires **[code execution to be enabled](https://support.claude.com/en/articles/12111783-create-and-edit-files-with-claude#h_1c99382190)**. Skills are also available in beta for Claude Code users and for all API users using the code execution tool.
Custom Skills let you enhance Claude with specialized knowledge and workflows specific to your organization or personal work style. This article explains how to create, structure, and test your own Skills.
Skills can be as simple as a few lines of instructions or as complex as multi-file packages with executable code. The best Skills:
- Solve a specific, repeatable task
- Have clear instructions that Claude can follow
- Include examples when helpful
- Define when they should be used
- Are focused on one workflow rather than trying to do everything
------------------------------------------------------------------------
## Create a Skill.md file
Every Skill consists of a directory containing at minimum a Skill.md file, which is the core of the Skill. This file must start with a YAML frontmatter to hold name and description fields, which are required metadata. It can also contain additional metadata, instructions for Claude or reference files, executable scripts, or tools.
### Required metadata fields
**name:** A human-friendly name for your Skill (64 characters maximum)
- **Example:** Brand Guidelines
**description:** A clear description of what the Skill does and when to use it.
- This is critical—Claude uses this to determine when to invoke your Skill (200 characters maximum).
- **Example:** Apply Acme Corp brand guidelines to presentations and documents, including official colors, fonts, and logo usage.
### Optional metadata fields
**dependencies:** Software packages required by your Skill.
- **Example:** python\>=3.8, pandas\>=1.5.0
The metadata in the Skill.md file serves as the first level of a progressive disclosure system, providing just enough information for Claude to know when the Skill should be used without having to load all of the content.
### Markdown body
The Markdown body is the second level of detail after the metadata, so Claude will access this if needed after reading the metadata. Depending on your task, Claude can access the Skill.md file and use the Skill.
### Example Skill.md
**Brand guidelines skill**
## Metadata
name: Brand Guidelines
description: Apply Acme Corp brand guidelines to all presentations and documents
## Overview
This Skill provides Acme Corp's official brand guidelines for creating consistent, professional materials. When creating presentations, documents, or marketing materials, apply these standards to ensure all outputs match Acme's visual identity. Claude should reference these guidelines whenever creating external-facing materials or documents that represent Acme Corp.
## Brand Colors
Our official brand colors are:
- Primary: #FF6B35 (Coral)
- Secondary: #004E89 (Navy Blue)
- Accent: #F7B801 (Gold)
- Neutral: #2E2E2E (Charcoal)
## Typography
Headers: Montserrat Bold
Body text: Open Sans Regular
Size guidelines:
- H1: 32pt
- H2: 24pt
- Body: 11pt
## Logo Usage
Always use the full-color logo on light backgrounds. Use the white logo on dark backgrounds. Maintain minimum spacing of 0.5 inches around the logo.
## When to Apply
Apply these guidelines whenever creating:
- PowerPoint presentations
- Word documents for external sharing
- Marketing materials
- Reports for clients
## Resources
See the resources folder for logo files and font downloads.
## Add resources
If you have too much information to add to a single Skill.md file (e.g., sections that only apply to specific scenarios), you can add more content by adding files within your Skill directory. For example, add a REFERENCE.md file containing supplemental and reference information to your Skill directory. Referencing it in Skill.md will help Claude decide if it needs to access that resource when executing the Skill.
## Add scripts
For more advanced Skills, attach executable code files to Skill.md, allowing Claude to run code. For example, our document skills use the following programming languages and packages:
- Python (pandas, numpy, matplotlib)
- JavaScript/Node.js
- Packages to help with file editing
- visualization tools
**Note:** Claude and Claude Code can install packages from standard repositories (Python PyPI, JavaScript npm) when loading Skills. It’s not possible to install additional packages at runtime with API Skills—all dependencies must be pre-installed in the container.
------------------------------------------------------------------------
## Package your skill
Once your Skill folder is complete:
1. Ensure the folder name matches your Skill's name.
2. Create a ZIP file of the folder.
3. The ZIP should contain the Skill folder as its root (not a subfolder).
**Correct structure:**
my-Skill.zip
└── my-Skill/
├── Skill.md
└── resources/
**Incorrect structure:**
my-Skill.zip
└── (files directly in ZIP root)
------------------------------------------------------------------------
## Test your skill
### Before uploading
1\. Review your Skill.md for clarity
2\. Check that the description accurately reflects when Claude should use the Skill
3\. Verify all referenced files exist in the correct locations
4\. Test with example prompts to ensure Claude invokes it appropriately
### After uploading to Claude
1\. Enable the Skill in **[Customize \> Skills](https://claude.ai/customize/skills)**.
2\. Try several different prompts that should trigger it
3\. Review Claude's thinking to confirm it's loading the Skill
4\. Iterate on the description if Claude isn't using it when expected
**Note for Team and Enterprise plans:** To make a skill available to all users in your organization, see **[Provision and manage Skills for your organization](https://support.claude.com/en/articles/13119606-provisioning-and-managing-skills-for-your-organization)**.
------------------------------------------------------------------------
## Best practices
**Keep it focused:** Create separate Skills for different workflows. Multiple focused Skills compose better than one large Skill.
**Write clear descriptions:** Claude uses descriptions to decide when to invoke your Skill. Be specific about when it applies.
**Start simple:** Begin with basic instructions in Markdown before adding complex scripts. You can always expand on the Skill later.
**Use examples:** Include example inputs and outputs in your Skill.md file to help Claude understand what success looks like.
**Test incrementally:** Test after each significant change rather than building a complex Skill all at once.
**Skills can build on each other:** While Skills can't explicitly reference other Skills, Claude can use multiple Skills together automatically. This composability is one of the most powerful parts of the Skills feature.
**Review the open Agent Skills specification:** Follow the guidelines at **[agentskills.io](http://agentskills.io)**, so skills you create can work across platforms that adopt the standard.
For a more in-depth guide to skill creation, refer to **[Skill authoring best practices](../04-API-Reference/Agents-Tools/agents-and-tools-agent-skills-best-practices-d1da876439.md)** in our Claude Docs.
------------------------------------------------------------------------
## Security considerations
- Exercise caution when adding scripts to your Skill.md file.
- Don't hardcode sensitive information (API keys, passwords).
- Review any Skills you download before enabling them.
- Use appropriate MCP connections for external service access.
------------------------------------------------------------------------
## Example skills to reference
Visit our repository on GitHub for example Skills you can use as templates: **[https://github.com/anthropics/skills/tree/main/skills](https://github.com/anthropics/skills/tree/main/skills)**.
---
## customize-keyboard-shortcuts-claude-code-docs-f23eb8cfd3.md
# Customize keyboard shortcuts
Customize keyboard shortcuts in Claude Code with a keybindings configuration file.
> ## Documentation Index
>
> Fetch the complete documentation index at:
>
> Use this file to discover all available pages before exploring further.
Customizable keyboard shortcuts require Claude Code v2.1.18 or later. Check your version with `claude --version`.
Claude Code supports customizable keyboard shortcuts. Run `/keybindings` to create or open your configuration file at `~/.claude/keybindings.json`.
Configuration file
The keybindings configuration file is an object with a `bindings` array. Each block specifies a context and a map of keystrokes to actions.
Changes to the keybindings file are automatically detected and applied without restarting Claude Code.
| Field | Description |
|:-----------|:---------------------------------------------------|
| `$schema` | Optional JSON Schema URL for editor autocompletion |
| `$docs` | Optional documentation URL |
| `bindings` | Array of binding blocks by context |
This example binds `Ctrl+E` to open an external editor in the chat context, and unbinds `Ctrl+U`:
```python
{
"$schema": "https://www.schemastore.org/claude-code-keybindings.json",
"$docs": "https://code.claude.com/docs/en/keybindings",
"bindings": [
{
"context": "Chat",
"bindings": {
"ctrl+e": "chat:externalEditor",
"ctrl+u": null
}
}
]
}
```
Contexts
Each binding block specifies a **context** where the bindings apply:
| Context | Description |
|:------------------|:-------------------------------------------------------------|
| `Global` | Applies everywhere in the app |
| `Chat` | Main chat input area |
| `Autocomplete` | Autocomplete menu is open |
| `Settings` | Settings menu |
| `Confirmation` | Permission and confirmation dialogs |
| `Tabs` | Tab navigation components |
| `Help` | Help menu is visible |
| `Transcript` | Transcript viewer |
| `HistorySearch` | History search mode (Ctrl+R) |
| `Task` | Background task is running |
| `ThemePicker` | Theme picker dialog |
| `Attachments` | Image attachment navigation in select dialogs |
| `Footer` | Footer indicator navigation (tasks, teams, diff) |
| `MessageSelector` | Rewind and summarize dialog message selection |
| `DiffDialog` | Diff viewer navigation |
| `ModelPicker` | Model picker effort level |
| `Select` | Generic select/list components |
| `Plugin` | Plugin dialog (browse, discover, manage) |
| `Scroll` | Conversation scrolling and text selection in fullscreen mode |
| `Doctor` | `/doctor` diagnostics screen |
Available actions
Actions follow a `namespace:action` format, such as `chat:submit` to send a message or `app:toggleTodos` to show the task list. Each context has specific actions available.
App actions
Actions available in the `Global` context:
| Action | Default | Description |
|:-----------------------|:----------|:----------------------------|
| `app:interrupt` | Ctrl+C | Cancel current operation |
| `app:exit` | Ctrl+D | Exit Claude Code |
| `app:redraw` | (unbound) | Force terminal redraw |
| `app:toggleTodos` | Ctrl+T | Toggle task list visibility |
| `app:toggleTranscript` | Ctrl+O | Toggle verbose transcript |
History actions
Actions for navigating command history:
| Action | Default | Description |
|:-------------------|:--------|:----------------------|
| `history:search` | Ctrl+R | Open history search |
| `history:previous` | Up | Previous history item |
| `history:next` | Down | Next history item |
Chat actions
Actions available in the `Chat` context:
| Action | Default | Description |
|:----------------------|:--------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `chat:cancel` | Escape | Cancel current input |
| `chat:clearInput` | Ctrl+L | Force a full screen redraw, preserving input. In [fullscreen rendering](/docs/en/fullscreen#clear-the-conversation), press twice within two seconds to run `/clear` |
| `chat:clearScreen` | Cmd+K | In [fullscreen rendering](/docs/en/fullscreen#clear-the-conversation), press twice within two seconds to run `/clear` |
| `chat:killAgents` | Ctrl+X Ctrl+K | Kill all running [background subagents](/docs/en/sub-agents#run-subagents-in-foreground-or-background) in this session |
| `chat:cycleMode` | Shift+Tab\* | Cycle permission modes |
| `chat:modelPicker` | Meta+P | Open model picker |
| `chat:fastMode` | Meta+O | Toggle fast mode |
| `chat:thinkingToggle` | Meta+T | Toggle extended thinking |
| `chat:submit` | Enter | Submit message |
| `chat:newline` | Ctrl+J | Insert a newline without submitting |
| `chat:undo` | Ctrl+\_, Ctrl+Shift+- | Undo last action |
| `chat:externalEditor` | Ctrl+G, Ctrl+X Ctrl+E | Open in external editor |
| `chat:stash` | Ctrl+S | Stash current prompt |
| `chat:imagePaste` | Ctrl+V (Alt+V on Windows) | Paste image |
\*On Windows without VT mode (Node \<24.2.0/\<22.17.0, Bun \<1.2.23), defaults to Meta+M.
Autocomplete actions
Actions available in the `Autocomplete` context:
| Action | Default | Description |
|:------------------------|:--------|:--------------------|
| `autocomplete:accept` | Tab | Accept suggestion |
| `autocomplete:dismiss` | Escape | Dismiss menu |
| `autocomplete:previous` | Up | Previous suggestion |
| `autocomplete:next` | Down | Next suggestion |
Confirmation actions
Actions available in the `Confirmation` context:
| Action | Default | Description |
|:----------------------------|:----------|:------------------------------|
| `confirm:yes` | Y, Enter | Confirm action |
| `confirm:no` | N, Escape | Decline action |
| `confirm:previous` | Up | Previous option |
| `confirm:next` | Down | Next option |
| `confirm:nextField` | Tab | Next field |
| `confirm:previousField` | (unbound) | Previous field |
| `confirm:toggle` | Space | Toggle selection |
| `confirm:cycleMode` | Shift+Tab | Cycle permission modes |
| `confirm:toggleExplanation` | Ctrl+E | Toggle permission explanation |
Permission actions
Actions available in the `Confirmation` context for permission dialogs:
| Action | Default | Description |
|:-------------------------|:--------|:-----------------------------|
| `permission:toggleDebug` | Ctrl+D | Toggle permission debug info |
Transcript actions
Actions available in the `Transcript` context:
| Action | Default | Description |
|:---------------------------|:------------------|:------------------------|
| `transcript:toggleShowAll` | Ctrl+E | Toggle show all content |
| `transcript:exit` | q, Ctrl+C, Escape | Exit transcript view |
History search actions
Actions available in the `HistorySearch` context:
| Action | Default | Description |
|:---------------------------|:------------|:------------------------------------------|
| `historySearch:next` | Ctrl+R | Next match |
| `historySearch:accept` | Escape, Tab | Accept selection |
| `historySearch:cancel` | Ctrl+C | Cancel search |
| `historySearch:execute` | Enter | Execute selected command |
| `historySearch:cycleScope` | Ctrl+S | Cycle scope: session, project, everywhere |
Task actions
Actions available in the `Task` context:
| Action | Default | Description |
|:------------------|:--------|:------------------------|
| `task:background` | Ctrl+B | Background current task |
Theme actions
Actions available in the `ThemePicker` context:
| Action | Default | Description |
|:---------------------------------|:--------|:---------------------------|
| `theme:toggleSyntaxHighlighting` | Ctrl+T | Toggle syntax highlighting |
Help actions
Actions available in the `Help` context:
| Action | Default | Description |
|:---------------|:--------|:----------------|
| `help:dismiss` | Escape | Close help menu |
Tabs actions
Actions available in the `Tabs` context:
| Action | Default | Description |
|:----------------|:----------------|:-------------|
| `tabs:next` | Tab, Right | Next tab |
| `tabs:previous` | Shift+Tab, Left | Previous tab |
Attachments actions
Actions available in the `Attachments` context:
| Action | Default | Description |
|:-----------------------|:------------------|:---------------------------|
| `attachments:next` | Right | Next attachment |
| `attachments:previous` | Left | Previous attachment |
| `attachments:remove` | Backspace, Delete | Remove selected attachment |
| `attachments:exit` | Down, Escape | Exit attachment navigation |
Footer actions
Actions available in the `Footer` context:
| Action | Default | Description |
|:------------------------|:--------|:-----------------------------------------|
| `footer:next` | Right | Next footer item |
| `footer:previous` | Left | Previous footer item |
| `footer:up` | Up | Navigate up in footer (deselects at top) |
| `footer:down` | Down | Navigate down in footer |
| `footer:openSelected` | Enter | Open selected footer item |
| `footer:clearSelection` | Escape | Clear footer selection |
Message selector actions
Actions available in the `MessageSelector` context:
| Action | Default | Description |
|:-------------------------|:------------------------------------------|:------------------|
| `messageSelector:up` | Up, K, Ctrl+P | Move up in list |
| `messageSelector:down` | Down, J, Ctrl+N | Move down in list |
| `messageSelector:top` | Ctrl+Up, Shift+Up, Meta+Up, Shift+K | Jump to top |
| `messageSelector:bottom` | Ctrl+Down, Shift+Down, Meta+Down, Shift+J | Jump to bottom |
| `messageSelector:select` | Enter | Select message |
Diff actions
Actions available in the `DiffDialog` context:
| Action | Default | Description |
|:----------------------|:-------------------|:-----------------------|
| `diff:dismiss` | Escape | Close diff viewer |
| `diff:previousSource` | Left | Previous diff source |
| `diff:nextSource` | Right | Next diff source |
| `diff:previousFile` | Up | Previous file in diff |
| `diff:nextFile` | Down | Next file in diff |
| `diff:viewDetails` | Enter | View diff details |
| `diff:back` | (context-specific) | Go back in diff viewer |
Model picker actions
Actions available in the `ModelPicker` context:
| Action | Default | Description |
|:-----------------------------|:--------|:--------------------------------------------------|
| `modelPicker:decreaseEffort` | Left | Decrease effort level |
| `modelPicker:increaseEffort` | Right | Increase effort level |
| `modelPicker:setAsDefault` | d | Set highlighted model as default for new sessions |
Select actions
Actions available in the `Select` context:
| Action | Default | Description |
|:------------------|:----------------|:-----------------|
| `select:next` | Down, J, Ctrl+N | Next option |
| `select:previous` | Up, K, Ctrl+P | Previous option |
| `select:accept` | Enter | Accept selection |
| `select:cancel` | Escape | Cancel selection |
Plugin actions
Actions available in the `Plugin` context:
| Action | Default | Description |
|:------------------|:--------|:---------------------------------------------------------------------------|
| `plugin:toggle` | Space | Toggle plugin selection |
| `plugin:install` | I | Install selected plugins |
| `plugin:favorite` | F | Favorite the selected plugin so it sorts near the top of the Installed tab |
Settings actions
Actions available in the `Settings` context:
| Action | Default | Description |
|:------------------|:--------|:----------------------------------------------------------------------------|
| `settings:search` | / | Enter search mode |
| `settings:retry` | R | Retry loading usage data (on error) |
| `settings:close` | Enter | Save changes and close the config panel. Escape discards changes and closes |
Doctor actions
Actions available in the `Doctor` context:
| Action | Default | Description |
|:-------------|:--------|:----------------------------------------------------------------------------------------------------|
| `doctor:fix` | F | Send the diagnostics report to Claude to fix the reported issues. Only active when issues are found |
Voice actions
Actions available in the `Chat` context when [voice dictation](/docs/en/voice-dictation) is enabled:
| Action | Default | Description |
|:-------------------|:--------|:---------------------------------------------------------|
| `voice:pushToTalk` | Space | Dictate a prompt. Hold or tap depending on `/voice` mode |
Scroll actions
Actions available in the `Scroll` context when [fullscreen rendering](/docs/en/fullscreen) is enabled:
| Action | Default | Description |
|:----------------------------|:---------------------|:----------------------------------------------------------------------------------------------------------|
| `scroll:lineUp` | (unbound) | Scroll up one line. Mouse wheel scrolling triggers this action |
| `scroll:lineDown` | (unbound) | Scroll down one line. Mouse wheel scrolling triggers this action |
| `scroll:pageUp` | PageUp | Scroll up half the viewport height |
| `scroll:pageDown` | PageDown | Scroll down half the viewport height |
| `scroll:top` | Ctrl+Home | Jump to the start of the conversation |
| `scroll:bottom` | Ctrl+End | Jump to the latest message and re-enable auto-follow |
| `scroll:halfPageUp` | (unbound) | Scroll up half the viewport height. Same behavior as `scroll:pageUp`, provided for vi-style rebinds |
| `scroll:halfPageDown` | (unbound) | Scroll down half the viewport height. Same behavior as `scroll:pageDown`, provided for vi-style rebinds |
| `scroll:fullPageUp` | (unbound) | Scroll up the full viewport height |
| `scroll:fullPageDown` | (unbound) | Scroll down the full viewport height |
| `selection:copy` | Ctrl+Shift+C / Cmd+C | Copy the selected text to the clipboard |
| `selection:clear` | (unbound) | Clear the active text selection |
| `selection:extendLeft` | Shift+Left | Extend the active selection one column left |
| `selection:extendRight` | Shift+Right | Extend the active selection one column right |
| `selection:extendUp` | Shift+Up | Extend the active selection one row up. Scrolls the viewport when the selection reaches the top edge |
| `selection:extendDown` | Shift+Down | Extend the active selection one row down. Scrolls the viewport when the selection reaches the bottom edge |
| `selection:extendLineStart` | Shift+Home | Extend the active selection to the start of the line |
| `selection:extendLineEnd` | Shift+End | Extend the active selection to the end of the line |
Keystroke syntax
Modifiers
Use modifier keys with the `+` separator:
- `ctrl` or `control` - Control key
- `shift` - Shift key
- `alt`, `opt`, `option`, or `meta` - Alt key on Windows and Linux, Option key on macOS
- `cmd`, `command`, `super`, or `win` - Command key on macOS, Windows key on Windows, Super key on Linux
The `cmd` group is only detected in terminals that report the Super modifier, such as those supporting the Kitty keyboard protocol or xterm’s `modifyOtherKeys` mode. Most terminals do not send it, so use `ctrl` or `meta` for bindings you want to work everywhere. For example:
```python
ctrl+k Ctrl + K
shift+tab Shift + Tab
meta+p Option + P on macOS, Alt + P elsewhere
ctrl+shift+c Multiple modifiers
```
Uppercase letters
A standalone uppercase letter implies Shift. For example, `K` is equivalent to `shift+k`. This is useful for vim-style bindings where uppercase and lowercase keys have different meanings. Uppercase letters with modifiers (e.g., `ctrl+K`) are treated as stylistic and do **not** imply Shift: `ctrl+K` is the same as `ctrl+k`.
Chords
Chords are sequences of keystrokes separated by spaces:
```python
ctrl+k ctrl+s Press Ctrl+K, release, then Ctrl+S
```
Special keys
- `escape` or `esc` - Escape key
- `enter` or `return` - Enter key
- `tab` - Tab key
- `space` - Space bar
- `up`, `down`, `left`, `right` - Arrow keys
- `backspace`, `delete` - Delete keys
Unbind default shortcuts
Set an action to `null` to unbind a default shortcut:
```python
{
"bindings": [
{
"context": "Chat",
"bindings": {
"ctrl+s": null
}
}
]
}
```
This also works for chord bindings. Unbinding every chord that shares a prefix frees that prefix for use as a single-key binding:
```python
{
"bindings": [
{
"context": "Chat",
"bindings": {
"ctrl+x ctrl+k": null,
"ctrl+x ctrl+e": null,
"ctrl+x": "chat:newline"
}
}
]
}
```
If you unbind some but not all chords on a prefix, pressing the prefix still enters chord-wait mode for the remaining bindings.
Reserved shortcuts
These shortcuts cannot be rebound:
| Shortcut | Reason |
|:----------|:-----------------------------------------------|
| Ctrl+C | Hardcoded interrupt/cancel |
| Ctrl+D | Hardcoded exit |
| Ctrl+M | Identical to Enter in terminals (both send CR) |
| Caps Lock | Not delivered to terminal applications |
Terminal conflicts
Some shortcuts may conflict with terminal multiplexers:
| Shortcut | Conflict |
|:---------|:----------------------------------|
| Ctrl+B | tmux prefix (press twice to send) |
| Ctrl+A | GNU screen prefix |
| Ctrl+Z | Unix process suspend (SIGTSTP) |
Vim mode interaction
When vim mode is enabled via `/config` → Editor mode, keybindings and vim mode operate independently:
- **Vim mode** handles input at the text input level (cursor movement, modes, motions)
- **Keybindings** handle actions at the component level (toggle todos, submit, etc.)
- The Escape key in vim mode switches INSERT to NORMAL mode; it does not trigger `chat:cancel`
- Most Ctrl+key shortcuts pass through vim mode to the keybinding system
- In vim NORMAL mode, `?` shows the help menu (vim behavior)
Validation
Claude Code validates your keybindings and shows warnings for:
- Parse errors (invalid JSON or structure)
- Invalid context names
- Reserved shortcut conflicts
- Terminal multiplexer conflicts
- Duplicate bindings in the same context
Run `/doctor` to see any keybinding warnings.
---
## customize-your-status-line-claude-code-docs-8a9fc80be1.md
# Customize your status line
Configure a custom status bar to monitor context window usage, costs, and git status in Claude Code
> ## Documentation Index
>
> Fetch the complete documentation index at:
>
> Use this file to discover all available pages before exploring further.
The status line is a customizable bar at the bottom of Claude Code that runs any shell script you configure. It receives JSON session data on stdin and displays whatever your script prints, giving you a persistent, at-a-glance view of context usage, costs, git status, or anything else you want to track. Status lines are useful when you:
- Want to monitor context window usage as you work
- Need to track session costs
- Work across multiple sessions and need to distinguish them
- Want git branch and status always visible
Here’s an example of a [multi-line status line](#display-multiple-lines) that displays git info on the first line and a color-coded context bar on the second.
This page walks through [setting up a basic status line](#set-up-a-status-line), explains [how the data flows](#how-status-lines-work) from Claude Code to your script, lists [all the fields you can display](#available-data), and provides [ready-to-use examples](#examples) for common patterns like git status, cost tracking, and progress bars.
Set up a status line
Use the [`/statusline` command](#use-the-%2Fstatusline-command) to have Claude Code generate a script for you, or [manually create a script](#manually-configure-a-status-line) and add it to your settings.
Use the /statusline command
The `/statusline` command accepts natural language instructions describing what you want displayed. Claude Code generates a script file in `~/.claude/` and updates your settings automatically:
```python
/statusline show model name and context percentage with a progress bar
```
Manually configure a status line
Add a `statusLine` field to your user settings (`~/.claude/settings.json`, where `~` is your home directory) or [project settings](/docs/en/settings#settings-files). Set `type` to `"command"` and point `command` to a script path or an inline shell command. For a full walkthrough of creating a script, see [Build a status line step by step](#build-a-status-line-step-by-step).
```python
{
"statusLine": {
"type": "command",
"command": "~/.claude/statusline.sh",
"padding": 2
}
}
```
The `command` field runs in a shell, so you can also use inline commands instead of a script file. This example uses `jq` to parse the JSON input and display the model name and context percentage:
```python
{
"statusLine": {
"type": "command",
"command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'"
}
}
```
The optional `padding` field adds extra horizontal spacing (in characters) to the status line content. Defaults to `0`. This padding is in addition to the interface’s built-in spacing, so it controls relative indentation rather than absolute distance from the terminal edge. The optional `refreshInterval` field re-runs your command every N seconds in addition to the [event-driven updates](#how-status-lines-work). The minimum is `1`. Set this when your status line shows time-based data such as a clock, or when background subagents change git state while the main session is idle. Leave it unset to run only on events. The optional `hideVimModeIndicator` field suppresses the built-in `-- INSERT --` text below the prompt. Set this to `true` when your script renders [`vim.mode`](#available-data) itself, so the mode is not shown twice.
Disable the status line
Run `/statusline` and ask it to remove or clear your status line (e.g., `/statusline delete`, `/statusline clear`, `/statusline remove it`). You can also manually delete the `statusLine` field from your settings.json.
Build a status line step by step
This walkthrough shows what’s happening under the hood by manually creating a status line that displays the current model, working directory, and context window usage percentage.
Running [`/statusline`](#use-the-%2Fstatusline-command) with a description of what you want configures all of this for you automatically.
These examples use Bash scripts, which work on macOS and Linux. On Windows, see [Windows configuration](#windows-configuration) for PowerShell and Git Bash examples.
1
Create a script that reads JSON and prints output
Claude Code sends JSON data to your script via stdin. This script uses [`jq`](https://jqlang.github.io/jq/), a command-line JSON parser you may need to install, to extract the model name, directory, and context percentage, then prints a formatted line.Save this to `~/.claude/statusline.sh` (where `~` is your home directory, such as `/Users/username` on macOS or `/home/username` on Linux):
```python
#!/bin/bash
# Read JSON data that Claude Code sends to stdin
input=$(cat)
# Extract fields using jq
MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(echo "$input" | jq -r '.workspace.current_dir')
# The "// 0" provides a fallback if the field is null
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
# Output the status line - ${DIR##*/} extracts just the folder name
echo "[$MODEL] 📁 ${DIR##*/} | ${PCT}% context"
```
2
Make it executable
Mark the script as executable so your shell can run it:
```python
chmod +x ~/.claude/statusline.sh
```
3
Add to settings
Tell Claude Code to run your script as the status line. Add this configuration to `~/.claude/settings.json`, which sets `type` to `"command"` (meaning “run this shell command”) and points `command` to your script:
```python
{
"statusLine": {
"type": "command",
"command": "~/.claude/statusline.sh"
}
}
```
Your status line appears at the bottom of the interface. Settings reload automatically, but changes won’t appear until your next interaction with Claude Code.
How status lines work
Claude Code runs your script and pipes [JSON session data](#available-data) to it via stdin. Your script reads the JSON, extracts what it needs, and prints text to stdout. Claude Code displays whatever your script prints. **When it updates** Your script runs after each new assistant message, after `/compact` finishes, when the permission mode changes, or when vim mode toggles. Updates are debounced at 300ms, meaning rapid changes batch together and your script runs once things settle. If a new update triggers while your script is still running, the in-flight execution is cancelled. If you edit your script, the changes won’t appear until your next interaction with Claude Code triggers an update. These triggers can go quiet when the main session is idle, for example while a coordinator waits on background subagents. To keep time-based or externally-sourced segments current during idle periods, set [`refreshInterval`](#manually-configure-a-status-line) to also re-run the command on a fixed timer. **What your script can output**
- **Multiple lines**: each `echo` or `print` statement displays as a separate row. See the [multi-line example](#display-multiple-lines).
- **Colors**: use [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors) like `\033[32m` for green (terminal must support them). See the [git status example](#git-status-with-colors).
- **Links**: use [OSC 8 escape sequences](https://en.wikipedia.org/wiki/ANSI_escape_code#OSC) to make text clickable (Cmd+click on macOS, Ctrl+click on Windows/Linux). Requires a terminal that supports hyperlinks like iTerm2, Kitty, or WezTerm. See the [clickable links example](#clickable-links).
The status line runs locally and does not consume API tokens. It temporarily hides during certain UI interactions, including autocomplete suggestions, the help menu, and permission prompts.
Available data
Claude Code sends the following JSON fields to your script via stdin:
| Field | Description |
|----------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `model.id`, `model.display_name` | Current model identifier and display name |
| `cwd`, `workspace.current_dir` | Current working directory. Both fields contain the same value; `workspace.current_dir` is preferred for consistency with `workspace.project_dir`. |
| `workspace.project_dir` | Directory where Claude Code was launched, which may differ from `cwd` if the working directory changes during a session |
| `workspace.added_dirs` | Additional directories added via `/add-dir` or `--add-dir`. Empty array if none have been added |
| `workspace.git_worktree` | Git worktree name when the current directory is inside a linked worktree created with `git worktree add`. Absent in the main working tree. Populated for any git worktree, unlike `worktree.*` which applies only to `--worktree` sessions |
| `cost.total_cost_usd` | Estimated session cost in USD, computed client-side. May differ from your actual bill |
| `cost.total_duration_ms` | Total wall-clock time since the session started, in milliseconds |
| `cost.total_api_duration_ms` | Total time spent waiting for API responses in milliseconds |
| `cost.total_lines_added`, `cost.total_lines_removed` | Lines of code changed |
| `context_window.total_input_tokens`, `context_window.total_output_tokens` | Token counts currently in the context window, from the most recent API response. Input includes cache reads and writes. Before v2.1.132 these were cumulative session totals |
| `context_window.context_window_size` | Maximum context window size in tokens. 200000 by default, or 1000000 for models with extended context. |
| `context_window.used_percentage` | Pre-calculated percentage of context window used |
| `context_window.remaining_percentage` | Pre-calculated percentage of context window remaining |
| `context_window.current_usage` | Token counts from the last API call, described in [context window fields](#context-window-fields) |
| `exceeds_200k_tokens` | Whether the total token count (input, cache, and output tokens combined) from the most recent API response exceeds 200k. This is a fixed threshold regardless of actual context window size. |
| `effort.level` | Current reasoning effort (`low`, `medium`, `high`, `xhigh`, or `max`). Reflects the live session value, including mid-session `/effort` changes. Absent when the current model does not support the effort parameter |
| `thinking.enabled` | Whether extended thinking is enabled for the session |
| `rate_limits.five_hour.used_percentage`, `rate_limits.seven_day.used_percentage` | Percentage of the 5-hour or 7-day rate limit consumed, from 0 to 100 |
| `rate_limits.five_hour.resets_at`, `rate_limits.seven_day.resets_at` | Unix epoch seconds when the 5-hour or 7-day rate limit window resets |
| `session_id` | Unique session identifier |
| `session_name` | Custom session name set with the `--name` flag or `/rename`. Absent if no custom name has been set |
| `transcript_path` | Path to conversation transcript file |
| `version` | Claude Code version |
| `output_style.name` | Name of the current output style |
| `vim.mode` | Current vim mode (`NORMAL`, `INSERT`, `VISUAL`, or `VISUAL LINE`) when [vim mode](/docs/en/interactive-mode#vim-editor-mode) is enabled |
| `agent.name` | Agent name when running with the `--agent` flag or agent settings configured |
| `worktree.name` | Name of the active worktree. Present only during `--worktree` sessions |
| `worktree.path` | Absolute path to the worktree directory |
| `worktree.branch` | Git branch name for the worktree (for example, `"worktree-my-feature"`). Absent for hook-based worktrees |
| `worktree.original_cwd` | The directory Claude was in before entering the worktree |
| `worktree.original_branch` | Git branch checked out before entering the worktree. Absent for hook-based worktrees |
Full JSON schema
Your status line command receives this JSON structure via stdin:
```python
{
"cwd": "/current/working/directory",
"session_id": "abc123...",
"session_name": "my-session",
"transcript_path": "/path/to/transcript.jsonl",
"model": {
"id": "claude-opus-4-7",
"display_name": "Opus"
},
"workspace": {
"current_dir": "/current/working/directory",
"project_dir": "/original/project/directory",
"added_dirs": [],
"git_worktree": "feature-xyz"
},
"version": "2.1.90",
"output_style": {
"name": "default"
},
"cost": {
"total_cost_usd": 0.01234,
"total_duration_ms": 45000,
"total_api_duration_ms": 2300,
"total_lines_added": 156,
"total_lines_removed": 23
},
"context_window": {
"total_input_tokens": 15500,
"total_output_tokens": 1200,
"context_window_size": 200000,
"used_percentage": 8,
"remaining_percentage": 92,
"current_usage": {
"input_tokens": 8500,
"output_tokens": 1200,
"cache_creation_input_tokens": 5000,
"cache_read_input_tokens": 2000
}
},
"exceeds_200k_tokens": false,
"effort": {
"level": "high"
},
"thinking": {
"enabled": true
},
"rate_limits": {
"five_hour": {
"used_percentage": 23.5,
"resets_at": 1738425600
},
"seven_day": {
"used_percentage": 41.2,
"resets_at": 1738857600
}
},
"vim": {
"mode": "NORMAL"
},
"agent": {
"name": "security-reviewer"
},
"worktree": {
"name": "my-feature",
"path": "/path/to/.claude/worktrees/my-feature",
"branch": "worktree-my-feature",
"original_cwd": "/path/to/project",
"original_branch": "main"
}
}
```
**Fields that may be absent** (not present in JSON):
- `session_name`: appears only when a custom name has been set with `--name` or `/rename`
- `workspace.git_worktree`: appears only when the current directory is inside a linked git worktree
- `effort`: appears only when the current model supports the reasoning effort parameter
- `vim`: appears only when vim mode is enabled
- `agent`: appears only when running with the `--agent` flag or agent settings configured
- `worktree`: appears only during `--worktree` sessions. When present, `branch` and `original_branch` may also be absent for hook-based worktrees
- `rate_limits`: appears only for Claude.ai subscribers (Pro/Max) after the first API response in the session. Each window (`five_hour`, `seven_day`) may be independently absent. Use `jq -r '.rate_limits.five_hour.used_percentage // empty'` to handle absence gracefully.
**Fields that may be `null`**:
- `context_window.current_usage`: `null` before the first API call in a session, and again after `/compact` until the next API call repopulates it
- `context_window.used_percentage`, `context_window.remaining_percentage`: may be `null` early in the session
Handle missing fields with conditional access and null values with fallback defaults in your scripts.
Context window fields
The `context_window` object describes the live context window from the most recent API response. As of v2.1.132, `total_input_tokens` and `total_output_tokens` reflect current context usage, not cumulative session totals.
- **Combined totals** (`total_input_tokens`, `total_output_tokens`): tokens currently in the context window. `total_input_tokens` is the sum of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`; `total_output_tokens` is the output tokens from the most recent response. Both are `0` before the first API response.
- **Per-component usage** (`current_usage`): the same token counts broken out by category. Use this when you need cache hits separate from fresh input.
The `current_usage` object contains:
- `input_tokens`: input tokens in current context
- `output_tokens`: output tokens generated
- `cache_creation_input_tokens`: tokens written to cache
- `cache_read_input_tokens`: tokens read from cache
For what the cache fields mean and how they’re billed, see [check cache performance](/docs/en/prompt-caching#check-cache-performance). The `used_percentage` field is calculated from input tokens only: `input_tokens + cache_creation_input_tokens + cache_read_input_tokens`. It does not include `output_tokens`. If you calculate context percentage manually from `current_usage`, use the same input-only formula to match `used_percentage`. The `current_usage` object is `null` before the first API call in a session, and again immediately after `/compact` until the next API call repopulates it.
Examples
These examples show common status line patterns. To use any example:
1. Save the script to a file like `~/.claude/statusline.sh` (or `.py`/`.js`)
2. Make it executable: `chmod +x ~/.claude/statusline.sh`
3. Add the path to your [settings](#manually-configure-a-status-line)
The Bash examples use [`jq`](https://jqlang.github.io/jq/) to parse JSON. Python and Node.js have built-in JSON parsing.
Context window usage
Display the current model and context window usage with a visual progress bar. Each script reads JSON from stdin, extracts the `used_percentage` field, and builds a 10-character bar where filled blocks (▓) represent usage:
Bash
Python
Node.js
```python
#!/bin/bash
# Read all of stdin into a variable
input=$(cat)
# Extract fields with jq, "// 0" provides fallback for null
MODEL=$(echo "$input" | jq -r '.model.display_name')
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
# Build progress bar: printf -v creates a run of spaces, then
# ${var// /▓} replaces each space with a block character
BAR_WIDTH=10
FILLED=$((PCT * BAR_WIDTH / 100))
EMPTY=$((BAR_WIDTH - FILLED))
BAR=""
[ "$FILLED" -gt 0 ] && printf -v FILL "%${FILLED}s" && BAR="${FILL// /▓}"
[ "$EMPTY" -gt 0 ] && printf -v PAD "%${EMPTY}s" && BAR="${BAR}${PAD// /░}"
echo "[$MODEL] $BAR $PCT%"
```
Git status with colors
Show git branch with color-coded indicators for staged and modified files. This script uses [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors) for terminal colors: `\033[32m` is green, `\033[33m` is yellow, and `\033[0m` resets to default.
Each script checks if the current directory is a git repository, counts staged and modified files, and displays color-coded indicators:
Bash
Python
Node.js
```python
#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(echo "$input" | jq -r '.workspace.current_dir')
GREEN='\033[32m'
YELLOW='\033[33m'
RESET='\033[0m'
if git rev-parse --git-dir > /dev/null 2>&1; then
BRANCH=$(git branch --show-current 2>/dev/null)
STAGED=$(git diff --cached --numstat 2>/dev/null | wc -l | tr -d ' ')
MODIFIED=$(git diff --numstat 2>/dev/null | wc -l | tr -d ' ')
GIT_STATUS=""
[ "$STAGED" -gt 0 ] && GIT_STATUS="${GREEN}+${STAGED}${RESET}"
[ "$MODIFIED" -gt 0 ] && GIT_STATUS="${GIT_STATUS}${YELLOW}~${MODIFIED}${RESET}"
echo -e "[$MODEL] 📁 ${DIR##*/} | 🌿 $BRANCH $GIT_STATUS"
else
echo "[$MODEL] 📁 ${DIR##*/}"
fi
```
Cost and duration tracking
Track your session’s API costs and elapsed time. The `cost.total_cost_usd` field accumulates the estimated cost of all API calls in the current session. The `cost.total_duration_ms` field measures total elapsed time since the session started, while `cost.total_api_duration_ms` tracks only the time spent waiting for API responses. Each script formats cost as currency and converts milliseconds to minutes and seconds:
Bash
Python
Node.js
```python
#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
COST=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
DURATION_MS=$(echo "$input" | jq -r '.cost.total_duration_ms // 0')
COST_FMT=$(printf '$%.2f' "$COST")
DURATION_SEC=$((DURATION_MS / 1000))
MINS=$((DURATION_SEC / 60))
SECS=$((DURATION_SEC % 60))
echo "[$MODEL] 💰 $COST_FMT | ⏱️ ${MINS}m ${SECS}s"
```
Display multiple lines
Your script can output multiple lines to create a richer display. Each `echo` statement produces a separate row in the status area.
This example combines several techniques: threshold-based colors (green under 70%, yellow 70-89%, red 90%+), a progress bar, and git branch info. Each `print` or `echo` statement creates a separate row:
Bash
Python
Node.js
```python
#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(echo "$input" | jq -r '.workspace.current_dir')
COST=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
DURATION_MS=$(echo "$input" | jq -r '.cost.total_duration_ms // 0')
CYAN='\033[36m'; GREEN='\033[32m'; YELLOW='\033[33m'; RED='\033[31m'; RESET='\033[0m'
# Pick bar color based on context usage
if [ "$PCT" -ge 90 ]; then BAR_COLOR="$RED"
elif [ "$PCT" -ge 70 ]; then BAR_COLOR="$YELLOW"
else BAR_COLOR="$GREEN"; fi
FILLED=$((PCT / 10)); EMPTY=$((10 - FILLED))
printf -v FILL "%${FILLED}s"; printf -v PAD "%${EMPTY}s"
BAR="${FILL// /█}${PAD// /░}"
MINS=$((DURATION_MS / 60000)); SECS=$(((DURATION_MS % 60000) / 1000))
BRANCH=""
git rev-parse --git-dir > /dev/null 2>&1 && BRANCH=" | 🌿 $(git branch --show-current 2>/dev/null)"
echo -e "${CYAN}[$MODEL]${RESET} 📁 ${DIR##*/}$BRANCH"
COST_FMT=$(printf '$%.2f' "$COST")
echo -e "${BAR_COLOR}${BAR}${RESET} ${PCT}% | ${YELLOW}${COST_FMT}${RESET} | ⏱️ ${MINS}m ${SECS}s"
```
Clickable links
This example creates a clickable link to your GitHub repository. It reads the git remote URL, converts SSH format to HTTPS with `sed`, and wraps the repo name in OSC 8 escape codes. Hold Cmd (macOS) or Ctrl (Windows/Linux) and click to open the link in your browser.
Each script gets the git remote URL, converts SSH format to HTTPS, and wraps the repo name in OSC 8 escape codes. The Bash version uses `printf '%b'` which interprets backslash escapes more reliably than `echo -e` across different shells:
Bash
Python
Node.js
```python
#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
# Convert git SSH URL to HTTPS
REMOTE=$(git remote get-url origin 2>/dev/null | sed 's/git@github.com:/https:\/\/github.com\//' | sed 's/\.git$//')
if [ -n "$REMOTE" ]; then
REPO_NAME=$(basename "$REMOTE")
# OSC 8 format: \e]8;;URL\a then TEXT then \e]8;;\a
# printf %b interprets escape sequences reliably across shells
printf '%b' "[$MODEL] 🔗 \e]8;;${REMOTE}\a${REPO_NAME}\e]8;;\a\n"
else
echo "[$MODEL]"
fi
```
Rate limit usage
Display Claude.ai subscription rate limit usage in the status line. The `rate_limits` object contains `five_hour` (5-hour rolling window) and `seven_day` (weekly) windows. Each window provides `used_percentage` (0-100) and `resets_at` (Unix epoch seconds when the window resets). This field is only present for Claude.ai subscribers (Pro/Max) after the first API response. Each script handles the absent field gracefully:
Bash
Python
Node.js
```python
#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
# "// empty" produces no output when rate_limits is absent
FIVE_H=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty')
WEEK=$(echo "$input" | jq -r '.rate_limits.seven_day.used_percentage // empty')
LIMITS=""
[ -n "$FIVE_H" ] && LIMITS="5h: $(printf '%.0f' "$FIVE_H")%"
[ -n "$WEEK" ] && LIMITS="${LIMITS:+$LIMITS }7d: $(printf '%.0f' "$WEEK")%"
[ -n "$LIMITS" ] && echo "[$MODEL] | $LIMITS" || echo "[$MODEL]"
```
Cache expensive operations
Your status line script runs frequently during active sessions. Commands like `git status` or `git diff` can be slow, especially in large repositories. This example caches git information to a temp file and only refreshes it every 5 seconds. The cache filename needs to be stable across status line invocations within a session, but unique across sessions so concurrent sessions in different repositories don’t read each other’s cached git state. Process-based identifiers like `$$`, `os.getpid()`, or `process.pid` change on every invocation and defeat the cache. Use the `session_id` from the JSON input instead: it’s stable for the lifetime of a session and unique per session. Each script checks if the cache file is missing or older than 5 seconds before running git commands:
Bash
Python
Node.js
```python
#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(echo "$input" | jq -r '.workspace.current_dir')
SESSION_ID=$(echo "$input" | jq -r '.session_id')
CACHE_FILE="/tmp/statusline-git-cache-$SESSION_ID"
CACHE_MAX_AGE=5 # seconds
cache_is_stale() {
[ ! -f "$CACHE_FILE" ] || \
# stat -f %m is macOS, stat -c %Y is Linux
[ $(($(date +%s) - $(stat -f %m "$CACHE_FILE" 2>/dev/null || stat -c %Y "$CACHE_FILE" 2>/dev/null || echo 0))) -gt $CACHE_MAX_AGE ]
}
if cache_is_stale; then
if git rev-parse --git-dir > /dev/null 2>&1; then
BRANCH=$(git branch --show-current 2>/dev/null)
STAGED=$(git diff --cached --numstat 2>/dev/null | wc -l | tr -d ' ')
MODIFIED=$(git diff --numstat 2>/dev/null | wc -l | tr -d ' ')
echo "$BRANCH|$STAGED|$MODIFIED" > "$CACHE_FILE"
else
echo "||" > "$CACHE_FILE"
fi
fi
IFS='|' read -r BRANCH STAGED MODIFIED < "$CACHE_FILE"
if [ -n "$BRANCH" ]; then
echo "[$MODEL] 📁 ${DIR##*/} | 🌿 $BRANCH +$STAGED ~$MODIFIED"
else
echo "[$MODEL] 📁 ${DIR##*/}"
fi
```
Windows configuration
On Windows, Claude Code runs status line commands through Git Bash when Git Bash is installed, or through PowerShell when Git Bash is absent. Git Bash treats unquoted backslashes as escape characters, so a Windows-style path such as `C:\Users\username\script.mjs` reaches the script runner with its separators removed and the command fails without a visible error. Write file paths in the `command` string with forward slashes, as shown in the examples below. The `~` shorthand also works and expands to your Windows home directory. To run a PowerShell script as your status line, invoke it via `powershell`. This works whether Claude Code routes the command through Git Bash or PowerShell:
settings.json
statusline.ps1
```python
{
"statusLine": {
"type": "command",
"command": "powershell -NoProfile -File C:/Users/username/.claude/statusline.ps1"
}
}
```
Or, when Git Bash is installed, run a Bash script directly:
settings.json
statusline.sh
```python
{
"statusLine": {
"type": "command",
"command": "~/.claude/statusline.sh"
}
}
```
Subagent status lines
The `subagentStatusLine` setting renders a custom row body for each [subagent](/docs/en/sub-agents) shown in the agent panel below the prompt. Use it to replace the default `name · description · token count` row with your own formatting.
```python
{
"subagentStatusLine": {
"type": "command",
"command": "~/.claude/subagent-statusline.sh"
}
}
```
The command runs once per refresh tick with all visible subagent rows passed as a single JSON object on stdin. The input includes the [base hook fields](/docs/en/hooks#common-input-fields) plus `columns` (the usable row width) and a `tasks` array, where each task has `id`, `name`, `type`, `status`, `description`, `label`, `startTime`, `tokenCount`, `tokenSamples`, and `cwd`. Write one JSON line to stdout per row you want to override, in the form `{"id": "", "content": ""}`. The `content` string is rendered as-is, including ANSI colors and OSC 8 hyperlinks. Omit a task’s `id` to keep the default rendering for that row; emit an empty `content` string to hide it. The same trust and `disableAllHooks` gates that apply to `statusLine` apply here. Plugins can ship a default `subagentStatusLine` in their [`settings.json`](/docs/en/plugins-reference#standard-plugin-layout).
Tips
- **Test with mock input**: `echo '{"model":{"display_name":"Opus"},"workspace":{"current_dir":"/home/user/project"},"context_window":{"used_percentage":25},"session_id":"test-session-abc"}' | ./statusline.sh`
- **Keep output short**: the status bar has limited width, so long output may get truncated or wrap awkwardly
- **Cache slow operations**: your script runs frequently during active sessions, so commands like `git status` can cause lag. See the [caching example](#cache-expensive-operations) for how to handle this.
Community projects like [ccstatusline](https://github.com/sirmalloc/ccstatusline) and [starship-claude](https://github.com/martinemde/starship-claude) provide pre-built configurations with themes and additional features.
Troubleshooting
**Status line not appearing**
- Verify your script is executable: `chmod +x ~/.claude/statusline.sh`
- Check that your script outputs to stdout, not stderr
- Run your script manually to verify it produces output
- On Windows with Git Bash installed, backslashes in the `command` path are likely being consumed as escape characters before the script runs. Use forward slashes in the path. See [Windows configuration](#windows-configuration).
- If `disableAllHooks` is set to `true` in your settings, the status line is also disabled. Remove this setting or set it to `false` to re-enable.
- Run `claude --debug` to log the exit code and stderr from the first status line invocation in a session
- Ask Claude to read your settings file and execute the `statusLine` command directly to surface errors
**Status line shows `--` or empty values**
- Fields may be `null` before the first API response completes
- Handle null values in your script with fallbacks such as `// 0` in jq
- Restart Claude Code if values remain empty after multiple messages
**Context percentage shows unexpected values**
- Use `used_percentage` for the simplest accurate context state
- Context percentage may differ from `/context` output due to when each is calculated
**OSC 8 links not clickable**
- Verify your terminal supports OSC 8 hyperlinks (iTerm2, Kitty, WezTerm)
- Terminal.app does not support clickable links
- If link text appears but isn’t clickable, Claude Code may not have detected hyperlink support in your terminal. This commonly affects Windows Terminal and other emulators not in the auto-detection list. Set the `FORCE_HYPERLINK` environment variable to override detection before launching Claude Code:
``` shiki
FORCE_HYPERLINK=1 claude
```
In PowerShell, set the variable in the current session first:
``` shiki
$env:FORCE_HYPERLINK = "1"; claude
```
- SSH and tmux sessions may strip OSC sequences depending on configuration
- If escape sequences appear as literal text like `\e]8;;`, use `printf '%b'` instead of `echo -e` for more reliable escape handling
**Display glitches with escape sequences**
- Complex escape sequences (ANSI colors, OSC 8 links) can occasionally cause garbled output if they overlap with other UI updates
- If you see corrupted text, try simplifying your script to plain text output
- Multi-line status lines with escape codes are more prone to rendering issues than single-line plain text
**Workspace trust required**
- The status line command only runs if you’ve accepted the workspace trust dialog for the current directory. Because `statusLine` executes a shell command, it requires the same trust acceptance as hooks and other shell-executing settings.
- If trust isn’t accepted, you’ll see the notification `statusline skipped · restart to fix` instead of your status line output. Restart Claude Code and accept the trust prompt to enable it.
**Script errors or hangs**
- Scripts that exit with non-zero codes or produce no output cause the status line to go blank
- Slow scripts block the status line from updating until they complete. Keep scripts fast to avoid stale output.
- If a new update triggers while a slow script is running, the in-flight script is cancelled
- Test your script independently with mock input before configuring it
**Notifications share the status line row**
- System notifications like MCP server errors and auto-updates display on the right side of the same row as your status line. Transient notifications such as the context-low warning also cycle through this area.
- Enabling verbose mode adds a token counter to this area
- On narrow terminals, these notifications may truncate your status line output
---
## data-usage-a28ecced65.md
> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Data usage
> Learn about Anthropic's data usage policies for Claude
## Data policies
### Data training policy
**Consumer users (Free, Pro, and Max plans)**:
We give you the choice to allow your data to be used to improve future Claude models. We will train new models using data from Free, Pro, and Max accounts when this setting is on (including when you use Claude Code from these accounts).
**Commercial users**: (Team and Enterprise plans, API, 3rd-party platforms, and Claude Gov) maintain existing policies: Anthropic does not train generative models using code or prompts sent to Claude Code under commercial terms, unless the customer has chosen to provide their data to us for model improvement (for example, the [Developer Partner Program](https://support.claude.com/en/articles/11174108-about-the-development-partner-program)).
### Development Partner Program
If you explicitly opt in to methods to provide us with materials to train on, such as via the [Development Partner Program](https://support.claude.com/en/articles/11174108-about-the-development-partner-program), we may use those materials provided to train our models. An organization admin can expressly opt-in to the Development Partner Program for their organization. Note that this program is available only for Anthropic first-party API, and not for Bedrock or Vertex users.
### Feedback using the `/feedback` command
If you choose to send us feedback about Claude Code using the `/feedback` command, we may use your feedback to improve our products and services. Transcripts shared via `/feedback` are retained for 5 years.
### Session quality surveys
When you see the "How is Claude doing this session?" prompt in Claude Code, responding to this survey (including selecting "Dismiss"), only your numeric rating (1, 2, 3, or dismiss) is recorded. We do not collect or store any conversation transcripts, inputs, outputs, or other session data as part of this survey. Unlike thumbs up/down feedback or `/feedback` reports, this session quality survey is a simple product satisfaction metric. Your responses to this survey do not impact your data training preferences and cannot be used to train our AI models.
To disable these surveys, set `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1`. The survey is also disabled when `DISABLE_TELEMETRY` or `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` is set. To control frequency instead of disabling, set [`feedbackSurveyRate`](/en/settings#available-settings) in your settings file to a probability between `0` and `1`.
### Data retention
Anthropic retains Claude Code data based on your account type and preferences.
**Consumer users (Free, Pro, and Max plans)**:
* Users who allow data use for model improvement: 5-year retention period to support model development and safety improvements
* Users who don't allow data use for model improvement: 30-day retention period
* Privacy settings can be changed at any time at [claude.ai/settings/data-privacy-controls](https://claude.ai/settings/data-privacy-controls).
**Commercial users (Team, Enterprise, and API)**:
* Standard: 30-day retention period
* [Zero data retention](../22-Safety-Policy/zero-data-retention-claude-code-docs-6ec9ee63f1.md): available for Claude Code on Claude for Enterprise. ZDR is enabled on a per-organization basis; each new organization must have ZDR enabled separately by your account team
* Local caching: Claude Code clients store session transcripts locally in plaintext under `~/.claude/projects/` for 30 days by default to enable session resumption. Adjust the period with `cleanupPeriodDays`. See [application data](/en/claude-directory#application-data) for what's stored and how to clear it.
You can delete individual Claude Code on the web sessions at any time. Deleting a session permanently removes the session's event data. For instructions on how to delete sessions, see [Delete sessions](/en/claude-code-on-the-web#delete-sessions).
Learn more about data retention practices in our [Privacy Center](https://privacy.anthropic.com/).
For full details, please review our [Commercial Terms of Service](https://www.anthropic.com/legal/commercial-terms) (for Team, Enterprise, and API users) or [Consumer Terms](https://www.anthropic.com/legal/consumer-terms) (for Free, Pro, and Max users) and [Privacy Policy](https://www.anthropic.com/legal/privacy).
## Data access
For all first party users, you can learn more about what data is logged for [local Claude Code](#local-claude-code-data-flow-and-dependencies) and [remote Claude Code](#cloud-execution-data-flow-and-dependencies). [Remote Control](continue-local-sessions-from-any-device-with-remote-control-claude-code-docs-c1c03fd914.md) sessions follow the local data flow since all execution happens on your machine. Note for remote Claude Code, Claude accesses the repository where you initiate your Claude Code session. Claude does not access repositories that you have connected but have not started a session in.
## Local Claude Code: Data flow and dependencies
The diagram below shows how Claude Code connects to external services during installation and normal operation. Solid lines indicate required connections, while dashed lines represent optional or user-initiated data flows.
Claude Code runs locally. To interact with the LLM, Claude Code sends data over the network. This data includes all user prompts and model outputs, encrypted in transit via TLS 1.2+. Claude Code is compatible with most popular VPNs and LLM proxies.
Encryption at rest depends on your model provider:
| Provider | Encryption at rest |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Anthropic API | Infrastructure-level disk encryption (AES-256). Enable [Zero Data Retention](../22-Safety-Policy/zero-data-retention-claude-code-docs-6ec9ee63f1.md) for no server-side persistence. |
| Amazon Bedrock | AES-256 with AWS-managed keys. Customer-managed keys available via AWS KMS. |
| Google Cloud Vertex AI | Google-managed encryption keys. CMEK available. |
| Microsoft Foundry | Requests route to Anthropic infrastructure with AES-256 disk encryption. |
Claude Code is built on Anthropic's APIs. For details on API security controls, including API logging procedures, see the compliance artifacts in the [Anthropic Trust Center](https://trust.anthropic.com).
### Cloud execution: Data flow and dependencies
When using [Claude Code on the web](claude-code-on-the-web-69d53821d4.md), sessions run in Anthropic-managed virtual machines instead of locally. In cloud environments:
* **Code and data storage:** Your repository is cloned to an isolated VM. Code and session data are subject to the retention and usage policies for your account type (see Data retention section above)
* **Credentials:** GitHub authentication is handled through a secure proxy; your GitHub credentials never enter the sandbox
* **Network traffic:** All outbound traffic goes through a security proxy for audit logging and abuse prevention
* **Session data:** Prompts, code changes, and outputs follow the same data policies as local Claude Code usage
For security details about cloud execution, see [Security](/en/security#cloud-execution-security).
## Telemetry services
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 `/feedback` command, a copy of their full conversation history including code is sent to Anthropic. The data is encrypted in transit via TLS. Optionally, a GitHub issue is created in the public repository. To opt out, set the `DISABLE_FEEDBACK_COMMAND` environment variable to `1`.
## Default behaviors by API provider
By default, error reporting, telemetry, and bug reporting are disabled when using Bedrock, Vertex, or Foundry. Session quality surveys and the WebFetch domain safety check are exceptions and run regardless of provider. You can opt out of all non-essential traffic, including surveys, at once by setting `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`. This variable does not affect the WebFetch check, which has its own opt-out. Here are the full default behaviors:
| Service | Claude API | Vertex API | Bedrock API | Foundry 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. | Default off.
`CLAUDE_CODE_USE_FOUNDRY` 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. | Default off.
`CLAUDE_CODE_USE_FOUNDRY` must be 1. | | **Claude API (`/feedback` reports)** | Default on.
`DISABLE_FEEDBACK_COMMAND=1` to disable. | Default off.
`CLAUDE_CODE_USE_VERTEX` must be 1. | Default off.
`CLAUDE_CODE_USE_BEDROCK` must be 1. | Default off.
`CLAUDE_CODE_USE_FOUNDRY` must be 1. | | **Session quality surveys** | Default on.
`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1` to disable. | Default on.
`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1` to disable. | Default on.
`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1` to disable. | Default on.
`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1` to disable. | | **WebFetch domain safety check** | Default on.
`skipWebFetchPreflight: true` in [settings](claude-code-settings-claude-code-docs-d4420b4b52.md) to disable. | Default on.
`skipWebFetchPreflight: true` in [settings](claude-code-settings-claude-code-docs-d4420b4b52.md) to disable. | Default on.
`skipWebFetchPreflight: true` in [settings](claude-code-settings-claude-code-docs-d4420b4b52.md) to disable. | Default on.
`skipWebFetchPreflight: true` in [settings](claude-code-settings-claude-code-docs-d4420b4b52.md) to disable. | All environment variables can be checked into `settings.json` (see [settings reference](claude-code-settings-claude-code-docs-d4420b4b52.md)). ### WebFetch domain safety check Before fetching a URL, the WebFetch tool sends the requested hostname to `api.anthropic.com` to check it against a safety blocklist maintained by Anthropic. Only the hostname is sent, not the full URL, path, or page contents. Results are cached per hostname for five minutes. This check runs regardless of which model provider you use and is not affected by `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`. If your network blocks `api.anthropic.com`, WebFetch requests fail until you either allowlist the domain or set `skipWebFetchPreflight: true` in [settings](claude-code-settings-claude-code-docs-d4420b4b52.md). Disabling the check means WebFetch attempts to retrieve any URL without consulting the blocklist, so combine it with [`WebFetch` permission rules](/en/permissions#webfetch) if you need to restrict which domains Claude can reach. --- ## debug-your-config-615fc7cc73.md > ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Debug your configuration > Diagnose why CLAUDE.md, settings, hooks, MCP servers, or skills aren't taking effect. Use /context, /doctor, /hooks, and /mcp to see what actually loaded. When Claude ignores an instruction or a feature you configured doesn't appear, the cause is usually that the file didn't load, it loaded from a different location than you expected, or another file overrode it. This guide shows how to inspect what Claude Code actually loaded so you can narrow down which applies. For installation, authentication, and connectivity problems, see [Troubleshooting](../21-Account-Support/troubleshooting-claude-code-docs-3f3657ed0f.md) instead. ## See what loaded into context The `/context` command shows everything occupying the context window for the current session, broken down by category: system prompt, memory files, skills, MCP tools, and conversation messages. Run it first to confirm whether your `CLAUDE.md`, rules, or skill descriptions are present at all. For detail on a specific category, follow up with the dedicated command: | Command | Shows | | :------------- | :-------------------------------------------------------------------------- | | `/memory` | Which `CLAUDE.md` and rules files loaded, plus auto-memory entries | | `/skills` | Available skills from project, user, and plugin sources | | `/agents` | Configured subagents and their settings | | `/hooks` | Active hook configurations | | `/mcp` | Connected MCP servers and their status | | `/permissions` | Resolved allow and deny rules currently in effect | | `/doctor` | Configuration diagnostics: invalid keys, schema errors, installation health | | `/status` | Active settings sources, including whether managed settings are in effect | If a memory file is missing from `/memory`, check its location against [how CLAUDE.md files load](/en/memory#how-claude-md-files-load). Subdirectory `CLAUDE.md` files load on demand when Claude reads a file in that directory with the Read tool, not at session start. If `/memory` confirms the file loaded but Claude still isn't following a particular instruction, the issue is likely how the instruction is written rather than whether it loaded. CLAUDE.md works well for the kinds of guidance you'd give a new teammate, such as project conventions, build commands, and where files belong. Adherence drops when an instruction is vague enough to interpret multiple ways, when two files give conflicting direction, or when the file has grown long enough that individual rules get less attention. [Write effective instructions](/en/memory#write-effective-instructions) covers the specificity, size, and structure patterns that keep adherence high.
CLAUDE.md and permissions solve different problems. CLAUDE.md tells Claude how your project works so it makes good decisions. [Permissions](configure-permissions-claude-code-docs-7b0e64d485.md) and [hooks](../07-Hooks/hooks-9168ed62a4.md) enforce limits regardless of what Claude decides. Use CLAUDE.md for "we do it this way here." Use permissions or hooks for security boundaries and anything that must never happen, where you need a guarantee instead of guidance.
## Check resolved settings
Settings merge across managed, user, project, and local scopes. Managed settings always win when present. Among the rest, the closer scope overrides the broader one in the order local, then project, then user. Some settings can also be set by command-line flags or [environment variables](env-vars-5c624d392b.md), which act as another override layer. When a setting doesn't seem to apply, the value you set is usually being overridden by another scope or an environment variable.
Run `/doctor` to validate your configuration files and surface invalid keys or schema errors. Run `/status` to see which settings sources are active, including whether managed settings are in effect. To understand which scope wins for a given key, see [How scopes interact](/en/settings#how-scopes-interact).
## Check MCP servers
Run `/mcp` to see every configured server, its connection status, and whether you have approved it for the current project. A server can be defined correctly but still not provide tools for a few common reasons:
* Project-scoped servers in `.mcp.json` require a one-time approval. If the prompt was dismissed, the server stays disabled until you approve it from `/mcp`.
* A server that fails to start shows as failed in `/mcp`. Relative file paths in `command` or `args` are a frequent cause, since they resolve against the directory you launched Claude Code from rather than the location of `.mcp.json`.
* A server that shows as connected but lists zero tools has started successfully but isn't returning a tool list. Select **Reconnect** from `/mcp`. If the count stays at zero, run `claude --debug mcp` to see the server's stderr output.
For configuration locations and scope rules, see [MCP](../06-MCP-Tools/mcp-208e742686.md).
## Check hooks
Run `/hooks` to list every hook registered for the current session, grouped by event. If a hook you defined doesn't appear, it isn't being read: hooks go under the `"hooks"` key in a settings file, not in a standalone file.
If the hook appears but doesn't fire, the matcher is the usual cause. The `matcher` field is a single string that uses `|` to match multiple tool names, for example `"Edit|Write"`. A misspelled tool name fails silently because the matcher never matches. An array value is a schema error: Claude Code shows a settings error notice, `/doctor` reports the validation failure, and the hook entry is dropped so it won't appear in `/hooks`.
Edits to `settings.json` take effect in the running session after a brief file-stability delay. You don't need to restart. If `/hooks` still shows the old definition a few seconds after saving, run `/hooks` again to refresh the view.
If `/hooks` shows the hook but it still does not fire, the next step is to watch hook evaluation live. Start a session with `claude --debug hooks` and trigger the tool call. The debug log records each event, which matchers were checked, and the hook's exit code and output. See [Debug hooks](/en/hooks#debug-hooks) for the log format and [hooks troubleshooting](/en/hooks-guide#limitations-and-troubleshooting) for common failure patterns.
## Common causes
Most configuration surprises trace back to a small set of location and syntax rules. Check these before assuming a bug:
| Symptom | Cause | Fix |
| :--------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hook never fires | `matcher` is a JSON array instead of a string | Use a single string with `\|` to match multiple tools, for example `"Edit\|Write"`. See [matcher patterns](/en/hooks#matcher-patterns). |
| Hook never fires | `matcher` value is lowercase, for example `"bash"` | Matching is case-sensitive. Tool names are capitalized: `Bash`, `Edit`, `Write`, `Read`. |
| Hook never fires | Hooks are in a standalone `.claude/hooks.json` file | There is no standalone hooks file. Define hooks under the `"hooks"` key in `settings.json`. See [hook configuration](../07-Hooks/hooks-9168ed62a4.md). |
| Permissions, hooks, or env set globally are ignored | Configuration was added to `~/.claude.json` | `~/.claude.json` holds app state and UI toggles. `permissions`, `hooks`, and `env` belong in `~/.claude/settings.json`. These are two different files. |
| A `settings.json` value seems ignored | The same key is set in `settings.local.json` | `settings.local.json` overrides `settings.json`, and both override `~/.claude/settings.json`. See [settings precedence](/en/settings#how-scopes-interact). |
| Skill doesn't appear in `/skills` | Skill file is at `.claude/skills/name.md` instead of in a folder | Use a folder with `SKILL.md` inside: `.claude/skills/name/SKILL.md`. |
| Skill appears in `/skills` but Claude never invokes it | Skill has `disable-model-invocation: true` in its frontmatter, or its description doesn't match how you phrase the request | Check the badge in `/skills`: a "user-only" label means Claude won't trigger it on its own. See [skill invocation](../08-Plugins-Skills/extend-claude-with-skills-claude-code-docs.md). |
| Subdirectory `CLAUDE.md` instructions seem ignored | Subdirectory files load on demand, not at session start | They load when Claude reads a file in that directory with the Read tool, not at launch and not when writing or creating files there. See [how CLAUDE.md files load](/en/memory#how-claude-md-files-load). |
| Subagent ignores `CLAUDE.md` instructions | Subagents don't always inherit project memory | Put critical rules in the agent file body, which becomes the subagent's system prompt. See [subagent configuration](../09-Agents-Patterns/create-custom-subagents-claude-code-docs-7dc93e85c0.md). |
| Cleanup logic never runs at session end | No `SessionEnd` hook configured | `SessionStart` and `SessionEnd` both exist. See the [hook events list](/en/hooks#hook-events). |
| MCP servers in `.mcp.json` never load | File is under `.claude/` or uses Claude Desktop's config format | Project MCP config goes at the repository root as `.mcp.json`, not inside `.claude/`. See [MCP configuration](../06-MCP-Tools/mcp-208e742686.md). |
| Project MCP server added but doesn't appear | The one-time approval prompt was dismissed | Project-scoped servers require approval. Run `/mcp` to see status and approve. |
| MCP server fails to start from some directories | `command` or `args` uses a relative file path | Use absolute paths for local scripts. Executables on your `PATH` like `npx` or `uvx` work as-is. |
| MCP server starts without expected environment variables | Variables are in `settings.json` `env`, which doesn't propagate to MCP child processes | Set per-server `env` inside `.mcp.json` instead. |
| `Bash(rm *)` deny rule doesn't block `/bin/rm` or `find -delete` | Prefix rules match the literal command string, not the underlying executable | Add explicit patterns for each variant, or use a [PreToolUse hook](../07-Hooks/automate-workflows-with-hooks-claude-code-docs-e843f93261.md) or the [sandbox](../22-Safety-Policy/sandboxing-claude-code-docs-5f97cd27c4.md) for a hard guarantee. |
## Related resources
For full reference on each configuration surface, see the dedicated page:
* **[`.claude` directory reference](claude-directory-06f83438fe.md)**: every config file location and what reads it
* **[Settings](claude-code-settings-claude-code-docs-d4420b4b52.md)**: precedence order and the full key list
* **[Hooks reference](../07-Hooks/hooks-9168ed62a4.md)**: event names, payloads, and `--debug hooks` output format
* **[MCP](../06-MCP-Tools/mcp-208e742686.md)**: server configuration, approval, and `/mcp` output
* **[Troubleshooting](../21-Account-Support/troubleshooting-claude-code-docs-3f3657ed0f.md)**: `claude doctor`, platform issues, and installation problems
---
## desktop-18b59ad2b5.md
> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Use Claude Code Desktop
> Get more out of Claude Code Desktop: parallel sessions with Git isolation, drag-and-drop pane layout, integrated terminal and file editor, side chats, computer use, Dispatch sessions from your phone, visual diff review, app previews, PR monitoring, connectors, and enterprise configuration.
The Claude Desktop app has three tabs: **Chat** for conversations, **Cowork** for [Dispatch and longer agentic work](https://claude.com/product/cowork), and **Code** for software development. This page is the reference for the Code tab.
Universal build for Intel and Apple Silicon
For x64 processors
For Windows ARM64, download the [ARM64 installer](https://claude.ai/api/desktop/win32/arm64/setup/latest/redirect?utm_source=claude_code\&utm_medium=docs). Linux is not supported.
After installing, launch Claude, sign in, and click the **Code** tab. The first time you open it on Windows, you need [Git for Windows](https://git-scm.com/downloads/win) installed; restart the app after installing it. For a walkthrough of your first session, see the [Get started guide](../16-Mobile-Desktop/desktop-quickstart.md).
In the Code tab, each conversation is a **session**: it has its own chat history, project folder, and code changes, independent of any other session. The sidebar lists your sessions and lets you run several in parallel. Within a session you can:
* [Review and comment on diffs](#review-changes-with-diff-view), then [watch the resulting PR through CI](#monitor-pull-request-status)
* [Preview your running app](#preview-your-app) in an embedded browser while Claude verifies its own changes
* [Arrange panes](#arrange-your-workspace) for the chat, diff, preview, terminal, and file editor side by side
* Ask a [side question](#ask-a-side-question-without-derailing-the-session) that uses the session's context without derailing it
* [Connect external tools](#connect-external-tools) like GitHub, Slack, and Linear
* Let Claude [open apps and control your screen](#let-claude-use-your-computer)
* Run on your machine, in the [cloud](#run-long-running-tasks-remotely), or over [SSH](#ssh-sessions)
For [scheduled recurring work](../16-Mobile-Desktop/desktop-scheduled-tasks.md), [keyboard shortcuts](#keyboard-shortcuts), or [sending tasks from your phone](#sessions-from-dispatch), see the linked pages and sections. If you already use the terminal-based CLI, see the [CLI comparison](#coming-from-the-cli) for what carries over.
## Start a session
Before you send your first message, configure four things in the prompt area:
* **Environment**: choose where Claude runs. Select **Local** for your machine, **Remote** for Anthropic-hosted cloud sessions, or an [**SSH connection**](#ssh-sessions) for a remote machine you manage. See [environment configuration](#environment-configuration).
* **Project folder**: select the folder or repository Claude works in. For remote sessions, you can add [multiple repositories](#run-long-running-tasks-remotely).
* **Model**: pick a [model](/en/model-config#available-models) from the dropdown next to the send button. You can change this during the session.
* **Permission mode**: choose how much autonomy Claude has from the [mode selector](#choose-a-permission-mode). You can change this during the session.
Type your task and press **Enter** to start. Each session tracks its own context and changes independently.
## Work with code
Give Claude the right context, control how much it does on its own, and review what it changed.
### Use the prompt box
Type what you want Claude to do and press **Enter** to send. Claude reads your project files, makes changes, and runs commands based on your [permission mode](#choose-a-permission-mode). You can interrupt Claude at any point: click the stop button or type your correction and press **Enter**. Claude stops what it's doing and adjusts based on your input.
The **+** button next to the prompt box gives you access to file attachments, [skills](#use-skills), [connectors](#connect-external-tools), and [plugins](#install-plugins).
### Add files and context to prompts
The prompt box supports two ways to bring in external context:
* **@mention files**: type `@` followed by a filename to add a file to the conversation context. Claude can then read and reference that file. @mention is not available in remote sessions.
* **Attach files**: attach images, PDFs, and other files to your prompt using the attachment button, or drag and drop files directly into the prompt. This is useful for sharing screenshots of bugs, design mockups, or reference documents.
### Choose a permission mode
Permission modes control how much autonomy Claude has during a session: whether it asks before editing files, running commands, or both. You can switch modes at any time using the mode selector next to the send button. Start with Ask permissions to see exactly what Claude does, then move to Auto accept edits or Plan mode as you get comfortable.
| Mode | Settings key | Behavior |
| ---------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Ask permissions** | `default` | Claude asks before editing files or running commands. You see a diff and can accept or reject each change. Recommended for new users. |
| **Auto accept edits** | `acceptEdits` | Claude auto-accepts file edits and common filesystem commands like `mkdir`, `touch`, and `mv`, but still asks before running other terminal commands. Use this when you trust file changes and want faster iteration. |
| **Plan mode** | `plan` | Claude reads files and runs commands to explore, then proposes a plan without editing your source code. Good for complex tasks where you want to review the approach first. |
| **Auto** | `auto` | Claude executes all actions with background safety checks that verify alignment with your request. Reduces permission prompts while maintaining oversight. Enable in your Settings → Claude Code. See [availability requirements](#auto-mode-availability) below. |
| **Bypass permissions** | `bypassPermissions` | Claude runs without any permission prompts, equivalent to the admin-gated bypass option in the CLI. Enable in your Settings → Claude Code under "Allow bypass permissions mode". Only use this in sandboxed containers or VMs. Enterprise admins can disable this option. |
The `dontAsk` permission mode is available only in the [CLI](/en/permission-modes#allow-only-pre-approved-tools-with-dontask-mode).
Auto mode is a research preview available on Max, Team, Enterprise, and API plans. It is not available on Pro plans or third-party providers. On Team, Enterprise, and API plans it requires Claude Sonnet 4.6, Opus 4.6, or Opus 4.7. On Max plans it requires Claude Opus 4.7.
Start complex tasks in Plan mode so Claude maps out an approach before making changes. Once you approve the plan, switch to Auto accept edits or Ask permissions to execute it. See [explore first, then plan, then code](/en/best-practices#explore-first-then-plan-then-code) for more on this workflow.
Remote sessions support Auto accept edits and Plan mode. Ask permissions is not available because remote sessions auto-accept file edits by default, and Bypass permissions is not available because the remote environment is already sandboxed.
Enterprise admins can restrict which permission modes are available. See [enterprise configuration](#enterprise-configuration) for details.
### Preview your app
Claude can start a dev server and open an embedded browser to verify its changes. This works for frontend web apps as well as backend servers: Claude can test API endpoints, view server logs, and iterate on issues it finds. In most cases, Claude starts the server automatically after editing project files. You can also ask Claude to preview at any time. By default, Claude [auto-verifies](#auto-verify-changes) changes after every edit.
The preview pane can also open static HTML files, PDFs, images, and videos from your project. Click an HTML, PDF, image, or video path in the chat to open it in preview.
From the preview pane, you can:
* Interact with your running app directly in the embedded browser
* Watch Claude verify its own changes automatically: it takes screenshots, inspects the DOM, clicks elements, fills forms, and fixes issues it finds
* Start or stop servers from the **Preview** dropdown in the session toolbar
* Persist cookies and local storage across server restarts by selecting **Persist sessions** in the dropdown, so you don't have to re-login during development
* Edit the server configuration or stop all servers at once
Claude creates the initial server configuration based on your project. If your app uses a custom dev command, edit `.claude/launch.json` to match your setup. See [Configure preview servers](#configure-preview-servers) for the full reference.
To clear saved session data, toggle **Persist preview sessions** off in Settings → Claude Code. To disable preview entirely, toggle off **Preview** in Settings → Claude Code.
### Review changes with diff view
After Claude makes changes to your code, the diff view lets you review modifications file by file before creating a pull request.
When Claude changes files, a diff stats indicator appears showing the number of lines added and removed, such as `+12 -1`. Click this indicator to open the diff viewer, which displays a file list on the left and the changes for each file on the right.
To comment on specific lines, click any line in the diff to open a comment box. Type your feedback and press **Enter** to add the comment. After adding comments to multiple lines, submit all comments at once:
* **macOS**: press **Cmd+Enter**
* **Windows**: press **Ctrl+Enter**
Claude reads your comments and makes the requested changes, which appear as a new diff you can review.
### Review your code
In the diff view, click **Review code** in the top-right toolbar to ask Claude to evaluate the changes before you commit. Claude examines the current diffs and leaves comments directly in the diff view. You can respond to any comment or ask Claude to revise.
The review focuses on high-signal issues: compile errors, definite logic errors, security vulnerabilities, and obvious bugs. It does not flag style, formatting, pre-existing issues, or anything a linter would catch.
### Monitor pull request status
After you open a pull request, a CI status bar appears in the session. Claude Code uses the GitHub CLI to poll check results and surface failures.
* **Auto-fix**: when enabled, Claude automatically attempts to fix failing CI checks by reading the failure output and iterating.
* **Auto-merge**: when enabled, Claude merges the PR once all checks pass. The merge method is squash. Auto-merge must be [enabled in your GitHub repository settings](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository) for this to work.
Use the **Auto-fix** and **Auto-merge** toggles in the CI status bar to enable either option. Claude Code also sends a desktop notification when CI finishes. To archive the session automatically once the PR merges or closes, turn on [auto-archive](#work-in-parallel-with-sessions) in Settings → Claude Code.
PR monitoring requires the [GitHub CLI (`gh`)](https://cli.github.com/) to be installed and authenticated on your machine. If `gh` is not installed, Desktop prompts you to install it the first time you try to create a PR.
## Arrange your workspace
The Code tab is built around panes you can arrange in any layout: chat, diff, preview, terminal, file, plan, tasks, and subagent. Drag a pane by its header to reposition it, or drag a pane edge to resize it. Press **Cmd+\\** on macOS or **Ctrl+\\** on Windows to close the focused pane. Open additional panes from the **Views** menu in the session toolbar.
The pane layout, terminal, file editor, and view modes in this section require Claude Desktop v1.2581.0 or later. Open **Claude → Check for Updates** on macOS or **Help → Check for Updates** on Windows to update.
### Run commands in the terminal
The integrated terminal lets you run commands alongside your session without switching to another app. Open it from the **Views** menu or press **Ctrl+\`** on macOS or Windows. The terminal opens in your session's working directory and shares the same environment as Claude, so commands like `npm test` or `git status` see the same files Claude is editing. The terminal is available in local sessions only.
### Open and edit files
Click a file path in the chat or diff viewer to open it in the file pane. HTML, PDF, image, and video paths open in the [preview pane](#preview-your-app) instead. Make spot edits and click **Save** to write them back. If the file changed on disk since you opened it, the pane warns you and lets you override or discard. Click **Discard** to revert your edits, or click the path in the pane header to copy the absolute path.
The file pane is available in local and SSH sessions. For remote sessions, ask Claude to make the change.
### Open files in other apps
Right-click any file path in the chat, diff viewer, or file pane to open a context menu:
* **Attach as context**: add the file to your next prompt
* **Open in**: open the file in an installed editor such as VS Code, Cursor, or Zed
* **Show in Finder** on macOS, **Show in Explorer** on Windows: open the containing folder
* **Copy path**: copy the absolute path to your clipboard
### Switch view modes
View modes control how much detail appears in the chat transcript. Switch modes from the **Transcript view** dropdown next to the send button, or press **Ctrl+O** on macOS or Windows to cycle through them.
| Mode | What it shows |
| ----------- | -------------------------------------------------------------- |
| **Normal** | Tool calls collapsed into summaries, with full text responses |
| **Verbose** | Every tool call, file read, and intermediate step Claude takes |
| **Summary** | Only Claude's final responses and the changes it made |
Use Verbose when debugging why Claude took a particular action. Use Summary when you're running multiple sessions and want to scan results quickly.
### Keyboard shortcuts
Press **Cmd+/** on macOS or **Ctrl+/** on Windows to see all shortcuts available in the Code tab. On Windows, use **Ctrl** in place of **Cmd** for the shortcuts below. Session cycling, the terminal toggle, and the view-mode toggle use **Ctrl** on every platform.
| Shortcut | Action |
| ------------------------------------- | ---------------------------- |
| `Cmd` `/` | Show keyboard shortcuts |
| `Cmd` `N` | New session |
| `Cmd` `W` | Close session |
| `Ctrl` `Tab` / `Ctrl` `Shift` `Tab` | Next or previous session |
| `Cmd` `Shift` `]` / `Cmd` `Shift` `[` | Next or previous session |
| `Esc` | Stop Claude's response |
| `Cmd` `Shift` `D` | Toggle diff pane |
| `Cmd` `Shift` `P` | Toggle preview pane |
| `Cmd` `Shift` `S` | Select an element in preview |
| `Ctrl` `` ` `` | Toggle terminal pane |
| `Cmd` `\` | Close focused pane |
| `Cmd` `;` | Open side chat |
| `Ctrl` `O` | Cycle view modes |
| `Cmd` `Shift` `M` | Open permission mode menu |
| `Cmd` `Shift` `I` | Open model menu |
| `Cmd` `Shift` `E` | Open effort menu |
| `1`–`9` | Select item in an open menu |
These shortcuts apply only to the Code tab. The terminal-based [interactive mode shortcuts](/en/interactive-mode#keyboard-shortcuts), such as `Shift+Tab` to cycle modes, do not apply in Desktop.
### Check usage
Click the usage ring next to the model picker to see your current context window usage and your plan usage for the period. Context usage is per session; plan usage is shared across all your Claude Code surfaces.
## Let Claude use your computer
Computer use lets Claude open your apps, control your screen, and work directly on your machine the way you would. Ask Claude to test a native app in a mobile simulator, interact with a desktop tool that has no CLI, or automate something that only works through a GUI.
Computer use is a research preview on macOS and Windows that requires a Pro or Max plan. It is not available on Team or Enterprise plans. The Claude Desktop app must be running.
Computer use is off by default. [Enable it in Settings](#enable-computer-use) before Claude can control your screen. On macOS, you also need to grant Accessibility and Screen Recording permissions.
Unlike the [sandboxed Bash tool](../22-Safety-Policy/sandboxing-claude-code-docs-5f97cd27c4.md), computer use runs on your actual desktop with access to whatever you approve. Claude checks each action and flags potential prompt injection from on-screen content, but the trust boundary is different. See the [computer use safety guide](https://support.claude.com/en/articles/14128542) for best practices.
### When computer use applies
Claude has several ways to interact with an app or service, and computer use is the broadest and slowest. It tries the most precise tool first:
* If you have a [connector](#connect-external-tools) for a service, Claude uses the connector.
* If the task is a shell command, Claude uses Bash.
* If the task is browser work and you have [Claude in Chrome](../03-IDE-Integrations/use-claude-code-with-chrome-beta-claude-code-docs-4f2f5a5a96.md) set up, Claude uses that.
* If none of those apply, Claude uses computer use.
The [per-app access tiers](#app-permissions) reinforce this: browsers are capped at view-only, and terminals and IDEs at click-only, steering Claude toward the dedicated tool even when computer use is active. Screen control is reserved for things nothing else can reach, like native apps, hardware control panels, mobile simulators, or proprietary tools without an API.
### Enable computer use
Computer use is off by default. If you ask Claude to do something that needs it while it's off, Claude tells you it could do the task if you enable computer use in Settings.
Make sure you have the latest version of Claude Desktop. Download or update at [claude.com/download](https://claude.com/download), then restart the app.
In the desktop app, go to **Settings > General** (under **Desktop app**). Find the **Computer use** toggle and turn it on. On Windows, the toggle takes effect immediately and setup is complete. On macOS, continue to the next step.
If you don't see the toggle, confirm you're on macOS or Windows with a Pro or Max plan, then update and restart the app.
On macOS, grant two system permissions before the toggle takes effect:
* **Accessibility**: lets Claude click, type, and scroll
* **Screen Recording**: lets Claude see what's on your screen
The Settings page shows the current status of each permission. If either is denied, click the badge to open the relevant System Settings pane.
### App permissions
The first time Claude needs to use an app, a prompt appears in your session. Click **Allow for this session** or **Deny**. Approvals last for the current session, or 30 minutes in [Dispatch-spawned sessions](#sessions-from-dispatch).
The prompt also shows what level of control Claude gets for that app. These tiers are fixed by app category and can't be changed:
| Tier | What Claude can do | Applies to |
| :----------- | :------------------------------------------------------- | :-------------------------- |
| View only | See the app in screenshots | Browsers, trading platforms |
| Click only | Click and scroll, but not type or use keyboard shortcuts | Terminals, IDEs |
| Full control | Click, type, drag, and use keyboard shortcuts | Everything else |
Apps with broad reach, like terminals, Finder or File Explorer, and System Settings or Settings, show an extra warning in the prompt so you know what approving them grants.
You can configure two settings in **Settings > General** (under **Desktop app**):
* **Denied apps**: add apps here to reject them without prompting. Claude may still affect a denied app indirectly through actions in an allowed app, but it can't interact with the denied app directly.
* **Unhide apps when Claude finishes**: while Claude is working, your other windows are hidden so it interacts with only the approved app. When Claude finishes, hidden windows are restored unless you turn this setting off.
## Manage sessions
Each session is an independent conversation with its own context and changes. You can run multiple sessions in parallel, branch off side chats, send work to the cloud, or let Dispatch start sessions for you from your phone.
### Work in parallel with sessions
Click **+ New session** in the sidebar, or press **Cmd+N** on macOS or **Ctrl+N** on Windows, to work on multiple tasks in parallel. Press **Ctrl+Tab** and **Ctrl+Shift+Tab** to cycle through sessions in the sidebar. For Git repositories, each session gets its own isolated copy of your project using [Git worktrees](/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees), so changes in one session don't affect other sessions until you commit them.
Worktrees are stored in `/.claude/worktrees/` by default. You can change this to a custom directory in Settings → Claude Code under "Worktree location". You can also set a branch prefix that gets prepended to every worktree branch name, which is useful for keeping Claude-created branches organized. To remove a worktree when you're done, hover over the session in the sidebar and click the archive icon. To have sessions archive themselves when their pull request merges or closes, turn on **Auto-archive after PR merge or close** in Settings → Claude Code. Auto-archive only applies to local sessions that have finished running.
To include gitignored files like `.env` in new worktrees, create a [`.worktreeinclude` file](/en/common-workflows#copy-gitignored-files-to-worktrees) in your project root.
Session isolation requires [Git](https://git-scm.com/downloads). Most Macs include Git by default. Run `git --version` in Terminal to check. On Windows, Git is required for the Code tab to work: [download Git for Windows](https://git-scm.com/downloads/win), install it, and restart the app. If you run into Git errors, ask Claude in the [Cowork tab](https://claude.com/product/cowork) to help troubleshoot your setup.
Use the controls at the top of the sidebar to filter sessions by status, project, or environment, and to group sessions by project. To rename a session, click the session title in the toolbar at the top of the active session. To check context usage, see [Check usage](#check-usage). When context fills up, Claude automatically summarizes the conversation and continues working. You can also type `/compact` to trigger summarization earlier and free up context space. See [the context window](/en/how-claude-code-works#the-context-window) for details on how compaction works.
### Ask a side question without derailing the session
A side chat lets you ask Claude a question that uses your session's context but doesn't add anything back to the main conversation. Use it when you want to understand a piece of code, check an assumption, or explore an idea without steering the session off course.
Press **Cmd+;** on macOS or **Ctrl+;** on Windows to open a side chat, or type `/btw` in the prompt box. The side chat can read everything in the main thread up to that point. When you're done, close the side chat and continue the main session where you left off. Side chats are available in local and SSH sessions.
### Watch background tasks
The tasks pane shows the background work running inside the current session: subagents, background shell commands, and workflows. Open it from the **Views** menu or drag it into your layout.
Click any entry to see its output in the subagent pane or stop it. To see what other sessions are doing, use the [sidebar](#work-in-parallel-with-sessions).
### Run long-running tasks remotely
For large refactors, test suites, migrations, or other long-running tasks, select **Remote** instead of **Local** when starting a session. Remote sessions run on Anthropic's cloud infrastructure and continue even if you close the app or shut down your computer. Check back anytime to see progress or steer Claude in a different direction. You can also monitor remote sessions from [claude.ai/code](https://claude.ai/code) or the Claude iOS app.
Remote sessions also support multiple repositories. After selecting a cloud environment, click the **+** button next to the repo pill to add additional repositories to the session. Each repo gets its own branch selector. This is useful for tasks that span multiple codebases, such as updating a shared library and its consumers.
See [Claude Code on the web](claude-code-on-the-web-69d53821d4.md) for more on how remote sessions work.
### Continue in another surface
The **Continue in** menu, accessible from the VS Code icon in the bottom right of the session toolbar, lets you move your session to another surface:
* **Claude Code on the Web**: sends your local session to continue running remotely. Desktop pushes your branch, generates a summary of the conversation, and creates a new remote session with the full context. You can then choose to archive the local session or keep it. This requires a clean working tree, and is not available for SSH sessions.
* **Your IDE**: opens your project in a supported IDE at the current working directory.
### Sessions from Dispatch
[Dispatch](https://support.claude.com/en/articles/13947068) is a persistent conversation with Claude that lives in the [Cowork](https://claude.com/product/cowork#dispatch-and-computer-use) tab. You message Dispatch a task, and it decides how to handle it.
A task can end up as a Code session in two ways: you ask for one directly, such as "open a Claude Code session and fix the login bug", or Dispatch decides the task is development work and spawns one on its own. Tasks that typically route to Code include fixing bugs, updating dependencies, running tests, or opening pull requests. Research, document editing, and spreadsheet work stay in Cowork.
Either way, the Code session appears in the Code tab's sidebar with a **Dispatch** badge. You get a push notification on your phone when it finishes or needs your approval.
If you have [computer use](#let-claude-use-your-computer) enabled, Dispatch-spawned Code sessions can use it too. App approvals in those sessions expire after 30 minutes and re-prompt, rather than lasting the full session like regular Code sessions.
For setup, pairing, and Dispatch settings, see the [Dispatch help article](https://support.claude.com/en/articles/13947068). Dispatch requires a Pro or Max plan and is not available on Team or Enterprise plans.
Dispatch is one of several ways to work with Claude when you're away from your terminal. See [Platforms and integrations](/en/platforms#work-when-you-are-away-from-your-terminal) to compare it with Remote Control, Channels, Slack, and scheduled tasks.
## Extend Claude Code
Connect external services, add reusable workflows, customize Claude's behavior, and configure preview servers. To manage connectors, skills, and plugins in one place, click **Customize** in the sidebar.
### Connect external tools
For local and [SSH](#ssh-sessions) sessions, click the **+** button next to the prompt box and select **Connectors** to add integrations like Google Calendar, Slack, GitHub, Linear, Notion, and more. You can add connectors before or during a session. The **+** button is not available in remote sessions, but [routines](routines-3111c7bd3a.md) configure connectors at routine creation time.
To manage or disconnect connectors, go to Settings → Connectors in the desktop app, or select **Manage connectors** from the Connectors menu in the prompt box.
Once connected, Claude can read your calendar, send messages, create issues, and interact with your tools directly. You can ask Claude what connectors are configured in your session.
Connectors are [MCP servers](../06-MCP-Tools/mcp-208e742686.md) with a graphical setup flow. Use them for quick integration with supported services. For integrations not listed in Connectors, add MCP servers manually via [settings files](/en/mcp#installing-mcp-servers). You can also [create custom connectors](../14-Connectors/getting-started-with-custom-connectors-using-remote-mcp.md).
### Use skills
[Skills](../08-Plugins-Skills/extend-claude-with-skills-claude-code-docs.md) extend what Claude can do. Claude loads them automatically when relevant, or you can invoke one directly: type `/` in the prompt box or click the **+** button and select **Slash commands** to browse what's available. This includes [built-in commands](built-in-commands-claude-code-docs.md), your [custom skills](/en/skills#create-your-first-skill), project skills from your codebase, and skills from any [installed plugins](../08-Plugins-Skills/create-plugins-claude-code-docs.md). Select one and it appears highlighted in the input field. Type your task after it and send as usual.
### Install plugins
[Plugins](../08-Plugins-Skills/create-plugins-claude-code-docs.md) are reusable packages that add skills, agents, hooks, MCP servers, and LSP configurations to Claude Code. You can install plugins from the desktop app without using the terminal.
For local and [SSH](#ssh-sessions) sessions, click the **+** button next to the prompt box and select **Plugins** to see your installed plugins and their skills. To add a plugin, select **Add plugin** from the submenu to open the plugin browser, which shows available plugins from your configured [marketplaces](../08-Plugins-Skills/create-and-distribute-a-plugin-marketplace-claude-code-docs-34a8f3c5e8.md) including the official Anthropic marketplace. Select **Manage plugins** to enable, disable, or uninstall plugins.
Plugins can be scoped to your user account, a specific project, or local-only. If your organization manages plugins centrally, those plugins are available in desktop sessions the same way they are in the CLI. Plugins are not available for remote sessions. For the full plugin reference including creating your own plugins, see [plugins](../08-Plugins-Skills/create-plugins-claude-code-docs.md).
### Configure preview servers
Claude automatically detects your dev server setup and stores the configuration in `.claude/launch.json` at the root of the folder you selected when starting the session. Preview uses this folder as its working directory, so if you selected a parent folder, subfolders with their own dev servers won't be detected automatically. To work with a subfolder's server, either start a session in that folder directly or add a configuration manually.
To customize how your server starts, for example to use `yarn dev` instead of `npm run dev` or to change the port, edit the file manually or click **Edit configuration** in the Preview dropdown to open it in your code editor. The file supports JSON with comments.
```json theme={null}
{
"version": "0.0.1",
"configurations": [
{
"name": "my-app",
"runtimeExecutable": "npm",
"runtimeArgs": ["run", "dev"],
"port": 3000
}
]
}
```
You can define multiple configurations to run different servers from the same project, such as a frontend and an API. See the [examples](#examples) below.
#### Auto-verify changes
When `autoVerify` is enabled, Claude automatically verifies code changes after editing files. It takes screenshots, checks for errors, and confirms changes work before completing its response.
Auto-verify is on by default. Disable it per-project by adding `"autoVerify": false` to `.claude/launch.json`, or toggle it from the **Preview** dropdown menu.
```json theme={null}
{
"version": "0.0.1",
"autoVerify": false,
"configurations": [...]
}
```
When disabled, preview tools are still available and you can ask Claude to verify at any time. Auto-verify makes it automatic after every edit.
#### Configuration fields
Each entry in the `configurations` array accepts the following fields:
| Field | Type | Description |
| ------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name` | string | A unique identifier for this server |
| `runtimeExecutable` | string | The command to run, such as `npm`, `yarn`, or `node` |
| `runtimeArgs` | string\[] | Arguments passed to `runtimeExecutable`, such as `["run", "dev"]` |
| `port` | number | The port your server listens on. Defaults to 3000 |
| `cwd` | string | Working directory relative to your project root. Defaults to the project root. Use `${workspaceFolder}` to reference the project root explicitly |
| `env` | object | Additional environment variables as key-value pairs, such as `{ "NODE_ENV": "development" }`. Don't put secrets here since this file is committed to your repo. To pass secrets to your dev server, set them in the [local environment editor](#local-sessions) instead. |
| `autoPort` | boolean | How to handle port conflicts. See below |
| `program` | string | A script to run with `node`. See [when to use `program` vs `runtimeExecutable`](#when-to-use-program-vs-runtimeexecutable) |
| `args` | string\[] | Arguments passed to `program`. Only used when `program` is set |
##### When to use `program` vs `runtimeExecutable`
Use `runtimeExecutable` with `runtimeArgs` to start a dev server through a package manager. For example, `"runtimeExecutable": "npm"` with `"runtimeArgs": ["run", "dev"]` runs `npm run dev`.
Use `program` when you have a standalone script you want to run with `node` directly. For example, `"program": "server.js"` runs `node server.js`. Pass additional flags with `args`.
#### Port conflicts
The `autoPort` field controls what happens when your preferred port is already in use:
* **`true`**: Claude finds and uses a free port automatically. Suitable for most dev servers.
* **`false`**: Claude fails with an error. Use this when your server must use a specific port, such as for OAuth callbacks or CORS allowlists.
* **Not set (default)**: Claude asks whether the server needs that exact port, then saves your answer.
When Claude picks a different port, it passes the assigned port to your server via the `PORT` environment variable.
#### Examples
These configurations show common setups for different project types:
This configuration runs a Next.js app using Yarn on port 3000:
```json theme={null}
{
"version": "0.0.1",
"configurations": [
{
"name": "web",
"runtimeExecutable": "yarn",
"runtimeArgs": ["dev"],
"port": 3000
}
]
}
```
For a monorepo with a frontend and an API server, define multiple configurations. The frontend uses `autoPort: true` so it picks a free port if 3000 is taken, while the API server requires port 8080 exactly:
```json theme={null}
{
"version": "0.0.1",
"configurations": [
{
"name": "frontend",
"runtimeExecutable": "npm",
"runtimeArgs": ["run", "dev"],
"cwd": "apps/web",
"port": 3000,
"autoPort": true
},
{
"name": "api",
"runtimeExecutable": "npm",
"runtimeArgs": ["run", "start"],
"cwd": "server",
"port": 8080,
"env": { "NODE_ENV": "development" },
"autoPort": false
}
]
}
```
To run a Node.js script directly instead of using a package manager command, use the `program` field:
```json theme={null}
{
"version": "0.0.1",
"configurations": [
{
"name": "server",
"program": "server.js",
"args": ["--verbose"],
"port": 4000
}
]
}
```
## Environment configuration
The environment you pick when [starting a session](#start-a-session) determines where Claude executes and how you connect:
* **Local**: runs on your machine with direct access to your files
* **Remote**: runs on Anthropic's cloud infrastructure. Sessions continue even if you close the app.
* **SSH**: runs on a remote machine you connect to over SSH, such as your own servers, cloud VMs, or dev containers
### Local sessions
The desktop app does not always inherit your full shell environment. On macOS, when you launch the app from the Dock or Finder, it reads your shell profile, such as `~/.zshrc` or `~/.bashrc`, to extract `PATH` and a fixed set of Claude Code variables, but other variables you export there are not picked up. On Windows, the app inherits user and system environment variables but does not read PowerShell profiles.
To set environment variables for local sessions and dev servers on any platform, open the environment dropdown in the prompt box, hover over **Local**, and click the gear icon to open the local environment editor. Variables you save here are stored encrypted on your machine and apply to every local session and preview server you start. You can also add variables to the `env` key in your `~/.claude/settings.json` file, though these reach Claude sessions only and not dev servers. See [environment variables](env-vars-5c624d392b.md) for the full list of supported variables.
[Extended thinking](/en/common-workflows#use-extended-thinking-thinking-mode) is enabled by default, which improves performance on complex reasoning tasks but uses additional tokens. To disable thinking entirely, set `MAX_THINKING_TOKENS` to `0` in the local environment editor. On models with [adaptive reasoning](/en/model-config#adjust-effort-level), any other `MAX_THINKING_TOKENS` value is ignored because adaptive reasoning controls thinking depth instead. On Opus 4.6 and Sonnet 4.6, set `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` to `1` to use a fixed thinking budget; Opus 4.7 always uses adaptive reasoning and has no fixed-budget mode.
### Remote sessions
Remote sessions continue in the background even if you close the app. Usage counts toward your [subscription plan limits](../17-Billing-Plans/manage-costs-effectively-claude-code-docs-7c26178a4f.md) with no separate compute charges.
You can create custom cloud environments with different network access levels and environment variables. Select the environment dropdown when starting a remote session and choose **Add environment**. See [the cloud environment](/en/claude-code-on-the-web#the-cloud-environment) for details on configuring network access and environment variables.
### SSH sessions
SSH sessions let you run Claude Code on a remote machine while using the desktop app as your interface. This is useful for working with codebases that live on cloud VMs, dev containers, or servers with specific hardware or dependencies.
To add an SSH connection, click the environment dropdown before starting a session and select **+ Add SSH connection**. The dialog asks for:
* **Name**: a friendly label for this connection
* **SSH Host**: `user@hostname` or a host defined in `~/.ssh/config`
* **SSH Port**: defaults to 22 if left empty, or uses the port from your SSH config
* **Identity File**: path to your private key, such as `~/.ssh/id_rsa`. Leave empty to use the default key or your SSH config.
Once added, the connection appears in the environment dropdown. Select it to start a session on that machine. Claude runs on the remote machine with access to its files and tools.
The remote machine must run Linux or macOS. Desktop installs Claude Code on the remote machine automatically the first time you connect. Once connected, SSH sessions support permission modes, connectors, plugins, and MCP servers.
#### Pre-configure SSH connections for your team
Administrators can distribute SSH connections to team members by adding `sshConfigs` to a [managed settings](/en/settings#settings-precedence) file. Connections defined this way appear in each user's environment dropdown automatically and are shown as managed, so users can select them but cannot edit or delete them in the app.
The following example pre-configures a single connection that opens in `~/projects` on the remote host:
```json theme={null}
{
"sshConfigs": [
{
"id": "shared-dev-vm",
"name": "Shared Dev VM",
"sshHost": "user@dev.example.com",
"sshPort": 22,
"sshIdentityFile": "~/.ssh/id_ed25519",
"startDirectory": "~/projects"
}
]
}
```
Each entry requires `id`, `name`, and `sshHost`. The `sshPort`, `sshIdentityFile`, and `startDirectory` fields are optional. Users can also add `sshConfigs` to their own `~/.claude/settings.json`, which is where connections added through the dialog are stored.
## Enterprise configuration
Organizations on Team or Enterprise plans can manage desktop app behavior through admin console controls, managed settings files, and device management policies.
### Admin console controls
These settings are configured through the [admin settings console](https://claude.ai/admin-settings/claude-code):
* **Code in the desktop**: control whether users in your organization can access Claude Code in the desktop app
* **Code in the web**: enable or disable [web sessions](claude-code-on-the-web-69d53821d4.md) for your organization
* **Remote Control**: enable or disable [Remote Control](continue-local-sessions-from-any-device-with-remote-control-claude-code-docs-c1c03fd914.md) for your organization
* **Disable Bypass permissions mode**: prevent users in your organization from enabling bypass permissions mode
### Managed settings
Managed settings override project and user settings and apply when Desktop spawns CLI sessions. You can set these keys in your organization's [managed settings](/en/settings#settings-precedence) file or push them remotely through the admin console.
| Key | Description |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `permissions.disableBypassPermissionsMode` | set to `"disable"` to prevent users from enabling Bypass permissions mode. |
| `disableAutoMode` | set to `"disable"` to prevent users from enabling [Auto](/en/permission-modes#eliminate-prompts-with-auto-mode) mode. Removes Auto from the mode selector. Also accepted under `permissions`. |
| `autoMode` | customize what the auto mode classifier trusts and blocks across your organization. See [Configure auto mode](auto-mode-config-f0dacf5866.md). |
| `sshConfigs` | pre-configure [SSH connections](#pre-configure-ssh-connections-for-your-team) that appear in the environment dropdown. Users cannot edit or delete managed connections. |
A managed settings file deployed to disk on each machine applies to Desktop sessions. Managed settings pushed remotely through the admin console currently reach CLI and IDE sessions only, so for Desktop deployments either distribute the file via MDM or use the [admin console controls](#admin-console-controls) above.
`permissions.disableBypassPermissionsMode` and `disableAutoMode` also work in user and project settings, but placing them in managed settings prevents users from overriding them. `autoMode` is read from user settings, `.claude/settings.local.json`, and managed settings, but not from the checked-in `.claude/settings.json`: a cloned repo cannot inject its own classifier rules. For the complete list of managed-only settings including `allowManagedPermissionRulesOnly` and `allowManagedHooksOnly`, see [managed-only settings](/en/permissions#managed-only-settings).
### Device management policies
IT teams can manage the desktop app through MDM on macOS or group policy on Windows. Available policies include enabling or disabling the Claude Code feature, controlling auto-updates, and setting a custom deployment URL.
* **macOS**: configure via `com.anthropic.Claude` preference domain using tools like Jamf or Kandji
* **Windows**: configure via registry at `SOFTWARE\Policies\Claude`
### Authentication and SSO
Enterprise organizations can require SSO for all users. See [authentication](../13-Enterprise-Admin/authentication-claude-code-docs-2c6ada8385.md) for plan-level details and [Setting up SSO](../21-Account-Support/setting-up-single-sign-on-sso.md) for SAML and OIDC configuration.
### Data handling
Claude Code processes your code locally in local sessions or on Anthropic's cloud infrastructure in remote sessions. Conversations and code context are sent to Anthropic's API for processing. See [data handling](../22-Safety-Policy/data-usage-claude-code-docs-06b2864aaa.md) for details on data retention, privacy, and compliance.
### Deployment
Desktop can be distributed through enterprise deployment tools:
* **macOS**: distribute via MDM such as Jamf or Kandji using the `.dmg` installer
* **Windows**: deploy via MSIX package or `.exe` installer. See [Deploy Claude Desktop for Windows](https://support.claude.com/en/articles/12622703-deploy-claude-desktop-for-windows) for enterprise deployment options including silent installation
For network configuration such as proxy settings, firewall allowlisting, and LLM gateways, see [network configuration](enterprise-network-configuration-claude-code-docs.md).
For the full enterprise configuration reference, see the [enterprise configuration guide](../13-Enterprise-Admin/enterprise-configuration.md).
## Coming from the CLI?
If you already use the Claude Code CLI, Desktop runs the same underlying engine with a graphical interface. You can run both simultaneously on the same machine, even on the same project. Each maintains separate session history, but they share configuration and project memory via CLAUDE.md files.
To move a CLI session into Desktop, run `/desktop` in the terminal. Claude saves your session and opens it in the desktop app, then exits the CLI. This command is available on macOS and Windows only.
When to use Desktop vs CLI: use Desktop when you want to manage parallel sessions in one window, arrange panes side by side, or review changes visually. Use the CLI when you need scripting, automation, or prefer a terminal workflow.
### CLI flag equivalents
This table shows the desktop app equivalent for common CLI flags. Flags not listed have no desktop equivalent because they are designed for scripting or automation.
| CLI | Desktop equivalent |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `--model sonnet` | Model dropdown next to the send button |
| `--resume`, `--continue` | Click a session in the sidebar |
| `--permission-mode` | Mode selector next to the send button |
| `--dangerously-skip-permissions` | Bypass permissions mode. Enable in Settings → Claude Code → "Allow bypass permissions mode". Enterprise admins can disable this setting. |
| `--add-dir` | Add multiple repos with the **+** button in remote sessions |
| `--allowedTools`, `--disallowedTools` | No per-session equivalent. Permission rules in [settings files](claude-code-settings-claude-code-docs-d4420b4b52.md) still apply. |
| `--verbose` | [Verbose view mode](#switch-view-modes) in the Transcript view dropdown |
| `--print`, `--output-format` | Not available. Desktop is interactive only. |
| `ANTHROPIC_MODEL` env var | Model dropdown next to the send button |
| `MAX_THINKING_TOKENS` env var | Set in the local environment editor. See [environment configuration](#environment-configuration). |
### Shared configuration
Desktop and CLI read the same configuration files, so your setup carries over:
* **[CLAUDE.md](how-claude-remembers-your-project-claude-code-docs-f1c064262d.md)** and `CLAUDE.local.md` files in your project are used by both
* **[MCP servers](../06-MCP-Tools/mcp-208e742686.md)** configured in `~/.claude.json` or `.mcp.json` work in both
* **[Hooks](../07-Hooks/hooks-9168ed62a4.md)** and **[skills](../08-Plugins-Skills/extend-claude-with-skills-claude-code-docs.md)** defined in settings apply to both
* **[Settings](claude-code-settings-claude-code-docs-d4420b4b52.md)** in `~/.claude.json` and `~/.claude/settings.json` are shared. Permission rules, allowed tools, and other settings in `settings.json` apply to Desktop sessions.
* **Models**: Sonnet, Opus, and Haiku are available in both. In Desktop, select the model from the dropdown next to the send button. You can change the model mid-session from the same dropdown.
**MCP servers: desktop chat app vs Claude Code**: MCP servers configured for the Claude Desktop chat app in `claude_desktop_config.json` are separate from Claude Code and will not appear in the Code tab. To use MCP servers in Claude Code, configure them in `~/.claude.json` or your project's `.mcp.json` file. See [MCP configuration](/en/mcp#installing-mcp-servers) for details.
### Feature comparison
This table compares core capabilities between the CLI and Desktop. For a full list of CLI flags, see the [CLI reference](cli-reference-7bb98e3312.md).
| Feature | CLI | Desktop |
| ----------------------------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Permission modes | All modes including `dontAsk` | Ask permissions, Auto accept edits, Plan mode, Auto, and Bypass permissions via Settings |
| `--dangerously-skip-permissions` | CLI flag | Bypass permissions mode. Enable in Settings → Claude Code → "Allow bypass permissions mode" |
| [Third-party providers](enterprise-deployment-overview-claude-code-docs-6eae0ecba2.md) | Bedrock, Vertex, Foundry | Anthropic's API by default. Enterprise deployments can configure Vertex AI and gateway providers. See the [enterprise configuration guide](../13-Enterprise-Admin/enterprise-configuration.md). |
| [MCP servers](../06-MCP-Tools/mcp-208e742686.md) | Configure in settings files | Connectors UI for local and SSH sessions, or settings files |
| [Plugins](../08-Plugins-Skills/create-plugins-claude-code-docs.md) | `/plugin` command | Plugin manager UI |
| @mention files | Text-based | With autocomplete; local and SSH sessions only |
| File attachments | Not available | Images, PDFs |
| Session isolation | [`--worktree`](cli-reference-7bb98e3312.md) flag | Automatic worktrees |
| Multiple sessions | Separate terminals | Sidebar tabs |
| Recurring tasks | Cron jobs, CI pipelines | [Scheduled tasks](../16-Mobile-Desktop/desktop-scheduled-tasks.md) |
| Computer use | [Enable via `/mcp`](computer-use-427032da98.md) on macOS | [App and screen control](#let-claude-use-your-computer) on macOS and Windows |
| Dispatch integration | Not available | [Dispatch sessions](#sessions-from-dispatch) in the sidebar |
| Scripting and automation | [`--print`](cli-reference-7bb98e3312.md), [Agent SDK](headless-b99e3140ec.md) | Not available |
### What's not available in Desktop
The following features are only available in the CLI or VS Code extension:
* **Third-party providers**: Desktop connects to Anthropic's API by default. Enterprise deployments can configure Vertex AI and gateway providers via [managed settings](../13-Enterprise-Admin/enterprise-configuration.md). For Bedrock or Foundry, use the [CLI](../01-Getting-Started/quickstart-claude-code-docs-a21b84bdea.md).
* **Linux**: the desktop app is available on macOS and Windows only.
* **Inline code suggestions**: Desktop does not provide autocomplete-style suggestions. It works through conversational prompts and explicit code changes.
* **Agent teams**: multi-agent orchestration is available via the [CLI](../09-Agents-Patterns/agent-teams-e29da6ed1b.md) and [Agent SDK](headless-b99e3140ec.md), not in Desktop.
## Troubleshooting
The sections below cover issues specific to the desktop app. For runtime API errors that appear in the chat such as `API Error: 500`, `529 Overloaded`, `429`, or `Prompt is too long`, see the [Error reference](errors-8648349cb4.md). Those errors and their fixes are the same across the CLI, desktop, and web.
### Check your version
To see which version of the desktop app you're running:
* **macOS**: click **Claude** in the menu bar, then **About Claude**
* **Windows**: click **Help**, then **About**
Click the version number to copy it to your clipboard.
### 403 or authentication errors in the Code tab
If you see `Error 403: Forbidden` or other authentication failures when using the Code tab:
1. Sign out and back in from the app menu. This is the most common fix.
2. Verify you have an active paid subscription: Pro, Max, Team, or Enterprise.
3. If the CLI works but Desktop does not, quit the desktop app completely, not just close the window, then reopen and sign in again.
4. Check your internet connection and proxy settings.
### Blank or stuck screen on launch
If the app opens but shows a blank or unresponsive screen:
1. Restart the app.
2. Check for pending updates. The app auto-updates on launch.
3. On Windows, check Event Viewer for crash logs under **Windows Logs → Application**.
### "Failed to load session"
If you see `Failed to load session`, the selected folder may no longer exist, a Git repository may require Git LFS that isn't installed, or file permissions may prevent access. Try selecting a different folder or restarting the app.
### Session not finding installed tools
If Claude can't find tools like `npm`, `node`, or other CLI commands, verify the tools work in your regular terminal, check that your shell profile properly sets up PATH, and restart the desktop app to reload environment variables.
### Git and Git LFS errors
On Windows, Git is required for the Code tab to start local sessions. If you see "Git is required," install [Git for Windows](https://git-scm.com/downloads/win) and restart the app.
If you see "Git LFS is required by this repository but is not installed," install Git LFS from [git-lfs.com](https://git-lfs.com/), run `git lfs install`, and restart the app.
### MCP servers not working on Windows
If MCP server toggles don't respond or servers fail to connect on Windows, check that the server is properly configured in your settings, restart the app, verify the server process is running in Task Manager, and review server logs for connection errors.
### App won't quit
* **macOS**: press Cmd+Q. If the app doesn't respond, use Force Quit with Cmd+Option+Esc, select Claude, and click Force Quit.
* **Windows**: use Task Manager with Ctrl+Shift+Esc to end the Claude process.
### Windows-specific issues
* **PATH not updated after install**: open a new terminal window. PATH updates only apply to new terminal sessions.
* **Concurrent installation error**: if you see an error about another installation in progress but there isn't one, try running the installer as Administrator.
### "Branch doesn't exist yet" when opening in CLI
Remote sessions can create branches that don't exist on your local machine. Click the branch name in the session toolbar to copy it, then fetch it locally:
```bash theme={null}
git fetch origin
git checkout
```
### Still stuck?
* Search or file a bug on [GitHub Issues](https://github.com/anthropics/claude-code/issues)
* Visit the [Claude support center](https://support.claude.com/)
When filing a bug, include your desktop app version, your operating system, the exact error message, and relevant logs. On macOS, check Console.app. On Windows, check Event Viewer → Windows Logs → Application.
---
## desktop-scheduled-tasks-eea8d1a9c8.md
> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Schedule recurring tasks in Claude Code Desktop
> Set up scheduled tasks in Claude Code Desktop to run Claude automatically on a recurring basis for daily code reviews, dependency audits, or morning briefings.
Scheduled tasks start a new session automatically at a time and frequency you choose. Use them for recurring work like daily code reviews, dependency update checks, or morning briefings that pull from your calendar and inbox.
The Desktop app's **Routines** page lets you create both local scheduled tasks and remote [routines](routines-3111c7bd3a.md). A local task runs on your machine with direct access to your files and tools, but only fires while the app is open and your computer is awake. A remote routine runs on Anthropic-managed cloud infrastructure even when your computer is off, and can also fire on API calls or GitHub events. This page covers local scheduled tasks; for remote routines and their trigger options, see [Routines](routines-3111c7bd3a.md).
## Compare scheduling options
Claude Code offers three ways to schedule recurring or one-off work:
| | [Cloud](routines-3111c7bd3a.md) | [Desktop](../16-Mobile-Desktop/desktop-scheduled-tasks.md) | [`/loop`](run-prompts-on-a-schedule-claude-code-docs.md) |
| :------------------------- | :----------------------------- | :------------------------------------- | :---------------------------------- |
| Runs on | Anthropic cloud | Your machine | Your machine |
| Requires machine on | No | Yes | Yes |
| Requires open session | No | No | Yes |
| Persistent across restarts | Yes | Yes | Restored on `--resume` if unexpired |
| Access to local files | No (fresh clone) | Yes | Yes |
| MCP servers | Connectors configured per task | [Config files](../06-MCP-Tools/mcp-208e742686.md) and connectors | Inherits from session |
| Permission prompts | No (runs autonomously) | Configurable per task | Inherits from session |
| Customizable schedule | Via `/schedule` in the CLI | Yes | Yes |
| Minimum interval | 1 hour | 1 minute | 1 minute |
Use **cloud tasks** for work that should run reliably without your machine. Use **Desktop tasks** when you need access to local files and tools. Use **`/loop`** for quick polling during a session.
By default, scheduled tasks run against whatever state your working directory is in, including uncommitted changes. Enable the worktree toggle when creating the task to give each run its own isolated Git worktree, the same way [parallel sessions](/en/desktop#work-in-parallel-with-sessions) work.
## Create a scheduled task
Click **Routines** in the sidebar, then click **New routine** and choose **Local**. Configure these fields:
| Field | Description |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Name | Identifier for the task. Converted to lowercase kebab-case and used as the folder name on disk. Must be unique across your tasks. |
| Description | Short summary shown in the task list. |
| Instructions | What Claude should do when the task runs. Write this the same way you'd write any message in the prompt box. The instructions input includes pickers for the permission mode and model, and below it you select the working folder and whether to run in an isolated worktree. |
| Schedule | How often the task runs. See [schedule options](#schedule-options) below. |
A folder is required before you can save the task. If you haven't trusted that folder yet, Desktop prompts you to trust it before saving.
You can also create a task by describing what you want in any session. For example, "set up a daily code review that runs every morning at 9am" creates a recurring task, and "remind me at 3pm tomorrow to check the deploy" creates a one-time task that disables itself after it fires.
## Schedule options
Pick a preset from the Schedule control:
* **Manual**: no schedule, only runs when you click **Run now**. Useful for saving a prompt you trigger on demand
* **Hourly**: runs every hour
* **Daily**: shows a time picker, defaults to 9:00 AM local time
* **Weekdays**: same as Daily but skips Saturday and Sunday
* **Weekly**: shows a time picker and a day picker
For intervals the picker doesn't offer, such as every 15 minutes, the first of each month, or a single run at a specific future time, ask Claude in any Desktop session to set the schedule. Use plain language; for example, "schedule a task to run all the tests every 6 hours."
## How scheduled tasks run
Scheduled tasks run on your machine. Desktop checks the schedule every minute while the app is open and starts a fresh session when a task is due, independent of any manual sessions you have open. Each task gets a small delay of a few minutes after the scheduled time to stagger API traffic. The delay is deterministic: the same task always starts at the same offset.
When a task fires, you get a desktop notification and a new session appears under a **Scheduled** section in the sidebar. Open it to see what Claude did, review changes, or respond to permission prompts. The session works like any other: Claude can edit files, run commands, create commits, and open pull requests.
Tasks only run while the desktop app is running and your computer is awake. If your computer sleeps through a scheduled time, the run is skipped. To prevent idle-sleep, enable **Keep computer awake** in Settings under **Desktop app → General**. Closing the laptop lid still puts it to sleep. For tasks that need to run even when your computer is off, or that should trigger on an API call or GitHub event, create a remote [routine](routines-3111c7bd3a.md) instead.
## Missed runs
When the app starts or your computer wakes, Desktop checks whether each task missed any runs in the last seven days. If it did, Desktop starts exactly one catch-up run for the most recently missed time and discards anything older. A daily task that missed six days runs once on wake. Desktop shows a notification when a catch-up run starts.
Keep this in mind when writing prompts. A task scheduled for 9am might run at 11pm if your computer was asleep all day. If timing matters, add guardrails to the prompt itself, for example: "Only review today's commits. If it's after 5pm, skip the review and just post a summary of what was missed."
## Permissions for scheduled tasks
Each task has its own permission mode, which you set when creating or editing the task. Allow rules from `~/.claude/settings.json` also apply to scheduled task sessions. If a task runs in Ask mode and needs to run a tool it doesn't have permission for, the run stalls until you approve it. The session stays open in the sidebar so you can answer later.
To avoid stalls, click **Run now** after creating a task, watch for permission prompts, and select "always allow" for each one. Future runs of that task auto-approve the same tools without prompting. You can review and revoke these approvals from the task's detail page.
## Manage scheduled tasks
Click a task in the **Routines** list to open its detail page. From here you can:
* **Run now**: start the task immediately without waiting for the next scheduled time
* **Status**: toggle between Active and Paused to pause or resume scheduled runs without deleting the task
* **Edit**: change the instructions, schedule, folder, or other settings
* **Review history**: see every past run, including skipped runs. Hover a skipped entry to see why: your computer was asleep, the previous run was still in progress, or other scheduled tasks were already running. Click **Show more** to load older entries.
* **Review allowed permissions**: see and revoke saved tool approvals for this task from the **Always allowed** panel
* **Delete**: remove the task and archive all sessions it created
You can also list, create, edit, and pause tasks by asking Claude in any Desktop session. For example, "pause my dependency-audit task" or "show me my scheduled tasks." To delete a task, use the **Delete** button on its detail page.
To edit a task's prompt on disk, open `~/.claude/scheduled-tasks//SKILL.md` (or under [`CLAUDE_CONFIG_DIR`](env-vars-5c624d392b.md) if set). The file uses YAML frontmatter for `name` and `description`, with the prompt as the body. Changes take effect on the next run. Schedule, folder, model, and enabled state are not in this file: change them through the Edit form or ask Claude.
## Related resources
* [Routines](routines-3111c7bd3a.md): run tasks on Anthropic-managed infrastructure on a schedule, via API call, or in response to GitHub events, even when your computer is off
* [Run prompts on a schedule](run-prompts-on-a-schedule-claude-code-docs.md): session-scoped scheduling with `/loop` in the CLI
* [Claude Code GitHub Actions](claude-code-github-actions-claude-code-docs-0d633fbd8a.md): run Claude on a schedule in CI instead of on your machine
* [Use Claude Code Desktop](../16-Mobile-Desktop/desktop.md): the full Desktop app guide
---
## devcontainer-38ed6ca20d.md
> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Development containers
> Learn about the Claude Code development container for teams that need consistent, secure environments.
The reference [devcontainer setup](https://github.com/anthropics/claude-code/tree/main/.devcontainer) and associated [Dockerfile](https://github.com/anthropics/claude-code/blob/main/.devcontainer/Dockerfile) offer a preconfigured development container that you can use as is, or customize for your needs. This devcontainer works with the Visual Studio Code [Dev Containers extension](https://code.visualstudio.com/docs/devcontainers/containers) 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.
While the devcontainer provides substantial protections, no system is completely immune to all attacks.
When executed with `--dangerously-skip-permissions`, devcontainers don't prevent a malicious project from exfiltrating anything accessible in the devcontainer including Claude Code credentials.
We recommend only using devcontainers when developing with trusted repositories.
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 [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
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 → "Dev Containers: Reopen in Container")
Once the container finishes building, open a terminal in VS Code with `` Ctrl+` `` and run `claude` to authenticate and start your first session. The container has Claude Code preinstalled, so you can begin working immediately. Your project files are mounted into the container, and any code Claude writes appears in your local repository.
## 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, Claude API, etc.)
* **Allowed outbound connections**: The firewall permits outbound DNS and SSH connections
* **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
## Example use cases
### Secure client work
Use devcontainers to isolate different client projects, ensuring code and credentials never mix between environments.
### Team onboarding
New team members can get a fully configured development environment in minutes, with all necessary tools and settings pre-installed.
### Consistent CI/CD environments
Mirror your devcontainer configuration in CI/CD pipelines to ensure development and production environments match.
## Related resources
* [VS Code devcontainers documentation](https://code.visualstudio.com/docs/devcontainers/containers)
* [Claude Code security best practices](../22-Safety-Policy/security-claude-code-docs-7538e94c51.md)
* [Enterprise network configuration](enterprise-network-configuration-claude-code-docs.md)
---
## devcontainer.md
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Development containers
> Learn about the Claude Code development container for teams that need consistent, secure environments.
The reference [devcontainer setup](https://github.com/anthropics/claude-code/tree/main/.devcontainer) and associated [Dockerfile](https://github.com/anthropics/claude-code/blob/main/.devcontainer/Dockerfile) offer a preconfigured development container that you can use as is, or customize for your needs. This devcontainer works with the Visual Studio Code [Dev Containers extension](https://code.visualstudio.com/docs/devcontainers/containers) 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.
While the devcontainer provides substantial protections, no system is completely immune to all attacks.
When executed with `--dangerously-skip-permissions`, devcontainers don't prevent a malicious project from exfiltrating anything accessible in the devcontainer including Claude Code credentials.
We recommend only using devcontainers when developing with trusted repositories.
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, Claude API, etc.)
* **Allowed outbound connections**: The firewall permits outbound DNS and SSH connections
* **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
## Example use cases
### Secure client work
Use devcontainers to isolate different client projects, ensuring code and credentials never mix between environments.
### Team onboarding
New team members can get a fully configured development environment in minutes, with all necessary tools and settings pre-installed.
### Consistent CI/CD environments
Mirror your devcontainer configuration in CI/CD pipelines to ensure development and production environments match.
## Related resources
* [VS Code devcontainers documentation](https://code.visualstudio.com/docs/devcontainers/containers)
* [Claude Code security best practices](security-claude-code-docs.md)
* [Enterprise network configuration](enterprise-network-configuration-claude-code-docs.md)
---
## development-containers-claude-code-docs-2e550b9d86.md
# Development containers
Run Claude Code inside a dev container for consistent, isolated environments across your team.
> ## Documentation Index
>
> Fetch the complete documentation index at:
>
> Use this file to discover all available pages before exploring further.
A [development container](https://containers.dev/), or dev container, lets you define an identical, isolated environment that every engineer on your team can run. With Claude Code installed in that container, commands Claude runs execute inside it rather than on the host machine, while edits to your project files appear in your local repository as you work. This page covers [installing Claude Code in a dev container](#add-claude-code-to-your-dev-container) and the configuration topics that follow. Each topic is self-contained, so jump to the ones that match what you need to set up:
- [Persist authentication and settings across rebuilds](#persist-authentication-and-settings-across-rebuilds)
- [Enforce organization policy](#enforce-organization-policy)
- [Restrict network egress](#restrict-network-egress)
- [Run without permission prompts](#run-without-permission-prompts)
While the dev container provides substantial protections, no system is completely immune to all attacks. When executed with `--dangerously-skip-permissions`, dev containers do not prevent a malicious project from exfiltrating anything accessible inside the container, including the Claude Code credentials stored in [`~/.claude`](/docs/en/claude-directory). Only use dev containers when developing with trusted repositories, and monitor Claude’s activities. Avoid mounting host secrets such as `~/.ssh` or cloud credential files into the container; prefer repository-scoped or short-lived tokens.
How dev containers work with your editor
A dev container runs as a Docker container, either on your machine or on a cloud host such as GitHub Codespaces. An editor that supports the Dev Containers spec, such as VS Code, GitHub Codespaces, a JetBrains IDE, or Cursor, connects to that container: you browse and edit files in the editor as usual, but the integrated terminal, language servers, and build tools all run inside the container rather than on your host. Editors without dev container support, such as plain Vim, are not part of this workflow.Claude Code runs inside the container, so it sees the same files, dependencies, and tools as the rest of your project’s toolchain. In VS Code you can use either the [Claude Code extension panel](/docs/en/vs-code) or run `claude` in the integrated terminal; both run inside the container and share the same `~/.claude` configuration.
Add Claude Code to your dev container
Claude Code installs into any dev container through the [Claude Code Dev Container Feature](https://github.com/anthropics/devcontainer-features/tree/main/src/claude-code). The settings work with any tool that supports the Dev Containers spec, such as VS Code, GitHub Codespaces, or JetBrains IDEs. The steps below use VS Code as an example. When you open the container in VS Code or Codespaces, the feature also adds the Claude Code VS Code extension; other editors ignore that part.
New to dev containers? The [VS Code Dev Containers tutorial](https://code.visualstudio.com/docs/devcontainers/tutorial) walks through installing Docker, the extension, and opening your first container. For a fuller hardened example with a firewall and persistent volumes, see [Try the reference container](#try-the-reference-container).
1
Create or update devcontainer.json
Save the following as `.devcontainer/devcontainer.json` in your repository, or add the `features` block to your existing file.The version tag at the end, such as `:1.0`, pins the feature’s install script, not the Claude Code release. The feature installs the latest Claude Code, and Claude Code auto-updates itself inside the container by default.To pin the CLI version or disable auto-update, see [Enforce organization policy](#enforce-organization-policy).
.devcontainer/devcontainer.json
```python
{
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
"features": {
"ghcr.io/anthropics/devcontainer-features/claude-code:1.0": {}
}
}
```
Replace the `image` line with your project’s base image or remove it if your existing file uses a Dockerfile.
2
Rebuild the container
Open the VS Code Command Palette with `Cmd+Shift+P` on Mac or `Ctrl+Shift+P` on Windows and Linux, and run **Dev Containers: Rebuild Container**.For other tools, follow that tool’s rebuild action: see [rebuilding in GitHub Codespaces](https://docs.github.com/en/codespaces/developing-in-a-codespace/rebuilding-the-container-in-a-codespace), the [Dev Containers CLI](https://github.com/devcontainers/cli), or your IDE’s dev container documentation.
3
Sign in to Claude Code
Open a terminal in the rebuilt container and run `claude`, then follow the authentication prompt.
What you see at the authentication prompt depends on your provider:
- **Anthropic**: sign in through a browser with your Claude or Anthropic Console account
- **[Amazon Bedrock, Google Vertex AI, or Microsoft Foundry](/docs/en/third-party-integrations)**: Claude Code uses your cloud provider credentials, with no browser prompt
For cloud providers, pass credentials into the container as environment variables through `containerEnv`, a Codespaces secret, or your cloud’s workload identity rather than mounting credential files from the host. See [Amazon Bedrock](/docs/en/amazon-bedrock), [Google Vertex AI](/docs/en/google-vertex-ai), or [Microsoft Foundry](/docs/en/microsoft-foundry) for the credential chain Claude Code reads. See [Choose your API provider](/docs/en/admin-setup#choose-your-api-provider) to decide which path fits your organization.
If the browser sign-in completes but the callback never reaches the container, copy the code shown in the browser and paste it at the `Paste code here if prompted` prompt in the terminal. This can happen when the editor’s port forwarding doesn’t route the localhost callback.
Persist authentication and settings across rebuilds
By default, the container’s home directory is discarded on rebuild, so engineers must sign in again each time. Claude Code stores its authentication token, user settings, and session history under [`~/.claude`](/docs/en/claude-directory). Mount a named volume at that path to keep this state across rebuilds. The following example mounts a volume at the home directory of the `node` user:
devcontainer.json
```python
"mounts": [
"source=claude-code-config,target=/home/node/.claude,type=volume"
]
```
Replace `/home/node` with the home directory of your container’s `remoteUser`. If you mount the volume somewhere other than `~/.claude`, set [`CLAUDE_CONFIG_DIR`](/docs/en/env-vars) to the mount path so Claude Code reads and writes there. To isolate state per project rather than sharing one volume across all repositories, include the `${devcontainerId}` variable in the source name. The [reference configuration](https://github.com/anthropics/claude-code/blob/main/.devcontainer/devcontainer.json) uses `source=claude-code-config-${devcontainerId}` for this purpose. In GitHub Codespaces, `~/.claude` persists across stopping and starting a codespace, but is still cleared when you rebuild the container, so the volume mount above applies there too. To carry authentication across codespaces, store `ANTHROPIC_API_KEY` or a `CLAUDE_CODE_OAUTH_TOKEN` from [`claude setup-token`](/docs/en/authentication#generate-a-long-lived-token) as a [Codespaces secret](https://docs.github.com/en/codespaces/managing-your-codespaces/managing-your-account-specific-secrets-for-github-codespaces); Codespaces makes secrets available as environment variables inside the container automatically.
Enforce organization policy
A dev container is a convenient place to apply organization policy, because the same image and configuration run on every engineer’s machine. Claude Code reads `/etc/claude-code/managed-settings.json` on Linux and applies it at the highest precedence in the [settings hierarchy](/docs/en/settings#how-scopes-interact), so values there override anything an engineer sets in `~/.claude` or the project’s `.claude/` directory. Copy the file into place from your Dockerfile:
Dockerfile
```python
RUN mkdir -p /etc/claude-code
COPY managed-settings.json /etc/claude-code/managed-settings.json
```
Because the Dockerfile lives in the repository, anyone with write access can change or remove this step. For policy that engineers cannot bypass by editing repository files, deliver managed settings through [server-managed settings](/docs/en/server-managed-settings) or your MDM instead. See [managed settings files](/docs/en/settings#settings-files) for the available keys and the other delivery paths. To set [environment variables](/docs/en/env-vars) that apply to every Claude Code session in the container, add them to `containerEnv` in your `devcontainer.json`. The following example opts out of telemetry and error reporting and prevents Claude Code from auto-updating after install:
devcontainer.json
```python
"containerEnv": {
"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
"DISABLE_AUTOUPDATER": "1"
}
```
The Dev Container Feature always installs the latest Claude Code release. To pin a specific Claude Code version for reproducible builds, install it from your Dockerfile with `npm install -g @anthropic-ai/claude-code@X.Y.Z` instead of using the feature, and set `DISABLE_AUTOUPDATER` as shown above. For the full list of policy controls including permission rules, tool restrictions, and MCP server allowlists, see [Set up Claude Code for your organization](/docs/en/admin-setup). To make [MCP servers](/docs/en/mcp) available inside the container, define them at [project scope](/docs/en/mcp#mcp-installation-scopes) in a `.mcp.json` file at the repository root so they are checked in alongside your dev container configuration. Install any binaries that local stdio servers depend on in your Dockerfile, and add remote server domains to your network allowlist.
Restrict network egress
You can limit the container’s outbound traffic to only the domains Claude Code needs. See [Network access requirements](/docs/en/network-config#network-access-requirements) for the inference and authentication domains, and [Telemetry services](/docs/en/data-usage#telemetry-services) for the optional telemetry and error reporting connections and how to disable them. The reference container includes an [`init-firewall.sh`](https://github.com/anthropics/claude-code/blob/main/.devcontainer/init-firewall.sh) script that blocks all outbound traffic except the domains Claude Code and your development tools need. Running a firewall inside a container requires extra permissions, so the reference adds the `NET_ADMIN` and `NET_RAW` capabilities through `runArgs`. The firewall script and these capabilities are not required for Claude Code itself: you can leave them out and rely on your own network controls instead.
Run without permission prompts
Because the container runs Claude Code as a non-root user and confines command execution to the container, you can pass `--dangerously-skip-permissions` for unattended operation. The CLI rejects this flag when launched as root, so confirm `remoteUser` is set to a non-root account. Skipping permission prompts removes your opportunity to review tool calls before they run. Claude can still modify any file in the bind-mounted workspace, which appears directly on your host, and reach anything the container’s network policy allows. Pair this flag with the [network egress restrictions](#restrict-network-egress) above to limit what a bypassed session can reach. If you want fewer prompts without disabling safety checks, consider [auto mode](/docs/en/permission-modes#eliminate-prompts-with-auto-mode) instead, which has a classifier review actions before they run. To prevent engineers from using `--dangerously-skip-permissions` at all, set `permissions.disableBypassPermissionsMode` to `"disable"` in [managed settings](/docs/en/settings#permission-settings).
Try the reference container
The [`anthropics/claude-code`](https://github.com/anthropics/claude-code/tree/main/.devcontainer) repository includes an example dev container that combines the CLI, the egress firewall, persistent volumes, and a Zsh-based shell. It is provided as a working example rather than a maintained base image; use it to see how the pieces fit together before applying them to your own configuration.
1
Install prerequisites
Install VS Code and the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
2
Clone the reference
Clone the [Claude Code repository](https://github.com/anthropics/claude-code) and open it in VS Code.
3
Reopen in container
When prompted, click **Reopen in Container**, or run **Dev Containers: Reopen in Container** from the Command Palette.
4
Start Claude Code
Once the container finishes building, open a terminal with `` Ctrl+` `` and run `claude` to sign in and start your first session.
To use this configuration with your own project, copy the `.devcontainer/` directory into your repository and adjust the Dockerfile for your toolchain, or return to [Add Claude Code to your dev container](#add-claude-code-to-your-dev-container) to add only the feature to a setup you already have. The reference configuration consists of three files. None of them are required when you add Claude Code to your own dev container through the feature, but they show one way to combine the pieces.
| File | Purpose |
|------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------|
| [`devcontainer.json`](https://github.com/anthropics/claude-code/blob/main/.devcontainer/devcontainer.json) | Volume mounts, `runArgs` capabilities, VS Code extensions, and `containerEnv` |
| [`Dockerfile`](https://github.com/anthropics/claude-code/blob/main/.devcontainer/Dockerfile) | Base image, development tools, and the Claude Code install |
| [`init-firewall.sh`](https://github.com/anthropics/claude-code/blob/main/.devcontainer/init-firewall.sh) | Blocks all outbound network traffic except the allowed domains |
Next steps
Once Claude Code is running in your dev container, the pages below cover the rest of an organization rollout: choosing an authentication path, delivering managed policy outside the repository, monitoring usage, and understanding what Claude Code stores and sends.
- [Set up Claude Code for your organization](/docs/en/admin-setup): choose an authentication provider, decide how policy reaches devices, and plan the rollout
- [Server-managed settings](/docs/en/server-managed-settings): deliver managed policy from the Claude.ai admin console so engineers cannot bypass it by editing repository files
- [Monitor usage and audit activity](/docs/en/monitoring-usage): export OpenTelemetry metrics and review what your team is running
- [Network access requirements](/docs/en/network-config#network-access-requirements): the full domain allowlist for proxies and firewalls
- [Telemetry services and opt-out](/docs/en/data-usage#telemetry-services): what Claude Code sends by default and the environment variables that disable it
- [Explore the `.claude` directory](/docs/en/claude-directory): what the volume mount holds, including credentials, settings, and session history
- [Security model](/docs/en/security): how Claude Code’s permission system, sandboxing, and prompt-injection protections fit together
- [Permission modes](/docs/en/permission-modes): the full range from plan mode to auto mode to bypass, and when to use each
---
## development-containers-claude-code-docs.md
# Development containers
Learn about the Claude Code development container for teams that need consistent, secure environments.
The reference [devcontainer setup](https://github.com/anthropics/claude-code/tree/main/.devcontainer) and associated [Dockerfile](https://github.com/anthropics/claude-code/blob/main/.devcontainer/Dockerfile) offer a preconfigured development container that you can use as is, or customize for your needs. This devcontainer works with the Visual Studio Code [Dev Containers extension](https://code.visualstudio.com/docs/devcontainers/containers) 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.
While the devcontainer provides substantial protections, no system is completely immune to all attacks. When executed with `--dangerously-skip-permissions`, devcontainers don’t prevent a malicious project from exfiltrating anything accessible in the devcontainer including Claude Code credentials. We recommend only using devcontainers when developing with trusted repositories. 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 [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
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 → “Dev Containers: Reopen in Container”)
Once the container finishes building, open a terminal in VS Code with `` Ctrl+` `` and run `claude` to authenticate and start your first session. The container has Claude Code preinstalled, so you can begin working immediately. Your project files are mounted into the container, and any code Claude writes appears in your local repository.
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, Claude API, etc.)
- **Allowed outbound connections**: The firewall permits outbound DNS and SSH connections
- **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
Example use cases
Secure client work
Use devcontainers to isolate different client projects, ensuring code and credentials never mix between environments.
Team onboarding
New team members can get a fully configured development environment in minutes, with all necessary tools and settings pre-installed.
Consistent CI/CD environments
Mirror your devcontainer configuration in CI/CD pipelines to ensure development and production environments match.
Related resources
- [VS Code devcontainers documentation](https://code.visualstudio.com/docs/devcontainers/containers)
- [Claude Code security best practices](/docs/en/security)
- [Enterprise network configuration](/docs/en/network-config)
---
## diff.md
# Claude Binary Intel Diff
- New: `/home/zack/claude-binary/2.1.74/2.1.74`
- Old: `/home/zack/.local/share/claude/versions/2.1.72`
- Generated (UTC): `2026-03-12T04:12:21.993635+00:00`
## flags
- added: `5`
- removed: `0`
### added
- `--auto-approve`
- `--kill-after`
- `--preserve-status`
- `--remote-control`
- `--signal`
## internal_flags
- added: `1`
- removed: `0`
### added
- `--remote-control`
## env_vars
- added: `5`
- removed: `1`
### added
- `ANTHROPIC_FOUNDRY_AUTH_TOKEN`
- `ANTHROPIC_UNIX_SOCKET`
- `CLAUDE_CODE_FRAME_TIMING_LOG`
- `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS`
- `CLAUDE_SONNET_4_6`
### removed
- `CLAUDE_CODE_TWO_STAGE_CLASSIFIER`
## domains
- added: `0`
- removed: `0`
## model_ids
- added: `2`
- removed: `0`
### added
- `claude-code-feedback`
- `claude-for-hiring`
## bunfs_paths
- added: `0`
- removed: `0`
## code_tokens
- added: `14`
- removed: `7`
### added
- `tengu_auto_mode_state`
- `tengu_chair_sermon`
- `tengu_compact_failedul`
- `tengu_hawthorn_steeple`
- `tengu_hawthorn_window`
- `tengu_image_resize_fallbackw`
- `tengu_marble_whisper2`
- `tengu_message_level_tool_result_budget_enforced`
- `tengu_orchid_trellis`
- `tengu_pewter_ledger`
- `tengu_tool_empty_result`
- `tengu_tool_result_persisted_message_budget`
- `tengu_voice_recording_completed`
- `tengu_voice_stream_early_retry`
### removed
- `tengu_marble_whisper`
- `tengu_native_version_cleanupk`
- `tengu_output_style_command_inline`
- `tengu_output_style_command_inline_help`
- `tengu_output_style_command_menu`
- `tengu_pdf_page_extractionm`
- `tengu_unexpected_tool_resulti`
## http_methods_with_url_context
- added: `0`
- removed: `0`
## urls
- added: `14`
- removed: `10`
### added
- `http://${w}:${q.port}/sse`
- `http://169.254.169.254${FSD`
- `https://${p}/${x}/${d`
- `https://${q}/${K`
- `https://${S}/${h}/${u`
- `https://code.claude.com/docs/en/microsoft-foundryj`
- `https://code.claude.com/docs/en/network-config`
- `https://code.claude.com/docs/en/remote-control`
- `https://example.com/mcp`
- `https://github.com/${fH`
- `https://github.com/${H}/compare/${P}...${z}?quick_pull=1&title=${encodeURIComponent(Xsf)}&body=${encodeURIComponent(Gsf`
- `https://github.com/${MH`
- `https://github.com/${x}/${d`
- `https://login.microsoftonline.com/${fz1}/`
### removed
- `http://${P}:${M.port}/sse`
- `http://169.254.169.254${yhf`
- `https://${h}/${R}/${x`
- `https://${K}/${q`
- `https://${p}/${b}/${d`
- `https://github.com/${_H`
- `https://github.com/${b}/${d`
- `https://github.com/${EH`
- `https://github.com/${H}/compare/${P}...${z}?quick_pull=1&title=${encodeURIComponent(Xa8)}&body=${encodeURIComponent(Ga8`
- `https://login.microsoftonline.com/${nP1}/`
---
## discover-and-install-prebuilt-plugins-through-marketplaces-claude-code-docs.md
# Discover and install prebuilt plugins through marketplaces
Find and install plugins from marketplaces to extend Claude Code with new commands, agents, and capabilities.
Plugins extend Claude Code with skills, agents, hooks, and MCP servers. Plugin marketplaces are catalogs that help you discover and install these extensions without building them yourself. Looking to create and distribute your own marketplace? See [Create and distribute a plugin marketplace](/docs/en/plugin-marketplaces).
##
How marketplaces work
A marketplace is a catalog of plugins that someone else has created and shared. Using a marketplace is a two-step process:
1
[](#)
Add the marketplace
This registers the catalog with Claude Code so you can browse what’s available. No plugins are installed yet.
2
[](#)
Install individual plugins
Browse the catalog and install the plugins you want.
Think of it like adding an app store: adding the store gives you access to browse its collection, but you still choose which apps to download individually.
##
Official Anthropic marketplace
The official Anthropic marketplace (`claude-plugins-official`) is automatically available when you start Claude Code. Run `/plugin` and go to the **Discover** tab to browse what’s available. To install a plugin from the official marketplace:
Report incorrect code
Copy
``` shiki
/plugin install plugin-name@claude-plugins-official
```
The official marketplace is maintained by Anthropic. To submit a plugin to the official marketplace, use one of the in-app submission forms:
- **Claude.ai**: [claude.ai/settings/plugins/submit](https://claude.ai/settings/plugins/submit)
- **Console**: [platform.claude.com/plugins/submit](https://platform.claude.com/plugins/submit)
To distribute plugins independently, [create your own marketplace](/docs/en/plugin-marketplaces) and share it with users.
The official marketplace includes several categories of plugins:
###
Code intelligence
Code intelligence plugins enable Claude Code’s built-in LSP tool, giving Claude the ability to jump to definitions, find references, and see type errors immediately after edits. These plugins configure [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) connections, the same technology that powers VS Code’s code intelligence. These plugins require the language server binary to be installed on your system. If you already have a language server installed, Claude may prompt you to install the corresponding plugin when you open a project.
| Language | Plugin | Binary required |
|:-----------|:--------------------|:-----------------------------|
| C/C++ | `clangd-lsp` | `clangd` |
| C# | `csharp-lsp` | `csharp-ls` |
| Go | `gopls-lsp` | `gopls` |
| Java | `jdtls-lsp` | `jdtls` |
| Kotlin | `kotlin-lsp` | `kotlin-language-server` |
| Lua | `lua-lsp` | `lua-language-server` |
| PHP | `php-lsp` | `intelephense` |
| Python | `pyright-lsp` | `pyright-langserver` |
| Rust | `rust-analyzer-lsp` | `rust-analyzer` |
| Swift | `swift-lsp` | `sourcekit-lsp` |
| TypeScript | `typescript-lsp` | `typescript-language-server` |
You can also [create your own LSP plugin](/docs/en/plugins-reference#lsp-servers) for other languages.
If you see `Executable not found in $PATH` in the `/plugin` Errors tab after installing a plugin, install the required binary from the table above.
####
What Claude gains from code intelligence plugins
Once a code intelligence plugin is installed and its language server binary is available, Claude gains two capabilities:
- **Automatic diagnostics**: after every file edit Claude makes, the language server analyzes the changes and reports errors and warnings back automatically. Claude sees type errors, missing imports, and syntax issues without needing to run a compiler or linter. If Claude introduces an error, it notices and fixes the issue in the same turn. This requires no configuration beyond installing the plugin. You can see diagnostics inline by pressing **Ctrl+O** when the “diagnostics found” indicator appears.
- **Code navigation**: Claude can use the language server to jump to definitions, find references, get type info on hover, list symbols, find implementations, and trace call hierarchies. These operations give Claude more precise navigation than grep-based search, though availability may vary by language and environment.
If you run into issues, see [Code intelligence troubleshooting](#code-intelligence-issues).
###
External integrations
These plugins bundle pre-configured [MCP servers](/docs/en/mcp) so you can connect Claude to external services without manual setup:
- **Source control**: `github`, `gitlab`
- **Project management**: `atlassian` (Jira/Confluence), `asana`, `linear`, `notion`
- **Design**: `figma`
- **Infrastructure**: `vercel`, `firebase`, `supabase`
- **Communication**: `slack`
- **Monitoring**: `sentry`
###
Development workflows
Plugins that add commands and agents for common development tasks:
- **commit-commands**: Git commit workflows including commit, push, and PR creation
- **pr-review-toolkit**: Specialized agents for reviewing pull requests
- **agent-sdk-dev**: Tools for building with the Claude Agent SDK
- **plugin-dev**: Toolkit for creating your own plugins
###
Output styles
Customize how Claude responds:
- **explanatory-output-style**: Educational insights about implementation choices
- **learning-output-style**: Interactive learning mode for skill building
##
Try it: add the demo marketplace
Anthropic also maintains a [demo plugins marketplace](https://github.com/anthropics/claude-code/tree/main/plugins) (`claude-code-plugins`) with example plugins that show what’s possible with the plugin system. Unlike the official marketplace, you need to add this one manually.
1
[](#)
Add the marketplace
From within Claude Code, run the `plugin marketplace add` command for the `anthropics/claude-code` marketplace:
Report incorrect code
Copy
``` shiki
/plugin marketplace add anthropics/claude-code
```
This downloads the marketplace catalog and makes its plugins available to you.
2
[](#)
Browse available plugins
Run `/plugin` to open the plugin manager. This opens a tabbed interface with four tabs you can cycle through using **Tab** (or **Shift+Tab** to go backward):
- **Discover**: browse available plugins from all your marketplaces
- **Installed**: view and manage your installed plugins
- **Marketplaces**: add, remove, or update your added marketplaces
- **Errors**: view any plugin loading errors
Go to the **Discover** tab to see plugins from the marketplace you just added.
3
[](#)
Install a plugin
Select a plugin to view its details, then choose an installation scope:
- **User scope**: install for yourself across all projects
- **Project scope**: install for all collaborators on this repository
- **Local scope**: install for yourself in this repository only
For example, select **commit-commands** (a plugin that adds git workflow commands) and install it to your user scope.You can also install directly from the command line:
Report incorrect code
Copy
``` shiki
/plugin install commit-commands@anthropics-claude-code
```
See [Configuration scopes](/docs/en/settings#configuration-scopes) to learn more about scopes.
4
[](#)
Use your new plugin
After installing, the plugin’s commands are immediately available. Plugin commands are namespaced by the plugin name, so **commit-commands** provides commands like `/commit-commands:commit`.Try it out by making a change to a file and running:
Report incorrect code
Copy
``` shiki
/commit-commands:commit
```
This stages your changes, generates a commit message, and creates the commit.Each plugin works differently. Check the plugin’s description in the **Discover** tab or its homepage to learn what commands and capabilities it provides.
The rest of this guide covers all the ways you can add marketplaces, install plugins, and manage your configuration.
##
Add marketplaces
Use the `/plugin marketplace add` command to add marketplaces from different sources.
**Shortcuts**: You can use `/plugin market` instead of `/plugin marketplace`, and `rm` instead of `remove`.
- **GitHub repositories**: `owner/repo` format (for example, `anthropics/claude-code`)
- **Git URLs**: any git repository URL (GitLab, Bitbucket, self-hosted)
- **Local paths**: directories or direct paths to `marketplace.json` files
- **Remote URLs**: direct URLs to hosted `marketplace.json` files
###
Add from GitHub
Add a GitHub repository that contains a `.claude-plugin/marketplace.json` file using the `owner/repo` format—where `owner` is the GitHub username or organization and `repo` is the repository name. For example, `anthropics/claude-code` refers to the `claude-code` repository owned by `anthropics`:
Report incorrect code
Copy
``` shiki
/plugin marketplace add anthropics/claude-code
```
###
Add from other Git hosts
Add any git repository by providing the full URL. This works with any Git host, including GitLab, Bitbucket, and self-hosted servers: Using HTTPS:
Report incorrect code
Copy
``` shiki
/plugin marketplace add https://gitlab.com/company/plugins.git
```
Using SSH:
Report incorrect code
Copy
``` shiki
/plugin marketplace add [email protected]:company/plugins.git
```
To add a specific branch or tag, append `#` followed by the ref:
Report incorrect code
Copy
``` shiki
/plugin marketplace add https://gitlab.com/company/plugins.git#v1.0.0
```
###
Add from local paths
Add a local directory that contains a `.claude-plugin/marketplace.json` file:
Report incorrect code
Copy
``` shiki
/plugin marketplace add ./my-marketplace
```
You can also add a direct path to a `marketplace.json` file:
Report incorrect code
Copy
``` shiki
/plugin marketplace add ./path/to/marketplace.json
```
###
Add from remote URLs
Add a remote `marketplace.json` file via URL:
Report incorrect code
Copy
``` shiki
/plugin marketplace add https://example.com/marketplace.json
```
URL-based marketplaces have some limitations compared to Git-based marketplaces. If you encounter “path not found” errors when installing plugins, see [Troubleshooting](/docs/en/plugin-marketplaces#plugins-with-relative-paths-fail-in-url-based-marketplaces).
##
Install plugins
Once you’ve added marketplaces, you can install plugins directly (installs to user scope by default):
Report incorrect code
Copy
``` shiki
/plugin install plugin-name@marketplace-name
```
To choose a different [installation scope](/docs/en/settings#configuration-scopes), use the interactive UI: run `/plugin`, go to the **Discover** tab, and press **Enter** on a plugin. You’ll see options for:
- **User scope** (default): install for yourself across all projects
- **Project scope**: install for all collaborators on this repository (adds to `.claude/settings.json`)
- **Local scope**: install for yourself in this repository only (not shared with collaborators)
You may also see plugins with **managed** scope—these are installed by administrators via [managed settings](/docs/en/settings#settings-files) and cannot be modified. Run `/plugin` and go to the **Installed** tab to see your plugins grouped by scope.
Make sure you trust a plugin before installing it. Anthropic does not control what MCP servers, files, or other software are included in plugins and cannot verify that they work as intended. Check each plugin’s homepage for more information.
##
Manage installed plugins
Run `/plugin` and go to the **Installed** tab to view, enable, disable, or uninstall your plugins. Type to filter the list by plugin name or description. You can also manage plugins with direct commands. Disable a plugin without uninstalling:
Report incorrect code
Copy
``` shiki
/plugin disable plugin-name@marketplace-name
```
Re-enable a disabled plugin:
Report incorrect code
Copy
``` shiki
/plugin enable plugin-name@marketplace-name
```
Completely remove a plugin:
Report incorrect code
Copy
``` shiki
/plugin uninstall plugin-name@marketplace-name
```
The `--scope` option lets you target a specific scope with CLI commands:
Report incorrect code
Copy
``` shiki
claude plugin install formatter@your-org --scope project
claude plugin uninstall formatter@your-org --scope project
```
###
Apply plugin changes without restarting
When you install, enable, or disable plugins during a session, some changes (like new commands and hooks) take effect immediately. Others, including LSP server updates, require a restart. To activate all pending plugin changes without restarting, run:
Report incorrect code
Copy
``` shiki
/reload-plugins
```
Claude Code reloads all active plugins and reports what was loaded. If any LSP servers were added or updated, it will let you know those require a restart to take effect.
##
Manage marketplaces
You can manage marketplaces through the interactive `/plugin` interface or with CLI commands.
###
Use the interactive interface
Run `/plugin` and go to the **Marketplaces** tab to:
- View all your added marketplaces with their sources and status
- Add new marketplaces
- Update marketplace listings to fetch the latest plugins
- Remove marketplaces you no longer need
###
Use CLI commands
You can also manage marketplaces with direct commands. List all configured marketplaces:
Report incorrect code
Copy
``` shiki
/plugin marketplace list
```
Refresh plugin listings from a marketplace:
Report incorrect code
Copy
``` shiki
/plugin marketplace update marketplace-name
```
Remove a marketplace:
Report incorrect code
Copy
``` shiki
/plugin marketplace remove marketplace-name
```
Removing a marketplace will uninstall any plugins you installed from it.
###
Configure auto-updates
Claude Code can automatically update marketplaces and their installed plugins at startup. When auto-update is enabled for a marketplace, Claude Code refreshes the marketplace data and updates installed plugins to their latest versions. If any plugins were updated, you’ll see a notification prompting you to run `/reload-plugins`. Toggle auto-update for individual marketplaces through the UI:
1. Run `/plugin` to open the plugin manager
2. Select **Marketplaces**
3. Choose a marketplace from the list
4. Select **Enable auto-update** or **Disable auto-update**
Official Anthropic marketplaces have auto-update enabled by default. Third-party and local development marketplaces have auto-update disabled by default. To disable all automatic updates entirely for both Claude Code and all plugins, set the `DISABLE_AUTOUPDATER` environment variable. See [Auto updates](/docs/en/setup#auto-updates) for details. To keep plugin auto-updates enabled while disabling Claude Code auto-updates, set `FORCE_AUTOUPDATE_PLUGINS=true` along with `DISABLE_AUTOUPDATER`:
Report incorrect code
Copy
``` shiki
export DISABLE_AUTOUPDATER=true
export FORCE_AUTOUPDATE_PLUGINS=true
```
This is useful when you want to manage Claude Code updates manually but still receive automatic plugin updates.
##
Configure team marketplaces
Team admins can set up automatic marketplace installation for projects by adding marketplace configuration to `.claude/settings.json`. When team members trust the repository folder, Claude Code prompts them to install these marketplaces and plugins. Add `extraKnownMarketplaces` to your project’s `.claude/settings.json`:
Report incorrect code
Copy
``` shiki
{
"extraKnownMarketplaces": {
"my-team-tools": {
"source": {
"source": "github",
"repo": "your-org/claude-plugins"
}
}
}
}
```
For full configuration options including `extraKnownMarketplaces` and `enabledPlugins`, see [Plugin settings](/docs/en/settings#plugin-settings).
##
Security
Plugins and marketplaces are highly trusted components that can execute arbitrary code on your machine with your user privileges. Only install plugins and add marketplaces from sources you trust. Organizations can restrict which marketplaces users are allowed to add using [managed marketplace restrictions](/docs/en/plugin-marketplaces#managed-marketplace-restrictions).
##
Troubleshooting
###
/plugin command not recognized
If you see “unknown command” or the `/plugin` command doesn’t appear:
1. **Check your version**: Run `claude --version`. Plugins require version 1.0.33 or later.
2. **Update Claude Code**:
- **Homebrew**: `brew upgrade claude-code`
- **npm**: `npm update -g @anthropic-ai/claude-code`
- **Native installer**: Re-run the install command from [Setup](/docs/en/setup)
3. **Restart Claude Code**: After updating, restart your terminal and run `claude` again.
###
Common issues
- **Marketplace not loading**: Verify the URL is accessible and that `.claude-plugin/marketplace.json` exists at the path
- **Plugin installation failures**: Check that plugin source URLs are accessible and repositories are public (or you have access)
- **Files not found after installation**: Plugins are copied to a cache, so paths referencing files outside the plugin directory won’t work
- **Plugin skills not appearing**: Clear the cache with `rm -rf ~/.claude/plugins/cache`, restart Claude Code, and reinstall the plugin.
For detailed troubleshooting with solutions, see [Troubleshooting](/docs/en/plugin-marketplaces#troubleshooting) in the marketplace guide. For debugging tools, see [Debugging and development tools](/docs/en/plugins-reference#debugging-and-development-tools).
###
Code intelligence issues
- **Language server not starting**: verify the binary is installed and available in your `$PATH`. Check the `/plugin` Errors tab for details.
- **High memory usage**: language servers like `rust-analyzer` and `pyright` can consume significant memory on large projects. If you experience memory issues, disable the plugin with `/plugin disable ` and rely on Claude’s built-in search tools instead.
- **False positive diagnostics in monorepos**: language servers may report unresolved import errors for internal packages if the workspace isn’t configured correctly. These don’t affect Claude’s ability to edit code.
##
Next steps
- **Build your own plugins**: See [Plugins](/docs/en/plugins) to create skills, agents, and hooks
- **Create a marketplace**: See [Create a plugin marketplace](/docs/en/plugin-marketplaces) to distribute plugins to your team or community
- **Technical reference**: See [Plugins reference](/docs/en/plugins-reference) for complete specifications
---
## discover-plugins-c8a77f0998.md
> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Discover and install prebuilt plugins through marketplaces
> Find and install plugins from marketplaces to extend Claude Code with new skills, agents, and capabilities.
Plugins extend Claude Code with skills, agents, hooks, and MCP servers. Plugin marketplaces are catalogs that help you discover and install these extensions without building them yourself.
Looking to create and distribute your own marketplace? See [Create and distribute a plugin marketplace](../08-Plugins-Skills/create-and-distribute-a-plugin-marketplace-claude-code-docs-34a8f3c5e8.md).
## How marketplaces work
A marketplace is a catalog of plugins that someone else has created and shared. Using a marketplace is a two-step process:
This registers the catalog with Claude Code so you can browse what's available. No plugins are installed yet.
Browse the catalog and install the plugins you want.
Think of it like adding an app store: adding the store gives you access to browse its collection, but you still choose which apps to download individually.
## Official Anthropic marketplace
The official Anthropic marketplace (`claude-plugins-official`) is automatically available when you start Claude Code. Run `/plugin` and go to the **Discover** tab to browse what's available, or view the catalog at [claude.com/plugins](https://claude.com/plugins).
To install a plugin from the official marketplace, use `/plugin install @claude-plugins-official`. For example, to install the GitHub integration:
```shell theme={null}
/plugin install github@claude-plugins-official
```
If Claude Code reports that the plugin is not found in any marketplace, your marketplace is either missing or outdated. Run `/plugin marketplace update claude-plugins-official` to refresh it, or `/plugin marketplace add anthropics/claude-plugins-official` if you haven't added it before. Then retry the install.
The official marketplace is maintained by Anthropic. To submit a plugin to the official marketplace, use one of the in-app submission forms:
* **Claude.ai**: [claude.ai/settings/plugins/submit](https://claude.ai/settings/plugins/submit)
* **Console**: [platform.claude.com/plugins/submit](https://platform.claude.com/plugins/submit)
To distribute plugins independently, [create your own marketplace](../08-Plugins-Skills/create-and-distribute-a-plugin-marketplace-claude-code-docs-34a8f3c5e8.md) and share it with users.
The official marketplace includes several categories of plugins:
### Code intelligence
Code intelligence plugins enable Claude Code's built-in LSP tool, giving Claude the ability to jump to definitions, find references, and see type errors immediately after edits. These plugins configure [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) connections, the same technology that powers VS Code's code intelligence.
These plugins require the language server binary to be installed on your system. If you already have a language server installed, Claude may prompt you to install the corresponding plugin when you open a project.
| Language | Plugin | Binary required |
| :--------- | :------------------ | :--------------------------- |
| C/C++ | `clangd-lsp` | `clangd` |
| C# | `csharp-lsp` | `csharp-ls` |
| Go | `gopls-lsp` | `gopls` |
| Java | `jdtls-lsp` | `jdtls` |
| Kotlin | `kotlin-lsp` | `kotlin-language-server` |
| Lua | `lua-lsp` | `lua-language-server` |
| PHP | `php-lsp` | `intelephense` |
| Python | `pyright-lsp` | `pyright-langserver` |
| Rust | `rust-analyzer-lsp` | `rust-analyzer` |
| Swift | `swift-lsp` | `sourcekit-lsp` |
| TypeScript | `typescript-lsp` | `typescript-language-server` |
You can also [create your own LSP plugin](/en/plugins-reference#lsp-servers) for other languages.
If you see `Executable not found in $PATH` in the `/plugin` Errors tab after installing a plugin, install the required binary from the table above.
#### What Claude gains from code intelligence plugins
Once a code intelligence plugin is installed and its language server binary is available, Claude gains two capabilities:
* **Automatic diagnostics**: after every file edit Claude makes, the language server analyzes the changes and reports errors and warnings back automatically. Claude sees type errors, missing imports, and syntax issues without needing to run a compiler or linter. If Claude introduces an error, it notices and fixes the issue in the same turn. This requires no configuration beyond installing the plugin. You can see diagnostics inline by pressing **Ctrl+O** when the "diagnostics found" indicator appears.
* **Code navigation**: Claude can use the language server to jump to definitions, find references, get type info on hover, list symbols, find implementations, and trace call hierarchies. These operations give Claude more precise navigation than grep-based search, though availability may vary by language and environment.
If you run into issues, see [Code intelligence troubleshooting](#code-intelligence-issues).
### External integrations
These plugins bundle pre-configured [MCP servers](../06-MCP-Tools/mcp-208e742686.md) so you can connect Claude to external services without manual setup:
* **Source control**: `github`, `gitlab`
* **Project management**: `atlassian` (Jira/Confluence), `asana`, `linear`, `notion`
* **Design**: `figma`
* **Infrastructure**: `vercel`, `firebase`, `supabase`
* **Communication**: `slack`
* **Monitoring**: `sentry`
### Development workflows
Plugins that add skills and agents for common development tasks:
* **commit-commands**: Git commit workflows including commit, push, and PR creation
* **pr-review-toolkit**: Specialized agents for reviewing pull requests
* **agent-sdk-dev**: Tools for building with the Claude Agent SDK
* **plugin-dev**: Toolkit for creating your own plugins
### Output styles
Customize how Claude responds:
* **explanatory-output-style**: Educational insights about implementation choices
* **learning-output-style**: Interactive learning mode for skill building
## Try it: add the demo marketplace
Anthropic also maintains a [demo plugins marketplace](https://github.com/anthropics/claude-code/tree/main/plugins) (`claude-code-plugins`) with example plugins that show what's possible with the plugin system. Unlike the official marketplace, you need to add this one manually.
From within Claude Code, run the `plugin marketplace add` command for the `anthropics/claude-code` marketplace:
```shell theme={null}
/plugin marketplace add anthropics/claude-code
```
This downloads the marketplace catalog and makes its plugins available to you.
Run `/plugin` to open the plugin manager. This opens a tabbed interface with four tabs you can cycle through using **Tab** (or **Shift+Tab** to go backward):
* **Discover**: browse available plugins from all your marketplaces
* **Installed**: view and manage your installed plugins
* **Marketplaces**: add, remove, or update your added marketplaces
* **Errors**: view any plugin loading errors
Go to the **Discover** tab to see plugins from the marketplace you just added.
Select a plugin to view its details, then choose an installation scope:
* **User scope**: install for yourself across all projects
* **Project scope**: install for all collaborators on this repository
* **Local scope**: install for yourself in this repository only
For example, select **commit-commands** (a plugin that adds git workflow skills) and install it to your user scope.
You can also install directly from the command line:
```shell theme={null}
/plugin install commit-commands@anthropics-claude-code
```
See [Configuration scopes](/en/settings#configuration-scopes) to learn more about scopes.
After installing, run `/reload-plugins` to activate the plugin. Plugin skills are namespaced by the plugin name, so **commit-commands** provides skills like `/commit-commands:commit`.
Try it out by making a change to a file and running:
```shell theme={null}
/commit-commands:commit
```
This stages your changes, generates a commit message, and creates the commit.
Each plugin works differently. Check the plugin's description in the **Discover** tab or its homepage to learn what skills and capabilities it provides.
The rest of this guide covers all the ways you can add marketplaces, install plugins, and manage your configuration.
## Add marketplaces
Use the `/plugin marketplace add` command to add marketplaces from different sources.
**Shortcuts**: You can use `/plugin market` instead of `/plugin marketplace`, and `rm` instead of `remove`.
* **GitHub repositories**: `owner/repo` format (for example, `anthropics/claude-code`)
* **Git URLs**: any git repository URL (GitLab, Bitbucket, self-hosted)
* **Local paths**: directories or direct paths to `marketplace.json` files
* **Remote URLs**: direct URLs to hosted `marketplace.json` files
### Add from GitHub
Add a GitHub repository that contains a `.claude-plugin/marketplace.json` file using the `owner/repo` format—where `owner` is the GitHub username or organization and `repo` is the repository name.
For example, `anthropics/claude-code` refers to the `claude-code` repository owned by `anthropics`:
```shell theme={null}
/plugin marketplace add anthropics/claude-code
```
### Add from other Git hosts
Add any git repository by providing the full URL. This works with any Git host, including GitLab, Bitbucket, and self-hosted servers:
Using HTTPS:
```shell theme={null}
/plugin marketplace add https://gitlab.com/company/plugins.git
```
Using SSH:
```shell theme={null}
/plugin marketplace add git@gitlab.com:company/plugins.git
```
To add a specific branch or tag, append `#` followed by the ref:
```shell theme={null}
/plugin marketplace add https://gitlab.com/company/plugins.git#v1.0.0
```
### Add from local paths
Add a local directory that contains a `.claude-plugin/marketplace.json` file:
```shell theme={null}
/plugin marketplace add ./my-marketplace
```
You can also add a direct path to a `marketplace.json` file:
```shell theme={null}
/plugin marketplace add ./path/to/marketplace.json
```
### Add from remote URLs
Add a remote `marketplace.json` file via URL:
```shell theme={null}
/plugin marketplace add https://example.com/marketplace.json
```
URL-based marketplaces have some limitations compared to Git-based marketplaces. If you encounter "path not found" errors when installing plugins, see [Troubleshooting](/en/plugin-marketplaces#plugins-with-relative-paths-fail-in-url-based-marketplaces).
## Install plugins
Once you've added marketplaces, you can install plugins directly (installs to user scope by default):
```shell theme={null}
/plugin install plugin-name@marketplace-name
```
To choose a different [installation scope](/en/settings#configuration-scopes), use the interactive UI: run `/plugin`, go to the **Discover** tab, and press **Enter** on a plugin. You'll see options for:
* **User scope** (default): install for yourself across all projects
* **Project scope**: install for all collaborators on this repository (adds to `.claude/settings.json`)
* **Local scope**: install for yourself in this repository only (not shared with collaborators)
You may also see plugins with **managed** scope—these are installed by administrators via [managed settings](/en/settings#settings-files) and cannot be modified.
Make sure you trust a plugin before installing it. Anthropic does not control what MCP servers, files, or other software are included in plugins and cannot verify that they work as intended. Check each plugin's homepage for more information.
## Manage installed plugins
Run `/plugin` and go to the **Installed** tab to view, enable, disable, or uninstall your plugins. The list is grouped by scope and sorted so you see problems first: plugins with load errors or unresolved dependencies appear at the top, followed by your favorites, with disabled plugins folded behind a collapsed header at the bottom.
From the list you can:
* press `f` to favorite or unfavorite the selected plugin
* type to filter by plugin name or description
* press Enter to open a plugin's detail view and enable, disable, or uninstall it
When you install a plugin that declares dependencies, the install output lists which dependencies were auto-installed alongside it.
You can also manage plugins with direct commands.
Disable a plugin without uninstalling:
```shell theme={null}
/plugin disable plugin-name@marketplace-name
```
Re-enable a disabled plugin:
```shell theme={null}
/plugin enable plugin-name@marketplace-name
```
Completely remove a plugin:
```shell theme={null}
/plugin uninstall plugin-name@marketplace-name
```
The `--scope` option lets you target a specific scope with CLI commands:
```shell theme={null}
claude plugin install formatter@your-org --scope project
claude plugin uninstall formatter@your-org --scope project
```
### Apply plugin changes without restarting
When you install, enable, or disable plugins during a session, run `/reload-plugins` to pick up all changes without restarting:
```shell theme={null}
/reload-plugins
```
Claude Code reloads all active plugins and shows counts for plugins, skills, agents, hooks, plugin MCP servers, and plugin LSP servers.
## Manage marketplaces
You can manage marketplaces through the interactive `/plugin` interface or with CLI commands.
### Use the interactive interface
Run `/plugin` and go to the **Marketplaces** tab to:
* View all your added marketplaces with their sources and status
* Add new marketplaces
* Update marketplace listings to fetch the latest plugins
* Remove marketplaces you no longer need
### Use CLI commands
You can also manage marketplaces with direct commands.
List all configured marketplaces:
```shell theme={null}
/plugin marketplace list
```
Refresh plugin listings from a marketplace:
```shell theme={null}
/plugin marketplace update marketplace-name
```
Remove a marketplace:
```shell theme={null}
/plugin marketplace remove marketplace-name
```
Removing a marketplace will uninstall any plugins you installed from it.
### Configure auto-updates
Claude Code can automatically update marketplaces and their installed plugins at startup. When auto-update is enabled for a marketplace, Claude Code refreshes the marketplace data and updates installed plugins to their latest versions. If any plugins were updated, you'll see a notification prompting you to run `/reload-plugins`.
Toggle auto-update for individual marketplaces through the UI:
1. Run `/plugin` to open the plugin manager
2. Select **Marketplaces**
3. Choose a marketplace from the list
4. Select **Enable auto-update** or **Disable auto-update**
Official Anthropic marketplaces have auto-update enabled by default. Third-party and local development marketplaces have auto-update disabled by default.
To disable all automatic updates entirely for both Claude Code and all plugins, set the `DISABLE_AUTOUPDATER` environment variable. See [Auto updates](/en/setup#auto-updates) for details.
To keep plugin auto-updates enabled while disabling Claude Code auto-updates, set `FORCE_AUTOUPDATE_PLUGINS=1` along with `DISABLE_AUTOUPDATER`:
```bash theme={null}
export DISABLE_AUTOUPDATER=1
export FORCE_AUTOUPDATE_PLUGINS=1
```
This is useful when you want to manage Claude Code updates manually but still receive automatic plugin updates.
## Configure team marketplaces
Team admins can set up automatic marketplace installation for projects by adding marketplace configuration to `.claude/settings.json`. When team members trust the repository folder, Claude Code prompts them to install these marketplaces and plugins.
Add `extraKnownMarketplaces` to your project's `.claude/settings.json`:
```json theme={null}
{
"extraKnownMarketplaces": {
"my-team-tools": {
"source": {
"source": "github",
"repo": "your-org/claude-plugins"
}
}
}
}
```
For full configuration options including `extraKnownMarketplaces` and `enabledPlugins`, see [Plugin settings](/en/settings#plugin-settings).
## Security
Plugins and marketplaces are highly trusted components that can execute arbitrary code on your machine with your user privileges. Only install plugins and add marketplaces from sources you trust. Organizations can restrict which marketplaces users are allowed to add using [managed marketplace restrictions](/en/plugin-marketplaces#managed-marketplace-restrictions).
## Troubleshooting
### /plugin command not recognized
If you see "unknown command" or the `/plugin` command doesn't appear:
1. **Check your version**: Run `claude --version` to see what's installed.
2. **Update Claude Code**:
* **Homebrew**: `brew upgrade claude-code` (or `brew upgrade claude-code@latest` if you installed that cask)
* **npm**: `npm update -g @anthropic-ai/claude-code`
* **Native installer**: Re-run the install command from [Setup](../01-Getting-Started/advanced-setup-claude-code-docs-0526bc1300.md)
3. **Restart Claude Code**: After updating, restart your terminal and run `claude` again.
### Common issues
* **Marketplace not loading**: Verify the URL is accessible and that `.claude-plugin/marketplace.json` exists at the path
* **Plugin installation failures**: Check that plugin source URLs are accessible and repositories are public (or you have access)
* **Files not found after installation**: Plugins are copied to a cache, so paths referencing files outside the plugin directory won't work
* **Plugin skills not appearing**: Clear the cache with `rm -rf ~/.claude/plugins/cache`, restart Claude Code, and reinstall the plugin.
For detailed troubleshooting with solutions, see [Troubleshooting](/en/plugin-marketplaces#troubleshooting) in the marketplace guide. For debugging tools, see [Debugging and development tools](/en/plugins-reference#debugging-and-development-tools).
### Code intelligence issues
* **Language server not starting**: verify the binary is installed and available in your `$PATH`. Check the `/plugin` Errors tab for details.
* **High memory usage**: language servers like `rust-analyzer` and `pyright` can consume significant memory on large projects. If you experience memory issues, disable the plugin with `/plugin disable ` and rely on Claude's built-in search tools instead.
* **False positive diagnostics in monorepos**: language servers may report unresolved import errors for internal packages if the workspace isn't configured correctly. These don't affect Claude's ability to edit code.
## Next steps
* **Build your own plugins**: See [Plugins](../08-Plugins-Skills/create-plugins-claude-code-docs.md) to create skills, agents, and hooks
* **Create a marketplace**: See [Create a plugin marketplace](../08-Plugins-Skills/create-and-distribute-a-plugin-marketplace-claude-code-docs-34a8f3c5e8.md) to distribute plugins to your team or community
* **Technical reference**: See [Plugins reference](../08-Plugins-Skills/plugins-reference-44aeea7968.md) for complete specifications
---
## enterprise-deployment-overview-claude-code-docs-6eae0ecba2.md
# Enterprise deployment overview
Learn how Claude Code can integrate with various third-party services and infrastructure to meet enterprise deployment requirements.
> ## Documentation Index
>
> Fetch the complete documentation index at:
>
> Use this file to discover all available pages before exploring further.
Organizations can deploy Claude Code through Anthropic directly or through a cloud provider. This page helps you choose the right configuration.
Compare deployment options
For most organizations, Claude for Teams or Claude for Enterprise provides the best experience. Team members get access to both Claude Code and Claude on the web with a single subscription, centralized billing, and no infrastructure setup required. **Claude for Teams** is self-service and includes collaboration features, admin tools, and billing management. Best for smaller teams that need to get started quickly. **Claude for Enterprise** adds SSO and domain capture, role-based permissions, compliance API access, and managed policy settings for deploying organization-wide Claude Code configurations. Best for larger organizations with security and compliance requirements. Learn more about [Team plans](../17-Billing-Plans/what-is-the-team-plan.md) and [Enterprise plans](../17-Billing-Plans/what-is-the-enterprise-plan.md). If your organization has specific infrastructure requirements, compare the options below:
[TABLE]
Select a deployment option to view setup instructions:
- [Claude for Teams or Enterprise](/docs/en/authentication#claude-for-teams-or-enterprise)
- [Anthropic Console](/docs/en/authentication#claude-console-authentication)
- [Amazon Bedrock](/docs/en/amazon-bedrock)
- [Claude Platform on AWS](/docs/en/claude-platform-on-aws)
- [Google Vertex AI](/docs/en/google-vertex-ai)
- [Microsoft Foundry](/docs/en/microsoft-foundry)
Configure proxies and gateways
Most organizations can use a cloud provider directly without additional configuration. However, you may need to configure a corporate proxy or LLM gateway if your organization has specific network or management requirements. These are different configurations that can be used together:
- **Corporate proxy**: Routes traffic through an HTTP/HTTPS proxy. Use this if your organization requires all outbound traffic to pass through a proxy server for security monitoring, compliance, or network policy enforcement. Configure with the `HTTPS_PROXY` or `HTTP_PROXY` environment variables. Learn more in [Enterprise network configuration](/docs/en/network-config).
- **LLM Gateway**: A service that sits between Claude Code and the cloud provider to handle authentication and routing. Use this if you need centralized usage tracking across teams, custom rate limiting or budgets, or centralized authentication management. Configure with the `ANTHROPIC_BASE_URL`, `ANTHROPIC_BEDROCK_BASE_URL`, `ANTHROPIC_AWS_BASE_URL`, or `ANTHROPIC_VERTEX_BASE_URL` environment variables. Learn more in [LLM gateway configuration](/docs/en/llm-gateway).
The following examples show the environment variables to set in your shell or shell profile (`.bashrc`, `.zshrc`). See [Settings](/docs/en/settings) for other configuration methods.
Amazon Bedrock
- Corporate proxy
- LLM Gateway
Route Bedrock traffic through your corporate proxy by setting the following [environment variables](/docs/en/env-vars):
```python
# Enable Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
# Configure corporate proxy
export HTTPS_PROXY='https://proxy.example.com:8080'
```
Route Bedrock traffic through your LLM gateway by setting the following [environment variables](/docs/en/env-vars):
```python
# Enable Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
# Configure LLM gateway
export ANTHROPIC_BEDROCK_BASE_URL='https://your-llm-gateway.com/bedrock'
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1 # If gateway handles AWS auth
```
Microsoft Foundry
- Corporate proxy
- LLM Gateway
Route Foundry traffic through your corporate proxy by setting the following [environment variables](/docs/en/env-vars):
```python
# Enable Microsoft Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_RESOURCE=your-resource
export ANTHROPIC_FOUNDRY_API_KEY=your-api-key # Or omit for Entra ID auth
# Configure corporate proxy
export HTTPS_PROXY='https://proxy.example.com:8080'
```
Route Foundry traffic through your LLM gateway by setting the following [environment variables](/docs/en/env-vars):
```python
# Enable Microsoft Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
# Configure LLM gateway
export ANTHROPIC_FOUNDRY_BASE_URL='https://your-llm-gateway.com'
export CLAUDE_CODE_SKIP_FOUNDRY_AUTH=1 # If gateway handles Azure auth
```
Google Vertex AI
- Corporate proxy
- LLM Gateway
Route Vertex AI traffic through your corporate proxy by setting the following [environment variables](/docs/en/env-vars):
```python
# Enable Vertex
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=your-project-id
# Configure corporate proxy
export HTTPS_PROXY='https://proxy.example.com:8080'
```
Route Vertex AI traffic through your LLM gateway by setting the following [environment variables](/docs/en/env-vars):
```python
# Enable Vertex
export CLAUDE_CODE_USE_VERTEX=1
# Configure LLM gateway
export ANTHROPIC_VERTEX_BASE_URL='https://your-llm-gateway.com/vertex'
export CLAUDE_CODE_SKIP_VERTEX_AUTH=1 # If gateway handles GCP auth
```
Use `/status` in Claude Code to verify your proxy and gateway configuration is applied correctly.
Best practices for organizations
Invest in documentation and memory
We strongly recommend investing in documentation so that Claude Code understands your codebase. Organizations can deploy CLAUDE.md files at multiple levels:
- **Organization-wide**: Deploy to system directories like `/Library/Application Support/ClaudeCode/CLAUDE.md` (macOS) for company-wide standards
- **Repository-level**: Create `CLAUDE.md` files in repository roots containing project architecture, build commands, and contribution guidelines. Check these into source control so all users benefit
Learn more in [Memory and CLAUDE.md files](/docs/en/memory).
Simplify deployment
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.
Start with guided usage
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.
Pin model versions for cloud providers
If you deploy through [Bedrock](/docs/en/amazon-bedrock), [Vertex AI](/docs/en/google-vertex-ai), [Foundry](/docs/en/microsoft-foundry), or [Claude Platform on AWS](/docs/en/claude-platform-on-aws), pin specific model versions using `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL`. Without pinning, model aliases resolve to the latest version, which may not yet be enabled in your account when Anthropic releases an update. Pinning lets you control when your users move to a new model. See [Model configuration](/docs/en/model-config#pin-models-for-third-party-deployments) for what each provider does when the latest version is unavailable.
Configure security policies
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](/docs/en/security).
Leverage MCP for integrations
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](/docs/en/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.
Next steps
Once you’ve chosen a deployment option and configured access for your team:
1. **Roll out to your team**: Share installation instructions and have team members [install Claude Code](/docs/en/setup) and authenticate with their credentials.
2. **Set up shared configuration**: Create a [CLAUDE.md file](/docs/en/memory) in your repositories to help Claude Code understand your codebase and coding standards.
3. **Configure permissions**: Review [security settings](/docs/en/security) to define what Claude Code can and cannot do in your environment.
---
## enterprise-network-configuration-claude-code-docs-5c48e6754e.md
# Enterprise network configuration
Configure Claude Code for enterprise environments with proxy servers, custom Certificate Authorities (CA), and mutual Transport Layer Security (mTLS) authentication.
> ## Documentation Index
>
> Fetch the complete documentation index at:
>
> Use this file to discover all available pages before exploring further.
Claude Code supports various enterprise network and security configurations through environment variables. This includes routing traffic through corporate proxy servers, trusting custom Certificate Authorities (CA), and authenticating with mutual Transport Layer Security (mTLS) certificates for enhanced security.
All environment variables shown on this page can also be configured in [`settings.json`](/docs/en/settings).
Proxy configuration
Environment variables
Claude Code respects standard proxy environment variables:
```python
# HTTPS proxy (recommended)
export HTTPS_PROXY=https://proxy.example.com:8080
# HTTP proxy (if HTTPS not available)
export HTTP_PROXY=http://proxy.example.com:8080
# Bypass proxy for specific requests - space-separated format
export NO_PROXY="localhost 192.168.1.1 example.com .example.com"
# Bypass proxy for specific requests - comma-separated format
export NO_PROXY="localhost,192.168.1.1,example.com,.example.com"
# Bypass proxy for all requests
export NO_PROXY="*"
```
Claude Code does not support SOCKS proxies.
Basic authentication
If your proxy requires basic authentication, include credentials in the proxy URL:
```python
export HTTPS_PROXY=http://username:password@proxy.example.com:8080
```
Avoid hardcoding passwords in scripts. Use environment variables or secure credential storage instead.
For proxies requiring advanced authentication (NTLM, Kerberos, etc.), consider using an LLM Gateway service that supports your authentication method.
CA certificate store
By default, Claude Code trusts both its bundled Mozilla CA certificates and your operating system’s certificate store. Enterprise TLS-inspection proxies such as CrowdStrike Falcon and Zscaler work without additional configuration when their root certificate is installed in the OS trust store. `CLAUDE_CODE_CERT_STORE` accepts a comma-separated list of sources. Recognized values are `bundled` for the Mozilla CA set shipped with Claude Code and `system` for the operating system trust store. The default is `bundled,system`. To trust only the bundled Mozilla CA set:
```python
export CLAUDE_CODE_CERT_STORE=bundled
```
To trust only the OS certificate store:
```python
export CLAUDE_CODE_CERT_STORE=system
```
`CLAUDE_CODE_CERT_STORE` has no dedicated `settings.json` schema key. Set it via the `env` block in `~/.claude/settings.json` or directly in the process environment.
Custom CA certificates
If your enterprise environment uses a custom CA, configure Claude Code to trust it directly:
```python
export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem
```
mTLS authentication
For enterprise environments requiring client certificate authentication:
```python
# Client certificate for authentication
export CLAUDE_CODE_CLIENT_CERT=/path/to/client-cert.pem
# Client private key
export CLAUDE_CODE_CLIENT_KEY=/path/to/client-key.pem
# Optional: Passphrase for encrypted private key
export CLAUDE_CODE_CLIENT_KEY_PASSPHRASE="your-passphrase"
```
Network access requirements
Claude Code requires access to the following URLs. Allowlist these in your proxy configuration and firewall rules, especially in containerized or restricted network environments.
| URL | Required for |
|--------------------------------|----------------------------------------------------------------------------------------------------------------------------------------|
| `api.anthropic.com` | Claude API requests |
| `claude.ai` | claude.ai account authentication |
| `platform.claude.com` | Anthropic Console account authentication |
| `downloads.claude.ai` | Plugin executable downloads; native installer and native auto-updater |
| `storage.googleapis.com` | Native installer and native auto-updater on versions prior to 2.1.116 |
| `bridge.claudeusercontent.com` | [Claude in Chrome](/docs/en/chrome) extension WebSocket bridge |
| `raw.githubusercontent.com` | Changelog feed for [`/release-notes`](/docs/en/commands) and the release notes shown after updating; plugin marketplace install counts |
If you install Claude Code through npm or manage your own binary distribution, end users may not need access to `downloads.claude.ai` or `storage.googleapis.com`. Claude Code also sends optional operational telemetry by default, which you can disable with environment variables. See [Telemetry services](/docs/en/data-usage#telemetry-services) for how to disable it before finalizing your allowlist. When using [Amazon Bedrock](/docs/en/amazon-bedrock), [Google Vertex AI](/docs/en/google-vertex-ai), or [Microsoft Foundry](/docs/en/microsoft-foundry), model traffic and authentication go to your provider instead of `api.anthropic.com`, `claude.ai`, or `platform.claude.com`. The WebFetch tool still calls `api.anthropic.com` for its [domain safety check](/docs/en/data-usage#webfetch-domain-safety-check) unless you set `skipWebFetchPreflight: true` in [settings](/docs/en/settings). [Claude Code on the web](/docs/en/claude-code-on-the-web) and [Code Review](/docs/en/code-review) connect to your repositories from Anthropic-managed infrastructure. If your GitHub Enterprise Cloud organization restricts access by IP address, enable [IP allow list inheritance for installed GitHub Apps](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization#allowing-access-by-github-apps). The Claude GitHub App registers its IP ranges, so enabling this setting allows access without manual configuration. To [add the ranges to your allow list manually](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization#adding-an-allowed-ip-address) instead, or to configure other firewalls, see the [Anthropic API IP addresses](../04-API-Reference/Other/api-ip-addresses-cc3c763ed7.md). For self-hosted [GitHub Enterprise Server](/docs/en/github-enterprise-server) instances behind a firewall, allowlist the same [Anthropic API IP addresses](../04-API-Reference/Other/api-ip-addresses-cc3c763ed7.md) so Anthropic infrastructure can reach your GHES host to clone repositories and post review comments.
Additional resources
- [Claude Code settings](/docs/en/settings)
- [Environment variables reference](/docs/en/env-vars)
- [Troubleshooting guide](/docs/en/troubleshooting)
---
## enterprise-network-configuration-claude-code-docs.md
# Enterprise network configuration
Configure Claude Code for enterprise environments with proxy servers, custom Certificate Authorities (CA), and mutual Transport Layer Security (mTLS) authentication.
Claude Code supports various enterprise network and security configurations through environment variables. This includes routing traffic through corporate proxy servers, trusting custom Certificate Authorities (CA), and authenticating with mutual Transport Layer Security (mTLS) certificates for enhanced security.
All environment variables shown on this page can also be configured in [`settings.json`](settings.md).
Proxy configuration
Environment variables
Claude Code respects standard proxy environment variables:
```python
# HTTPS proxy (recommended)
export HTTPS_PROXY=https://proxy.example.com:8080
# HTTP proxy (if HTTPS not available)
export HTTP_PROXY=http://proxy.example.com:8080
# Bypass proxy for specific requests - space-separated format
export NO_PROXY="localhost 192.168.1.1 example.com .example.com"
# Bypass proxy for specific requests - comma-separated format
export NO_PROXY="localhost,192.168.1.1,example.com,.example.com"
# Bypass proxy for all requests
export NO_PROXY="*"
```
Claude Code does not support SOCKS proxies.
Basic authentication
If your proxy requires basic authentication, include credentials in the proxy URL:
```python
export HTTPS_PROXY=http://username:password@proxy.example.com:8080
```
Avoid hardcoding passwords in scripts. Use environment variables or secure credential storage instead.
For proxies requiring advanced authentication (NTLM, Kerberos, etc.), consider using an LLM Gateway service that supports your authentication method.
CA certificate store
By default, Claude Code trusts both its bundled Mozilla CA certificates and your operating system’s certificate store. Enterprise TLS-inspection proxies such as CrowdStrike Falcon and Zscaler work without additional configuration when their root certificate is installed in the OS trust store.
System CA store integration requires the native Claude Code binary distribution. When running on the Node.js runtime, the system CA store is not merged automatically. In that case, set `NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem` to trust an enterprise root CA.
`CLAUDE_CODE_CERT_STORE` accepts a comma-separated list of sources. Recognized values are `bundled` for the Mozilla CA set shipped with Claude Code and `system` for the operating system trust store. The default is `bundled,system`. To trust only the bundled Mozilla CA set:
```python
export CLAUDE_CODE_CERT_STORE=bundled
```
To trust only the OS certificate store:
```python
export CLAUDE_CODE_CERT_STORE=system
```
`CLAUDE_CODE_CERT_STORE` has no dedicated `settings.json` schema key. Set it via the `env` block in `~/.claude/settings.json` or directly in the process environment.
Custom CA certificates
If your enterprise environment uses a custom CA, configure Claude Code to trust it directly:
```python
export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem
```
mTLS authentication
For enterprise environments requiring client certificate authentication:
```python
# Client certificate for authentication
export CLAUDE_CODE_CLIENT_CERT=/path/to/client-cert.pem
# Client private key
export CLAUDE_CODE_CLIENT_KEY=/path/to/client-key.pem
# Optional: Passphrase for encrypted private key
export CLAUDE_CODE_CLIENT_KEY_PASSPHRASE="your-passphrase"
```
Network access requirements
Claude Code requires access to the following URLs. Allowlist these in your proxy configuration and firewall rules, especially in containerized or restricted network environments.
| URL | Required for |
|----|----|
| `api.anthropic.com` | Claude API requests |
| `claude.ai` | claude.ai account authentication |
| `platform.claude.com` | Anthropic Console account authentication |
| `downloads.claude.ai` | Plugin executable downloads; native installer and native auto-updater |
| `storage.googleapis.com` | Native installer and native auto-updater on versions prior to 2.1.116 |
| `bridge.claudeusercontent.com` | [Claude in Chrome](/docs/en/chrome) extension WebSocket bridge |
If you install Claude Code through npm or manage your own binary distribution, end users may not need access to `downloads.claude.ai` or `storage.googleapis.com`. When using [Amazon Bedrock](/docs/en/amazon-bedrock), [Google Vertex AI](/docs/en/google-vertex-ai), or [Microsoft Foundry](/docs/en/microsoft-foundry), model traffic and authentication go to your provider instead of `api.anthropic.com`, `claude.ai`, or `platform.claude.com`. The WebFetch tool still calls `api.anthropic.com` for its [domain safety check](/docs/en/data-usage#webfetch-domain-safety-check) unless you set `skipWebFetchPreflight: true` in [settings](/docs/en/settings). [Claude Code on the web](/docs/en/claude-code-on-the-web) and [Code Review](/docs/en/code-review) connect to your repositories from Anthropic-managed infrastructure. If your GitHub Enterprise Cloud organization restricts access by IP address, enable [IP allow list inheritance for installed GitHub Apps](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization#allowing-access-by-github-apps). The Claude GitHub App registers its IP ranges, so enabling this setting allows access without manual configuration. To [add the ranges to your allow list manually](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization#adding-an-allowed-ip-address) instead, or to configure other firewalls, see the [Anthropic API IP addresses](../04-API-Reference/Other/api-ip-addresses-cc3c763ed7.md). For self-hosted [GitHub Enterprise Server](/docs/en/github-enterprise-server) instances behind a firewall, allowlist the same [Anthropic API IP addresses](../04-API-Reference/Other/api-ip-addresses-cc3c763ed7.md) so Anthropic infrastructure can reach your GHES host to clone repositories and post review comments.
Additional resources
- [Claude Code settings](/docs/en/settings)
- [Environment variables reference](/docs/en/env-vars)
- [Troubleshooting guide](troubleshooting.md)
---
*Truncated: 107 more documents not shown (size limit)*
Explore the context window
A simulated session showing what enters context and what it costs
~{fmt(totalTokens)}tokens
/ {fmt(MAX)} · illustrative
{blocks.map((b, i) => {
const w = Math.max(b.tokens / MAX * 100, 0.15);
const isHov = b.visIdx === activeIdx;
const catMatch = hovCat && b.color === hovCat;
const dimmed = hovCat ? !catMatch : activeIdx !== null && !isHov;
return
{}
setHovIdx(b.visIdx)} onMouseLeave={() => setHovIdx(null)} onClick={() => setSelIdx(selIdx === b.visIdx ? null : b.visIdx)} style={{
width: w + '%',
height: '100%',
background: b.color,
opacity: isHov || catMatch ? 1 : dimmed ? 0.25 : 0.65,
borderRight: i < blocks.length - 1 ? '0.5px solid var(--cw-border)' : 'none',
transition: 'opacity 0.15s',
cursor: 'pointer'
}} />;
})}
{LEGEND.map(x => {
const active = hovCat === x.c;
return
setHovCat(x.c)} onMouseLeave={() => setHovCat(null)} style={{
display: 'flex',
alignItems: 'center',
gap: 4,
padding: '2px 6px',
borderRadius: 4,
cursor: 'pointer',
background: active ? 'var(--cw-hover)' : 'transparent',
transition: 'background 0.1s'
}}>
{x.l}
;
})}
= appears in your terminal
{}
{}
{visible.length === 0 && !playing &&
}
{isCompacted &&
}
{time > 0 && visible.length > 0 &&
}
{activeGate && activeGate.kind === 'compact' &&
}
{}
$
claude
Watch what loads into context, from the moment you run
claude through a full conversation.
After /compact
{fmt(preCompactTotal)} → {fmt(totalTokens)} tokens · freed {fmt(preCompactTotal - totalTokens)}
This is what's left in context: startup content, which lives outside the message history and reloads after compaction, plus a structured summary of the entire conversation. Skill descriptions don't reload.
{isCompacted ? 'Reloaded after compact' : 'Before you type anything'}
}
{time > 0 && visible.map((evt, i) => {
const meta = KIND_META[evt.kind];
const isHov = hovIdx === i;
const prevKind = i > 0 ? visible[i - 1].kind : null;
const isSub = evt.kind === 'sub';
const enteringSubagent = isSub && prevKind !== 'sub';
const leavingSubagent = prevKind === 'sub' && !isSub;
let showPhase = null;
if (evt.kind === 'user' && prevKind !== 'user') showPhase = 'You'; else if (evt.kind === 'claude' && prevKind === 'user') showPhase = 'Claude works'; else if (evt.label === 'Conversation summary') showPhase = 'Summarized by /compact';
const isNewRow = isCompacted && !(evt.kind === 'auto' && evt.t < STARTUP_END);
return
{showPhase &&
;
})}
{activeGate && (activeGate.kind === 'prompt' || activeGate.kind === 'bang' || activeGate.kind === 'slash') &&
{showPhase}
}
{enteringSubagent &&
Subagent's separate context window
}
{leavingSubagent &&
↓ {fmt(subTotal)} tokens stayed in subagent's context · only the summary returns
}
setHovIdx(i)} onMouseLeave={() => setHovIdx(null)} onClick={() => setSelIdx(selIdx === i ? null : i)} style={{
display: 'flex',
alignItems: 'flex-start',
borderRadius: 6,
cursor: 'pointer',
background: selIdx === i || isHov ? 'var(--cw-hover)' : 'transparent',
outline: selIdx === i ? '1px solid rgba(217,119,87,0.4)' : 'none',
opacity: hovCat && evt.color !== hovCat ? 0.35 : 1,
transition: 'background 0.1s, opacity 0.15s',
marginLeft: isSub ? 28 : 0,
paddingLeft: isSub ? 10 : 0,
borderLeft: isSub ? '2px solid rgba(155,123,196,0.4)' : 'none'
}}>
{i < visible.length - 1 && }
{meta.badge}
{evt.label}
{evt.tokens > 0 &&
+{fmt(evt.tokens)}
}
{evt.subTokens > 0 &&
+{fmt(evt.subTokens)}
}
{evt.tokens > 0 &&
}
{evt.vis !== 'hidden' && }
You type in your terminal
❯
{activeGate.text}
Context is at {fmt(totalTokens)} tokens.
Run
/compact to
summarize older exchanges and free space for more work.
❯
{activeGate.text}
{hovEvent ?
{hovEvent.tip &&
}
{hovEvent.link &&
Learn more →
}
:
}
{hovEvent.label}
{KIND_META[hovEvent.kind].detail}
{hovEvent.tokens > 0 &&
{fmt(hovEvent.tokens)} tokens
}
{hovEvent.subTokens > 0 &&
{fmt(hovEvent.subTokens)} tokens in the subagent's context
}
{renderWithCode(hovEvent.desc)}
{hovEvent.vis === 'full' ? '●' : hovEvent.vis === 'brief' ? '◐' : '○'}
{VIS_META[hovEvent.vis].label}
{VIS_META[hovEvent.vis].sub}
💡 Save context
{renderWithCode(hovEvent.tip)}
👁
Hover or click any event
Hover to preview. Click to pin so you can scroll.
Key takeaway
{takeaway}
In your terminal you see
{terminalView}
Claude Code runs locally. To interact with the LLM, Claude Code sends data over the network. This data includes all user prompts and model outputs, encrypted in transit via TLS 1.2+. Claude Code is compatible with most popular VPNs and LLM proxies.
Encryption at rest depends on your model provider:
| Provider | Encryption at rest |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Anthropic API | Infrastructure-level disk encryption (AES-256). Enable [Zero Data Retention](../22-Safety-Policy/zero-data-retention-claude-code-docs-6ec9ee63f1.md) for no server-side persistence. |
| Amazon Bedrock | AES-256 with AWS-managed keys. Customer-managed keys available via AWS KMS. |
| Google Cloud Vertex AI | Google-managed encryption keys. CMEK available. |
| Microsoft Foundry | Requests route to Anthropic infrastructure with AES-256 disk encryption. |
Claude Code is built on Anthropic's APIs. For details on API security controls, including API logging procedures, see the compliance artifacts in the [Anthropic Trust Center](https://trust.anthropic.com).
### Cloud execution: Data flow and dependencies
When using [Claude Code on the web](claude-code-on-the-web-69d53821d4.md), sessions run in Anthropic-managed virtual machines instead of locally. In cloud environments:
* **Code and data storage:** Your repository is cloned to an isolated VM. Code and session data are subject to the retention and usage policies for your account type (see Data retention section above)
* **Credentials:** GitHub authentication is handled through a secure proxy; your GitHub credentials never enter the sandbox
* **Network traffic:** All outbound traffic goes through a security proxy for audit logging and abuse prevention
* **Session data:** Prompts, code changes, and outputs follow the same data policies as local Claude Code usage
For security details about cloud execution, see [Security](/en/security#cloud-execution-security).
## Telemetry services
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 `/feedback` command, a copy of their full conversation history including code is sent to Anthropic. The data is encrypted in transit via TLS. Optionally, a GitHub issue is created in the public repository. To opt out, set the `DISABLE_FEEDBACK_COMMAND` environment variable to `1`.
## Default behaviors by API provider
By default, error reporting, telemetry, and bug reporting are disabled when using Bedrock, Vertex, or Foundry. Session quality surveys and the WebFetch domain safety check are exceptions and run regardless of provider. You can opt out of all non-essential traffic, including surveys, at once by setting `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`. This variable does not affect the WebFetch check, which has its own opt-out. Here are the full default behaviors:
| Service | Claude API | Vertex API | Bedrock API | Foundry 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. | Default off.
`CLAUDE_CODE_USE_FOUNDRY` 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. | Default off.
`CLAUDE_CODE_USE_FOUNDRY` must be 1. | | **Claude API (`/feedback` reports)** | Default on.
`DISABLE_FEEDBACK_COMMAND=1` to disable. | Default off.
`CLAUDE_CODE_USE_VERTEX` must be 1. | Default off.
`CLAUDE_CODE_USE_BEDROCK` must be 1. | Default off.
`CLAUDE_CODE_USE_FOUNDRY` must be 1. | | **Session quality surveys** | Default on.
`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1` to disable. | Default on.
`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1` to disable. | Default on.
`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1` to disable. | Default on.
`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1` to disable. | | **WebFetch domain safety check** | Default on.
`skipWebFetchPreflight: true` in [settings](claude-code-settings-claude-code-docs-d4420b4b52.md) to disable. | Default on.
`skipWebFetchPreflight: true` in [settings](claude-code-settings-claude-code-docs-d4420b4b52.md) to disable. | Default on.
`skipWebFetchPreflight: true` in [settings](claude-code-settings-claude-code-docs-d4420b4b52.md) to disable. | Default on.
`skipWebFetchPreflight: true` in [settings](claude-code-settings-claude-code-docs-d4420b4b52.md) to disable. | All environment variables can be checked into `settings.json` (see [settings reference](claude-code-settings-claude-code-docs-d4420b4b52.md)). ### WebFetch domain safety check Before fetching a URL, the WebFetch tool sends the requested hostname to `api.anthropic.com` to check it against a safety blocklist maintained by Anthropic. Only the hostname is sent, not the full URL, path, or page contents. Results are cached per hostname for five minutes. This check runs regardless of which model provider you use and is not affected by `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`. If your network blocks `api.anthropic.com`, WebFetch requests fail until you either allowlist the domain or set `skipWebFetchPreflight: true` in [settings](claude-code-settings-claude-code-docs-d4420b4b52.md). Disabling the check means WebFetch attempts to retrieve any URL without consulting the blocklist, so combine it with [`WebFetch` permission rules](/en/permissions#webfetch) if you need to restrict which domains Claude can reach. --- ## debug-your-config-615fc7cc73.md > ## Documentation Index > Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Debug your configuration > Diagnose why CLAUDE.md, settings, hooks, MCP servers, or skills aren't taking effect. Use /context, /doctor, /hooks, and /mcp to see what actually loaded. When Claude ignores an instruction or a feature you configured doesn't appear, the cause is usually that the file didn't load, it loaded from a different location than you expected, or another file overrode it. This guide shows how to inspect what Claude Code actually loaded so you can narrow down which applies. For installation, authentication, and connectivity problems, see [Troubleshooting](../21-Account-Support/troubleshooting-claude-code-docs-3f3657ed0f.md) instead. ## See what loaded into context The `/context` command shows everything occupying the context window for the current session, broken down by category: system prompt, memory files, skills, MCP tools, and conversation messages. Run it first to confirm whether your `CLAUDE.md`, rules, or skill descriptions are present at all. For detail on a specific category, follow up with the dedicated command: | Command | Shows | | :------------- | :-------------------------------------------------------------------------- | | `/memory` | Which `CLAUDE.md` and rules files loaded, plus auto-memory entries | | `/skills` | Available skills from project, user, and plugin sources | | `/agents` | Configured subagents and their settings | | `/hooks` | Active hook configurations | | `/mcp` | Connected MCP servers and their status | | `/permissions` | Resolved allow and deny rules currently in effect | | `/doctor` | Configuration diagnostics: invalid keys, schema errors, installation health | | `/status` | Active settings sources, including whether managed settings are in effect | If a memory file is missing from `/memory`, check its location against [how CLAUDE.md files load](/en/memory#how-claude-md-files-load). Subdirectory `CLAUDE.md` files load on demand when Claude reads a file in that directory with the Read tool, not at session start. If `/memory` confirms the file loaded but Claude still isn't following a particular instruction, the issue is likely how the instruction is written rather than whether it loaded. CLAUDE.md works well for the kinds of guidance you'd give a new teammate, such as project conventions, build commands, and where files belong. Adherence drops when an instruction is vague enough to interpret multiple ways, when two files give conflicting direction, or when the file has grown long enough that individual rules get less attention. [Write effective instructions](/en/memory#write-effective-instructions) covers the specificity, size, and structure patterns that keep adherence high.