mirror of
https://github.com/zebbern/claude-code-guide.git
synced 2026-09-15 04:48:56 +08:00
2643 lines
105 KiB
Markdown
2643 lines
105 KiB
Markdown
<div align="center">
|
||
|
||
<h2 id="claude-code-community-guide">Claude Code Guide</h2>
|
||
|
||
*For updates and contributions, visit the [official Claude Code documentation](https://claude.ai/code)*
|
||
|
||
|
||
[](https://github.com/anthropics/claude-code)
|
||
[](https://claude.ai/code)
|
||
|
||
|
||
</div>
|
||
|
||
<div align="center">
|
||
|
||
<kbd>
|
||
|
||
| Section | Status |
|
||
|---------------------------------------------|------------------------------|
|
||
| Guides on how to install on Windows, Linux, MacOS | ✅ |
|
||
| Tips and Tricks | ✅ |
|
||
| MCP Overview with what to use | ✅ |
|
||
| Community Guides | ✅ |
|
||
| Troubleshooting | ✅ |
|
||
| How to use Claude code the most optimal way| ✅ |
|
||
|
||
### How To Use Claude Code Via Discord [Here!](https://github.com/zebbern/claude-code-discord)
|
||
|
||
|
||
</kbd>
|
||
|
||
#### [Click For Daily Updated & Organized Claude Changelogs & News](https://github.com/zebbern/claude-code-guide/tree/main/Official%20Claude%20Releases)
|
||
|
||
</div>
|
||
|
||
---
|
||
|
||
<h3 id="content">Content</h3>
|
||
|
||
_Quick links:_ [Install](#quick-start) · [Commands](#claude-commands) · [Shortcuts](#keyboard-shortcuts) · [MCP](#mcp-integration) · [Troubleshoot](#help--troubleshooting)
|
||
|
||
- **[Getting Started](#getting-started)**
|
||
- [Quick Start](#quick-start)
|
||
- [Initial Setup](#initial-setup)
|
||
|
||
- **[Configuration & Environment](#configuration--environment)**
|
||
- [Environment Variables](#environment-variables)
|
||
- [Configuration Files](#configuration-files)
|
||
|
||
- **[Commands & Usage](#commands--usage)**
|
||
- [Claude Commands](#claude-commands)
|
||
- [Cheat Sheet](#cheat-sheet)
|
||
|
||
- **[Interface & Input](#interface--input)**
|
||
- [Keyboard Shortcuts](#keyboard-shortcuts)
|
||
- [Vim Mode](#vim-mode)
|
||
|
||
- **[Advanced Features](#advanced-features)**
|
||
- [Sub Agents](#sub-agents)
|
||
- [MCP Integration](#mcp-integration)
|
||
- [Hooks System](#hooks-system)
|
||
|
||
- **[Security & Permissions](#security--permissions)**
|
||
- [Dangerous Mode](#dangerous-mode)
|
||
- [Security Best Practices](#security-best-practices-main)
|
||
|
||
- **[Automation & Integration](#automation--integration)**
|
||
- [Automation & Scripting](#automation--scripting-with-claude-code)
|
||
- [Auto PR Review](#auto-pr-review-inline-comments)
|
||
- [Issue Triage](#issue-triage-suggest-labels--severity)
|
||
|
||
- **[Help & Troubleshooting](#help--troubleshooting)**
|
||
- [Installation Issues](#installation--nodejs-issues)
|
||
- [MCP Issues](#mcp-model-context-protocol-issues)
|
||
- [Best Practices](#best-practices)
|
||
|
||
- **[Third-Party Integrations](#third-party-integrations)**
|
||
- [DeepSeek Integration](#deepseek-integration)
|
||
|
||
|
||
---
|
||
|
||
<h1 id="getting-started">Getting Started</h1>
|
||
|
||
**Enable sound alerts when claude completes the task:**
|
||
>
|
||
> <kbd>claude config set --global preferredNotifChannel terminal_bell</kbd>
|
||
<h2 id="quick-start">Quick Start</h2>
|
||
|
||
> [!TIP]
|
||
> **Send <mark>claude</mark> or <mark>npx claude</mark> in terminal to start the interface**
|
||
>
|
||
> **Go to [Help & Troubleshooting](#help--troubleshooting) to fix issues...**
|
||
```C
|
||
# Node.js 18+⭐️
|
||
/*Universal Method */ npm install -g @anthropic-ai/claude-code
|
||
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
|
||
# Windows
|
||
/* Via CMD */ npm install -g @anthropic-ai/claude-code
|
||
/* Via Powershell */ irm https://claude.ai/install.ps1 | iex
|
||
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
|
||
# WSL/GIT
|
||
/* Via Terminal */ npm install -g @anthropic-ai/claude-code
|
||
/* Via Terminal */ curl -fsSL https://claude.ai/install.sh | bash
|
||
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
|
||
# MacOS */ brew install node && npm install -g @anthropic-ai/claude-code
|
||
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
|
||
# Linux
|
||
/* Via Terminal */ sudo apt update && sudo apt install -y nodejs npm
|
||
/* Via Terminal */ npm install -g @anthropic-ai/claude-code
|
||
/* Via Terminal */ curl -fsSL https://claude.ai/install.sh | bash
|
||
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
|
||
# Arch
|
||
/* Via Terminal */ yay -S claude-code*/
|
||
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
|
||
# Docker
|
||
/* Windows (CMD) */ docker run -it --rm -v "%cd%:/workspace" -e ANTHROPIC_API_KEY="sk-your-key" node:20-slim bash -lc "npm i -g @anthropic-ai/claude-code && cd /workspace && claude"
|
||
/* macOS/Linux (bash/zsh)*/ docker run -it --rm -v "$PWD:/workspace" -e ANTHROPIC_API_KEY="sk-your-key" node:20-slim bash -lc 'npm i -g @anthropic-ai/claude-code && cd /workspace && claude'
|
||
/* No bash Fallback */ docker run -it --rm -v "$PWD:/workspace" -e ANTHROPIC_API_KEY="sk-your-key" node:20-slim sh -lc 'npm i -g @anthropic-ai/claude-code && cd /workspace && claude'
|
||
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
|
||
# Check if claude is installed correctly
|
||
/* Linux */ which claude
|
||
/* Windows */ where claude
|
||
/* Universal */ claude --version
|
||
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
|
||
# Common Management
|
||
/*claude config */ Configure settings
|
||
/*claude mcp list */ Setup MCP servers, you can also replace "list" with add/remove
|
||
/*claude /agents */ Configure/Setup Subagents for different tasks
|
||
/*claude update */ Update to latest
|
||
```
|
||
|
||
---
|
||
|
||
> [!Tip]
|
||
> <ins>**Open Project Via Terminal Into VS Code / Cursor**</ins>
|
||
> ### $ - <kbd>cd /path/to/project</kbd>
|
||
> ### $ - <kbd>code .</kbd>
|
||
>
|
||
**Make sure you have the <mark>(Claude Code extension)</mark> installed in your VS Code / Cursor**
|
||
|
||
---
|
||
|
||
<h2 id="system-requirements">System Requirements</h2>
|
||
|
||
> - OS: macOS 10.15+, Ubuntu 20.04+/Debian 10+, or Windows 10/11 or WSL
|
||
|
||
> - Hardware: 4GB RAM minimum 8GB+ recommended
|
||
|
||
> - Software: Node.js 18+ or git 2.23+ (optional) & GitHub or GitLab CLI for PR workflows (optional)
|
||
|
||
> - Internet: Connection for API calls
|
||
|
||
> - Node.js 18+
|
||
|
||
|
||
---
|
||
|
||
<h2 id="initial-setup">Initial Setup</h2>
|
||
|
||
> [!Tip]
|
||
> **Find API key from [Anthropic Console](https://console.anthropic.com)**
|
||
>
|
||
> **Do NOT commit real keys use git-ignored files, OS key stores, or secret managers**
|
||
```C
|
||
# Universal
|
||
/* start login process */ claude /login
|
||
/* Setup long-lived authentication token */ claude setup-token
|
||
----------------------------------------------------------------------------------------------------------------------------------
|
||
# Windows
|
||
/* Set-api-key */ set ANTHROPIC_API_KEY=sk-your-key-here-here
|
||
/* cmd-masked-check */ echo OK: %ANTHROPIC_API_KEY:~0,8%***
|
||
/* Set-persistent-key */ setx ANTHROPIC_API_KEY "sk-your-key-here-here"
|
||
/* cmd-unset-key */ set ANTHROPIC_API_KEY=
|
||
----------------------------------------------------------------------------------------------------------------------------------
|
||
# Linux
|
||
/* Set-api-key */ export ANTHROPIC_API_KEY="sk-your-key-here-here"
|
||
/* masked-check */ echo "OK: ${ANTHROPIC_API_KEY:0:8}***"
|
||
/* remove-session */ unset ANTHROPIC_API_KEY
|
||
----------------------------------------------------------------------------------------------------------------------------------
|
||
# Powershell
|
||
/* ps-session */ $env:ANTHROPIC_API_KEY = "sk-your-key-here-here"
|
||
/* ps-masked-check */ "OK: $($env:ANTHROPIC_API_KEY.Substring(0,8))***"
|
||
/* ps-persist */ [Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY","sk-your-key-here-here","User")
|
||
/* ps-rotate */ $env:ANTHROPIC_API_KEY = "sk-new-key"
|
||
/* ps-remove */ Remove-Item Env:\ANTHROPIC_API_KEY
|
||
----------------------------------------------------------------------------------------------------------------------------------
|
||
# Other...
|
||
# persist-bash/* */ echo 'export ANTHROPIC_API_KEY="sk-your-key-here-here"' >> ~/.bashrc && source ~/.bashrc
|
||
# persist-zsh /* */ echo 'export ANTHROPIC_API_KEY="sk-your-key-here-here"' >> ~/.zshrc && source ~/.zshrc
|
||
# persist-fish/* */ fish -lc 'set -Ux ANTHROPIC_API_KEY sk-your-key-here-here'
|
||
----------------------------------------------------------------------------------------------------------------------------------
|
||
```
|
||
|
||
---
|
||
|
||
<h1 id="configuration--environment">Configuration & Environment</h1>
|
||
|
||
<h2 id="environment-variables">Environment Variables</h2>
|
||
|
||
> **You can also set any of these in settings.json under the "env" key for automatic application.**
|
||
|
||
> [!Important]
|
||
> **Windows Users replace <kbd>export</kbd> with <kbd>set</kbd> or <kbd>setx</kbd> for perm**
|
||
```bash
|
||
# Environment toggles (put in ~/.bashrc or ~/.zshrc)
|
||
export ANTHROPIC_API_KEY="sk-your-key-here-here" # API key sent as X-Api-Key header (interactive usage: /login)
|
||
export ANTHROPIC_AUTH_TOKEN="my-auth-token" # Custom Authorization header; Claude adds "Bearer " prefix automatically
|
||
export ANTHROPIC_CUSTOM_HEADERS="X-Trace-Id: 12345" # Extra request headers (format: "Name: Value")
|
||
|
||
export ANTHROPIC_MODEL="claude-sonnet-4-20250514" # Custom model name to use
|
||
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4-20250514" # Default Sonnet model alias
|
||
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-20250514" # Default Opus model alias
|
||
export ANTHROPIC_SMALL_FAST_MODEL="haiku-model" # Haiku-class model for background tasks (placeholder)
|
||
export ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION="REGION" # Override AWS region for the small/fast model on Bedrock (placeholder)
|
||
|
||
export AWS_BEARER_TOKEN_BEDROCK="bedrock_..." # Amazon Bedrock API key/token for authentication
|
||
|
||
export BASH_DEFAULT_TIMEOUT_MS=60000 # Default timeout (ms) for long-running bash commands
|
||
export BASH_MAX_TIMEOUT_MS=300000 # Maximum timeout (ms) allowed for long-running bash commands
|
||
export BASH_MAX_OUTPUT_LENGTH=20000 # Max characters in bash outputs before middle-truncation
|
||
|
||
export CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1 # (0 or 1) return to original project dir after each Bash command
|
||
export CLAUDE_CODE_API_KEY_HELPER_TTL_MS=600000 # Interval (ms) to refresh creds when using apiKeyHelper
|
||
export CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL=1 # (0 or 1) skip auto-installation of IDE extensions
|
||
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=4096 # Max number of output tokens for most requests
|
||
|
||
export CLAUDE_CODE_USE_BEDROCK=1 # (0 or 1) use Amazon Bedrock
|
||
export CLAUDE_CODE_USE_VERTEX=0 # (0 or 1) use Google Vertex AI
|
||
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=0 # (0 or 1) skip AWS auth for Bedrock (e.g., via LLM gateway)
|
||
export CLAUDE_CODE_SKIP_VERTEX_AUTH=0 # (0 or 1) skip Google auth for Vertex (e.g., via LLM gateway)
|
||
|
||
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=0 # (0 or 1) disable nonessential traffic (equivalent to DISABLE_* below)
|
||
export CLAUDE_CODE_DISABLE_TERMINAL_TITLE=0 # (0 or 1) disable automatic terminal title updates
|
||
|
||
export DISABLE_AUTOUPDATER=0 # (0 or 1) disable automatic updates (overrides autoUpdates setting)
|
||
export DISABLE_BUG_COMMAND=0 # (0 or 1) disable the /bug command
|
||
export DISABLE_COST_WARNINGS=0 # (0 or 1) disable cost warning messages
|
||
export DISABLE_ERROR_REPORTING=0 # (0 or 1) opt out of Sentry error reporting
|
||
export DISABLE_NON_ESSENTIAL_MODEL_CALLS=0 # (0 or 1) disable model calls for non-critical paths
|
||
export DISABLE_TELEMETRY=0 # (0 or 1) opt out of Statsig telemetry
|
||
|
||
export HTTP_PROXY="http://proxy:8080" # HTTP proxy server URL
|
||
export HTTPS_PROXY="https://proxy:8443" # HTTPS proxy server URL
|
||
|
||
export MAX_THINKING_TOKENS=0 # (0 or 1 to turn off/on) force a thinking budget for the model
|
||
export MCP_TIMEOUT=120000 # MCP server startup timeout (ms)
|
||
export MCP_TOOL_TIMEOUT=60000 # MCP tool execution timeout (ms)
|
||
export MAX_MCP_OUTPUT_TOKENS=25000 # Max tokens allowed in MCP tool responses (default 25000)
|
||
|
||
export USE_BUILTIN_RIPGREP=0 # (0 or 1) set 0 to use system-installed rg instead of bundled one
|
||
|
||
export VERTEX_REGION_CLAUDE_3_5_HAIKU="REGION" # Region override for Claude 3.5 Haiku on Vertex AI
|
||
export VERTEX_REGION_CLAUDE_3_5_SONNET="REGION" # Region override for Claude 3.5 Sonnet on Vertex AI
|
||
export VERTEX_REGION_CLAUDE_3_7_SONNET="REGION" # Region override for Claude 3.7 Sonnet on Vertex AI
|
||
export VERTEX_REGION_CLAUDE_4_0_OPUS="REGION" # Region override for Claude 4.0 Opus on Vertex AI
|
||
export VERTEX_REGION_CLAUDE_4_0_SONNET="REGION" # Region override for Claude 4.0 Sonnet on Vertex AI
|
||
export VERTEX_REGION_CLAUDE_4_1_OPUS="REGION" # Region override for Claude 4.1 Opus on Vertex AI
|
||
```
|
||
|
||
<h2 id="global-config-options">Global Config Options</h2>
|
||
|
||
```bash
|
||
claude config set -g theme dark # Theme: dark | light | light-daltonized | dark-daltonized
|
||
claude config set -g preferredNotifChannel iterm2_with_bell # Notification channel: iterm2 | iterm2_with_bell | terminal_bell | notifications_disabled
|
||
claude config set -g autoUpdates true # Auto-download & install updates (applied on restart)
|
||
claude config set -g verbose true # Show full bash/command outputs
|
||
|
||
claude config set -g includeCoAuthoredBy false # Omit "co-authored-by Claude" in git commits/PRs
|
||
claude config set -g forceLoginMethod console # Restrict login to Anthropic Console (API billing)
|
||
claude config set -g model "claude-3-5-sonnet-20241022" # Default model override
|
||
claude config set -g statusLine '{"type":"command","command":"~/.claude/statusline.sh"}' # Custom status line
|
||
|
||
claude config set -g enableAllProjectMcpServers true # Auto-approve all MCP servers from .mcp.json
|
||
claude config set -g enabledMcpjsonServers '["memory","github"]' # Approve specific MCP servers
|
||
claude config set -g disabledMcpjsonServers '["filesystem"]' # Reject specific MCP servers
|
||
```
|
||
> [!Important]
|
||
> **Windows Users replace <kbd>export</kbd> with <kbd>set</kbd>**
|
||
```bash
|
||
export DISABLE_AUTOUPDATER=1 # Turn off automatic updates globally (overrides autoUpdates)
|
||
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 # Disable nonessential traffic (equiv. to DISABLE_* toggles below)
|
||
export DISABLE_TELEMETRY=1 # Opt out of Statsig telemetry
|
||
export DISABLE_ERROR_REPORTING=1 # Opt out of Sentry error reporting
|
||
export DISABLE_BUG_COMMAND=1 # Disable the /bug command
|
||
export DISABLE_COST_WARNINGS=0 # Keep cost warnings (set 1 to hide)
|
||
export DISABLE_NON_ESSENTIAL_MODEL_CALLS=1 # Skip non-critical model calls (flavor text, etc.)
|
||
|
||
export CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1 # Stop auto-updating terminal titles
|
||
export CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1 # Return to original project dir after each Bash command
|
||
export CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL=1 # Skip auto-installation of IDE extensions
|
||
export USE_BUILTIN_RIPGREP=0 # Use system 'rg' (0) instead of bundled 'rg'
|
||
|
||
export MAX_THINKING_TOKENS=0 # (0 or 1 to turn off/on) force a thinking budget for the model
|
||
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=4096 # Cap typical response size (example value)
|
||
|
||
export HTTP_PROXY="http://proxy.company:8080" # HTTP proxy (if needed)
|
||
export HTTPS_PROXY="https://proxy.company:8443" # HTTPS proxy (if needed)
|
||
```
|
||
|
||
<h2 id="configuration-files">Configuration Files</h2>
|
||
|
||
**(Memory type) Claude Code offers four memory locations in a hierarchical structure, each serving a different purpose:**
|
||
|
||
| Memory Type | Location | Purpose | Use Case Examples | Shared With |
|
||
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------- |
|
||
| **Enterprise policy** | macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md`<br />Linux: `/etc/claude-code/CLAUDE.md`<br />Windows: `C:\ProgramData\ClaudeCode\CLAUDE.md` | Organization-wide instructions managed by IT/DevOps | Company coding standards, security policies, compliance requirements | All users in organization |
|
||
| **Project memory** | `./CLAUDE.md` | Team-shared instructions for the project | Project architecture, coding standards, common workflows | Team members via source control |
|
||
| **User memory** | `~/.claude/CLAUDE.md` | Personal preferences for all projects | Code styling preferences, personal tooling shortcuts | Just you (all projects) |
|
||
| **Project memory (local)** | `./CLAUDE.local.md` | Personal project-specific preferences | *(Deprecated, see below)* Your sandbox URLs, preferred test data | Just you (current project) |
|
||
|
||
>All memory files are automatically loaded into Claude Code's context when launched. Files higher in the hierarchy take precedence and are loaded first, providing a foundation that more specific memories build upon.
|
||
|
||
---
|
||
|
||
<h1 id="commands--usage">Commands & Usage</h1>
|
||
|
||
<h2 id="claude-commands">Claude Commands</h2>
|
||
|
||
| Command | Purpose |
|
||
| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `/add-dir` | Add additional working directories |
|
||
| `/agents` | Manage custom AI subagents for specialized tasks |
|
||
| `/bug` | Report bugs (sends conversation to Anthropic) |
|
||
| `/clear` | Clear conversation history |
|
||
| `/compact [instructions]` | Compact conversation with optional focus instructions |
|
||
| `/config` | View/modify configuration |
|
||
| `/cost` | Show token usage statistics and billing information |
|
||
| `/doctor` | Checks the health of your Claude Code installation |
|
||
| `/help` | Get usage help |
|
||
| `/init` | Initialize project with CLAUDE.md guide |
|
||
| `/login` | Switch Anthropic accounts |
|
||
| `/logout` | Sign out from your Anthropic account |
|
||
| `/mcp` | Manage MCP server connections and OAuth authentication |
|
||
| `/memory` | Edit CLAUDE.md memory files |
|
||
| `/model` | Select or change the AI model |
|
||
| `/permissions` | View or update tool permissions |
|
||
| `/pr_comments` | View pull request comments |
|
||
| `/review` | Request code review |
|
||
| `/status` | View account and system statuses |
|
||
| `/terminal-setup` | Install Shift+Enter key binding for newlines (iTerm2 and VSCode only) |
|
||
| `/vim` | Enter vim mode for alternating insert and command modes |
|
||
|
||
<h2 id="command-line-flags">Command Line Flags</h2>
|
||
|
||
| 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-format <format>` | Output format (only works with `--print`): `text` (default), `json` (single result), or `stream-json` (realtime streaming). | `claude -p "query" --output-format json` |
|
||
| `--input-format <format>` | Input format (only works with `--print`): `text` (default) or `stream-json` (realtime streaming input). | `claude -p --output-format stream-json --input-format stream-json` |
|
||
| `--replay-user-messages` | Re-emit user messages from stdin back to stdout for acknowledgment — **only works with** `--input-format=stream-json` **and** `--output-format=stream-json`. | `claude --input-format stream-json --output-format stream-json --replay-user-messages` |
|
||
| `--allowedTools`, `--allowed-tools <tools...>` | Comma/space-separated list of tool names to allow (e.g. `"Bash(git:*) Edit"`). | `--allowed-tools "Bash(git:*)" Edit"` |
|
||
| `--disallowedTools`, `--disallowed-tools <tools...>` | Comma/space-separated list of tool names to deny (e.g. `"Bash(git:*) Edit"`). | `--disallowed-tools "Edit"` |
|
||
| `--mcp-config <configs...>` | Load MCP servers from JSON files or strings (space-separated). | `claude --mcp-config ./mcp-servers.json` |
|
||
| `--strict-mcp-config` | Only use MCP servers from `--mcp-config`, ignoring other MCP configurations. | `claude --mcp-config ./a.json --strict-mcp-config` |
|
||
| `--append-system-prompt <prompt>` | Append a system prompt to the default system prompt (useful in print mode). | `claude -p --append-system-prompt "Do X then Y"` |
|
||
| `--permission-mode <mode>` | Permission mode for the session (choices include `acceptEdits`, `bypassPermissions`, `default`, `plan`). | `claude --permission-mode plan` |
|
||
| `--permission-prompt-tool <tool>` | Specify an MCP tool to handle permission prompts in non-interactive mode. | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |
|
||
| `--fallback-model <model>` | Enable automatic fallback to a specified model when the default is overloaded (note: only works with `--print` per help). | `claude -p --fallback-model claude-haiku-20240307 "query"` |
|
||
| `--model <model>` | Model for the current session. Accepts aliases like `sonnet`/`opus` or a full model name (e.g. `claude-sonnet-4-20250514`). | `claude --model sonnet` |
|
||
| `--settings <file-or-json>` | Load additional settings from a JSON file or a JSON string. | `claude --settings ./settings.json` |
|
||
| `--add-dir <directories...>` | Additional directories to allow tool access to. | `claude --add-dir ../apps ../lib` |
|
||
| `--ide` | Automatically connect to an IDE on startup if exactly one valid IDE is available. | `claude --ide` |
|
||
| `-c, --continue` | Continue the most recent conversation in the current directory. | `claude --continue` |
|
||
| `-r, --resume [sessionId]` | Resume a conversation; provide a session ID or interactively select one. | `claude -r "abc123"` |
|
||
| `--session-id <uuid>` | Use a specific session ID for the conversation (must be a valid UUID). | `claude --session-id 123e4567-e89b-12d3-a456-426614174000` |
|
||
| `--dangerously-skip-permissions` | Bypass all permission checks (only for trusted sandboxes). | `claude --dangerously-skip-permissions` |
|
||
| `-v, --version` | Show the installed `claude` CLI version. | `claude --version` |
|
||
| `-h, --help` | Display help / usage. | `claude --help` |
|
||
|
||
|
||
> The `--output-format json` flag is particularly useful for scripting and automation, allowing you to parse Claude's responses programmatically.
|
||
|
||
<h2 id="cheat-sheet">Cheat Sheet</h2>
|
||
|
||
```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 "<session-id>" "finish this" # Resume specific session by ID (alias for --resume)
|
||
claude --model claude-sonnet-4-20250514# Pick model for this run
|
||
claude --max-turns 3 -p "lint this" # Cap agentic turns in print mode
|
||
claude --replay-user-messages # Replay user messages to stdout for debugging / SDK workflows
|
||
|
||
# Update & install
|
||
claude update # Manually update Claude Code
|
||
claude doctor # Diagnose install/version & setup
|
||
claude install # Start native binary installer (beta)
|
||
claude migrate-installer # Migrate from global npm to local installer
|
||
|
||
# Config: interactive wizard + direct ops
|
||
claude config # Interactive config wizard
|
||
claude config get <key> # Get value (e.g., claude config get theme)
|
||
claude config set <key> <val> # Set value (e.g., claude config set theme dark)
|
||
claude config add <key> <vals…> # Append to array-type keys (e.g., claude config add env DEV=1)
|
||
claude config remove <key> <vals…> # Remove items from list-type keys
|
||
claude config list # Show all current settings for project (project scope is default)
|
||
|
||
# Example project-scoped settings
|
||
claude config set model "claude-3-5-sonnet-20241022" # Override default model for this project
|
||
claude config set includeCoAuthoredBy false # Disable "co-authored-by Claude" byline in git/PRs
|
||
claude config set forceLoginMethod claudeai # Restrict login flow: claudeai | console
|
||
claude config set enableAllProjectMcpServers true # Auto-approve all MCP servers from .mcp.json
|
||
claude config set defaultMode "acceptEdits" # Set default permission mode
|
||
claude config set disableBypassPermissionsMode disable # Prevent bypassPermissions mode (example key)
|
||
|
||
# Manage list settings (project scope)
|
||
claude config add enabledMcpjsonServers github # Approve a specific MCP server from .mcp.json
|
||
claude config add enabledMcpjsonServers memory # Add another
|
||
claude config remove enabledMcpjsonServers memory # Remove one entry
|
||
claude config add disabledMcpjsonServers filesystem # Explicitly reject a specific MCP server
|
||
|
||
# Global scope (use -g or --global)
|
||
claude config set -g autoUpdates false # Turn off automatic updates globally
|
||
claude config set --global preferredNotifChannel iterm2_with_bell
|
||
claude config set -g theme dark # Theme: dark | light | light-daltonized | dark-daltonized
|
||
claude config set -g verbose true # Show full bash/command outputs everywhere
|
||
claude config get -g theme # Confirm a global value
|
||
|
||
# MCP (Model Context Protocol) management
|
||
claude mcp # Launch MCP wizard / configure MCP servers
|
||
claude mcp list # List configured MCP servers
|
||
claude mcp get <name> # Show details for a server
|
||
claude mcp remove <name> # Remove a server
|
||
claude mcp add <name> <command> [args...] # Add local stdio server
|
||
claude mcp add --transport sse <name> <url> # Add remote SSE server
|
||
claude mcp add --transport http <name> <url> # Add remote HTTP server
|
||
claude mcp add <name> --env KEY=VALUE -- <cmd> [args...] # Pass env to server command
|
||
claude mcp add --transport sse private-api https://api.example/mcp \
|
||
--header "Authorization: Bearer TOKEN" # Add with auth header
|
||
claude mcp add-json <name> '<json>' # Add server via JSON blob
|
||
claude mcp add-from-claude-desktop # Import servers from Claude Desktop
|
||
claude mcp reset-project-choices # Reset approvals for project .mcp.json servers
|
||
claude mcp serve # Run Claude Code itself as an MCP stdio server
|
||
|
||
# Other useful flags (print / SDK mode)
|
||
claude --add-dir ../apps ../lib # Add additional working directories
|
||
claude --allowedTools "Bash(git log:*)" "Read" # Allow listed tools without permission prompts
|
||
claude --disallowedTools "Edit" # Disallow listed tools without permission prompts
|
||
claude --append-system-prompt "Custom instruction" # Append to system prompt (only with -p)
|
||
claude -p "query" --output-format json --input-format stream-json # Control IO formats for scripting
|
||
claude --verbose # Verbose logging (turn-by-turn)
|
||
claude --dangerously-skip-permissions # Skip permission prompts (use with caution)
|
||
|
||
# Quick verification / notes
|
||
# - Project scope is default for 'claude config'; use -g/--global to affect all projects.
|
||
# - Settings precedence: Enterprise > CLI args > local project > shared project > user (~/.claude).
|
||
# - Use 'add' / 'remove' only with list-type keys (e.g., enabledMcpjsonServers).
|
||
# - The CLI reference and release notes are the authoritative sources for flags and recent additions.
|
||
```
|
||
|
||
---
|
||
|
||
<h1 id="interface--input">Interface & Input</h1>
|
||
|
||
<h2 id="keyboard-shortcuts">Keyboard Shortcuts</h2>
|
||
|
||
| Shortcut | Description | Context |
|
||
| :--------------- | :--------------------------------- | :------------------------- |
|
||
| `Ctrl+C` | Cancel current input or generation | Standard interrupt |
|
||
| `Ctrl+D` | Exit Claude Code session | EOF signal |
|
||
| `Ctrl+L` | Clear terminal screen | Keeps conversation history |
|
||
| `Up/Down arrows` | Navigate command history | Recall previous inputs |
|
||
| `Esc` + `Esc` | Edit previous message | Double-escape to modify |
|
||
|
||
<h3 id="multiline-input">Multiline Input</h3>
|
||
|
||
| 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 |
|
||
|
||
<h3 id="quick-commands">Quick Commands</h3>
|
||
|
||
| Shortcut | Description | Notes |
|
||
| :----------- | :--------------------------------- | :-------------------------------------------------------- |
|
||
| `#` at start | Memory shortcut add to CLAUDE.md | Prompts for file selection |
|
||
| `/` at start | Slash command |
|
||
|
||
<h2 id="vim-mode">Vim Mode</h2>
|
||
|
||
> [!Note]
|
||
> Enable vim-style editing with `/vim` command or configure permanently via `/config`.
|
||
|
||
<h3 id="vim-mode-switching">Vim Mode Switching</h3>
|
||
|
||
| 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 |
|
||
|
||
<h3 id="vim-navigation">Vim Navigation</h3>
|
||
|
||
| 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 |
|
||
|
||
<h3 id="vim-editing">Vim Editing</h3>
|
||
|
||
| 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 and VS Code terminals.
|
||
|
||
<h2 id="command-history">Command History</h2>
|
||
|
||
> 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
|
||
```
|
||
|
||
---
|
||
|
||
<h1 id="advanced-features">Advanced Features</h1>
|
||
|
||
<h2 id="thinking-keywords">Thinking Keywords</h2>
|
||
|
||
> [!Note]
|
||
> **Gives Claude extra pre-answer planning time by adding ONE of these keywords to your prompt.**
|
||
> **Order (lowest → highest) token consumption**
|
||
> <table><tr><td>
|
||
>
|
||
> > **<kbd>think</kbd> -------------> Lowest**
|
||
>
|
||
> > **<kbd>think hard</kbd>**
|
||
>
|
||
> > **<kbd>think harder</kbd>**
|
||
>
|
||
> > **<kbd>ultrathink</kbd> --------> Highest**
|
||
>
|
||
> </td></tr></table>
|
||
|
||
<h3 id="this-makes-claude-spend-more-time">This makes Claude spend more time:</h3>
|
||
|
||
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.
|
||
|
||
|
||
<h5 id="thinking-examples">Examples</h5>
|
||
|
||
```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."
|
||
```
|
||
|
||
<h2 id="sub-agents">Sub Agents</h2>
|
||
|
||
> 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.
|
||
|
||
**When to use them**
|
||
> - 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.
|
||
|
||
<h3 id="each-sub-agent-has-its-own-context">Each Sub‑Agent Has Its Own Context</h3>
|
||
|
||
**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.
|
||
|
||
<img width="700" height="160" alt="image" src="https://github.com/user-attachments/assets/42767417-20aa-4bd4-aaf2-cfa0e515b54b" />
|
||
|
||
*Caption: Agents selection UI in the terminal.*
|
||
|
||
<h3 id="configure-agents">Configure Agents</h3>
|
||
|
||
> Keep agents **in the project** so they're versioned with the repo and evolve via PRs.
|
||
|
||
<h3 id="agents-quick-start">Quick start</h3>
|
||
|
||
> Update CLI and open the agents panel
|
||
```bash
|
||
claude update
|
||
/agents
|
||
```
|
||
|
||
<h3 id="create-your-core-agents">Create your core agents</h3>
|
||
|
||
> - **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.*
|
||
|
||
<img width="700" height="173" alt="image" src="https://github.com/user-attachments/assets/84bc80de-35b8-4ef7-9b27-f74f7d4a51f9" />
|
||
|
||
*Caption: Choose only the tools an agent truly needs (e.g., advisory vs editing access).*
|
||
|
||
<h3 id="example-prompts">Example prompts</h3>
|
||
|
||
> Keep prompts short, testable, and repo‑specific. Check them into `agents/`:
|
||
|
||
<img width="700" height="217" alt="image" src="https://github.com/user-attachments/assets/b4f92591-ff5c-4775-aec2-051f145b9616" />
|
||
|
||
*Caption: Example prompt for a **test‑coverage‑analyzer** agent.*
|
||
|
||
**tester.prompt.md (sample)**
|
||
```
|
||
Role: Write a single, focused failing test for the specific scenario I describe.
|
||
Scope: Only create/modify tests under tests/. Do not change src/.
|
||
Output: A brief rationale + a unified diff or patch.
|
||
If the scenario is unclear, ask exactly one clarifying question.
|
||
```
|
||
|
||
<h3 id="expected-output">Expected output</h3>
|
||
|
||
> Your tester agent should produce a small diff or patch plus a short rationale:
|
||
|
||
<img width="700" height="273" alt="image" src="https://github.com/user-attachments/assets/839151ce-02c9-4283-a53b-9dd105802ada" />
|
||
|
||
*Caption: Example response from the **test‑coverage‑analyzer** agent.*
|
||
|
||
<h3 id="why-this-shift-matters">Why This Shift Matters</h3>
|
||
|
||
**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.
|
||
|
||
<h3 id="a-mindset-shift">A Mindset Shift</h3>
|
||
|
||
**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.
|
||
|
||
<h2 id="mcp-integration">MCP Integration</h2>
|
||
|
||
<h3 id="understanding-mcp-model-context-protocol">Understanding MCP (Model Context Protocol)</h3>
|
||
|
||
#### 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
|
||
```
|
||
|
||
<h3 id="mcp-setup--configuration">MCP Setup & Configuration</h3>
|
||
|
||
###### Basic MCP Commands
|
||
```bash
|
||
claude mcp # Interactive MCP configuration
|
||
claude mcp list # List configured servers
|
||
claude mcp add <name> <cmd> # Add new server
|
||
claude mcp remove <name> # Remove server
|
||
```
|
||
|
||
###### MCP Configuration File Location
|
||
```bash
|
||
~/.claude.json # Global File
|
||
`.mcp.json` # Project-scoped servers are stored in a File at your project's root directory
|
||
```
|
||
|
||
## Quick Start
|
||
> **If you're in a hurry, here's the fastest way to add:**
|
||
|
||
```bash
|
||
# Add file system access (most commonly used)
|
||
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Documents ~/Desktop
|
||
|
||
# Verify if successful
|
||
claude mcp list
|
||
```
|
||
> **Responce if it worked like it should:**
|
||
<img width="868" height="192" alt="image" src="https://github.com/user-attachments/assets/8e7b23c7-ccfb-49aa-9203-e37f07c2514e" />
|
||
</td></table>
|
||
|
||
## Additional Methods:
|
||
|
||
<table><td>
|
||
|
||
### 1. Command Line Addition
|
||
> **Claude Code provides simple command line tools to add MCP servers:**
|
||
|
||
```bash
|
||
# Basic syntax
|
||
claude mcp add <name> <command> [parameters...]
|
||
|
||
# Actual example: Add local file system access
|
||
claude mcp add my-filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/Documents
|
||
|
||
# Example with environment variables
|
||
claude mcp add api-server -e API_KEY=your-key-here -- /path/to/server
|
||
```
|
||
|
||
</td></table>
|
||
|
||
<table><td>
|
||
|
||
### 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**
|
||
|
||
</td></table>
|
||
<table><td>
|
||
|
||
### 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": {}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
</td></table>
|
||
|
||
## MCP Server Scope Detailed
|
||
|
||
Understanding scope is crucial to avoid "server not found" errors:
|
||
|
||
### 1. Local Scope (Default)
|
||
- Only available in current directory
|
||
- Configuration stored in the projects section of `~/.claude.json`
|
||
- Suitable for: Personal project-specific tools
|
||
|
||
### 2. User Scope (Global)
|
||
- Available in all projects
|
||
- Added using `-s user` flag
|
||
- Suitable for: Common tools like file systems, database clients
|
||
|
||
### 3. Project Scope (Team shared)
|
||
- Shared through `.mcp.json` file
|
||
- Added using `-s project` flag
|
||
- Suitable for: Team-shared project-specific tools
|
||
|
||
## Practical MCP Server Recommendations
|
||
> **Here's the most worthwhile MCP server list to install:**
|
||
|
||
### 1. File System Access
|
||
```bash
|
||
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Documents ~/Projects ~/Desktop
|
||
```
|
||
Use: Let Claude directly read and write files, modify code
|
||
|
||
### 2. GitHub Integration
|
||
```bash
|
||
claude mcp add github -s user -e GITHUB_TOKEN=your-token -- npx -y @modelcontextprotocol/server-github
|
||
```
|
||
Use: Manage issues, PRs, code reviews
|
||
|
||
### 3. Web Browser Control
|
||
```bash
|
||
claude mcp add puppeteer -s user -- npx -y @modelcontextprotocol/server-puppeteer
|
||
```
|
||
Use: Automated web operations, crawling, testing
|
||
|
||
### 4. Database Connection (PostgreSQL)
|
||
```bash
|
||
claude mcp add postgres -s user -e DATABASE_URL=your-db-url -- npx -y @modelcontextprotocol/server-postgres
|
||
```
|
||
Use: Directly query and manipulate databases
|
||
|
||
### 5. Fetch Tool (API Calls)
|
||
```bash
|
||
claude mcp add fetch -s user -- npx -y @kazuph/mcp-fetch
|
||
```
|
||
Use: Call various REST APIs
|
||
|
||
### 6. Search Engine
|
||
```bash
|
||
claude mcp add search -s user -e BRAVE_API_KEY=your-key -- npx -y @modelcontextprotocol/server-brave-search
|
||
```
|
||
Use: Search for latest information
|
||
|
||
### 7. Slack Integration
|
||
```bash
|
||
claude mcp add slack -s user -e SLACK_TOKEN=your-token -- npx -y @modelcontextprotocol/server-slack
|
||
```
|
||
Use: Send messages, manage channels
|
||
|
||
### 8. Time Management
|
||
```bash
|
||
claude mcp add time -s user -- npx -y @modelcontextprotocol/server-time
|
||
```
|
||
Use: Time zone conversion, date calculation
|
||
|
||
### 9. Memory Storage
|
||
```bash
|
||
claude mcp add memory -s user -- npx -y @modelcontextprotocol/server-memory
|
||
```
|
||
Use: Save information across conversations
|
||
|
||
### 10. Sequential Thinking (Thought Chain)
|
||
```bash
|
||
claude mcp add thinking -s user -- npx -y @modelcontextprotocol/server-sequential-thinking
|
||
```
|
||
Use: Step-by-step thinking for complex problems
|
||
|
||
## Common Errors and Solutions
|
||
|
||
### Error 1: Tool Name Validation Failed
|
||
```
|
||
API Error 400: "tools.11.custom.name: String should match pattern '^[a-zA-Z0-9_-]{1,64}$'"
|
||
```
|
||
|
||
**Solution**:
|
||
- Ensure server name only contains letters, numbers, underscores and hyphens
|
||
- Name length should not exceed 64 characters
|
||
- Don't use special characters or spaces
|
||
|
||
### Error 2: MCP Server Not Found
|
||
```
|
||
MCP server 'my-server' not found
|
||
```
|
||
|
||
**Solution**:
|
||
1. Check if scope settings are correct
|
||
2. Run `claude mcp list` to confirm server has been added
|
||
3. Ensure you're in the correct directory (for local scope)
|
||
4. Restart Claude Code
|
||
|
||
### Error 3: Protocol Version Error
|
||
```
|
||
"protocolVersion": "Required"
|
||
```
|
||
|
||
**Solution**: This is a known bug in Claude Code, temporary solutions:
|
||
1. Use wrapper scripts
|
||
2. Ensure MCP server returns correct protocol version
|
||
3. Update to latest version of Claude Code
|
||
|
||
### Error 4: Windows Path Issues
|
||
```
|
||
Error: Cannot find module 'C:UsersusernameDocuments'
|
||
```
|
||
|
||
**Solution**: Windows paths need to use forward slashes or double backslashes:
|
||
|
||
```bash
|
||
# Wrong
|
||
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem C:\Users\username\Documents
|
||
|
||
# Correct
|
||
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem C:/Users/username/Documents
|
||
# or
|
||
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem C:\\Users\\username\\Documents
|
||
```
|
||
|
||
### Error 5: Permission Issues
|
||
```
|
||
Permission denied
|
||
```
|
||
|
||
**Solution**:
|
||
1. macOS/Linux: Use `sudo` (not recommended) or modify file permissions
|
||
2. Windows: Run as administrator
|
||
3. Best method: Install MCP servers in user directory
|
||
|
||
## Debugging Techniques
|
||
|
||
When encountering problems, these debugging methods can help you quickly locate issues:
|
||
|
||
### 1. Enable Debug Mode
|
||
```bash
|
||
claude --mcp-debug
|
||
```
|
||
|
||
### 2. View MCP Status
|
||
In Claude Code, enter:
|
||
```
|
||
/mcp
|
||
```
|
||
|
||
### 3. View Log Files
|
||
|
||
**macOS/Linux:**
|
||
```bash
|
||
tail -f ~/Library/Logs/Claude/mcp*.log
|
||
```
|
||
|
||
**Windows:**
|
||
```cmd
|
||
type "%APPDATA%\Claude\logs\mcp*.log"
|
||
```
|
||
|
||
### 4. Manually Test Server
|
||
```bash
|
||
# Directly run server command to see if there's output
|
||
npx -y @modelcontextprotocol/server-filesystem ~/Documents
|
||
```
|
||
|
||
## Special Notes for International Users
|
||
|
||
### 1. Non-English Path Issues
|
||
Avoid using non-English characters in paths:
|
||
|
||
```bash
|
||
# Avoid
|
||
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem ~/文档
|
||
|
||
# Recommended
|
||
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem ~/Documents
|
||
```
|
||
|
||
### 2. Proxy Configuration
|
||
If you're using a proxy:
|
||
|
||
```bash
|
||
# Set npm proxy
|
||
npm config set proxy http://your-proxy:port
|
||
npm config set https-proxy http://your-proxy:port
|
||
|
||
# Then add MCP server
|
||
claude mcp add ...
|
||
```
|
||
|
||
### 3. Mirror Sources
|
||
Use mirror sources to accelerate downloads:
|
||
|
||
```bash
|
||
# Temporary use
|
||
claude mcp add fs -- npx -y --registry=https://registry.npmjs.org @modelcontextprotocol/server-filesystem ~/Documents
|
||
|
||
# Or permanent setting
|
||
npm config set registry https://registry.npmjs.org
|
||
```
|
||
|
||
## Best Practice Recommendations
|
||
|
||
1. **Add as needed**: Don't add too many MCP servers at once, it will affect performance
|
||
2. **Regular cleanup**: Use `claude mcp remove <name>` to delete unused servers
|
||
3. **Security first**: Only add trusted MCP servers, especially those requiring network access
|
||
4. **Backup configuration**: Regularly backup `~/.claude.json` file
|
||
5. **Team collaboration**: Use project scope to share common configurations
|
||
|
||
## Advanced Techniques
|
||
|
||
### 1. Create Custom MCP Server
|
||
|
||
If existing MCP servers can't meet your needs, you can create your own:
|
||
|
||
```javascript
|
||
// my-mcp-server.js
|
||
import { Server } from '@modelcontextprotocol/sdk';
|
||
|
||
const server = new Server({
|
||
name: 'my-custom-server',
|
||
version: '1.0.0',
|
||
});
|
||
|
||
server.setRequestHandler('tools/list', async () => {
|
||
return {
|
||
tools: [{
|
||
name: 'my_custom_tool',
|
||
description: 'Custom tool',
|
||
inputSchema: {
|
||
type: 'object',
|
||
properties: {
|
||
input: { type: 'string' }
|
||
}
|
||
}
|
||
}]
|
||
};
|
||
});
|
||
|
||
server.start();
|
||
```
|
||
|
||
### 2. Batch Configuration Script
|
||
|
||
Create a script to configure all common MCP servers at once:
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
# setup-mcp.sh
|
||
|
||
echo "Configuring common MCP servers..."
|
||
|
||
# File system
|
||
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Documents ~/Projects
|
||
|
||
# GitHub
|
||
read -p "Enter GitHub Token: " github_token
|
||
claude mcp add github -s user -e GITHUB_TOKEN=$github_token -- npx -y @modelcontextprotocol/server-github
|
||
|
||
# Other servers...
|
||
|
||
echo "MCP servers configured successfully!"
|
||
```
|
||
|
||
|
||
<h3 id="popular-mcp-servers">Popular MCP Servers</h3>
|
||
|
||
#### 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__*"
|
||
```
|
||
|
||
<h2 id="hooks-system">Hooks System</h2>
|
||
|
||
> 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).
|
||
</Tip>
|
||
|
||
<h3 id="hooks-configuration">Configuration</h3>
|
||
|
||
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"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
* **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`: Currently only `"command"` is supported
|
||
* `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"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
<h3 id="hook-events">Hook Events</h3>
|
||
|
||
#### 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.
|
||
|
||
#### 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`
|
||
|
||
<h3 id="hook-input">Hook Input</h3>
|
||
|
||
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
|
||
}
|
||
```
|
||
|
||
#### 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"
|
||
}
|
||
```
|
||
|
||
<h3 id="hook-output">Hook Output</h3>
|
||
|
||
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.
|
||
</Warning>
|
||
|
||
##### 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
|
||
</Note>
|
||
|
||
```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)
|
||
```
|
||
|
||
<h3 id="working-with-mcp-tools">Working with MCP Tools</h3>
|
||
|
||
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__<server>__<tool>`, for example:
|
||
|
||
* `mcp__memory__create_entities` - Memory server's create entities tool
|
||
* `mcp__filesystem__read_file` - Filesystem server's read file tool
|
||
* `mcp__github__search_repositories` - GitHub server's search tool
|
||
|
||
#### Configuring Hooks for MCP Tools
|
||
|
||
You can target specific MCP tools or entire MCP servers:
|
||
|
||
```json
|
||
{
|
||
"hooks": {
|
||
"PreToolUse": [
|
||
{
|
||
"matcher": "mcp__memory__.*",
|
||
"hooks": [
|
||
{
|
||
"type": "command",
|
||
"command": "echo 'Memory operation initiated' >> ~/mcp-operations.log"
|
||
}
|
||
]
|
||
},
|
||
{
|
||
"matcher": "mcp__.*__write.*",
|
||
"hooks": [
|
||
{
|
||
"type": "command",
|
||
"command": "/home/user/scripts/validate-mcp-write.py"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
<h3 id="hooks-examples">Examples</h3>
|
||
|
||
<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.
|
||
</Tip>
|
||
|
||
<h3 id="security-considerations">Security Considerations</h3>
|
||
|
||
#### 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.
|
||
|
||
##<h2 id="security-best-practices-main">Security Best Practices</h2>
|
||
|
||
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.
|
||
|
||
<h3 id="hook-execution-details">Hook Execution Details</h3>
|
||
|
||
* **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`)
|
||
|
||
<h3 id="hooks-debugging">Debugging</h3>
|
||
|
||
#### 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: <Your command> with timeout 60000ms
|
||
[DEBUG] Hook command completed with status 0: <Your stdout>
|
||
```
|
||
|
||
Progress messages appear in transcript mode (Ctrl-R) showing:
|
||
|
||
* Which hook is running
|
||
* Command being executed
|
||
* Success/failure status
|
||
* Output or error messages
|
||
|
||
---
|
||
|
||
<h1 id="security--permissions">Security & Permissions</h1>
|
||
|
||
#### 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:*)"
|
||
```
|
||
|
||
<h3 id="dangerous-mode">Dangerous Mode</h3>
|
||
|
||
> [!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`
|
||
|
||
<h2 id="security-best-practices-main">Security Best Practices</h2>
|
||
|
||
<h3 id="start-restrictive">Start Restrictive</h3>
|
||
|
||
<h3 id="protect-sensitive-data">Protect Sensitive Data</h3>
|
||
|
||
- **Keep `~/.claude.json` private (`chmod 600`).**
|
||
- **Prefer environment variables for API keys over plain‑text.**
|
||
- Use `--strict-mcp-config` to only load MCP servers from specified config files
|
||
|
||
<h1 id="automation--integration">Automation & Integration</h1>
|
||
|
||
<h2 id="automation--scripting-with-claude-code">Automation & Scripting with Claude Code</h2>
|
||
|
||
> 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.
|
||
|
||
<h2 id="auto-pr-review-inline-comments">Auto PR Review (inline comments)</h2>
|
||
|
||
> **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
|
||
```
|
||
|
||
<h2 id="security-review-on-every-pr">Security Review on Every PR</h2>
|
||
|
||
> **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-3-5-sonnet-20240620"
|
||
```
|
||
|
||
<h2 id="issue-triage-suggest-labels--severity">Issue Triage (suggest labels & severity)</h2>
|
||
|
||
> **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-3-5-sonnet-20240620
|
||
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-3-5-sonnet-20240620`) 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.
|
||
|
||
|
||
---
|
||
|
||
<h1 id="help--troubleshooting">Help & Troubleshooting</h1>
|
||
|
||
> [!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 <mark>must</mark> open a <mark>new</mark> terminal window.**
|
||
|
||
<table><td>
|
||
|
||
<h2 id="debug-quick-commands">Debug Quick Commands</h2>
|
||
|
||
*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
|
||
> ```
|
||
|
||
|
||
|
||
|
||
|
||
|
||
</td></table>
|
||
|
||
<table><td>
|
||
|
||
<h2 id="linuxpath">Path Temp Fix</h2>
|
||
|
||
**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 --debugg
|
||
> ```
|
||
> #### Windows (PowerShell):
|
||
> ```powershell
|
||
> $env:Path = "$env:USERPROFILE\AppData\Roaming\npm;C:\Program Files\nodejs;$env:Path"
|
||
> where claude
|
||
> claude --debugg
|
||
> ```
|
||
> #### Linux/MacOS (bash/zsh)
|
||
> ```bash
|
||
> export PATH="$(npm config get prefix)/bin:$HOME/.local/bin:$PATH"
|
||
> which claude
|
||
> claude doctor
|
||
> ```
|
||
|
||
|
||
|
||
|
||
|
||
|
||
</td></table>
|
||
|
||
|
||
<table><td>
|
||
|
||
<h2 id="windowspath">Windows Path Perm Fix</h2>
|
||
|
||
**Replace `<you>` with your own Windows username (without the angle brackets)**
|
||
|
||
- **Start → type: <kbd>Environment Variables</kbd>**
|
||
- **Open <kbd>Edit the system environment variables</kbd> → <kbd>Environment Variables</kbd>**
|
||
- **Under <kbd>User variables for</kbd> <mark><you></mark> select `Path` → `Edit` → `New` add:**
|
||
|
||
```path
|
||
C:\Users\<you>\AppData\Roaming\npm
|
||
C:\Program Files\nodejs</kbd>
|
||
```
|
||
> **Optional locations to add:**
|
||
```path
|
||
C:\Users\<you>\.claude\local\bin
|
||
C:\Users\<you>\.local\bin
|
||
```
|
||
- **Remove duplicates, any entry containing `%PATH%`, and stray quotes (`"`). Click `OK`.**
|
||
- **Open a `new` Command Prompt/PowerShell and verify:**
|
||
```C
|
||
where claude
|
||
claude doctor
|
||
```
|
||
|
||
> [!Tip]
|
||
> ### Optional Run directly (when PATH is broken)
|
||
>
|
||
> > **Windows (PowerShell/cmd)**
|
||
> ```powershell
|
||
> "%USERPROFILE%\AppData\Roaming\npm\claude.cmd" --version
|
||
> "%USERPROFILE%\AppData\Roaming\npm\claude.cmd" doctor
|
||
> ```
|
||
> > **Or via npx:**
|
||
> ```
|
||
> npx claude doctor
|
||
> ```
|
||
|
||
|
||
|
||
|
||
|
||
|
||
</td></table>
|
||
|
||
<table><td>
|
||
|
||
<h3 id="installation--nodejs-issues">Installation / Node.js Issues</h3>
|
||
|
||
**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
|
||
```
|
||
|
||
</td></table>
|
||
|
||
<table><td>
|
||
|
||
<h3 id="authentication-issues">Authentication Issues</h3>
|
||
> *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.*
|
||
|
||
</td></table>
|
||
|
||
<table><td>
|
||
|
||
<h3 id="permission--allowed-tools-issues">Permission / Allowed Tools Issues</h3>
|
||
|
||
**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"]'
|
||
```
|
||
|
||
</td></table>
|
||
|
||
<table><td>
|
||
|
||
<h3 id="mcp-model-context-protocol-issues">MCP (Model Context Protocol) Issues</h3>
|
||
|
||
> **Debug MCP servers**
|
||
```bash
|
||
claude --mcp-debug
|
||
```
|
||
> **List & remove MCP servers**
|
||
```bash
|
||
claude mcp list
|
||
claude mcp remove <server-name>
|
||
```
|
||
|
||
</td></table>
|
||
|
||
<table><td>
|
||
|
||
<h2 id="full-clean-reinstall-windows--powershell">Full Clean Reinstall (Windows / PowerShell)</h2>
|
||
|
||
> [!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
|
||
```
|
||
|
||
|
||
</td></table>
|
||
|
||
<table><td>
|
||
|
||
<h2 id="one-shot-health-check-copypaste">One‑Shot Health Check (copy/paste)</h2>
|
||
|
||
**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
|
||
```
|
||
|
||
|
||
|
||
</td></table>
|
||
|
||
---
|
||
|
||
<table><td>
|
||
|
||
<h2 id="appendix-useful-paths">Appendix: Useful Paths</h2>
|
||
|
||
- **Windows npm global bin:** `C:\Users\<you>\AppData\Roaming\npm`
|
||
- **Windows Node.js:** `C:\Program Files\nodejs`
|
||
- **Claude local data (Win):** `C:\Users\<you>\.claude\`
|
||
- **Claude config (Win):** `C:\Users\<you>\.claude.json`
|
||
- **macOS/Linux npm global bin:** `$(npm config get prefix)/bin` (often `/usr/local/bin` or `$HOME/.npm-global/bin`)
|
||
|
||
|
||
|
||
</td></table>
|
||
|
||
|
||
## Best Practices
|
||
|
||
> Curated guidance for safe, fast, and correct use of the Claude Code CLI and interactive REPL. All commands and flags here match the current Anthropic docs as of **Aug 23, 2025**.
|
||
|
||
<h2 id="effective-prompting">Effective Prompting</h2>
|
||
|
||
```bash
|
||
# Good: Specific and detailed
|
||
claude "Review UserAuth.js for security vulnerabilities, focusing on JWT handling"
|
||
|
||
# Bad: Vague
|
||
claude "check my code"
|
||
```
|
||
|
||
Tip: `claude "query"` starts the interactive REPL pre-seeded with your prompt; `claude -p "query"` runs **print mode** (non‑interactive) and exits.
|
||
|
||
---
|
||
|
||
<h2 id="security-best-practices-main">Security Best Practices</h2>
|
||
|
||
1. **Start with minimal permissions**
|
||
- Prefer explicit allows and denies, either on the CLI or in settings files.
|
||
```bash
|
||
# Allow only what you need for this run
|
||
claude --allowedTools "Read" "Grep" "LS" "Bash(npm run test:*)"
|
||
```
|
||
Or commit a project policy at `.claude/settings.json`:
|
||
```json
|
||
{
|
||
"permissions": {
|
||
"allow": ["Read", "Grep", "LS", "Bash(npm run test:*)"],
|
||
"deny": ["WebFetch", "Bash(curl:*)", "Read(./.env)", "Read(./secrets/**)"]
|
||
}
|
||
}
|
||
```
|
||
|
||
2. **Handle secrets correctly**
|
||
- Use environment variables for SDK/automation flows:
|
||
```bash
|
||
export ANTHROPIC_API_KEY="your_key" # for SDK/print mode
|
||
```
|
||
- In the interactive REPL, prefer `/login` instead of hard‑coding tokens.
|
||
- Deny access to sensitive files in settings (replaces older `ignorePatterns`):
|
||
```json
|
||
{ "permissions": { "deny": ["Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)"] } }
|
||
```
|
||
|
||
3. **Audit permissions regularly**
|
||
```bash
|
||
# Project settings
|
||
claude config list
|
||
claude config get permissions.allow
|
||
claude config get permissions.deny
|
||
|
||
# Global settings
|
||
claude config list -g
|
||
```
|
||
|
||
4. **Avoid bypass modes in production**
|
||
- Do **not** use `--dangerously-skip-permissions` outside isolated/dev sandboxes.
|
||
- For unattended runs, combine narrow `--allowedTools` with `--disallowedTools` and project settings.
|
||
|
||
---
|
||
|
||
<h2 id="performance-tips">Performance Tips</h2>
|
||
|
||
1. **Use machine‑readable output in automations**
|
||
```bash
|
||
claude -p "summarize this error log" --output-format json
|
||
# valid: text | json | stream-json
|
||
```
|
||
|
||
2. **Bound non‑interactive work**
|
||
```bash
|
||
claude -p "run type checks and summarize failures" --max-turns 3
|
||
# optionally also bound thinking:
|
||
export MAX_THINKING_TOKENS=20000
|
||
```
|
||
|
||
3. **Keep sessions tidy**
|
||
```bash
|
||
# Retain recent sessions only (default is 30 days)
|
||
claude config set -g cleanupPeriodDays 20
|
||
```
|
||
|
||
4. **Limit context scope**
|
||
```bash
|
||
# Grant access only to relevant paths to reduce scanning/noise
|
||
claude --add-dir ./services/api ./packages/ui
|
||
```
|
||
|
||
5. **Pick the right model**
|
||
- CLI aliases: `--model sonnet` or `--model opus` (latest of that family).
|
||
- For reproducibility in settings, pin a full model ID (e.g., `"claude-3-5-sonnet-20241022"`).
|
||
|
||
---
|
||
|
||
<h2 id="monitoring--alerting">Monitoring & Alerting</h2>
|
||
|
||
**1) Health checks**
|
||
Use the built‑in **doctor** command to verify installation and environment.
|
||
```bash
|
||
# Every 15 minutes
|
||
*/15 * * * * /usr/local/bin/claude doctor >/dev/null 2>&1 || \
|
||
mail -s "Claude Code doctor failed" admin@company.com </dev/null
|
||
```
|
||
|
||
**2) Log analysis batch job**
|
||
```bash
|
||
# Daily analysis with non-interactive JSON output (print mode)
|
||
0 6 * * * tail -1000 /var/log/app.log | \
|
||
claude -p "Analyze errors, regressions, and suspect patterns; output JSON." \
|
||
--output-format json > /tmp/daily-analysis.json
|
||
```
|
||
|
||
**3) Telemetry (optional)**
|
||
Claude Code emits OpenTelemetry metrics/events. Set exporters in settings/env (e.g., OTLP) and ship to your observability stack (Datadog, Honeycomb, Prometheus/Grafana, etc.).
|
||
|
||
---
|
||
|
||
<h2 id="collaboration-best-practices">Collaboration Best Practices</h2>
|
||
|
||
<h3 id="team-workflows">Team Workflows</h3>
|
||
|
||
**1) Share versioned configuration**
|
||
```jsonc
|
||
// .claude/settings.json (checked into the repo)
|
||
{
|
||
"permissions": {
|
||
"allow": ["Read", "Grep", "LS", "Bash(npm run lint)", "Bash(npm run test:*)"],
|
||
"deny": ["WebFetch", "Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)"]
|
||
},
|
||
// Pin a model here for reproducibility if desired, using a full model ID:
|
||
"model": "claude-3-5-sonnet-20241022"
|
||
}
|
||
```
|
||
|
||
**2) Documentation automation**
|
||
```bash
|
||
# Update docs with explicit tasks
|
||
claude "Update README.md to reflect the latest API endpoints and examples."
|
||
claude "Generate TypeScript types from schema.prisma and write to /types."
|
||
```
|
||
|
||
**3) Code review standards**
|
||
```bash
|
||
# Review a local diff with constrained tools
|
||
git fetch origin main
|
||
git diff origin/main...HEAD > /tmp/diff.patch
|
||
claude --allowedTools "Read" "Grep" "Bash(git:*)" \
|
||
"Review /tmp/diff.patch using team standards:
|
||
- Security best practices
|
||
- Performance considerations
|
||
- Code style compliance
|
||
- Test coverage adequacy"
|
||
```
|
||
|
||
<h3 id="knowledge-sharing">Knowledge Sharing</h3>
|
||
|
||
**1) Project runbooks**
|
||
```bash
|
||
claude "Create a deployment runbook for this app: steps, checks, rollback."
|
||
claude "Document onboarding for new developers: setup, commands, conventions."
|
||
```
|
||
|
||
**2) Architecture docs**
|
||
```bash
|
||
claude "Update architecture docs to reflect new microservices."
|
||
claude "Create sequence diagrams for the authentication flow."
|
||
```
|
||
|
||
> Tip: Keep durable context in **CLAUDE.md** at the project root. In the REPL, use `/memory` to manage it and `@path` to import file content into prompts.
|
||
|
||
---
|
||
|
||
<h2 id="common-pitfalls-to-avoid">Common Pitfalls to Avoid</h2>
|
||
|
||
<h3 id="security-pitfalls">Security</h3>
|
||
|
||
**❌ Don’t**
|
||
- Use `--dangerously-skip-permissions` on production systems
|
||
- Hard‑code secrets in commands/config
|
||
- Grant overly broad permissions (e.g., `Bash(*)`)
|
||
- Run with elevated privileges unnecessarily
|
||
|
||
**✅ Do**
|
||
- Store secrets in env vars and credential helpers
|
||
- Start from minimal `permissions.allow` and expand gradually
|
||
- Audit with `claude config list` / `claude config get`
|
||
- Isolate risky operations in containers/VMs
|
||
|
||
<h3 id="performance-pitfalls">Performance</h3>
|
||
|
||
**❌ Don’t**
|
||
- Load an entire monorepo when you only need a package
|
||
- Max out thinking/turn budgets for simple tasks
|
||
- Ignore session cleanup
|
||
|
||
**✅ Do**
|
||
- Use `--add-dir` for focused context
|
||
- Right‑size with `--max-turns` and `MAX_THINKING_TOKENS`
|
||
- Set `cleanupPeriodDays` to prune old sessions
|
||
|
||
<h3 id="workflow-pitfalls">Workflow</h3>
|
||
|
||
**❌ Don’t**
|
||
- Skip project context (`CLAUDE.md`)
|
||
- Use vague prompts
|
||
- Ignore errors/logs
|
||
- Automate without testing
|
||
|
||
**✅ Do**
|
||
- Maintain and update `CLAUDE.md`
|
||
- Be specific and goal‑oriented in prompts
|
||
- Monitor via logs/OTel as appropriate
|
||
- Test automation in safe environments first
|
||
|
||
|
||
|
||
---
|
||
|
||
<h1 id="third-party-integrations">Third-Party Integrations</h1>
|
||
|
||
<h2 id="deepseek-integration">DeepSeek Integration</h2>
|
||
|
||
1. ###### Have claude Code installed
|
||
```
|
||
npm install -g @anthropic-ai/claude-code
|
||
```
|
||
|
||
2. ###### Config Environment Variables
|
||
```bash
|
||
export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
|
||
export ANTHROPIC_AUTH_TOKEN=${YOUR_API_KEY}
|
||
export ANTHROPIC_MODEL=deepseek-chat
|
||
export ANTHROPIC_SMALL_FAST_MODEL=deepseek-chat
|
||
```
|
||
|
||
3. ###### Now all you need to do is launch `claude`
|
||
|
||
Find more information from the [Official Deepseek Docs](https://api-docs.deepseek.com/guides/anthropic_api)
|
||
|