Command Line Flags
| Flag / Command | Description | Example | | :--------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------- | | `-d, --debug` | Enable debug mode (shows detailed debug output). | `claude -d -p "query"` | | `--include-partial-messages` | partial message streaming support via CLI flag | | `--mcp-debug` | [DEPRECATED] MCP debug mode (shows MCP server errors). Use `--debug` instead. | `claude --mcp-debug` | | `--verbose` | Override verbose mode setting from config (shows expanded logging / turn-by-turn output). | `claude --verbose` | | `-p, --print` | Print response and exit (useful for piping output). | `claude -p "query"` | | `--output-formatCLI Quick Reference & Configuration Examples
```md ## Claude Cheat Sheet # Basics / interactive claude # Start interactive REPL claude "explain this project" # Start REPL seeded with a prompt claude -p "summarize README.md" # Non-interactive print mode (SDK-backed) cat logs.txt | claude -p "explain" # Pipe input to Claude and exit claude -c # Continue most recent conversation (alias for --continue) claude -r "Interface & Input
Keyboard Shortcuts
| Shortcut | Description | Context | | :--------------------------- | :--------------------------------- | :--------------------------------------- | | `Ctrl+C` | Cancel current input or generation | Standard interrupt | | `Ctrl+D` | Exit Claude Code session | EOF signal | | `Ctrl+G` | Open in default text editor | Edit your prompt or custom response | | `Ctrl+L` | Clear terminal screen | Keeps conversation history | | `Ctrl+O` | Toggle verbose output | Shows detailed tool usage and execution | | `Ctrl+R` | Reverse search command history | Search through previous commands | | `Ctrl+V` or `Cmd+V` (iTerm2) | Paste image from clipboard | Pastes an image or path to an image file | | `Ctrl+B` | Background running tasks | Backgrounds bash commands and agents | | `Ctrl+F` (press twice) | Kill all background agents | Two-press confirmation to stop agents | | `Up/Down arrows` | Navigate command history | Recall previous inputs | | `Left/Right arrows` | Cycle through dialog tabs | Navigate between tabs in dialogs | | `Esc` + `Esc` | Rewind the code/conversation | Restore to a previous point | | `Shift+Tab` or `Alt+M` | Toggle permission modes | Switch between Auto-Accept, Plan, Normal | | `Option+P` (macOS) / `Alt+P` | Switch model | Switch models without clearing prompt | | `Option+T` (macOS) / `Alt+T` | Toggle extended thinking | Enable/disable extended thinking mode |Text Editing
| Shortcut | Description | Context | | :--------------------- | :--------------------------- | :------------------------------------ | | `Ctrl+K` | Delete to end of line | Stores deleted text for pasting | | `Ctrl+U` | Delete entire line | Stores deleted text for pasting | | `Ctrl+Y` | Paste deleted text | Paste text deleted with Ctrl+K/U | | `Alt+Y` (after Ctrl+Y) | Cycle paste history | Cycle through previously deleted text | | `Alt+B` | Move cursor back one word | Requires Option as Meta on macOS | | `Alt+F` | Move cursor forward one word | Requires Option as Meta on macOS |Multiline Input
| Method | Shortcut | Context | | :--------------- | :------------- | :-------------------------------- | | Quick escape | `\` + `Enter` | Works in all terminals | | macOS default | `Option+Enter` | Default on macOS | | Terminal setup | `Shift+Enter` | After `/terminal-setup` | | Control sequence | `Ctrl+J` | Line feed character for multiline | | Paste mode | Paste directly | For code blocks, logs |Quick Commands
| Shortcut | Description | Notes | | :----------- | :---------------- | :------------------------------------ | | `/` at start | Command or skill | See built-in commands and skills | | `!` at start | Bash mode | Run commands directly, add to context | | `@` | File path mention | Trigger file path autocomplete | > [!Tip] > **PDF Page Ranges:** Use the `pages` parameter with the Read tool for PDFs (e.g., `pages: "1-5"`). Large PDFs (>10 pages) return a lightweight reference when @-mentioned instead of being inlined.Vim Mode
> [!Note] > Enable vim-style editing with `/vim` command or configure permanently via `/config`.Vim Mode Switching
| Command | Action | From mode | | :------ | :-------------------------- | :-------- | | `Esc` | Enter NORMAL mode | INSERT | | `i` | Insert before cursor | NORMAL | | `I` | Insert at beginning of line | NORMAL | | `a` | Insert after cursor | NORMAL | | `A` | Insert at end of line | NORMAL | | `o` | Open line below | NORMAL | | `O` | Open line above | NORMAL |Vim Navigation
| Command | Action | | :-------------- | :------------------------ | | `h`/`j`/`k`/`l` | Move left/down/up/right | | `w` | Next word | | `e` | End of word | | `b` | Previous word | | `0` | Beginning of line | | `$` | End of line | | `^` | First non-blank character | | `gg` | Beginning of input | | `G` | End of input |Vim Editing
| Command | Action | | :------------- | :---------------------- | | `x` | Delete character | | `dd` | Delete line | | `D` | Delete to end of line | | `dw`/`de`/`db` | Delete word/to end/back | | `cc` | Change line | | `C` | Change to end of line | | `cw`/`ce`/`cb` | Change word/to end/back | | `.` | Repeat last change | > [!Tip] > Configure your preferred line break behavior in terminal settings. Run `/terminal-setup` to install Shift+Enter binding for iTerm2, VS Code, Kitty, Alacritty, Zed, Warp, and WezTerm.Command History
> Claude Code maintains command history for the current session: ``` * History is stored per working directory * Cleared with `/clear` command * Use Up/Down arrows to navigate (see keyboard shortcuts above) * **Ctrl+R**: Reverse search through history (if supported by terminal) * **Note**: History expansion (`!`) is disabled by default ``` ---Advanced Features
Thinking Keywords
> [!Note] > **Gives Claude extra pre-answer planning time by adding ONE of these keywords to your prompt.** > **Order (lowest → highest) token consumption** > >| > > > **think -------------> Lowest** > > > **think hard** > > > **think harder** > > > **ultrathink --------> Highest** > > |
This makes Claude spend more time:
1. **Planning the solution** 2. #### breaking down steps 3. #### weighing alternatives/trade-offs 4. #### checking constraints & edge cases > > #### Higher levels usually increase **latency** and **token usage** pick the smallest that works.Examples
```md # Small boost claude -p "Think. Outline a plan to refactor the auth module." # Medium boost claude -p "Think harder. Draft a migration plan from REST to gRPC." # Max boost claude -p "Ultrathink. Propose a step-by-step strategy to fix flaky payment tests and add guardrails." ```Fast Mode
> [!Note] > **Fast Mode provides accelerated response times for Opus 4.6, optimized for rapid iteration and quick tasks.** **How to enable Fast Mode:** ```bash # Enable fast mode in the REPL (requires extra-usage first) /extra-usage /fast # Or toggle during conversation # The status bar will show when Fast Mode is active ``` **Key features:** - **Faster responses** - Reduced latency for quick tasks - **Available for Opus 4.6** - New in version 2.1.36 - **Requires extra-usage** - Must enable `/extra-usage` first **When to use Fast Mode:** - Quick code reviews and edits - Rapid prototyping - Simple questions and commands - Iterative debugging > Fast Mode trades some depth for speed. Use normal mode for complex analysis and planning tasks.Plan Mode
> [!Note] > **Plan Mode instructs Claude to analyze the codebase with read-only operations, perfect for exploring codebases, planning complex changes, or reviewing code safely.** **When to use Plan Mode:** - **Multi-step implementation**: When your feature requires making edits to many files - **Code exploration**: When you want to research the codebase thoroughly before changing anything - **Interactive development**: When you want to iterate on the direction with Claude **How to enable Plan Mode:** ```bash # Start a new session in Plan Mode claude --permission-mode plan # Or toggle during session with Shift+Tab # (cycles through: Normal → Auto-Accept → Plan Mode) # Enter plan mode from the prompt /plan # Run headless queries in Plan Mode claude --permission-mode plan -p "Analyze the authentication system and suggest improvements" ``` **Configure Plan Mode as default:** ```json // .claude/settings.json { "permissions": { "defaultMode": "plan" } } ``` ---Background Tasks
> [!Note] > **Claude Code supports running bash commands in the background, allowing you to continue working while long-running processes execute.** **How to use background tasks:** | Method | Description | | :------------ | :------------------------------------------------------------------------- | | Prompt Claude | Ask Claude to "run this in the background" | | `Ctrl+B` | Move a running Bash tool invocation to background (tmux users press twice) | **Key features:** - Output is buffered and Claude can retrieve it using the TaskOutput tool - Background tasks have unique IDs for tracking and output retrieval - Background tasks are automatically cleaned up when Claude Code exits - Use `/tasks` to list and manage background tasks **Common backgrounded commands:** - Build tools (webpack, vite, make) - Package managers (npm, yarn, pnpm) - Test runners (jest, pytest) - Development servers - Long-running processes (docker, terraform) **Bash mode with `!` prefix:** ```bash # Run bash commands directly without Claude interpretation ! npm test ! git status ! ls -la ``` **Disable background tasks:** ```bash export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 ``` ---Remote Sessions
> [!Note] > **For subscribers: Use `--remote` to start tasks on claude.ai and `--teleport` to resume them locally.** **Start a remote session:** ```bash # Create a new web session on claude.ai with task description claude --remote "Fix the login bug" ``` **Resume a remote session:** ```bash # Resume a web session in your local terminal claude --teleport # Or use the slash command /teleport ``` ---Claude in Chrome
Claude Code can control Google Chrome for browser-based tasks like testing, web scraping, and UI verification. **Setup:** ```bash claude --chrome # Launch with Chrome integration ``` **Capabilities:** - Navigate to URLs, click elements, fill forms - Take screenshots and analyze page content - Execute JavaScript in the browser context - Interact with web applications for testing > [!NOTE] > Requires Google Chrome installed. Claude uses the Chrome DevTools Protocol for browser control. ---Sandbox Mode
Sandbox mode restricts the BashTool to run commands in an isolated environment, preventing modifications to your actual filesystem. ```bash /sandbox # Toggle sandbox mode on/off ``` **When sandboxed:** - File system writes are contained - Network access may be restricted - Useful for testing destructive commands safely Available on Linux and macOS. Use `claude --sandbox` to start in sandbox mode. ---LSP Tool (Language Server Protocol)
Claude Code integrates with language servers to provide IDE-level code intelligence: - **Go to Definition** — Jump to where a symbol is defined - **Find References** — Find all usages of a symbol across the codebase - **Hover Information** — Get type information and documentation The LSP tool activates automatically when a compatible language server is available for the current project. This enables Claude to navigate codebases more precisely than text search alone. > Tool results exceeding 50,000 characters are automatically persisted to disk to manage context efficiently. ---Sub Agents
> Sub‑Agents are purpose‑built helpers with their **own prompts, tools, and isolated context windows**. Treat this like a "mixture‑of‑experts" you **compose** per repo.Built-in Subagents
Claude Code includes built-in subagents that Claude automatically uses when appropriate: | Subagent | Model | Tools | Purpose | | :------------------ | :----------- | :-------- | :------------------------------------------------ | | **Explore** | Haiku (fast) | Read-only | File discovery, code search, codebase exploration | | **Plan** | Configurable | Read-only | Planning complex changes without making edits | | **General-purpose** | Default | Inherited | General task delegation | > Claude delegates to **Explore** when it needs to search or understand a codebase without making changes, keeping exploration results out of your main conversation context. **When to use subagents:** > - You need high signal responses (plans, reviews, diffs) without side quests. > - You want version‑controlled prompts and tool policies alongside the codebase. > - You work in PR‑driven teams and want scoped edits by role. > - The task produces verbose output you don't need in your main context.Each Sub‑Agent Has Its Own Context
**Design rules for your lineup** > - Define **one clear responsibility** per agent. > - Keep the **minimum** tool set needed for that role. > - Prefer **read‑only** agents for analysis/review tasks. > - Give edit powers to as few agents as possible.Configure Agents
> Keep agents **in the project** so they're versioned with the repo and evolve via PRs.Quick start
> Update CLI and open the agents panel ```bash claude update /agents ```Subagent Scopes
| Location | Scope | Priority | | :--------------------------- | :---------------------- | :---------- | | `--agents` CLI flag | Current session only | 1 (highest) | | `.claude/agents/` | Current project | 2 | | `~/.claude/agents/` | All your projects | 3 | | Plugin's `agents/` directory | Where plugin is enabled | 4 (lowest) |Define Agents via CLI
```bash # Define custom subagents dynamically via JSON claude --agents '{ "code-reviewer": { "description": "Expert code reviewer. Use proactively after code changes.", "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.", "tools": ["Read", "Grep", "Glob", "Bash"], "model": "sonnet" }, "debugger": { "description": "Debugging specialist for errors and test failures.", "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes." }, "background-impl": { "description": "Implements features in an isolated worktree in the background.", "prompt": "Implement the requested feature. Commit when done.", "isolation": "worktree", "background": true } }' ```Create your core agents
> - **planner** (read‑only): turns features/issues into small, testable tasks; outputs a task list or plan.md. > - **codegen** (edit‑capable): implements tasks; limited to `src/` + `tests/`. > - **tester** (read‑only or patch‑only): writes _one_ failing test or a minimal repro. > - **reviewer** (read‑only): leaves structured review comments; never edits. > - **docs** (edit‑capable): updates `README.md`/`docs/` only. **\*Policy** tip: Prefer **patch output** for edit‑capable agents so changes land through your normal Git workflow.\*Example prompts
> Keep prompts short, testable, and repo‑specific. Check them into `agents/`:Expected output
> Your tester agent should produce a small diff or patch plus a short rationale:Subagent Frontmatter Fields
Subagent files use YAML frontmatter for configuration: ```markdown --- name: code-reviewer description: Reviews code for quality and best practices tools: Read, Glob, Grep disallowedTools: Write, Edit model: sonnet permissionMode: default skills: - api-conventions --- You are a code reviewer. Analyze the code and provide feedback. ``` | Field | Required | Description | | :---------------- | :------- | :------------------------------------------------------------------ | | `name` | Yes | Unique identifier (lowercase, hyphens) | | `description` | Yes | When Claude should delegate to this subagent | | `tools` | No | Tools the subagent can use (inherits all if omitted) | | `disallowedTools` | No | Tools to deny, removed from inherited or specified list | | `model` | No | Model: `sonnet`, `opus`, `haiku`, or `inherit` (default: sonnet) | | `permissionMode` | No | `default`, `acceptEdits`, `dontAsk`, `bypassPermissions`, or `plan` | | `skills` | No | Skills to preload into the subagent's context | | `hooks` | No | Lifecycle hooks scoped to this subagent | | `memory` | No | Persistent memory scope: `user`, `project`, or `local` | | `isolation` | No | Set to `worktree` to run the agent in an isolated git worktree | | `background` | No | Set to `true` to run the agent as a background task |Why This Shift Matters
**Operational benefits** > - **Less context switching:** you stay in one mental mode; agents do the rest. > - **Cleaner PRs:** narrow prompts + limited tools → smaller, reviewable diffs. > - **Fewer regressions:** tester/reviewer agents catch gaps before merge. > - **Repeatability:** prompts + policies live in the repo and travel with branches. **Security & governance** > - Limit write access by path (e.g., `src/`, `tests/`, `docs/`). > - Favor read‑only analysis for high‑risk areas. > - Log/commit assistant outputs as patches for auditability.A Mindset Shift
**Do** > - Treat agents as teammates with job descriptions. > - Start read‑only; grant write access _last_. > - Keep prompts in version control and iterate via PR. **Don't** > - Ask one agent to plan, code, and test in a single turn. > - Give blanket write permissions. > - Accept multi‑file diffs when you asked for one test. ---Agent Teams (Research Preview)
> [!Note] > **Agent Teams is an experimental feature enabling multiple Claude instances to work in parallel on a shared codebase autonomously.** **Enable Agent Teams:** ```bash export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 ``` **Key Concepts:** - Multiple Claude instances run in parallel on the same codebase - Each agent can specialize in different tasks (debugging, documentation, testing, etc.) - Agents communicate through git-based synchronization - Enables autonomous, long-running development workflows **Case Study: C Compiler Built by Agent Teams** Anthropic's research team demonstrated agent teams by tasking 16 parallel Claude instances to build a C compiler from scratch. Key results: | Metric | Value | | :------------------ | :------------------------------------- | | **Claude Sessions** | ~2,000 | | **API Cost** | ~$20,000 | | **Lines of Code** | 100,000 | | **Capability** | Compiled Linux 6.9 on x86, ARM, RISC-V | | **Test Pass Rate** | 99% on GCC torture test suite | **Lessons for Agent Teams:** 1. **Write high-quality tests** - The task verifier must be nearly perfect 2. **Design for parallelism** - Agents should be able to work independently without blocking each other 3. **Specialize agents** - Dedicate agents to specific roles (code quality, documentation, performance) 4. **Maintain context files** - Keep READMEs and progress files updated for agent orientation > Read the full case study: [Building a C Compiler with Parallel Claudes](https://www.anthropic.com/engineering/building-c-compiler) ---Skills (Custom Slash Commands)
> [!Note] > **Skills extend what Claude can do. Create a `SKILL.md` file with instructions, and Claude adds it to its toolkit. Claude uses skills when relevant, or you can invoke one directly with `/skill-name`.**Skill Locations
| Location | Scope | Description | | :--------------------------------------- | :------- | :-------------------------------------------- | | `~/.claude/skills/Create a Skill
```bash # Create skill directory mkdir -p ~/.claude/skills/explain-code ``` Create `~/.claude/skills/explain-code/SKILL.md`: ```markdown --- name: explain-code description: Explains code with visual diagrams and analogies. Use when explaining how code works. --- When explaining code, always include: 1. **Start with an analogy**: Compare the code to something from everyday life 2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships 3. **Walk through the code**: Explain step-by-step what happens 4. **Highlight a gotcha**: What's a common mistake or misconception? ``` **Use the skill:** ```bash # Let Claude invoke automatically How does this code work? # Or invoke directly /explain-code src/auth/login.ts ```Skill Frontmatter Fields
| Field | Required | Description | | :------------------------- | :---------- | :---------------------------------------------------------- | | `name` | No | Display name for the skill (uses directory name if omitted) | | `description` | Recommended | What the skill does and when to use it | | `argument-hint` | No | Hint shown during autocomplete (e.g., `[filename]`) | | `disable-model-invocation` | No | Set `true` to prevent Claude from auto-invoking | | `user-invocable` | No | Set `false` to hide from / menu | | `allowed-tools` | No | Tools Claude can use without asking permission | | `model` | No | Model to use when this skill is active | | `context` | No | Set to `fork` to run in a forked subagent context | | `agent` | No | Which subagent to use when `context: fork` is set | | `hooks` | No | Hooks scoped to this skill's lifecycle |Pass Arguments to Skills
Use `$ARGUMENTS` placeholder to receive arguments: ```markdown --- name: fix-issue description: Fix a GitHub issue disable-model-invocation: true --- Fix GitHub issue $ARGUMENTS following our coding standards. 1. Read the issue description 2. Implement the fix 3. Write tests 4. Create a commit ``` **Usage:** `/fix-issue 123`Inject Dynamic Context
Use `` !`command` `` syntax to run shell commands before the skill content is sent to Claude: ```markdown --- name: pr-summary description: Summarize changes in a pull request context: fork agent: Explore --- ## Pull request context - PR diff: !`gh pr diff` - PR comments: !`gh pr view --comments` - Changed files: !`gh pr diff --name-only` ## Your task Summarize this pull request... ```Run Skills in a Subagent
Add `context: fork` to run a skill in isolation: ```markdown --- name: deep-research description: Research a topic thoroughly context: fork agent: Explore --- Research $ARGUMENTS thoroughly: 1. Find relevant files using Glob and Grep 2. Read and analyze the code 3. Summarize findings with specific file references ``` > The `agent` field can be `Explore`, `Plan`, `general-purpose`, or any custom subagent from `.claude/agents/`. ---Plugin System
> [!Note] > **Plugins extend Claude Code with custom commands, skills, agents, hooks, and MCP servers. Plugins can be loaded from local directories, Git repos, or the npm registry.** **Key commands:** ```bash # Install a plugin from a Git repository /plugins install https://github.com/org/claude-plugin-example # Install from npm registry /plugins install @org/claude-code-plugin # List installed plugins /plugins list # Enable / disable a plugin /plugins enableWorktree Isolation (v2.1.49+)
> [!Note] > **The `--worktree` (`-w`) flag starts Claude in an isolated git worktree, allowing it to make changes in a separate branch without affecting your working directory.** **Usage:** ```bash # Start Claude in an isolated worktree claude -w "implement the new feature" # Claude will: # 1. Create a temporary git worktree from your current branch # 2. Run in that isolated worktree # 3. Commit changes and optionally create a PR # 4. Clean up the worktree when done ``` **Agent-level worktree isolation:** ```markdown --- name: background-coder description: Implements features in isolation isolation: worktree background: true --- Implement the requested feature in this isolated worktree. ``` > Worktree isolation is especially powerful combined with `background: true` for agents, enabling parallel development workflows where multiple agents work on separate features simultaneously. ---Native Installer (v2.1.15+)
> [!Note] > **Claude Code now offers a native binary installer as an alternative to the npm global install. The native installer provides faster startup, auto-updates, and doesn't require Node.js on your PATH.** ```bash # Start the native installer (interactive) claude install # Migrate from npm global install to native installer claude migrate-installer # Windows ARM64 is supported natively since v2.1.41 ``` > The npm installation method (`npm install -g @anthropic-ai/claude-code`) continues to work. A deprecation notice for npm-based installs was introduced in v2.1.15, but both methods are supported. ---Authentication CLI (v2.1.41+)
> [!Note] > **Manage authentication directly from the CLI without entering the REPL.** ```bash # Log in to your Anthropic account claude auth login # Check current authentication status claude auth status # Log out claude auth logout ``` ---Agent Management CLI (v2.1.50+)
> [!Note] > **List and inspect all configured agents from the command line.** ```bash # List all agents (project, user, plugin, CLI-defined) claude agents ``` ---Remote Control (v2.1.51+)
> [!Note] > **The `claude remote-control` subcommand allows external tools and build systems to drive Claude Code programmatically.** ```bash # Start Claude in remote-control mode claude remote-control ``` This is useful for IDE extensions, CI/CD pipelines, or custom orchestration tools that want to interact with Claude Code via its SDK interface. ---Managed Settings (v2.1.51+)
> [!Note] > **Enterprise administrators can push managed settings via macOS plist or Windows Registry, providing organization-wide configuration control.** **macOS (plist):** Settings can be deployed via MDM profiles to `/Library/Managed Preferences/com.anthropic.claude-code.plist`. **Windows (Registry):** Settings can be deployed via Group Policy to `HKLM\SOFTWARE\Policies\Anthropic\ClaudeCode`. > Managed settings take precedence over user/project settings and cannot be overridden by individual users. ---Model Updates
### Claude Sonnet 4.6 (February 17, 2026) > [!Note] > **Claude Sonnet 4.6 delivers frontier-level performance at Sonnet pricing ($3/$15 per million tokens) with a 1M-token context window.** **Key highlights:** - **Approaches Opus-level performance** on coding, reasoning, and agent planning tasks - **1M token context window** (previously only available on Max plan for Sonnet 4.5) - **Improved coding benchmarks**: significant gains on SWE-bench, agentic coding, and multi-file refactoring - **Better long-context reasoning**: improved accuracy across needle-in-a-haystack and long-document tasks - **Enhanced computer use**: more reliable browser automation and GUI interaction - **Same pricing as Sonnet 4.5**: $3 input / $15 output per million tokens **Use in Claude Code:** ```bash # Set as default model claude --model sonnet # Or pin the specific version claude --model claude-sonnet-4-6-20260217 # Configure in settings claude config set model "claude-sonnet-4-6-20260217" ``` > Sonnet 4.5 with 1M context has been removed from the Max plan in favor of Sonnet 4.6. Claude Opus 4.6 (released in v2.1.32) remains available for the most demanding tasks. ---Claude Code Insights
> [!Note] > **The `/insights` command generates an interactive HTML report analyzing your coding habits from the past 30 days.** **Run Insights:** ```bash # In Claude Code terminal /insights # Open the generated report start ~/.claude/usage-data/report.html # Windows open ~/.claude/usage-data/report.html # Mac xdg-open ~/.claude/usage-data/report.html # Linux ``` **How It Works:** 1. **Session Collection** - Pulls session logs from `~/.claude/projects/`, filters agent sub-sessions and short sessions 2. **Metadata Extraction** - Extracts duration, token usage, tools used, languages detected, git activity 3. **Facet Extraction** - Uses Haiku model to analyze transcripts and identify goals, satisfaction signals, friction points 4. **Report Generation** - Creates interactive HTML report with personalized suggestions **Report Sections:** | Section | Description | | :-------------------- | :---------------------------------------------------------- | | **What's Working** | Your strengths and successful patterns | | **What's Hindering** | Where Claude struggled or where you caused friction | | **Friction Analysis** | Breakdown of problem areas with specific examples | | **Stats Dashboard** | Tool usage, language breakdown, coding time distribution | | **Quick Wins** | Copy-paste suggestions for CLAUDE.md improvements | | **Features to Try** | Personalized recommendations (skills, hooks, headless mode) | > Everything runs locally using the Anthropic API. Session data stays on your machine. ---MCP Integration
Understanding MCP (Model Context Protocol)
#### What is MCP? > MCP extends Claude's capabilities by connecting to external services, databases, APIs, and tools (filesystem, Puppeteer, GitHub, Context7 etc...) ###### **MCP Architecture:** ``` Claude Code ←→ MCP Protocol ←→ MCP Servers ←→ External Services ```claude.ai MCP Connectors
Claude Code can use MCP servers configured in your claude.ai account, bringing cloud-hosted tools to your CLI workflow. ```bash # Enabled by default — to opt out: export ENABLE_CLAUDEAI_MCP_SERVERS=false ``` This allows you to access the same MCP tool integrations available in claude.ai directly from the command line, without local MCP server configuration.MCP Setup & Configuration
###### Basic MCP Commands ```bash claude mcp # Interactive MCP configuration claude mcp list # List configured servers claude mcp add|
### 1. Command Line Addition
> **Claude Code provides simple command line tools to add MCP servers:**
```bash
# Basic syntax
claude mcp add |
| ### 2. Direct Configuration File Editing > Many developers find CLI wizards too cumbersome, especially when you have to restart if you make a mistake. > > Direct configuration file editing is more efficient: **1. Find configuration file location:** - macOS/Linux: `~/.claude.json` - Windows: `%USERPROFILE%\.claude.json` **2. Edit configuration file:** ```json { "mcpServers": { "filesystem": { "type": "stdio", "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Documents" ], "env": {} }, "github": { "type": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_TOKEN": "your-github-token" } } } } ``` **3. Restart Claude Code to take effect** |
| ### 3. Project-level Configuration (Recommended for team collaboration) > If you want team members to all use the same MCP configuration: ```bash # Add project-level MCP server claude mcp add shared-tools -s project -- npx -y @your-team/mcp-tools ``` **This will create a `.mcp.json` file in the project root directory:** ```json { "mcpServers": { "shared-tools": { "command": "npx", "args": ["-y", "@your-team/mcp-tools"], "env": {} } } } ``` |
Popular MCP Servers
#### Development Tools ```bash # npm install -g git-mcp-server # claude mcp add git "git-mcp-server" # claude mcp add github "github-mcp-server --token $GITHUB_TOKEN" ``` #### Database Integration ```bash npm install -g postgres-mcp-server npm install -g mysql-mcp-server npm install -g sqlite-mcp-server # Setup examples may look like this: # export POSTGRES_URL="postgresql://user:password@localhost:5432/mydb" # claude mcp add postgres "postgres-mcp-server --url $POSTGRES_URL" ``` #### MCP Tool Permissions ```bash # Allow specific MCP tools claude --allowedTools "mcp__git__commit,mcp__git__push" # Allow all tools from specific server claude --allowedTools "mcp__postgres__*" # Combined with built-in tools claude --allowedTools "Edit,View,mcp__git__*" ```Hooks System
> This page provides reference documentation for implementing hooks in Claude Code. > [!TIP] > For a quickstart guide with examples, see [Get started with Claude Code hooks](/en/docs/claude-code/hooks-guide).Configuration
Claude Code hooks are configured in your [settings files](/en/docs/claude-code/settings): - `~/.claude/settings.json` - User settings - `.claude/settings.json` - Project settings - `.claude/settings.local.json` - Local project settings (not committed) - Enterprise managed policy settings #### Structure Hooks are organized by matchers, where each matcher can have multiple hooks: ```json { "hooks": { "EventName": [ { "matcher": "ToolPattern", "hooks": [ { "type": "command", "command": "your-command-here" } ] } ] } } ``` #### HTTP Hooks (v2.1.63+) In addition to shell commands, hooks can POST JSON to a URL and receive a JSON response: ```json { "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "http", "url": "https://hooks.example.com/validate", "timeout": 10 } ] } ] } } ``` HTTP hooks send the same JSON payload that `command` hooks receive via stdin, as a POST body. The response JSON follows the same output schema. This is useful for centralized policy enforcement or remote hook execution without local scripts. - **matcher**: Pattern to match tool names, case-sensitive (only applicable for `PreToolUse` and `PostToolUse`) - Simple strings match exactly: `Write` matches only the Write tool - Supports regex: `Edit|Write` or `Notebook.*` - Use `*` to match all tools. You can also use empty string (`""`) or leave `matcher` blank. - **hooks**: Array of commands to execute when the pattern matches - `type`: `"command"` (shell command) or `"http"` (POST JSON to a URL, v2.1.63+) - `command`: The bash command to execute (can use `$CLAUDE_PROJECT_DIR` environment variable) - `timeout`: (Optional) How long a command should run, in seconds, before canceling that specific command. For events like `UserPromptSubmit`, `Notification`, `Stop`, and `SubagentStop` that don't use matchers, you can omit the matcher field: ```json { "hooks": { "UserPromptSubmit": [ { "hooks": [ { "type": "command", "command": "/path/to/prompt-validator.py" } ] } ] } } ``` #### Project-Specific Hook Scripts You can use the environment variable `CLAUDE_PROJECT_DIR` (only available when Claude Code spawns the hook command) to reference scripts stored in your project, ensuring they work regardless of Claude's current directory: ```json { "hooks": { "PostToolUse": [ { "matcher": "Write|Edit", "hooks": [ { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/check-style.sh" } ] } ] } } ```Hook Events
#### PreToolUse Runs after Claude creates tool parameters and before processing the tool call. **Common matchers:** - `Task` - Subagent tasks (see [subagents documentation](/en/docs/claude-code/sub-agents)) - `Bash` - Shell commands - `Glob` - File pattern matching - `Grep` - Content search - `Read` - File reading - `Edit`, `MultiEdit` - File editing - `Write` - File writing - `WebFetch`, `WebSearch` - Web operations #### PostToolUse Runs immediately after a tool completes successfully. Recognizes the same matcher values as PreToolUse. #### Notification Runs when Claude Code sends notifications. Notifications are sent when: 1. Claude needs your permission to use a tool. Example: "Claude needs your permission to use Bash" 2. The prompt input has been idle for at least 60 seconds. "Claude is waiting for your input" #### UserPromptSubmit Runs when the user submits a prompt, before Claude processes it. This allows you to add additional context based on the prompt/conversation, validate prompts, or block certain types of prompts. #### Stop Runs when the main Claude Code agent has finished responding. Does not run if the stoppage occurred due to a user interrupt. #### SubagentStop Runs when a Claude Code subagent (Task tool call) has finished responding. #### TeammateIdle Triggered when an agent teammate becomes idle (multi-agent workflows). #### TaskCompleted Triggered when a background task completes (multi-agent workflows). #### ConfigChange Fires when Claude Code configuration files change (e.g., settings, CLAUDE.md, `.mcp.json`). Useful for reloading external state or triggering side effects on config edits. #### WorktreeCreate Fires when Claude creates a new git worktree (via `--worktree` / `-w` flag or `isolation: worktree` in agent definitions). Useful for setting up worktree-specific resources. #### WorktreeRemove Fires when a git worktree is cleaned up after use. Useful for tearing down worktree-specific resources. #### Setup Triggered via `--init`, `--init-only`, or `--maintenance` CLI flags. Useful for one-time project setup tasks, plugin installation, or maintenance scripts. #### PermissionRequest Fires when Claude shows a permission prompt to the user. Useful for logging or automating permission decisions. #### PreCompact Runs before Claude Code is about to run a compact operation. **Matchers:** - `manual` - Invoked from `/compact` - `auto` - Invoked from auto-compact (due to full context window) #### SessionStart Runs when Claude Code starts a new session or resumes an existing session (which currently does start a new session under the hood). Useful for loading in development context like existing issues or recent changes to your codebase. **Matchers:** - `startup` - Invoked from startup - `resume` - Invoked from `--resume`, `--continue`, or `/resume` - `clear` - Invoked from `/clear`Hook Input
Hooks receive JSON data via stdin containing session information and event-specific data: ```typescript { // Common fields session_id: string transcript_path: string // Path to conversation JSON cwd: string // The current working directory when the hook is invoked // Event-specific fields hook_event_name: string ... } ``` #### PreToolUse Input The exact schema for `tool_input` depends on the tool. ```json { "session_id": "abc123", "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", "cwd": "/Users/...", "hook_event_name": "PreToolUse", "tool_name": "Write", "tool_input": { "file_path": "/path/to/file.txt", "content": "file content" } } ``` #### PostToolUse Input The exact schema for `tool_input` and `tool_response` depends on the tool. ```json { "session_id": "abc123", "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", "cwd": "/Users/...", "hook_event_name": "PostToolUse", "tool_name": "Write", "tool_input": { "file_path": "/path/to/file.txt", "content": "file content" }, "tool_response": { "filePath": "/path/to/file.txt", "success": true } } ``` #### Notification Input ```json { "session_id": "abc123", "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", "cwd": "/Users/...", "hook_event_name": "Notification", "message": "Task completed successfully" } ``` #### UserPromptSubmit Input ```json { "session_id": "abc123", "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", "cwd": "/Users/...", "hook_event_name": "UserPromptSubmit", "prompt": "Write a function to calculate the factorial of a number" } ``` #### Stop and SubagentStop Input `stop_hook_active` is true when Claude Code is already continuing as a result of a stop hook. Check this value or process the transcript to prevent Claude Code from running indefinitely. ```json { "session_id": "abc123", "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", "hook_event_name": "Stop", "stop_hook_active": true, "last_assistant_message": "I've completed all the requested changes." } ``` > The `last_assistant_message` field (v2.1.47+) contains the final text Claude produced before stopping. Useful for validating completeness or logging outcomes. #### PreCompact Input For `manual`, `custom_instructions` comes from what the user passes into `/compact`. For `auto`, `custom_instructions` is empty. ```json { "session_id": "abc123", "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", "hook_event_name": "PreCompact", "trigger": "manual", "custom_instructions": "" } ``` #### SessionStart Input ```json { "session_id": "abc123", "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", "hook_event_name": "SessionStart", "source": "startup" } ```Hook Output
There are two ways for hooks to return output back to Claude Code. The output communicates whether to block and any feedback that should be shown to Claude and the user. #### Simple: Exit Code Hooks communicate status through exit codes, stdout, and stderr: - **Exit code 0**: Success. `stdout` is shown to the user in transcript mode (CTRL-R), except for `UserPromptSubmit` and `SessionStart`, where stdout is added to the context. - **Exit code 2**: Blocking error. `stderr` is fed back to Claude to process automatically. See per-hook-event behavior below. - **Other exit codes**: Non-blocking error. `stderr` is shown to the user and execution continues. > [!WARNING] > Reminder: Claude Code does not see stdout if the exit code is 0, except for > the `UserPromptSubmit` hook where stdout is injected as context. ##### Exit Code 2 Behavior | Hook Event | Behavior | | ------------------ | ------------------------------------------------------------------ | | `PreToolUse` | Blocks the tool call, shows stderr to Claude | | `PostToolUse` | Shows stderr to Claude (tool already ran) | | `Notification` | N/A, shows stderr to user only | | `UserPromptSubmit` | Blocks prompt processing, erases prompt, shows stderr to user only | | `Stop` | Blocks stoppage, shows stderr to Claude | | `SubagentStop` | Blocks stoppage, shows stderr to Claude subagent | | `PreCompact` | N/A, shows stderr to user only | | `SessionStart` | N/A, shows stderr to user only | #### Advanced: JSON Output Hooks can return structured JSON in `stdout` for more sophisticated control: ##### Common JSON Fields All hook types can include these optional fields: ```json { "continue": true, // Whether Claude should continue after hook execution (default: true) "stopReason": "string" // Message shown when continue is false "suppressOutput": true, // Hide stdout from transcript mode (default: false) } ``` If `continue` is false, Claude stops processing after the hooks run. - For `PreToolUse`, this is different from `"permissionDecision": "deny"`, which only blocks a specific tool call and provides automatic feedback to Claude. - For `PostToolUse`, this is different from `"decision": "block"`, which provides automated feedback to Claude. - For `UserPromptSubmit`, this prevents the prompt from being processed. - For `Stop` and `SubagentStop`, this takes precedence over any `"decision": "block"` output. - In all cases, `"continue" = false` takes precedence over any `"decision": "block"` output. `stopReason` accompanies `continue` with a reason shown to the user, not shown to Claude. ##### `PreToolUse` Decision Control `PreToolUse` hooks can control whether a tool call proceeds. - `"allow"` bypasses the permission system. `permissionDecisionReason` is shown to the user but not to Claude. (_Deprecated `"approve"` value + `reason` has the same behavior._) - `"deny"` prevents the tool call from executing. `permissionDecisionReason` is shown to Claude. (_`"block"` value + `reason` has the same behavior._) - `"ask"` asks the user to confirm the tool call in the UI. `permissionDecisionReason` is shown to the user but not to Claude. ```json { "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "allow" | "deny" | "ask", "permissionDecisionReason": "My reason here (shown to user)" }, "decision": "approve" | "block" | undefined, // Deprecated for PreToolUse but still supported "reason": "Explanation for decision" // Deprecated for PreToolUse but still supported } ``` ##### `PostToolUse` Decision Control `PostToolUse` hooks can control whether a tool call proceeds. - `"block"` automatically prompts Claude with `reason`. - `undefined` does nothing. `reason` is ignored. ```json { "decision": "block" | undefined, "reason": "Explanation for decision" } ``` ##### `UserPromptSubmit` Decision Control `UserPromptSubmit` hooks can control whether a user prompt is processed. - `"block"` prevents the prompt from being processed. The submitted prompt is erased from context. `"reason"` is shown to the user but not added to context. - `undefined` allows the prompt to proceed normally. `"reason"` is ignored. - `"hookSpecificOutput.additionalContext"` adds the string to the context if not blocked. ```json { "decision": "block" | undefined, "reason": "Explanation for decision", "hookSpecificOutput": { "hookEventName": "UserPromptSubmit", "additionalContext": "My additional context here" } } ``` ##### `Stop`/`SubagentStop` Decision Control `Stop` and `SubagentStop` hooks can control whether Claude must continue. - `"block"` prevents Claude from stopping. You must populate `reason` for Claude to know how to proceed. - `undefined` allows Claude to stop. `reason` is ignored. ```json { "decision": "block" | undefined, "reason": "Must be provided when Claude is blocked from stopping" } ``` ##### `SessionStart` Decision Control `SessionStart` hooks allow you to load in context at the start of a session. - `"hookSpecificOutput.additionalContext"` adds the string to the context. ```json { "hookSpecificOutput": { "hookEventName": "SessionStart", "additionalContext": "My additional context here" } } ``` ##### Exit Code Example: Bash Command Validation ```python #!/usr/bin/env python3 import json import re import sys # Define validation rules as a list of (regex pattern, message) tuples VALIDATION_RULES = [ ( r"\bgrep\b(?!.*\|)", "Use 'rg' (ripgrep) instead of 'grep' for better performance and features", ), ( r"\bfind\s+\S+\s+-name\b", "Use 'rg --files | rg pattern' or 'rg --files -g pattern' instead of 'find -name' for better performance", ), ] def validate_command(command: str) -> list[str]: issues = [] for pattern, message in VALIDATION_RULES: if re.search(pattern, command): issues.append(message) return issues try: input_data = json.load(sys.stdin) except json.JSONDecodeError as e: print(f"Error: Invalid JSON input: {e}", file=sys.stderr) sys.exit(1) tool_name = input_data.get("tool_name", "") tool_input = input_data.get("tool_input", {}) command = tool_input.get("command", "") if tool_name != "Bash" or not command: sys.exit(1) # Validate the command issues = validate_command(command) if issues: for message in issues: print(f"• {message}", file=sys.stderr) # Exit code 2 blocks tool call and shows stderr to Claude sys.exit(2) ``` ##### JSON Output Example: UserPromptSubmit to Add Context and Validation > [!NOTE] > For `UserPromptSubmit` hooks, you can inject context using either method: > > - Exit code 0 with stdout: Claude sees the context (special case for `UserPromptSubmit`) > - JSON output: Provides more control over the behavior ```python #!/usr/bin/env python3 import json import sys import re import datetime # Load input from stdin try: input_data = json.load(sys.stdin) except json.JSONDecodeError as e: print(f"Error: Invalid JSON input: {e}", file=sys.stderr) sys.exit(1) prompt = input_data.get("prompt", "") # Check for sensitive patterns sensitive_patterns = [ (r"(?i)\b(password|secret|key|token)\s*[:=]", "Prompt contains potential secrets"), ] for pattern, message in sensitive_patterns: if re.search(pattern, prompt): # Use JSON output to block with a specific reason output = { "decision": "block", "reason": f"Security policy violation: {message}. Please rephrase your request without sensitive information." } print(json.dumps(output)) sys.exit(0) # Add current time to context context = f"Current time: {datetime.datetime.now()}" print(context) """ The following is also equivalent: print(json.dumps({ "hookSpecificOutput": { "hookEventName": "UserPromptSubmit", "additionalContext": context, }, })) """ # Allow the prompt to proceed with the additional context sys.exit(0) ``` ##### JSON Output Example: PreToolUse with Approval ```python #!/usr/bin/env python3 import json import sys # Load input from stdin try: input_data = json.load(sys.stdin) except json.JSONDecodeError as e: print(f"Error: Invalid JSON input: {e}", file=sys.stderr) sys.exit(1) tool_name = input_data.get("tool_name", "") tool_input = input_data.get("tool_input", {}) # Example: Auto-approve file reads for documentation files if tool_name == "Read": file_path = tool_input.get("file_path", "") if file_path.endswith((".md", ".mdx", ".txt", ".json")): # Use JSON output to auto-approve the tool call output = { "decision": "approve", "reason": "Documentation file auto-approved", "suppressOutput": True # Don't show in transcript mode } print(json.dumps(output)) sys.exit(0) # For other cases, let the normal permission flow proceed sys.exit(0) ```Working with MCP Tools
Claude Code hooks work seamlessly with [Model Context Protocol (MCP) tools](/en/docs/claude-code/mcp). When MCP servers provide tools, they appear with a special naming pattern that you can match in your hooks. #### MCP Tool Naming MCP tools follow the pattern `mcp__Examples
> [!TIP] > For practical examples including code formatting, notifications, and file protection, see [More Examples](/en/docs/claude-code/hooks-guide#more-examples) in the get started guide.Security Considerations
#### Disclaimer **USE AT YOUR OWN RISK**: Claude Code hooks execute arbitrary shell commands on your system automatically. By using hooks, you acknowledge that: - You are solely responsible for the commands you configure - Hooks can modify, delete, or access any files your user account can access - Malicious or poorly written hooks can cause data loss or system damage - Anthropic provides no warranty and assumes no liability for any damages resulting from hook usage - You should thoroughly test hooks in a safe environment before production use Always review and understand any hook commands before adding them to your configuration.Hooks Security Considerations
Here are some key practices for writing more secure hooks: 1. **Validate and sanitize inputs** - Never trust input data blindly 2. **Always quote shell variables** - Use `"$VAR"` not `$VAR` 3. **Block path traversal** - Check for `..` in file paths 4. **Use absolute paths** - Specify full paths for scripts (use `$CLAUDE_PROJECT_DIR` for the project path) 5. **Skip sensitive files** - Avoid `.env`, `.git/`, keys, etc. #### Configuration Safety Direct edits to hooks in settings files don't take effect immediately. Claude Code: 1. Captures a snapshot of hooks at startup 2. Uses this snapshot throughout the session 3. Warns if hooks are modified externally 4. Requires review in `/hooks` menu for changes to apply This prevents malicious hook modifications from affecting your current session.Hook Execution Details
- **Timeout**: 60-second execution limit by default, configurable per command. - A timeout for an individual command does not affect the other commands. - **Parallelization**: All matching hooks run in parallel - **Environment**: Runs in current directory with Claude Code's environment - The `CLAUDE_PROJECT_DIR` environment variable is available and contains the absolute path to the project root directory - **Input**: JSON via stdin - **Output**: - PreToolUse/PostToolUse/Stop: Progress shown in transcript (Ctrl-R) - Notification: Logged to debug only (`--debug`)Debugging
#### Basic Troubleshooting If your hooks aren't working: 1. **Check configuration** - Run `/hooks` to see if your hook is registered 2. **Verify syntax** - Ensure your JSON settings are valid 3. **Test commands** - Run hook commands manually first 4. **Check permissions** - Make sure scripts are executable 5. **Review logs** - Use `claude --debug` to see hook execution details Common issues: - **Quotes not escaped** - Use `\"` inside JSON strings - **Wrong matcher** - Check tool names match exactly (case-sensitive) - **Command not found** - Use full paths for scripts #### Advanced Debugging For complex hook issues: 1. **Inspect hook execution** - Use `claude --debug` to see detailed hook execution 2. **Validate JSON schemas** - Test hook input/output with external tools 3. **Check environment variables** - Verify Claude Code's environment is correct 4. **Test edge cases** - Try hooks with unusual file paths or inputs 5. **Monitor system resources** - Check for resource exhaustion during hook execution 6. **Use structured logging** - Implement logging in your hook scripts #### Debug Output Example Use `claude --debug` to see hook execution details: ``` [DEBUG] Executing hooks for PostToolUse:Write [DEBUG] Getting matching hook commands for PostToolUse with query: Write [DEBUG] Found 1 hook matchers in settings [DEBUG] Matched 1 hooks for query "Write" [DEBUG] Found 1 hook commands to execute [DEBUG] Executing hook command:Security & Permissions
#### Tool Permission Patterns ```bash # Allow specific tools (read/edit files) claude --allowedTools "Edit,Read" # Allow tool categories incl. Bash (but still scoped below) claude --allowedTools "Edit,Read,Bash" # Scoped permissions (all git commands) claude --allowedTools "Bash(git:*)" # Multiple scopes (git + npm) claude --allowedTools "Bash(git:*),Bash(npm:*)" ```Dangerous Mode
> [!Warning] > NEVER use in Production systems, shared machines, or any systems with important data > Only use with isolated environments like a **Docker container**, using this mode can cause data loss and comprimise your system! > > `claude --dangerously-skip-permissions`Automation & Integration
Automation & Scripting with Claude Code
> GitHub Actions you can copy/paste :p 1. **Install the Claude GitHub App** on your org/repo (required for Actions to comment on PRs/issues). 2. In your repo, add a secret **`ANTHROPIC_API_KEY`** Settings → Secrets and variables → Actions → New repository secret 3. Copy the workflows below into **`.github/workflows/`**. 4. Open a **test PR** (or a new issue) to see them run. > [!TIP] > Pin Actions to a release tag (e.g. `@v1`) when you adopt them long‑term. The snippets below use branch tags for readability.Auto PR Review (inline comments)
> **Creates a structured review (with inline comments) as soon as a PR opens or updates.** **File:** `.github/workflows/claude-pr-auto-review.yml` ```yaml name: Auto review PRs on: pull_request: types: [opened, synchronize, reopened, ready_for_review] permissions: contents: read pull-requests: write jobs: auto-review: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 1 - name: Claude PR review uses: anthropics/claude-code-action@main with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} # Claude will fetch the diff and leave inline comments direct_prompt: | Review this pull request’s diff for correctness, readability, testing, performance, and DX. Prefer specific, actionable suggestions. Use inline comments where relevant. # GitHub tools permitted during the run: allowed_tools: >- mcp__github__get_pull_request_diff, mcp__github__create_pending_pull_request_review, mcp__github__add_comment_to_pending_review, mcp__github__submit_pending_pull_request_review ```Security Review on Every PR
> **Runs a focused security scan and comments findings directly on the PR.** **File:** `.github/workflows/claude-security-review.yml` ```yaml name: Security Review on: pull_request: permissions: contents: read pull-requests: write jobs: security: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: ref: ${{ github.event.pull_request.head.sha || github.sha }} fetch-depth: 2 - name: Claude Code Security Review uses: anthropics/claude-code-security-review@main with: claude-api-key: ${{ secrets.ANTHROPIC_API_KEY }} comment-pr: true # Optional: # exclude-directories: "docs,examples" # claudecode-timeout: "20" # claude-model: "claude-sonnet-4-6-20260217" ```Issue Triage (suggest labels & severity)
> **When a new issue opens, Claude proposes labels/severity and posts a tidy triage comment. You can enable **auto‑apply labels** by flipping a single flag** **File:** `.github/workflows/claude-issue-triage.yml` ```yaml name: Claude Issue Triage on: issues: types: [opened, edited, reopened] permissions: contents: read issues: write jobs: triage: runs-on: ubuntu-latest env: CLAUDE_MODEL: claude-sonnet-4-6-20260217 steps: - name: Collect context & similar issues id: gather env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | TITLE="${{ github.event.issue.title }}" BODY="${{ github.event.issue.body }}" # naive similar search by title words Q=$(echo "$TITLE" | tr -dc '[:alnum:] ' | awk '{print $1" "$2" "$3" "$4}') gh api -X GET search/issues -f q="repo:${{ github.repository }} is:issue $Q" -f per_page=5 > similars.json echo "$TITLE" > title.txt echo "$BODY" > body.txt - name: Ask Claude for triage JSON env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} run: | cat > payload.json << 'JSON' { "model": "${{ env.CLAUDE_MODEL }}", "max_tokens": 1500, "system": "You are a pragmatic triage engineer. Be specific, cautious with duplicates.", "messages": [{ "role": "user", "content": [{ "type":"text", "text":"Given the issue and similar candidates, produce STRICT JSON with keys: labels (array of strings), severity (one of: low, medium, high, critical), duplicate_url (string or empty), comment_markdown (string brief). Do not include any extra keys." }, {"type":"text","text":"Issue title:\n"}, {"type":"text","text": (include from file) }, {"type":"text","text":"\n\nIssue body:\n"}, {"type":"text","text": (include from file) }, {"type":"text","text":"\n\nSimilar issues (JSON):\n"}, {"type":"text","text": (include from file) }] }] } JSON # Inject files safely jq --arg title "$(cat title.txt)" '.messages[0].content[2].text = $title' payload.json \ | jq --arg body "$(cat body.txt)" '.messages[0].content[4].text = $body' \ | jq --arg sims "$(cat similars.json)" '.messages[0].content[6].text = $sims' > payload.final.json curl -s https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d @payload.final.json > out.json jq -r '.content[0].text' out.json > triage.json || echo '{}' > triage.json # Validate JSON to avoid posting garbage jq -e . triage.json >/dev/null 2>&1 || echo '{"labels":[],"severity":"low","duplicate_url":"","comment_markdown":"(triage failed to parse)"}' > triage.json - name: Apply labels (optional) if: ${{ false }} # flip to `true` to auto-apply labels uses: actions/github-script@v7 with: script: | const triage = JSON.parse(require('fs').readFileSync('triage.json','utf8')) if (triage.labels?.length) { await github.rest.issues.addLabels({ owner: context.repo.owner, repo: context.repo.repo, issue_number: context.issue.number, labels: triage.labels }) } - name: Post triage comment uses: actions/github-script@v7 with: script: | const fs = require('fs') const triage = JSON.parse(fs.readFileSync('triage.json','utf8')) const md = `### 🤖 Triage - **Suggested labels:** ${triage.labels?.join(', ') || '—'} - **Severity:** ${triage.severity || '—'} ${triage.duplicate_url ? `- **Possible duplicate:** ${triage.duplicate_url}\n` : ''} --- ${triage.comment_markdown || ''}` await github.rest.issues.createComment({ owner: context.repo.owner, repo: context.repo.repo, issue_number: context.issue.number, body: md }) ``` > [!NOTE] > The triage workflow posts a **suggestion comment** by default. Flip the `Apply labels` step to `true` if you want labels applied automatically. > > ### Configuration & Customization > > - **Model selection**: set `CLAUDE_MODEL` (e.g., `claude-sonnet-4-6-20260217`) where shown. > - **Secrets**: `ANTHROPIC_API_KEY` is required. The built‑in `GITHUB_TOKEN` is sufficient for posting comments and applying labels. > - **Permissions**: each workflow declares the least privileges it needs (`pull-requests: write` and/or `issues: write`). Adjust only if your org requires stricter policies. > - **Scope**: use `paths:` filters on triggers to limit when workflows run (e.g., only for `/src` or exclude `/docs`). > > ### Troubleshooting > > Check the **Actions logs** first—most issues are missing secrets/permissions or a mis‑indented YAML block. > > - **No comments appear on PRs**: Verify the Claude GitHub App is installed and the workflow has `pull-requests: write` permission. > - **403 when applying labels**: Ensure the job or step has `issues: write`. The default `GITHUB_TOKEN` must have access to this repo. > - **Anthropic API errors**: Confirm `ANTHROPIC_API_KEY` is set at repository (or org) level and not expired. > - **“YAML not well‑formed”**: Validate spacing—two spaces per nesting level; no tabs. ---Help & Troubleshooting
> [!TIP] > **Q:`claude` not found, but `npx claude` works?** > > > **A: Your `PATH` is missing the npm global bin. See the `PATH` issue section for [`Windows`](#windowspath) or [`Linux`](#linuxpath)** > > **Q:** **Which Node.js version do I need?** > > > **A:** **Node.js **18+** (ideally **20+**). Check with `node --version`.** > > **Q: Where do I see logs** > > > **A: Run `claude doctor` and `claude --verbose` the diagnostic window will point to log locations.** > > **Q: Do I need to reboot after editing PATH?** > > > **A: No reboot required, but you must open a new terminal window.**
Debug Quick Commands_Check the output of `claude doctor` for log locations and environment checks._ > [!Note] > > ```bash > claude # Open Claude UI (if on PATH) > claude --version # Show CLI version (e.g., 1.0.xx) > claude update # Update the CLI (if supported) > > claude doctor # Open diagnostic / debug window > npx claude /doctor # Opens diagnostic/debug window > > claude --debug # Launch claude with diagnostics > claude --verbose # Verbose logging > > where claude # Windows (cmd) > which claude # macOS/Linux (bash/zsh) > > npm bin -g # Linux Verify your global bin path > npm prefix -g # Windows Verify your global bin path > ``` |
Path Temp Fix**Your **PATH** likely doesn’t include the global npm bin directory.** > [!Note] > > #### Windows (CMD): > > ```bash > set PATH=%USERPROFILE%\AppData\Roaming\npm;C:\Program Files\nodejs;%PATH% > where claude > claude --debug > ``` > > #### Windows (PowerShell): > > ```powershell > $env:Path = "$env:USERPROFILE\AppData\Roaming\npm;C:\Program Files\nodejs;$env:Path" > where claude > claude --debug > ``` > > #### Linux/MacOS (bash/zsh) > > ```bash > export PATH="$(npm config get prefix)/bin:$HOME/.local/bin:$PATH" > which claude > claude doctor > ``` |
Windows Path Perm Fix**Replace ` |
Installation / Node.js Issues**Must be Node 18+ (20+ recommended)** ```bash node --version ``` **Clean uninstall** ```bash npm uninstall -g @anthropic-ai/claude-code ``` **Fresh install** ```bash npm install -g @anthropic-ai/claude-code ``` |
Authentication Issues> *Verify your Anthropic API key is available to the CLI.* **PowerShell (Windows):** ```powershell echo $env:ANTHROPIC_API_KEY claude -p "test" --verbose ``` **bash/zsh (macOS/Linux):** ```bash echo $ANTHROPIC_API_KEY claude -p "test" --verbose ``` _If the variable is empty set it for your shell/profile or use your OS keychain/secrets manager._ |
Permission / Allowed Tools Issues**Inspect permissions** ```bash claude config get allowedTools ``` **Reset permissions** ```bash claude config set allowedTools "[]" ``` **Minimal safe set (example)** ```bash claude config set allowedTools '["Edit","View"]' ``` |
MCP (Model Context Protocol) Issues> **Debug MCP servers** ```bash claude --debug ``` > **List & remove MCP servers** ```bash claude mcp list claude mcp remove |
Full Clean Reinstall (Windows / PowerShell)> [!Caution] > **The following removes Claude Code binaries, caches, and config under your user profile** > 1. Uninstall the global npm package ```powershell npm uninstall -g @anthropic-ai/claude-code ``` > 2. Remove leftover shim files ```powershell Remove-Item -LiteralPath "$env:USERPROFILE\AppData\Roaming\npm\claude*" -Force -ErrorAction SilentlyContinue Remove-Item -LiteralPath "$env:USERPROFILE\AppData\Roaming\npm\node_modules\@anthropic-ai\claude-code" -Recurse -Force -ErrorAction SilentlyContinue ``` > 3. Delete cached installer & native files ```powershell Remove-Item -LiteralPath "$env:USERPROFILE\.claude\downloads\*" -Recurse -Force -ErrorAction SilentlyContinue Remove-Item -LiteralPath "$env:USERPROFILE\.claude\local\bin\claude.exe" -Force -ErrorAction SilentlyContinue Remove-Item -LiteralPath "$env:USERPROFILE\.claude\local" -Recurse -Force -ErrorAction SilentlyContinue ``` > 4. Remove config and project-local files ```powershell Remove-Item -LiteralPath "$env:USERPROFILE\.claude.json" -Force -ErrorAction SilentlyContinue Remove-Item -LiteralPath "$env:USERPROFILE\.claude" -Recurse -Force -ErrorAction SilentlyContinue ``` > 5. Reinstall ```powershell npm install -g @anthropic-ai/claude-code ``` |
One‑Shot Health Check (copy/paste)**Windows (PowerShell):** ```powershell Write-Host "`n=== Node & npm ==="; node --version; npm --version Write-Host "`n=== Where is claude? ==="; where claude Write-Host "`n=== Try doctor ==="; try { claude doctor } catch { Write-Host "claude not on PATH" } Write-Host "`n=== API key set? ==="; if ($env:ANTHROPIC_API_KEY) { "Yes" } else { "No" } ``` **macOS/Linux (bash/zsh):** ```bash echo "=== Node & npm ==="; node --version; npm --version echo "=== Where is claude? ==="; which claude || echo "claude not on PATH" echo "=== Try doctor ==="; claude doctor || true echo "=== API key set? ==="; [ -n "$ANTHROPIC_API_KEY" ] && echo Yes || echo No ``` |
Appendix: Useful Paths- **Windows npm global bin:** `C:\Users\ |