Documentation 2026-05-26 06:33 UTC to 2026-05-27 06:42 UTC

132 132 

133* [Server-managed settings](/en/server-managed-settings): deliver managed policy from the Claude admin console133* [Server-managed settings](/en/server-managed-settings): deliver managed policy from the Claude admin console

134* [Settings reference](/en/settings): every setting key, file location, and precedence rule134* [Settings reference](/en/settings): every setting key, file location, and precedence rule

135* [Monorepos and large repos](/en/large-codebases): per-directory configuration patterns for organizations deploying into a monorepo

135* [Amazon Bedrock](/en/amazon-bedrock), [Google Vertex AI](/en/google-vertex-ai), [Microsoft Foundry](/en/microsoft-foundry): provider-specific deployment136* [Amazon Bedrock](/en/amazon-bedrock), [Google Vertex AI](/en/google-vertex-ai), [Microsoft Foundry](/en/microsoft-foundry): provider-specific deployment

136* [Claude Enterprise Administrator Guide](https://claude.com/resources/tutorials/claude-enterprise-administrator-guide): SSO, SCIM, seat management, and rollout playbook137* [Claude Enterprise Administrator Guide](https://claude.com/resources/tutorials/claude-enterprise-administrator-guide): SSO, SCIM, seat management, and rollout playbook

223 223 

224* **Summarization instructions in CLAUDE.md:** The compactor reads your CLAUDE.md like any other context, so you can include a section telling it what to preserve when summarizing. The section header is free-form (not a magic string); the compactor matches on intent.224* **Summarization instructions in CLAUDE.md:** The compactor reads your CLAUDE.md like any other context, so you can include a section telling it what to preserve when summarizing. The section header is free-form (not a magic string); the compactor matches on intent.

225* **`PreCompact` hook:** Run custom logic before compaction occurs, for example to archive the full transcript. The hook receives a `trigger` field (`manual` or `auto`). See [hooks](/en/agent-sdk/hooks).225* **`PreCompact` hook:** Run custom logic before compaction occurs, for example to archive the full transcript. The hook receives a `trigger` field (`manual` or `auto`). See [hooks](/en/agent-sdk/hooks).

226* **Manual compaction:** Send `/compact` as a prompt string to trigger compaction on demand. (Slash commands sent this way are SDK inputs, not CLI-only shortcuts. See [slash commands in the SDK](/en/agent-sdk/slash-commands).)226* **Manual compaction:** Send `/compact` as a prompt string to trigger compaction on demand. Commands sent this way are SDK inputs, not CLI-only shortcuts. See [commands in the SDK](/en/agent-sdk/slash-commands).

227 227 

228<Accordion title="Example: Summarization instructions in CLAUDE.md">228<Accordion title="Example: Summarization instructions in CLAUDE.md">

229 Add a section to your project's CLAUDE.md telling the compactor what to preserve. The header name isn't special; use any clear label.229 Add a section to your project's CLAUDE.md telling the compactor what to preserve. The header name isn't special; use any clear label.

473The SDK also supports Claude Code's filesystem-based configuration. With default options the SDK loads these from `.claude/` in your working directory and `~/.claude/`. To restrict which sources load, set `setting_sources` (Python) or `settingSources` (TypeScript) in your options.473The SDK also supports Claude Code's filesystem-based configuration. With default options the SDK loads these from `.claude/` in your working directory and `~/.claude/`. To restrict which sources load, set `setting_sources` (Python) or `settingSources` (TypeScript) in your options.

474 474 

475| Feature | Description | Location |475| Feature | Description | Location |

476| ------------------------------------------------ | ---------------------------------------------------- | ---------------------------------- |476| ------------------------------------------------ | ----------------------------------------------------------------------------- | ---------------------------------- |

477| [Skills](/en/agent-sdk/skills) | Specialized capabilities defined in Markdown | `.claude/skills/*/SKILL.md` |477| [Skills](/en/agent-sdk/skills) | Specialized capabilities Claude uses automatically or you invoke with `/name` | `.claude/skills/*/SKILL.md` |

478| [Slash commands](/en/agent-sdk/slash-commands) | Custom commands for common tasks | `.claude/commands/*.md` |478| [Commands](/en/agent-sdk/slash-commands) | Custom commands in the legacy format. Use skills for new custom commands | `.claude/commands/*.md` |

479| [Memory](/en/agent-sdk/modifying-system-prompts) | Project context and instructions | `CLAUDE.md` or `.claude/CLAUDE.md` |479| [Memory](/en/agent-sdk/modifying-system-prompts) | Project context and instructions | `CLAUDE.md` or `.claude/CLAUDE.md` |

480| [Plugins](/en/agent-sdk/plugins) | Extend with custom commands, agents, and MCP servers | Programmatic via `plugins` option |480| [Plugins](/en/agent-sdk/plugins) | Extend with skills, agents, hooks, and MCP servers | Programmatic via `plugins` option |

481 481 

482## Compare the Agent SDK to other Claude tools482## Compare the Agent SDK to other Claude tools

483 483 

4 4 

5# Plugins in the SDK5# Plugins in the SDK

6 6 

7> Load custom plugins to extend Claude Code with commands, agents, skills, and hooks through the Agent SDK7> Load custom plugins to extend Claude Code with skills, agents, hooks, and MCP servers through the Agent SDK

8 8 

9Plugins allow you to extend Claude Code with custom functionality that can be shared across projects. Through the Agent SDK, you can programmatically load plugins from local directories to add custom slash commands, agents, skills, hooks, and MCP servers to your agent sessions.9Plugins allow you to extend Claude Code with custom functionality that can be shared across projects. Through the Agent SDK, you can programmatically load plugins from local directories to add skills, agents, hooks, and MCP servers to your agent sessions.

10 10 

11## What are plugins?11## What are plugins?

12 12 

97 console.log("Plugins:", message.plugins);97 console.log("Plugins:", message.plugins);

98 // Example: [{ name: "my-plugin", path: "./my-plugin" }]98 // Example: [{ name: "my-plugin", path: "./my-plugin" }]

99 99 

100 // Check available commands from plugins100 // Plugin skills appear with the plugin name as a prefix

101 console.log("Skills:", message.skills);

102 // Example: ["my-plugin:greet"]

103 

104 // Plugin commands use the same prefix, and skills appear here too

101 console.log("Commands:", message.slash_commands);105 console.log("Commands:", message.slash_commands);

102 // Example: ["compact", "context", "my-plugin:custom-command"]106 // Example: ["compact", "context", "my-plugin:custom-command", "my-plugin:greet"]

103 }107 }

104 }108 }

105 ```109 ```

121 print("Plugins:", message.data.get("plugins"))125 print("Plugins:", message.data.get("plugins"))

122 # Example: [{"name": "my-plugin", "path": "./my-plugin"}]126 # Example: [{"name": "my-plugin", "path": "./my-plugin"}]

123 127 

124 # Check available commands from plugins128 # Plugin skills appear with the plugin name as a prefix

129 print("Skills:", message.data.get("skills"))

130 # Example: ["my-plugin:greet"]

131 

132 # Plugin commands use the same prefix, and skills appear here too

125 print("Commands:", message.data.get("slash_commands"))133 print("Commands:", message.data.get("slash_commands"))

126 # Example: ["compact", "context", "my-plugin:custom-command"]134 # Example: ["compact", "context", "my-plugin:custom-command", "my-plugin:greet"]

127 135 

128 136 

129 asyncio.run(main())137 asyncio.run(main())

132 140 

133## Using plugin skills141## Using plugin skills

134 142 

135Skills from plugins are automatically namespaced with the plugin name to avoid conflicts. When invoked as slash commands, the format is `plugin-name:skill-name`.143Skills from plugins are automatically namespaced with the plugin name to avoid conflicts. To invoke one directly, send `/plugin-name:skill-name` as the prompt.

136 144 

137<CodeGroup>145<CodeGroup>

138 ```typescript TypeScript theme={null}146 ```typescript TypeScript theme={null}

203 })) {211 })) {

204 if (message.type === "system" && message.subtype === "init") {212 if (message.type === "system" && message.subtype === "init") {

205 console.log("Loaded plugins:", message.plugins);213 console.log("Loaded plugins:", message.plugins);

214 console.log("Available skills:", message.skills);

206 console.log("Available commands:", message.slash_commands);215 console.log("Available commands:", message.slash_commands);

207 }216 }

208 217 

246 ):255 ):

247 if isinstance(message, SystemMessage) and message.subtype == "init":256 if isinstance(message, SystemMessage) and message.subtype == "init":

248 print(f"Loaded plugins: {message.data.get('plugins')}")257 print(f"Loaded plugins: {message.data.get('plugins')}")

258 print(f"Available skills: {message.data.get('skills')}")

249 print(f"Available commands: {message.data.get('slash_commands')}")259 print(f"Available commands: {message.data.get('slash_commands')}")

250 260 

251 if isinstance(message, AssistantMessage):261 if isinstance(message, AssistantMessage):

327 337 

328If plugin skills don't work:338If plugin skills don't work:

329 339 

3301. **Use the namespace**: Plugin skills require the `plugin-name:skill-name` format when invoked as slash commands3401. **Use the namespace**: invoke plugin skills as `/plugin-name:skill-name`

3312. **Check init message**: Verify the skill appears in `slash_commands` with the correct namespace3412. **Check init message**: verify the skill appears in the `skills` list with the correct namespace

3323. **Validate skill files**: Ensure each skill has a `SKILL.md` file in its own subdirectory under `skills/` (for example, `skills/my-skill/SKILL.md`)3423. **Validate skill files**: ensure each skill has a `SKILL.md` file in its own subdirectory under `skills/`, for example `skills/my-skill/SKILL.md`

333 343 

334### Path resolution issues344### Path resolution issues

335 345 

343 353 

344* [Plugins](/en/plugins) - Complete plugin development guide354* [Plugins](/en/plugins) - Complete plugin development guide

345* [Plugins reference](/en/plugins-reference) - Technical specifications355* [Plugins reference](/en/plugins-reference) - Technical specifications

346* [Slash Commands](/en/agent-sdk/slash-commands) - Using slash commands in the SDK356* [Commands](/en/agent-sdk/slash-commands) - Using commands in the SDK

347* [Subagents](/en/agent-sdk/subagents) - Working with specialized agents357* [Subagents](/en/agent-sdk/subagents) - Working with specialized agents

348* [Skills](/en/agent-sdk/skills) - Using Agent Skills358* [Skills](/en/agent-sdk/skills) - Using Agent Skills

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

224 224 

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

226* When using Bedrock, the `/login` and `/logout` commands are disabled since authentication is handled through AWS credentials.226* When using Bedrock, the `/logout` command is unavailable since authentication is handled through AWS credentials.

227* You can use settings files for environment variables like `AWS_PROFILE` that you don't want to leak to other processes. See [Settings](/en/settings) for more information.227* You can use settings files for environment variables like `AWS_PROFILE` that you don't want to leak to other processes. See [Settings](/en/settings) for more information.

228 228 

229### 4. Pin model versions229### 4. Pin model versions

130```130```

131 131 

132<Note>132<Note>

133 When using Microsoft Foundry, the `/login` and `/logout` commands are disabled since authentication is handled through Azure credentials.133 When using Microsoft Foundry, the `/logout` command is unavailable since authentication is handled through Azure credentials.

134</Note>134</Note>

135 135 

136### 3. Configure Claude Code136### 3. Configure Claude Code

44 44 

45Your verification can also be a test suite, a linter, or a Bash command that checks output. Invest in making your verification rock-solid.45Your verification can also be a test suite, a linter, or a Bash command that checks output. Invest in making your verification rock-solid.

46 46 

47Have Claude show evidence rather than asserting success: the test output, the command it ran and what it returned, or a screenshot of the result. Reviewing evidence is faster than re-running the verification yourself, and it works for sessions you weren't watching.

48 

47***49***

48 50 

49## Explore first, then plan, then code51## Explore first, then plan, then code

198* **Project root (`./CLAUDE.md`)**: check into git to share with your team200* **Project root (`./CLAUDE.md`)**: check into git to share with your team

199* **Project root (`./CLAUDE.local.md`)**: personal project-specific notes; add this file to your `.gitignore` so it isn't shared with your team201* **Project root (`./CLAUDE.local.md`)**: personal project-specific notes; add this file to your `.gitignore` so it isn't shared with your team

200* **Parent directories**: useful for monorepos where both `root/CLAUDE.md` and `root/foo/CLAUDE.md` are pulled in automatically202* **Parent directories**: useful for monorepos where both `root/CLAUDE.md` and `root/foo/CLAUDE.md` are pulled in automatically

201* **Child directories**: Claude pulls in child CLAUDE.md files on demand when working with files in those directories203* **Child directories**: Claude pulls in child CLAUDE.md files on demand when it reads a file in those directories

202 204 

203### Configure permissions205### Configure permissions

204 206 

362 364 

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

364 366 

367The most useful specs are self-contained: they name the files and interfaces involved, state what is out of scope, and end with an end-to-end verification step that proves the feature works. Time spent making the spec precise pays off more than time spent watching the implementation.

368 

365***369***

366 370 

367## Manage your session371## Manage your session

454### Run non-interactive mode458### Run non-interactive mode

455 459 

456<Tip>460<Tip>

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

458</Tip>462</Tip>

459 463 

460With `claude -p "your prompt"`, you can run Claude non-interactively, without a session. [Non-interactive mode](/en/headless) is how you integrate Claude into CI pipelines, pre-commit hooks, or any automated workflow. The output formats let you parse results programmatically: plain text, JSON, or streaming JSON.464With `claude -p "your prompt"`, you can run Claude non-interactively, without a session. [Non-interactive mode](/en/headless) is how you integrate Claude into CI pipelines, pre-commit hooks, or any automated workflow. The output formats let you parse results programmatically: plain text, JSON, or streaming JSON.

467claude -p "List all API endpoints" --output-format json471claude -p "List all API endpoints" --output-format json

468 472 

469# Streaming for real-time processing473# Streaming for real-time processing

470claude -p "Analyze this log file" --output-format stream-json474claude -p "Analyze this log file" --output-format stream-json --verbose

471```475```

472 476 

473### Run multiple Claude sessions477### Run multiple Claude sessions

540 544 

541For non-interactive runs with the `-p` flag, auto mode aborts if the classifier repeatedly blocks actions, since there is no user to fall back to. See [when auto mode falls back](/en/permission-modes#when-auto-mode-falls-back) for thresholds.545For non-interactive runs with the `-p` flag, auto mode aborts if the classifier repeatedly blocks actions, since there is no user to fall back to. See [when auto mode falls back](/en/permission-modes#when-auto-mode-falls-back) for thresholds.

542 546 

547### Add an adversarial review step

548 

549<Tip>

550 Before treating a task as done, have a subagent review the diff in a fresh context and report gaps.

551</Tip>

552 

553The longer Claude works unattended, the more an independent check matters before you count the work as done. A reviewer running in a fresh [subagent](/en/sub-agents) context sees only the diff and the criteria you give it, not the reasoning that produced the change, so it evaluates the result on its own terms.

554 

555For a correctness check, run the bundled [`/code-review` skill](/en/commands), which reviews the current diff for bugs in a fresh subagent and returns findings to the session. To check the diff against your plan instead, write the review prompt yourself. Name the work to check, the plan to check it against, and what counts as a finding:

556 

557```text theme={null}

558Use a subagent to review the rate limiter diff against PLAN.md. Check that

559every requirement is implemented, the listed edge cases have tests, and

560nothing outside the task's scope changed. Report gaps, not style preferences.

561```

562 

563Because the reviewer runs as a subagent, the implementing session receives the gaps directly and can fix them and re-review without you copying findings between windows. For longer autonomous runs, an [agent team](/en/agent-teams) can keep this loop going across many tasks while you spot-check the recorded findings.

564 

565<Callout>

566 A reviewer prompted to find gaps will usually report some, even when the work is sound, because that is what it was asked to do. Chasing every finding leads to over-engineering: extra abstraction layers, defensive code, and tests for cases that can't happen. Tell the reviewer to flag only gaps that affect correctness or the stated requirements, and treat the rest as optional.

567</Callout>

568 

543***569***

544 570 

545## Avoid common failure patterns571## Avoid common failure patterns

46Customize Claude Code's behavior with these command-line flags. `claude --help` does not list every flag, so a flag's absence from `--help` does not mean it is unavailable.46Customize Claude Code's behavior with these command-line flags. `claude --help` does not list every flag, so a flag's absence from `--help` does not mean it is unavailable.

47 47 

48| Flag | Description | Example |48| Flag | Description | Example |

49| :---------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------- |49| :---------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------- |

50| `--add-dir` | Add additional working directories for Claude to read and edit files. Grants file access; most `.claude/` configuration is [not discovered](/en/permissions#additional-directories-grant-file-access-not-configuration) from these directories. Validates each path exists as a directory. To persist these directories across sessions, set [`permissions.additionalDirectories`](/en/settings#permission-settings) in settings | `claude --add-dir ../apps ../lib` |50| `--add-dir` | Add additional working directories for Claude to read and edit files. Grants file access; most `.claude/` configuration is [not discovered](/en/permissions#additional-directories-grant-file-access-not-configuration) from these directories. Validates each path exists as a directory. To persist these directories across sessions, set [`permissions.additionalDirectories`](/en/settings#permission-settings) in settings | `claude --add-dir ../apps ../lib` |

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

52| `--agents` | Define custom subagents dynamically via JSON. Uses the same field names as subagent [frontmatter](/en/sub-agents#supported-frontmatter-fields), plus a `prompt` field for the agent's instructions | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` |52| `--agents` | Define custom subagents dynamically via JSON. Uses the same field names as subagent [frontmatter](/en/sub-agents#supported-frontmatter-fields), plus a `prompt` field for the agent's instructions | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` |

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

76| `--init` | Run [Setup hooks](/en/hooks#setup) with the `init` matcher before the session (print mode only) | `claude -p --init "query"` |76| `--init` | Run [Setup hooks](/en/hooks#setup) with the `init` matcher before the session (print mode only) | `claude -p --init "query"` |

77| `--init-only` | Run [Setup](/en/hooks#setup) and `SessionStart` hooks, then exit without starting a conversation | `claude --init-only` |77| `--init-only` | Run [Setup](/en/hooks#setup) and `SessionStart` hooks, then exit without starting a conversation | `claude --init-only` |

78| `--include-hook-events` | Include all hook lifecycle events in the output stream. Requires `--output-format stream-json` | `claude -p --output-format stream-json --include-hook-events "query"` |78| `--include-hook-events` | Include all hook lifecycle events in the output stream. Requires `--output-format stream-json` | `claude -p --output-format stream-json --verbose --include-hook-events "query"` |

79| `--include-partial-messages` | Include partial streaming events in output. Requires `--print` and `--output-format stream-json` | `claude -p --output-format stream-json --include-partial-messages "query"` |79| `--include-partial-messages` | Include partial streaming events in output. Requires `--print` and `--output-format stream-json` | `claude -p --output-format stream-json --verbose --include-partial-messages "query"` |

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

81| `--json-schema` | Get validated JSON output matching a JSON Schema after agent completes its workflow (print mode only, see [structured outputs](/en/agent-sdk/structured-outputs)) | `claude -p --json-schema '{"type":"object","properties":{...}}' "query"` |81| `--json-schema` | Get validated JSON output matching a JSON Schema after agent completes its workflow (print mode only, see [structured outputs](/en/agent-sdk/structured-outputs)) | `claude -p --json-schema '{"type":"object","properties":{...}}' "query"` |

82| `--maintenance` | Run [Setup hooks](/en/hooks#setup) with the `maintenance` matcher before the session (print mode only) | `claude -p --maintenance "query"` |82| `--maintenance` | Run [Setup hooks](/en/hooks#setup) with the `maintenance` matcher before the session (print mode only) | `claude -p --maintenance "query"` |

96| `--remote` | Create a new [web session](/en/claude-code-on-the-web) on claude.ai with the provided task description | `claude --remote "Fix the login bug"` |96| `--remote` | Create a new [web session](/en/claude-code-on-the-web) on claude.ai with the provided task description | `claude --remote "Fix the login bug"` |

97| `--remote-control`, `--rc` | Start an interactive session with [Remote Control](/en/remote-control#start-a-remote-control-session) enabled so you can also control it from claude.ai or the Claude app. Optionally pass a name for the session | `claude --remote-control "My Project"` |97| `--remote-control`, `--rc` | Start an interactive session with [Remote Control](/en/remote-control#start-a-remote-control-session) enabled so you can also control it from claude.ai or the Claude app. Optionally pass a name for the session | `claude --remote-control "My Project"` |

98| `--remote-control-session-name-prefix <prefix>` | Prefix for auto-generated [Remote Control](/en/remote-control) session names when no explicit name is set. Defaults to your machine's hostname, producing names like `myhost-graceful-unicorn`. Set `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` for the same effect | `claude remote-control --remote-control-session-name-prefix dev-box` |98| `--remote-control-session-name-prefix <prefix>` | Prefix for auto-generated [Remote Control](/en/remote-control) session names when no explicit name is set. Defaults to your machine's hostname, producing names like `myhost-graceful-unicorn`. Set `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` for the same effect | `claude remote-control --remote-control-session-name-prefix dev-box` |

99| `--replay-user-messages` | Re-emit user messages from stdin back on stdout for acknowledgment. Requires `--input-format stream-json` and `--output-format stream-json` | `claude -p --input-format stream-json --output-format stream-json --replay-user-messages` |99| `--replay-user-messages` | Re-emit user messages from stdin back on stdout for acknowledgment. Requires `--input-format stream-json` and `--output-format stream-json` | `claude -p --input-format stream-json --output-format stream-json --verbose --replay-user-messages` |

100| `--resume`, `-r` | Resume a specific session by ID or name, or show an interactive picker to choose a session. Includes sessions that added this directory with `/add-dir`. As of v2.1.144, [background sessions](/en/agent-view) appear in the picker marked with `bg` | `claude --resume auth-refactor` |100| `--resume`, `-r` | Resume a specific session by ID or name, or show an interactive picker to choose a session. Includes sessions that added this directory with `/add-dir`. As of v2.1.144, [background sessions](/en/agent-view) appear in the picker marked with `bg` | `claude --resume auth-refactor` |

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

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

23 23 

24### Understand new codebases24### Understand new codebases

25 25 

26For configuring Claude Code in a monorepo or large codebase, see [Monorepos and large repos](/en/large-codebases).

27 

26#### Get a quick codebase overview28#### Get a quick codebase overview

27 29 

28Suppose you've just joined a new project and need to understand its structure quickly.30Suppose you've just joined a new project and need to understand its structure quickly.

90* **Communication**: `slack`90* **Communication**: `slack`

91* **Monitoring**: `sentry`91* **Monitoring**: `sentry`

92 92 

93### Automatic security review

94 

95The `security-guidance` plugin reviews each change Claude makes for common vulnerabilities and instructs Claude to fix what it finds in the same session. See [Catch security issues as Claude writes code](/en/security-guidance) for what it checks and how to add project-specific rules.

96 

93### Development workflows97### Development workflows

94 98 

95Plugins that add skills and agents for common development tasks:99Plugins that add skills and agents for common development tasks:

200 200 

201Most model versions have a corresponding `VERTEX_REGION_CLAUDE_*` variable. See the [Environment variables reference](/en/env-vars) for the full list. Check [Vertex Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) to determine which models support global endpoints versus regional only.201Most model versions have a corresponding `VERTEX_REGION_CLAUDE_*` variable. See the [Environment variables reference](/en/env-vars) for the full list. Check [Vertex Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) to determine which models support global endpoints versus regional only.

202 202 

203[Prompt caching](/en/prompt-caching) is enabled automatically. To disable it, set `DISABLE_PROMPT_CACHING=1`. To request a 1-hour cache TTL instead of the 5-minute default, set `ENABLE_PROMPT_CACHING_1H=1`; cache writes with a 1-hour TTL are billed at a higher rate. For heightened rate limits, contact Google Cloud support. When using Vertex AI, the `/login` and `/logout` commands are disabled since authentication is handled through Google Cloud credentials.203[Prompt caching](/en/prompt-caching) is enabled automatically. To disable it, set `DISABLE_PROMPT_CACHING=1`. To request a 1-hour cache TTL instead of the 5-minute default, set `ENABLE_PROMPT_CACHING_1H=1`; cache writes with a 1-hour TTL are billed at a higher rate. For heightened rate limits, contact Google Cloud support. When using Vertex AI, the `/logout` command is unavailable since authentication is handled through Google Cloud credentials.

204 204 

205Claude Code disables [MCP tool search](/en/mcp#scale-with-mcp-tool-search) by default on Vertex AI, so MCP tool definitions load upfront. Vertex AI supports tool search for Claude Sonnet 4.5 and later and Claude Opus 4.5 and later. Set `ENABLE_TOOL_SEARCH=true` to enable it on those models. Earlier models on Vertex AI do not accept the required beta header, and requests fail if you enable tool search with them.205Claude Code disables [MCP tool search](/en/mcp#scale-with-mcp-tool-search) by default on Vertex AI, so MCP tool definitions load upfront. Vertex AI supports tool search for Claude Sonnet 4.5 and later and Claude Opus 4.5 and later. Set `ENABLE_TOOL_SEARCH=true` to enable it on those models. Earlier models on Vertex AI do not accept the required beta header, and requests fail if you enable tool search with them.

206 206 

93* [Reload environment when directory or files change](#reload-environment-when-directory-or-files-change)93* [Reload environment when directory or files change](#reload-environment-when-directory-or-files-change)

94* [Auto-approve specific permission prompts](#auto-approve-specific-permission-prompts)94* [Auto-approve specific permission prompts](#auto-approve-specific-permission-prompts)

95 95 

96For a production example of hooks that run a separate model review and feed findings back into the session, see [how the `security-guidance` plugin integrates with Claude Code](/en/security-guidance#how-the-plugin-integrates-with-claude-code).

97 

96### Get notified when Claude needs input98### Get notified when Claude needs input

97 99 

98Get a desktop notification whenever Claude finishes working and needs your input, so you can switch to other tasks without checking the terminal.100Get a desktop notification whenever Claude finishes working and needs your input, so you can switch to other tasks without checking the terminal.

1> ## Documentation Index

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

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

4 

5# Set up Claude Code in a monorepo or large codebase

6 

7> Configure Claude Code for monorepos and large single-tree codebases with nested CLAUDE.md files, sparse worktrees, code intelligence, and per-package skills so Claude stays focused on the code you're working in.

8 

9A large codebase can be one repository with millions of lines or a monorepo with many packages. Claude Code works at any size, but as the codebase grows, the defaults tuned for smaller projects can fill the context window with instructions and file reads unrelated to the task, costing tokens and degrading Claude's performance.

10 

11This guide shows individual developers and engineering teams how to scope Claude to the part of the codebase a task touches. Each section notes whether a setting is personal to your machine or committed to the repository.

12 

13## What this guide covers

14 

15The [table below](#settings-on-this-page) lists each setting and what it accomplishes. The [file tree after it](#the-example-monorepo) is the example monorepo every code sample on this page refers to.

16 

17### Settings on this page

18 

19Each setting below is independent. They layer rather than replace each other, so apply whichever fit your repository. [Choose where to start Claude](#choose-where-to-start-claude) determines where your settings files live, so read it first. [Put it together](#put-it-together) shows all of them combined.

20 

21| I want to | Use |

22| :-------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------- |

23| Load only the conventions for the code you touch, instead of one root file covering every subsystem | Per-directory [CLAUDE.md files](#layer-claude-md-files-by-directory) |

24| Exclude CLAUDE.md files for packages you never work in | [`claudeMdExcludes`](#exclude-irrelevant-claude-md-files) |

25| Block Claude from opening build output, generated code, and vendored dependencies | [`Read` deny rules](#block-reads-of-generated-and-vendored-code) in `permissions.deny` |

26| Find a symbol's definition or callers through the language server instead of scanning files | A [code intelligence plugin](#reduce-file-reads-with-code-intelligence) |

27| Check out only the directories a task needs when Claude creates a worktree | [`worktree.sparsePaths`](#check-out-only-the-directories-you-need) |

28| Read and edit a sibling package or another repository from the same session | [`--add-dir`](#grant-access-across-packages-or-repositories) or `additionalDirectories` |

29| Give Claude procedures specific to one area that load only when relevant | Per-directory [skills](#add-per-directory-skills) |

30| Replace many per-directory CLAUDE.md files with one set of conventions everyone installs | A [plugin](#centralize-conventions-when-layering-stops-scaling) in an internal marketplace |

31 

32<Tip>

33 For workflow techniques that keep context small in any repository, such as [running exploration in a subagent](/en/best-practices#use-subagents-for-investigation) so file reads stay out of the main conversation, see [Best practices for Claude Code](/en/best-practices). To roll out a baseline configuration to every developer in your organization, see [Set up Claude Code for your organization](/en/admin-setup).

34</Tip>

35 

36### The example monorepo

37 

38The examples throughout this page refer to a monorepo with three packages. The same patterns work in a large single-tree codebase: where an example uses `packages/api/`, substitute your own subsystem directory such as `src/backend/` or `lib/core/`.

39 

40```text theme={null}

41monorepo/

42 CLAUDE.md # root instructions

43 packages/

44 api/

45 CLAUDE.md # API-specific instructions

46 .claude/skills/

47 src/

48 web/

49 CLAUDE.md # frontend-specific instructions

50 .claude/skills/

51 src/

52 shared/

53 CLAUDE.md # shared library instructions

54 src/

55```

56 

57## Choose where to start Claude

58 

59Where you launch `claude` determines which files Claude can read and edit without an additional permission grant, which CLAUDE.md files load into context at startup, and which project settings apply.

60 

61| Start from | File access | CLAUDE.md loaded at launch | Use when |

62| :-------------- | :-------------------------------------- | :------------------------------------------------------------------- | :----------------------------------------- |

63| Repository root | Every file | Root only; subdirectory files load on demand when Claude reads there | Tasks span multiple packages or subsystems |

64| A subdirectory | That subtree only, until you grant more | That directory's plus every ancestor's | Work is scoped to one package or subsystem |

65 

66Project settings in `.claude/settings.json` load only from your starting directory and are not inherited from parent directories the way CLAUDE.md files are: a `.claude/settings.json` at the repository root applies only when you start from the root.

67 

68Each section below states whether its settings file belongs at the repository root or in the subdirectory you start from, and whether it is committed or kept local.

69 

70## Layer CLAUDE.md files by directory

71 

72In a large codebase, a single CLAUDE.md at the repository root tends to either grow to cover every subsystem's conventions, costing context on instructions unrelated to the current task, or stay too generic to be useful. Splitting instructions across per-directory files means Claude loads repository-wide rules plus only the conventions for the code you're working in.

73 

74Claude Code loads every [CLAUDE.md](/en/memory) file from your working directory and every parent directory at launch, then loads each subdirectory's file on demand when it reads files there. A root file sets repository-wide rules and each subdirectory adds its own.

75 

76A common split is two levels:

77 

78* **Root `CLAUDE.md`**: instructions that apply everywhere, such as coding standards, commit conventions, and repository layout

79* **Per-subdirectory `CLAUDE.md`**: conventions specific to that area's stack. In a monorepo that's one per package. In a large single tree it's one per subsystem such as `src/db/` or `src/api/`

80 

81Commit these files to the repository so teammates inherit them. Each directory's owner typically maintains its file.

82 

83The root `CLAUDE.md` orients Claude to the repository structure:

84 

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

86This is a monorepo with three packages under packages/:

87 

88- packages/api: Node.js REST API with Express, TypeScript, and PostgreSQL

89- packages/web: React frontend with Vite, TypeScript, and TailwindCSS

90- packages/shared: shared TypeScript utilities used by both api and web

91 

92Run commands from the package directory, not the monorepo root.

93Each package has its own tsconfig.json, package.json, and test suite.

94```

95 

96Each subdirectory's `CLAUDE.md`, here `packages/api/CLAUDE.md`, adds context specific to that area's stack:

97 

98```markdown packages/api/CLAUDE.md theme={null}

99This package is the REST API server.

100 

101- Run tests: `npm test` (uses Vitest)

102- Run dev server: `npm run dev` (port 3001)

103- Database migrations: `npm run migrate`

104- Environment variables: copy `.env.example` to `.env`

105 

106API routes are in src/routes/. Each route file exports an Express router.

107Database queries use Knex in src/db/. Never write raw SQL strings in route handlers.

108```

109 

110When you start Claude from `packages/api/`, it loads both `packages/api/CLAUDE.md` and the root `CLAUDE.md`. Claude sees the local instructions alongside the repository-wide rules, with no instructions from `packages/web/` in context. The same holds for any subdirectory in a non-monorepo tree.

111 

112A few ways to keep the files current as the codebase and models change:

113 

114* **Review in pull requests**: treat CLAUDE.md edits like any other documentation change so conventions track the code

115* **Revisit after major model releases**: instructions that worked around an older model's limitation may become overhead once a newer model handles the case on its own. For example, a rule that forces single-file refactors can be deleted once the limitation is gone

116* **Add a Stop hook that proposes updates**: a [`Stop` hook](/en/hooks#stop) receives the path to the session transcript when Claude finishes responding, so a script can review the session and propose CLAUDE.md updates while the gap it exposed is fresh

117 

118For more on how CLAUDE.md files load and interact, see [Memory and project instructions](/en/memory).

119 

120### Choose between per-directory CLAUDE.md and path-scoped rules

121 

122Per-directory `CLAUDE.md` files and [path-scoped rules](/en/memory#path-specific-rules) under `.claude/rules/` both let you target instructions to part of the tree. They differ in where the file lives and when it loads.

123 

124| Approach | File location | Loads when | Use when |

125| :----------------------------------- | :--------------------------------------- | :-------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------- |

126| Per-directory `CLAUDE.md` | Inside the directory, alongside its code | At launch when started from that directory, or on demand when Claude reads a file there | Directory owners maintain their own conventions; instructions are versioned with the code |

127| Path-scoped rule in `.claude/rules/` | Central `.claude/` at the repo root | When Claude works with a file matching the rule's `paths:` glob | You want all conventions in one place, or the same rule applies to many scattered paths |

128 

129For a comparison that also covers skills, see [Compare similar features](/en/features-overview#compare-similar-features).

130 

131### Exclude irrelevant CLAUDE.md files

132 

133When you start Claude from the repository root, each subdirectory's CLAUDE.md loads as soon as Claude reads a file in that directory. The `claudeMdExcludes` setting skips specific files by path or glob pattern so they never load.

134 

135Use this for directories you never work in, such as other teams' packages, legacy code, or vendored subtrees. The exclusion list is static, not a per-task switch. To focus on one package today and another tomorrow, [start Claude from that package's directory](#choose-where-to-start-claude) instead of editing exclusions.

136 

137If you only want these exclusions for yourself, put the setting in `.claude/settings.local.json`, which is gitignored and not committed. Patterns use glob syntax matched against absolute file paths, so start relative-style patterns with `**/` to match anywhere in the tree. The example below excludes packages owned by other teams:

138 

139```json .claude/settings.local.json theme={null}

140{

141 "claudeMdExcludes": [

142 "**/packages/admin-dashboard/**",

143 "**/packages/legacy-*/**"

144 ]

145}

146```

147 

148This skips every CLAUDE.md and rules file under those packages. The root CLAUDE.md and the packages you do work in still load normally.

149 

150These patterns cover other common cases:

151 

152* `"**/packages/*/CLAUDE.md"`: excludes every package's CLAUDE.md while keeping the root

153* `"**/packages/web/**"`: excludes everything under the web package, including rules

154* `"/home/user/monorepo/legacy/CLAUDE.md"`: excludes one specific file by absolute path

155 

156Managed policy CLAUDE.md files cannot be excluded, so organization-wide instructions always apply. You can set `claudeMdExcludes` at any [settings scope](/en/settings#configuration-scopes): user, project, local, or managed. Arrays merge across scopes, so a team can set project-level defaults while individuals add local overrides.

157 

158For the full exclusion documentation, see [Exclude specific CLAUDE.md files](/en/memory#exclude-specific-claude-md-files).

159 

160## Reduce what Claude reads

161 

162Instructions are only part of what ends up in Claude's context. File reads are another cost that grows with the codebase. The settings below block reads of irrelevant paths and replace exhaustive file scans with language-server lookups.

163 

164### Block reads of generated and vendored code

165 

166Claude's content searches respect `.gitignore` by default, so paths already listed there, such as `node_modules/`, `dist/`, and `build/`, stay out of search results without additional configuration.

167 

168For paths that are checked in, such as a vendored SDK or committed generated code, add `Read` deny rules in `permissions.deny` to block Claude from opening those files even when a search lists them.

169 

170To apply these exclusions for everyone working in the repository, commit them to `.claude/settings.json`. To keep them personal, use `.claude/settings.local.json` instead. Like other project settings on this page, these files load only from your starting directory. Place them at the repository root if you start Claude there, or in each package's `.claude/` if you start from subdirectories. To enforce the same deny rules in every session regardless of starting directory, set them in [managed settings](/en/settings#settings-files), which user and project settings cannot override.

171 

172The example below blocks build artifacts and a vendored SDK:

173 

174```json .claude/settings.json theme={null}

175{

176 "permissions": {

177 "deny": [

178 "Read(./**/dist/**)",

179 "Read(./**/build/**)",

180 "Read(./**/*.generated.*)",

181 "Read(./vendor/**)"

182 ]

183 }

184}

185```

186 

187Deny rules cover Claude's built-in file tools and recognized Bash file commands, including `cat`, `head`, `grep`, and `find`, when a denied path is passed as an argument. They do not filter denied paths out of a recursive search's output, and they do not cover arbitrary subprocesses that open files themselves. For the full pattern syntax, see [Read and Edit permission rules](/en/permissions#read-and-edit).

188 

189### Reduce file reads with code intelligence

190 

191In a large codebase, finding where a symbol is defined or used can cost many file reads and grep calls. [Code intelligence plugins](/en/discover-plugins#code-intelligence) connect Claude to a language server so it can jump to definitions, find references, and surface type errors directly instead of scanning the tree.

192 

193The official marketplace has plugins for TypeScript, Python, Go, Rust, and other common languages. The example below installs the TypeScript plugin:

194 

195```shell theme={null}

196/plugin install typescript-lsp@claude-plugins-official

197```

198 

199To enable a plugin for everyone in the repository rather than installing it yourself, add it to the [`enabledPlugins` project setting](/en/settings#plugin-settings).

200 

201Code intelligence plugins require the language's language server binary on each developer's machine. See [which binary each language requires](/en/discover-plugins#code-intelligence). Installing from the official marketplace requires network access to GitHub, where the marketplace is hosted. On a restricted network, [add the marketplace from an internal Git host or local path](/en/discover-plugins#add-from-other-git-hosts) instead.

202 

203This pairs well with `claudeMdExcludes` and the `Read` deny rules above. Those keep irrelevant content out of context, and code intelligence keeps Claude from reading through what remains to locate a definition.

204 

205## Scope worktrees and file access

206 

207These settings control what's on disk in worktrees and which directories Claude can read and write beyond your starting point.

208 

209### Check out only the directories you need

210 

211The `--worktree` flag starts a session in a new git worktree so changes stay isolated from your main checkout. By default it checks out the entire repository. In a large repository, the `worktree.sparsePaths` setting uses git sparse-checkout to write only the listed directories plus root-level files to disk, so worktrees start faster and use less space.

212 

213If everyone working in this directory needs the same paths, commit the setting to `.claude/settings.json`. To add paths for yourself, use `.claude/settings.local.json`: the lists merge across scopes, so a local file can add paths to the committed list but not remove them. The example below shows the committed file:

214 

215```json .claude/settings.json theme={null}

216{

217 "worktree": {

218 "sparsePaths": [

219 ".claude",

220 "packages/api",

221 "packages/shared"

222 ]

223 }

224}

225```

226 

227When Claude creates a worktree, it checks out only `.claude/`, `packages/api/`, and `packages/shared/` instead of the full tree. Paths in `sparsePaths` are relative to the repository root, regardless of which subdirectory you start Claude from. Any directory paths work here, not only package roots.

228 

229This is particularly useful for [subagent worktree isolation](/en/worktrees#isolate-subagents-with-worktrees). Subagents are parallel Claude instances spawned for subtasks, and each one that runs in a worktree gets a lightweight checkout instead of the full tree. All worktrees in a session share the same `sparsePaths`, so if one subagent needs `packages/api/` and another needs `packages/web/`, list both.

230 

231List directories in `sparsePaths`, not individual files. Root-level files like `package.json`, `tsconfig.base.json`, and lock files are always checked out alongside the directories you list. Root-level directories are not, so include `.claude` in the list if you want the repository root's `.claude/settings.json`, `.claude/rules/`, or `.claude/skills/` available inside the worktree.

232 

233To avoid duplicating large directories like `node_modules` across worktrees, pair `sparsePaths` with `symlinkDirectories` in the same `.claude/settings.json`:

234 

235```json .claude/settings.json theme={null}

236{

237 "worktree": {

238 "sparsePaths": [

239 ".claude",

240 "packages/api",

241 "packages/shared"

242 ],

243 "symlinkDirectories": [

244 "node_modules"

245 ]

246 }

247}

248```

249 

250This creates a symlink from each worktree's `node_modules/` back to the main repository's copy rather than duplicating it on disk.

251 

252<Note>

253 The `sparsePaths` and `symlinkDirectories` settings are read from your starting directory before the worktree is created. After creation, the session's working directory is the worktree root, not the subdirectory you launched from. Project settings inside the worktree therefore load from the worktree root's `.claude/settings.json`, the checked-out copy of the repository root's file. Put any other settings you need inside worktrees, such as permission rules or hooks, in the repository root's `.claude/settings.json`.

254</Note>

255 

256For the full worktree settings reference, see [Worktree settings](/en/settings#worktree-settings).

257 

258### Grant access across packages or repositories

259 

260This section applies when you start Claude from a subdirectory, or when a task spans multiple checkouts. If you start from the repository root in a single large tree, Claude already has access to every file and you can skip this.

261 

262When you start Claude from `packages/api/`, it can read and write files within that directory. If a task requires changes across packages, such as updating a shared type that both `api` and `web` import, you need to grant access to the sibling directory. The same mechanism grants access to a separately-checked-out repository.

263 

264The `additionalDirectories` setting in `.claude/settings.json` gives Claude access to directories outside the working directory. The example below grants access to two sibling packages:

265 

266```json .claude/settings.json theme={null}

267{

268 "permissions": {

269 "additionalDirectories": [

270 "../shared",

271 "../web"

272 ]

273 }

274}

275```

276 

277Relative paths resolve against the directory you start Claude from. With this configuration, Claude can read and edit files in `packages/shared/` and `packages/web/` while working from `packages/api/`.

278 

279You can also grant access at runtime without editing settings by passing `--add-dir` when you start Claude:

280 

281```bash theme={null}

282claude --add-dir ../shared

283```

284 

285However you add a directory, Claude can read and edit files in it. Whether the directory's CLAUDE.md, `.claude/rules/` files, and skills also load depends on how you added it:

286 

287| Added with | Loads CLAUDE.md and rules | Loads skills |

288| :------------------------------------- | :--------------------------------------- | :----------- |

289| `additionalDirectories` setting | Never | Never |

290| `--add-dir` flag or `/add-dir` command | Only with the environment variable below | Yes |

291 

292To load CLAUDE.md and rules files from a directory added with `--add-dir` or `/add-dir`, set the `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` environment variable:

293 

294```bash theme={null}

295CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared

296```

297 

298The environment variable has no effect on directories listed in the `additionalDirectories` setting. See [Load from additional directories](/en/memory#load-from-additional-directories) for details.

299 

300For sibling directories that everyone in this area needs, commit `additionalDirectories` to `.claude/settings.json`. For a personal selection or one-off access, use `.claude/settings.local.json` or pass `--add-dir` at launch.

301 

302## Add per-directory skills

303 

304Any subdirectory can define [skills](/en/skills) scoped to its own stack. A skill loads on demand when Claude determines it's relevant, so API-specific tooling doesn't consume context during frontend work.

305 

306Skills live under `.claude/skills/` inside the directory. Commit them alongside that area's code so anyone who clones the repository gets them. In a monorepo this can be one set of skills per package. In a large single-tree codebase it's one set per subsystem such as `src/db/.claude/skills/`.

307 

308Create a skill directory inside the subdirectory:

309 

310```bash theme={null}

311mkdir -p packages/api/.claude/skills/api-testing

312```

313 

314Then write `SKILL.md` inside that directory, here `packages/api/.claude/skills/api-testing/SKILL.md`. This example teaches Claude the API package's testing patterns:

315 

316```markdown packages/api/.claude/skills/api-testing/SKILL.md theme={null}

317---

318name: api-testing

319description: Testing patterns for the API package. Use when writing or modifying tests in packages/api/.

320---

321 

322## Test structure

323 

324Tests are in `src/__tests__/` mirroring the `src/` directory structure.

325Each route file has a corresponding `.test.ts` file.

326 

327## Running tests

328 

329- All tests: `npm test`

330- Single file: `npm test -- src/__tests__/routes/users.test.ts`

331- Watch mode: `npm test -- --watch`

332 

333## Test utilities

334 

335- `src/__tests__/helpers/db.ts`: provides `setupTestDb()` and `teardownTestDb()` for database tests

336- `src/__tests__/helpers/auth.ts`: provides `createTestUser()` and `getAuthToken()` for authenticated endpoints

337 

338## Patterns

339 

340- Use `supertest` for HTTP assertions, not raw fetch

341- Always wrap database tests in a transaction that rolls back

342- Mock external services in `src/__tests__/mocks/`

343```

344 

345A different subdirectory holds different skills the same way: `packages/web/.claude/skills/component-patterns/` describes the frontend's component conventions instead of testing. When Claude works on a file in `packages/api/`, it loads the api-testing skill. When it works in `packages/web/`, it loads component-patterns instead. Neither directory's skills load during the other's tasks.

346 

347You can also scope a skill by file pattern instead of by placement. The [`paths` frontmatter field](/en/skills#frontmatter-reference) takes glob patterns, and Claude loads the skill automatically only when it works with matching files. Use this for a skill that lives in the repository root's `.claude/skills/` but applies only to certain files wherever they appear, such as a database-migration skill scoped to `**/migrations/**`.

348 

349For more on creating and organizing skills, see [Skills](/en/skills).

350 

351### Keep skills discoverable

352 

353With skills spread across many directories, the list Claude chooses from can grow large. Claude picks a skill by reading every discovered skill's name and description, and only the chosen skill's full content loads into context. This section covers how to keep that list small and write descriptions that survive shortening.

354 

355Which skills are in scope depends on where you start Claude:

356 

357* **From a subdirectory such as `packages/api/`**: skills from that directory, every parent up to the repository root, and the user and enterprise levels

358* **From the repository root**: skills from every subdirectory Claude touches during the session, which can accumulate into the hundreds

359* **After adding a sibling with [`--add-dir`](#grant-access-across-packages-or-repositories)**: that sibling's skills load too. The `additionalDirectories` setting grants file access only and does not load skills

360 

361Names always load, but [descriptions are shortened when there are many](/en/skills#skill-descriptions-are-cut-short), which can strip the keywords Claude uses to decide whether a skill applies. Keep descriptions short and lead with words a request would contain, like "writing or modifying tests in `packages/api/`".

362 

363For skills that many directories share, such as PR conventions or a deploy checklist, place them in the repository root's `.claude/skills/` so they load from any starting directory. When shared skills need their own version history or must work across repositories, package them as a [plugin](/en/plugins) instead. Plugin skills use a `plugin-name:skill-name` namespace, so they never collide with per-directory skills. A platform team can version and update them in one place.

364 

365To find which skills go unused, enable the OpenTelemetry [logs exporter](/en/monitoring-usage) and set `OTEL_LOG_TOOL_DETAILS=1` so skill names are recorded verbatim instead of redacted. The [`skill_activated` event](/en/monitoring-usage#skill-activated-event) records every invocation in its `skill.name` attribute, and `invocation_trigger` records whether a command, Claude, or a nested skill invoked it, which tells you what to consolidate or retire.

366 

367## Centralize conventions when layering stops scaling

368 

369Per-directory CLAUDE.md files can become hard to govern as the codebase grows. Conventions drift, files go stale, and no one owns the root. Solving that typically falls to the team that maintains the repository's Claude Code setup rather than to each developer working in their own area.

370 

371Move conventions and reference content out of always-loaded CLAUDE.md and into mechanisms that load on demand:

372 

373* [Skills](/en/skills): reference material Claude loads only when relevant to the task

374* [Plugins](/en/plugins): versioned bundles of skills, hooks, and commands that a platform team owns centrally

375* [MCP servers](/en/mcp): if your organization already runs a code search or RAG index over the repository, expose it as an MCP tool so Claude queries it instead of reading files directly

376 

377See [server-managed or endpoint-managed settings](/en/server-managed-settings#choose-between-server-managed-and-endpoint-managed-settings) for how platform teams can enforce these centrally.

378 

379### Recommend the right plugin at session start

380 

381Once conventions live in plugins, a teammate starting Claude in an unfamiliar part of the tree has no signal about which plugin that area's owners maintain. A [`SessionStart` hook](/en/hooks#sessionstart) can close that gap, since anything the hook prints to stdout is added to Claude's context before the first prompt.

382 

383For example, you can write a script that reads the launch directory from the [hook input](/en/hooks#common-input-fields), looks it up in a path-to-plugin map committed to the repository, and prints the recommendation for Claude to relay in its first reply. See [Automate workflows with hooks](/en/hooks-guide) to write and register the hook.

384 

385## Put it together

386 

387The combined configuration below uses the monorepo layout. The same files work for any subdirectory in a large single tree. Project settings load only from the directory you start Claude in, so each subdirectory's `.claude/settings.json` must be self-contained rather than layered on a root file.

388 

389The example commits `worktree`, `additionalDirectories`, and the `Read` deny rules in `.claude/settings.json` so every developer in `packages/api/` gets the same sibling access, sparse paths, and exclusions. The file below is the committed per-area settings for `packages/api/`:

390 

391```json packages/api/.claude/settings.json theme={null}

392{

393 "worktree": {

394 "sparsePaths": [

395 ".claude",

396 "packages/api",

397 "packages/shared"

398 ],

399 "symlinkDirectories": [

400 "node_modules"

401 ]

402 },

403 "permissions": {

404 "additionalDirectories": [

405 "../shared"

406 ],

407 "deny": [

408 "Read(./**/dist/**)",

409 "Read(./**/build/**)"

410 ]

411 }

412}

413```

414 

415Because this session starts from `packages/api/`, sibling packages' CLAUDE.md files are already out of scope, so `claudeMdExcludes` is not needed here. Add it to the repository root's `.claude/settings.local.json` instead if you also start sessions from the root.

416 

417The `additionalDirectories` entry applies when you start Claude from `packages/api/` directly. Inside a worktree created from this session, the working directory is the worktree root, so this settings file does not load. The sibling packages are already reachable inside the worktree without it, but the deny rules need a second copy in the repository root's `.claude/settings.json` so worktree sessions pick them up, as the [worktree settings note](#check-out-only-the-directories-you-need) describes:

418 

419```json .claude/settings.json theme={null}

420{

421 "permissions": {

422 "deny": [

423 "Read(./**/dist/**)",

424 "Read(./**/build/**)"

425 ]

426 }

427}

428```

429 

430After setup, the repository has this layout:

431 

432```text theme={null}

433monorepo/

434 CLAUDE.md

435 .claude/settings.json # deny rules for worktree sessions

436 packages/

437 api/

438 CLAUDE.md

439 .claude/settings.json # worktree, additionalDirectories, deny rules

440 .claude/skills/api-testing/SKILL.md

441 web/

442 CLAUDE.md

443 .claude/skills/component-patterns/SKILL.md

444 shared/

445 CLAUDE.md

446```

447 

448With this setup, starting Claude from `packages/api/`:

449 

450* Loads the root CLAUDE.md and `packages/api/CLAUDE.md`, skips `packages/web/CLAUDE.md`

451* Can read and edit files in `packages/api/` and `packages/shared/`

452* Skips reads of build output under `dist/` and `build/` in `packages/api/`

453* Has the api-testing skill available on demand

454* Creates worktrees containing `.claude/`, `packages/api/`, `packages/shared/`, and root-level files, with the deny rules applied across the worktree from the root settings file

455 

456## Scope and plan changes that span packages

457 

458The configuration above controls what Claude sees. When a single change touches several packages, such as updating a shared type along with every call site that uses it, how you scope and sequence the task also affects the result.

459 

460Two techniques help keep a cross-package change consistent:

461 

462* **Give Claude the whole change in one session**: handing over the shared edit and its call sites together keeps the decisions behind each edit consistent, rather than re-deriving them per package

463* **Save the plan to a file before editing**: [plan first](/en/best-practices#explore-first-then-plan-then-code) and ask Claude to write the plan to a markdown file in the repository. A long cross-package session [compacts its context](/en/context-window#what-survives-compaction) along the way, and the saved plan survives where conversation history may not

464 

465## Next steps

466 

467Once this configuration is in place, you can refine it:

468 

469* Use [hooks](/en/hooks-guide) to run per-directory linters or type-checkers after Claude edits files

470* Review [Manage costs effectively](/en/costs) to understand how codebase size affects token usage and how to set spend limits before a wider rollout

471* Read [How Claude Code works in large codebases](https://claude.com/blog/how-claude-code-works-in-large-codebases-best-practices-and-where-to-start) on the Claude blog for organizational rollout patterns and ownership models that sit above the per-repository configuration on this page

323 323 

324### Scope hierarchy and precedence324### Scope hierarchy and precedence

325 325 

326When the same server is defined in more than one place, Claude Code connects to it once, using the definition from the highest-precedence source:326When the same server is defined in more than one place, Claude Code connects to it once, using the definition from the highest-precedence source. The entire server entry from that source is used; fields are not merged across scopes.

327 327 

3281. Local scope3281. Local scope

3292. Project scope3292. Project scope

20 20 

21## CLAUDE.md vs auto memory21## CLAUDE.md vs auto memory

22 22 

23Claude Code has two complementary memory systems. Both are loaded at the start of every conversation. Claude treats them as context, not enforced configuration. The more specific and concise your instructions, the more consistently Claude follows them.23Claude Code has two complementary memory systems. Both are loaded at the start of every conversation. Claude treats them as context, not enforced configuration. To block an action regardless of what Claude decides, use a [PreToolUse hook](/en/hooks-guide) instead. The more specific and concise your instructions, the more consistently Claude follows them.

24 24 

25| | CLAUDE.md files | Auto memory |25| | CLAUDE.md files | Auto memory |

26| :------------------- | :------------------------------------------------ | :--------------------------------------------------------------- |26| :------------------- | :------------------------------------------------ | :--------------------------------------------------------------- |

94 94 

95CLAUDE.md files can import additional files using `@path/to/import` syntax. Imported files are expanded and loaded into context at launch alongside the CLAUDE.md that references them.95CLAUDE.md files can import additional files using `@path/to/import` syntax. Imported files are expanded and loaded into context at launch alongside the CLAUDE.md that references them.

96 96 

97Both relative and absolute paths are allowed. Relative paths resolve relative to the file containing the import, not the working directory. Imported files can recursively import other files, with a maximum depth of five hops.97Both relative and absolute paths are allowed. Relative paths resolve relative to the file containing the import, not the working directory. Imported files can recursively import other files, with a maximum depth of four hops.

98 98 

99To pull in a README, package.json, and a workflow guide, reference them with `@` syntax anywhere in your CLAUDE.md:99To pull in a README, package.json, and a workflow guide, reference them with `@` syntax anywhere in your CLAUDE.md:

100 100 

150 150 

151Claude also discovers `CLAUDE.md` and `CLAUDE.local.md` files in subdirectories under your current working directory. Instead of loading them at launch, they are included when Claude reads files in those subdirectories.151Claude also discovers `CLAUDE.md` and `CLAUDE.local.md` files in subdirectories under your current working directory. Instead of loading them at launch, they are included when Claude reads files in those subdirectories.

152 152 

153If you work in a large monorepo where other teams' CLAUDE.md files get picked up, use [`claudeMdExcludes`](#exclude-specific-claude-md-files) to skip them.153If you work in a large monorepo where other teams' CLAUDE.md files get picked up, use [`claudeMdExcludes`](#exclude-specific-claude-md-files) to skip them. For the full layout of root and per-directory CLAUDE.md files and rules, see [Monorepos and large repos](/en/large-codebases).

154 154 

155Block-level HTML comments (`<!-- maintainer notes -->`) in CLAUDE.md files are stripped before the content is injected into Claude's context. Use them to leave notes for human maintainers without spending context tokens on them. Comments inside code blocks are preserved. When you open a CLAUDE.md file directly with the Read tool, comments remain visible.155Block-level HTML comments (`<!-- maintainer notes -->`) in CLAUDE.md files are stripped before the content is injected into Claude's context. Use them to leave notes for human maintainers without spending context tokens on them. Comments inside code blocks are preserved. When you open a CLAUDE.md file directly with the Read tool, comments remain visible.

156 156 

130```130```

131 131 

132<Note>132<Note>

133 When using Microsoft Foundry, the `/login` and `/logout` commands are disabled since authentication is handled through Azure credentials.133 When using Microsoft Foundry, the `/logout` command is unavailable since authentication is handled through Azure credentials.

134</Note>134</Note>

135 135 

136### 3. Configure Claude Code136### 3. Configure Claude Code

944This example shows what the output looks like for a plugin with two skills:944This example shows what the output looks like for a plugin with two skills:

945 945 

946```946```

947security-guidance 1.2.0947dependency-guard 1.2.0

948 Real-time security analysis for Claude Code sessions948 Dependency analysis for Claude Code sessions

949 Source: security-guidance@claude-code-marketplace949 Source: dependency-guard@example-marketplace

950 950 

951Component inventory951Component inventory

952 Skills (2) scan-dependencies, review-changes952 Skills (2) scan-dependencies, review-changes

137 137 

138## Related resources138## Related resources

139 139 

140* [Security guidance plugin](/en/security-guidance): have Claude review and fix vulnerabilities in its own code changes during the session

140* [Sandbox environments](/en/sandbox-environments): compare isolation approaches and choose one for your threat model141* [Sandbox environments](/en/sandbox-environments): compare isolation approaches and choose one for your threat model

141* [Sandboxing](/en/sandboxing): filesystem and network isolation for Bash commands142* [Sandboxing](/en/sandboxing): filesystem and network isolation for Bash commands

142* [Permissions](/en/permissions): configure permissions and access controls143* [Permissions](/en/permissions): configure permissions and access controls

1> ## Documentation Index

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

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

4 

5# Catch security issues as Claude writes code

6 

7> Install the security-guidance plugin to have Claude review its own code changes for vulnerabilities and fix them in the same session.

8 

9The security guidance plugin makes Claude review its own code changes for common vulnerabilities while it works and fix what it finds in the same session. The plugin catches issues such as injection, unsafe deserialization, and unsafe DOM APIs before the code reaches a pull request, reducing how much security review falls to human reviewers downstream.

10 

11Once installed, the plugin runs automatically. There is nothing to invoke and no separate command to remember.

12 

13The plugin is the in-session companion to [Code Review](/en/code-review), which runs on pull requests. This plugin reduces what reaches the PR. Code Review catches what does. For how the plugin layers with on-demand review and CI scanning, see [How this fits with other security tools](#how-this-fits-with-other-security-tools).

14 

15## Prerequisites

16 

17* Claude Code CLI version 2.1.144 or later

18* Python 3.8 or later on your `PATH`. The plugin tries `python3`, `python`, and `py -3` in that order

19* A git repository for the directory you work in. The end-of-turn and commit reviews diff against git state and skip silently outside a repository. The per-edit pattern check works anywhere

20 

21On first run the plugin creates a virtual environment under `~/.claude/security/` and installs the Claude Agent SDK into it, which requires `pip` and network access. If that install fails, the commit review falls back to a single-shot review instead of the agentic one. On Windows the virtual environment step is skipped, so the agentic commit review runs only if `claude-agent-sdk` is already importable and otherwise falls back the same way.

22 

23## Install the plugin

24 

25In a Claude Code session, install from the [official Anthropic marketplace](/en/discover-plugins#official-anthropic-marketplace):

26 

27```text theme={null}

28/plugin install security-guidance@claude-plugins-official

29```

30 

31The install prompts for a scope. Choose user scope to write the plugin to your user settings, so it loads in every new local session you start on this machine. If Claude Code reports that the marketplace is not found, run `/plugin marketplace add anthropics/claude-plugins-official` first, then retry the install.

32 

33Then activate it in the current session with `/reload-plugins`, which applies pending plugin changes without a restart:

34 

35```text theme={null}

36/reload-plugins

37```

38 

39### Enable in cloud sessions and shared repositories

40 

41User-scoped plugins do not carry into [Claude Code on the web](/en/claude-code-on-the-web), because those sessions run on Anthropic infrastructure rather than your machine. To enable the plugin there, or to turn it on for everyone who clones a repository, declare it in the project's checked-in settings:

42 

43```json .claude/settings.json theme={null}

44{

45 "enabledPlugins": {

46 "security-guidance@claude-plugins-official": true

47 }

48}

49```

50 

51Administrators can enable the plugin organization-wide by setting [`enabledPlugins`](/en/settings#plugin-settings) in [managed settings](/en/admin-setup).

52 

53## What the plugin checks

54 

55The plugin reviews Claude's work at three points, each at a different depth:

56 

57* [On each file edit](#on-each-file-edit): a fast pattern match for risky calls, with no model call

58* [At the end of each turn](#at-the-end-of-each-turn): a background model review of everything that turn changed

59* [On each commit or push Claude makes](#on-each-commit-or-push-claude-makes): a deeper agentic review that reads surrounding code

60 

61You can extend each layer by [adding your own rules](#add-your-own-rules). Built-in checks cannot be removed individually, but you can [disable each layer](#disable-or-uninstall) independently.

62 

63### On each file edit

64 

65When Claude writes to a file, the plugin scans the new content for known risky patterns. This is a pattern match with no model call, so it adds no usage cost.

66 

67Example pattern categories:

68 

69* Dynamic code execution: `eval(`, `new Function`, `os.system`, `child_process.exec`

70* Unsafe deserialization: `pickle`

71* DOM injection: `dangerouslySetInnerHTML`, `.innerHTML =`, `document.write`

72* Workflow files: edits under `.github/workflows/`, which can grant repository-level permissions

73 

74The check runs after the edit lands and appends the warning to Claude's context for the next step. Each warning fires once per pattern per file per session, so repeat matches in the same file do not flood the conversation.

75 

76You can [add your own patterns](#add-custom-per-edit-patterns) to this layer with a `security-patterns.yaml` file.

77 

78### At the end of each turn

79 

80A turn is one round of Claude responding: you send a message, Claude works and replies, and the turn ends. After each turn, the plugin computes a git diff of everything that changed in the working tree during the turn, including changes from Claude's edit tools, Bash commands, and subagents, and sends it to a separate Claude review focused on security. The review runs in the background, so Claude's reply is not delayed. If the review finds issues, Claude is re-prompted with the findings and addresses them as a follow-up.

81 

82This catches issues a string match cannot, such as:

83 

84* Authorization bypass

85* Insecure direct object references

86* Injection

87* Server-side request forgery

88* Weak cryptography

89 

90You see both the finding and Claude's resolution directly in your session. The review covers up to 30 changed files per turn and fires at most three times in a row before yielding back to you.

91 

92### On each commit or push Claude makes

93 

94When Claude runs `git commit` or `git push` through its Bash tool, the plugin runs a deeper agentic review of the change in the background. This review reads surrounding code, including callers, sanitizers, and related files, to decide whether a finding is real before reporting it. The extra context keeps false positives low on patterns that look dangerous in isolation but are safe in your codebase.

95 

96This layer fires only on commits and pushes Claude makes through its Bash tool. Commits you run from your own shell, including the `!` shell escape inside a session, are not reviewed. Commit and push reviews are capped at 20 per rolling hour. If the commit review's findings duplicate what the end-of-turn review already reported, Claude is not re-prompted, so a clean commit produces no visible output from this layer.

97 

98### Review independence and limits

99 

100The plugin does not ask the same Claude instance that wrote the code to grade itself. The per-edit check is a deterministic string match with no model involved. The end-of-turn and commit reviews run as a separate Claude call with a fresh context and a security-focused prompt: the reviewer starts from the diff, has no investment in the original approach, and is instructed only to find problems.

101 

102None of the layers block writes or commits. Findings reach the writing Claude as instructions, Claude addresses them in the conversation, and the review model can miss issues. Treat the plugin as one layer of defense in depth, not a complete security solution. See [How this fits with other security tools](#how-this-fits-with-other-security-tools).

103 

104## Add your own rules

105 

106The plugin has two extension points: a Markdown guidance file for the model-backed reviews, and a YAML or JSON patterns file for the per-edit string match. Both are additive. You can add checks but cannot disable built-in ones from these files.

107 

108### Add guidance for the model-backed reviews

109 

110Create `.claude/claude-security-guidance.md` in your project and describe your threat model and review checklist in plain language. The model-backed reviews load it as additional context alongside the built-in vulnerability checklist.

111 

112The following example is for a web service with role-gated admin routes and a customer-data logging policy:

113 

114```markdown .claude/claude-security-guidance.md theme={null}

115# Security guidance for this repo

116 

117- Do not log `customer_id` or `account_number` at INFO level or above.

118- All routes under `/admin` must call `require_role("admin")` before any database read.

119- Use `crypto.timingSafeEqual` for token comparison instead of `===`.

120```

121 

122These rules are guidance for the reviewer, not deterministic guardrails. The plugin surfaces violations as findings for Claude to fix, but it does not block writes or guarantee every violation is caught. The guidance is additive only: a rule that says to ignore a vulnerability class does not suppress those findings. For hard enforcement, pair the plugin with a [hook that blocks the edit](/en/hooks-guide#block-edits-to-protected-files) or a CI check.

123 

124### Add custom per-edit patterns

125 

126Create `.claude/security-patterns.yaml` to add regex or substring rules to the [per-edit pattern check](#on-each-file-edit). These run as deterministic string matches alongside the built-in patterns:

127 

128```yaml .claude/security-patterns.yaml theme={null}

129patterns:

130 - rule_name: internal_api_key

131 substrings: ["sk_live_", "AKIA"]

132 reminder: "Hardcoded API key prefix. Load credentials from the secret manager."

133 - rule_name: tenant_unfiltered_query

134 regex: "\\.objects\\.all\\(\\)"

135 paths: ["**/src/tenants/**"]

136 reminder: "Multi-tenant code must filter by org_id."

137```

138 

139| Field | Type | Description |

140| :-------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------ |

141| `rule_name` | string | Identifier shown in the warning |

142| `reminder` | string | Warning text appended to Claude's context, capped at 1 KB |

143| `regex` | string | Python regex matched against the edited content |

144| `substrings` | list | Literal substrings; provide this or `regex` |

145| `paths` | list | Optional glob patterns; the rule applies only to matching files. Globs match against the full file path, so prefix project-relative patterns with `**/` |

146| `exclude_paths` | list | Optional glob patterns to skip; same matching as `paths` |

147 

148The plugin also reads `.claude/security-patterns.yml` and `.claude/security-patterns.json` with the same schema. JSON works on any Python install. The YAML forms require PyYAML to be importable, which the plugin does not install for you. The plugin loads up to 50 custom rules and skips regexes that look prone to catastrophic backtracking.

149 

150### Rule file lookup locations

151 

152The plugin looks for `claude-security-guidance.md` and `security-patterns.yaml` in the same locations, independently of how the plugin was enabled:

153 

154| Scope | Path | Notes |

155| :------------ | :------------------------------------------ | :--------------------------------------- |

156| User | `~/.claude/claude-security-guidance.md` | Applies to every project on your machine |

157| Project | `.claude/claude-security-guidance.md` | Checked in with the repository |

158| Project local | `.claude/claude-security-guidance.local.md` | Gitignored, for personal overrides |

159 

160The plugin loads all locations that exist and concatenates them, with a combined cap of 8 KB for the guidance file. Administrators can distribute organization-wide rules by pushing the user-scope file to `~/.claude/` through device management. The same paths apply to `security-patterns.yaml`.

161 

162## Usage cost

163 

164The [per-edit pattern check](#on-each-file-edit) makes no model call and adds no cost. The [end-of-turn](#at-the-end-of-each-turn) and [commit](#on-each-commit-or-push-claude-makes) reviews each spend additional model usage that counts toward your [usage](/en/costs) like any other Claude request. The commit review is agentic and may take several model turns per commit, capped at 20 reviews per rolling hour. Expect roughly one review call per turn that changes files and one deeper review per commit, both subject to the caps above.

165 

166Both model-backed reviews use Claude Opus 4.7 by default. Set `SECURITY_REVIEW_MODEL` to choose a different model for the end-of-turn review and `SG_AGENTIC_MODEL` for the commit review.

167 

168The plugin is available on all plans.

169 

170## Disable or uninstall

171 

172To turn off individual layers while keeping the rest, set the matching environment variable:

173 

174| Variable | Effect |

175| :------------------------------ | :------------------------------------------------------------------------- |

176| `ENABLE_PATTERN_RULES=0` | Disable the [per-edit pattern check](#on-each-file-edit) |

177| `ENABLE_STOP_REVIEW=0` | Disable the [end-of-turn diff review](#at-the-end-of-each-turn) |

178| `ENABLE_COMMIT_REVIEW=0` | Disable the [commit and push review](#on-each-commit-or-push-claude-makes) |

179| `ENABLE_CODE_SECURITY_REVIEW=0` | Disable all model-backed reviews at once |

180| `SECURITY_GUIDANCE_DISABLE=1` | Disable the plugin entirely without uninstalling |

181 

182To pause the plugin in your user scope:

183 

184```text theme={null}

185/plugin disable security-guidance@claude-plugins-official

186```

187 

188To remove it from your user scope:

189 

190```text theme={null}

191/plugin uninstall security-guidance@claude-plugins-official

192```

193 

194If the plugin was enabled through a project's `.claude/settings.json`, disabling it from `/plugin` writes an override to your `.claude/settings.local.json` rather than editing the checked-in file, so the plugin stays off for you while teammates are unaffected. If it was enabled through [managed settings](/en/admin-setup), only an administrator can disable it.

195 

196## How the plugin integrates with Claude Code

197 

198The plugin is built entirely on [hooks](/en/hooks), the mechanism for running your own code at specific points in Claude's loop. It registers:

199 

200| Hook event | Purpose |

201| :--------------------------------------------------------------- | :-------------------------------------------------------------------------- |

202| `SessionStart` | Bootstrap the plugin's Python environment |

203| `UserPromptSubmit` | Capture the working-tree baseline that the end-of-turn review diffs against |

204| `PostToolUse` on `Edit`, `Write`, and `NotebookEdit` | Per-edit pattern match |

205| `Stop` | End-of-turn diff review, run in the background |

206| `PostToolUse` on `Bash`, filtered to `git commit` and `git push` | Commit and push review, run in the background |

207 

208If you build your own hooks, the [plugin's source](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/security-guidance) is a working example of running a separate model call from a hook and feeding the result back to the session.

209 

210## How this fits with other security tools

211 

212The plugin is one layer in a defense-in-depth approach. It catches issues earliest, while code is still in the editor, but it is not a guarantee and does not replace later checks. A typical stack:

213 

214| Stage | Tool | What it covers |

215| :-------------- | :-------------------------------------------------------- | :----------------------------------------------------------------------------------------------- |

216| In session | Security guidance plugin | Common vulnerabilities in code Claude writes, fixed in the same session |

217| On demand | [`/security-review`](/en/commands#all-commands) | One-time security pass on the current branch, run when you ask |

218| On pull request | [Code Review](/en/code-review), Team and Enterprise plans | Multi-agent correctness and security review with full codebase context |

219| In CI | Your existing static analysis and dependency scanners | Language-specific rules, supply-chain checks, and policy enforcement the plugin does not attempt |

220 

221Each later stage catches what earlier ones miss. The plugin's value is reducing the volume that reaches them, not eliminating the need for them.

222 

223## Troubleshooting

224 

225The plugin writes runtime diagnostics to `~/.claude/security/log.txt`. Check there first if reviews are not appearing.

226 

227Common reasons a review layer skips without a message in the conversation:

228 

229* The directory is not a git repository: the end-of-turn and commit reviews require git state and skip outside a repository

230* The session has no Anthropic authentication: the model-backed reviews skip and only the per-edit pattern check runs

231* A `security-patterns.yaml` file is present but PyYAML is not importable: the file is ignored. Use `security-patterns.json` instead

232 

233## Related resources

234 

235To go deeper on the pieces this page touches:

236 

237* [Code Review](/en/code-review): set up the PR-time multi-agent review

238* [Automate workflows with hooks](/en/hooks-guide): build your own checks at the same lifecycle points

239* [Discover and install plugins](/en/discover-plugins#official-anthropic-marketplace): browse other official plugins