| 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!
Quick links: Install · Commands · Shortcuts · MCP · Troubleshoot
Enable sound alerts when claude completes the task:
claude config set --global preferredNotifChannel terminal_bell
Tip
Send claude or npx claude in terminal to start the interface
Go to Help & Troubleshooting to fix issues...
# 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 latestMake sure you have the (Claude Code extension) installed in your VS Code / Cursor
- 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+
Tip
Find API key from Anthropic Console
Do NOT commit real keys use git-ignored files, OS key stores, or secret managers
# 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'
----------------------------------------------------------------------------------------------------------------------------------You can also set any of these in settings.json under the "env" key for automatic application.
Important
Windows Users replace export with set or setx for perm
# 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 AIclaude 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 serversImportant
Windows Users replace export with set
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)(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.mdLinux: /etc/claude-code/CLAUDE.mdWindows: 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.
| 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 |
| 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 jsonflag is particularly useful for scripting and automation, allowing you to parse Claude's responses programmatically.
## 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.| 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 |
| 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 |
| Shortcut | Description | Notes |
|---|---|---|
# at start |
Memory shortcut add to CLAUDE.md | Prompts for file selection |
/ at start |
Slash command |
Note
Enable vim-style editing with /vim command or configure permanently via /config.
| 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 |
| 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 |
| 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.
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
Note
Gives Claude extra pre-answer planning time by adding ONE of these keywords to your prompt. Order (lowest → highest) token consumption
|
- Planning the solution
# 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."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.
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.
Caption: Agents selection UI in the terminal.
Keep agents in the project so they're versioned with the repo and evolve via PRs.
Update CLI and open the agents panel
claude update
/agents
- planner (read‑only): turns features/issues into small, testable tasks; outputs a task list or plan.md.
- codegen (edit‑capable): implements tasks; limited to
src/+tests/.- tester (read‑only or patch‑only): writes one failing test or a minimal repro.
- reviewer (read‑only): leaves structured review comments; never edits.
- docs (edit‑capable): updates
README.md/docs/only.
Policy tip: Prefer patch output for edit‑capable agents so changes land through your normal Git workflow.
Caption: Choose only the tools an agent truly needs (e.g., advisory vs editing access).
Keep prompts short, testable, and repo‑specific. Check them into
agents/:
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.
Your tester agent should produce a small diff or patch plus a short rationale:
Caption: Example response from the test‑coverage‑analyzer agent.
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.
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.
MCP extends Claude's capabilities by connecting to external services, databases, APIs, and tools (filesystem, Puppeteer, GitHub, Context7 etc...)
Claude Code ←→ MCP Protocol ←→ MCP Servers ←→ External Services
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~/.claude.json # Global File
`.mcp.json` # Project-scoped servers are stored in a File at your project's root directoryIf you're in a hurry, here's the fastest way to add:
# 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 listResponce if it worked like it should:
# 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 |
1. Find configuration file location:
2. Edit configuration file: {
"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 |
# Add project-level MCP server
claude mcp add shared-tools -s project -- npx -y @your-team/mcp-toolsThis will create a {
"mcpServers": {
"shared-tools": {
"command": "npx",
"args": ["-y", "@your-team/mcp-tools"],
"env": {}
}
}
} |
Understanding scope is crucial to avoid "server not found" errors:
- Only available in current directory
- Configuration stored in the projects section of
~/.claude.json - Suitable for: Personal project-specific tools
- Available in all projects
- Added using
-s userflag - Suitable for: Common tools like file systems, database clients
- Shared through
.mcp.jsonfile - Added using
-s projectflag - Suitable for: Team-shared project-specific tools
Here's the most worthwhile MCP server list to install:
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Documents ~/Projects ~/DesktopUse: Let Claude directly read and write files, modify code
claude mcp add github -s user -e GITHUB_TOKEN=your-token -- npx -y @modelcontextprotocol/server-githubUse: Manage issues, PRs, code reviews
claude mcp add puppeteer -s user -- npx -y @modelcontextprotocol/server-puppeteerUse: Automated web operations, crawling, testing
claude mcp add postgres -s user -e DATABASE_URL=your-db-url -- npx -y @modelcontextprotocol/server-postgresUse: Directly query and manipulate databases
claude mcp add fetch -s user -- npx -y @kazuph/mcp-fetchUse: Call various REST APIs
claude mcp add search -s user -e BRAVE_API_KEY=your-key -- npx -y @modelcontextprotocol/server-brave-searchUse: Search for latest information
claude mcp add slack -s user -e SLACK_TOKEN=your-token -- npx -y @modelcontextprotocol/server-slackUse: Send messages, manage channels
claude mcp add time -s user -- npx -y @modelcontextprotocol/server-timeUse: Time zone conversion, date calculation
claude mcp add memory -s user -- npx -y @modelcontextprotocol/server-memoryUse: Save information across conversations
claude mcp add thinking -s user -- npx -y @modelcontextprotocol/server-sequential-thinkingUse: Step-by-step thinking for complex problems
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
MCP server 'my-server' not found
Solution:
- Check if scope settings are correct
- Run
claude mcp listto confirm server has been added - Ensure you're in the correct directory (for local scope)
- Restart Claude Code
"protocolVersion": "Required"
Solution: This is a known bug in Claude Code, temporary solutions:
- Use wrapper scripts
- Ensure MCP server returns correct protocol version
- Update to latest version of Claude Code
Error: Cannot find module 'C:UsersusernameDocuments'
Solution: Windows paths need to use forward slashes or double backslashes:
# 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\\DocumentsPermission denied
Solution:
- macOS/Linux: Use
sudo(not recommended) or modify file permissions - Windows: Run as administrator
- Best method: Install MCP servers in user directory
When encountering problems, these debugging methods can help you quickly locate issues:
claude --mcp-debugIn Claude Code, enter:
/mcp
macOS/Linux:
tail -f ~/Library/Logs/Claude/mcp*.logWindows:
type "%APPDATA%\Claude\logs\mcp*.log"# Directly run server command to see if there's output
npx -y @modelcontextprotocol/server-filesystem ~/DocumentsAvoid using non-English characters in paths:
# Avoid
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem ~/文档
# Recommended
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem ~/DocumentsIf you're using a proxy:
# 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 ...Use mirror sources to accelerate downloads:
# 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- Add as needed: Don't add too many MCP servers at once, it will affect performance
- Regular cleanup: Use
claude mcp remove <name>to delete unused servers - Security first: Only add trusted MCP servers, especially those requiring network access
- Backup configuration: Regularly backup
~/.claude.jsonfile - Team collaboration: Use project scope to share common configurations
If existing MCP servers can't meet your needs, you can create your own:
// 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();Create a script to configure all common MCP servers at once:
#!/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!"# npm install -g git-mcp-server
# claude mcp add git "git-mcp-server"
# claude mcp add github "github-mcp-server --token $GITHUB_TOKEN"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"# 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__*"For a quickstart guide with examples, see [Get started with Claude Code hooks](/en/docs/claude-code/hooks-guide).This page provides reference documentation for implementing hooks in Claude Code.
Claude Code hooks are configured in your settings files:
~/.claude/settings.json- User settings.claude/settings.json- Project settings.claude/settings.local.json- Local project settings (not committed)- Enterprise managed policy settings
Hooks are organized by matchers, where each matcher can have multiple hooks:
{
"hooks": {
"EventName": [
{
"matcher": "ToolPattern",
"hooks": [
{
"type": "command",
"command": "your-command-here"
}
]
}
]
}
}- matcher: Pattern to match tool names, case-sensitive (only applicable for
PreToolUseandPostToolUse)- Simple strings match exactly:
Writematches only the Write tool - Supports regex:
Edit|WriteorNotebook.* - Use
*to match all tools. You can also use empty string ("") or leavematcherblank.
- Simple strings match exactly:
- hooks: Array of commands to execute when the pattern matches
type: Currently only"command"is supportedcommand: The bash command to execute (can use$CLAUDE_PROJECT_DIRenvironment 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:
{
"hooks": {
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "/path/to/prompt-validator.py"
}
]
}
]
}
}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:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/check-style.sh"
}
]
}
]
}
}Runs after Claude creates tool parameters and before processing the tool call.
Common matchers:
Task- Subagent tasks (see subagents documentation)Bash- Shell commandsGlob- File pattern matchingGrep- Content searchRead- File readingEdit,MultiEdit- File editingWrite- File writingWebFetch,WebSearch- Web operations
Runs immediately after a tool completes successfully.
Recognizes the same matcher values as PreToolUse.
Runs when Claude Code sends notifications. Notifications are sent when:
- Claude needs your permission to use a tool. Example: "Claude needs your permission to use Bash"
- The prompt input has been idle for at least 60 seconds. "Claude is waiting for your input"
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.
Runs when the main Claude Code agent has finished responding. Does not run if the stoppage occurred due to a user interrupt.
Runs when a Claude Code subagent (Task tool call) has finished responding.
Runs before Claude Code is about to run a compact operation.
Matchers:
manual- Invoked from/compactauto- Invoked from auto-compact (due to full context window)
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 startupresume- Invoked from--resume,--continue, or/resumeclear- Invoked from/clear
Hooks receive JSON data via stdin containing session information and event-specific data:
{
// 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
...
}The exact schema for tool_input depends on the tool.
{
"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"
}
}The exact schema for tool_input and tool_response depends on the tool.
{
"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
}
}{
"session_id": "abc123",
"transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
"cwd": "/Users/...",
"hook_event_name": "Notification",
"message": "Task completed successfully"
}{
"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_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.
{
"session_id": "abc123",
"transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
"hook_event_name": "Stop",
"stop_hook_active": true
}For manual, custom_instructions comes from what the user passes into
/compact. For auto, custom_instructions is empty.
{
"session_id": "abc123",
"transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
"hook_event_name": "PreCompact",
"trigger": "manual",
"custom_instructions": ""
}{
"session_id": "abc123",
"transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
"hook_event_name": "SessionStart",
"source": "startup"
}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.
Hooks communicate status through exit codes, stdout, and stderr:
- Exit code 0: Success.
stdoutis shown to the user in transcript mode (CTRL-R), except forUserPromptSubmitandSessionStart, where stdout is added to the context. - Exit code 2: Blocking error.
stderris fed back to Claude to process automatically. See per-hook-event behavior below. - Other exit codes: Non-blocking error.
stderris shown to the user and execution continues.
| 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 |
Hooks can return structured JSON in stdout for more sophisticated control:
All hook types can include these optional fields:
{
"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
StopandSubagentStop, this takes precedence over any"decision": "block"output. - In all cases,
"continue" = falsetakes precedence over any"decision": "block"output.
stopReason accompanies continue with a reason shown to the user, not shown
to Claude.
PreToolUse hooks can control whether a tool call proceeds.
"allow"bypasses the permission system.permissionDecisionReasonis shown to the user but not to Claude. (Deprecated"approve"value +reasonhas the same behavior.)"deny"prevents the tool call from executing.permissionDecisionReasonis shown to Claude. ("block"value +reasonhas the same behavior.)"ask"asks the user to confirm the tool call in the UI.permissionDecisionReasonis shown to the user but not to Claude.
{
"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 hooks can control whether a tool call proceeds.
"block"automatically prompts Claude withreason.undefineddoes nothing.reasonis ignored.
{
"decision": "block" | undefined,
"reason": "Explanation for decision"
}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.undefinedallows the prompt to proceed normally."reason"is ignored."hookSpecificOutput.additionalContext"adds the string to the context if not blocked.
{
"decision": "block" | undefined,
"reason": "Explanation for decision",
"hookSpecificOutput": {
"hookEventName": "UserPromptSubmit",
"additionalContext": "My additional context here"
}
}Stop and SubagentStop hooks can control whether Claude must continue.
"block"prevents Claude from stopping. You must populatereasonfor Claude to know how to proceed.undefinedallows Claude to stop.reasonis ignored.
{
"decision": "block" | undefined,
"reason": "Must be provided when Claude is blocked from stopping"
}SessionStart hooks allow you to load in context at the start of a session.
"hookSpecificOutput.additionalContext"adds the string to the context.
{
"hookSpecificOutput": {
"hookEventName": "SessionStart",
"additionalContext": "My additional context here"
}
}#!/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)- Exit code 0 with stdout: Claude sees the context (special case for
UserPromptSubmit) - JSON output: Provides more control over the behavior
#!/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)#!/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)Claude Code hooks work seamlessly with Model Context Protocol (MCP) tools. When MCP servers provide tools, they appear with a special naming pattern that you can match in your hooks.
MCP tools follow the pattern mcp__<server>__<tool>, for example:
mcp__memory__create_entities- Memory server's create entities toolmcp__filesystem__read_file- Filesystem server's read file toolmcp__github__search_repositories- GitHub server's search tool
You can target specific MCP tools or entire MCP servers:
{
"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"
}
]
}
]
}
}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.
##
Here are some key practices for writing more secure hooks:
- Validate and sanitize inputs - Never trust input data blindly
- Always quote shell variables - Use
"$VAR"not$VAR - Block path traversal - Check for
..in file paths - Use absolute paths - Specify full paths for scripts (use
$CLAUDE_PROJECT_DIRfor the project path) - Skip sensitive files - Avoid
.env,.git/, keys, etc.
Direct edits to hooks in settings files don't take effect immediately. Claude Code:
- Captures a snapshot of hooks at startup
- Uses this snapshot throughout the session
- Warns if hooks are modified externally
- Requires review in
/hooksmenu for changes to apply
This prevents malicious hook modifications from affecting your current session.
- 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_DIRenvironment variable is available and contains the absolute path to the project root directory
- The
- Input: JSON via stdin
- Output:
- PreToolUse/PostToolUse/Stop: Progress shown in transcript (Ctrl-R)
- Notification: Logged to debug only (
--debug)
If your hooks aren't working:
- Check configuration - Run
/hooksto see if your hook is registered - Verify syntax - Ensure your JSON settings are valid
- Test commands - Run hook commands manually first
- Check permissions - Make sure scripts are executable
- Review logs - Use
claude --debugto 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
For complex hook issues:
- Inspect hook execution - Use
claude --debugto see detailed hook execution - Validate JSON schemas - Test hook input/output with external tools
- Check environment variables - Verify Claude Code's environment is correct
- Test edge cases - Try hooks with unusual file paths or inputs
- Monitor system resources - Check for resource exhaustion during hook execution
- Use structured logging - Implement logging in your hook scripts
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
# 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:*)"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
- Keep
~/.claude.jsonprivate (chmod 600). - Prefer environment variables for API keys over plain‑text.
- Use
--strict-mcp-configto only load MCP servers from specified config files
GitHub Actions you can copy/paste :p
- Install the Claude GitHub App on your org/repo (required for Actions to comment on PRs/issues).
- In your repo, add a secret
ANTHROPIC_API_KEYSettings → Secrets and variables → Actions → New repository secret - Copy the workflows below into
.github/workflows/. - 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.
Creates a structured review (with inline comments) as soon as a PR opens or updates.
File: .github/workflows/claude-pr-auto-review.yml
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_reviewRuns a focused security scan and comments findings directly on the PR.
File: .github/workflows/claude-security-review.yml
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"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
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.
- Model selection: set
CLAUDE_MODEL(e.g.,claude-3-5-sonnet-20240620) where shown. - Secrets:
ANTHROPIC_API_KEYis required. The built‑inGITHUB_TOKENis sufficient for posting comments and applying labels. - Permissions: each workflow declares the least privileges it needs (
pull-requests: writeand/orissues: write). Adjust only if your org requires stricter policies. - Scope: use
paths:filters on triggers to limit when workflows run (e.g., only for/srcor exclude/docs).
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: writepermission. - 403 when applying labels: Ensure the job or step has
issues: write. The defaultGITHUB_TOKENmust have access to this repo. - Anthropic API errors: Confirm
ANTHROPIC_API_KEYis set at repository (or org) level and not expired. - “YAML not well‑formed”: Validate spacing—two spaces per nesting level; no tabs.
Tip
Q:claude not found, but npx claude works?
A: Your
PATHis missing the npm global bin. See thePATHissue section forWindowsorLinux
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 doctorandclaude --verbosethe diagnostic window will point to log locations.
Q: Do I need to reboot after editing PATH?
A: No reboot required, but you must open a new terminal window.
|
Check the output of Note 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
|
|
Your PATH likely doesn’t include the global npm bin directory. Note set PATH=%USERPROFILE%\AppData\Roaming\npm;C:\Program Files\nodejs;%PATH%
where claude
claude --debugg$env:Path = "$env:USERPROFILE\AppData\Roaming\npm;C:\Program Files\nodejs;$env:Path"
where claude
claude --debuggexport PATH="$(npm config get prefix)/bin:$HOME/.local/bin:$PATH"
which claude
claude doctor
|
|
Replace
where claude
claude doctorTip
"%USERPROFILE%\AppData\Roaming\npm\claude.cmd" --version
"%USERPROFILE%\AppData\Roaming\npm\claude.cmd" doctor
|
|
Must be Node 18+ (20+ recommended) node --versionClean uninstall npm uninstall -g @anthropic-ai/claude-code Fresh install npm install -g @anthropic-ai/claude-code |
|
> *Verify your Anthropic API key is available to the CLI.*
PowerShell (Windows): echo $env:ANTHROPIC_API_KEY
claude -p "test" --verbosebash/zsh (macOS/Linux): echo $ANTHROPIC_API_KEY
claude -p "test" --verboseIf the variable is empty set it for your shell/profile or use your OS keychain/secrets manager. |
|
Inspect permissions claude config get allowedToolsReset permissions claude config set allowedTools "[]"Minimal safe set (example) claude config set allowedTools '["Edit","View"]' |
claude --mcp-debug
claude mcp list
claude mcp remove <server-name> |
|
Caution The following removes Claude Code binaries, caches, and config under your user profile
npm uninstall -g @anthropic-ai/claude-code
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
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
Remove-Item -LiteralPath "$env:USERPROFILE\.claude.json" -Force -ErrorAction SilentlyContinue
Remove-Item -LiteralPath "$env:USERPROFILE\.claude" -Recurse -Force -ErrorAction SilentlyContinue
npm install -g @anthropic-ai/claude-code |
|
Windows (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): 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
|
|
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.
# 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.
-
Start with minimal permissions
- Prefer explicit allows and denies, either on the CLI or in settings files.
# 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:{ "permissions": { "allow": ["Read", "Grep", "LS", "Bash(npm run test:*)"], "deny": ["WebFetch", "Bash(curl:*)", "Read(./.env)", "Read(./secrets/**)"] } } -
Handle secrets correctly
- Use environment variables for SDK/automation flows:
export ANTHROPIC_API_KEY="your_key" # for SDK/print mode
- In the interactive REPL, prefer
/logininstead of hard‑coding tokens. - Deny access to sensitive files in settings (replaces older
ignorePatterns):
{ "permissions": { "deny": ["Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)"] } } -
Audit permissions regularly
# Project settings claude config list claude config get permissions.allow claude config get permissions.deny # Global settings claude config list -g
-
Avoid bypass modes in production
- Do not use
--dangerously-skip-permissionsoutside isolated/dev sandboxes. - For unattended runs, combine narrow
--allowedToolswith--disallowedToolsand project settings.
- Do not use
-
Use machine‑readable output in automations
claude -p "summarize this error log" --output-format json # valid: text | json | stream-json
-
Bound non‑interactive work
claude -p "run type checks and summarize failures" --max-turns 3 # optionally also bound thinking: export MAX_THINKING_TOKENS=20000
-
Keep sessions tidy
# Retain recent sessions only (default is 30 days) claude config set -g cleanupPeriodDays 20
-
Limit context scope
# Grant access only to relevant paths to reduce scanning/noise claude --add-dir ./services/api ./packages/ui -
Pick the right model
- CLI aliases:
--model sonnetor--model opus(latest of that family). - For reproducibility in settings, pin a full model ID (e.g.,
"claude-3-5-sonnet-20241022").
- CLI aliases:
1) Health checks
Use the built‑in doctor command to verify installation and environment.
# Every 15 minutes
*/15 * * * * /usr/local/bin/claude doctor >/dev/null 2>&1 || \
mail -s "Claude Code doctor failed" [email protected] </dev/null2) Log analysis batch job
# 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.json3) 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.).
1) Share versioned configuration
2) Documentation automation
# 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
# 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"1) Project runbooks
claude "Create a deployment runbook for this app: steps, checks, rollback."
claude "Document onboarding for new developers: setup, commands, conventions."2) Architecture docs
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
/memoryto manage it and@pathto import file content into prompts.
❌ Don’t
- Use
--dangerously-skip-permissionson 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.allowand expand gradually - Audit with
claude config list/claude config get - Isolate risky operations in containers/VMs
❌ 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-dirfor focused context - Right‑size with
--max-turnsandMAX_THINKING_TOKENS - Set
cleanupPeriodDaysto prune old sessions
❌ 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
npm install -g @anthropic-ai/claude-code
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-chatFind more information from the Official Deepseek Docs
![@github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=64&v=4){kind=small}
