# https://github.com/anthropics/claude-code Project Manual
Generated at: 2026-05-31 03:52:46 UTC
## Table of Contents
- [Claude Code Overview](#overview)
- [Installation and Setup](#installation)
- [Configuration and Settings](#configuration)
- [Slash Commands](#slash-commands)
- [Agents and Subagents](#agents)
- [Hooks System](#hooks)
- [Plugin System Architecture](#plugin-system)
- [Official Plugins Reference](#official-plugins)
- [MDM and Enterprise Deployment](#mdm-deployment)
- [Managed Settings Reference](#managed-settings)
## Claude Code Overview
### Related Pages
Related topics: [Installation and Setup](#installation), [Slash Commands](#slash-commands), [Plugin System Architecture](#plugin-system)
Related Source Files
The following source files were used to generate this page:
- [plugins/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/README.md)
- [plugins/plugin-dev/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/README.md)
- [plugins/plugin-dev/skills/plugin-structure/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/plugin-structure/README.md)
- [plugins/plugin-dev/skills/command-development/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/command-development/README.md)
- [plugins/feature-dev/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/feature-dev/README.md)
- [plugins/pr-review-toolkit/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/pr-review-toolkit/README.md)
- [plugins/agent-sdk-dev/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/agent-sdk-dev/README.md)
- [plugins/commit-commands/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/commit-commands/README.md)
- [plugins/frontend-design/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/frontend-design/README.md)
# Claude Code Overview
Claude Code is Anthropic's official command-line interface for coding with Claude AI. It provides a terminal-based development environment where Claude can read and modify files, execute commands, git operations, browse the web, and use tools to assist with software development tasks.
## What is Claude Code?
Claude Code extends Claude's capabilities into a full-featured coding assistant that integrates directly into your terminal workflow. The tool enables AI-assisted development by combining:
- **Natural language understanding** for interpreting developer requests
- **File system access** for reading, writing, and modifying code
- **Command execution** for running build tools, tests, and scripts
- **Git operations** for version control workflows
- **Web browsing** for research and documentation lookup
- **Tool orchestration** for coordinated multi-step tasks
Source: [plugins/README.md:1-8]()
## Plugin System Architecture
Claude Code features an extensible plugin system that allows developers to create custom commands, agents, skills, and integrations. The plugin architecture follows a standardized directory structure with auto-discovery capabilities.
### Directory Structure
```
plugin-name/
├── plugin.json # Plugin manifest
├── commands/ # Slash commands
├── agents/ # Specialized AI agents
├── skills/ # Domain knowledge bases
├── hooks/ # Event-driven automation
├── mcp/ # MCP server configurations
├── examples/ # Example files
└── README.md # Plugin documentation
```
Source: [plugins/plugin-dev/skills/plugin-structure/README.md:15-22]()
### Plugin Components
| Component | Purpose | File Type |
|-----------|---------|-----------|
| Commands | Slash commands invoked by users | Markdown with YAML frontmatter |
| Agents | Autonomous AI agents for specific tasks | Markdown files with system prompts |
| Skills | Knowledge bases with references and examples | Markdown with progressive disclosure |
| Hooks | Event-driven automation (PreToolUse, etc.) | JSON configuration + optional scripts |
| MCP | Model Context Protocol server integration | JSON configuration |
Source: [plugins/plugin-dev/README.md:28-34]()
### Plugin Manifest (plugin.json)
The `plugin.json` manifest defines plugin metadata and component discovery:
```json
{
"name": "plugin-name",
"version": "1.0.0",
"description": "What this plugin does",
"author": "Author Name",
"components": {
"commands": ["commands/*.md"],
"agents": ["agents/*.md"],
"skills": ["skills/*/SKILL.md"]
}
}
```
Source: [plugins/plugin-dev/skills/plugin-structure/README.md:24-32]()
### Portable Path References
Plugins use `${CLAUDE_PLUGIN_ROOT}` for portable path references, allowing plugins to be distributed without hardcoded paths:
```bash
# Example in a hook script
cd ${CLAUDE_PLUGIN_ROOT}
./scripts/validate.sh
```
Source: [plugins/plugin-dev/skills/plugin-structure/README.md:34-36]()
## Official Plugins
Claude Code ships with several official plugins in the `plugins/` directory.
### Plugin Development Toolkit
A comprehensive toolkit for building Claude Code plugins with seven specialized skills:
| Skill | Focus Area | Trigger Phrases |
|-------|------------|-----------------|
| Hook Development | Advanced hooks API and event-driven automation | "create a hook", "add a hook", "hook configuration" |
| MCP Integration | Model Context Protocol server integration | "add MCP server", "integrate MCP", "MCP configuration" |
| Plugin Structure | Plugin organization and manifest configuration | "plugin structure", "plugin layout", "manifest file" |
| Plugin Settings | Configuration patterns using .claude files | "add settings", "user preferences", "plugin configuration" |
| Command Development | Creating slash commands with frontmatter | "create a slash command", "add a command" |
| Agent Development | Creating autonomous agents | "create an agent", "add an agent", "write a subagent" |
| Skill Development | Creating skills with progressive disclosure | "create a skill", "add knowledge", "skill structure" |
Source: [plugins/plugin-dev/README.md:12-21]()
### Feature Development Plugin
The `/feature-dev` command provides a systematic 7-phase approach to building features:
```mermaid
graph TD
A[Phase 1: Discovery] --> B[Phase 2: Codebase Exploration]
B --> C[Phase 3: Clarifying Questions]
C --> D[Phase 4: Architecture Design]
D --> E[Phase 5: Implementation]
E --> F[Phase 6: Quality Review]
F --> G[Phase 7: Completion]
```
**Phase Overview:**
| Phase | Goal | Key Activities |
|-------|------|----------------|
| 1. Discovery | Understand what needs to be built | Clarify requirements, identify constraints |
| 2. Codebase Exploration | Understand existing code and patterns | Launch code-explorer agents in parallel |
| 3. Clarifying Questions | Fill gaps and resolve ambiguities | Ask specific questions before proceeding |
| 4. Architecture Design | Design elegant solutions | Present architecture for approval |
| 5. Implementation | Build the feature | Track progress with TodoWrite |
| 6. Quality Review | Ensure code quality | Verify correctness and patterns |
| 7. Completion | Finalize and summarize | Present final implementation |
Source: [plugins/feature-dev/README.md:30-60]()
### PR Review Toolkit
The `pr-review-toolkit` plugin bundles 6 expert review agents for comprehensive pull request analysis:
| Agent | Focus | Triggers |
|-------|-------|----------|
| comment-analyzer | Comment accuracy and maintainability | "Check if the comments are accurate" |
| pr-test-analyzer | Test coverage quality | "Review test coverage for this PR" |
| silent-failure-hunter | Error handling and silent failures | "Find silent failures" |
| type-design-analyzer | Type design and usage | "Review type safety" |
| code-reviewer | General code quality | "Review my recent changes" |
| code-simplifier | Code refactoring | "Simplify this code" |
Source: [plugins/pr-review-toolkit/README.md:10-40]()
### Agent SDK Development Plugin
The `agent-sdk-dev` plugin streamlines Claude Agent SDK application development:
**Command:** `/new-sdk-app`
Interactive workflow that:
1. Asks clarifying questions about project requirements
2. Checks for and installs the latest SDK version
3. Creates project files and configuration
4. Sets up environment files (.env.example, .gitignore)
5. Runs type checking or syntax validation
6. Verifies setup using verifier agents
**Supported Languages:** TypeScript, Python
Source: [plugins/agent-sdk-dev/README.md:20-45]()
### Commit Commands Plugin
The `commit-commands` plugin provides git workflow automation:
| Command | Purpose |
|---------|---------|
| `/commit` | Analyze and commit changes with descriptive messages |
| `/commit-push-pr` | Commit, push, and create PR with full history analysis |
| `/clean_gone` | Remove local branches whose remote counterparts are deleted |
Source: [plugins/commit-commands/README.md:1-25]()
### Frontend Design Plugin
Automatically used for frontend work, creating production-ready code with:
- Bold aesthetic choices
- Distinctive typography and color palettes
- High-impact animations
- Context-aware implementation
Source: [plugins/frontend-design/README.md:1-18]()
## Commands Development
Slash commands are Markdown files with YAML frontmatter that define user-invokable actions.
### Command File Structure
```markdown
---
description: What the command does
argument-hint: Hint for command arguments
allowed-tools: [ToolName1, ToolName2]
---
# Command Title
Command body with instructions for Claude...
```
Source: [plugins/plugin-dev/skills/command-development/README.md:15-25]()
### Dynamic Arguments
Commands support dynamic argument substitution:
| Syntax | Description |
|--------|-------------|
| `$ARGUMENTS` | All arguments passed to command |
| `$1`, `$2`, etc. | Positional arguments |
| `@filepath` | File references |
| `!`bash command`` | Bash execution for context |
Source: [plugins/plugin-dev/skills/command-development/README.md:27-33]()
## Community Considerations
Based on community feedback and reported issues, several areas are notable for users:
### Known Issues and Limitations
| Category | Issue | Status |
|----------|-------|--------|
| Rate Limits | Weekly limits counter resets on ~24-hour cycle instead of documented 7-day cycle | Open issue #52921 |
| Permissions | Permission mode "auto" not inherited in new sessions | Open issue #55558 |
| TUI Rendering | Lines stack/overlap on Windows Terminal | Open issue #58579 |
| Context Propagation | CLAUDE.md rules not propagated to Agent subagents | Open issue #59309 |
Source: Community context analysis
### Feature Requests
The community has requested several enhancements:
- **AGENTS.md Support** (Issue #6235): Standardizing around the agents.md convention for cross-platform compatibility
- **Rate-limit-aware scheduling** (Issue #59634): Deferred prompt scheduling when limits are reached
- **Extended Auto mode** (v2.1.158): Now available on Bedrock, Vertex, and Foundry for Opus 4.7 and Opus 4.8
Source: Community context
## Installation and Setup
### Global Installation
```bash
npm install -g @anthropic-ai/claude-code
```
### Plugin Installation
1. Use the `/plugin` command to install from marketplaces
2. Or configure plugins in project `.claude/settings.json`
### Project Configuration
Plugins can be configured per-project:
```json
{
"plugins": ["plugin-name"],
"settings": {
"plugin-name": {
"option": "value"
}
}
}
```
Source: [plugins/README.md:55-65]()
## Best Practices
### Skill Development Guidelines
- Keep SKILL.md lean with core concepts
- Use progressive disclosure (detailed references available on demand)
- Include strong trigger phrases for activation
- Provide examples/ directory for working patterns
- Use imperative/infinitive form in documentation
### Command Development Guidelines
- Use third-person descriptions for skills
- Write commands in imperative form (instructions FOR Claude)
- Use ${CLAUDE_PLUGIN_ROOT} for portability
- Apply security-first patterns (HTTPS, no hardcoded credentials)
- Prefer prompt-based hooks for complex logic
### Plugin Structure Guidelines
- Follow consistent directory naming
- Use YAML frontmatter for metadata
- Validate components with provided utility scripts
- Document required environment variables
- Provide clear README with usage examples
Source: [plugins/plugin-dev/README.md:40-55]()
## Architecture Diagram
```mermaid
graph TD
subgraph "User Interface"
A[Terminal/CLI]
B[VSCode Extension]
C[Cursor Extension]
end
subgraph "Core Engine"
D[Command Parser]
E[Agent Orchestrator]
F[Tool Executor]
G[Context Manager]
end
subgraph "Plugin System"
H[Plugin Loader]
I[Command Registry]
J[Agent Registry]
K[Hook Manager]
end
subgraph "External Services"
L[Anthropic API]
M[MCP Servers]
N[Git Provider]
end
A --> D
B --> D
C --> D
D --> E
E --> F
E --> G
H --> I
H --> J
H --> K
I --> F
J --> E
K --> F
F --> L
F --> N
F --> M
```
## Summary
Claude Code provides a powerful command-line coding environment with an extensible plugin architecture. The system enables developers to:
1. **Develop features systematically** using the `/feature-dev` workflow
2. **Review code thoroughly** with the PR Review Toolkit agents
3. **Extend functionality** through custom plugins, commands, agents, and hooks
4. **Integrate external services** via MCP server configurations
5. **Automate workflows** with event-driven hooks and slash commands
The plugin system follows consistent patterns with portable path references, progressive disclosure for documentation, and validation utilities for quality assurance.
---
## Installation and Setup
### Related Pages
Related topics: [Claude Code Overview](#overview), [Configuration and Settings](#configuration)
Related Source Files
The following source files were used to generate this page:
- [plugins/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/README.md)
- [plugins/plugin-dev/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/README.md)
- [examples/mdm/README.md](https://github.com/anthropics/claude-code/blob/main/examples/mdm/README.md)
- [.devcontainer/Dockerfile](https://github.com/anthropics/claude-code/blob/main/.devcontainer/Dockerfile)
- [.devcontainer/devcontainer.json](https://github.com/anthropics/claude-code/blob/main/.devcontainer/devcontainer.json)
- [Script/run_devcontainer_claude_code.ps1](https://github.com/anthropics/claude-code/blob/main/Script/run_devcontainer_claude_code.ps1)
# Installation and Setup
## Overview
This page covers all methods for installing Claude Code and configuring your development environment, including global installation via npm, containerized development using Dev Containers, and enterprise deployment through Mobile Device Management (MDM) systems.
Claude Code is distributed as a Node.js package and can be installed on macOS, Linux, and Windows systems. The installation process differs slightly between platforms, with support for both interactive terminal usage and headless/server deployment scenarios.
---
## System Requirements
### Prerequisites
| Requirement | Version | Notes |
|-------------|---------|-------|
| Node.js | 18+ | Required for npm installation |
| npm | 9+ | Bundled with Node.js 18+ |
| Operating System | macOS, Linux, Windows | Terminal environment required |
| API Access | Anthropic API key | Configured after installation |
### Environment Considerations
Users have reported various environment-specific issues:
- **Windows Terminal**: TUI rendering issues may occur with older Windows Terminal versions. Users on Windows 11 with Windows Terminal 1.24+ are recommended.
- **VSCode Extension**: The `/model` command may hang indefinitely in certain VSCode extension configurations.
- **AVX-only CPUs**: The Bun baseline build may crash with "Illegal instruction" on AVX-only CPUs (Windows 10).
---
## Global Installation via npm
The standard installation method for Claude Code is through the npm registry.
### Installation Command
```bash
npm install -g @anthropic-ai/claude-code
```
This command installs Claude Code globally, making the `claude` command available in any terminal session.
### Post-Installation Steps
1. Navigate to your project directory:
```bash
cd /path/to/your/project
```
2. Launch Claude Code:
```bash
claude
```
3. On first launch, Claude Code will prompt you to authenticate with your Anthropic API key.
### Verification
To verify the installation:
```bash
claude --version
```
---
## Plugin Installation
Claude Code supports a plugin system that extends functionality. Plugins are included in the repository and can be installed for use in your projects.
### Using the Plugin Command
After installing Claude Code globally, use the built-in `/plugin` command to discover and install plugins:
```bash
claude
/plugin
```
### Configuration Methods
Plugins can be configured in two ways:
#### 1. Plugin Marketplace
Use the `/plugin` command to browse and install plugins from the marketplace directly within Claude Code.
#### 2. Settings Configuration
Configure plugins in your project's `.claude/settings.json`:
```json
{
"plugins": ["plugin-name-1", "plugin-name-2"]
}
```
### Included Plugins
The repository includes several pre-built plugins:
| Plugin | Purpose | Key Commands |
|--------|---------|--------------|
| `plugin-dev` | Create and develop new plugins | `/plugin-dev:create-plugin` |
| `feature-dev` | Guided feature development workflow | `/feature-dev` |
| `pr-review-toolkit` | Comprehensive PR review agents | `/pr-review-toolkit:review-pr` |
| `ralph-wiggum` | Iterative development loops | `/ralph-loop`, `/cancel-ralph` |
| `security-guidance` | Security reminder hook | PreToolUse hook |
| `hookify` | Custom hook creation | `/hookify` |
### Third-Party Plugins
The community maintains additional plugins. Users have shared curated lists of Claude Skills and plugins on social platforms.
---
## Dev Container Setup
For containerized development environments, Claude Code includes Dev Container configuration files.
### Files Overview
| File | Purpose |
|------|---------|
| `.devcontainer/devcontainer.json` | Dev Container specification |
| `.devcontainer/Dockerfile` | Container image definition |
| `Script/run_devcontainer_claude_code.ps1` | PowerShell launcher script |
### Quick Start with Dev Container
1. Open the repository in a Dev Container-supported IDE (VS Code with Dev Containers extension)
2. The Dev Container configuration will:
- Build the container image from the provided Dockerfile
- Install Claude Code within the container
- Mount your project directory for development
3. Launch Claude Code inside the container:
```bash
claude
```
### Windows PowerShell Launcher
For Windows environments, a PowerShell script is provided to launch Claude Code within the Dev Container:
```powershell
./Script/run_devcontainer_claude_code.ps1
```
### Dockerfile Base Image
The Dev Container uses a base Node.js image. The Dockerfile is minimal and designed to work with standard Dev Container workflows.
---
## Managed Settings Deployment
For enterprise environments, Claude Code supports deployment through Mobile Device Management (MDM) systems.
### Supported Platforms
| Platform | MDM Tools | Configuration Method |
|----------|-----------|---------------------|
| macOS | Jamf, Kandji (Iru) | Custom Settings payload |
| Windows | Intune | Platform scripts |
| Cross-platform | Any MDM | JSON settings file |
### Configuration Files
#### Managed Settings JSON
Deploy to the system config directory using `managed-settings.json`:
```json
{
"permissions": {
"disableBypassPermissionsMode": true
}
}
```
#### macOS Configuration Profile
For Jamf/Kandji deployments, use the preference domain `com.anthropic.claudecode`:
| File | Format | Use Case |
|------|--------|----------|
| `com.anthropic.claudecode.plist` | Property List | Jamf, Kandji Custom Settings |
| `com.anthropic.claudecode.mobileconfig` | Mobileconfig | Full profile for testing or MDMs accepting complete profiles |
#### Windows Intune Script
For Intune deployments, use the PowerShell script located at `examples/mdm/windows/Set-ClaudeCodePolicy.ps1`, which writes `managed-settings.json` to the system configuration directory.
### Settings Reference
For the complete list of available managed settings, refer to the [official settings reference](https://code.claude.com/docs/en/settings#available-settings).
---
## Environment Variables
Claude Code respects several environment variables for configuration:
| Variable | Purpose | Example |
|----------|---------|---------|
| `CLAUDE_CODE_ENABLE_AUTO_MODE` | Enable auto mode on Bedrock, Vertex, and Foundry | `CLAUDE_CODE_ENABLE_AUTO_MODE=1` |
| `ANTHROPIC_API_KEY` | API key for authentication | `sk-ant-...` |
### Auto Mode Configuration
Auto mode is available on Bedrock, Vertex, and Foundry for Opus 4.7 and Opus 4.8. Opt in by setting:
```bash
export CLAUDE_CODE_ENABLE_AUTO_MODE=1
```
---
## Authentication Setup
After installation, Claude Code requires authentication to use the Anthropic API.
### First-Time Authentication
1. Run Claude Code:
```bash
claude
```
2. Claude Code will prompt for API key input
3. Enter your Anthropic API key when prompted
### Permission Modes
Claude Code supports different permission modes that control how it handles command execution:
- **Auto**: Permission mode may not be inherited in new sessions and cannot be set mid-session
- **Manual**: Requires explicit user approval for each command
Users have reported issues with the `auto` permission mode not being properly inherited between sessions.
---
## Troubleshooting
### Common Installation Issues
#### npm Installation Fails
**Issue**: `npm install -g` fails with permission errors
**Solution**:
- Use a Node version manager (nvm, fnm) to avoid permission issues
- Or use `sudo npm install -g` on systems without nvm
#### Dev Container Build Failures
**Issue**: Container build fails on AVX-only CPUs
**Solution**: Use a different container base image or build configuration. The Bun baseline build has known issues with AVX-only CPUs.
#### TUI Rendering Issues on Windows
**Issue**: Lines stack/overlap on Windows Terminal
**Solution**: Update to Windows Terminal 1.24+ or use an alternative terminal emulator.
### Configuration Issues
#### Plugin Marketplace Crashes
**Issue**: Plugin marketplace list crashes with "Illegal instruction" on AVX-only CPUs
**Solution**: This is a known issue with the Bun baseline build on Windows 10. No workaround currently available.
#### Permission Mode Not Inherited
**Issue**: `auto` permission mode not inherited by new sessions
**Solution**: This is a known bug. Set `defaultMode` in `~/.claude/settings.json` to ensure consistent behavior across sessions.
---
## Upgrading Claude Code
### npm Upgrade
To upgrade to the latest version:
```bash
npm update -g @anthropic-ai/claude-code
```
### Check Current Version
```bash
claude --version
```
---
## Repository Structure for Installation-Related Files
```
claude-code/
├── .devcontainer/
│ ├── Dockerfile # Container image definition
│ ├── devcontainer.json # Dev Container specification
│ └── (Dockerfile and config files)
├── examples/
│ └── mdm/ # MDM deployment templates
│ ├── README.md
│ ├── managed-settings.json
│ ├── macos/
│ └── windows/
├── plugins/
│ ├── README.md # Plugin system documentation
│ ├── plugin-dev/ # Plugin development plugin
│ ├── feature-dev/ # Feature development workflow
│ └── (other included plugins)
└── Script/
└── run_devcontainer_claude_code.ps1 # Windows launcher
```
---
## Related Documentation
- [Settings Reference](https://code.claude.com/docs/en/settings#settings-files) - Complete list of available settings
- [Plugin Development](./plugins/plugin-dev/) - Creating custom plugins
- [Feature Development](./plugins/feature-dev/) - Structured development workflows
- [Security Guidance](./plugins/security-guidance/) - Security best practices
---
## Configuration and Settings
### Related Pages
Related topics: [Claude Code Overview](#overview), [Managed Settings Reference](#managed-settings)
Related Source Files
The following source files were used to generate this page:
- [examples/settings/README.md](https://github.com/anthropics/claude-code/blob/main/examples/settings/README.md)
- [examples/settings/settings-bash-sandbox.json](https://github.com/anthropics/claude-code/blob/main/examples/settings/settings-bash-sandbox.json)
- [examples/settings/settings-strict.json](https://github.com/anthropics/claude-code/blob/main/examples/settings/settings-strict.json)
- [examples/settings/settings-lax.json](https://github.com/anthropics/claude-code/blob/main/examples/settings/settings-lax.json)
- [examples/mdm/README.md](https://github.com/anthropics/claude-code/blob/main/examples/mdm/README.md)
- [examples/mdm/managed-settings.json](https://github.com/anthropics/claude-code/blob/main/examples/mdm/managed-settings.json)
- [plugins/plugin-dev/skills/plugin-settings/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/plugin-settings/README.md)
# Configuration and Settings
Claude Code provides a flexible configuration system that allows users and organizations to customize behavior through multiple configuration layers. This system supports per-project settings via files, per-user settings in the home directory, and enterprise-wide managed settings deployed through MDM (Mobile Device Management) solutions.
## Overview
The configuration system in Claude Code operates across three distinct layers:
```mermaid
graph TD
A[Configuration Layers] --> B[Project Level
CLAUDE.md + .claude/settings.json]
A --> C[User Level
~/.claude/settings.json]
A --> D[Enterprise Level
Managed Settings via MDM]
B --> E[Project-specific rules
Custom commands
Local plugin configs]
C --> F[Default model
Permission modes
Global preferences]
D --> G[Organizational policies
Disabled features
Security enforcement]
```
Each layer has a specific scope and purpose. Project-level settings take precedence for local customization, while enterprise managed settings enforce organizational policies that cannot be overridden by individual users.
Source: [examples/settings/README.md:1-15]()
## Configuration Files
### Project-Level Configuration
#### CLAUDE.md
The `CLAUDE.md` file in a project root provides project-specific instructions that Claude Code reads at the start of each session. This file defines:
- Project purpose and context
- Coding standards and conventions
- Build and test commands
- Important file locations
- Development workflows
```markdown
# Project Name
This is a Next.js application with TypeScript.
## Development
- Run `npm run dev` to start development server
- Use `npm test` for testing
## Code Standards
- All components must use TypeScript
- Follow the existing component patterns in /components
```
**Note:** CLAUDE.md rules are not propagated to Agent subagents, and rule adherence may degrade after context compaction. Source: [Community Issue #59309](https://github.com/anthropics/claude-code/issues/59309)
#### Local Settings (.claude/settings.json)
The `.claude/settings.json` file in a project contains local configuration overrides:
```json
{
"permissions": {
"allowGdp": true,
"autoApprove": false
},
"resume": true,
"dangerouslySkipUriPermissionsPrompt": false
}
```
Source: [examples/settings/README.md:20-30]()
### User-Level Configuration
Located at `~/.claude/settings.json`, user-level settings provide defaults that apply across all projects:
```json
{
"permissions": {
"defaultMode": "auto"
},
"model": "claude-opus-4-5",
"maxTokens": 8192
}
```
**Known Issue:** The permission mode "auto" is not inherited in new sessions and cannot be set mid-session. Source: [Community Issue #55558](https://github.com/anthropics/claude-code/issues/55558)
### Managed Settings (Enterprise)
Enterprise deployments use managed settings to enforce organizational policies. These settings are deployed through MDM solutions and cannot be overridden by users.
#### Deployment Methods
| Platform | Method | File Location |
|----------|--------|---------------|
| Jamf / Kandji | Custom Settings payload | `com.anthropic.claudecode.plist` |
| Intune | Platform scripts | `Set-ClaudeCodePolicy.ps1` |
| Group Policy | JSON configuration | System config directory |
| Any platform | Direct JSON | System config directory |
Source: [examples/mdm/README.md:1-25]()
#### Example Managed Settings
```json
{
"permissions": {
"disableBypassPermissionsMode": true
}
}
```
Source: [examples/mdm/managed-settings.json:1-5]()
## Settings Configuration Options
### Permission Settings
Permissions control what actions Claude Code can perform without explicit user confirmation:
```mermaid
graph LR
A[Permission Modes] --> B[auto
Confirm dangerous ops]
A --> C[full
All operations allowed]
A --> D[restricted
Read-only by default]
B --> E[Ask before bypass]
C --> F[No restrictions]
D --> G[Explicit approval needed]
```
| Setting | Type | Description |
|---------|------|-------------|
| `defaultMode` | `string` | Default permission mode: `auto`, `full`, or `restricted` |
| `allowGdp` | `boolean` | Allow GDP operations |
| `autoApprove` | `boolean` | Automatically approve safe operations |
| `disableBypassPermissionsMode` | `boolean` | Prevent users from bypassing permission mode (managed only) |
Source: [examples/settings/settings-strict.json:1-15]()
### Behavior Settings
These settings control Claude Code's operational behavior:
| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `resume` | `boolean` | `false` | Resume previous session automatically |
| `dangerouslySkipUriPermissionsPrompt` | `boolean` | `false` | Skip URI permission prompts |
| `gitPromptReplacement` | `string` | `"y"` | Default response for git prompts |
| `outputFormat` | `string` | `"text"` | Output format: `text` or `stream`
Source: [examples/settings/settings-strict.json:1-20]()
## Preset Configuration Profiles
Claude Code includes preset configuration profiles for common use cases:
### Strict Profile
Designed for security-conscious environments:
```json
{
"permissions": {
"defaultMode": "restricted",
"allowGdp": false,
"autoApprove": false
},
"resume": false,
"dangerouslySkipUriPermissionsPrompt": false
}
```
Source: [examples/settings/settings-strict.json:1-10]()
### Lax Profile
Provides maximum convenience with minimal friction:
```json
{
"permissions": {
"defaultMode": "auto",
"allowGdp": true,
"autoApprove": true
},
"resume": true
}
```
Source: [examples/settings/settings-lax.json:1-10]()
### Bash Sandbox Profile
Restricts command execution to sandboxed environments:
```json
{
"permissions": {
"defaultMode": "restricted",
"allowGdp": false,
"autoApprove": false
},
"sandbox": {
"enabled": true,
"allowedPaths": ["/tmp/sandbox"],
"deniedCommands": ["rm", "dd", "mkfs"]
}
}
```
Source: [examples/settings/settings-bash-sandbox.json:1-15]()
## Plugin Settings
Plugins can define their own configuration system using per-project settings files. This follows a standardized pattern:
### Configuration File Pattern
Plugin settings are stored in `.claude/plugin-name.local.md` files with YAML frontmatter:
```markdown
---
option1: value1
option2: value2
---
# Plugin Configuration
Additional markdown content for documentation or templates.
```
Source: [plugins/plugin-dev/skills/plugin-settings/README.md:1-20]()
### Settings Structure
| Component | Purpose |
|-----------|---------|
| YAML Frontmatter | Structured configuration options |
| Markdown Body | Templates, examples, documentation |
| `.local.md` suffix | Indicates local (non-shared) configuration |
Source: [plugins/plugin-dev/skills/plugin-settings/README.md:25-35]()
### Parsing Configuration
Bash scripts within plugins can parse these settings using common Unix tools:
```bash
# Parse YAML frontmatter
parse_frontmatter() {
local file="$1"
awk '/^---/,/^---/' "$file" | sed '1d;$d'
}
# Extract specific values
get_setting() {
local file="$1"
local key="$2"
grep "^${key}:" "$file" | sed "s/^${key}: *//"
}
```
Source: [plugins/plugin-dev/skills/plugin-settings/README.md:40-55]()
## Environment Variables
Claude Code also supports configuration via environment variables:
| Variable | Purpose |
|----------|---------|
| `CLAUDE_CODE_ENABLE_AUTO_MODE` | Enable auto mode on additional platforms |
| `ANTHROPIC_API_KEY` | API key for Claude requests |
| `CLAUDE_CODE_CONFIG_DIR` | Custom configuration directory |
The latest release (v2.1.158) enables auto mode on Bedrock, Vertex, and Foundry for Opus 4.7 and Opus 4.8 when `CLAUDE_CODE_ENABLE_AUTO_MODE=1` is set. Source: [Community Release Notes]()
## Configuration Precedence
When multiple configuration layers define the same setting, Claude Code follows this precedence order (highest to lowest):
1. **Managed Settings** (MDM) - Cannot be overridden
2. **Project Settings** (.claude/settings.json)
3. **User Settings** (~/.claude/settings.json)
4. **Environment Variables**
5. **Default Values**
```mermaid
graph TD
A[Configuration Resolution] --> B{Has Managed Setting?}
B -->|Yes| C[Use Managed Setting
Cannot Override]
B -->|No| D{Has Project Setting?}
D -->|Yes| E[Use Project Setting]
D -->|No| F{Has User Setting?}
F -->|Yes| G[Use User Setting]
F -->|No| H[Use Default]
```
## Best Practices
### For Individual Developers
- Use `CLAUDE.md` for project-specific instructions and conventions
- Store shared preferences in `~/.claude/settings.json`
- Use project settings for team-specific configurations
### For Teams
- Document required settings in project README
- Use version-controlled settings files for reproducible environments
- Consider using preset profiles (strict, lax, sandbox)
### For Enterprise Deployments
- Deploy managed settings through MDM for policy enforcement
- Use `disableBypassPermissionsMode` to prevent permission mode bypass
- Document organizational policies separately from technical settings
## Troubleshooting
### Settings Not Applied
If settings are not being applied:
1. Verify file location matches expected path
2. Check JSON syntax validity
3. Confirm file permissions allow reading
4. Review Claude Code logs for configuration errors
### Permission Mode Issues
The "auto" permission mode may not persist across sessions. As a workaround:
- Explicitly set `defaultMode` in user settings
- Restart Claude Code after modifying settings
- Check for managed settings that may override user preferences
Source: [Community Issue #55558](https://github.com/anthropics/claude-code/issues/55558)
## Related Documentation
- [Settings Reference](https://code.claude.com/docs/en/settings) - Complete settings documentation
- [Managed Settings Deployment](https://code.claude.com/docs/en/settings#settings-files) - MDM deployment guide
- [Plugin Development](../plugins/plugin-dev/) - Creating configurable plugins
---
## Slash Commands
### Related Pages
Related topics: [Claude Code Overview](#overview), [Agents and Subagents](#agents), [Hooks System](#hooks)
Related Source Files
The following source files were used to generate this page:
- [.claude/commands/commit-push-pr.md](https://github.com/anthropics/claude-code/blob/main/.claude/commands/commit-push-pr.md)
- [.claude/commands/dedupe.md](https://github.com/anthropics/claude-code/blob/main/.claude/commands/dedupe.md)
- [.claude/commands/triage-issue.md](https://github.com/anthropics/claude-code/blob/main/.claude/commands/triage-issue.md)
- [plugins/plugin-dev/skills/command-development/SKILL.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/command-development/SKILL.md)
- [plugins/commit-commands/commands/commit.md](https://github.com/anthropics/claude-code/blob/main/plugins/commit-commands/commands/commit.md)
- [plugins/plugin-dev/skills/command-development/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/command-development/README.md)
- [plugins/plugin-dev/commands/create-plugin.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/commands/create-plugin.md)
- [plugins/pr-review-toolkit/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/pr-review-toolkit/README.md)
- [plugins/code-review/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/code-review/README.md)
- [plugins/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/README.md)
# Slash Commands
Slash Commands are user-defined shortcuts that trigger Claude to execute predefined workflows, prompts, or actions. They provide a way to encapsulate common development tasks, automate repetitive workflows, and extend Claude Code's capabilities beyond its built-in commands.
## Overview
Slash Commands serve as a trigger mechanism that invokes Claude with a specific prompt and context. When invoked with `/command-name`, Claude executes the command's defined workflow, which can include argument handling, file references, bash execution, and integration with other Claude Code components like agents and skills.
### Core Characteristics
| Characteristic | Description |
|----------------|-------------|
| **Format** | Markdown files with optional YAML frontmatter |
| **Location** | `.claude/commands/` (project) or plugin command directories |
| **Invocation** | `/command-name` followed by optional arguments |
| **Arguments** | Support for positional (`$1`, `$2`) and `$ARGUMENTS` |
| **Tool Access** | Configurable via `allowed-tools` frontmatter field |
Source: [plugins/plugin-dev/skills/command-development/SKILL.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/command-development/SKILL.md)
## File Structure
Slash Commands are stored as Markdown (`.md`) files with a specific structure:
```markdown
---
description: Brief description of what the command does
argument-hint: [arg1] [arg2]
allowed-tools: Read, Bash(git:*)
---
Command prompt content with:
- $ARGUMENTS or $1, $2 for positional arguments
- @path/to/file for file references
- !`command` for bash execution
```
### Command Locations
Commands can be placed in multiple locations for different scopes:
| Location | Scope | Example Path |
|----------|-------|--------------|
| Project | Current project only | `.claude/commands/commit.md` |
| User | All projects for current user | `~/.claude/commands/` |
| Plugin | Shared via plugin marketplace | `plugins/*/commands/` |
Source: [plugins/plugin-dev/skills/command-development/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/command-development/README.md)
## YAML Frontmatter Reference
The frontmatter section contains metadata that controls command behavior:
| Field | Type | Description | Default |
|-------|------|-------------|---------|
| `description` | string | Brief description shown in help | Required |
| `argument-hint` | string | Shows expected arguments to user | None |
| `allowed-tools` | string[] | Tools the command can use | All tools |
| `disable-model-invocation` | boolean | Skip Claude for manual-only commands | false |
### Frontmatter Examples
**Simple command with description:**
```yaml
---
description: Review code for issues
---
```
**Command with arguments and tool restrictions:**
```yaml
---
description: Deploy to environment
argument-hint: [environment] [version]
allowed-tools: Read, Bash, Write
---
```
**Manual-only command:**
```yaml
---
description: Show Git status
disable-model-invocation: true
allowed-tools: Bash(git:*)
---
```
Source: [plugins/plugin-dev/skills/command-development/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/command-development/README.md)
## Dynamic Arguments
Commands support dynamic argument substitution using several syntaxes:
### Argument Types
| Syntax | Description | Example |
|--------|-------------|---------|
| `$ARGUMENTS` | All remaining text after command name | `/deploy production v2.1.0` → `$ARGUMENTS` = `production v2.1.0` |
| `$1`, `$2`, `$N` | Positional arguments | `/deploy $1 $2` with `production` → `$1` = `production` |
| `$CLAUDE_PLUGIN_ROOT` | Plugin installation path | `${CLAUDE_PLUGIN_ROOT}/scripts/setup.sh` |
### Argument Handling
Arguments are passed as plain text and can be combined with other prompt content:
```markdown
---
description: Create a commit with the given message
argument-hint: [commit-message]
---
Create a commit with the following message:
$ARGUMENTS
Ensure the commit follows conventional commit format.
```
Source: [plugins/plugin-dev/skills/command-development/SKILL.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/command-development/SKILL.md)
## File References and Bash Execution
### File References (@ syntax)
Reference files to include them in Claude's context:
```markdown
---
description: Analyze code quality
argument-hint: [file-path]
---
Review the following code for quality issues:
@$1
```
### Bash Execution (!` syntax)
Execute shell commands inline to gather context:
```markdown
---
description: Show recent commits
allowed-tools: Bash(git:*)
---
Recent commits:
!`git log --oneline -10`
Current branch:
!`git branch --show-current`
Status:
!`git status --short`
```
### Combined Usage
```markdown
---
description: Review PR changes
argument-hint: [pr-number]
allowed-tools: Bash, Read, WebFetch
---
Fetch PR details for #$1:
!`gh pr view $1 --json title,body,state`
Review the changes:
!`gh pr diff $1`
```
Source: [plugins/plugin-dev/skills/command-development/SKILL.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/command-development/SKILL.md)
## Plugin Commands
Commands within plugins follow the same structure but benefit from additional features:
### Plugin Command Organization
```
plugins/my-plugin/
├── commands/
│ ├── command-one.md
│ └── command-two.md
├── plugin.json
└── ...
```
### Key Plugin Command Features
| Feature | Description |
|---------|-------------|
| `${CLAUDE_PLUGIN_ROOT}` | Portable path reference to plugin root directory |
| Component integration | Can invoke agents, load skills, trigger hooks |
| Marketplace distribution | Share commands via plugin marketplace |
| Namespace support | Commands can be namespaced (e.g., `pr-review:analyze`) |
### Plugin Command Example
```markdown
---
description: Initialize plugin structure
argument-hint: [plugin-name] [type]
allowed-tools: Bash, Write, Read
---
Create a new plugin with the following structure:
1. Set up ${CLAUDE_PLUGIN_ROOT} as the project root
2. Create the following directory structure:
- commands/
- skills/
- agents/
- hooks/
3. Initialize plugin.json with metadata
```
Source: [plugins/plugin-dev/commands/create-plugin.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/commands/create-plugin.md)
## Workflow Integration
### Standard Development Workflow
```mermaid
graph TD
A[User invokes /command] --> B{Command has arguments?}
B -->|Yes| C[Parse arguments]
B -->|No| D[Load command prompt]
C --> E[Substitute variables]
D --> E
E --> F[Execute bash commands if present]
F --> G[Read referenced files]
G --> H[Invoke Claude with prompt]
H --> I[Execute requested actions]
I --> J[Return results]
```
### Command with CLAUDE.md Integration
Commands work alongside CLAUDE.md for comprehensive project guidance:
1. **CLAUDE.md** defines project-wide rules and conventions
2. **Slash Commands** provide task-specific workflows
3. **Agents** handle autonomous multi-step tasks
Source: [plugins/code-review/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/code-review/README.md)
## Best Practices
### Command Design Guidelines
| Guideline | Rationale |
|-----------|-----------|
| Use descriptive names | Easy to discover and remember |
| Limit scope | Single-purpose commands are more reusable |
| Document arguments | Use `argument-hint` for clarity |
| Restrict tools when possible | Follow least-privilege principle |
| Use strong trigger phrases | Improves Claude's recognition |
### Writing Effective Prompts
- Use imperative form ("Review code", "Create commit")
- Include specific instructions and constraints
- Reference relevant files or patterns
- Set clear expectations for output format
### Security Considerations
```markdown
---
description: Run build command
argument-hint: [script-name]
allowed-tools: Bash
---
Execute the build script:
!`./scripts/$1.sh`
Do NOT run any other commands.
Do NOT modify any files.
```
Source: [plugins/plugin-dev/skills/command-development/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/command-development/README.md)
## Examples
### Commit Command
```markdown
---
description: Create a commit with a message
argument-hint: [message]
allowed-tools: Bash(git:*)
---
Create a git commit with the message:
$ARGUMENTS
First show what would be committed using:
!`git status`
!`git diff --staged --stat`
```
Source: [plugins/commit-commands/commands/commit.md](https://github.com/anthropics/claude-code/blob/main/plugins/commit-commands/commands/commit.md)
### Triage Issue Command
```markdown
---
description: Triage GitHub issue and create action items
argument-hint: [issue-number]
allowed-tools: Bash, WebFetch, Write, Read
---
Triage issue #$ARGUMENTS:
1. Fetch the issue details
2. Analyze the bug report or feature request
3. Identify missing information
4. Create TODO.md with action items if needed
```
Source: [.claude/commands/triage-issue.md](https://github.com/anthropics/claude-code/blob/main/.claude/commands/triage-issue.md)
### Dedupe Command
```markdown
---
description: Find and remove duplicate dependencies
---
Review package.json for duplicate dependencies and remove them.
Use npm ls --depth=0 to identify duplicates.
Propose removals and execute only after confirmation.
```
Source: [.claude/commands/dedupe.md](https://github.com/anthropics/claude-code/blob/main/.claude/commands/dedupe.md)
## Community Commands
The Claude Code community has developed numerous command collections:
| Collection | Description |
|------------|-------------|
| [awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code) | Curated list of slash commands, skills, and extensions |
| [claude-code-skills](https://github.com/levnikolaevich/claude-code-skills) | Plugin suite with bundled MCP servers |
Source: [Community Social Signals](https://x.com/JackCulpan/status/2015182846705717535)
## Related Components
Slash Commands often work in conjunction with other Claude Code features:
- **Agents**: Autonomous subtasks triggered by commands
- **Skills**: Specialized knowledge loaded during command execution
- **Hooks**: Event-driven automation that can intercept command execution
- **CLAUDE.md**: Project-level instructions that commands inherit
For creating commands as part of a plugin, use the `/feature-dev` workflow which guides through component planning and implementation.
Source: [plugins/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/README.md)
---
## Agents and Subagents
### Related Pages
Related topics: [Slash Commands](#slash-commands), [Plugin System Architecture](#plugin-system)
Related Source Files
The following source files were used to generate this page:
- [plugins/plugin-dev/skills/agent-development/SKILL.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/agent-development/SKILL.md)
- [plugins/plugin-dev/agents/agent-creator.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/agents/agent-creator.md)
- [plugins/feature-dev/agents/code-architect.md](https://github.com/anthropics/claude-code/blob/main/plugins/feature-dev/agents/code-architect.md)
- [plugins/feature-dev/agents/code-explorer.md](https://github.com/anthropics/claude-code/blob/main/plugins/feature-dev/agents/code-explorer.md)
- [plugins/feature-dev/agents/code-reviewer.md](https://github.com/anthropics/claude-code/blob/main/plugins/feature-dev/agents/code-reviewer.md)
- [plugins/pr-review-toolkit/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/pr-review-toolkit/README.md)
# Agents and Subagents
Agents are specialized AI subagents that Claude Code uses to perform focused, autonomous tasks. They operate as independent problem-solving units that can analyze code, generate implementations, validate outputs, and orchestrate complex workflows. The agent system enables Claude to delegate specific responsibilities to purpose-built agents, improving task specialization and reducing context overhead.
## Architecture Overview
Agents in Claude Code are defined as Markdown files with YAML frontmatter that configure their behavior, capabilities, and triggering conditions. Each agent consists of:
1. **YAML Frontmatter** — Metadata that defines the agent's identity, model preferences, available tools, and trigger conditions
2. **System Prompt** — Detailed instructions that guide the agent's behavior and decision-making process
3. **Resources** — Optional references, examples, and scripts that provide additional context
```mermaid
graph TD
A[Main Claude Session] -->|launches| B[Agent]
B --> C[YAML Frontmatter]
B --> D[System Prompt]
B --> E[Resources]
B --> F{Tools}
F --> G[Read]
F --> H[Write]
F --> I[Bash]
F --> J[Edit]
F --> K[Grep]
```
## Agent File Structure
Agents are stored as `.md` files in either user-level (`~/.claude/agents/`) or project-level (`.claude/agents/`) directories.
### YAML Frontmatter Fields
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Unique identifier for the agent |
| `description` | string | Yes | Human-readable description of the agent's purpose |
| `model` | string | No | Preferred model for this agent (defaults to main session model) |
| `color` | string | No | UI color indicator for agent output |
| `tools` | array | No | List of tools the agent can use |
| `triggers` | array | No | Phrases that should activate this agent |
Source: [plugins/plugin-dev/skills/agent-development/SKILL.md]()
### System Prompt Structure
The system prompt defines what the agent actually does. Effective system prompts follow these patterns:
- **Analysis** — Code review, pattern identification, architecture assessment
- **Generation** — Code creation, file scaffolding, template population
- **Validation** — Quality checking, error detection, compliance verification
- **Orchestration** — Coordinating multiple tasks, managing workflows
```yaml
---
name: code-reviewer
description: Expert code reviewer that analyzes PRs for quality and best practices
model: sonnet
color: yellow
tools:
- Read
- Grep
- Bash
---
# Code Reviewer
You are an expert code reviewer. Your role is to...
```
## Agent Triggering Mechanism
Agents are activated through specific trigger phrases in user prompts. The `description` field contains `` blocks that define reliable activation patterns.
```mermaid
graph LR
A[User Prompt] --> B{Trigger Matching}
B -->|"Check code quality"| C[code-reviewer]
B -->|"Find similar patterns"| D[code-explorer]
B -->|"Design architecture"| E[code-architect]
B -->|No match| F[Main Claude Session]
```
### Description Format with Examples
Agent descriptions use `` blocks to define precise triggering conditions:
```yaml
description: |
Expert at analyzing code architecture and suggesting improvements.
"Design a new API layer for the auth module"
"Suggest architecture changes for better scalability"
"Review the current layered architecture"
```
## Built-in Feature Dev Agents
The `feature-dev` plugin provides a set of specialized agents for structured feature development:
### Code Explorer Agent
Analyzes existing codebase patterns and traces implementation paths.
**Purpose**: Understand how similar features are implemented before building new ones.
**Trigger phrases**:
- "Find features similar to..."
- "Trace the implementation of..."
- "How does the existing... work?"
Source: [plugins/feature-dev/agents/code-explorer.md]()
### Code Architect Agent
Designs system architecture and technical specifications.
**Purpose**: Create elegant, maintainable designs before implementation begins.
**Trigger phrases**:
- "Design a solution for..."
- "Create an architecture for..."
- "What would a good design look like?"
Source: [plugins/feature-dev/agents/code-architect.md]()
### Code Reviewer Agent
Performs thorough code quality analysis.
**Purpose**: Ensure code meets standards before merging.
**Trigger phrases**:
- "Review this code for..."
- "Check for best practices in..."
- "Analyze the code quality of..."
Source: [plugins/feature-dev/agents/code-reviewer.md]()
## PR Review Toolkit Agents
The `pr-review-toolkit` plugin bundles specialized agents for comprehensive pull request review:
| Agent | Focus Area | Key Capabilities |
|-------|------------|------------------|
| `comment-analyzer` | Documentation | Comment accuracy, documentation completeness, comment rot detection |
| `pr-test-analyzer` | Testing | Test coverage quality, behavioral coverage, edge case identification |
| `silent-failure-hunter` | Error Handling | Silent failures, inadequate error handling, missing logging |
| `type-design-analyzer` | Type Safety | Type design, interface quality, type inference issues |
| `code-reviewer` | Code Quality | General code quality, maintainability, readability |
| `code-simplifier` | Simplification | Complex code reduction, unnecessary abstraction removal |
Source: [plugins/pr-review-toolkit/README.md]()
## Creating Custom Agents
Claude Code provides the `agent-creator` agent for AI-assisted agent generation:
### Workflow
1. **Describe the agent's purpose** — Define what task the agent should handle
2. **Generate components** — The agent-creator produces identifier, description, system prompt
3. **Create the file** — Generate Markdown file with proper frontmatter
4. **Validate** — Run `validate-agent.sh` to check format compliance
```mermaid
graph TD
A[Define Agent Purpose] --> B[Launch agent-creator]
B --> C[Generate frontmatter]
B --> D[Write system prompt]
C --> E[Create agent file]
D --> E
E --> F[validate-agent.sh]
F --> G{Valid?}
G -->|Yes| H[Agent Ready]
G -->|No| I[Fix Issues]
I --> E
```
### Frontmatter Configuration
```yaml
---
name: my-custom-agent
description: |
Brief description of what this agent does.
"Action that triggers agent"
model: sonnet
color: green
tools:
- Read
- Write
- Bash
- Grep
---
```
Source: [plugins/plugin-dev/agents/agent-creator.md]()
## Tool Configuration
Agents can be configured with specific tool sets that determine their capabilities:
| Tool | Purpose |
|------|---------|
| `Read` | Read file contents |
| `Write` | Create or overwrite files |
| `Edit` | Modify specific portions of files |
| `Bash` | Execute shell commands |
| `Grep` | Search file contents |
| `Glob` | Find files by pattern |
| `WebFetch` | Retrieve web content |
| `TodoWrite` | Track progress |
Source: [plugins/plugin-dev/skills/agent-development/SKILL.md]()
## Known Limitations
### CLAUDE.md Rule Propagation
A documented issue affects subagent behavior regarding CLAUDE.md rule inheritance:
> **Issue #59309**: CLAUDE.md rules not propagated to Agent subagents and weakened after context compaction.
Specifically:
- Agent subagents do not inherit the parent session's CLAUDE.md rules
- After context compaction, rule adherence degrades significantly
This limitation means agents launched from Claude Code may not follow project-specific instructions that are defined in CLAUDE.md files.
## Best Practices
### Agent Design Principles
1. **Clear, focused scope** — Each agent should do one thing well
2. **Specific trigger conditions** — Use concrete examples in descriptions
3. **Appropriate tool access** — Grant minimum necessary tools
4. **Model selection** — Choose models suited to task complexity
5. **Comprehensive system prompts** — Include edge cases and quality standards
### System Prompt Guidelines
- Start with clear role definition
- Define input/output expectations
- Include working examples
- Specify quality criteria
- Handle edge cases explicitly
Source: [plugins/plugin-dev/skills/agent-development/SKILL.md]()
## Directory Structure
```
~/.claude/
└── agents/
├── code-explorer.md
├── code-architect.md
├── code-reviewer.md
└── custom-agents/
└── my-agent.md
.claude/ (project-level)
└── agents/
└── project-specific-agent.md
```
User-level agents (`~/.claude/agents/`) are available globally, while project-level agents (`.claude/agents/`) are scoped to specific repositories.
---
## Hooks System
### Related Pages
Related topics: [Slash Commands](#slash-commands), [Plugin System Architecture](#plugin-system)
Related Source Files
The following source files were used to generate this page:
- [plugins/security-guidance/hooks/security_reminder_hook.py](https://github.com/anthropics/claude-code/blob/main/plugins/security-guidance/hooks/security_reminder_hook.py)
- [plugins/security-guidance/hooks/hooks.json](https://github.com/anthropics/claude-code/blob/main/plugins/security-guidance/hooks/hooks.json)
- [plugins/hookify/hooks/hooks.json](https://github.com/anthropics/claude-code/blob/main/plugins/hookify/hooks/hooks.json)
- [plugins/hookify/hooks/pretooluse.py](https://github.com/anthropics/claude-code/blob/main/plugins/hookify/hooks/pretooluse.py)
- [plugins/hookify/hooks/posttooluse.py](https://github.com/anthropics/claude-code/blob/main/plugins/hookify/hooks/posttooluse.py)
- [plugins/hookify/hooks/stop.py](https://github.com/anthropics/claude-code/blob/main/plugins/hookify/hooks/stop.py)
- [plugins/plugin-dev/skills/hook-development/SKILL.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/hook-development/SKILL.md)
- [examples/hooks/bash_command_validator_example.py](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py)
# Hooks System
The Hooks System in Claude Code provides event-driven automation that intercepts and responds to specific actions during Claude's execution. Hooks enable developers to validate operations, enforce policies, trigger notifications, and modify behavior at key points in the tool-use lifecycle.
## Overview
Hooks serve as middleware between Claude Code and tool execution, allowing custom logic to run before tools are invoked, after tools complete, or when specific events occur. This system is fundamental to building security-conscious plugins, implementing workflow automation, and customizing Claude Code behavior.
The Hooks System supports multiple programming languages for hook implementations, with primary support for Python and Bash scripts. Hooks are configured through a declarative `hooks.json` file that defines which hooks to activate and their execution parameters.
**Key capabilities:**
- Intercept tool execution for validation and modification
- Enforce security policies and best practices
- Automate workflows based on conversation events
- Provide warnings and阻止 potentially dangerous operations
- Enable custom logging and analytics
Source: [plugins/plugin-dev/skills/hook-development/SKILL.md]()
## Architecture
### Hook Execution Model
```mermaid
graph TD
A[User Request] --> B[Tool Selection]
B --> C{PreToolUse Hooks}
C -->|Allow| D[Execute Tool]
C -->|Block| E[Show Warning]
C -->|Modify| F[Modified Tool Call]
D --> G[Tool Result]
G --> H{PostToolUse Hooks}
H --> I[Process Result]
I --> J[Continue Conversation]
K[Stop Event] --> L[Stop Hooks]
L --> M[Continue/Cancel Decision]
```
### Hook Types
| Hook Type | Trigger | Purpose |
|-----------|---------|---------|
| `PreToolUse` | Before tool execution | Validate, modify, or block tool calls |
| `PostToolUse` | After tool execution | Log, transform results, or trigger actions |
| `Stop` | When conversation attempts to end | Continue iteration or allow termination |
| `PreConversation` | Before conversation starts | Initialize context or settings |
| `PostConversation` | After conversation ends | Cleanup or final reporting |
Source: [plugins/plugin-dev/skills/hook-development/SKILL.md]()
## Configuration
### hooks.json Structure
Hooks are configured in `hooks/hooks.json` within a plugin or project's `.claude` directory:
```json
{
"hooks": [
{
"name": "security-reminder",
"description": "Warns about potentially dangerous operations",
"events": ["PreToolUse"],
"parallel": false
}
]
}
```
**Configuration fields:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Unique identifier for the hook |
| `description` | string | Yes | Human-readable description of hook purpose |
| `events` | array | Yes | Array of event types to listen for |
| `parallel` | boolean | No | Execute hooks in parallel when true (default: false) |
Source: [plugins/security-guidance/hooks/hooks.json]()
### Event Mapping
| Event | Description | Available Data |
|-------|-------------|----------------|
| `PreToolUse` | Before any tool is used | Tool name, arguments, session context |
| `PostToolUse` | After any tool completes | Tool name, result, error status |
| `Stop` | Conversation termination requested | Exit reason, session state |
Source: [plugins/hookify/hooks/hooks.json]()
## PreToolUse Hooks
PreToolUse hooks execute before tool invocation, allowing validation, modification, or blocking of tool calls.
### Execution Flow
```mermaid
graph TD
A[PreToolUse Event] --> B{Continue?}
B -->|No| C[Return Continue: false]
B -->|Yes| D{Should Modify?}
D -->|No| E[Execute Original Tool Call]
D -->|Yes| F[Return Modified Tool Call]
F --> G[Execute Modified Tool Call]
style B fill:#f9f,color:#000
style D fill:#ff9,color:#000
```
### Return Values
A PreToolUse hook can return one of the following:
| Return | Effect |
|--------|--------|
| `{ continue: true }` | Proceed with original tool call |
| `{ continue: false, response: "message" }` | Block tool, show message |
| `{ continue: true, toolCall: modifiedCall }` | Execute modified tool call |
Source: [plugins/hookify/hooks/pretooluse.py]()
### Example: Security Reminder Hook
```python
#!/usr/bin/env python3
"""Security reminder hook for dangerous operations."""
SECURITY_PATTERNS = [
("rm -rf", "Recursive removal can permanently delete files"),
("eval", "Dynamic code execution is a security risk"),
("chmod 777", "World-writable permissions are insecure"),
# ... additional patterns
]
def pretoolusehook(tool_name, tool_input):
"""Check for potentially dangerous commands."""
if tool_name == "Bash":
command = tool_input.get("command", "")
for pattern, warning in SECURITY_PATTERNS:
if pattern in command:
return {
"continue": True,
"response": f"Warning: {warning}\n\nCommand: {command}"
}
return {"continue": True}
```
Source: [plugins/security-guidance/hooks/security_reminder_hook.py]()
## PostToolUse Hooks
PostToolUse hooks execute after tool completion, enabling result processing, logging, and follow-up actions.
### Execution Flow
```mermaid
graph TD
A[Tool Execution Complete] --> B[PostToolUse Hook Called]
B --> C{Process Result?}
C -->|Log| D[Write to Log/Analytics]
C -->|Transform| E[Modify Response]
C -->|Trigger| F[Execute Follow-up Action]
B --> G[Return Processed Result]
```
### Return Values
| Return | Effect |
|--------|--------|
| `{ continue: true }` | Return original result |
| `{ continue: true, response: modified }` | Return modified result |
| `{ continue: false }` | Block result propagation |
Source: [plugins/hookify/hooks/posttooluse.py]()
## Stop Hooks
Stop hooks intercept conversation termination, enabling autonomous iteration loops and workflow continuation.
### Example: Ralph-Wiggum Iteration Hook
The Ralph-Wiggum plugin demonstrates Stop hooks for iterative development:
```json
{
"name": "continue-iteration",
"description": "Intercept stop to continue iteration loop",
"events": ["Stop"]
}
```
```python
#!/bin/bash
# Continue iteration if work remains
if [ -f "$HOOK_STATE_FILE" ]; then
echo "Work remains, continuing iteration..."
exit 0 # Allow continuation
fi
exit 1 # Allow stop
```
Source: [plugins/hookify/hooks/stop.py]()
### Stop Event Data
| Field | Type | Description |
|-------|------|-------------|
| `reason` | string | Reason for stop request |
| `hasError` | boolean | Whether an error triggered the stop |
| `sessionState` | object | Current session context |
## Development Workflow
### Creating a Hook
1. **Plan hook behavior:**
- Identify which event to hook (PreToolUse, PostToolUse, Stop)
- Define validation criteria or modifications
- Determine return values
2. **Create hook implementation:**
- Python scripts for complex logic
- Bash scripts for simple operations
- Include proper shebang for execution
3. **Register in hooks.json:**
- Add hook configuration with name, description, events
- Set parallel execution if needed
4. **Test and validate:**
- Use `validate-hook-schema.sh` to verify configuration
- Test with `test-hook.sh` utility
- Validate in actual Claude Code usage
### Best Practices
| Practice | Rationale |
|----------|-----------|
| Use Python for complex logic | Better string parsing, regex, data structures |
| Use Bash for simple checks | Faster startup, system command access |
| Return quickly when possible | Minimize latency impact on tool execution |
| Log errors gracefully | Prevent hook failures from breaking tools |
| Document pattern matching | Help maintainers understand validation rules |
Source: [plugins/plugin-dev/skills/hook-development/SKILL.md]()
## Hookify Plugin
The Hookify plugin provides a simplified interface for creating hooks without editing complex JSON files.
### Features
- **Pattern-based rules**: Define hooks through markdown configuration
- **Automatic analysis**: Detects unwanted behaviors from conversation history
- **Quick enable/disable**: Toggle rules without restart
- **Regex support**: Powerful pattern matching capabilities
### Usage
```bash
# Create rule from explicit instruction
/hookify Warn me when I use rm -rf commands
# Analyze conversation for patterns
/hookify
# List all rules
/hookify:list
# Configure rules interactively
/hookify:configure
```
### Hookify Rule Format
```markdown
# .claude/hookify.warn-rm.local.md
---
trigger:
tool: Bash
pattern: "rm -rf"
severity: warning
message: "Recursive removal is dangerous. Consider using rm -I instead."
---
```
Source: [plugins/hookify/README.md]()
## Security Hooks
The security-guidance plugin demonstrates comprehensive hook usage for security enforcement.
### Monitored Patterns
| Pattern Type | Examples | Severity |
|--------------|----------|----------|
| Command injection | `; rm`, `&& rm`, `\| sh` | Critical |
| Shell execution | `os.system`, `subprocess` with shell=True | High |
| Eval usage | `eval(`, `exec(` | High |
| Dangerous HTML | `.innerHTML =`, `document.write` | Medium |
| File operations | `chmod 777`, `chmod +x` | Medium |
| Data serialization | `pickle.load`, `yaml.load` | Medium |
### Security Hook Implementation
```python
def pretoolusehook(tool_name, tool_input):
"""Monitor for security-sensitive operations."""
if tool_name == "Bash":
command = tool_input.get("command", "")
if contains_injection_pattern(command):
return {
"continue": False,
"response": "Command injection detected. Refusing to execute."
}
if tool_name == "Write":
content = tool_input.get("content", "")
if contains_dangerous_html(content):
return {
"continue": True,
"response": "Warning: Writing potentially dangerous HTML content"
}
return {"continue": True}
```
Source: [plugins/security-guidance/hooks/security_reminder_hook.py]()
## Plugin Integration
### Plugin Directory Structure
```
plugins/
my-plugin/
hooks/
hooks.json # Hook configuration
pretooluse.py # PreToolUse implementation
posttooluse.py # PostToolUse implementation
stop.sh # Stop hook implementation
```
### Referencing Plugin Paths
Use `${CLAUDE_PLUGIN_ROOT}` for portable paths in hook scripts:
```bash
#!/bin/bash
CONFIG="${CLAUDE_PLUGIN_ROOT}/config/settings.json"
LOG_FILE="${CLAUDE_PLUGIN_ROOT}/logs/hook.log"
```
Source: [plugins/plugin-dev/skills/hook-development/SKILL.md]()
## Examples
### Bash Command Validator
```python
#!/usr/bin/env python3
"""Validate bash commands before execution."""
import re
import sys
import json
DANGEROUS_PATTERNS = [
(r'rm\s+-rf\s+/', "Refusing to recursively delete root"),
(r'>\s*/dev/sd', "Direct device writing is dangerous"),
(r'chmod\s+-R\s+777', "World-writable permissions are insecure"),
]
def pretoolusehook(tool_name, tool_input):
if tool_name != "Bash":
return {"continue": True}
command = tool_input.get("command", "")
for pattern, message in DANGEROUS_PATTERNS:
if re.search(pattern, command):
return {
"continue": False,
"response": f"SECURITY: {message}\n\nCommand: {command}"
}
return {"continue": True}
if __name__ == "__main__":
input_data = json.load(sys.stdin)
result = pretoolusehook(
input_data.get("tool_name"),
input_data.get("tool_input", {})
)
print(json.dumps(result))
```
Source: [examples/hooks/bash_command_validator_example.py]()
## Environment Variables
Hooks have access to the following environment variables:
| Variable | Description |
|----------|-------------|
| `CLAUDE_PLUGIN_ROOT` | Root directory of the containing plugin |
| `CLAUDE_PROJECT_ROOT` | Root of the current project |
| `CLAUDE_HOOK_EVENT` | Current event type being processed |
| `CLAUDE_SESSION_ID` | Unique identifier for current session |
| `HOOK_STATE_FILE` | Path to hook state persistence file (if set) |
Source: [plugins/plugin-dev/skills/hook-development/SKILL.md]()
## Limitations and Considerations
### Performance Impact
- Hooks add latency to tool execution
- Parallel execution reduces impact for multiple hooks
- Complex pattern matching in Python can be slower than simple Bash checks
### Error Handling
- Hook failures should not break tool execution
- Return `{"continue": true}` on error to allow tools to proceed
- Log errors for debugging without blocking operations
### Context Limitations
- Hooks have limited context to conversation history
- Large file content may not be fully available for validation
- Consider using agents for complex analysis within hooks
## Related Documentation
- [Plugin Development Guide](../plugin-dev/README.md) - Full plugin development workflow
- [Hook Development Skill](../plugin-dev/skills/hook-development/SKILL.md) - Detailed hook implementation reference
- [Hookify Plugin](../hookify/README.md) - Simplified hook creation
- [Security Guidance Plugin](../security-guidance/README.md) - Security-focused hooks example
---
## Plugin System Architecture
### Related Pages
Related topics: [Official Plugins Reference](#official-plugins), [Slash Commands](#slash-commands), [Agents and Subagents](#agents), [Hooks System](#hooks)
Related Source Files
The following source files were used to generate this page:
- [plugins/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/README.md)
- [plugins/plugin-dev/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/README.md)
- [plugins/plugin-dev/skills/plugin-structure/SKILL.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/plugin-structure/SKILL.md)
- [plugins/plugin-dev/skills/plugin-structure/references/manifest-reference.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/plugin-structure/references/manifest-reference.md)
- [plugins/plugin-dev/skills/plugin-structure/references/component-patterns.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/plugin-structure/references/component-patterns.md)
- [plugins/plugin-dev/commands/create-plugin.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/commands/create-plugin.md)
- [.claude-plugin/marketplace.json](https://github.com/anthropics/claude-code/blob/main/.claude-plugin/marketplace.json)
# Plugin System Architecture
Claude Code's plugin system provides an extensible framework for customizing and extending the CLI's behavior through a modular architecture. Plugins can add commands, agents, skills, hooks, and MCP server integrations that integrate seamlessly with Claude Code's core functionality.
## Overview
The plugin architecture is designed around several core principles:
- **Auto-discovery**: Plugins are automatically discovered and loaded from standard locations
- **Component-based**: Plugins compose functionality from reusable components
- **Portable paths**: All file references use `${CLAUDE_PLUGIN_ROOT}` for portability
- **Progressive disclosure**: Documentation layers allow for incremental complexity
- **Validation-first**: Components are validated before deployment
Source: [plugins/plugin-dev/skills/plugin-structure/SKILL.md]()
## Directory Structure
Plugins follow a standardized directory structure that enables Claude Code to discover and load components automatically.
```
plugin-name/
├── plugin.json # Plugin manifest
├── README.md # Documentation
├── commands/ # Slash commands
│ ├── command-name.md
│ └── ...
├── agents/ # Subagent definitions
│ ├── agent-name.md
│ └── ...
├── skills/ # Skill definitions
│ ├── skill-name/
│ │ ├── SKILL.md
│ │ ├── README.md
│ │ ├── references/
│ │ └── examples/
│ └── ...
├── hooks/ # Hook configurations
│ ├── hooks.json
│ └── scripts/
├── mcp/ # MCP server configurations
│ └── .mcp.json
└── scripts/ # Utility scripts
└── ...
```
Source: [plugins/plugin-dev/skills/plugin-structure/references/component-patterns.md]()
### Directory Organization Patterns
| Pattern | Use Case | Structure |
|---------|----------|-----------|
| **Minimal** | Single-purpose plugins | Flat structure with plugin.json and one component |
| **Standard** | Production plugins | Organized directories per component type |
| **Advanced** | Enterprise plugins | Multi-level organization, shared libraries, MCP servers |
Source: [plugins/plugin-dev/skills/plugin-structure/references/component-patterns.md]()
## Plugin Manifest
The `plugin.json` manifest is the entry point for every plugin. It declares metadata, dependencies, and the components available in the plugin.
### Manifest Fields
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Unique identifier for the plugin |
| `version` | string | Yes | Semantic version string |
| `description` | string | Yes | Human-readable description |
| `authors` | string[] | No | List of author names or emails |
| `homepage` | string | No | URL to plugin homepage |
| `readme` | string | No | Path to README file (default: README.md) |
| `license` | string | No | SPDX license identifier |
| `commands` | string[] | No | Paths to command files |
| `agents` | string[] | No | Paths to agent files |
| `skills` | string[] | No | Paths to skill directories |
| `hooks` | string | No | Path to hooks.json file |
| `mcpServers` | string[] | No | Paths to MCP server configurations |
| `conditions` | object | No | Runtime conditions for plugin activation |
Source: [plugins/plugin-dev/skills/plugin-structure/references/manifest-reference.md]()
### Example Manifest
```json
{
"name": "pr-review-toolkit",
"version": "1.0.0",
"description": "Comprehensive PR review agents specializing in comments, tests, error handling, type design, code quality, and code simplification",
"authors": ["Claude Team "],
"readme": "README.md",
"license": "MIT",
"commands": [
"commands/pr-review.md"
],
"agents": [
"agents/comment-analyzer.md",
"agents/pr-test-analyzer.md",
"agents/silent-failure-hunter.md",
"agents/type-design-analyzer.md",
"agents/code-reviewer.md",
"agents/code-simplifier.md"
]
}
```
Source: [.claude-plugin/marketplace.json]()
## Component Types
The plugin system supports five primary component types, each serving a distinct purpose in extending Claude Code's functionality.
```mermaid
graph TD
A[Plugin] --> B[Commands]
A --> C[Agents]
A --> D[Skills]
A --> E[Hooks]
A --> F[MCP Servers]
B --> B1[User-initiated actions]
C --> C1[Autonomous subagents]
D --> D1[Specialized knowledge]
E --> E1[Event-driven automation]
F --> F1[External service integration]
```
Source: [plugins/plugin-dev/README.md]()
### Commands
Commands are slash-prefixed actions that users invoke directly. They are defined as markdown files with YAML frontmatter.
**Frontmatter Fields:**
| Field | Type | Description |
|-------|------|-------------|
| `description` | string | Help text shown in command list |
| `argument-hint` | string | Placeholder text for arguments |
| `allowed-tools` | string[] | Tools the command may use |
Source: [plugins/plugin-dev/skills/plugin-structure/references/manifest-reference.md]()
**Example Command Structure:**
```markdown
---
description: Guided feature development with codebase understanding
argument-hint: Optional feature description
---
# Feature Development
You are helping a developer implement a new feature...
```
Source: [plugins/plugin-dev/commands/create-plugin.md]()
### Agents
Agents are autonomous subagents that Claude Code can launch to perform specialized tasks. Each agent is defined with a markdown file containing YAML frontmatter and a system prompt.
**Agent Frontmatter Fields:**
| Field | Type | Description |
|-------|------|-------------|
| `description` | string | What the agent does |
| `whenToUse` | string | Triggers and usage examples |
| `model` | string | Model override (optional) |
| `color` | string | UI color identifier (optional) |
| `tools` | string[] | Available tools for this agent |
Source: [plugins/plugin-dev/skills/plugin-structure/references/component-patterns.md]()
### Skills
Skills provide specialized knowledge and patterns that Claude Code uses when performing specific tasks. They support progressive disclosure through layered documentation.
**Skill Structure:**
```
skill-name/
├── SKILL.md # Core skill content (~1,500-2,000 words)
├── README.md # Overview and usage guide
├── references/ # Detailed reference documentation
│ ├── field-reference.md
│ └── patterns.md
└── examples/ # Working examples
└── example-name.md
```
Source: [plugins/plugin-dev/skills/plugin-structure/SKILL.md]()
### Hooks
Hooks enable event-driven automation by intercepting Claude Code events and executing custom logic.
**Available Hook Events:**
| Event | Timing | Purpose |
|-------|--------|---------|
| `PreToolUse` | Before tool execution | Validate, modify, or block tool calls |
| `PostToolUse` | After tool execution | Inspect results, trigger side effects |
| `Stop` | On conversation end | Intercept or delay session termination |
| `SubagentStop` | On subagent termination | Handle subagent lifecycle events |
| `SessionStart` | On session begin | Initialize session state |
| `SessionEnd` | On session termination | Cleanup and finalization |
| `UserPromptSubmit` | On user input | Process or validate user prompts |
| `PreCompact` | Before context compaction | Prepare for context reduction |
| `Notification` | On notifications | Handle notification events |
Source: [plugins/plugin-dev/skills/plugin-structure/references/component-patterns.md]()
**Hook Configuration:**
```json
{
"hooks": [
{
"event": "PreToolUse",
"name": "validate-write",
"prompt": "Check if the file write is safe and follows best practices"
}
]
}
```
### MCP Servers
MCP (Model Context Protocol) server integration allows plugins to connect to external services, APIs, databases, and tools.
**Server Types:**
| Type | Transport | Use Case |
|------|-----------|----------|
| `stdio` | Standard I/O | Local MCP servers |
| `SSE` | Server-Sent Events | Hosted MCP services |
| `HTTP` | HTTP/REST | REST API integrations |
Source: [plugins/plugin-dev/skills/plugin-structure/references/component-patterns.md]()
**Example MCP Configuration:**
```json
{
"mcpServers": {
"database": {
"type": "stdio",
"command": "node",
"args": ["${CLAUDE_PLUGIN_ROOT}/mcp/database-server.js"],
"env": {
"DATABASE_URL": "${DATABASE_URL}"
}
}
}
}
```
## Plugin Discovery
Claude Code discovers plugins through multiple mechanisms:
```mermaid
graph LR
A[Discovery Locations] --> B[Global Plugins]
A --> C[Project Plugins]
A --> D[Marketplace]
B --> E[~/.claude/plugins/]
C --> F[.claude/ directory]
D --> G[/plugin install command]
E --> H[Auto-load on startup]
F --> H
G --> H
```
Source: [plugins/plugin-dev/skills/plugin-structure/SKILL.md]()
### Discovery Locations
| Location | Scope | Purpose |
|----------|-------|---------|
| `~/.claude/plugins/` | Global | Available to all projects |
| `.claude/` | Project | Project-specific plugins |
| Marketplace | Remote | Downloaded on demand |
Source: [plugins/plugin-dev/skills/plugin-structure/references/component-patterns.md]()
### Auto-Discovery Mechanism
When Claude Code starts, it scans plugin directories and:
1. Locates all directories containing `plugin.json`
2. Validates the manifest structure
3. Registers commands, agents, and skills
4. Configures hooks and MCP servers
5. Makes plugins available to the user
## Built-in Plugins
Claude Code includes several official plugins:
| Plugin | Purpose | Key Components |
|--------|---------|----------------|
| `plugin-dev` | Plugin creation and development | 7 skills, 8-phase workflow |
| `feature-dev` | Systematic feature development | 3-phase exploration process |
| `pr-review-toolkit` | Pull request review automation | 6 specialized review agents |
| `hookify` | Custom hook creation | Pattern-based rules system |
| `frontend-design` | UI generation with distinctive aesthetics | Design skill |
| `agent-sdk-dev` | Agent SDK application development | Project scaffolding |
Source: [plugins/README.md]()
## Plugin Development Workflow
The `plugin-dev` plugin provides a structured 8-phase workflow for creating plugins:
```mermaid
graph TD
A[Phase 1: Discovery] --> B[Phase 2: Planning]
B --> C[Phase 3: Clarifying Questions]
C --> D[Phase 4: Structure Creation]
D --> E[Phase 5: Implementation]
E --> F[Phase 6: Validation]
F --> G[Phase 7: Testing]
G --> H[Phase 8: Documentation]
H --> I[Complete Plugin]
F -.->|Issues Found| E
G -.->|Failures| E
```
Source: [plugins/plugin-dev/commands/create-plugin.md]()
### Phase Details
| Phase | Goal | Key Activities |
|-------|------|----------------|
| 1. Discovery | Understand plugin purpose | Identify problem, target users, scope |
| 2. Planning | Determine components | Select commands, agents, skills, hooks, MCP |
| 3. Clarification | Resolve ambiguities | Ask targeted questions, define requirements |
| 4. Structure | Create directories | Set up layout, write manifest |
| 5. Implementation | Build components | Use specialized agents and skills |
| 6. Validation | Quality check | Run validators, check patterns |
| 7. Testing | Verify functionality | Test in Claude Code |
| 8. Documentation | Finalize docs | Write README, examples |
Source: [plugins/plugin-dev/README.md]()
## Component Lifecycle
Components follow a consistent lifecycle from discovery through activation:
```mermaid
graph TD
A[Discovery] --> B[Parsing]
B --> C[Validation]
C --> D{Valid?}
D -->|Yes| E[Registration]
D -->|No| F[Error/Warning]
E --> G[Activation]
G --> H[Execution]
H --> I[Deactivation]
I --> J[Cleanup]
```
Source: [plugins/plugin-dev/skills/plugin-structure/references/component-patterns.md]()
## Best Practices
### Security
- Always use HTTPS for remote resources
- Never hardcode credentials in plugin files
- Use environment variables via `${ENV_VAR}` syntax
- Validate all inputs in hook scripts
### Portability
- Replace all hardcoded paths with `${CLAUDE_PLUGIN_ROOT}`
- Use relative paths within the plugin directory
- Make paths configurable via settings files
### Documentation
- Provide clear descriptions for all components
- Include usage examples for skills and commands
- Document required environment variables
- Provide troubleshooting guidance in README
### Quality Standards
| Standard | Requirement |
|----------|-------------|
| Naming | Consistent conventions (kebab-case for files) |
| Triggers | Strong trigger phrases for skills/agents |
| Examples | Working examples for every component |
| Validation | Pass all validation utilities before release |
| Testing | Verified in actual Claude Code sessions |
Source: [plugins/plugin-dev/README.md]()
## Related Documentation
- [Plugin Structure Skill](plugins/plugin-dev/skills/plugin-structure/) - Core plugin architecture documentation
- [Command Development](plugins/plugin-dev/skills/command-development/) - Slash command creation
- [Agent Development](plugins/plugin-dev/skills/agent-development/) - Subagent creation
- [Hook Development](plugins/plugin-dev/skills/hook-development/) - Event-driven automation
- [MCP Integration](plugins/plugin-dev/skills/mcp-integration/) - External service integration
---
## Official Plugins Reference
### Related Pages
Related topics: [Plugin System Architecture](#plugin-system), [MDM and Enterprise Deployment](#mdm-deployment)
Related Source Files
The following source files were used to generate this page:
- [plugins/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/README.md)
- [plugins/plugin-dev/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/README.md)
- [plugins/plugin-dev/skills/plugin-structure/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/plugin-structure/README.md)
- [plugins/plugin-dev/skills/command-development/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/command-development/README.md)
- [plugins/plugin-dev/commands/create-plugin.md](https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/commands/create-plugin.md)
- [plugins/feature-dev/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/feature-dev/README.md)
- [plugins/pr-review-toolkit/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/pr-review-toolkit/README.md)
- [plugins/hookify/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/hookify/README.md)
- [plugins/agent-sdk-dev/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/agent-sdk-dev/README.md)
- [plugins/security-guidance/README.md](https://github.com/anthropics/claude-code/blob/main/plugins/security-guidance/README.md)
# Official Plugins Reference
This reference documents the official plugins bundled with Claude Code, designed to extend and enhance the development workflow. These plugins provide specialized capabilities for feature development, code review, security analysis, plugin creation, and autonomous task execution.
## Overview
Official plugins are pre-installed components that Claude Code automatically loads to provide domain-specific expertise and automation. Each plugin is self-contained with its own commands, agents, skills, and hooks that activate based on user interactions.
| Plugin | Primary Purpose |
|--------|-----------------|
| [plugin-dev](./plugin-dev/) | Build new Claude Code plugins |
| [feature-dev](./feature-dev/) | Systematic feature development workflow |
| [pr-review-toolkit](./pr-review-toolkit/) | Comprehensive PR review agents |
| [code-review](./code-review/) | General code quality review |
| [commit-commands](./commit-commands/) | Git commit generation and management |
| [security-guidance](./security-guidance/) | Security vulnerability detection |
| [agent-sdk-dev](./agent-sdk-dev/) | Agent SDK application development |
| [frontend-design](./frontend-design/) | Production-grade frontend generation |
| [hookify](./hookify/) | Custom hook creation from patterns |
| [ralph-wiggum](./ralph-wiggum/) | Autonomous iterative development loops |
Source: [plugins/README.md]()
## Plugin Architecture
Claude Code plugins follow a standardized structure with auto-discovery mechanisms. Each plugin can contain multiple component types that integrate seamlessly with the core Claude Code experience.
```mermaid
graph TD
A[Claude Code] --> B[Plugin Directory]
B --> C[plugin.json Manifest]
B --> D[commands/]
B --> E[agents/]
B --> F[skills/]
B --> G[hooks/]
B --> H[.mcp.json]
C --> I[Metadata & Auto-discovery]
D --> J[Slash Commands]
E --> K[Autonomous Subagents]
F --> L[Specialized Knowledge]
G --> M[Event-driven Automation]
H --> N[External MCP Servers]
```
### Component Types
| Component | Description | Activation |
|-----------|-------------|------------|
| **Commands** | Slash commands prefixed with `/` | User invocation |
| **Agents** | Autonomous subagents with specialized prompts | Trigger phrases |
| **Skills** | Progressive disclosure documentation | Context matching |
| **Hooks** | Event-driven automation scripts | Tool use, prompts, exits |
| **MCP** | Model Context Protocol server integrations | Service configuration |
Source: [plugins/plugin-dev/skills/plugin-structure/README.md]()
## Development Plugins
### plugin-dev
The plugin development toolkit provides comprehensive guidance for building Claude Code plugins. It offers a guided 8-phase workflow command and seven specialized skills covering all aspects of plugin creation.
**Main Command:** `/plugin-dev:create-plugin`
**Supported Skill Areas:**
| Skill | Focus Area |
|-------|-----------|
| Hook Development | Advanced hooks API and event-driven automation |
| MCP Integration | Model Context Protocol server integration |
| Plugin Structure | Plugin organization and manifest configuration |
| Plugin Settings | `.claude/plugin-name.local.md` configuration patterns |
| Command Development | Slash commands with frontmatter and arguments |
| Agent Development | Autonomous agents with AI-assisted generation |
| Skill Development | Progressive disclosure and strong trigger phrases |
Source: [plugins/plugin-dev/README.md]()
#### Plugin Creation Workflow
The `/plugin-dev:create-plugin` command guides users through an 8-phase process:
| Phase | Goal | Key Actions |
|-------|------|-------------|
| 1 | Discovery | Understand plugin purpose and requirements |
| 2 | Component Planning | Determine skills, commands, agents, hooks, MCP |
| 3 | Detailed Design | Specify each component and resolve ambiguities |
| 4 | Structure Creation | Set up directories and manifest |
| 5 | Component Implementation | Create each component using AI-assisted agents |
| 6 | Validation | Run plugin-validator and component checks |
| 7 | Testing | Verify plugin works in Claude Code |
| 8 | Documentation | Finalize README and prepare for distribution |
Source: [plugins/plugin-dev/commands/create-plugin.md]()
### feature-dev
The Feature Development Plugin implements a systematic 7-phase workflow that prioritizes codebase understanding before implementation.
**Command:** `/feature-dev`
**7-Phase Process:**
```mermaid
graph LR
A[Discovery] --> B[Codebase Exploration]
B --> C[Clarifying Questions]
C --> D[Architecture Design]
D --> E[Implementation]
E --> F[Review & Quality]
F --> G[Cleanup]
```
| Phase | Description |
|-------|-------------|
| Discovery | Clarify what needs to be built, identify constraints |
| Codebase Exploration | Launch code-explorer agents to analyze existing patterns |
| Clarifying Questions | Resolve all ambiguities before implementation |
| Architecture Design | Design elegant, maintainable solutions |
| Implementation | Write code following project standards |
| Review & Quality | Verify quality and CLAUDE.md compliance |
| Cleanup | Remove artifacts and finalize |
Source: [plugins/feature-dev/README.md]()
### agent-sdk-dev
The Agent SDK Development Plugin streamlines creating Claude Agent SDK applications in Python and TypeScript.
**Command:** `/new-sdk-app`
**Features:**
- Interactive project scaffolding
- Latest SDK version detection and installation
- Environment configuration (`.env.example`, `.gitignore`)
- Working examples tailored to use case
- Automatic setup verification
**Agent:** `agent-sdk-verifier` - Validates applications against best practices
Source: [plugins/agent-sdk-dev/README.md]()
## Code Review Plugins
### pr-review-toolkit
The PR Review Toolkit bundles six specialized review agents for comprehensive pull request analysis.
| Agent | Focus | Triggers |
|-------|-------|----------|
| `comment-analyzer` | Code comment accuracy | "Check if comments are accurate" |
| `pr-test-analyzer` | Test coverage quality | "Review test coverage" |
| `silent-failure-hunter` | Error handling | "Review error handling" |
| `type-design-analyzer` | Type system design | "Check type design" |
| `code-reviewer` | General guidelines | "Review my changes" |
| `code-simplifier` | Code clarity | "Simplify this code" |
**Command:** `/pr-review-toolkit:review-pr`
Options: `comments`, `tests`, `errors`, `types`, `code`, `simplify`, `all`
Source: [plugins/pr-review-toolkit/README.md]()
### code-review
A lightweight code review plugin for general quality assessment against project guidelines.
### commit-commands
Git commit management plugin with commands for generating and managing commit messages.
## Automation Plugins
### hookify
The Hookify plugin enables creating custom hooks without editing complex `hooks.json` files. Users create markdown configuration files with regex patterns.
**Commands:**
- `/hookify` - Create rules from instructions or conversation analysis
- `/hookify:list` - List all active rules
- `/hookify:configure` - Enable/disable rules interactively
**Example:**
```bash
/hookify Warn me when I use rm -rf commands
```
Creates `.claude/hookify.warn-rm.local.md` with the specified rule. Rules take effect immediately without restart.
Source: [plugins/hookify/README.md]()
### security-guidance
Security reminder hook that monitors file edits for potential security vulnerabilities.
**Hook Type:** `PreToolUse`
**Monitored Patterns (9 total):**
- Command injection
- Cross-site scripting (XSS)
- `eval()` usage
- Dangerous HTML generation
- Pickle deserialization
- `os.system` calls
- And additional vulnerability patterns
Source: [plugins/security-guidance/README.md]()
### ralph-wiggum
Interactive autonomous iteration plugin where Claude works on the same task repeatedly until completion.
**Commands:**
- `/ralph-loop` - Start autonomous iteration
- `/cancel-ralph` - Stop iteration loop
**Hook:** `Stop` - Intercepts exit attempts to continue iteration
## Design Plugins
### frontend-design
Generates production-grade frontend interfaces with distinctive aesthetics that avoid generic AI patterns.
**Capabilities:**
- Bold aesthetic choices
- Distinctive typography and color palettes
- High-impact animations
- Context-aware implementation
**Usage:**
```
"Create a dashboard for a music streaming app"
"Build a landing page for an AI security startup"
"Design a settings panel with dark mode"
```
Source: [plugins/frontend-design/README.md]()
## Installation
Official plugins are included in the Claude Code repository. To use them in your own projects:
```bash
# Install Claude Code globally
npm install -g @anthropic-ai/claude-code
# Navigate to your project
cd your-project
# Run Claude Code
claude
# Install additional plugins from marketplaces
/plugin install
```
Plugins can also be configured in your project's `.claude/settings.json`:
```json
{
"plugins": ["plugin-dev", "feature-dev", "pr-review-toolkit"]
}
```
Source: [plugins/README.md]()
## Plugin Structure Reference
### Directory Layout
```
plugin-name/
├── plugin.json # Manifest with metadata
├── commands/ # Slash commands (*.md)
├── agents/ # Autonomous agents (*.md)
├── skills/ # Specialized knowledge
│ └── SKILL.md # Core skill content
├── hooks/ # Hook configurations
│ └── hooks.json # Hook definitions
├── .mcp.json # MCP server configurations
└── README.md # Plugin documentation
```
Source: [plugins/plugin-dev/skills/plugin-structure/README.md]()
### Command Organization
Commands support namespacing with colons:
```markdown
---
description: My command description
argument-hint: Optional argument
---
# Command Content
```
Source: [plugins/plugin-dev/skills/command-development/README.md]()
## Community Considerations
Based on community feedback, several issues relate to plugin and extension behavior:
- **CLAUDE.md rules not propagated to Agent subagents** (#59309): Rules defined in CLAUDE.md may not be inherited by autonomous agents spawned during development
- **plugin marketplace crashes on AVX-only CPUs** (#59645): Some plugin marketplace operations may crash on older CPU architectures
- **Security considerations**: The security-guidance plugin helps address concerns about potential vulnerabilities in edited code
These issues are actively being addressed in ongoing development.
---
## MDM and Enterprise Deployment
### Related Pages
Related topics: [Managed Settings Reference](#managed-settings), [Configuration and Settings](#configuration)
Related Source Files
The following source files were used to generate this page:
- [examples/mdm/README.md](https://github.com/anthropics/claude-code/blob/main/examples/mdm/README.md)
- [examples/mdm/macos/com.anthropic.claudecode.mobileconfig](https://github.com/anthropics/claude-code/blob/main/examples/mdm/macos/com.anthropic.claudecode.mobileconfig)
- [examples/mdm/macos/com.anthropic.claudecode.plist](https://github.com/anthropics/claude-code/blob/main/examples/mdm/macos/com.anthropic.claudecode.plist)
- [examples/mdm/windows/ClaudeCode.admx](https://github.com/anthropics/claude-code/blob/main/examples/mdm/windows/ClaudeCode.admx)
- [examples/mdm/windows/Set-ClaudeCodePolicy.ps1](https://github.com/anthropics/claude-code/blob/main/examples/mdm/windows/Set-ClaudeCodePolicy.ps1)
- [examples/mdm/windows/en-US/ClaudeCode.adml](https://github.com/anthropics/claude-code/blob/main/examples/mdm/windows/en-US/ClaudeCode.adml)
- [examples/mdm/managed-settings.json](https://github.com/anthropics/claude-code/blob/main/examples/mdm/managed-settings.json)
# MDM and Enterprise Deployment
## Overview
Claude Code supports enterprise deployment through Mobile Device Management (MDM) systems and Group Policy, enabling organizations to centrally manage Claude Code settings across their workforce. This functionality allows IT administrators to deploy managed settings that control user permissions, default behaviors, and operational constraints.
The deployment system leverages Claude Code's **managed settings** capability, which provides a configuration mechanism for enterprise environments. All deployment templates encode the same minimal example (`permissions.disableBypassPermissionsMode`), demonstrating how to enforce security policies organization-wide. Source: [examples/mdm/README.md](https://github.com/anthropics/claude-code/blob/main/examples/mdm/README.md)
## Deployment Architecture
```mermaid
graph TD
A[Enterprise IT Admin] --> B[MDM Console]
B --> C[Jamf/Kandji]
B --> D[Intune]
B --> E[Group Policy]
C --> F[macOS Devices]
D --> G[Windows Devices]
E --> G
F --> H[Claude Code Settings]
G --> H
```
## Supported Deployment Methods
| Deployment Method | Platform | MDM System | Configuration Format |
|-------------------|----------|------------|----------------------|
| Custom Settings Payload | macOS | Jamf, Kandji (Iru) | `.plist` |
| Configuration Profile | macOS | Any MDM supporting mobileconfig | `.mobileconfig` |
| Platform Scripts | Windows | Intune | PowerShell |
| Group Policy | Windows | Active Directory/GPO | `.admx` / `.adml` |
Source: [examples/mdm/README.md](https://github.com/anthropics/claude-code/blob/main/examples/mdm/README.md)
## Configuration Files
### Managed Settings JSON
The `managed-settings.json` file serves as the universal configuration format deployable to any platform. It should be deployed to the **system config directory** as specified in the settings documentation.
```json
{
"permissions": {
"disableBypassPermissionsMode": true
}
}
```
Source: [examples/mdm/managed-settings.json](https://github.com/anthropics/claude-code/blob/main/examples/mdm/managed-settings.json)
This minimal configuration demonstrates the structure for managed settings, which can be extended with additional keys from the [settings reference](https://code.claude.com/docs/en/settings#available-settings).
### macOS Deployment
#### Custom Settings Payload (.plist)
For Jamf or Kandji deployments, use the preference domain `com.anthropic.claudecode` with a Custom Settings payload.
**File:** `macos/com.anthropic.claudecode.plist`
```xml
permissions
disableBypassPermissionsMode
```
Source: [examples/mdm/macos/com.anthropic.claudecode.plist](https://github.com/anthropics/claude-code/blob/main/examples/mdm/macos/com.anthropic.claudecode.plist)
#### Configuration Profile (.mobileconfig)
For MDMs that require complete configuration profiles, or for local testing, use the `.mobileconfig` format:
**File:** `macos/com.anthropic.claudecode.mobileconfig`
```xml
PayloadContent
PayloadDisplayName
Claude Code
PayloadIdentifier
com.anthropic.claudecode
PayloadType
com.apple.ManagedClient.preferences
PayloadUUID
UNIQUE-UUID-HERE
PayloadVersion
1
mcx_preference_settings
permissions
disableBypassPermissionsMode
PayloadDisplayName
Claude Code Managed Settings
PayloadIdentifier
com.anthropic.claudecode.profile
PayloadRemovalDisallowed
PayloadScope
System
PayloadType
Configuration
PayloadUUID
UNIQUE-PROFILE-UUID
PayloadVersion
1
```
Source: [examples/mdm/macos/com.anthropic.claudecode.mobileconfig](https://github.com/anthropics/claude-code/blob/main/examples/mdm/macos/com.anthropic.claudecode.mobileconfig)
### Windows Deployment
#### Intune Platform Scripts
For Microsoft Intune deployments on Windows, use the PowerShell script approach. The script writes `managed-settings.json` to the system config directory.
**File:** `windows/Set-ClaudeCodePolicy.ps1`
```powershell
# Set-ClaudeCodePolicy.ps1
# Writes managed-settings.json to the Claude Code config directory
$ErrorActionPreference = "Stop"
# Define the settings to deploy
$settings = @{
permissions = @{
disableBypassPermissionsMode = $true
}
}
# Determine config directory path
$configDir = "$env:APPDATA\Claude"
$settingsFile = Join-Path $configDir "managed-settings.json"
# Ensure directory exists
if (-not (Test-Path $configDir)) {
New-Item -ItemType Directory -Path $configDir -Force | Out-Null
}
# Write settings file
$settings | ConvertTo-Json -Depth 10 | Set-Content -Path $settingsFile -Encoding UTF8
Write-Host "Claude Code policy settings applied successfully."
```
Source: [examples/mdm/windows/Set-ClaudeCodePolicy.ps1](https://github.com/anthropics/claude-code/blob/main/examples/mdm/windows/Set-ClaudeCodePolicy.ps1)
#### Group Policy (ADMX/ADML)
Windows enterprise environments can also leverage Group Policy through ADMX template files.
**Files:**
- `windows/ClaudeCode.admx` - Policy definitions
- `windows/en-US/ClaudeCode.adml` - English localization
The ADMX template defines policy settings that map to managed settings keys, enabling IT administrators to configure Claude Code through standard Group Policy management tools.
Source: [examples/mdm/windows/ClaudeCode.admx](https://github.com/anthropics/claude-code/blob/main/examples/mdm/windows/ClaudeCode.admx)
Source: [examples/mdm/windows/en-US/ClaudeCode.adml](https://github.com/anthropics/claude-code/blob/main/examples/mdm/windows/en-US/ClaudeCode.adml)
## Deployment Workflow
```mermaid
graph LR
A[Test Settings Locally] --> B[Select MDM System]
B --> C{Platform?}
C -->|macOS| D[Choose Format]
C -->|Windows| E[Choose Format]
D --> F[.plist or .mobileconfig]
E --> G[PowerShell or ADMX]
F --> H[Upload to MDM Console]
G --> H
H --> I[Assign to Devices/Users]
I --> J[Settings Applied]
```
## Settings Reference
The templates demonstrate `permissions.disableBypassPermissionsMode`, which prevents users from bypassing permission mode. For the complete list of available managed settings keys, refer to the official settings documentation at [code.claude.com/docs/en/settings#available-settings](https://code.claude.com/docs/en/settings#available-settings).
Source: [examples/mdm/README.md](https://github.com/anthropics/claude-code/blob/main/examples/mdm/README.md)
## Best Practices
### Template Validation
> [!WARNING]
> These examples are **community-maintained templates** which may be unsupported or incorrect. You are responsible for the correctness of your own deployment configuration.
Source: [examples/mdm/README.md](https://github.com/anthropics/claude-code/blob/main/examples/mdm/README.md)
### Recommended Steps
1. **Test locally first** - Validate settings before MDM deployment
2. **Start with minimal configuration** - Use the provided templates as starting points
3. **Adjust for your environment** - Modify paths, UUIDs, and settings as needed
4. **Verify deployment** - Confirm settings are applied correctly to target devices
5. **Document your configuration** - Maintain records of deployed settings versions
### macOS-Specific Considerations
- Ensure the `.mobileconfig` profile is signed if your MDM requires it
- Verify the payload UUIDs are unique within your environment
- Test with a pilot group before organization-wide deployment
### Windows-Specific Considerations
- PowerShell scripts require appropriate execution policy
- For Intune, ensure the script runs under the correct user context
- Group Policy requires proper ADMX template installation in the Central Store
## Extending Configuration
The minimal examples demonstrate the foundation for managed settings. Organizations can extend these templates to include additional settings:
```json
{
"permissions": {
"disableBypassPermissionsMode": true
},
"defaultMode": "auto",
"claudeCodeOptions": {
// Additional settings per documentation
}
}
```
Consult the [settings reference](https://code.claude.com/docs/en/settings#available-settings) and the [`../settings`](../settings) directory for more complete example configurations.
## Community Support
These MDM templates are maintained by the Claude Code community. For issues, questions, or improvements, consider contributing to the repository or engaging with the community through GitHub Discussions.
For issues specific to Claude Code behavior with managed settings, report bugs through the official [GitHub issues](https://github.com/anthropics/claude-code/issues) page.
---
## Managed Settings Reference
### Related Pages
Related topics: [MDM and Enterprise Deployment](#mdm-deployment), [Configuration and Settings](#configuration)
Related Source Files
The following source files were used to generate this page:
- [examples/mdm/README.md](https://github.com/anthropics/claude-code/blob/main/examples/mdm/README.md)
- [examples/settings/README.md](https://github.com/anthropics/claude-code/blob/main/examples/settings/README.md)
- [examples/settings/settings-strict.json](https://github.com/anthropics/claude-code/blob/main/examples/settings/settings-strict.json)
- [examples/settings/settings-lax.json](https://github.com/anthropics/claude-code/blob/main/examples/settings/settings-lax.json)
- [examples/mdm/managed-settings.json](https://github.com/anthropics/claude-code/blob/main/examples/mdm/managed-settings.json)
# Managed Settings Reference
Managed Settings provide enterprise administrators with the ability to deploy and enforce configuration policies across their organization using standard Mobile Device Management (MDM) tools. This reference documents the configuration format, available settings, and deployment patterns for enterprise Claude Code installations.
## Overview
Managed Settings allow organizations to control Claude Code behavior centrally without requiring end-users to modify their local configurations. Settings deployed via MDM are read-only and cannot be overridden by individual users, providing administrators with guaranteed enforcement of organizational policies.
**Key characteristics:**
- Read-only configuration enforced at the system level
- Deployed via standard MDM platforms (Jamf, Kandji, Intune, Group Policy)
- Takes precedence over user-level settings
- Supports both macOS and Windows deployments
- JSON-based configuration format
Source: [examples/mdm/README.md:1-8]()
## Configuration Format
Managed settings use a JSON configuration file that can be deployed through various MDM platforms. The primary format is `managed-settings.json`, which contains key-value pairs defining the enforced configuration.
### Basic Structure
```json
{
"permissions.disableBypassPermissionsMode": true,
"permissions": {
"disableBypassPermissionsMode": true
}
}
```
Source: [examples/mdm/managed-settings.json:1-6]()
### Available Setting Categories
| Category | Description |
|----------|-------------|
| `permissions` | Permission mode controls and restrictions |
| `limits` | Usage limits and rate limiting |
| `network` | Network and proxy configuration |
| `updates` | Auto-update behavior |
| `telemetry` | Data collection preferences |
Source: [examples/settings/README.md]()
## Settings Examples
The repository includes example configurations demonstrating different policy enforcement levels.
### Strict Configuration
A strict configuration enforces maximum security and control:
```json
{
"permissions.disableBypassPermissionsMode": true,
"permissions": {
"disableBypassPermissionsMode": true,
"defaultMode": "review"
}
}
```
This configuration prevents users from bypassing permission mode, ensuring all potentially sensitive operations require explicit approval.
Source: [examples/settings/settings-strict.json]()
### Lax Configuration
A lax configuration allows more user flexibility:
```json
{
"permissions.disableBypassPermissionsMode": false,
"permissions": {
"disableBypassPermissionsMode": false,
"defaultMode": "auto"
}
}
```
This configuration permits users to use auto mode and bypass permission checks as appropriate.
Source: [examples/settings/settings-lax.json]()
## MDM Deployment Templates
The repository provides deployment templates for major MDM platforms.
### Platform Support Matrix
| MDM Platform | File Format | Configuration Method |
|---------------|-------------|---------------------|
| Jamf | `.plist` | Custom Settings payload |
| Kandji (Iru) | `.plist` | Custom Settings payload |
| Intune | PowerShell script | Platform scripts |
| Group Policy | JSON | System config directory |
| Generic | `managed-settings.json` | Any platform |
Source: [examples/mdm/README.md:14-21]()
### Deployment File Locations
| Platform | File Path |
|----------|-----------|
| macOS (plist) | `/Library/Preferences/com.anthropic.claudecode.plist` |
| macOS (mobileconfig) | Full configuration profile |
| Windows | `C:\ProgramData\Claude\managed-settings.json` |
| Generic | System config directory |
Source: [examples/mdm/README.md:14-21]()
## macOS Deployment
### Using Jamf or Kandji
For Jamf and Kandji deployments, use the macOS Preference Domain format.
**Preference domain:** `com.anthropic.claudecode`
**Payload structure:**
```xml
permissions
disableBypassPermissionsMode
```
Source: [examples/mdm/macos/com.anthropic.claudecode.plist]()
### Configuration Profile
For MDMs that require complete configuration profiles, use the `.mobileconfig` format:
```xml
PayloadContent
PayloadType
com.apple.MCX
permissions
disableBypassPermissionsMode
```
Source: [examples/mdm/macos/com.anthropic.claudecode.mobileconfig]()
## Windows Deployment
### Using Intune
For Intune deployments, use the PowerShell script method:
```powershell
# Set-ClaudeCodePolicy.ps1
# Intune Platform Script for Claude Code Managed Settings
$configPath = "$env:ProgramData\Claude\managed-settings.json"
$config = @{
"permissions" = @{
"disableBypassPermissionsMode" = $true
}
}
if (-not (Test-Path (Split-Path $configPath -Parent))) {
New-Item -ItemType Directory -Path (Split-Path $configPath -Parent) -Force
}
$config | ConvertTo-Json -Depth 10 | Set-Content -Path $configPath -Encoding UTF8
```
Source: [examples/mdm/windows/Set-ClaudeCodePolicy.ps1]()
## Settings Precedence
Understanding how managed settings interact with other configuration sources is critical for enterprise deployments.
```mermaid
graph TD
A[Configuration Sources] --> B[Managed Settings
MDM Deployed]
A --> C[User Settings
~/.claude/settings.json]
A --> D[Environment Variables]
A --> E[Project Settings
.claude/settings.json]
B --> F[Effective Configuration]
C --> F
D --> F
E --> F
style B fill:#e1f5fe
style F fill:#c8e6c9
```
**Precedence order (highest to lowest):**
1. Managed Settings (MDM) - Read-only, enforced
2. Project Settings (`.claude/settings.json`)
3. User Settings (`~/.claude/settings.json`)
4. Environment Variables
Source: [examples/settings/README.md]()
## Common Deployment Scenarios
### Restricting Permission Bypass
Organizations requiring strict audit trails should enable `disableBypassPermissionsMode`:
```json
{
"permissions.disableBypassPermissionsMode": true
}
```
This ensures all operations that could modify the system require explicit user approval, regardless of the active permission mode.
### Setting Default Permission Mode
Control the default permission mode for new sessions:
```json
{
"permissions.defaultMode": "review"
}
```
Valid modes include:
- `auto` - Automatically approve safe operations
- `review` - Require approval for potentially risky operations
- `bypass` - Allow all operations (not recommended)
> **Note:** The `auto` permission mode may not be inherited in new sessions as expected. This is a known issue in certain Claude Code versions. See [GitHub Issue #55558](https://github.com/anthropics/claude-code/issues/55558) for details.
## Validation
Before deploying managed settings, validate the JSON format:
```bash
# Validate JSON syntax
cat managed-settings.json | python3 -m json.tool > /dev/null && echo "Valid JSON"
# Check for known settings keys
jq 'keys' managed-settings.json
```
## Related Documentation
- [Settings Reference](https://code.claude.com/docs/en/settings) - Full list of available settings
- [MDM Deployment Guide](https://code.claude.com/docs/en/settings#settings-files) - Official deployment documentation
- [Permissions Configuration](https://code.claude.com/docs/en/permissions) - Permission mode documentation
## Community Considerations
When deploying managed settings in enterprise environments, note the following community-reported behaviors:
- **Permission mode inheritance**: The `auto` permission mode may not be properly inherited by new sessions and cannot be set mid-session. See [Issue #55558](https://github.com/anthropics/claude-code/issues/55558).
- **Weekly limits**: Rate limiting behavior may not perfectly align with documented cycles. See [Issue #52921](https://github.com/anthropics/claude-code/issues/52921).
These issues may affect organizations relying on specific permission or rate-limiting behaviors.
---
---
## Pitfall Log
Project: anthropics/claude-code
Summary: Found 39 structured pitfall item(s), including 16 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.
## 1. Installation risk - Installation risk requires verification
- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_6fd2423d8dd840ad898450c124291027 | https://github.com/anthropics/claude-code/issues/63335
## 2. Installation risk - Installation risk requires verification
- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_abbd745212d743c6b17ef3e919d49b0d | https://github.com/anthropics/claude-code/issues/64109
## 3. Configuration risk - Configuration risk requires verification
- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_cd5af4117b394f29bd45302db852a9e9 | https://github.com/anthropics/claude-code/issues/61298
## 4. Configuration risk - Configuration risk requires verification
- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_e75af4578a6c41e8820a88e1e8b8d617 | https://github.com/anthropics/claude-code/issues/64111
## 5. Configuration risk - Configuration risk requires verification
- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_262f6cbca571401884333f86087e0ddd | https://github.com/anthropics/claude-code/issues/64095
## 6. Configuration risk - Configuration risk requires verification
- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_9c64894658eb475f9ad68245eed8d2f5 | https://github.com/anthropics/claude-code/issues/64094
## 7. Capability evidence risk - Capability evidence risk requires verification
- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a capability evidence risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_e0c0e16324d045f38cb9237f7f4dfff6 | https://github.com/anthropics/claude-code/issues/64115
## 8. Runtime risk - Runtime risk requires verification
- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_a1a5923e7779438ca2f53dafbaf38d00 | https://github.com/anthropics/claude-code/issues/13354
## 9. Security or permission risk - Security or permission risk requires verification
- Severity: high
- Evidence strength: source_linked
- Finding: Developers should check this security_permissions risk before relying on the project: Remote Control (/remote-control) disconnects frequently
- User impact: Developers may expose sensitive permissions or credentials: Remote Control (/remote-control) disconnects frequently
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Remote Control (/remote-control) disconnects frequently. Context: Observed when using windows, macos, linux
- Guardrail: Do not recommend enabling privileged or credential-bearing paths until the source-backed risk is reviewed: https://github.com/anthropics/claude-code/issues/33041
- Evidence: failure_mode_cluster:github_issue | fmev_9c4c7261c368bad5ca3425e0acae9cca | https://github.com/anthropics/claude-code/issues/33041
## 10. Security or permission risk - Security or permission risk requires verification
- Severity: high
- Evidence strength: source_linked
- Finding: Developers should check this security_permissions risk before relying on the project: [BUG] VS Code extension doesn't load Chrome browser tools in chat panel despite docs stating @browser should work (Linux)
- User impact: Developers may expose sensitive permissions or credentials: [BUG] VS Code extension doesn't load Chrome browser tools in chat panel despite docs stating @browser should work (Linux)
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [BUG] VS Code extension doesn't load Chrome browser tools in chat panel despite docs stating @browser should work (Linux). Context: Observed when using node, linux
- Guardrail: Do not recommend enabling privileged or credential-bearing paths until the source-backed risk is reviewed: https://github.com/anthropics/claude-code/issues/50423
- Evidence: failure_mode_cluster:github_issue | fmev_8458acfcfab9d6641fe4696ba1202131 | https://github.com/anthropics/claude-code/issues/50423
## 11. Security or permission risk - Security or permission risk requires verification
- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_1448fd32254e42c7a13bb07c4d4b376e | https://github.com/anthropics/claude-code/issues/63538
## 12. Security or permission risk - Security or permission risk requires verification
- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_88549375cbdc40f5b59125e4fbda8e11 | https://github.com/anthropics/claude-code/issues/33041
## 13. Security or permission risk - Security or permission risk requires verification
- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_87e11d1be1a941db9b9a16f57f0303ef | https://github.com/anthropics/claude-code/issues/64117
## 14. Security or permission risk - Security or permission risk requires verification
- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_79e2cfaaa0d840d0ad2301e7fdee0458 | https://github.com/anthropics/claude-code/issues/64112
## 15. Security or permission risk - Security or permission risk requires verification
- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_ff2e3e5c8d8544f49fb33923239ce9ae | https://github.com/anthropics/claude-code/issues/50423
## 16. Security or permission risk - Security or permission risk requires verification
- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_72142433607342c683efa2dfd91727e1 | https://github.com/anthropics/claude-code/issues/63884
## 17. Installation risk - Installation risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: [BUG] Old sessions do not open, also cannot start new sessions
- User impact: Developers may fail before the first successful local run: [BUG] Old sessions do not open, also cannot start new sessions
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [BUG] Old sessions do not open, also cannot start new sessions. Context: Observed when using windows
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_369baf02a3bc53ab601dee041b939afe | https://github.com/anthropics/claude-code/issues/64109
## 18. Configuration risk - Configuration risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: capability.host_targets | github_repo:937253475 | https://github.com/anthropics/claude-code
## 19. Configuration risk - Configuration risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: Feature Request: Cross-device session sync between desktop and mobile
- User impact: Developers may misconfigure credentials, environment, or host setup: Feature Request: Cross-device session sync between desktop and mobile
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Feature Request: Cross-device session sync between desktop and mobile. Context: Source discussion did not expose a precise runtime context.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_283825ec99bcea39a11f0a6e6c298804 | https://github.com/anthropics/claude-code/issues/61298
## 20. Configuration risk - Configuration risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: Harness silently executes duplicated parallel tool_use blocks: subagent fan-out runs N× the intended count (6 → 24)
- User impact: Developers may misconfigure credentials, environment, or host setup: Harness silently executes duplicated parallel tool_use blocks: subagent fan-out runs N× the intended count (6 → 24)
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Harness silently executes duplicated parallel tool_use blocks: subagent fan-out runs N× the intended count (6 → 24). Context: Observed during installation or first-run setup.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_a856115bae11a139a2c97e4617737eed | https://github.com/anthropics/claude-code/issues/64080
## 21. Configuration risk - Configuration risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: Session titles generated in English despite locale set to ko-KR
- User impact: Developers may misconfigure credentials, environment, or host setup: Session titles generated in English despite locale set to ko-KR
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Session titles generated in English despite locale set to ko-KR. Context: Observed when using windows
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_0388434519fd0a36700613913cb137e0 | https://github.com/anthropics/claude-code/issues/64111
## 22. Configuration risk - Configuration risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: [FEATURE] Multi-account switching in Claude Mobile app without shared email
- User impact: Developers may misconfigure credentials, environment, or host setup: [FEATURE] Multi-account switching in Claude Mobile app without shared email
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [FEATURE] Multi-account switching in Claude Mobile app without shared email. Context: Source discussion did not expose a precise runtime context.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_13a40dd6b5f966f8cf8d81e22aa64f3e | https://github.com/anthropics/claude-code/issues/36151
## 23. Configuration risk - Configuration risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_d98a409f57c74c26a5ba696527e6c1b0 | https://github.com/anthropics/claude-code/issues/64110
## 24. Capability evidence risk - Capability evidence risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: capability.assumptions | github_repo:937253475 | https://github.com/anthropics/claude-code
## 25. Runtime risk - Runtime risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this runtime risk before relying on the project: [FEATURE] Continue when the session limit reached
- User impact: Developers may hit a documented source-backed failure mode: [FEATURE] Continue when the session limit reached
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [FEATURE] Continue when the session limit reached. Context: Source discussion did not expose a precise runtime context.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_0940bbcf61d4a9404571f32848072c7d | https://github.com/anthropics/claude-code/issues/13354
## 26. Maintenance risk - Maintenance risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | github_repo:937253475 | https://github.com/anthropics/claude-code
## 27. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: downstream_validation.risk_items | github_repo:937253475 | https://github.com/anthropics/claude-code
## 28. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: risks.scoring_risks | github_repo:937253475 | https://github.com/anthropics/claude-code
## 29. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_2cc9f1b9f9da461b8ec530dcb1cdf6fa | https://github.com/anthropics/claude-code/issues/64106
## 30. Capability evidence risk - Capability evidence risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this capability risk before relying on the project: Tool calls intermittently emitted as literal text (stray 'court' + raw ) instead of executing — mostly Edit/Read (Opus, CLI)
- User impact: Developers may hit a documented source-backed failure mode: Tool calls intermittently emitted as literal text (stray 'court' + raw ) instead of executing — mostly Edit/Read (Opus, CLI)
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Tool calls intermittently emitted as literal text (stray 'court' + raw ) instead of executing — mostly Edit/Read (Opus, CLI). Context: Observed when using macos
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_2933d9f47cbf4f5f4fb221bac31ceb7d | https://github.com/anthropics/claude-code/issues/64108
## 31. Capability evidence risk - Capability evidence risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this capability risk before relying on the project: Tool-result envelope injected into tool-call input channel during parallel tool batches (corruption + cascade cancellation)
- User impact: Developers may hit a documented source-backed failure mode: Tool-result envelope injected into tool-call input channel during parallel tool batches (corruption + cascade cancellation)
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Tool-result envelope injected into tool-call input channel during parallel tool batches (corruption + cascade cancellation). Context: Observed when using macos
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_c36dedf952efb0b87258d9add70eb890 | https://github.com/anthropics/claude-code/issues/64095
## 32. Capability evidence risk - Capability evidence risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this capability risk before relying on the project: [BUG] API Error: Server is temporarily limiting requests (not your usage limit) · Rate limited
- User impact: Developers may hit a documented source-backed failure mode: [BUG] API Error: Server is temporarily limiting requests (not your usage limit) · Rate limited
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [BUG] API Error: Server is temporarily limiting requests (not your usage limit) · Rate limited. Context: Observed when using windows
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_f149428db4eaf50a33b3d1a869e10e0a | https://github.com/anthropics/claude-code/issues/53915
## 33. Capability evidence risk - Capability evidence risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this capability risk before relying on the project: [BUG] Repeated malformed tool-call markup (stray count before ) within one session — commands silently dropped
- User impact: Developers may hit a documented source-backed failure mode: [BUG] Repeated malformed tool-call markup (stray count before ) within one session — commands silently dropped
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [BUG] Repeated malformed tool-call markup (stray count before ) within one session — commands silently dropped. Context: Observed when using macos
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_90aaa75e00b64d60d6925606deeeac09 | https://github.com/anthropics/claude-code/issues/64112
## 34. Capability evidence risk - Capability evidence risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this capability risk before relying on the project: [Bug] Anthropic API Error: Server Rate Limiting on Recurring Requests
- User impact: Developers may hit a documented source-backed failure mode: [Bug] Anthropic API Error: Server Rate Limiting on Recurring Requests
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [Bug] Anthropic API Error: Server Rate Limiting on Recurring Requests. Context: Observed when using macos
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_74b4a063bf7b78b902bf847b1e15998c | https://github.com/anthropics/claude-code/issues/64101
## 35. Capability evidence risk - Capability evidence risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this conceptual risk before relying on the project: Cancelling a parallel tool-call batch corrupts thinking blocks -> 400 "thinking blocks cannot be modified" permanently wedges the session
- User impact: Developers may hit a documented source-backed failure mode: Cancelling a parallel tool-call batch corrupts thinking blocks -> 400 "thinking blocks cannot be modified" permanently wedges the session
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_c47900c3ee637585906fc588a2c5cca4 | https://github.com/anthropics/claude-code/issues/63192
## 36. Capability evidence risk - Capability evidence risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this conceptual risk before relying on the project: Opus (CLI) took down a node's DNS by deploying a k8s LoadBalancer on :53, after dismissing on-screen evidence the port was the host resolver
- User impact: Developers may hit a documented source-backed failure mode: Opus (CLI) took down a node's DNS by deploying a k8s LoadBalancer on :53, after dismissing on-screen evidence the port was the host resolver
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_412c2e9812e680366a198d368bc09d58 | https://github.com/anthropics/claude-code/issues/64110
## 37. Capability evidence risk - Capability evidence risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this conceptual risk before relying on the project: Tool calls leak as raw text ('call' + args) instead of executing — frequent on Opus 4.8
- User impact: Developers may hit a documented source-backed failure mode: Tool calls leak as raw text ('call' + args) instead of executing — frequent on Opus 4.8
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_fae94d46beb702ecb9e71f49ebeb7268 | https://github.com/anthropics/claude-code/issues/64106
## 38. Maintenance risk - Maintenance risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | github_repo:937253475 | https://github.com/anthropics/claude-code
## 39. Maintenance risk - Maintenance risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | github_repo:937253475 | https://github.com/anthropics/claude-code