Documentation 2025-12-01 03:31 UTC to 2025-12-02 21:01 UTC

13| **Enterprise policy** | macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md`<br />Linux: `/etc/claude-code/CLAUDE.md`<br />Windows: `C:\ProgramData\ClaudeCode\CLAUDE.md` | Organization-wide instructions managed by IT/DevOps | Company coding standards, security policies, compliance requirements | All users in organization |13| **Enterprise policy** | macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md`<br />Linux: `/etc/claude-code/CLAUDE.md`<br />Windows: `C:\ProgramData\ClaudeCode\CLAUDE.md` | Organization-wide instructions managed by IT/DevOps | Company coding standards, security policies, compliance requirements | All users in organization |

14| **Project memory** | `./CLAUDE.md` or `./.claude/CLAUDE.md` | Team-shared instructions for the project | Project architecture, coding standards, common workflows | Team members via source control |14| **Project memory** | `./CLAUDE.md` or `./.claude/CLAUDE.md` | Team-shared instructions for the project | Project architecture, coding standards, common workflows | Team members via source control |

15| **User memory** | `~/.claude/CLAUDE.md` | Personal preferences for all projects | Code styling preferences, personal tooling shortcuts | Just you (all projects) |15| **User memory** | `~/.claude/CLAUDE.md` | Personal preferences for all projects | Code styling preferences, personal tooling shortcuts | Just you (all projects) |

16| **Project memory (local)** | `./CLAUDE.local.md` | Personal project-specific preferences | *(Deprecated, see below)* Your sandbox URLs, preferred test data | Just you (current project) |16| **Project memory (local)** | `./CLAUDE.local.md` | Personal project-specific preferences | Your sandbox URLs, preferred test data | Just you (current project) |

17 17 

18All memory files are automatically loaded into Claude Code's context when launched. Files higher in the hierarchy take precedence and are loaded first, providing a foundation that more specific memories build upon.18All memory files are automatically loaded into Claude Code's context when launched. Files higher in the hierarchy take precedence and are loaded first, providing a foundation that more specific memories build upon.

19 19 

20<Note>

21 CLAUDE.local.md files are automatically added to .gitignore, making them ideal for private project-specific preferences that shouldn't be checked into version control.

22</Note>

23 

20## CLAUDE.md imports24## CLAUDE.md imports

21 25 

22CLAUDE.md files can import additional files using `@path/to/import` syntax. The following example imports 3 files:26CLAUDE.md files can import additional files using `@path/to/import` syntax. The following example imports 3 files:

28- git workflow @docs/git-instructions.md32- git workflow @docs/git-instructions.md

29```33```

30 34 

31Both relative and absolute paths are allowed. In particular, importing files in user's home dir is a convenient way for your team members to provide individual instructions that are not checked into the repository. Previously CLAUDE.local.md served a similar purpose, but is now deprecated in favor of imports since they work better across multiple git worktrees.35Both relative and absolute paths are allowed. In particular, importing files in user's home dir is a convenient way for your team members to provide individual instructions that are not checked into the repository. Imports are an alternative to CLAUDE.local.md that work better across multiple git worktrees.

32 36 

33```37```

34# Individual Preferences38# Individual Preferences

60| Key | Description | Example |60| Key | Description | Example |

61| :--------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------- |61| :--------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------- |

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

63| `cleanupPeriodDays` | How long to locally retain chat transcripts based on last activity date (default: 30 days) | `20` |63| `cleanupPeriodDays` | Sessions inactive for longer than this period are deleted at startup. Setting to `0` immediately deletes all sessions. (default: 30 days) | `20` |

64| `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"]` |64| `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"]` |

65| `env` | Environment variables that will be applied to every session | `{"FOO": "bar"}` |65| `env` | Environment variables that will be applied to every session | `{"FOO": "bar"}` |

66| `includeCoAuthoredBy` | Whether to include the `co-authored-by Claude` byline in git commits and pull requests (default: `true`) | `false` |66| `includeCoAuthoredBy` | Whether to include the `co-authored-by Claude` byline in git commits and pull requests (default: `true`) | `false` |

340| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | Set to `1` to disable automatic terminal title updates based on conversation context |340| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | Set to `1` to disable automatic terminal title updates based on conversation context |

341| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | Skip auto-installation of IDE extensions |341| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | Skip auto-installation of IDE extensions |

342| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | Set the maximum number of output tokens for most requests |342| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | Set the maximum number of output tokens for most requests |

343| `CLAUDE_CODE_SHELL_PREFIX` | Command prefix to wrap all bash commands (e.g., for logging or auditing). Example: `/path/to/logger.sh` will execute `/path/to/logger.sh <command>` |

343| `CLAUDE_CODE_SKIP_BEDROCK_AUTH` | Skip AWS authentication for Bedrock (e.g. when using an LLM gateway) |344| `CLAUDE_CODE_SKIP_BEDROCK_AUTH` | Skip AWS authentication for Bedrock (e.g. when using an LLM gateway) |

344| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | Skip Azure authentication for Microsoft Foundry (e.g. when using an LLM gateway) |345| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | Skip Azure authentication for Microsoft Foundry (e.g. when using an LLM gateway) |

345| `CLAUDE_CODE_SKIP_VERTEX_AUTH` | Skip Google authentication for Vertex (e.g. when using an LLM gateway) |346| `CLAUDE_CODE_SKIP_VERTEX_AUTH` | Skip Google authentication for Vertex (e.g. when using an LLM gateway) |

378Claude Code has access to a set of powerful tools that help it understand and modify your codebase:379Claude Code has access to a set of powerful tools that help it understand and modify your codebase:

379 380 

380| Tool | Description | Permission Required |381| Tool | Description | Permission Required |

381| :------------------ | :--------------------------------------------------------------------------------- | :------------------ |382| :------------------ | :------------------------------------------------------------------------------------------------ | :------------------ |

382| **AskUserQuestion** | Asks the user multiple choice questions to gather information or clarify ambiguity | No |383| **AskUserQuestion** | Asks the user multiple choice questions to gather information or clarify ambiguity | No |

383| **Bash** | Executes shell commands in your environment | Yes |384| **Bash** | Executes shell commands in your environment (see [Bash tool behavior](#bash-tool-behavior) below) | Yes |

384| **BashOutput** | Retrieves output from a background bash shell | No |385| **BashOutput** | Retrieves output from a background bash shell | No |

385| **Edit** | Makes targeted edits to specific files | Yes |386| **Edit** | Makes targeted edits to specific files | Yes |

386| **ExitPlanMode** | Prompts the user to exit plan mode and start coding | Yes |387| **ExitPlanMode** | Prompts the user to exit plan mode and start coding | Yes |

399 400 

400Permission 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).401Permission 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).

401 402 

403### Bash tool behavior

404 

405The Bash tool executes shell commands with the following persistence behavior:

406 

407* **Working directory persists**: When Claude changes the working directory (e.g., `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.

408* **Environment variables do NOT persist**: Environment variables set in one Bash command (e.g., `export MY_VAR=value`) are **not** available in subsequent Bash commands. Each Bash command runs in a fresh shell environment.

409 

410To make environment variables available in Bash commands, you have **three options**:

411 

412**Option 1: Activate environment before starting Claude Code** (simplest approach)

413 

414Activate your virtual environment in your terminal before launching Claude Code:

415 

416```bash theme={null}

417conda activate myenv

418# or: source /path/to/venv/bin/activate

419claude

420```

421 

422This works for shell environments but environment variables set within Claude's Bash commands will not persist between commands.

423 

424**Option 2: Set CLAUDE\_ENV\_FILE before starting Claude Code** (persistent environment setup)

425 

426Export the path to a shell script containing your environment setup:

427 

428```bash theme={null}

429export CLAUDE_ENV_FILE=/path/to/env-setup.sh

430claude

431```

432 

433Where `/path/to/env-setup.sh` contains:

434 

435```bash theme={null}

436conda activate myenv

437# or: source /path/to/venv/bin/activate

438# or: export MY_VAR=value

439```

440 

441Claude Code will source this file before each Bash command, making the environment persistent across all commands.

442 

443**Option 3: Use a SessionStart hook** (project-specific configuration)

444 

445Configure in `.claude/settings.json`:

446 

447```json theme={null}

448{

449 "hooks": {

450 "SessionStart": [{

451 "matcher": "startup",

452 "hooks": [{

453 "type": "command",

454 "command": "echo 'conda activate myenv' >> \"$CLAUDE_ENV_FILE\""

455 }]

456 }]

457 }

458}

459```

460 

461The hook writes to `$CLAUDE_ENV_FILE`, which is then sourced before each Bash command. This is ideal for team-shared project configurations.

462 

463See [SessionStart hooks](/en/hooks#persisting-environment-variables) for more details on Option 3.

464 

402### Extending tools with hooks465### Extending tools with hooks

403 466 

404You can run custom commands before or after any tool executes using467You can run custom commands before or after any tool executes using

221# ... create subagent file221# ... create subagent file

222```222```

223 223 

224<Note>

225 Subagents created by manually adding files will be loaded the next time you start a Claude Code session. To create and use a subagent immediately without restarting, use the `/agents` command instead.

226</Note>

227 

224## Using subagents effectively228## Using subagents effectively

225 229 

226### Automatic delegation230### Automatic delegation