@tkpdx01/ccc 1.2.7 → 1.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/Claude Code settings.txt +776 -776
- package/README.md +77 -0
- package/index.js +4 -2
- package/package.json +40 -39
- package/src/commands/delete.js +66 -66
- package/src/commands/edit.js +120 -120
- package/src/commands/help.js +61 -50
- package/src/commands/import.js +356 -356
- package/src/commands/index.js +11 -10
- package/src/commands/list.js +46 -46
- package/src/commands/new.js +109 -109
- package/src/commands/show.js +68 -68
- package/src/commands/sync.js +93 -93
- package/src/commands/use.js +19 -19
- package/src/commands/webdav.js +477 -0
- package/src/config.js +9 -9
- package/src/crypto.js +147 -0
- package/src/launch.js +69 -69
- package/src/parsers.js +154 -154
- package/src/profiles.js +182 -182
- package/src/utils.js +67 -67
- package/src/webdav.js +268 -0
- package/.claude/settings.local.json +0 -34
- package/nul +0 -1
package/Claude Code settings.txt
CHANGED
|
@@ -1,777 +1,777 @@
|
|
|
1
|
-
# Claude Code settings
|
|
2
|
-
|
|
3
|
-
> Configure Claude Code with global and project-level settings, and environment variables.
|
|
4
|
-
|
|
5
|
-
Claude Code offers a variety of settings to configure its behavior to meet your needs. You can configure Claude Code by running the `/config` command when using the interactive REPL, which opens a tabbed Settings interface where you can view status information and modify configuration options.
|
|
6
|
-
|
|
7
|
-
## Settings files
|
|
8
|
-
|
|
9
|
-
The `settings.json` file is our official mechanism for configuring Claude
|
|
10
|
-
Code through hierarchical settings:
|
|
11
|
-
|
|
12
|
-
* **User settings** are defined in `~/.claude/settings.json` and apply to all
|
|
13
|
-
projects.
|
|
14
|
-
* **Project settings** are saved in your project directory:
|
|
15
|
-
* `.claude/settings.json` for settings that are checked into source control and shared with your team
|
|
16
|
-
* `.claude/settings.local.json` for settings that are not checked in, useful for personal preferences and experimentation. Claude Code will configure git to ignore `.claude/settings.local.json` when it is created.
|
|
17
|
-
* **Managed settings** (Enterprise): Enterprise administrators can configure and distribute Claude Code settings to their organization through the [Claude.ai admin console](https://claude.ai/admin-settings/claude-code). These settings are fetched automatically when users authenticate, take precedence over user and project settings, and cannot be overridden locally. This feature is available to Claude for Enterprise customers. If you don't see this option in your admin console, contact your Anthropic account team to have the feature enabled.
|
|
18
|
-
|
|
19
|
-
For organizations that prefer file-based policy distribution, Claude Code also supports `managed-settings.json` and `managed-mcp.json` files that can be deployed to system directories:
|
|
20
|
-
|
|
21
|
-
* macOS: `/Library/Application Support/ClaudeCode/`
|
|
22
|
-
* Linux and WSL: `/etc/claude-code/`
|
|
23
|
-
* Windows: `C:\Program Files\ClaudeCode\`
|
|
24
|
-
|
|
25
|
-
<Note>
|
|
26
|
-
These are system-wide paths (not user home directories like `~/Library/...`) that require administrator privileges. They are designed to be deployed by IT administrators.
|
|
27
|
-
</Note>
|
|
28
|
-
|
|
29
|
-
See [Enterprise managed settings](/en/iam#enterprise-managed-settings) and [Enterprise MCP configuration](/en/mcp#enterprise-mcp-configuration) for details.
|
|
30
|
-
|
|
31
|
-
<Note>
|
|
32
|
-
Enterprise deployments can also restrict **plugin marketplace additions** using
|
|
33
|
-
`strictKnownMarketplaces`. For more information, see [Enterprise marketplace restrictions](/en/plugin-marketplaces#enterprise-marketplace-restrictions).
|
|
34
|
-
</Note>
|
|
35
|
-
* **Other configuration** is stored in `~/.claude.json`. This file contains your preferences (theme, notification settings, editor mode), OAuth session, [MCP server](/en/mcp) configurations for user and local scopes, per-project state (allowed tools, trust settings), and various caches. Project-scoped MCP servers are stored separately in `.mcp.json`.
|
|
36
|
-
|
|
37
|
-
```JSON Example settings.json theme={null}
|
|
38
|
-
{
|
|
39
|
-
"permissions": {
|
|
40
|
-
"allow": [
|
|
41
|
-
"Bash(npm run lint)",
|
|
42
|
-
"Bash(npm run test:*)",
|
|
43
|
-
"Read(~/.zshrc)"
|
|
44
|
-
],
|
|
45
|
-
"deny": [
|
|
46
|
-
"Bash(curl:*)",
|
|
47
|
-
"Read(./.env)",
|
|
48
|
-
"Read(./.env.*)",
|
|
49
|
-
"Read(./secrets/**)"
|
|
50
|
-
]
|
|
51
|
-
},
|
|
52
|
-
"env": {
|
|
53
|
-
"CLAUDE_CODE_ENABLE_TELEMETRY": "1",
|
|
54
|
-
"OTEL_METRICS_EXPORTER": "otlp"
|
|
55
|
-
},
|
|
56
|
-
"companyAnnouncements": [
|
|
57
|
-
"Welcome to Acme Corp! Review our code guidelines at docs.acme.com",
|
|
58
|
-
"Reminder: Code reviews required for all PRs",
|
|
59
|
-
"New security policy in effect"
|
|
60
|
-
]
|
|
61
|
-
}
|
|
62
|
-
```
|
|
63
|
-
|
|
64
|
-
### Available settings
|
|
65
|
-
|
|
66
|
-
`settings.json` supports a number of options:
|
|
67
|
-
|
|
68
|
-
| Key | Description | Example |
|
|
69
|
-
| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------- |
|
|
70
|
-
| `apiKeyHelper` | Custom script, to be executed in `/bin/sh`, to generate an auth value. This value will be sent as `X-Api-Key` and `Authorization: Bearer` headers for model requests | `/bin/generate_temp_api_key.sh` |
|
|
71
|
-
| `cleanupPeriodDays` | Sessions inactive for longer than this period are deleted at startup. Setting to `0` immediately deletes all sessions. (default: 30 days) | `20` |
|
|
72
|
-
| `companyAnnouncements` | Announcement to display to users at startup. If multiple announcements are provided, they will be cycled through at random. | `["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"]` |
|
|
73
|
-
| `env` | Environment variables that will be applied to every session | `{"FOO": "bar"}` |
|
|
74
|
-
| `attribution` | Customize attribution for git commits and pull requests. See [Attribution settings](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |
|
|
75
|
-
| `includeCoAuthoredBy` | **Deprecated**: Use `attribution` instead. Whether to include the `co-authored-by Claude` byline in git commits and pull requests (default: `true`) | `false` |
|
|
76
|
-
| `permissions` | See table below for structure of permissions. | |
|
|
77
|
-
| `hooks` | Configure custom commands to run before or after tool executions. See [hooks documentation](/en/hooks) | `{"PreToolUse": {"Bash": "echo 'Running command...'"}}` |
|
|
78
|
-
| `disableAllHooks` | Disable all [hooks](/en/hooks) | `true` |
|
|
79
|
-
| `allowManagedHooksOnly` | (Enterprise) Prevent loading of user, project, and plugin hooks. Only allows managed hooks and SDK hooks. See [Hook configuration](#hook-configuration) | `true` |
|
|
80
|
-
| `model` | Override the default model to use for Claude Code | `"claude-sonnet-4-5-20250929"` |
|
|
81
|
-
| `otelHeadersHelper` | Script to generate dynamic OpenTelemetry headers. Runs at startup and periodically (see [Dynamic headers](/en/monitoring-usage#dynamic-headers)) | `/bin/generate_otel_headers.sh` |
|
|
82
|
-
| `statusLine` | Configure a custom status line to display context. See [`statusLine` documentation](/en/statusline) | `{"type": "command", "command": "~/.claude/statusline.sh"}` |
|
|
83
|
-
| `fileSuggestion` | Configure a custom script for `@` file autocomplete. See [File suggestion settings](#file-suggestion-settings) | `{"type": "command", "command": "~/.claude/file-suggestion.sh"}` |
|
|
84
|
-
| `outputStyle` | Configure an output style to adjust the system prompt. See [output styles documentation](/en/output-styles) | `"Explanatory"` |
|
|
85
|
-
| `forceLoginMethod` | Use `claudeai` to restrict login to Claude.ai accounts, `console` to restrict login to Claude Console (API usage billing) accounts | `claudeai` |
|
|
86
|
-
| `forceLoginOrgUUID` | Specify the UUID of an organization to automatically select it during login, bypassing the organization selection step. Requires `forceLoginMethod` to be set | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` |
|
|
87
|
-
| `enableAllProjectMcpServers` | Automatically approve all MCP servers defined in project `.mcp.json` files | `true` |
|
|
88
|
-
| `enabledMcpjsonServers` | List of specific MCP servers from `.mcp.json` files to approve | `["memory", "github"]` |
|
|
89
|
-
| `disabledMcpjsonServers` | List of specific MCP servers from `.mcp.json` files to reject | `["filesystem"]` |
|
|
90
|
-
| `allowedMcpServers` | When set in managed-settings.json, allowlist of MCP servers users can configure. Undefined = no restrictions, empty array = lockdown. Applies to all scopes. Denylist takes precedence. See [Enterprise MCP configuration](/en/mcp#enterprise-mcp-configuration) | `[{ "serverName": "github" }]` |
|
|
91
|
-
| `deniedMcpServers` | When set in managed-settings.json, denylist of MCP servers that are explicitly blocked. Applies to all scopes including enterprise servers. Denylist takes precedence over allowlist. See [Enterprise MCP configuration](/en/mcp#enterprise-mcp-configuration) | `[{ "serverName": "filesystem" }]` |
|
|
92
|
-
| `strictKnownMarketplaces` | When set in managed-settings.json, allowlist of plugin marketplaces users can add. Undefined = no restrictions, empty array = lockdown. Applies to marketplace additions only. See [Enterprise marketplace restrictions](/en/plugin-marketplaces#enterprise-marketplace-restrictions) | `[{ "source": "github", "repo": "company/plugins" }]` |
|
|
93
|
-
| `awsAuthRefresh` | Custom script that modifies the `.aws` directory (see [advanced credential configuration](/en/amazon-bedrock#advanced-credential-configuration)) | `aws sso login --profile myprofile` |
|
|
94
|
-
| `awsCredentialExport` | Custom script that outputs JSON with AWS credentials (see [advanced credential configuration](/en/amazon-bedrock#advanced-credential-configuration)) | `/bin/generate_aws_grant.sh` |
|
|
95
|
-
| `alwaysThinkingEnabled` | Enable [extended thinking](/en/common-workflows#use-extended-thinking) by default for all sessions. Typically configured via the `/config` command rather than editing directly | `true` |
|
|
96
|
-
|
|
97
|
-
### Permission settings
|
|
98
|
-
|
|
99
|
-
| Keys | Description | Example |
|
|
100
|
-
| :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------- |
|
|
101
|
-
| `allow` | Array of [permission rules](/en/iam#configuring-permissions) to allow tool use. **Note:** Bash rules use prefix matching, not regex | `[ "Bash(git diff:*)" ]` |
|
|
102
|
-
| `ask` | Array of [permission rules](/en/iam#configuring-permissions) to ask for confirmation upon tool use. | `[ "Bash(git push:*)" ]` |
|
|
103
|
-
| `deny` | Array of [permission rules](/en/iam#configuring-permissions) to deny tool use. Use this to also exclude sensitive files from Claude Code access. **Note:** Bash patterns are prefix matches and can be bypassed (see [Bash permission limitations](/en/iam#tool-specific-permission-rules)) | `[ "WebFetch", "Bash(curl:*)", "Read(./.env)", "Read(./secrets/**)" ]` |
|
|
104
|
-
| `additionalDirectories` | Additional [working directories](/en/iam#working-directories) that Claude has access to | `[ "../docs/" ]` |
|
|
105
|
-
| `defaultMode` | Default [permission mode](/en/iam#permission-modes) when opening Claude Code | `"acceptEdits"` |
|
|
106
|
-
| `disableBypassPermissionsMode` | Set to `"disable"` to prevent `bypassPermissions` mode from being activated. This disables the `--dangerously-skip-permissions` command-line flag. See [managed settings](/en/iam#enterprise-managed-settings) | `"disable"` |
|
|
107
|
-
|
|
108
|
-
### Sandbox settings
|
|
109
|
-
|
|
110
|
-
Configure advanced sandboxing behavior. Sandboxing isolates bash commands from your filesystem and network. See [Sandboxing](/en/sandboxing) for details.
|
|
111
|
-
|
|
112
|
-
**Filesystem and network restrictions** are configured via Read, Edit, and WebFetch permission rules, not via these sandbox settings.
|
|
113
|
-
|
|
114
|
-
| Keys | Description | Example |
|
|
115
|
-
| :-------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------ |
|
|
116
|
-
| `enabled` | Enable bash sandboxing (macOS/Linux only). Default: false | `true` |
|
|
117
|
-
| `autoAllowBashIfSandboxed` | Auto-approve bash commands when sandboxed. Default: true | `true` |
|
|
118
|
-
| `excludedCommands` | Commands that should run outside of the sandbox | `["git", "docker"]` |
|
|
119
|
-
| `allowUnsandboxedCommands` | Allow commands to run outside the sandbox via the `dangerouslyDisableSandbox` parameter. When set to `false`, the `dangerouslyDisableSandbox` escape hatch is completely disabled and all commands must run sandboxed (or be in `excludedCommands`). Useful for enterprise policies that require strict sandboxing. Default: true | `false` |
|
|
120
|
-
| `network.allowUnixSockets` | Unix socket paths accessible in sandbox (for SSH agents, etc.) | `["~/.ssh/agent-socket"]` |
|
|
121
|
-
| `network.allowLocalBinding` | Allow binding to localhost ports (macOS only). Default: false | `true` |
|
|
122
|
-
| `network.httpProxyPort` | HTTP proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. | `8080` |
|
|
123
|
-
| `network.socksProxyPort` | SOCKS5 proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. | `8081` |
|
|
124
|
-
| `enableWeakerNestedSandbox` | Enable weaker sandbox for unprivileged Docker environments (Linux only). **Reduces security.** Default: false | `true` |
|
|
125
|
-
|
|
126
|
-
**Configuration example:**
|
|
127
|
-
|
|
128
|
-
```json theme={null}
|
|
129
|
-
{
|
|
130
|
-
"sandbox": {
|
|
131
|
-
"enabled": true,
|
|
132
|
-
"autoAllowBashIfSandboxed": true,
|
|
133
|
-
"excludedCommands": ["docker"],
|
|
134
|
-
"network": {
|
|
135
|
-
"allowUnixSockets": [
|
|
136
|
-
"/var/run/docker.sock"
|
|
137
|
-
],
|
|
138
|
-
"allowLocalBinding": true
|
|
139
|
-
}
|
|
140
|
-
},
|
|
141
|
-
"permissions": {
|
|
142
|
-
"deny": [
|
|
143
|
-
"Read(.envrc)",
|
|
144
|
-
"Read(~/.aws/**)"
|
|
145
|
-
]
|
|
146
|
-
}
|
|
147
|
-
}
|
|
148
|
-
```
|
|
149
|
-
|
|
150
|
-
**Filesystem and network restrictions** use standard permission rules:
|
|
151
|
-
|
|
152
|
-
* Use `Read` deny rules to block Claude from reading specific files or directories
|
|
153
|
-
* Use `Edit` allow rules to let Claude write to directories beyond the current working directory
|
|
154
|
-
* Use `Edit` deny rules to block writes to specific paths
|
|
155
|
-
* Use `WebFetch` allow/deny rules to control which network domains Claude can access
|
|
156
|
-
|
|
157
|
-
### Attribution settings
|
|
158
|
-
|
|
159
|
-
Claude Code adds attribution to git commits and pull requests. These are configured separately:
|
|
160
|
-
|
|
161
|
-
* Commits use [git trailers](https://git-scm.com/docs/git-interpret-trailers) (like `Co-Authored-By`) by default, which can be customized or disabled
|
|
162
|
-
* Pull request descriptions are plain text
|
|
163
|
-
|
|
164
|
-
| Keys | Description |
|
|
165
|
-
| :------- | :----------------------------------------------------------------------------------------- |
|
|
166
|
-
| `commit` | Attribution for git commits, including any trailers. Empty string hides commit attribution |
|
|
167
|
-
| `pr` | Attribution for pull request descriptions. Empty string hides pull request attribution |
|
|
168
|
-
|
|
169
|
-
**Default commit attribution:**
|
|
170
|
-
|
|
171
|
-
```
|
|
172
|
-
🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
|
173
|
-
|
|
174
|
-
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
|
|
175
|
-
```
|
|
176
|
-
|
|
177
|
-
**Default pull request attribution:**
|
|
178
|
-
|
|
179
|
-
```
|
|
180
|
-
🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
|
181
|
-
```
|
|
182
|
-
|
|
183
|
-
**Example:**
|
|
184
|
-
|
|
185
|
-
```json theme={null}
|
|
186
|
-
{
|
|
187
|
-
"attribution": {
|
|
188
|
-
"commit": "Generated with AI\n\nCo-Authored-By: AI <ai@example.com>",
|
|
189
|
-
"pr": ""
|
|
190
|
-
}
|
|
191
|
-
}
|
|
192
|
-
```
|
|
193
|
-
|
|
194
|
-
<Note>
|
|
195
|
-
The `attribution` setting takes precedence over the deprecated `includeCoAuthoredBy` setting. To hide all attribution, set `commit` and `pr` to empty strings.
|
|
196
|
-
</Note>
|
|
197
|
-
|
|
198
|
-
### File suggestion settings
|
|
199
|
-
|
|
200
|
-
Configure a custom command for `@` file path autocomplete. The built-in file suggestion uses fast filesystem traversal, but large monorepos may benefit from project-specific indexing such as a pre-built file index or custom tooling.
|
|
201
|
-
|
|
202
|
-
```json theme={null}
|
|
203
|
-
{
|
|
204
|
-
"fileSuggestion": {
|
|
205
|
-
"type": "command",
|
|
206
|
-
"command": "~/.claude/file-suggestion.sh"
|
|
207
|
-
}
|
|
208
|
-
}
|
|
209
|
-
```
|
|
210
|
-
|
|
211
|
-
The command runs with the same environment variables as [hooks](/en/hooks), including `CLAUDE_PROJECT_DIR`. It receives JSON via stdin with a `query` field:
|
|
212
|
-
|
|
213
|
-
```json theme={null}
|
|
214
|
-
{"query": "src/comp"}
|
|
215
|
-
```
|
|
216
|
-
|
|
217
|
-
Output newline-separated file paths to stdout (currently limited to 15):
|
|
218
|
-
|
|
219
|
-
```
|
|
220
|
-
src/components/Button.tsx
|
|
221
|
-
src/components/Modal.tsx
|
|
222
|
-
src/components/Form.tsx
|
|
223
|
-
```
|
|
224
|
-
|
|
225
|
-
**Example:**
|
|
226
|
-
|
|
227
|
-
```bash theme={null}
|
|
228
|
-
#!/bin/bash
|
|
229
|
-
query=$(cat | jq -r '.query')
|
|
230
|
-
your-repo-file-index --query "$query" | head -20
|
|
231
|
-
```
|
|
232
|
-
|
|
233
|
-
### Hook configuration
|
|
234
|
-
|
|
235
|
-
**Enterprise-only setting**: Controls which hooks are allowed to run. This setting can only be configured in [managed settings](#settings-files) and provides enterprise administrators with strict control over hook execution.
|
|
236
|
-
|
|
237
|
-
**Behavior when `allowManagedHooksOnly` is `true`:**
|
|
238
|
-
|
|
239
|
-
* Managed hooks and SDK hooks are loaded
|
|
240
|
-
* User hooks, project hooks, and plugin hooks are blocked
|
|
241
|
-
|
|
242
|
-
**Configuration:**
|
|
243
|
-
|
|
244
|
-
```json theme={null}
|
|
245
|
-
{
|
|
246
|
-
"allowManagedHooksOnly": true
|
|
247
|
-
}
|
|
248
|
-
```
|
|
249
|
-
|
|
250
|
-
### Settings precedence
|
|
251
|
-
|
|
252
|
-
Settings apply in order of precedence. From highest to lowest:
|
|
253
|
-
|
|
254
|
-
1. **Managed settings** (Enterprise)
|
|
255
|
-
* Remote settings configured via the [Claude.ai admin console](https://claude.ai/admin-settings/claude-code)
|
|
256
|
-
* Fetched automatically when users authenticate
|
|
257
|
-
* Cannot be overridden
|
|
258
|
-
|
|
259
|
-
2. **File-based managed settings** (`managed-settings.json`)
|
|
260
|
-
* Policies deployed by IT/DevOps to system directories
|
|
261
|
-
* Cannot be overridden by user or project settings
|
|
262
|
-
* Ignored when remote managed settings are configured
|
|
263
|
-
|
|
264
|
-
3. **Command line arguments**
|
|
265
|
-
* Temporary overrides for a specific session
|
|
266
|
-
|
|
267
|
-
4. **Local project settings** (`.claude/settings.local.json`)
|
|
268
|
-
* Personal project-specific settings
|
|
269
|
-
|
|
270
|
-
5. **Shared project settings** (`.claude/settings.json`)
|
|
271
|
-
* Team-shared project settings in source control
|
|
272
|
-
|
|
273
|
-
6. **User settings** (`~/.claude/settings.json`)
|
|
274
|
-
* Personal global settings
|
|
275
|
-
|
|
276
|
-
This hierarchy ensures that enterprise security policies are always enforced while still allowing teams and individuals to customize their experience.
|
|
277
|
-
|
|
278
|
-
For example, if your user settings allow `Bash(npm run:*)` but a project's shared settings deny it, the project setting takes precedence and the command is blocked.
|
|
279
|
-
|
|
280
|
-
### Key points about the configuration system
|
|
281
|
-
|
|
282
|
-
* **Memory files (`CLAUDE.md`)**: Contain instructions and context that Claude loads at startup
|
|
283
|
-
* **Settings files (JSON)**: Configure permissions, environment variables, and tool behavior
|
|
284
|
-
* **Slash commands**: Custom commands that can be invoked during a session with `/command-name`
|
|
285
|
-
* **MCP servers**: Extend Claude Code with additional tools and integrations
|
|
286
|
-
* **Precedence**: Higher-level configurations (Enterprise) override lower-level ones (User/Project)
|
|
287
|
-
* **Inheritance**: Settings are merged, with more specific settings adding to or overriding broader ones
|
|
288
|
-
|
|
289
|
-
### System prompt
|
|
290
|
-
|
|
291
|
-
Claude Code's internal system prompt is not published. To add custom instructions, use `CLAUDE.md` files or the `--append-system-prompt` flag.
|
|
292
|
-
|
|
293
|
-
### Excluding sensitive files
|
|
294
|
-
|
|
295
|
-
To prevent Claude Code from accessing files containing sensitive information like API keys, secrets, and environment files, use the `permissions.deny` setting in your `.claude/settings.json` file:
|
|
296
|
-
|
|
297
|
-
```json theme={null}
|
|
298
|
-
{
|
|
299
|
-
"permissions": {
|
|
300
|
-
"deny": [
|
|
301
|
-
"Read(./.env)",
|
|
302
|
-
"Read(./.env.*)",
|
|
303
|
-
"Read(./secrets/**)",
|
|
304
|
-
"Read(./config/credentials.json)",
|
|
305
|
-
"Read(./build)"
|
|
306
|
-
]
|
|
307
|
-
}
|
|
308
|
-
}
|
|
309
|
-
```
|
|
310
|
-
|
|
311
|
-
This replaces the deprecated `ignorePatterns` configuration. Files matching these patterns will be completely invisible to Claude Code, preventing any accidental exposure of sensitive data.
|
|
312
|
-
|
|
313
|
-
## Subagent configuration
|
|
314
|
-
|
|
315
|
-
Claude Code supports custom AI subagents that can be configured at both user and project levels. These subagents are stored as Markdown files with YAML frontmatter:
|
|
316
|
-
|
|
317
|
-
* **User subagents**: `~/.claude/agents/` - Available across all your projects
|
|
318
|
-
* **Project subagents**: `.claude/agents/` - Specific to your project and can be shared with your team
|
|
319
|
-
|
|
320
|
-
Subagent files define specialized AI assistants with custom prompts and tool permissions. Learn more about creating and using subagents in the [subagents documentation](/en/sub-agents).
|
|
321
|
-
|
|
322
|
-
## Plugin configuration
|
|
323
|
-
|
|
324
|
-
Claude Code supports a plugin system that lets you extend functionality with custom commands, agents, hooks, and MCP servers. Plugins are distributed through marketplaces and can be configured at both user and repository levels.
|
|
325
|
-
|
|
326
|
-
### Plugin settings
|
|
327
|
-
|
|
328
|
-
Plugin-related settings in `settings.json`:
|
|
329
|
-
|
|
330
|
-
```json theme={null}
|
|
331
|
-
{
|
|
332
|
-
"enabledPlugins": {
|
|
333
|
-
"formatter@company-tools": true,
|
|
334
|
-
"deployer@company-tools": true,
|
|
335
|
-
"analyzer@security-plugins": false
|
|
336
|
-
},
|
|
337
|
-
"extraKnownMarketplaces": {
|
|
338
|
-
"company-tools": {
|
|
339
|
-
"source": "github",
|
|
340
|
-
"repo": "company/claude-plugins"
|
|
341
|
-
}
|
|
342
|
-
}
|
|
343
|
-
}
|
|
344
|
-
```
|
|
345
|
-
|
|
346
|
-
#### `enabledPlugins`
|
|
347
|
-
|
|
348
|
-
Controls which plugins are enabled. Format: `"plugin-name@marketplace-name": true/false`
|
|
349
|
-
|
|
350
|
-
**Scopes**:
|
|
351
|
-
|
|
352
|
-
* **User settings** (`~/.claude/settings.json`): Personal plugin preferences
|
|
353
|
-
* **Project settings** (`.claude/settings.json`): Project-specific plugins shared with team
|
|
354
|
-
* **Local settings** (`.claude/settings.local.json`): Per-machine overrides (not committed)
|
|
355
|
-
|
|
356
|
-
**Example**:
|
|
357
|
-
|
|
358
|
-
```json theme={null}
|
|
359
|
-
{
|
|
360
|
-
"enabledPlugins": {
|
|
361
|
-
"code-formatter@team-tools": true,
|
|
362
|
-
"deployment-tools@team-tools": true,
|
|
363
|
-
"experimental-features@personal": false
|
|
364
|
-
}
|
|
365
|
-
}
|
|
366
|
-
```
|
|
367
|
-
|
|
368
|
-
#### `extraKnownMarketplaces`
|
|
369
|
-
|
|
370
|
-
Defines additional marketplaces that should be made available for the repository. Typically used in repository-level settings to ensure team members have access to required plugin sources.
|
|
371
|
-
|
|
372
|
-
**When a repository includes `extraKnownMarketplaces`**:
|
|
373
|
-
|
|
374
|
-
1. Team members are prompted to install the marketplace when they trust the folder
|
|
375
|
-
2. Team members are then prompted to install plugins from that marketplace
|
|
376
|
-
3. Users can skip unwanted marketplaces or plugins (stored in user settings)
|
|
377
|
-
4. Installation respects trust boundaries and requires explicit consent
|
|
378
|
-
|
|
379
|
-
**Example**:
|
|
380
|
-
|
|
381
|
-
```json theme={null}
|
|
382
|
-
{
|
|
383
|
-
"extraKnownMarketplaces": {
|
|
384
|
-
"company-tools": {
|
|
385
|
-
"source": {
|
|
386
|
-
"source": "github",
|
|
387
|
-
"repo": "company-org/claude-plugins"
|
|
388
|
-
}
|
|
389
|
-
},
|
|
390
|
-
"security-plugins": {
|
|
391
|
-
"source": {
|
|
392
|
-
"source": "git",
|
|
393
|
-
"url": "https://git.company.com/security/plugins.git"
|
|
394
|
-
}
|
|
395
|
-
}
|
|
396
|
-
}
|
|
397
|
-
}
|
|
398
|
-
```
|
|
399
|
-
|
|
400
|
-
**Marketplace source types**:
|
|
401
|
-
|
|
402
|
-
* `github`: GitHub repository (uses `repo`)
|
|
403
|
-
* `git`: Any git URL (uses `url`)
|
|
404
|
-
* `directory`: Local filesystem path (uses `path`, for development only)
|
|
405
|
-
|
|
406
|
-
#### `strictKnownMarketplaces`
|
|
407
|
-
|
|
408
|
-
**Enterprise-only setting**: Controls which plugin marketplaces users are allowed to add. This setting can only be configured in `managed-settings.json` and provides enterprise administrators with strict control over marketplace sources.
|
|
409
|
-
|
|
410
|
-
**Managed settings file locations**:
|
|
411
|
-
|
|
412
|
-
* **macOS**: `/Library/Application Support/ClaudeCode/managed-settings.json`
|
|
413
|
-
* **Linux and WSL**: `/etc/claude-code/managed-settings.json`
|
|
414
|
-
* **Windows**: `C:\ProgramData\ClaudeCode\managed-settings.json`
|
|
415
|
-
|
|
416
|
-
**Key characteristics**:
|
|
417
|
-
|
|
418
|
-
* Only available in enterprise managed settings (`managed-settings.json`)
|
|
419
|
-
* Cannot be overridden by user or project settings (highest precedence)
|
|
420
|
-
* Enforced BEFORE network/filesystem operations (blocked sources never execute)
|
|
421
|
-
* Uses exact matching for source specifications (including `ref`, `path` for git sources)
|
|
422
|
-
|
|
423
|
-
**Allowlist behavior**:
|
|
424
|
-
|
|
425
|
-
* `undefined` (default): No restrictions - users can add any marketplace
|
|
426
|
-
* Empty array `[]`: Complete lockdown - users cannot add any new marketplaces
|
|
427
|
-
* List of sources: Users can only add marketplaces that match exactly
|
|
428
|
-
|
|
429
|
-
**All supported source types**:
|
|
430
|
-
|
|
431
|
-
The allowlist supports six marketplace source types. Each source must match exactly for a user's marketplace addition to be allowed.
|
|
432
|
-
|
|
433
|
-
1. **GitHub repositories**:
|
|
434
|
-
|
|
435
|
-
```json theme={null}
|
|
436
|
-
{ "source": "github", "repo": "company/approved-plugins" }
|
|
437
|
-
{ "source": "github", "repo": "company/security-tools", "ref": "v2.0" }
|
|
438
|
-
{ "source": "github", "repo": "team/plugins", "ref": "main", "path": "marketplace" }
|
|
439
|
-
```
|
|
440
|
-
|
|
441
|
-
Fields: `repo` (required), `ref` (optional: branch/tag/SHA), `path` (optional: subdirectory)
|
|
442
|
-
|
|
443
|
-
2. **Git repositories**:
|
|
444
|
-
|
|
445
|
-
```json theme={null}
|
|
446
|
-
{ "source": "git", "url": "https://gitlab.company.com/tools/plugins.git" }
|
|
447
|
-
{ "source": "git", "url": "https://bitbucket.org/company/plugins.git", "ref": "production" }
|
|
448
|
-
{ "source": "git", "url": "ssh://git@internal.company.com/plugins.git", "ref": "v3.1", "path": "approved" }
|
|
449
|
-
```
|
|
450
|
-
|
|
451
|
-
Fields: `url` (required), `ref` (optional: branch/tag/SHA), `path` (optional: subdirectory)
|
|
452
|
-
|
|
453
|
-
3. **URL-based marketplaces**:
|
|
454
|
-
|
|
455
|
-
```json theme={null}
|
|
456
|
-
{ "source": "url", "url": "https://internal.company.com/plugins/marketplace.json" }
|
|
457
|
-
{ "source": "url", "url": "https://cdn.company.com/marketplace.json", "headers": { "Authorization": "Bearer ${TOKEN}" } }
|
|
458
|
-
```
|
|
459
|
-
|
|
460
|
-
Fields: `url` (required), `headers` (optional: HTTP headers for authenticated access)
|
|
461
|
-
|
|
462
|
-
4. **NPM packages**:
|
|
463
|
-
|
|
464
|
-
```json theme={null}
|
|
465
|
-
{ "source": "npm", "package": "@company/claude-plugins" }
|
|
466
|
-
{ "source": "npm", "package": "@company-internal/approved-marketplace" }
|
|
467
|
-
```
|
|
468
|
-
|
|
469
|
-
Fields: `package` (required, supports scoped packages)
|
|
470
|
-
|
|
471
|
-
5. **File paths**:
|
|
472
|
-
|
|
473
|
-
```json theme={null}
|
|
474
|
-
{ "source": "file", "path": "/usr/local/share/claude/company-marketplace.json" }
|
|
475
|
-
{ "source": "file", "path": "/opt/company/plugins/marketplace.json" }
|
|
476
|
-
```
|
|
477
|
-
|
|
478
|
-
Fields: `path` (required: absolute path to marketplace.json file)
|
|
479
|
-
|
|
480
|
-
6. **Directory paths**:
|
|
481
|
-
|
|
482
|
-
```json theme={null}
|
|
483
|
-
{ "source": "directory", "path": "/usr/local/share/claude/company-plugins" }
|
|
484
|
-
{ "source": "directory", "path": "/opt/company/approved-marketplaces" }
|
|
485
|
-
```
|
|
486
|
-
|
|
487
|
-
Fields: `path` (required: absolute path to directory containing `.claude-plugin/marketplace.json`)
|
|
488
|
-
|
|
489
|
-
**Configuration examples**:
|
|
490
|
-
|
|
491
|
-
Example - Allow specific marketplaces only:
|
|
492
|
-
|
|
493
|
-
```json theme={null}
|
|
494
|
-
{
|
|
495
|
-
"strictKnownMarketplaces": [
|
|
496
|
-
{
|
|
497
|
-
"source": "github",
|
|
498
|
-
"repo": "company/approved-plugins"
|
|
499
|
-
},
|
|
500
|
-
{
|
|
501
|
-
"source": "github",
|
|
502
|
-
"repo": "company/security-tools",
|
|
503
|
-
"ref": "v2.0"
|
|
504
|
-
},
|
|
505
|
-
{
|
|
506
|
-
"source": "url",
|
|
507
|
-
"url": "https://internal.company.com/plugins/marketplace.json"
|
|
508
|
-
},
|
|
509
|
-
{
|
|
510
|
-
"source": "npm",
|
|
511
|
-
"package": "@company/compliance-plugins"
|
|
512
|
-
}
|
|
513
|
-
]
|
|
514
|
-
}
|
|
515
|
-
```
|
|
516
|
-
|
|
517
|
-
Example - Disable all marketplace additions:
|
|
518
|
-
|
|
519
|
-
```json theme={null}
|
|
520
|
-
{
|
|
521
|
-
"strictKnownMarketplaces": []
|
|
522
|
-
}
|
|
523
|
-
```
|
|
524
|
-
|
|
525
|
-
**Exact matching requirements**:
|
|
526
|
-
|
|
527
|
-
Marketplace sources must match **exactly** for a user's addition to be allowed. For git-based sources (`github` and `git`), this includes all optional fields:
|
|
528
|
-
|
|
529
|
-
* The `repo` or `url` must match exactly
|
|
530
|
-
* The `ref` field must match exactly (or both be undefined)
|
|
531
|
-
* The `path` field must match exactly (or both be undefined)
|
|
532
|
-
|
|
533
|
-
Examples of sources that **do NOT match**:
|
|
534
|
-
|
|
535
|
-
```json theme={null}
|
|
536
|
-
// These are DIFFERENT sources:
|
|
537
|
-
{ "source": "github", "repo": "company/plugins" }
|
|
538
|
-
{ "source": "github", "repo": "company/plugins", "ref": "main" }
|
|
539
|
-
|
|
540
|
-
// These are also DIFFERENT:
|
|
541
|
-
{ "source": "github", "repo": "company/plugins", "path": "marketplace" }
|
|
542
|
-
{ "source": "github", "repo": "company/plugins" }
|
|
543
|
-
```
|
|
544
|
-
|
|
545
|
-
**Comparison with `extraKnownMarketplaces`**:
|
|
546
|
-
|
|
547
|
-
| Aspect | `strictKnownMarketplaces` | `extraKnownMarketplaces` |
|
|
548
|
-
| --------------------- | ------------------------------------ | ------------------------------------ |
|
|
549
|
-
| **Purpose** | Enterprise policy enforcement | Team convenience |
|
|
550
|
-
| **Settings file** | `managed-settings.json` only | Any settings file |
|
|
551
|
-
| **Behavior** | Blocks non-allowlisted additions | Auto-installs missing marketplaces |
|
|
552
|
-
| **When enforced** | Before network/filesystem operations | After user trust prompt |
|
|
553
|
-
| **Can be overridden** | No (highest precedence) | Yes (by higher precedence settings) |
|
|
554
|
-
| **Source format** | Direct source object | Named marketplace with nested source |
|
|
555
|
-
| **Use case** | Compliance, security restrictions | Onboarding, standardization |
|
|
556
|
-
|
|
557
|
-
**Format difference**:
|
|
558
|
-
|
|
559
|
-
`strictKnownMarketplaces` uses direct source objects:
|
|
560
|
-
|
|
561
|
-
```json theme={null}
|
|
562
|
-
{
|
|
563
|
-
"strictKnownMarketplaces": [
|
|
564
|
-
{ "source": "github", "repo": "company/plugins" }
|
|
565
|
-
]
|
|
566
|
-
}
|
|
567
|
-
```
|
|
568
|
-
|
|
569
|
-
`extraKnownMarketplaces` requires named marketplaces:
|
|
570
|
-
|
|
571
|
-
```json theme={null}
|
|
572
|
-
{
|
|
573
|
-
"extraKnownMarketplaces": {
|
|
574
|
-
"company-tools": {
|
|
575
|
-
"source": { "source": "github", "repo": "company/plugins" }
|
|
576
|
-
}
|
|
577
|
-
}
|
|
578
|
-
}
|
|
579
|
-
```
|
|
580
|
-
|
|
581
|
-
**Important notes**:
|
|
582
|
-
|
|
583
|
-
* Restrictions are checked BEFORE any network requests or filesystem operations
|
|
584
|
-
* When blocked, users see clear error messages indicating the source is blocked by enterprise policy
|
|
585
|
-
* The restriction applies only to adding NEW marketplaces; previously installed marketplaces remain accessible
|
|
586
|
-
* Enterprise managed settings have the highest precedence and cannot be overridden
|
|
587
|
-
|
|
588
|
-
See [Enterprise marketplace restrictions](/en/plugin-marketplaces#enterprise-marketplace-restrictions) for user-facing documentation.
|
|
589
|
-
|
|
590
|
-
### Managing plugins
|
|
591
|
-
|
|
592
|
-
Use the `/plugin` command to manage plugins interactively:
|
|
593
|
-
|
|
594
|
-
* Browse available plugins from marketplaces
|
|
595
|
-
* Install/uninstall plugins
|
|
596
|
-
* Enable/disable plugins
|
|
597
|
-
* View plugin details (commands, agents, hooks provided)
|
|
598
|
-
* Add/remove marketplaces
|
|
599
|
-
|
|
600
|
-
Learn more about the plugin system in the [plugins documentation](/en/plugins).
|
|
601
|
-
|
|
602
|
-
## Environment variables
|
|
603
|
-
|
|
604
|
-
Claude Code supports the following environment variables to control its behavior:
|
|
605
|
-
|
|
606
|
-
<Note>
|
|
607
|
-
All environment variables can also be configured in [`settings.json`](#available-settings). This is useful as a way to automatically set environment variables for each session, or to roll out a set of environment variables for your whole team or organization.
|
|
608
|
-
</Note>
|
|
609
|
-
|
|
610
|
-
| Variable | Purpose |
|
|
611
|
-
| :-------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
612
|
-
| `ANTHROPIC_API_KEY` | API key sent as `X-Api-Key` header, typically for the Claude SDK (for interactive usage, run `/login`) |
|
|
613
|
-
| `ANTHROPIC_AUTH_TOKEN` | Custom value for the `Authorization` header (the value you set here will be prefixed with `Bearer `) |
|
|
614
|
-
| `ANTHROPIC_CUSTOM_HEADERS` | Custom headers you want to add to the request (in `Name: Value` format) |
|
|
615
|
-
| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | See [Model configuration](/en/model-config#environment-variables) |
|
|
616
|
-
| `ANTHROPIC_DEFAULT_OPUS_MODEL` | See [Model configuration](/en/model-config#environment-variables) |
|
|
617
|
-
| `ANTHROPIC_DEFAULT_SONNET_MODEL` | See [Model configuration](/en/model-config#environment-variables) |
|
|
618
|
-
| `ANTHROPIC_FOUNDRY_API_KEY` | API key for Microsoft Foundry authentication (see [Microsoft Foundry](/en/microsoft-foundry)) |
|
|
619
|
-
| `ANTHROPIC_MODEL` | Name of the model setting to use (see [Model Configuration](/en/model-config#environment-variables)) |
|
|
620
|
-
| `ANTHROPIC_SMALL_FAST_MODEL` | \[DEPRECATED] Name of [Haiku-class model for background tasks](/en/costs) |
|
|
621
|
-
| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | Override AWS region for the Haiku-class model when using Bedrock |
|
|
622
|
-
| `AWS_BEARER_TOKEN_BEDROCK` | Bedrock API key for authentication (see [Bedrock API keys](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)) |
|
|
623
|
-
| `BASH_DEFAULT_TIMEOUT_MS` | Default timeout for long-running bash commands |
|
|
624
|
-
| `BASH_MAX_OUTPUT_LENGTH` | Maximum number of characters in bash outputs before they are middle-truncated |
|
|
625
|
-
| `BASH_MAX_TIMEOUT_MS` | Maximum timeout the model can set for long-running bash commands |
|
|
626
|
-
| `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR` | Return to the original working directory after each Bash command |
|
|
627
|
-
| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` | Interval in milliseconds at which credentials should be refreshed (when using `apiKeyHelper`) |
|
|
628
|
-
| `CLAUDE_CODE_CLIENT_CERT` | Path to client certificate file for mTLS authentication |
|
|
629
|
-
| `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE` | Passphrase for encrypted CLAUDE\_CODE\_CLIENT\_KEY (optional) |
|
|
630
|
-
| `CLAUDE_CODE_CLIENT_KEY` | Path to client private key file for mTLS authentication |
|
|
631
|
-
| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Set to `1` to disable Anthropic API-specific `anthropic-beta` headers. Use this if experiencing issues like "Unexpected value(s) for the `anthropic-beta` header" when using an LLM gateway with third-party providers |
|
|
632
|
-
| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | Equivalent of setting `DISABLE_AUTOUPDATER`, `DISABLE_BUG_COMMAND`, `DISABLE_ERROR_REPORTING`, and `DISABLE_TELEMETRY` |
|
|
633
|
-
| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | Set to `1` to disable automatic terminal title updates based on conversation context |
|
|
634
|
-
| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | Skip auto-installation of IDE extensions |
|
|
635
|
-
| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | Set the maximum number of output tokens for most requests |
|
|
636
|
-
| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | Interval for refreshing dynamic OpenTelemetry headers in milliseconds (default: 1740000 / 29 minutes). See [Dynamic headers](/en/monitoring-usage#dynamic-headers) |
|
|
637
|
-
| `CLAUDE_CODE_SHELL_PREFIX` | Command prefix to wrap all bash commands (for example, for logging or auditing). Example: `/path/to/logger.sh` will execute `/path/to/logger.sh <command>` |
|
|
638
|
-
| `CLAUDE_CODE_SKIP_BEDROCK_AUTH` | Skip AWS authentication for Bedrock (for example, when using an LLM gateway) |
|
|
639
|
-
| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | Skip Azure authentication for Microsoft Foundry (for example, when using an LLM gateway) |
|
|
640
|
-
| `CLAUDE_CODE_SKIP_VERTEX_AUTH` | Skip Google authentication for Vertex (for example, when using an LLM gateway) |
|
|
641
|
-
| `CLAUDE_CODE_SUBAGENT_MODEL` | See [Model configuration](/en/model-config) |
|
|
642
|
-
| `CLAUDE_CODE_USE_BEDROCK` | Use [Bedrock](/en/amazon-bedrock) |
|
|
643
|
-
| `CLAUDE_CODE_USE_FOUNDRY` | Use [Microsoft Foundry](/en/microsoft-foundry) |
|
|
644
|
-
| `CLAUDE_CODE_USE_VERTEX` | Use [Vertex](/en/google-vertex-ai) |
|
|
645
|
-
| `CLAUDE_CONFIG_DIR` | Customize where Claude Code stores its configuration and data files |
|
|
646
|
-
| `DISABLE_AUTOUPDATER` | Set to `1` to disable automatic updates. |
|
|
647
|
-
| `DISABLE_BUG_COMMAND` | Set to `1` to disable the `/bug` command |
|
|
648
|
-
| `DISABLE_COST_WARNINGS` | Set to `1` to disable cost warning messages |
|
|
649
|
-
| `DISABLE_ERROR_REPORTING` | Set to `1` to opt out of Sentry error reporting |
|
|
650
|
-
| `DISABLE_NON_ESSENTIAL_MODEL_CALLS` | Set to `1` to disable model calls for non-critical paths like flavor text |
|
|
651
|
-
| `DISABLE_PROMPT_CACHING` | Set to `1` to disable prompt caching for all models (takes precedence over per-model settings) |
|
|
652
|
-
| `DISABLE_PROMPT_CACHING_HAIKU` | Set to `1` to disable prompt caching for Haiku models |
|
|
653
|
-
| `DISABLE_PROMPT_CACHING_OPUS` | Set to `1` to disable prompt caching for Opus models |
|
|
654
|
-
| `DISABLE_PROMPT_CACHING_SONNET` | Set to `1` to disable prompt caching for Sonnet models |
|
|
655
|
-
| `DISABLE_TELEMETRY` | Set to `1` to opt out of Statsig telemetry (note that Statsig events do not include user data like code, file paths, or bash commands) |
|
|
656
|
-
| `HTTP_PROXY` | Specify HTTP proxy server for network connections |
|
|
657
|
-
| `HTTPS_PROXY` | Specify HTTPS proxy server for network connections |
|
|
658
|
-
| `MAX_MCP_OUTPUT_TOKENS` | Maximum number of tokens allowed in MCP tool responses. Claude Code displays a warning when output exceeds 10,000 tokens (default: 25000) |
|
|
659
|
-
| `MAX_THINKING_TOKENS` | Enable [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) and set the token budget for the thinking process. Extended thinking improves performance on complex reasoning and coding tasks but impacts [prompt caching efficiency](https://docs.claude.com/en/docs/build-with-claude/prompt-caching#caching-with-thinking-blocks). Disabled by default. |
|
|
660
|
-
| `MCP_TIMEOUT` | Timeout in milliseconds for MCP server startup |
|
|
661
|
-
| `MCP_TOOL_TIMEOUT` | Timeout in milliseconds for MCP tool execution |
|
|
662
|
-
| `NO_PROXY` | List of domains and IPs to which requests will be directly issued, bypassing proxy |
|
|
663
|
-
| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | Maximum number of characters for slash command metadata shown to [SlashCommand tool](/en/slash-commands#slashcommand-tool) (default: 15000) |
|
|
664
|
-
| `USE_BUILTIN_RIPGREP` | Set to `0` to use system-installed `rg` instead of `rg` included with Claude Code |
|
|
665
|
-
| `VERTEX_REGION_CLAUDE_3_5_HAIKU` | Override region for Claude 3.5 Haiku when using Vertex AI |
|
|
666
|
-
| `VERTEX_REGION_CLAUDE_3_7_SONNET` | Override region for Claude 3.7 Sonnet when using Vertex AI |
|
|
667
|
-
| `VERTEX_REGION_CLAUDE_4_0_OPUS` | Override region for Claude 4.0 Opus when using Vertex AI |
|
|
668
|
-
| `VERTEX_REGION_CLAUDE_4_0_SONNET` | Override region for Claude 4.0 Sonnet when using Vertex AI |
|
|
669
|
-
| `VERTEX_REGION_CLAUDE_4_1_OPUS` | Override region for Claude 4.1 Opus when using Vertex AI |
|
|
670
|
-
|
|
671
|
-
## Tools available to Claude
|
|
672
|
-
|
|
673
|
-
Claude Code has access to a set of powerful tools that help it understand and modify your codebase:
|
|
674
|
-
|
|
675
|
-
| Tool | Description | Permission Required |
|
|
676
|
-
| :------------------ | :------------------------------------------------------------------------------------------------ | :------------------ |
|
|
677
|
-
| **AskUserQuestion** | Asks the user multiple choice questions to gather information or clarify ambiguity | No |
|
|
678
|
-
| **Bash** | Executes shell commands in your environment (see [Bash tool behavior](#bash-tool-behavior) below) | Yes |
|
|
679
|
-
| **BashOutput** | Retrieves output from a background bash shell | No |
|
|
680
|
-
| **Edit** | Makes targeted edits to specific files | Yes |
|
|
681
|
-
| **ExitPlanMode** | Prompts the user to exit plan mode and start coding | Yes |
|
|
682
|
-
| **Glob** | Finds files based on pattern matching | No |
|
|
683
|
-
| **Grep** | Searches for patterns in file contents | No |
|
|
684
|
-
| **KillShell** | Kills a running background bash shell by its ID | No |
|
|
685
|
-
| **NotebookEdit** | Modifies Jupyter notebook cells | Yes |
|
|
686
|
-
| **Read** | Reads the contents of files | No |
|
|
687
|
-
| **Skill** | Executes a skill within the main conversation | Yes |
|
|
688
|
-
| **SlashCommand** | Runs a [custom slash command](/en/slash-commands#slashcommand-tool) | Yes |
|
|
689
|
-
| **Task** | Runs a sub-agent to handle complex, multi-step tasks | No |
|
|
690
|
-
| **TodoWrite** | Creates and manages structured task lists | No |
|
|
691
|
-
| **WebFetch** | Fetches content from a specified URL | Yes |
|
|
692
|
-
| **WebSearch** | Performs web searches with domain filtering | Yes |
|
|
693
|
-
| **Write** | Creates or overwrites files | Yes |
|
|
694
|
-
|
|
695
|
-
Permission rules can be configured using `/allowed-tools` or in [permission settings](/en/settings#available-settings). Also see [Tool-specific permission rules](/en/iam#tool-specific-permission-rules).
|
|
696
|
-
|
|
697
|
-
### Bash tool behavior
|
|
698
|
-
|
|
699
|
-
The Bash tool executes shell commands with the following persistence behavior:
|
|
700
|
-
|
|
701
|
-
* **Working directory persists**: When Claude changes the working directory (for example, `cd /path/to/dir`), subsequent Bash commands will execute in that directory. You can use `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1` to reset to the project directory after each command.
|
|
702
|
-
* **Environment variables do NOT persist**: Environment variables set in one Bash command (for example, `export MY_VAR=value`) are **not** available in subsequent Bash commands. Each Bash command runs in a fresh shell environment.
|
|
703
|
-
|
|
704
|
-
To make environment variables available in Bash commands, you have **three options**:
|
|
705
|
-
|
|
706
|
-
**Option 1: Activate environment before starting Claude Code** (simplest approach)
|
|
707
|
-
|
|
708
|
-
Activate your virtual environment in your terminal before launching Claude Code:
|
|
709
|
-
|
|
710
|
-
```bash theme={null}
|
|
711
|
-
conda activate myenv
|
|
712
|
-
# or: source /path/to/venv/bin/activate
|
|
713
|
-
claude
|
|
714
|
-
```
|
|
715
|
-
|
|
716
|
-
This works for shell environments but environment variables set within Claude's Bash commands will not persist between commands.
|
|
717
|
-
|
|
718
|
-
**Option 2: Set CLAUDE\_ENV\_FILE before starting Claude Code** (persistent environment setup)
|
|
719
|
-
|
|
720
|
-
Export the path to a shell script containing your environment setup:
|
|
721
|
-
|
|
722
|
-
```bash theme={null}
|
|
723
|
-
export CLAUDE_ENV_FILE=/path/to/env-setup.sh
|
|
724
|
-
claude
|
|
725
|
-
```
|
|
726
|
-
|
|
727
|
-
Where `/path/to/env-setup.sh` contains:
|
|
728
|
-
|
|
729
|
-
```bash theme={null}
|
|
730
|
-
conda activate myenv
|
|
731
|
-
# or: source /path/to/venv/bin/activate
|
|
732
|
-
# or: export MY_VAR=value
|
|
733
|
-
```
|
|
734
|
-
|
|
735
|
-
Claude Code will source this file before each Bash command, making the environment persistent across all commands.
|
|
736
|
-
|
|
737
|
-
**Option 3: Use a SessionStart hook** (project-specific configuration)
|
|
738
|
-
|
|
739
|
-
Configure in `.claude/settings.json`:
|
|
740
|
-
|
|
741
|
-
```json theme={null}
|
|
742
|
-
{
|
|
743
|
-
"hooks": {
|
|
744
|
-
"SessionStart": [{
|
|
745
|
-
"matcher": "startup",
|
|
746
|
-
"hooks": [{
|
|
747
|
-
"type": "command",
|
|
748
|
-
"command": "echo 'conda activate myenv' >> \"$CLAUDE_ENV_FILE\""
|
|
749
|
-
}]
|
|
750
|
-
}]
|
|
751
|
-
}
|
|
752
|
-
}
|
|
753
|
-
```
|
|
754
|
-
|
|
755
|
-
The hook writes to `$CLAUDE_ENV_FILE`, which is then sourced before each Bash command. This is ideal for team-shared project configurations.
|
|
756
|
-
|
|
757
|
-
See [SessionStart hooks](/en/hooks#persisting-environment-variables) for more details on Option 3.
|
|
758
|
-
|
|
759
|
-
### Extending tools with hooks
|
|
760
|
-
|
|
761
|
-
You can run custom commands before or after any tool executes using
|
|
762
|
-
[Claude Code hooks](/en/hooks-guide).
|
|
763
|
-
|
|
764
|
-
For example, you could automatically run a Python formatter after Claude
|
|
765
|
-
modifies Python files, or prevent modifications to production configuration
|
|
766
|
-
files by blocking Write operations to certain paths.
|
|
767
|
-
|
|
768
|
-
## See also
|
|
769
|
-
|
|
770
|
-
* [Identity and Access Management](/en/iam#configuring-permissions) - Learn about Claude Code's permission system
|
|
771
|
-
* [IAM and access control](/en/iam#enterprise-managed-settings) - Enterprise policy management
|
|
772
|
-
* [Troubleshooting](/en/troubleshooting#auto-updater-issues) - Solutions for common configuration issues
|
|
773
|
-
|
|
774
|
-
|
|
775
|
-
---
|
|
776
|
-
|
|
1
|
+
# Claude Code settings
|
|
2
|
+
|
|
3
|
+
> Configure Claude Code with global and project-level settings, and environment variables.
|
|
4
|
+
|
|
5
|
+
Claude Code offers a variety of settings to configure its behavior to meet your needs. You can configure Claude Code by running the `/config` command when using the interactive REPL, which opens a tabbed Settings interface where you can view status information and modify configuration options.
|
|
6
|
+
|
|
7
|
+
## Settings files
|
|
8
|
+
|
|
9
|
+
The `settings.json` file is our official mechanism for configuring Claude
|
|
10
|
+
Code through hierarchical settings:
|
|
11
|
+
|
|
12
|
+
* **User settings** are defined in `~/.claude/settings.json` and apply to all
|
|
13
|
+
projects.
|
|
14
|
+
* **Project settings** are saved in your project directory:
|
|
15
|
+
* `.claude/settings.json` for settings that are checked into source control and shared with your team
|
|
16
|
+
* `.claude/settings.local.json` for settings that are not checked in, useful for personal preferences and experimentation. Claude Code will configure git to ignore `.claude/settings.local.json` when it is created.
|
|
17
|
+
* **Managed settings** (Enterprise): Enterprise administrators can configure and distribute Claude Code settings to their organization through the [Claude.ai admin console](https://claude.ai/admin-settings/claude-code). These settings are fetched automatically when users authenticate, take precedence over user and project settings, and cannot be overridden locally. This feature is available to Claude for Enterprise customers. If you don't see this option in your admin console, contact your Anthropic account team to have the feature enabled.
|
|
18
|
+
|
|
19
|
+
For organizations that prefer file-based policy distribution, Claude Code also supports `managed-settings.json` and `managed-mcp.json` files that can be deployed to system directories:
|
|
20
|
+
|
|
21
|
+
* macOS: `/Library/Application Support/ClaudeCode/`
|
|
22
|
+
* Linux and WSL: `/etc/claude-code/`
|
|
23
|
+
* Windows: `C:\Program Files\ClaudeCode\`
|
|
24
|
+
|
|
25
|
+
<Note>
|
|
26
|
+
These are system-wide paths (not user home directories like `~/Library/...`) that require administrator privileges. They are designed to be deployed by IT administrators.
|
|
27
|
+
</Note>
|
|
28
|
+
|
|
29
|
+
See [Enterprise managed settings](/en/iam#enterprise-managed-settings) and [Enterprise MCP configuration](/en/mcp#enterprise-mcp-configuration) for details.
|
|
30
|
+
|
|
31
|
+
<Note>
|
|
32
|
+
Enterprise deployments can also restrict **plugin marketplace additions** using
|
|
33
|
+
`strictKnownMarketplaces`. For more information, see [Enterprise marketplace restrictions](/en/plugin-marketplaces#enterprise-marketplace-restrictions).
|
|
34
|
+
</Note>
|
|
35
|
+
* **Other configuration** is stored in `~/.claude.json`. This file contains your preferences (theme, notification settings, editor mode), OAuth session, [MCP server](/en/mcp) configurations for user and local scopes, per-project state (allowed tools, trust settings), and various caches. Project-scoped MCP servers are stored separately in `.mcp.json`.
|
|
36
|
+
|
|
37
|
+
```JSON Example settings.json theme={null}
|
|
38
|
+
{
|
|
39
|
+
"permissions": {
|
|
40
|
+
"allow": [
|
|
41
|
+
"Bash(npm run lint)",
|
|
42
|
+
"Bash(npm run test:*)",
|
|
43
|
+
"Read(~/.zshrc)"
|
|
44
|
+
],
|
|
45
|
+
"deny": [
|
|
46
|
+
"Bash(curl:*)",
|
|
47
|
+
"Read(./.env)",
|
|
48
|
+
"Read(./.env.*)",
|
|
49
|
+
"Read(./secrets/**)"
|
|
50
|
+
]
|
|
51
|
+
},
|
|
52
|
+
"env": {
|
|
53
|
+
"CLAUDE_CODE_ENABLE_TELEMETRY": "1",
|
|
54
|
+
"OTEL_METRICS_EXPORTER": "otlp"
|
|
55
|
+
},
|
|
56
|
+
"companyAnnouncements": [
|
|
57
|
+
"Welcome to Acme Corp! Review our code guidelines at docs.acme.com",
|
|
58
|
+
"Reminder: Code reviews required for all PRs",
|
|
59
|
+
"New security policy in effect"
|
|
60
|
+
]
|
|
61
|
+
}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### Available settings
|
|
65
|
+
|
|
66
|
+
`settings.json` supports a number of options:
|
|
67
|
+
|
|
68
|
+
| Key | Description | Example |
|
|
69
|
+
| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------- |
|
|
70
|
+
| `apiKeyHelper` | Custom script, to be executed in `/bin/sh`, to generate an auth value. This value will be sent as `X-Api-Key` and `Authorization: Bearer` headers for model requests | `/bin/generate_temp_api_key.sh` |
|
|
71
|
+
| `cleanupPeriodDays` | Sessions inactive for longer than this period are deleted at startup. Setting to `0` immediately deletes all sessions. (default: 30 days) | `20` |
|
|
72
|
+
| `companyAnnouncements` | Announcement to display to users at startup. If multiple announcements are provided, they will be cycled through at random. | `["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"]` |
|
|
73
|
+
| `env` | Environment variables that will be applied to every session | `{"FOO": "bar"}` |
|
|
74
|
+
| `attribution` | Customize attribution for git commits and pull requests. See [Attribution settings](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |
|
|
75
|
+
| `includeCoAuthoredBy` | **Deprecated**: Use `attribution` instead. Whether to include the `co-authored-by Claude` byline in git commits and pull requests (default: `true`) | `false` |
|
|
76
|
+
| `permissions` | See table below for structure of permissions. | |
|
|
77
|
+
| `hooks` | Configure custom commands to run before or after tool executions. See [hooks documentation](/en/hooks) | `{"PreToolUse": {"Bash": "echo 'Running command...'"}}` |
|
|
78
|
+
| `disableAllHooks` | Disable all [hooks](/en/hooks) | `true` |
|
|
79
|
+
| `allowManagedHooksOnly` | (Enterprise) Prevent loading of user, project, and plugin hooks. Only allows managed hooks and SDK hooks. See [Hook configuration](#hook-configuration) | `true` |
|
|
80
|
+
| `model` | Override the default model to use for Claude Code | `"claude-sonnet-4-5-20250929"` |
|
|
81
|
+
| `otelHeadersHelper` | Script to generate dynamic OpenTelemetry headers. Runs at startup and periodically (see [Dynamic headers](/en/monitoring-usage#dynamic-headers)) | `/bin/generate_otel_headers.sh` |
|
|
82
|
+
| `statusLine` | Configure a custom status line to display context. See [`statusLine` documentation](/en/statusline) | `{"type": "command", "command": "~/.claude/statusline.sh"}` |
|
|
83
|
+
| `fileSuggestion` | Configure a custom script for `@` file autocomplete. See [File suggestion settings](#file-suggestion-settings) | `{"type": "command", "command": "~/.claude/file-suggestion.sh"}` |
|
|
84
|
+
| `outputStyle` | Configure an output style to adjust the system prompt. See [output styles documentation](/en/output-styles) | `"Explanatory"` |
|
|
85
|
+
| `forceLoginMethod` | Use `claudeai` to restrict login to Claude.ai accounts, `console` to restrict login to Claude Console (API usage billing) accounts | `claudeai` |
|
|
86
|
+
| `forceLoginOrgUUID` | Specify the UUID of an organization to automatically select it during login, bypassing the organization selection step. Requires `forceLoginMethod` to be set | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` |
|
|
87
|
+
| `enableAllProjectMcpServers` | Automatically approve all MCP servers defined in project `.mcp.json` files | `true` |
|
|
88
|
+
| `enabledMcpjsonServers` | List of specific MCP servers from `.mcp.json` files to approve | `["memory", "github"]` |
|
|
89
|
+
| `disabledMcpjsonServers` | List of specific MCP servers from `.mcp.json` files to reject | `["filesystem"]` |
|
|
90
|
+
| `allowedMcpServers` | When set in managed-settings.json, allowlist of MCP servers users can configure. Undefined = no restrictions, empty array = lockdown. Applies to all scopes. Denylist takes precedence. See [Enterprise MCP configuration](/en/mcp#enterprise-mcp-configuration) | `[{ "serverName": "github" }]` |
|
|
91
|
+
| `deniedMcpServers` | When set in managed-settings.json, denylist of MCP servers that are explicitly blocked. Applies to all scopes including enterprise servers. Denylist takes precedence over allowlist. See [Enterprise MCP configuration](/en/mcp#enterprise-mcp-configuration) | `[{ "serverName": "filesystem" }]` |
|
|
92
|
+
| `strictKnownMarketplaces` | When set in managed-settings.json, allowlist of plugin marketplaces users can add. Undefined = no restrictions, empty array = lockdown. Applies to marketplace additions only. See [Enterprise marketplace restrictions](/en/plugin-marketplaces#enterprise-marketplace-restrictions) | `[{ "source": "github", "repo": "company/plugins" }]` |
|
|
93
|
+
| `awsAuthRefresh` | Custom script that modifies the `.aws` directory (see [advanced credential configuration](/en/amazon-bedrock#advanced-credential-configuration)) | `aws sso login --profile myprofile` |
|
|
94
|
+
| `awsCredentialExport` | Custom script that outputs JSON with AWS credentials (see [advanced credential configuration](/en/amazon-bedrock#advanced-credential-configuration)) | `/bin/generate_aws_grant.sh` |
|
|
95
|
+
| `alwaysThinkingEnabled` | Enable [extended thinking](/en/common-workflows#use-extended-thinking) by default for all sessions. Typically configured via the `/config` command rather than editing directly | `true` |
|
|
96
|
+
|
|
97
|
+
### Permission settings
|
|
98
|
+
|
|
99
|
+
| Keys | Description | Example |
|
|
100
|
+
| :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------- |
|
|
101
|
+
| `allow` | Array of [permission rules](/en/iam#configuring-permissions) to allow tool use. **Note:** Bash rules use prefix matching, not regex | `[ "Bash(git diff:*)" ]` |
|
|
102
|
+
| `ask` | Array of [permission rules](/en/iam#configuring-permissions) to ask for confirmation upon tool use. | `[ "Bash(git push:*)" ]` |
|
|
103
|
+
| `deny` | Array of [permission rules](/en/iam#configuring-permissions) to deny tool use. Use this to also exclude sensitive files from Claude Code access. **Note:** Bash patterns are prefix matches and can be bypassed (see [Bash permission limitations](/en/iam#tool-specific-permission-rules)) | `[ "WebFetch", "Bash(curl:*)", "Read(./.env)", "Read(./secrets/**)" ]` |
|
|
104
|
+
| `additionalDirectories` | Additional [working directories](/en/iam#working-directories) that Claude has access to | `[ "../docs/" ]` |
|
|
105
|
+
| `defaultMode` | Default [permission mode](/en/iam#permission-modes) when opening Claude Code | `"acceptEdits"` |
|
|
106
|
+
| `disableBypassPermissionsMode` | Set to `"disable"` to prevent `bypassPermissions` mode from being activated. This disables the `--dangerously-skip-permissions` command-line flag. See [managed settings](/en/iam#enterprise-managed-settings) | `"disable"` |
|
|
107
|
+
|
|
108
|
+
### Sandbox settings
|
|
109
|
+
|
|
110
|
+
Configure advanced sandboxing behavior. Sandboxing isolates bash commands from your filesystem and network. See [Sandboxing](/en/sandboxing) for details.
|
|
111
|
+
|
|
112
|
+
**Filesystem and network restrictions** are configured via Read, Edit, and WebFetch permission rules, not via these sandbox settings.
|
|
113
|
+
|
|
114
|
+
| Keys | Description | Example |
|
|
115
|
+
| :-------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------ |
|
|
116
|
+
| `enabled` | Enable bash sandboxing (macOS/Linux only). Default: false | `true` |
|
|
117
|
+
| `autoAllowBashIfSandboxed` | Auto-approve bash commands when sandboxed. Default: true | `true` |
|
|
118
|
+
| `excludedCommands` | Commands that should run outside of the sandbox | `["git", "docker"]` |
|
|
119
|
+
| `allowUnsandboxedCommands` | Allow commands to run outside the sandbox via the `dangerouslyDisableSandbox` parameter. When set to `false`, the `dangerouslyDisableSandbox` escape hatch is completely disabled and all commands must run sandboxed (or be in `excludedCommands`). Useful for enterprise policies that require strict sandboxing. Default: true | `false` |
|
|
120
|
+
| `network.allowUnixSockets` | Unix socket paths accessible in sandbox (for SSH agents, etc.) | `["~/.ssh/agent-socket"]` |
|
|
121
|
+
| `network.allowLocalBinding` | Allow binding to localhost ports (macOS only). Default: false | `true` |
|
|
122
|
+
| `network.httpProxyPort` | HTTP proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. | `8080` |
|
|
123
|
+
| `network.socksProxyPort` | SOCKS5 proxy port used if you wish to bring your own proxy. If not specified, Claude will run its own proxy. | `8081` |
|
|
124
|
+
| `enableWeakerNestedSandbox` | Enable weaker sandbox for unprivileged Docker environments (Linux only). **Reduces security.** Default: false | `true` |
|
|
125
|
+
|
|
126
|
+
**Configuration example:**
|
|
127
|
+
|
|
128
|
+
```json theme={null}
|
|
129
|
+
{
|
|
130
|
+
"sandbox": {
|
|
131
|
+
"enabled": true,
|
|
132
|
+
"autoAllowBashIfSandboxed": true,
|
|
133
|
+
"excludedCommands": ["docker"],
|
|
134
|
+
"network": {
|
|
135
|
+
"allowUnixSockets": [
|
|
136
|
+
"/var/run/docker.sock"
|
|
137
|
+
],
|
|
138
|
+
"allowLocalBinding": true
|
|
139
|
+
}
|
|
140
|
+
},
|
|
141
|
+
"permissions": {
|
|
142
|
+
"deny": [
|
|
143
|
+
"Read(.envrc)",
|
|
144
|
+
"Read(~/.aws/**)"
|
|
145
|
+
]
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
**Filesystem and network restrictions** use standard permission rules:
|
|
151
|
+
|
|
152
|
+
* Use `Read` deny rules to block Claude from reading specific files or directories
|
|
153
|
+
* Use `Edit` allow rules to let Claude write to directories beyond the current working directory
|
|
154
|
+
* Use `Edit` deny rules to block writes to specific paths
|
|
155
|
+
* Use `WebFetch` allow/deny rules to control which network domains Claude can access
|
|
156
|
+
|
|
157
|
+
### Attribution settings
|
|
158
|
+
|
|
159
|
+
Claude Code adds attribution to git commits and pull requests. These are configured separately:
|
|
160
|
+
|
|
161
|
+
* Commits use [git trailers](https://git-scm.com/docs/git-interpret-trailers) (like `Co-Authored-By`) by default, which can be customized or disabled
|
|
162
|
+
* Pull request descriptions are plain text
|
|
163
|
+
|
|
164
|
+
| Keys | Description |
|
|
165
|
+
| :------- | :----------------------------------------------------------------------------------------- |
|
|
166
|
+
| `commit` | Attribution for git commits, including any trailers. Empty string hides commit attribution |
|
|
167
|
+
| `pr` | Attribution for pull request descriptions. Empty string hides pull request attribution |
|
|
168
|
+
|
|
169
|
+
**Default commit attribution:**
|
|
170
|
+
|
|
171
|
+
```
|
|
172
|
+
🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
|
173
|
+
|
|
174
|
+
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
**Default pull request attribution:**
|
|
178
|
+
|
|
179
|
+
```
|
|
180
|
+
🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
**Example:**
|
|
184
|
+
|
|
185
|
+
```json theme={null}
|
|
186
|
+
{
|
|
187
|
+
"attribution": {
|
|
188
|
+
"commit": "Generated with AI\n\nCo-Authored-By: AI <ai@example.com>",
|
|
189
|
+
"pr": ""
|
|
190
|
+
}
|
|
191
|
+
}
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
<Note>
|
|
195
|
+
The `attribution` setting takes precedence over the deprecated `includeCoAuthoredBy` setting. To hide all attribution, set `commit` and `pr` to empty strings.
|
|
196
|
+
</Note>
|
|
197
|
+
|
|
198
|
+
### File suggestion settings
|
|
199
|
+
|
|
200
|
+
Configure a custom command for `@` file path autocomplete. The built-in file suggestion uses fast filesystem traversal, but large monorepos may benefit from project-specific indexing such as a pre-built file index or custom tooling.
|
|
201
|
+
|
|
202
|
+
```json theme={null}
|
|
203
|
+
{
|
|
204
|
+
"fileSuggestion": {
|
|
205
|
+
"type": "command",
|
|
206
|
+
"command": "~/.claude/file-suggestion.sh"
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
The command runs with the same environment variables as [hooks](/en/hooks), including `CLAUDE_PROJECT_DIR`. It receives JSON via stdin with a `query` field:
|
|
212
|
+
|
|
213
|
+
```json theme={null}
|
|
214
|
+
{"query": "src/comp"}
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
Output newline-separated file paths to stdout (currently limited to 15):
|
|
218
|
+
|
|
219
|
+
```
|
|
220
|
+
src/components/Button.tsx
|
|
221
|
+
src/components/Modal.tsx
|
|
222
|
+
src/components/Form.tsx
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
**Example:**
|
|
226
|
+
|
|
227
|
+
```bash theme={null}
|
|
228
|
+
#!/bin/bash
|
|
229
|
+
query=$(cat | jq -r '.query')
|
|
230
|
+
your-repo-file-index --query "$query" | head -20
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
### Hook configuration
|
|
234
|
+
|
|
235
|
+
**Enterprise-only setting**: Controls which hooks are allowed to run. This setting can only be configured in [managed settings](#settings-files) and provides enterprise administrators with strict control over hook execution.
|
|
236
|
+
|
|
237
|
+
**Behavior when `allowManagedHooksOnly` is `true`:**
|
|
238
|
+
|
|
239
|
+
* Managed hooks and SDK hooks are loaded
|
|
240
|
+
* User hooks, project hooks, and plugin hooks are blocked
|
|
241
|
+
|
|
242
|
+
**Configuration:**
|
|
243
|
+
|
|
244
|
+
```json theme={null}
|
|
245
|
+
{
|
|
246
|
+
"allowManagedHooksOnly": true
|
|
247
|
+
}
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
### Settings precedence
|
|
251
|
+
|
|
252
|
+
Settings apply in order of precedence. From highest to lowest:
|
|
253
|
+
|
|
254
|
+
1. **Managed settings** (Enterprise)
|
|
255
|
+
* Remote settings configured via the [Claude.ai admin console](https://claude.ai/admin-settings/claude-code)
|
|
256
|
+
* Fetched automatically when users authenticate
|
|
257
|
+
* Cannot be overridden
|
|
258
|
+
|
|
259
|
+
2. **File-based managed settings** (`managed-settings.json`)
|
|
260
|
+
* Policies deployed by IT/DevOps to system directories
|
|
261
|
+
* Cannot be overridden by user or project settings
|
|
262
|
+
* Ignored when remote managed settings are configured
|
|
263
|
+
|
|
264
|
+
3. **Command line arguments**
|
|
265
|
+
* Temporary overrides for a specific session
|
|
266
|
+
|
|
267
|
+
4. **Local project settings** (`.claude/settings.local.json`)
|
|
268
|
+
* Personal project-specific settings
|
|
269
|
+
|
|
270
|
+
5. **Shared project settings** (`.claude/settings.json`)
|
|
271
|
+
* Team-shared project settings in source control
|
|
272
|
+
|
|
273
|
+
6. **User settings** (`~/.claude/settings.json`)
|
|
274
|
+
* Personal global settings
|
|
275
|
+
|
|
276
|
+
This hierarchy ensures that enterprise security policies are always enforced while still allowing teams and individuals to customize their experience.
|
|
277
|
+
|
|
278
|
+
For example, if your user settings allow `Bash(npm run:*)` but a project's shared settings deny it, the project setting takes precedence and the command is blocked.
|
|
279
|
+
|
|
280
|
+
### Key points about the configuration system
|
|
281
|
+
|
|
282
|
+
* **Memory files (`CLAUDE.md`)**: Contain instructions and context that Claude loads at startup
|
|
283
|
+
* **Settings files (JSON)**: Configure permissions, environment variables, and tool behavior
|
|
284
|
+
* **Slash commands**: Custom commands that can be invoked during a session with `/command-name`
|
|
285
|
+
* **MCP servers**: Extend Claude Code with additional tools and integrations
|
|
286
|
+
* **Precedence**: Higher-level configurations (Enterprise) override lower-level ones (User/Project)
|
|
287
|
+
* **Inheritance**: Settings are merged, with more specific settings adding to or overriding broader ones
|
|
288
|
+
|
|
289
|
+
### System prompt
|
|
290
|
+
|
|
291
|
+
Claude Code's internal system prompt is not published. To add custom instructions, use `CLAUDE.md` files or the `--append-system-prompt` flag.
|
|
292
|
+
|
|
293
|
+
### Excluding sensitive files
|
|
294
|
+
|
|
295
|
+
To prevent Claude Code from accessing files containing sensitive information like API keys, secrets, and environment files, use the `permissions.deny` setting in your `.claude/settings.json` file:
|
|
296
|
+
|
|
297
|
+
```json theme={null}
|
|
298
|
+
{
|
|
299
|
+
"permissions": {
|
|
300
|
+
"deny": [
|
|
301
|
+
"Read(./.env)",
|
|
302
|
+
"Read(./.env.*)",
|
|
303
|
+
"Read(./secrets/**)",
|
|
304
|
+
"Read(./config/credentials.json)",
|
|
305
|
+
"Read(./build)"
|
|
306
|
+
]
|
|
307
|
+
}
|
|
308
|
+
}
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
This replaces the deprecated `ignorePatterns` configuration. Files matching these patterns will be completely invisible to Claude Code, preventing any accidental exposure of sensitive data.
|
|
312
|
+
|
|
313
|
+
## Subagent configuration
|
|
314
|
+
|
|
315
|
+
Claude Code supports custom AI subagents that can be configured at both user and project levels. These subagents are stored as Markdown files with YAML frontmatter:
|
|
316
|
+
|
|
317
|
+
* **User subagents**: `~/.claude/agents/` - Available across all your projects
|
|
318
|
+
* **Project subagents**: `.claude/agents/` - Specific to your project and can be shared with your team
|
|
319
|
+
|
|
320
|
+
Subagent files define specialized AI assistants with custom prompts and tool permissions. Learn more about creating and using subagents in the [subagents documentation](/en/sub-agents).
|
|
321
|
+
|
|
322
|
+
## Plugin configuration
|
|
323
|
+
|
|
324
|
+
Claude Code supports a plugin system that lets you extend functionality with custom commands, agents, hooks, and MCP servers. Plugins are distributed through marketplaces and can be configured at both user and repository levels.
|
|
325
|
+
|
|
326
|
+
### Plugin settings
|
|
327
|
+
|
|
328
|
+
Plugin-related settings in `settings.json`:
|
|
329
|
+
|
|
330
|
+
```json theme={null}
|
|
331
|
+
{
|
|
332
|
+
"enabledPlugins": {
|
|
333
|
+
"formatter@company-tools": true,
|
|
334
|
+
"deployer@company-tools": true,
|
|
335
|
+
"analyzer@security-plugins": false
|
|
336
|
+
},
|
|
337
|
+
"extraKnownMarketplaces": {
|
|
338
|
+
"company-tools": {
|
|
339
|
+
"source": "github",
|
|
340
|
+
"repo": "company/claude-plugins"
|
|
341
|
+
}
|
|
342
|
+
}
|
|
343
|
+
}
|
|
344
|
+
```
|
|
345
|
+
|
|
346
|
+
#### `enabledPlugins`
|
|
347
|
+
|
|
348
|
+
Controls which plugins are enabled. Format: `"plugin-name@marketplace-name": true/false`
|
|
349
|
+
|
|
350
|
+
**Scopes**:
|
|
351
|
+
|
|
352
|
+
* **User settings** (`~/.claude/settings.json`): Personal plugin preferences
|
|
353
|
+
* **Project settings** (`.claude/settings.json`): Project-specific plugins shared with team
|
|
354
|
+
* **Local settings** (`.claude/settings.local.json`): Per-machine overrides (not committed)
|
|
355
|
+
|
|
356
|
+
**Example**:
|
|
357
|
+
|
|
358
|
+
```json theme={null}
|
|
359
|
+
{
|
|
360
|
+
"enabledPlugins": {
|
|
361
|
+
"code-formatter@team-tools": true,
|
|
362
|
+
"deployment-tools@team-tools": true,
|
|
363
|
+
"experimental-features@personal": false
|
|
364
|
+
}
|
|
365
|
+
}
|
|
366
|
+
```
|
|
367
|
+
|
|
368
|
+
#### `extraKnownMarketplaces`
|
|
369
|
+
|
|
370
|
+
Defines additional marketplaces that should be made available for the repository. Typically used in repository-level settings to ensure team members have access to required plugin sources.
|
|
371
|
+
|
|
372
|
+
**When a repository includes `extraKnownMarketplaces`**:
|
|
373
|
+
|
|
374
|
+
1. Team members are prompted to install the marketplace when they trust the folder
|
|
375
|
+
2. Team members are then prompted to install plugins from that marketplace
|
|
376
|
+
3. Users can skip unwanted marketplaces or plugins (stored in user settings)
|
|
377
|
+
4. Installation respects trust boundaries and requires explicit consent
|
|
378
|
+
|
|
379
|
+
**Example**:
|
|
380
|
+
|
|
381
|
+
```json theme={null}
|
|
382
|
+
{
|
|
383
|
+
"extraKnownMarketplaces": {
|
|
384
|
+
"company-tools": {
|
|
385
|
+
"source": {
|
|
386
|
+
"source": "github",
|
|
387
|
+
"repo": "company-org/claude-plugins"
|
|
388
|
+
}
|
|
389
|
+
},
|
|
390
|
+
"security-plugins": {
|
|
391
|
+
"source": {
|
|
392
|
+
"source": "git",
|
|
393
|
+
"url": "https://git.company.com/security/plugins.git"
|
|
394
|
+
}
|
|
395
|
+
}
|
|
396
|
+
}
|
|
397
|
+
}
|
|
398
|
+
```
|
|
399
|
+
|
|
400
|
+
**Marketplace source types**:
|
|
401
|
+
|
|
402
|
+
* `github`: GitHub repository (uses `repo`)
|
|
403
|
+
* `git`: Any git URL (uses `url`)
|
|
404
|
+
* `directory`: Local filesystem path (uses `path`, for development only)
|
|
405
|
+
|
|
406
|
+
#### `strictKnownMarketplaces`
|
|
407
|
+
|
|
408
|
+
**Enterprise-only setting**: Controls which plugin marketplaces users are allowed to add. This setting can only be configured in `managed-settings.json` and provides enterprise administrators with strict control over marketplace sources.
|
|
409
|
+
|
|
410
|
+
**Managed settings file locations**:
|
|
411
|
+
|
|
412
|
+
* **macOS**: `/Library/Application Support/ClaudeCode/managed-settings.json`
|
|
413
|
+
* **Linux and WSL**: `/etc/claude-code/managed-settings.json`
|
|
414
|
+
* **Windows**: `C:\ProgramData\ClaudeCode\managed-settings.json`
|
|
415
|
+
|
|
416
|
+
**Key characteristics**:
|
|
417
|
+
|
|
418
|
+
* Only available in enterprise managed settings (`managed-settings.json`)
|
|
419
|
+
* Cannot be overridden by user or project settings (highest precedence)
|
|
420
|
+
* Enforced BEFORE network/filesystem operations (blocked sources never execute)
|
|
421
|
+
* Uses exact matching for source specifications (including `ref`, `path` for git sources)
|
|
422
|
+
|
|
423
|
+
**Allowlist behavior**:
|
|
424
|
+
|
|
425
|
+
* `undefined` (default): No restrictions - users can add any marketplace
|
|
426
|
+
* Empty array `[]`: Complete lockdown - users cannot add any new marketplaces
|
|
427
|
+
* List of sources: Users can only add marketplaces that match exactly
|
|
428
|
+
|
|
429
|
+
**All supported source types**:
|
|
430
|
+
|
|
431
|
+
The allowlist supports six marketplace source types. Each source must match exactly for a user's marketplace addition to be allowed.
|
|
432
|
+
|
|
433
|
+
1. **GitHub repositories**:
|
|
434
|
+
|
|
435
|
+
```json theme={null}
|
|
436
|
+
{ "source": "github", "repo": "company/approved-plugins" }
|
|
437
|
+
{ "source": "github", "repo": "company/security-tools", "ref": "v2.0" }
|
|
438
|
+
{ "source": "github", "repo": "team/plugins", "ref": "main", "path": "marketplace" }
|
|
439
|
+
```
|
|
440
|
+
|
|
441
|
+
Fields: `repo` (required), `ref` (optional: branch/tag/SHA), `path` (optional: subdirectory)
|
|
442
|
+
|
|
443
|
+
2. **Git repositories**:
|
|
444
|
+
|
|
445
|
+
```json theme={null}
|
|
446
|
+
{ "source": "git", "url": "https://gitlab.company.com/tools/plugins.git" }
|
|
447
|
+
{ "source": "git", "url": "https://bitbucket.org/company/plugins.git", "ref": "production" }
|
|
448
|
+
{ "source": "git", "url": "ssh://git@internal.company.com/plugins.git", "ref": "v3.1", "path": "approved" }
|
|
449
|
+
```
|
|
450
|
+
|
|
451
|
+
Fields: `url` (required), `ref` (optional: branch/tag/SHA), `path` (optional: subdirectory)
|
|
452
|
+
|
|
453
|
+
3. **URL-based marketplaces**:
|
|
454
|
+
|
|
455
|
+
```json theme={null}
|
|
456
|
+
{ "source": "url", "url": "https://internal.company.com/plugins/marketplace.json" }
|
|
457
|
+
{ "source": "url", "url": "https://cdn.company.com/marketplace.json", "headers": { "Authorization": "Bearer ${TOKEN}" } }
|
|
458
|
+
```
|
|
459
|
+
|
|
460
|
+
Fields: `url` (required), `headers` (optional: HTTP headers for authenticated access)
|
|
461
|
+
|
|
462
|
+
4. **NPM packages**:
|
|
463
|
+
|
|
464
|
+
```json theme={null}
|
|
465
|
+
{ "source": "npm", "package": "@company/claude-plugins" }
|
|
466
|
+
{ "source": "npm", "package": "@company-internal/approved-marketplace" }
|
|
467
|
+
```
|
|
468
|
+
|
|
469
|
+
Fields: `package` (required, supports scoped packages)
|
|
470
|
+
|
|
471
|
+
5. **File paths**:
|
|
472
|
+
|
|
473
|
+
```json theme={null}
|
|
474
|
+
{ "source": "file", "path": "/usr/local/share/claude/company-marketplace.json" }
|
|
475
|
+
{ "source": "file", "path": "/opt/company/plugins/marketplace.json" }
|
|
476
|
+
```
|
|
477
|
+
|
|
478
|
+
Fields: `path` (required: absolute path to marketplace.json file)
|
|
479
|
+
|
|
480
|
+
6. **Directory paths**:
|
|
481
|
+
|
|
482
|
+
```json theme={null}
|
|
483
|
+
{ "source": "directory", "path": "/usr/local/share/claude/company-plugins" }
|
|
484
|
+
{ "source": "directory", "path": "/opt/company/approved-marketplaces" }
|
|
485
|
+
```
|
|
486
|
+
|
|
487
|
+
Fields: `path` (required: absolute path to directory containing `.claude-plugin/marketplace.json`)
|
|
488
|
+
|
|
489
|
+
**Configuration examples**:
|
|
490
|
+
|
|
491
|
+
Example - Allow specific marketplaces only:
|
|
492
|
+
|
|
493
|
+
```json theme={null}
|
|
494
|
+
{
|
|
495
|
+
"strictKnownMarketplaces": [
|
|
496
|
+
{
|
|
497
|
+
"source": "github",
|
|
498
|
+
"repo": "company/approved-plugins"
|
|
499
|
+
},
|
|
500
|
+
{
|
|
501
|
+
"source": "github",
|
|
502
|
+
"repo": "company/security-tools",
|
|
503
|
+
"ref": "v2.0"
|
|
504
|
+
},
|
|
505
|
+
{
|
|
506
|
+
"source": "url",
|
|
507
|
+
"url": "https://internal.company.com/plugins/marketplace.json"
|
|
508
|
+
},
|
|
509
|
+
{
|
|
510
|
+
"source": "npm",
|
|
511
|
+
"package": "@company/compliance-plugins"
|
|
512
|
+
}
|
|
513
|
+
]
|
|
514
|
+
}
|
|
515
|
+
```
|
|
516
|
+
|
|
517
|
+
Example - Disable all marketplace additions:
|
|
518
|
+
|
|
519
|
+
```json theme={null}
|
|
520
|
+
{
|
|
521
|
+
"strictKnownMarketplaces": []
|
|
522
|
+
}
|
|
523
|
+
```
|
|
524
|
+
|
|
525
|
+
**Exact matching requirements**:
|
|
526
|
+
|
|
527
|
+
Marketplace sources must match **exactly** for a user's addition to be allowed. For git-based sources (`github` and `git`), this includes all optional fields:
|
|
528
|
+
|
|
529
|
+
* The `repo` or `url` must match exactly
|
|
530
|
+
* The `ref` field must match exactly (or both be undefined)
|
|
531
|
+
* The `path` field must match exactly (or both be undefined)
|
|
532
|
+
|
|
533
|
+
Examples of sources that **do NOT match**:
|
|
534
|
+
|
|
535
|
+
```json theme={null}
|
|
536
|
+
// These are DIFFERENT sources:
|
|
537
|
+
{ "source": "github", "repo": "company/plugins" }
|
|
538
|
+
{ "source": "github", "repo": "company/plugins", "ref": "main" }
|
|
539
|
+
|
|
540
|
+
// These are also DIFFERENT:
|
|
541
|
+
{ "source": "github", "repo": "company/plugins", "path": "marketplace" }
|
|
542
|
+
{ "source": "github", "repo": "company/plugins" }
|
|
543
|
+
```
|
|
544
|
+
|
|
545
|
+
**Comparison with `extraKnownMarketplaces`**:
|
|
546
|
+
|
|
547
|
+
| Aspect | `strictKnownMarketplaces` | `extraKnownMarketplaces` |
|
|
548
|
+
| --------------------- | ------------------------------------ | ------------------------------------ |
|
|
549
|
+
| **Purpose** | Enterprise policy enforcement | Team convenience |
|
|
550
|
+
| **Settings file** | `managed-settings.json` only | Any settings file |
|
|
551
|
+
| **Behavior** | Blocks non-allowlisted additions | Auto-installs missing marketplaces |
|
|
552
|
+
| **When enforced** | Before network/filesystem operations | After user trust prompt |
|
|
553
|
+
| **Can be overridden** | No (highest precedence) | Yes (by higher precedence settings) |
|
|
554
|
+
| **Source format** | Direct source object | Named marketplace with nested source |
|
|
555
|
+
| **Use case** | Compliance, security restrictions | Onboarding, standardization |
|
|
556
|
+
|
|
557
|
+
**Format difference**:
|
|
558
|
+
|
|
559
|
+
`strictKnownMarketplaces` uses direct source objects:
|
|
560
|
+
|
|
561
|
+
```json theme={null}
|
|
562
|
+
{
|
|
563
|
+
"strictKnownMarketplaces": [
|
|
564
|
+
{ "source": "github", "repo": "company/plugins" }
|
|
565
|
+
]
|
|
566
|
+
}
|
|
567
|
+
```
|
|
568
|
+
|
|
569
|
+
`extraKnownMarketplaces` requires named marketplaces:
|
|
570
|
+
|
|
571
|
+
```json theme={null}
|
|
572
|
+
{
|
|
573
|
+
"extraKnownMarketplaces": {
|
|
574
|
+
"company-tools": {
|
|
575
|
+
"source": { "source": "github", "repo": "company/plugins" }
|
|
576
|
+
}
|
|
577
|
+
}
|
|
578
|
+
}
|
|
579
|
+
```
|
|
580
|
+
|
|
581
|
+
**Important notes**:
|
|
582
|
+
|
|
583
|
+
* Restrictions are checked BEFORE any network requests or filesystem operations
|
|
584
|
+
* When blocked, users see clear error messages indicating the source is blocked by enterprise policy
|
|
585
|
+
* The restriction applies only to adding NEW marketplaces; previously installed marketplaces remain accessible
|
|
586
|
+
* Enterprise managed settings have the highest precedence and cannot be overridden
|
|
587
|
+
|
|
588
|
+
See [Enterprise marketplace restrictions](/en/plugin-marketplaces#enterprise-marketplace-restrictions) for user-facing documentation.
|
|
589
|
+
|
|
590
|
+
### Managing plugins
|
|
591
|
+
|
|
592
|
+
Use the `/plugin` command to manage plugins interactively:
|
|
593
|
+
|
|
594
|
+
* Browse available plugins from marketplaces
|
|
595
|
+
* Install/uninstall plugins
|
|
596
|
+
* Enable/disable plugins
|
|
597
|
+
* View plugin details (commands, agents, hooks provided)
|
|
598
|
+
* Add/remove marketplaces
|
|
599
|
+
|
|
600
|
+
Learn more about the plugin system in the [plugins documentation](/en/plugins).
|
|
601
|
+
|
|
602
|
+
## Environment variables
|
|
603
|
+
|
|
604
|
+
Claude Code supports the following environment variables to control its behavior:
|
|
605
|
+
|
|
606
|
+
<Note>
|
|
607
|
+
All environment variables can also be configured in [`settings.json`](#available-settings). This is useful as a way to automatically set environment variables for each session, or to roll out a set of environment variables for your whole team or organization.
|
|
608
|
+
</Note>
|
|
609
|
+
|
|
610
|
+
| Variable | Purpose |
|
|
611
|
+
| :-------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
612
|
+
| `ANTHROPIC_API_KEY` | API key sent as `X-Api-Key` header, typically for the Claude SDK (for interactive usage, run `/login`) |
|
|
613
|
+
| `ANTHROPIC_AUTH_TOKEN` | Custom value for the `Authorization` header (the value you set here will be prefixed with `Bearer `) |
|
|
614
|
+
| `ANTHROPIC_CUSTOM_HEADERS` | Custom headers you want to add to the request (in `Name: Value` format) |
|
|
615
|
+
| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | See [Model configuration](/en/model-config#environment-variables) |
|
|
616
|
+
| `ANTHROPIC_DEFAULT_OPUS_MODEL` | See [Model configuration](/en/model-config#environment-variables) |
|
|
617
|
+
| `ANTHROPIC_DEFAULT_SONNET_MODEL` | See [Model configuration](/en/model-config#environment-variables) |
|
|
618
|
+
| `ANTHROPIC_FOUNDRY_API_KEY` | API key for Microsoft Foundry authentication (see [Microsoft Foundry](/en/microsoft-foundry)) |
|
|
619
|
+
| `ANTHROPIC_MODEL` | Name of the model setting to use (see [Model Configuration](/en/model-config#environment-variables)) |
|
|
620
|
+
| `ANTHROPIC_SMALL_FAST_MODEL` | \[DEPRECATED] Name of [Haiku-class model for background tasks](/en/costs) |
|
|
621
|
+
| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | Override AWS region for the Haiku-class model when using Bedrock |
|
|
622
|
+
| `AWS_BEARER_TOKEN_BEDROCK` | Bedrock API key for authentication (see [Bedrock API keys](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)) |
|
|
623
|
+
| `BASH_DEFAULT_TIMEOUT_MS` | Default timeout for long-running bash commands |
|
|
624
|
+
| `BASH_MAX_OUTPUT_LENGTH` | Maximum number of characters in bash outputs before they are middle-truncated |
|
|
625
|
+
| `BASH_MAX_TIMEOUT_MS` | Maximum timeout the model can set for long-running bash commands |
|
|
626
|
+
| `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR` | Return to the original working directory after each Bash command |
|
|
627
|
+
| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` | Interval in milliseconds at which credentials should be refreshed (when using `apiKeyHelper`) |
|
|
628
|
+
| `CLAUDE_CODE_CLIENT_CERT` | Path to client certificate file for mTLS authentication |
|
|
629
|
+
| `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE` | Passphrase for encrypted CLAUDE\_CODE\_CLIENT\_KEY (optional) |
|
|
630
|
+
| `CLAUDE_CODE_CLIENT_KEY` | Path to client private key file for mTLS authentication |
|
|
631
|
+
| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Set to `1` to disable Anthropic API-specific `anthropic-beta` headers. Use this if experiencing issues like "Unexpected value(s) for the `anthropic-beta` header" when using an LLM gateway with third-party providers |
|
|
632
|
+
| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | Equivalent of setting `DISABLE_AUTOUPDATER`, `DISABLE_BUG_COMMAND`, `DISABLE_ERROR_REPORTING`, and `DISABLE_TELEMETRY` |
|
|
633
|
+
| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | Set to `1` to disable automatic terminal title updates based on conversation context |
|
|
634
|
+
| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | Skip auto-installation of IDE extensions |
|
|
635
|
+
| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | Set the maximum number of output tokens for most requests |
|
|
636
|
+
| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | Interval for refreshing dynamic OpenTelemetry headers in milliseconds (default: 1740000 / 29 minutes). See [Dynamic headers](/en/monitoring-usage#dynamic-headers) |
|
|
637
|
+
| `CLAUDE_CODE_SHELL_PREFIX` | Command prefix to wrap all bash commands (for example, for logging or auditing). Example: `/path/to/logger.sh` will execute `/path/to/logger.sh <command>` |
|
|
638
|
+
| `CLAUDE_CODE_SKIP_BEDROCK_AUTH` | Skip AWS authentication for Bedrock (for example, when using an LLM gateway) |
|
|
639
|
+
| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | Skip Azure authentication for Microsoft Foundry (for example, when using an LLM gateway) |
|
|
640
|
+
| `CLAUDE_CODE_SKIP_VERTEX_AUTH` | Skip Google authentication for Vertex (for example, when using an LLM gateway) |
|
|
641
|
+
| `CLAUDE_CODE_SUBAGENT_MODEL` | See [Model configuration](/en/model-config) |
|
|
642
|
+
| `CLAUDE_CODE_USE_BEDROCK` | Use [Bedrock](/en/amazon-bedrock) |
|
|
643
|
+
| `CLAUDE_CODE_USE_FOUNDRY` | Use [Microsoft Foundry](/en/microsoft-foundry) |
|
|
644
|
+
| `CLAUDE_CODE_USE_VERTEX` | Use [Vertex](/en/google-vertex-ai) |
|
|
645
|
+
| `CLAUDE_CONFIG_DIR` | Customize where Claude Code stores its configuration and data files |
|
|
646
|
+
| `DISABLE_AUTOUPDATER` | Set to `1` to disable automatic updates. |
|
|
647
|
+
| `DISABLE_BUG_COMMAND` | Set to `1` to disable the `/bug` command |
|
|
648
|
+
| `DISABLE_COST_WARNINGS` | Set to `1` to disable cost warning messages |
|
|
649
|
+
| `DISABLE_ERROR_REPORTING` | Set to `1` to opt out of Sentry error reporting |
|
|
650
|
+
| `DISABLE_NON_ESSENTIAL_MODEL_CALLS` | Set to `1` to disable model calls for non-critical paths like flavor text |
|
|
651
|
+
| `DISABLE_PROMPT_CACHING` | Set to `1` to disable prompt caching for all models (takes precedence over per-model settings) |
|
|
652
|
+
| `DISABLE_PROMPT_CACHING_HAIKU` | Set to `1` to disable prompt caching for Haiku models |
|
|
653
|
+
| `DISABLE_PROMPT_CACHING_OPUS` | Set to `1` to disable prompt caching for Opus models |
|
|
654
|
+
| `DISABLE_PROMPT_CACHING_SONNET` | Set to `1` to disable prompt caching for Sonnet models |
|
|
655
|
+
| `DISABLE_TELEMETRY` | Set to `1` to opt out of Statsig telemetry (note that Statsig events do not include user data like code, file paths, or bash commands) |
|
|
656
|
+
| `HTTP_PROXY` | Specify HTTP proxy server for network connections |
|
|
657
|
+
| `HTTPS_PROXY` | Specify HTTPS proxy server for network connections |
|
|
658
|
+
| `MAX_MCP_OUTPUT_TOKENS` | Maximum number of tokens allowed in MCP tool responses. Claude Code displays a warning when output exceeds 10,000 tokens (default: 25000) |
|
|
659
|
+
| `MAX_THINKING_TOKENS` | Enable [extended thinking](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) and set the token budget for the thinking process. Extended thinking improves performance on complex reasoning and coding tasks but impacts [prompt caching efficiency](https://docs.claude.com/en/docs/build-with-claude/prompt-caching#caching-with-thinking-blocks). Disabled by default. |
|
|
660
|
+
| `MCP_TIMEOUT` | Timeout in milliseconds for MCP server startup |
|
|
661
|
+
| `MCP_TOOL_TIMEOUT` | Timeout in milliseconds for MCP tool execution |
|
|
662
|
+
| `NO_PROXY` | List of domains and IPs to which requests will be directly issued, bypassing proxy |
|
|
663
|
+
| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | Maximum number of characters for slash command metadata shown to [SlashCommand tool](/en/slash-commands#slashcommand-tool) (default: 15000) |
|
|
664
|
+
| `USE_BUILTIN_RIPGREP` | Set to `0` to use system-installed `rg` instead of `rg` included with Claude Code |
|
|
665
|
+
| `VERTEX_REGION_CLAUDE_3_5_HAIKU` | Override region for Claude 3.5 Haiku when using Vertex AI |
|
|
666
|
+
| `VERTEX_REGION_CLAUDE_3_7_SONNET` | Override region for Claude 3.7 Sonnet when using Vertex AI |
|
|
667
|
+
| `VERTEX_REGION_CLAUDE_4_0_OPUS` | Override region for Claude 4.0 Opus when using Vertex AI |
|
|
668
|
+
| `VERTEX_REGION_CLAUDE_4_0_SONNET` | Override region for Claude 4.0 Sonnet when using Vertex AI |
|
|
669
|
+
| `VERTEX_REGION_CLAUDE_4_1_OPUS` | Override region for Claude 4.1 Opus when using Vertex AI |
|
|
670
|
+
|
|
671
|
+
## Tools available to Claude
|
|
672
|
+
|
|
673
|
+
Claude Code has access to a set of powerful tools that help it understand and modify your codebase:
|
|
674
|
+
|
|
675
|
+
| Tool | Description | Permission Required |
|
|
676
|
+
| :------------------ | :------------------------------------------------------------------------------------------------ | :------------------ |
|
|
677
|
+
| **AskUserQuestion** | Asks the user multiple choice questions to gather information or clarify ambiguity | No |
|
|
678
|
+
| **Bash** | Executes shell commands in your environment (see [Bash tool behavior](#bash-tool-behavior) below) | Yes |
|
|
679
|
+
| **BashOutput** | Retrieves output from a background bash shell | No |
|
|
680
|
+
| **Edit** | Makes targeted edits to specific files | Yes |
|
|
681
|
+
| **ExitPlanMode** | Prompts the user to exit plan mode and start coding | Yes |
|
|
682
|
+
| **Glob** | Finds files based on pattern matching | No |
|
|
683
|
+
| **Grep** | Searches for patterns in file contents | No |
|
|
684
|
+
| **KillShell** | Kills a running background bash shell by its ID | No |
|
|
685
|
+
| **NotebookEdit** | Modifies Jupyter notebook cells | Yes |
|
|
686
|
+
| **Read** | Reads the contents of files | No |
|
|
687
|
+
| **Skill** | Executes a skill within the main conversation | Yes |
|
|
688
|
+
| **SlashCommand** | Runs a [custom slash command](/en/slash-commands#slashcommand-tool) | Yes |
|
|
689
|
+
| **Task** | Runs a sub-agent to handle complex, multi-step tasks | No |
|
|
690
|
+
| **TodoWrite** | Creates and manages structured task lists | No |
|
|
691
|
+
| **WebFetch** | Fetches content from a specified URL | Yes |
|
|
692
|
+
| **WebSearch** | Performs web searches with domain filtering | Yes |
|
|
693
|
+
| **Write** | Creates or overwrites files | Yes |
|
|
694
|
+
|
|
695
|
+
Permission rules can be configured using `/allowed-tools` or in [permission settings](/en/settings#available-settings). Also see [Tool-specific permission rules](/en/iam#tool-specific-permission-rules).
|
|
696
|
+
|
|
697
|
+
### Bash tool behavior
|
|
698
|
+
|
|
699
|
+
The Bash tool executes shell commands with the following persistence behavior:
|
|
700
|
+
|
|
701
|
+
* **Working directory persists**: When Claude changes the working directory (for example, `cd /path/to/dir`), subsequent Bash commands will execute in that directory. You can use `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1` to reset to the project directory after each command.
|
|
702
|
+
* **Environment variables do NOT persist**: Environment variables set in one Bash command (for example, `export MY_VAR=value`) are **not** available in subsequent Bash commands. Each Bash command runs in a fresh shell environment.
|
|
703
|
+
|
|
704
|
+
To make environment variables available in Bash commands, you have **three options**:
|
|
705
|
+
|
|
706
|
+
**Option 1: Activate environment before starting Claude Code** (simplest approach)
|
|
707
|
+
|
|
708
|
+
Activate your virtual environment in your terminal before launching Claude Code:
|
|
709
|
+
|
|
710
|
+
```bash theme={null}
|
|
711
|
+
conda activate myenv
|
|
712
|
+
# or: source /path/to/venv/bin/activate
|
|
713
|
+
claude
|
|
714
|
+
```
|
|
715
|
+
|
|
716
|
+
This works for shell environments but environment variables set within Claude's Bash commands will not persist between commands.
|
|
717
|
+
|
|
718
|
+
**Option 2: Set CLAUDE\_ENV\_FILE before starting Claude Code** (persistent environment setup)
|
|
719
|
+
|
|
720
|
+
Export the path to a shell script containing your environment setup:
|
|
721
|
+
|
|
722
|
+
```bash theme={null}
|
|
723
|
+
export CLAUDE_ENV_FILE=/path/to/env-setup.sh
|
|
724
|
+
claude
|
|
725
|
+
```
|
|
726
|
+
|
|
727
|
+
Where `/path/to/env-setup.sh` contains:
|
|
728
|
+
|
|
729
|
+
```bash theme={null}
|
|
730
|
+
conda activate myenv
|
|
731
|
+
# or: source /path/to/venv/bin/activate
|
|
732
|
+
# or: export MY_VAR=value
|
|
733
|
+
```
|
|
734
|
+
|
|
735
|
+
Claude Code will source this file before each Bash command, making the environment persistent across all commands.
|
|
736
|
+
|
|
737
|
+
**Option 3: Use a SessionStart hook** (project-specific configuration)
|
|
738
|
+
|
|
739
|
+
Configure in `.claude/settings.json`:
|
|
740
|
+
|
|
741
|
+
```json theme={null}
|
|
742
|
+
{
|
|
743
|
+
"hooks": {
|
|
744
|
+
"SessionStart": [{
|
|
745
|
+
"matcher": "startup",
|
|
746
|
+
"hooks": [{
|
|
747
|
+
"type": "command",
|
|
748
|
+
"command": "echo 'conda activate myenv' >> \"$CLAUDE_ENV_FILE\""
|
|
749
|
+
}]
|
|
750
|
+
}]
|
|
751
|
+
}
|
|
752
|
+
}
|
|
753
|
+
```
|
|
754
|
+
|
|
755
|
+
The hook writes to `$CLAUDE_ENV_FILE`, which is then sourced before each Bash command. This is ideal for team-shared project configurations.
|
|
756
|
+
|
|
757
|
+
See [SessionStart hooks](/en/hooks#persisting-environment-variables) for more details on Option 3.
|
|
758
|
+
|
|
759
|
+
### Extending tools with hooks
|
|
760
|
+
|
|
761
|
+
You can run custom commands before or after any tool executes using
|
|
762
|
+
[Claude Code hooks](/en/hooks-guide).
|
|
763
|
+
|
|
764
|
+
For example, you could automatically run a Python formatter after Claude
|
|
765
|
+
modifies Python files, or prevent modifications to production configuration
|
|
766
|
+
files by blocking Write operations to certain paths.
|
|
767
|
+
|
|
768
|
+
## See also
|
|
769
|
+
|
|
770
|
+
* [Identity and Access Management](/en/iam#configuring-permissions) - Learn about Claude Code's permission system
|
|
771
|
+
* [IAM and access control](/en/iam#enterprise-managed-settings) - Enterprise policy management
|
|
772
|
+
* [Troubleshooting](/en/troubleshooting#auto-updater-issues) - Solutions for common configuration issues
|
|
773
|
+
|
|
774
|
+
|
|
775
|
+
---
|
|
776
|
+
|
|
777
777
|
> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://code.claude.com/docs/llms.txt
|