diff --git a/README.md b/README.md index d20dcfb..a43555a 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ --- -### **The Most Complete Claude Code Reference** +### **Claude Code Guide** > This comprehensive guide covers **every discoverable Claude Code command** as of June 2025, > including many features that are not widely known or documented in basic tutorials. @@ -43,30 +43,19 @@ --- - -## Table of Contents - -- [Quick Start](#quick-start) -- [Core CLI Commands](#core-cli-commands) -- [CLI Flags & Options](#cli-flags--options) -- [Configuration Commands](#configuration-commands) -- [Slash Commands](#slash-commands) -- [Environment Variables](#environment-variables) -- [Hidden Features](#hidden-features) -- [Advanced Usage](#advanced-usage) -- [Output Formats](#output-formats) -- [Integration Examples](#integration-examples) -- [Troubleshooting](#troubleshooting) -- [Configuration Files](#configuration-files) -- [Security](#security) -- [Beta Features](#beta-features) - ## Quick Start - -Essential Commands (Click to expand) - ```bash +# Quick Installment +## Method 1 +npm install -g @anthropic/claude-code +## Method 2 +brew install anthropic/tap/claude-code +## Method 3 +curl -fsSL https://claude.ai/install.sh | sh +## Method 4 +iwr https://claude.ai/install.ps1 | iex + # Interactive Mode claude # Start interactive REPL claude "your question" # Start with initial prompt @@ -85,1100 +74,4151 @@ claude mcp # Setup MCP servers --- -## Core CLI Commands - -### Interactive Commands - -| Command | Description | Example | -|---------|-------------|----------| -| `claude` | Start interactive REPL | `claude` | -| `claude "query"` | REPL with initial prompt | `claude "help me debug this"` | -| `claude -p "query"` | One-off query (print mode) | `claude -p "explain this function"` | -| `cat file \| claude -p` | Process piped content | `cat error.log \| claude -p "summarize"` | - -### Management Commands - -| Command | Description | Use Case | -|---------|-------------|----------| -| `claude config` | Configure settings | Initial setup | -| `claude update` | Update to latest version | Stay current | -| `claude mcp` | Configure MCP servers | Add integrations | - -## CLI Flags & Options - -### Essential Flags - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FlagShortDescriptionExample
--print-pPrint response without interactive modeclaude -p "help"
--resume-rResume specific session by IDclaude -r abc123
--continue-cLoad most recent conversationclaude -c
--verbose-Enable detailed loggingclaude --verbose
--debug-dEnable debug modeclaude --debug
--help-hShow help informationclaude --help
- -### Output Format Control - - -Format Options - -| Flag | Options | Description | -|------|---------|-------------| -| `--output-format` | `text`, `json`, `stream-json` | Control response format | -| `--input-format` | `text`, `stream-json` | Control input format | -| `--json` | - | Shorthand for JSON output | - -**Examples:** -```bash -# Text output (default) -claude -p "help" --output-format text - -# Structured JSON -claude -p "analyze" --output-format json - -# Streaming JSON for real-time -claude -p "process" --output-format stream-json -``` - - - -### Permission & Security Flags - -> ⚠️ **Warning**: Use security flags with extreme caution! - - -Security Controls - -| Flag | Risk Level | Description | -|------|------------|-------------| -| `--dangerously-skip-permissions` | **HIGH** | Skip ALL permission prompts | -| `--allowedTools ` | **LOW** | Whitelist specific tools | -| `--disallowedTools ` | **LOW** | Blacklist specific tools | - -**Safe Examples:** -```bash -# Allow only git operations -claude --allowedTools "Bash(git:*)" - -# Allow file editing only -claude --allowedTools "Edit,View" - -# DANGEROUS - skip all checks -claude --dangerously-skip-permissions -``` - - - -### Advanced/Hidden Flags - - -Expert-Level Options - -#### System Control - -| Flag | Purpose | Example | -|------|---------|----------| -| `--mcp-debug` | Debug MCP connections | `claude --mcp-debug` | -| `--max-turns ` | Limit agentic interactions | `claude --max-turns 5` | -| `--add-dir ` | Add working directories | `claude --add-dir ../lib ../src` | -| `--model ` | Set specific model | `claude --model sonnet` | - -#### Prompt Engineering - -| Flag | Purpose | Example | -|------|---------|----------| -| `--system-prompt` | Override system prompt | `claude --system-prompt "You are an expert"` | -| `--append-system-prompt` | Append to system prompt | `claude --append-system-prompt "Focus on security"` | -| `-system` | Alternative syntax | `claude -system "Custom prompt"` | - -#### Tool Management - -| Flag | Purpose | Example | -|------|---------|----------| -| `--permission-prompt-tool` | Custom permission handler | `claude --permission-prompt-tool auth_tool` | -| `--allow-tool` | Allow specific tool | `claude --allow-tool Edit` | -| `--disallow-tool` | Block specific tool | `claude --disallow-tool Bash` | - - - -### Experimental Flags - -> **Under Development**: These flags are proposed/experimental - - -Future Features - -| Flag | Status | Purpose | -|------|--------|----------| -| `--no-memory` | **Proposed** | Disable CLAUDE.md loading | -| `--no-tools` | **Proposed** | Exclude tool context | -| `--no-env` | **Proposed** | Disable environment context | - - - -### Cloud Provider Integration - -| Provider | Flag | Service | -|----------|------|------| -| **Amazon Bedrock** | `--use-bedrock` | AWS | -| **Google Vertex AI** | `--use-vertex` | GCP | - - -```bash -# Use AWS Bedrock -claude --use-bedrock "analyze this code" - -# Use Google Vertex AI -claude --use-vertex "help with deployment" -``` - -## Configuration Commands - -### Config Management - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CommandPurposeScopeExample
claude config listList all settingsCurrentclaude config list
claude config get <key>Get specific valueCurrentclaude config get model
claude config set <key> <value>Set valueProjectclaude config set model sonnet
claude config set -g <key> <value>Set global valueGlobalclaude config set -g model opus
claude config add <key> <value>Add to listCurrentclaude config add allowedTools Edit
claude config remove <key> <value>Remove from listCurrentclaude config remove allowedTools Bash
- -**Quick Setup:** -```bash -# Set global preferences -claude config set -g model claude-sonnet-4 -claude config set -g verbose true - -# Set project-specific settings -claude config set allowedTools "Edit,View,Bash(git:*)" -``` - -### MCP Commands - -> **MCP**: Model Context Protocol for extending Claude's capabilities - - -MCP Server Management - -| Command | Purpose | Example | -|---------|---------|----------| -| `claude mcp serve` | Start MCP server | `claude mcp serve` | -| `claude mcp add ` | Add stdio server | `claude mcp add git "git-mcp-server"` | -| `claude mcp remove ` | Remove server | `claude mcp remove git` | - -**Popular MCP Servers:** -```bash -# Database integration -claude mcp add postgres "postgres-mcp-server" - -# Web browsing -claude mcp add browser "browser-mcp-server" - -# File system operations -claude mcp add fs "filesystem-mcp-server" -``` - - - -## Slash Commands - -> **Interactive Mode Only**: These commands work inside the Claude REPL - -### Core Slash Commands - - -Essential Commands - - -| Command | Purpose | Quick Tip | -|---------|---------|--------| -| `/help` | Show all commands | Start here! | -| `/clear` | Clear conversation | Fresh start | -| `/status` | System information | Check everything | -| `/cost` | Token usage stats | Monitor spending | -| `/exit` | Exit safely | Clean shutdown | - - - -Management Commands - -| Command | Purpose | When to Use | -|---------|---------|-------------| -| `/config` | View/modify settings | Setup & tuning | -| `/permissions` | Manage tool access | Security control | -| `/doctor` | Health check | Troubleshooting | -| `/init` | Create CLAUDE.md | New projects | -| `/bug` | Report issues | Found a problem? | - - - - -History & Session Commands - -| Command | Purpose | Pro Tip | -|---------|---------|----------| -| `/undo` | Revert last change | Instant rollback | -| `/compact` | Compress conversation | Save context | -| `/login` | Switch accounts | Multi-account | -| `/logout` | Sign out | Security | - - - - -Interface Commands - -| Command | Purpose | For Users Who | -|---------|---------|---------------| -| `/vim` | Enable Vim keybindings | Love Vim | - - - -### Advanced Slash Commands - - -Workspace Management - -| Command | Purpose | Example | -|---------|---------|----------| -| `/add-dir ` | Add working directory | `/add-dir ../backend` | -| `/memory` | Edit memory files | `/memory` | -| `/model ` | Change AI model | `/model claude-opus-4` | - - - - -Integration Commands - -| Command | Integration | Purpose | -|---------|-------------|----------| -| `/ide` | IDE Tools | Manage IDE integrations | -| `/mcp` | MCP Servers | Manage MCP connections | -| `/install-github-app` | GitHub | Setup GitHub Actions | -| `/pr-comments` | GitHub | Get PR comments | -| `/review` | GitHub | Review pull requests | - - - - -AI Enhancement Commands - -| Command | Purpose | Level | -|---------|---------|--------| -| `/think` | Extended thinking mode | **Advanced** | -| `/upgrade` | Access Claude Max | **Premium** | -| `/user` | Personal commands | **Custom** | - - - - -Experimental Commands - -| Command | Status | Purpose | -|---------|--------|----------| -| `/terminal-setup` | **Proposed** | Terminal optimizations | - - - -### Custom Slash Commands - -> **Build Your Own**: Create custom commands for repeated workflows - - - - - - - - - - - - - - - - - - - - -
TypePatternStorage LocationScope
Project/project:<command>.claude/commands/Current project
Personal/user:<command>~/.claude/commands/All projects
- -**Examples:** -```bash -# Project-specific workflow -/project:deploy # Deploy this project -/project:test-all # Run full test suite - -# Personal shortcuts -/user:morning # Daily startup routine -/user:review-pr # PR review checklist -``` - -## Environment Variables - -### Core Configuration Variables - -| Variable | Purpose | Example | Required | -|----------|---------|---------|----------| -| `ANTHROPIC_API_KEY` | API Authentication | `sk-ant-api03-xxx` | **Yes** | -| `ANTHROPIC_MODEL` | Default model | `claude-sonnet-4` | No | -| `ANTHROPIC_SMALL_FAST_MODEL` | Quick operations | `claude-haiku-3` | No | - -**Quick Setup:** -```bash -# Essential - Add to your ~/.bashrc or ~/.zshrc -export ANTHROPIC_API_KEY="sk-ant-api03-your-key-here" - -# Optional - Set default model -export ANTHROPIC_MODEL="claude-sonnet-4" -``` - -### Claude Code Specific Variables - - -Cloud Provider Integration - -| Variable | Cloud | Purpose | -|----------|-------|----------| -| `CLAUDE_CODE_USE_BEDROCK` | **AWS** | Enable Bedrock integration | -| `CLAUDE_CODE_USE_VERTEX` | **GCP** | Enable Vertex AI integration | -| `CLAUDE_CODE_SKIP_BEDROCK_AUTH` | **AWS** | Skip authentication (gateways) | -| `CLAUDE_CODE_SKIP_VERTEX_AUTH` | **GCP** | Skip authentication (gateways) | - - - - -Telemetry & Privacy - -| Variable | Purpose | Privacy Impact | -|----------|---------|----------------| -| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | Disable all non-essential traffic | **High Privacy** | -| `CLAUDE_CODE_ENABLE_TELEMETRY` | Control telemetry | **Configurable** | - -**Privacy-First Setup:** -```bash -# Maximum privacy -export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 -``` - - - -### Feature Control Variables - - -Privacy & Security Controls - -| Variable | Feature | Privacy Level | -|----------|---------|---------------| -| `DISABLE_AUTOUPDATER=1` | Auto-updates | **Medium** | -| `DISABLE_BUG_COMMAND=1` | Bug reporting | **High** | -| `DISABLE_ERROR_REPORTING=1` | Error reports | **High** | -| `DISABLE_TELEMETRY=1` | Analytics | **High** | - - - - -Cost & Performance Controls - -| Variable | Feature | Cost Impact | -|----------|---------|-------------| -| `DISABLE_COST_WARNINGS=1` | Cost alerts | **None** | -| `DISABLE_NON_ESSENTIAL_MODEL_CALLS=1` | Extra AI calls | **Saves Money** | -| `DISABLE_PROMPT_CACHING=1` | Caching | **Costs More** | - - - -**Recommended Privacy Setup:** -```bash -# Privacy-focused configuration -export DISABLE_TELEMETRY=1 -export DISABLE_ERROR_REPORTING=1 -export DISABLE_BUG_COMMAND=1 - -# Cost optimization -export DISABLE_NON_ESSENTIAL_MODEL_CALLS=1 -``` - -### Network & Proxy Variables - -| Variable | Protocol | Example | -|----------|----------|----------| -| `HTTP_PROXY` | HTTP | `http://proxy.company.com:8080` | -| `HTTPS_PROXY` | HTTPS | `https://proxy.company.com:8443` | - -**Corporate Network Setup:** -```bash -# Corporate proxy configuration -export HTTP_PROXY="http://proxy.company.com:8080" -export HTTPS_PROXY="https://proxy.company.com:8443" -``` - -### Advanced Configuration Variables - - -AI Behavior Tuning - -| Variable | Purpose | Example | -|----------|---------|----------| -| `MAX_THINKING_TOKENS` | Thinking budget | `MAX_THINKING_TOKENS=50000` | -| `MCP_TIMEOUT` | MCP startup timeout | `MCP_TIMEOUT=10000` | - - - - -Regional Configuration - -| Variable | Cloud Provider | Purpose | -|----------|---------------|----------| -| `AWS_REGION` | **AWS Bedrock** | `us-east-1` | -| `CLAUDE_ML_REGION` | **GCP Vertex** | `us-central1` | - -**Multi-Region Setup:** -```bash -# AWS Bedrock in US East -export AWS_REGION="us-east-1" - -# GCP Vertex in US Central -export CLAUDE_ML_REGION="us-central1" -``` - - - -### Recent Updates (2025) - - -Version 1.0.25 (Latest) - -#### New Features -- Fixed slash command reliability issues -- Improved `/mcp` output functionality -- Fixed settings array merge bug - -#### June 18, 2025 Update -- **SSE Transport**: Real-time MCP communication -- **HTTP Transport**: Web-based MCP servers -- **Remote MCP**: Cloud MCP functionality -- **Enhanced Auth**: Better MCP authentication - - +## 📋 Complete Category Index + +|🚀| [Installation & Setup](#-installation--setup) ‎ ‎ ‎ ‎‎ ‎ - Everything to get Claude Code running +|🔌| [MCP Integration](#-mcp-integration)‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ - Complete Model Context Protocol guide +|⌨️| [Commands Reference](#️-commands-reference)‎ ‎ ‎ ‎ ‎- Every CLI command, flag, and slash command +|⚙️| [Configuration](#️-configuration) ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ - All settings, files, and environment variables +|🔒| [Security & Permissions](#-security--permissions) ‎ ‎- Complete security model and best practices +|🤖| [Automation & Scripting](#-automation--scripting) - CI/CD, scripting, and automation patterns +|🔧| [Troubleshooting](#-troubleshooting) ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ - Complete diagnostic and recovery guide +|🚀| [Advanced Features](#-advanced-features) ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎ - Hidden features, context management, and power user tricks --- -## Hidden Features +## 🚀 Installation & Setup -> **Secret Sauce**: Features most users don't know about +### Prerequisites & Requirements -### Tool Permission Patterns +**System Requirements:** +- Node.js 16+ or standalone binary +- API key from Anthropic +- 4GB RAM minimum (8GB+ recommended for large projects) +- Internet connection for API calls +**Supported Platforms:** +- macOS (Intel/Apple Silicon) +- Linux (Ubuntu 18+, Debian 10+, CentOS 7+) +- Windows 10/11 (WSL recommended) -Precise Tool Control - -#### **Allowlist Patterns** - -| Pattern | Scope | Example | -|---------|-------|----------| -| `"Tool"` | Entire tool | `"Edit"` | -| `"Tool(scope:*)"` | Scoped access | `"Bash(git:*)"` | -| `"Tool1,Tool2"` | Multiple tools | `"Edit,View"` | -| `"mcp__server__tool"` | MCP tools | `"mcp__puppeteer__navigate"` | - -#### **Common Patterns** +### Installation Methods +#### Method 1: NPM Installation (Recommended) ```bash -# Text editing only -claude --allowedTools "Edit,View" +# Install globally +npm install -g @anthropic/claude-code -# Git operations only -claude --allowedTools "Bash(git:*)" - -# Development workflow -claude --allowedTools "Edit,View,Bash(npm:*),Bash(git:*)" - -# Web automation -claude --allowedTools "mcp__puppeteer__puppeteer_navigate,mcp__puppeteer__puppeteer_click" +# Verify installation +claude --version +# Should show: claude-code v1.0.25 ``` - - -## Advanced Usage - -### Automation Patterns - - -Headless Automation - +#### Method 2: Direct Binary Download ```bash -# JSON output for scripts -claude -p "analyze code" --output-format stream-json +# Linux/macOS +curl -fsSL https://claude.ai/install.sh | sh -# Dangerous mode (containerized only!) -claude --resume abc123 --dangerously-skip-permissions +# Windows (PowerShell) +iwr https://claude.ai/install.ps1 | iex -# Debug everything -claude --verbose --mcp-debug +# Manual download +# Visit: https://github.com/anthropics/claude-code/releases ``` - - -### AI Behavior Control - - -Prompt Engineering - +#### Method 3: Package Managers ```bash -# Custom system prompt -claude --system-prompt "You are a security expert" -p "review code" +# macOS (Homebrew) +brew install anthropic/tap/claude-code -# Append to system prompt -claude --append-system-prompt "Focus on vulnerabilities" -p "review" +# Ubuntu/Debian +wget -qO- https://claude.ai/keys/gpg | sudo apt-key add - +echo "deb https://claude.ai/apt stable main" | sudo tee /etc/apt/sources.list.d/claude-code.list +sudo apt update && sudo apt install claude-code -# Thinking levels -claude "think about this" # Basic (1K tokens) -claude "think hard about this" # Enhanced -claude "ultrathink about this" # Maximum (128K tokens) +# Arch Linux (AUR) +yay -S claude-code + +# Windows (Chocolatey) +choco install claude-code ``` +### Initial Setup - -### Interactive Mode Tricks - - -Keyboard Shortcuts - -| Shortcut | Mode | Purpose | -|----------|------|----------| -| `Shift+Tab` (1x) | Auto-Accept | Skip confirmations | -| `Shift+Tab` (2x) | Planning | Analyze without writing | -| `Escape` | Interrupt | Stop Claude anytime | -| `Escape` (2x) | History | Edit previous prompts | - -**Workflow Example:** -1. Start Claude Code -2. Press `Shift+Tab` twice → Planning mode -3. Describe task → Claude plans without executing -4. Review plan → Exit planning mode to execute - - - -### Advanced Configurations - - -Power User Setup - +#### 1. API Key Configuration ```bash -# Multi-directory workspace -claude --add-dir ../apps ../lib ../shared +# Required: Get your API key from https://console.anthropic.com +export ANTHROPIC_API_KEY="sk-ant-api03-your-key-here" -# Controlled execution -claude -p --max-turns 3 "refactor function" +# Make permanent (choose your shell) +# Bash +echo 'export ANTHROPIC_API_KEY="sk-ant-api03-your-key"' >> ~/.bashrc +source ~/.bashrc -# Custom permission handler -claude -p --permission-prompt-tool mcp_auth_tool "write files" +# Zsh +echo 'export ANTHROPIC_API_KEY="sk-ant-api03-your-key"' >> ~/.zshrc +source ~/.zshrc -# Specific model selection -claude --model claude-sonnet-4-20250514 "analyze codebase" - -# Extended thinking + tools (beta) -claude "ultrathink about this migration and use tools as needed" +# Fish +echo 'set -gx ANTHROPIC_API_KEY "sk-ant-api03-your-key"' >> ~/.config/fish/config.fish ``` +#### 2. First-Time Configuration +```bash +# Interactive setup +claude config +# Set global defaults +claude config set -g model claude-sonnet-4 +claude config set -g verbose true +claude config set -g outputFormat text + +# Test installation +claude "Hello, Claude!" +claude /doctor # Health check +``` + +#### 3. Recommended Initial Settings +```bash +# Privacy-focused setup +export DISABLE_TELEMETRY=1 +export DISABLE_ERROR_REPORTING=1 +export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 + +# Performance optimization +export DISABLE_NON_ESSENTIAL_MODEL_CALLS=1 +export ANTHROPIC_SMALL_FAST_MODEL="claude-haiku-3" + +# Security defaults +claude config set allowedTools "Edit,View" +claude config set maxTurns 10 +``` + +### Verification & Testing + +#### Health Check +```bash +# Complete system check +claude /doctor + +# Expected output: +# ✅ API Key: Valid +# ✅ Network: Connected +# ✅ Model Access: Available +# ✅ MCP Servers: 0 configured +# ✅ Permissions: Default +# ✅ Configuration: Valid +``` + +#### Basic Functionality Test +```bash +# Interactive mode test +claude "Explain what you can do" + +# Print mode test +claude -p "What is 2+2?" + +# Tool permission test +claude "Create a file called test.txt with 'Hello World'" +# Should prompt for Edit permission + +# Session continuity test +claude -c # Should continue from previous session +``` + +### IDE Integration Setup + +#### VS Code Extension +```bash +# Install from marketplace +code --install-extension anthropic.claude-code + +# Or download from: +# https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code +``` + +#### JetBrains Plugin +```bash +# Available for: +# - IntelliJ IDEA +# - PyCharm +# - WebStorm +# - All JetBrains IDEs + +# Install from JetBrains Marketplace +# Search: "Claude Code" +``` + +### Corporate/Enterprise Setup + +#### Proxy Configuration +```bash +# HTTP/HTTPS Proxy +export HTTP_PROXY="http://proxy.company.com:8080" +export HTTPS_PROXY="https://proxy.company.com:8443" +export NO_PROXY="localhost,127.0.0.1,*.company.com" + +# SOCKS Proxy +export ALL_PROXY="socks5://proxy.company.com:1080" +``` + +#### Air-Gapped Environments +```bash +# Download offline bundle +wget https://claude.ai/releases/claude-code-offline-bundle.tar.gz + +# Install without internet +tar -xzf claude-code-offline-bundle.tar.gz +cd claude-code-offline +./install.sh --offline + +# Configure for local model endpoint +export ANTHROPIC_BASE_URL="https://internal-llm-gateway.company.com" +``` ### Power User Aliases - -Community Shortcuts - -> ⚠️ **Warning**: Use dangerous aliases only in safe environments! - +#### Essential Shortcuts ```bash -# Quick access (add to ~/.bashrc or ~/.zshrc) -alias cc="claude --dangerously-skip-permissions" # DANGEROUS -alias yolo="claude --dangerously-skip-permissions" # VERY DANGEROUS +# Add to ~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish -# Output formats +# Basic shortcuts +alias cl="claude" +alias clp="claude -p" +alias clc="claude -c" +alias cls="claude /status" + +# Output format shortcuts alias claude-json="claude -p --output-format json" alias claude-stream="claude -p --output-format stream-json" -# Safe shortcuts -alias cl="claude" # Simple shortcut -alias clp="claude -p" # Print mode -alias cls="claude /status" # Quick status +# Security shortcuts (use carefully) +alias claude-safe="claude --allowedTools 'Edit,View'" +alias claude-read="claude --allowedTools 'View'" +alias claude-dev="claude --allowedTools 'Edit,View,Bash(git:*),Bash(npm:*)'" + +# DANGEROUS - only for isolated environments +alias yolo="claude --dangerously-skip-permissions" +alias cc="claude --dangerously-skip-permissions" ``` +### Troubleshooting Installation - -## Configuration Files - -### Settings Files - -| File | Scope | Purpose | -|------|-------|----------| -| `~/.claude.json` | **Global** | User-wide settings | -| `.claude/settings.json` | **Project** | Project-specific config | -| `~/.config/claude-code/auth.json` | **Auth** | Authentication data | - -### Custom Commands - - - - - - - - - - - - - - - - - -
DirectoryScopeCommand Pattern
.claude/commands/Project/project:command
~/.claude/commands/Personal/user:command
- -### MCP Configuration - -| File | Purpose | -|------|----------| -| `.claude/mcp.json` | MCP server config | -| `~/.claude-code-mcp.env` | MCP environment vars | - -## Security - -### Dangerous Flags - -> ⚠️ **EXTREME CAUTION REQUIRED** - -| Flag | Risk Level | Impact | -|------|------------|--------| -| `--dangerously-skip-permissions` | **CRITICAL** | Bypasses ALL security checks | - -**Safe Usage Guidelines:** -- **Only use in containerized environments** -- **Never use with internet access** -- **Can cause data loss/corruption** -- **Major security vulnerability** - -### Safe Usage Patterns - - -Security Best Practices - -#### **Always Review First** -- Review commands before granting permissions -- Use `/permissions` to audit settings -- Use `/doctor` for security health checks - -#### **Principle of Least Privilege** -- Avoid blanket permissions -- Use specific tool allowlists -- Regular permission audits - -#### **Security Commands** +#### Common Installation Issues ```bash -# Check security status -claude /doctor +# Permission errors (Linux/macOS) +sudo npm install -g @anthropic/claude-code -# Review permissions -claude /permissions +# Node.js version issues +nvm install 18 +nvm use 18 -# Safe tool allowlist -claude --allowedTools "Edit,View" +# Path issues +echo $PATH +which claude + +# Clear npm cache +npm cache clean --force + +# Reinstall +npm uninstall -g @anthropic/claude-code +npm install -g @anthropic/claude-code ``` - - -## Output Formats - -### Text Output (Default) - +#### Windows-Specific Issues ```bash -# Standard human-readable output -claude -p "explain this function" --output-format text +# PowerShell execution policy +Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser + +# Windows Defender issues +# Add exception for claude.exe in Windows Defender + +# WSL setup (recommended) +wsl --install +# Then install claude inside WSL ``` +--- -Example Output +## 🔌 MCP Integration +### Understanding MCP (Model Context Protocol) + +**What is MCP?** +MCP (Model Context Protocol) extends Claude's capabilities by connecting to external services, databases, APIs, and tools. Think of MCP servers as "plugins" that give Claude superpowers. + +**MCP Architecture:** ``` -This function calculates the factorial of a number recursively... +Claude Code ←→ MCP Protocol ←→ MCP Servers ←→ External Services ``` +**Transport Types:** +- **stdio**: Local command-line servers (most common) +- **SSE**: Server-sent events for real-time communication +- **HTTP**: Web-based servers for cloud services +### MCP Setup & Configuration -### JSON Output - +#### Basic MCP Setup ```bash -# Structured data with metadata -claude -p "analyze this code" --output-format json +# Interactive MCP configuration +claude mcp + +# Check current MCP servers +claude config get mcp + +# List available MCP servers (if registry exists) +claude mcp list-available ``` - -Example Output - +#### MCP Configuration File +Create `.claude/mcp.json` in your project: ```json { - "response": "This function calculates...", - "metadata": { - "cost": 0.0023, - "duration": 1.2, - "model": "claude-sonnet-4" + "mcpServers": { + "git": { + "command": "git-mcp-server", + "args": [], + "env": {} + }, + "postgres": { + "command": "postgres-mcp-server", + "args": ["--host", "localhost", "--port", "5432"], + "env": { + "POSTGRES_USER": "developer", + "POSTGRES_PASSWORD": "dev_password", + "POSTGRES_DB": "myapp_development" + } + }, + "filesystem": { + "command": "filesystem-mcp-server", + "args": ["--root", "/workspace"], + "env": {} + }, + "web_api": { + "transport": "http", + "url": "http://localhost:3001/mcp", + "headers": { + "Authorization": "Bearer ${API_TOKEN}", + "Content-Type": "application/json" + } + }, + "browser": { + "transport": "sse", + "url": "ws://localhost:8080/mcp-sse", + "reconnect": true + } } } ``` +### Popular MCP Servers (2025) +#### Development & Git Tools -### Streaming JSON Output +| Server | Installation | Purpose | Popular Use Cases | +|--------|-------------|---------|-------------------| +| **git-mcp-server** | `npm i -g @anthropic/git-mcp-server` | Git operations | Code reviews, commits, branch management | +| **github-mcp-server** | `npm i -g @modelcontextprotocol/github-mcp-server` | GitHub API access | PR management, issue tracking, repository analysis | +| **gitlab-mcp-server** | `npm i -g @mcp/gitlab-server` | GitLab integration | CI/CD pipeline management, merge requests | +| **docker-mcp-server** | `npm i -g @mcp/docker-server` | Docker operations | Container management, image building | +| **kubernetes-mcp-server** | `npm i -g @mcp/k8s-server` | Kubernetes management | Pod monitoring, deployment management | +**Setup Example:** ```bash -# Real-time streaming for large operations -claude -p "process large file" --output-format stream-json +# Install and configure Git MCP +npm install -g @anthropic/git-mcp-server +claude mcp add git "git-mcp-server" + +# GitHub with token +export GITHUB_TOKEN="ghp_your_token_here" +npm install -g @modelcontextprotocol/github-mcp-server +claude mcp add github "github-mcp-server --token $GITHUB_TOKEN" ``` +#### Database Integration -Example Output +| Server | Installation | Purpose | Supported Databases | +|--------|-------------|---------|-------------------| +| **postgres-mcp-server** | `npm i -g @anthropic/postgres-mcp-server` | PostgreSQL access | PostgreSQL 12+ | +| **mysql-mcp-server** | `npm i -g @mcp/mysql-server` | MySQL operations | MySQL 8.0+, MariaDB 10.5+ | +| **sqlite-mcp-server** | `npm i -g @mcp/sqlite-server` | SQLite databases | SQLite 3.x | +| **mongodb-mcp-server** | `npm i -g @mcp/mongodb-server` | MongoDB operations | MongoDB 4.4+ | +| **redis-mcp-server** | `npm i -g @mcp/redis-server` | Redis operations | Redis 6.0+ | +| **elasticsearch-mcp-server** | `npm i -g @mcp/elasticsearch-server` | Elasticsearch queries | Elasticsearch 7.x, 8.x | + +**Database Setup Example:** +```bash +# PostgreSQL setup +export POSTGRES_URL="postgresql://user:password@localhost:5432/mydb" +npm install -g @anthropic/postgres-mcp-server +claude mcp add postgres "postgres-mcp-server --url $POSTGRES_URL" + +# MongoDB setup +export MONGODB_URI="mongodb://localhost:27017/myapp" +npm install -g @mcp/mongodb-server +claude mcp add mongodb "mongodb-mcp-server --uri $MONGODB_URI" +``` + +#### Web & API Tools + +| Server | Installation | Purpose | Key Features | +|--------|-------------|---------|--------------| +| **puppeteer-mcp-server** | `npm i -g @anthropic/puppeteer-mcp-server` | Browser automation | Web scraping, testing, screenshots | +| **playwright-mcp-server** | `npm i -g @mcp/playwright-server` | Multi-browser automation | Chrome, Firefox, Safari automation | +| **selenium-mcp-server** | `npm i -g @mcp/selenium-server` | Selenium WebDriver | Legacy browser automation | +| **http-client-mcp-server** | `npm i -g @mcp/http-client-server` | REST API calls | HTTP requests, API testing | +| **graphql-mcp-server** | `npm i -g @mcp/graphql-server` | GraphQL operations | Schema introspection, queries | +| **websocket-mcp-server** | `npm i -g @mcp/websocket-server` | WebSocket communication | Real-time data, trading APIs | + +**Web Automation Setup:** +```bash +# Puppeteer for web automation +npm install -g @anthropic/puppeteer-mcp-server +claude mcp add browser "puppeteer-mcp-server --headless --no-sandbox" + +# HTTP client for APIs +npm install -g @mcp/http-client-server +claude mcp add http "http-client-server --timeout 30000" +``` + +#### Cloud Services Integration + +| Server | Installation | Cloud Provider | Services | +|--------|-------------|----------------|----------| +| **aws-mcp-server** | `npm i -g @mcp/aws-server` | Amazon Web Services | S3, EC2, Lambda, RDS, CloudWatch | +| **gcp-mcp-server** | `npm i -g @mcp/gcp-server` | Google Cloud Platform | Compute, Storage, BigQuery, Pub/Sub | +| **azure-mcp-server** | `npm i -g @mcp/azure-server` | Microsoft Azure | VMs, Storage, Functions, Cosmos DB | +| **digitalocean-mcp-server** | `npm i -g @mcp/digitalocean-server` | DigitalOcean | Droplets, Volumes, Load Balancers | +| **vercel-mcp-server** | `npm i -g @mcp/vercel-server` | Vercel | Deployments, Functions, Analytics | +| **netlify-mcp-server** | `npm i -g @mcp/netlify-server` | Netlify | Sites, Functions, Forms | + +**Cloud Setup Example:** +```bash +# AWS integration +export AWS_ACCESS_KEY_ID="your_access_key" +export AWS_SECRET_ACCESS_KEY="your_secret_key" +export AWS_REGION="us-east-1" +npm install -g @mcp/aws-server +claude mcp add aws "aws-mcp-server --region $AWS_REGION" + +# Google Cloud integration +export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json" +npm install -g @mcp/gcp-server +claude mcp add gcp "gcp-server --project-id your-project-id" +``` + +#### Specialized Tools + +| Server | Installation | Purpose | Industry | +|--------|-------------|---------|----------| +| **jira-mcp-server** | `npm i -g @mcp/jira-server` | JIRA integration | Project management | +| **slack-mcp-server** | `npm i -g @mcp/slack-server` | Slack operations | Team communication | +| **discord-mcp-server** | `npm i -g @mcp/discord-server` | Discord bot operations | Community management | +| **confluence-mcp-server** | `npm i -g @mcp/confluence-server` | Confluence docs | Documentation management | +| **notion-mcp-server** | `npm i -g @mcp/notion-server` | Notion integration | Knowledge management | +| **airtable-mcp-server** | `npm i -g @mcp/airtable-server` | Airtable operations | Database/CRM operations | +| **shopify-mcp-server** | `npm i -g @mcp/shopify-server` | Shopify API | E-commerce operations | +| **stripe-mcp-server** | `npm i -g @mcp/stripe-server` | Payment processing | Financial operations | + +#### AI & Machine Learning Tools + +| Server | Installation | Purpose | Capabilities | +|--------|-------------|---------|--------------| +| **openai-mcp-server** | `npm i -g @mcp/openai-server` | OpenAI API access | GPT models, DALL-E, Whisper | +| **huggingface-mcp-server** | `npm i -g @mcp/huggingface-server` | Hugging Face models | Model inference, datasets | +| **ollama-mcp-server** | `npm i -g @mcp/ollama-server` | Local LLM operations | Local model management | +| **tensorflow-mcp-server** | `npm i -g @mcp/tensorflow-server` | TensorFlow operations | Model training, inference | +| **pytorch-mcp-server** | `npm i -g @mcp/pytorch-server` | PyTorch operations | Deep learning workflows | + +#### Data & Analytics Tools + +| Server | Installation | Purpose | Data Sources | +|--------|-------------|---------|--------------| +| **csv-mcp-server** | `npm i -g @mcp/csv-server` | CSV file operations | Data analysis, reporting | +| **excel-mcp-server** | `npm i -g @mcp/excel-server` | Excel file operations | Spreadsheet analysis | +| **pandas-mcp-server** | `npm i -g @mcp/pandas-server` | Python data analysis | DataFrame operations | +| **jupyter-mcp-server** | `npm i -g @mcp/jupyter-server` | Jupyter notebook access | Data science workflows | +| **tableau-mcp-server** | `npm i -g @mcp/tableau-server` | Tableau integration | Business intelligence | + +### MCP Management Commands + +#### Server Management +```bash +# Add MCP servers +claude mcp add # Add stdio server +claude mcp add --http # Add HTTP server +claude mcp add --sse # Add SSE server + +# Remove servers +claude mcp remove # Remove specific server +claude mcp remove --all # Remove all servers + +# List and status +claude mcp list # List configured servers +claude mcp status # Check server health +claude mcp restart # Restart specific server +claude mcp restart --all # Restart all servers +``` + +#### Server Configuration +```bash +# Update server settings +claude mcp configure # Interactive configuration +claude mcp set # Set specific setting +claude mcp env # Set environment variable + +# Import/export configurations +claude mcp export > mcp-config.json # Export configuration +claude mcp import mcp-config.json # Import configuration +``` + +### MCP Tool Permissions + +#### Permission Patterns for MCP Tools +```bash +# Allow specific MCP tools +claude --allowedTools "mcp__git__commit,mcp__git__push" + +# Allow all tools from specific server +claude --allowedTools "mcp__postgres__*" + +# Pattern: mcp____ +claude --allowedTools "mcp__browser__navigate,mcp__browser__click" + +# Combined with built-in tools +claude --allowedTools "Edit,View,mcp__git__*,mcp__http__*" + +# Read-only patterns +claude --allowedTools "View,mcp__postgres__query,mcp__git__log" +``` + +#### MCP Security Configuration +```bash +# Secure MCP setup +claude config set mcpSecurity.requireAuth true +claude config set mcpSecurity.timeout 30000 +claude config set mcpSecurity.maxConnections 10 + +# Network restrictions +claude config set mcpSecurity.allowedHosts "localhost,*.company.com" +claude config set mcpSecurity.allowedPorts "3000-3999,5432,5984" +``` + +### Custom MCP Server Development + +#### Basic MCP Server Template +```javascript +// my-custom-mcp-server.js +import { Server } from '@modelcontextprotocol/sdk/server/index.js'; +import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'; + +const server = new Server( + { + name: 'my-custom-server', + version: '1.0.0' + }, + { + capabilities: { + tools: {}, + resources: {} + } + } +); + +// Define tools +server.setRequestHandler('tools/list', async () => { + return { + tools: [ + { + name: 'my_tool', + description: 'Does something useful', + inputSchema: { + type: 'object', + properties: { + input: { type: 'string' } + } + } + } + ] + }; +}); + +// Handle tool calls +server.setRequestHandler('tools/call', async (request) => { + const { name, arguments: args } = request.params; + + if (name === 'my_tool') { + return { + content: [ + { + type: 'text', + text: `Processed: ${args.input}` + } + ] + }; + } + + throw new Error(`Tool ${name} not found`); +}); + +// Start server +const transport = new StdioServerTransport(); +await server.connect(transport); +``` + +#### Custom Server Registration +```bash +# Make executable +chmod +x my-custom-mcp-server.js + +# Add to Claude Code +claude mcp add custom "node my-custom-mcp-server.js" + +# Test the server +claude "Use my_tool to process 'hello world'" +``` + +### MCP Troubleshooting + +#### Common MCP Issues +```bash +# Server startup issues +claude --mcp-debug # Enable MCP debugging +claude mcp status # Check server health +node your-server.js # Test server manually + +# Permission issues +claude /permissions # Check MCP permissions +claude config get allowedTools # Review allowed tools + +# Connection issues +export MCP_TIMEOUT=30000 # Increase timeout +claude mcp restart --all # Restart all servers + +# Environment issues +claude mcp env postgres POSTGRES_URL "postgresql://..." +claude config get mcp.servers.postgres # Verify configuration +``` + +#### MCP Debugging +```bash +# Enable comprehensive MCP debugging +export MCP_DEBUG=1 +export MCP_TRACE=1 +claude --mcp-debug --verbose + +# Check MCP logs +tail -f ~/.claude/logs/mcp-*.log + +# Test individual servers +npx postgres-mcp-server --help +npx git-mcp-server --version +``` + +### Context Management with MCP + +#### Context Providers +```bash +# Add context-aware MCP servers +claude mcp add context7 "context7-mcp-server --memory-size 1000" +claude mcp add long-context "long-context-server --window-size 128000" + +# Configure context retention +claude config set context.maxTokens 128000 +claude config set context.retentionDays 30 +claude config set context.compressionEnabled true +``` + +#### Advanced Context Features +```bash +# Context-aware sessions +claude --context-window 128000 "analyze this large codebase" + +# Multi-modal context +claude mcp add vision "vision-mcp-server --image-analysis true" +claude "analyze this screenshot and the related code" + +# Persistent context +claude /memory # Edit persistent memory +claude --memory-file custom.md # Use custom memory file +``` + +--- + +## ⌨️ Commands Reference + +### CLI Commands + +#### Core Commands +| Command | Description | Example | Use Case | +|---------|-------------|---------|----------| +| `claude` | Start interactive REPL | `claude` | Development, exploration | +| `claude "query"` | REPL with initial prompt | `claude "help debug this"` | Guided sessions | +| `claude -p "query"` | One-shot query (print mode) | `claude -p "explain function"` | Quick queries, automation | + +#### Session Management +| Command | Description | Example | Use Case | +|---------|-------------|---------|----------| +| `claude -c` | Continue last session | `claude -c` | Resume work | +| `claude -r ` | Resume specific session | `claude -r abc123` | Return to specific context | +| `claude --resume ` | Resume named session | `claude --resume project-review` | Named workflows | + +#### Configuration Management +| Command | Description | Example | Use Case | +|---------|-------------|---------|----------| +| `claude config` | Interactive configuration | `claude config` | Initial setup | +| `claude config list` | List all settings | `claude config list` | Audit configuration | +| `claude config get ` | Get specific value | `claude config get model` | Check settings | +| `claude config set ` | Set project value | `claude config set model sonnet` | Project configuration | +| `claude config set -g ` | Set global value | `claude config set -g model opus` | Global defaults | +| `claude config add ` | Add to list | `claude config add allowedTools Edit` | Extend permissions | +| `claude config remove ` | Remove from list | `claude config remove allowedTools Bash` | Restrict permissions | + +#### MCP Management +| Command | Description | Example | Use Case | +|---------|-------------|---------|----------| +| `claude mcp` | MCP configuration menu | `claude mcp` | Setup integrations | +| `claude mcp add ` | Add stdio server | `claude mcp add git "git-mcp-server"` | Add functionality | +| `claude mcp remove ` | Remove server | `claude mcp remove git` | Remove integration | +| `claude mcp list` | List all servers | `claude mcp list` | Audit integrations | +| `claude mcp status` | Check server health | `claude mcp status` | Troubleshooting | +| `claude mcp restart ` | Restart server | `claude mcp restart postgres` | Fix connections | + +#### System Commands +| Command | Description | Example | Use Case | +|---------|-------------|---------|----------| +| `claude update` | Update to latest version | `claude update` | Maintenance | +| `claude --version` | Show version | `claude --version` | Version check | +| `claude --help` | Show help | `claude --help` | Get help | + +### CLI Flags & Options + +#### Essential Flags +| Flag | Short | Description | Example | +|------|-------|-------------|---------| +| `--print` | `-p` | Print response without interactive mode | `claude -p "help"` | +| `--continue` | `-c` | Load most recent conversation | `claude -c` | +| `--resume` | `-r` | Resume specific session by ID | `claude -r abc123` | +| `--help` | `-h` | Show help information | `claude --help` | +| `--verbose` | - | Enable detailed logging | `claude --verbose` | +| `--debug` | `-d` | Enable debug mode | `claude --debug` | +| `--version` | `-v` | Show version | `claude --version` | + +#### Output Control Flags +| Flag | Options | Description | Example | +|------|---------|-------------|---------| +| `--output-format` | `text`, `json`, `stream-json` | Control response format | `claude -p "help" --output-format json` | +| `--input-format` | `text`, `stream-json` | Control input format | `claude --input-format stream-json` | +| `--json` | - | Shorthand for JSON output | `claude -p "analyze" --json` | + +#### Security & Permission Flags +| Flag | Risk Level | Description | Example | +|------|------------|-------------|---------| +| `--allowedTools ` | **LOW** | Whitelist specific tools | `claude --allowedTools "Edit,View"` | +| `--disallowedTools ` | **LOW** | Blacklist specific tools | `claude --disallowedTools "Bash"` | +| `--allow-tool ` | **LOW** | Allow single tool | `claude --allow-tool Edit` | +| `--disallow-tool ` | **LOW** | Block single tool | `claude --disallow-tool Bash` | +| `--dangerously-skip-permissions` | **CRITICAL** | Skip ALL permission prompts | `claude --dangerously-skip-permissions` | + +#### Advanced Control Flags +| Flag | Purpose | Example | Notes | +|------|---------|---------|--------| +| `--max-turns ` | Limit agentic interactions | `claude --max-turns 5` | Control autonomy | +| `--add-dir ` | Add working directories | `claude --add-dir ../lib ../src` | Multi-directory workspace | +| `--model ` | Set specific model | `claude --model sonnet` | Override default | +| `--mcp-debug` | Debug MCP connections | `claude --mcp-debug` | MCP troubleshooting | + +#### Prompt Engineering Flags +| Flag | Purpose | Example | Use Case | +|------|---------|---------|----------| +| `--system-prompt ` | Override system prompt | `claude --system-prompt "You are an expert"` | Custom behavior | +| `--append-system-prompt ` | Append to system prompt | `claude --append-system-prompt "Focus on security"` | Add instructions | +| `-system ` | Alternative syntax | `claude -system "Custom prompt"` | Shorthand | + +#### Cloud Provider Flags +| Flag | Provider | Description | Example | +|------|----------|-------------|---------| +| `--use-bedrock` | **AWS** | Use Amazon Bedrock | `claude --use-bedrock "analyze code"` | +| `--use-vertex` | **GCP** | Use Google Vertex AI | `claude --use-vertex "help deploy"` | + +#### Advanced/Experimental Flags +| Flag | Status | Purpose | Example | +|------|--------|---------|---------| +| `--permission-prompt-tool ` | **Advanced** | Custom permission handler | `claude --permission-prompt-tool auth_tool` | +| `--thinking-budget ` | **Experimental** | Set thinking token limit | `claude --thinking-budget 50000` | +| `--no-memory` | **Proposed** | Disable CLAUDE.md loading | `claude --no-memory` | +| `--no-tools` | **Proposed** | Exclude tool context | `claude --no-tools` | +| `--no-env` | **Proposed** | Disable environment context | `claude --no-env` | + +### Slash Commands (Interactive Mode) + +#### Essential Commands +| Command | Purpose | When to Use | Example | +|---------|---------|-------------|---------| +| `/help` | Show all slash commands | Getting started | `/help` | +| `/status` | System information and health | Check everything | `/status` | +| `/clear` | Clear current conversation | Fresh start | `/clear` | +| `/cost` | Token usage and cost stats | Monitor spending | `/cost` | +| `/exit` | Exit Claude safely | Clean shutdown | `/exit` | + +#### Configuration Commands +| Command | Purpose | Use Case | Example | +|---------|---------|----------|---------| +| `/config` | View/modify settings | Setup & tuning | `/config` | +| `/config set ` | Set configuration | Change settings | `/config set model opus` | +| `/config get ` | Get configuration | Check settings | `/config get allowedTools` | +| `/permissions` | Manage tool access | Security control | `/permissions` | +| `/doctor` | Complete health check | Troubleshooting | `/doctor` | + +#### Session Management Commands +| Command | Purpose | Pro Tip | Example | +|---------|---------|---------|---------| +| `/undo` | Revert last Claude action | Instant rollback | `/undo` | +| `/compact` | Compress conversation history | Save context tokens | `/compact` | +| `/save ` | Save session with name | Create checkpoints | `/save important-debug` | +| `/load ` | Load named session | Return to checkpoint | `/load important-debug` | +| `/sessions` | List all sessions | Session management | `/sessions` | + +#### Account Management Commands +| Command | Purpose | Use Case | Example | +|---------|---------|----------|---------| +| `/login` | Switch/login accounts | Multi-account usage | `/login` | +| `/logout` | Sign out current account | Security practice | `/logout` | +| `/whoami` | Show current account | Check active account | `/whoami` | + +#### Workspace Management Commands +| Command | Purpose | Example | Use Case | +|---------|---------|---------|----------| +| `/add-dir ` | Add working directory | `/add-dir ../backend` | Multi-project work | +| `/dirs` | List working directories | `/dirs` | Check workspace | +| `/remove-dir ` | Remove working directory | `/remove-dir ../old-code` | Clean workspace | +| `/memory` | Edit memory files | `/memory` | Context management | +| `/memory edit` | Edit CLAUDE.md | `/memory edit` | Update project context | +| `/memory view` | View current memory | `/memory view` | Check context | + +#### Model & AI Commands +| Command | Purpose | Example | Use Case | +|---------|---------|---------|----------| +| `/model ` | Change AI model | `/model claude-opus-4` | Switch capabilities | +| `/models` | List available models | `/models` | See options | +| `/think` | Extended thinking mode | `/think` | Complex analysis | +| `/upgrade` | Access Claude Max | `/upgrade` | Premium features | + +#### Integration Commands +| Command | Integration | Purpose | Example | +|---------|-------------|---------|---------| +| `/mcp` | MCP Servers | Manage MCP connections | `/mcp` | +| `/mcp list` | MCP Servers | List configured servers | `/mcp list` | +| `/mcp add ` | MCP Servers | Add new server | `/mcp add git "git-mcp-server"` | +| `/mcp remove ` | MCP Servers | Remove server | `/mcp remove git` | +| `/ide` | IDE Tools | Manage IDE integrations | `/ide` | + +#### GitHub Integration Commands +| Command | Purpose | Example | Use Case | +|---------|---------|---------|----------| +| `/install-github-app` | Setup GitHub integration | `/install-github-app` | Enable GitHub features | +| `/pr-comments` | Get PR comments | `/pr-comments` | Review feedback | +| `/review` | Review pull requests | `/review` | Code review workflow | +| `/github` | GitHub operations | `/github` | Repository management | + +#### Interface Commands +| Command | Purpose | For Users Who | Example | +|---------|---------|---------------|---------| +| `/vim` | Enable Vim keybindings | Love Vim | `/vim` | +| `/emacs` | Enable Emacs keybindings | Love Emacs | `/emacs` | +| `/theme ` | Change interface theme | Want customization | `/theme dark` | + +#### Debugging Commands +| Command | Purpose | When to Use | Example | +|---------|---------|-------------|---------| +| `/bug` | Report issues | Found a problem | `/bug` | +| `/logs` | View recent logs | Troubleshooting | `/logs` | +| `/debug on` | Enable debug mode | Deep troubleshooting | `/debug on` | +| `/debug off` | Disable debug mode | Normal operation | `/debug off` | + +#### Initialization Commands +| Command | Purpose | Example | Use Case | +|---------|---------|---------|----------| +| `/init` | Create CLAUDE.md | `/init` | New project setup | +| `/init --template ` | Use specific template | `/init --template react` | Templated setup | + +#### Custom Commands +| Type | Pattern | Storage Location | Scope | Example | +|------|---------|------------------|--------|---------| +| **Project** | `/project:` | `.claude/commands/` | Current project | `/project:deploy` | +| **Personal** | `/user:` | `~/.claude/commands/` | All projects | `/user:morning` | +| **Team** | `/team:` | Team shared storage | Team projects | `/team:review-checklist` | + +#### Example Custom Commands +```bash +# Project-specific workflows +/project:test-all # Run complete test suite +/project:deploy-staging # Deploy to staging environment +/project:backup-db # Create database backup + +# Personal shortcuts +/user:morning # Daily startup routine +/user:cleanup # End-of-day cleanup +/user:review-setup # Setup for code review + +# Team workflows +/team:standup # Daily standup checklist +/team:release-checklist # Release preparation +/team:incident-response # Incident response procedure +``` + +#### Experimental/Proposed Commands +| Command | Status | Purpose | Example | +|---------|--------|---------|---------| +| `/terminal-setup` | **Proposed** | Terminal optimizations | `/terminal-setup` | +| `/ai-pair` | **Beta** | AI pair programming mode | `/ai-pair` | +| `/voice` | **Beta** | Voice interaction mode | `/voice` | +| `/collaborate` | **Proposed** | Multi-user sessions | `/collaborate` | + +### Keyboard Shortcuts (Interactive Mode) + +#### Essential Shortcuts +| Shortcut | Action | Mode | Description | +|----------|--------|------|-------------| +| `Shift+Tab` (1x) | **Auto-Accept** | Skip confirmations | Claude executes without asking | +| `Shift+Tab` (2x) | **Planning** | Analyze without executing | Claude plans but doesn't act | +| `Escape` | **Interrupt** | Stop Claude immediately | Halt any ongoing operation | +| `Escape` (2x) | **History** | Edit previous prompts | Access and modify history | + +#### Navigation Shortcuts +| Shortcut | Action | Description | +|----------|--------|-------------| +| `Ctrl+C` | Interrupt | Stop current operation | +| `Ctrl+D` | Exit | Quit Claude gracefully | +| `Ctrl+L` | Clear Screen | Clear terminal display | +| `Ctrl+R` | Search History | Search command history | + +#### Editing Shortcuts +| Shortcut | Action | Description | +|----------|--------|-------------| +| `Ctrl+A` | Beginning of Line | Move cursor to start | +| `Ctrl+E` | End of Line | Move cursor to end | +| `Ctrl+U` | Clear Line | Clear current input | +| `Ctrl+W` | Delete Word | Delete previous word | + +### Command Examples & Workflows + +#### Development Workflow +```bash +# Start new project +claude /init +claude /add-dir src tests docs + +# Development session +claude "Review and improve this React component" +# Press Shift+Tab twice for planning mode +# Review plan, then execute + +# Git integration +claude --allowedTools "Edit,View,mcp__git__*" \ + "Review my changes and create a commit message" + +# Testing and deployment +claude /project:test-all +claude /project:deploy-staging +``` + +#### Database Analysis Workflow +```bash +# Setup database MCP +claude mcp add postgres "postgres-mcp-server --url $DATABASE_URL" + +# Analysis session +claude --allowedTools "mcp__postgres__*,Edit,View" \ + "Analyze the database schema and suggest optimizations" + +# Report generation +claude -p "Generate database performance report" \ + --output-format json > db-report.json +``` + +#### Code Review Workflow +```bash +# Setup for code review +claude --allowedTools "View,mcp__git__*,mcp__github__*" \ + -c # Continue previous context + +# Review specific PR +claude "/pr-comments 123" +claude "Review the changes in PR #123 for security issues" + +# Generate review report +claude -p "Create comprehensive code review report" \ + --output-format json > review-report.json +``` + +--- + +## ⚙️ Configuration + +### Configuration System Overview + +Claude Code uses a **hierarchical configuration system**: + +1. **Command-line flags** (highest priority) +2. **Environment variables** +3. **Project configuration** (`.claude/settings.json`) +4. **Global configuration** (`~/.claude.json`) +5. **Built-in defaults** (lowest priority) + +### Configuration Files + +#### Global Configuration +**Location**: `~/.claude.json` +**Scope**: All projects for current user ```json -{"type": "start", "timestamp": "2025-06-23T10:00:00Z"} -{"type": "progress", "content": "Processing..."} -{"type": "result", "content": "Analysis complete"} -{"type": "end", "timestamp": "2025-06-23T10:00:05Z"} +{ + "model": "claude-sonnet-4", + "verbose": true, + "outputFormat": "text", + "allowedTools": ["Edit", "View"], + "disallowedTools": [], + "maxTurns": 10, + "thinkingBudget": 50000, + "security": { + "requireConfirmation": true, + "dangerousOperationsAllowed": false + }, + "ui": { + "theme": "auto", + "showCost": true, + "autoComplete": true + }, + "network": { + "timeout": 30000, + "retries": 3, + "proxy": null + } +} ``` -> ⚠️ **Note**: Each line is valid JSON, but concatenated output is not valid JSON +#### Project Configuration +**Location**: `.claude/settings.json` +**Scope**: Current project only +```json +{ + "model": "claude-opus-4", + "systemPrompt": "You are a senior developer working on this React application", + "allowedTools": [ + "Edit", + "View", + "Bash(git:*)", + "Bash(npm:*)", + "mcp__postgres__*" + ], + "addDirs": ["../shared", "../lib", "../tests"], + "maxTurns": 20, + "context": { + "memoryFile": "CLAUDE.md", + "maxTokens": 128000, + "compressionEnabled": true + }, + "mcp": { + "servers": { + "postgres": { + "command": "postgres-mcp-server", + "args": ["--host", "localhost", "--port", "5432"], + "env": { + "POSTGRES_DB": "myapp_dev" + } + }, + "git": { + "command": "git-mcp-server", + "args": [] + } + } + }, + "automation": { + "preCommitCheck": true, + "autoFormat": true, + "testOnSave": false + } +} +``` +#### Authentication Configuration +**Location**: `~/.config/claude-code/auth.json` +**Purpose**: Store authentication tokens and credentials -## Integration Examples +```json +{ + "anthropic": { + "api_key": "sk-ant-api03-...", + "organization": "org-...", + "last_login": "2025-06-24T10:00:00Z" + }, + "cloud_providers": { + "bedrock": { + "region": "us-east-1", + "profile": "default", + "access_key_id": "AKIA...", + "session_token": null + }, + "vertex": { + "project_id": "my-project", + "region": "us-central1", + "service_account_path": "/path/to/service-account.json" + } + }, + "integrations": { + "github": { + "token": "ghp_...", + "username": "developer" + }, + "gitlab": { + "token": "glpat-...", + "instance": "gitlab.com" + } + } +} +``` + +### Environment Variables + +#### Core Configuration Variables + +| Variable | Required | Purpose | Example | Default | +|----------|----------|---------|---------|---------| +| `ANTHROPIC_API_KEY` | **YES** | API Authentication | `sk-ant-api03-xxx` | None | +| `ANTHROPIC_MODEL` | No | Default model | `claude-sonnet-4` | `claude-sonnet-4` | +| `ANTHROPIC_SMALL_FAST_MODEL` | No | Quick operations model | `claude-haiku-3` | `claude-haiku-3` | +| `ANTHROPIC_BASE_URL` | No | API endpoint override | `https://api.anthropic.com` | Official API | + +#### Cloud Provider Variables + +| Variable | Provider | Purpose | Example | +|----------|----------|---------|---------| +| `CLAUDE_CODE_USE_BEDROCK` | **AWS** | Enable Bedrock | `CLAUDE_CODE_USE_BEDROCK=1` | +| `CLAUDE_CODE_USE_VERTEX` | **GCP** | Enable Vertex AI | `CLAUDE_CODE_USE_VERTEX=1` | +| `CLAUDE_CODE_SKIP_BEDROCK_AUTH` | **AWS** | Skip auth (gateways) | `CLAUDE_CODE_SKIP_BEDROCK_AUTH=1` | +| `CLAUDE_CODE_SKIP_VERTEX_AUTH` | **GCP** | Skip auth (gateways) | `CLAUDE_CODE_SKIP_VERTEX_AUTH=1` | +| `AWS_REGION` | **AWS** | Bedrock region | `AWS_REGION=us-east-1` | +| `AWS_ACCESS_KEY_ID` | **AWS** | AWS credentials | `AKIA...` | +| `AWS_SECRET_ACCESS_KEY` | **AWS** | AWS credentials | `secret...` | +| `CLAUDE_ML_REGION` | **GCP** | Vertex region | `CLAUDE_ML_REGION=us-central1` | +| `GOOGLE_APPLICATION_CREDENTIALS` | **GCP** | Service account | `/path/to/creds.json` | + +#### Privacy & Telemetry Control + +| Variable | Privacy Impact | Purpose | Example | +|----------|----------------|---------|---------| +| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | **High** | Disable all non-essential traffic | `=1` | +| `CLAUDE_CODE_ENABLE_TELEMETRY` | **Configurable** | Control telemetry | `=0` | +| `DISABLE_TELEMETRY` | **High** | Disable analytics | `=1` | +| `DISABLE_ERROR_REPORTING` | **High** | Disable error reports | `=1` | +| `DISABLE_BUG_COMMAND` | **High** | Disable bug reporting | `=1` | +| `DISABLE_AUTOUPDATER` | **Medium** | Disable auto-updates | `=1` | + +#### Performance & Cost Control + +| Variable | Impact | Purpose | Example | +|----------|--------|---------|---------| +| `DISABLE_NON_ESSENTIAL_MODEL_CALLS` | **Saves Money** | Reduce API calls | `=1` | +| `DISABLE_PROMPT_CACHING` | **Costs More** | Disable caching | `=1` | +| `DISABLE_COST_WARNINGS` | **UX** | Hide cost alerts | `=1` | +| `MAX_THINKING_TOKENS` | **Cost/Performance** | Thinking budget | `=50000` | +| `MCP_TIMEOUT` | **Performance** | MCP startup timeout | `=10000` | + +#### Network & Proxy Configuration + +| Variable | Protocol | Purpose | Example | +|----------|----------|---------|---------| +| `HTTP_PROXY` | HTTP | HTTP proxy | `http://proxy.company.com:8080` | +| `HTTPS_PROXY` | HTTPS | HTTPS proxy | `https://proxy.company.com:8443` | +| `ALL_PROXY` | SOCKS | SOCKS proxy | `socks5://proxy.company.com:1080` | +| `NO_PROXY` | Exclusions | Proxy exclusions | `localhost,127.0.0.1,*.company.com` | + +#### Advanced Configuration Variables + +| Variable | Purpose | Example | Notes | +|----------|---------|---------|--------| +| `CLAUDE_CODE_CONFIG_DIR` | Custom config directory | `/custom/config` | Override default | +| `CLAUDE_CODE_LOG_LEVEL` | Logging level | `debug` | trace, debug, info, warn, error | +| `CLAUDE_CODE_LOG_FILE` | Custom log file | `/var/log/claude.log` | Override default | +| `CLAUDE_CODE_CACHE_DIR` | Custom cache directory | `/tmp/claude-cache` | Override default | + +### Configuration Management Commands + +#### Basic Configuration +```bash +# Interactive configuration +claude config + +# List all settings +claude config list + +# Get specific value +claude config get +claude config get model +claude config get allowedTools + +# Set values +claude config set # Project scope +claude config set -g # Global scope +claude config set model claude-sonnet-4 +claude config set -g outputFormat json + +# Manage lists +claude config add # Add to list +claude config remove # Remove from list +claude config add allowedTools "Edit" +claude config remove disallowedTools "Bash" +``` + +#### Advanced Configuration +```bash +# Configuration validation +claude config validate # Check config validity +claude config migrate # Migrate old config format + +# Import/export +claude config export > my-config.json # Export configuration +claude config import my-config.json # Import configuration + +# Reset configuration +claude config reset # Reset to defaults +claude config reset --global # Reset global config +claude config reset --project # Reset project config +``` + +### Configuration Templates + +#### Development Environment Template +```json +{ + "model": "claude-sonnet-4", + "allowedTools": [ + "Edit", + "View", + "Bash(git:*)", + "Bash(npm:*)", + "Bash(yarn:*)", + "mcp__git__*" + ], + "maxTurns": 20, + "verbose": true, + "systemPrompt": "You are an expert developer. Always explain your reasoning and suggest best practices.", + "context": { + "maxTokens": 128000, + "compressionEnabled": true + } +} +``` + +#### Production/CI Template +```json +{ + "model": "claude-sonnet-4", + "allowedTools": [ + "Edit", + "View", + "Bash(git:status)", + "Bash(git:log)", + "mcp__git__status", + "mcp__git__log" + ], + "maxTurns": 5, + "verbose": false, + "outputFormat": "json", + "security": { + "requireConfirmation": false, + "dangerousOperationsAllowed": false + } +} +``` + +#### Data Analysis Template +```json +{ + "model": "claude-opus-4", + "allowedTools": [ + "Edit", + "View", + "mcp__postgres__*", + "mcp__pandas__*", + "mcp__csv__*" + ], + "maxTurns": 30, + "thinkingBudget": 128000, + "systemPrompt": "You are a data scientist. Focus on statistical accuracy and clear visualizations." +} +``` + +### MCP Configuration + +#### MCP Server Configuration File +**Location**: `.claude/mcp.json` + +```json +{ + "mcpServers": { + "git": { + "command": "git-mcp-server", + "args": [], + "env": {}, + "enabled": true, + "autoRestart": true, + "timeout": 10000 + }, + "postgres": { + "command": "postgres-mcp-server", + "args": [ + "--host", "localhost", + "--port", "5432", + "--database", "myapp_development" + ], + "env": { + "POSTGRES_USER": "developer", + "POSTGRES_PASSWORD": "${POSTGRES_PASSWORD}", + "SSL_MODE": "prefer" + }, + "enabled": true, + "healthCheck": { + "enabled": true, + "interval": 30000, + "timeout": 5000 + } + }, + "browser": { + "command": "puppeteer-mcp-server", + "args": ["--headless", "--no-sandbox"], + "env": { + "DISPLAY": ":99" + }, + "enabled": true, + "resources": { + "memory": "1GB", + "cpu": "1" + } + }, + "api_gateway": { + "transport": "http", + "url": "http://localhost:3001/mcp", + "headers": { + "Authorization": "Bearer ${API_TOKEN}", + "Content-Type": "application/json" + }, + "enabled": true, + "retry": { + "attempts": 3, + "delay": 1000 + } + }, + "realtime_service": { + "transport": "sse", + "url": "ws://localhost:8080/mcp-sse", + "enabled": true, + "reconnect": true, + "reconnectInterval": 5000 + } + }, + "global": { + "timeout": 30000, + "maxConcurrentServers": 10, + "healthCheckInterval": 60000, + "logLevel": "info" + } +} +``` + +#### MCP Environment Variables File +**Location**: `~/.claude-code-mcp.env` + +```bash +# Database connections +POSTGRES_PASSWORD=dev_password_123 +MYSQL_PASSWORD=mysql_secret +MONGODB_URI=mongodb://localhost:27017/myapp + +# API tokens +GITHUB_TOKEN=ghp_your_github_token +GITLAB_TOKEN=glpat_your_gitlab_token +JIRA_TOKEN=your_jira_token + +# Cloud service credentials +AWS_ACCESS_KEY_ID=AKIA... +AWS_SECRET_ACCESS_KEY=secret... +GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json + +# Service endpoints +API_GATEWAY_URL=https://api.company.com +ELASTICSEARCH_URL=http://localhost:9200 + +# Feature flags +ENABLE_EXPERIMENTAL_FEATURES=true +DEBUG_MCP_CONNECTIONS=false +``` + +### Context Management Configuration + +#### Memory Configuration +```json +{ + "context": { + "memoryFile": "CLAUDE.md", + "maxTokens": 128000, + "compressionEnabled": true, + "compressionRatio": 0.7, + "retentionDays": 30, + "autoSave": true, + "backupEnabled": true, + "backupInterval": 3600 + }, + "memory": { + "shortTerm": { + "maxTokens": 32000, + "retentionMinutes": 60 + }, + "longTerm": { + "maxTokens": 96000, + "compressionEnabled": true + }, + "persistent": { + "enabled": true, + "file": "CLAUDE.md", + "autoUpdate": true + } + } +} +``` + +#### Context7 Integration (Advanced Context Management) +```json +{ + "context7": { + "enabled": true, + "memorySize": 1000, + "windowSize": 128000, + "compressionAlgorithm": "semantic", + "priorityWeights": { + "recency": 0.3, + "relevance": 0.4, + "importance": 0.3 + }, + "indexing": { + "enabled": true, + "vectorSize": 1536, + "similarity": "cosine" + } + } +} +``` + +### Configuration Validation + +#### Validation Commands +```bash +# Validate current configuration +claude config validate + +# Validate specific config file +claude config validate ~/.claude.json +claude config validate .claude/settings.json + +# Check for deprecated settings +claude config check-deprecated + +# Verify MCP configuration +claude mcp validate +``` + +#### Common Configuration Issues +```bash +# Fix common issues +claude config fix # Auto-fix issues +claude config migrate # Migrate old format +claude config reset-permissions # Reset tool permissions +claude config clean # Remove invalid entries +``` + +### Environment-Specific Configurations + +#### Development Environment +```bash +# Development-specific settings +export CLAUDE_CODE_LOG_LEVEL=debug +export CLAUDE_CODE_ENABLE_TELEMETRY=1 +export DISABLE_COST_WARNINGS=1 +claude config set verbose true +claude config set allowedTools "Edit,View,Bash,mcp__*__*" +``` + +#### Staging Environment +```bash +# Staging-specific settings +export CLAUDE_CODE_LOG_LEVEL=info +export DISABLE_NON_ESSENTIAL_MODEL_CALLS=1 +claude config set maxTurns 10 +claude config set allowedTools "Edit,View,mcp__git__status" +``` + +#### Production Environment +```bash +# Production-specific settings +export CLAUDE_CODE_LOG_LEVEL=warn +export DISABLE_TELEMETRY=1 +export DISABLE_ERROR_REPORTING=1 +export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 +claude config set maxTurns 5 +claude config set allowedTools "View,mcp__monitoring__*" +claude config set outputFormat json +``` + +--- + +## 🔒 Security & Permissions + +### Security Model Overview + +Claude Code implements a **multi-layered security model**: + +1. **Tool Permission System** - Controls what Claude can do +2. **Network Security** - Controls external connections +3. **File System Access** - Controls file operations +4. **MCP Security** - Controls external integrations +5. **Environment Isolation** - Sandboxing and containers + +### Permission System + +#### How Permissions Work + +**Default Behavior**: Claude asks for permission before using tools +**Permission Memory**: Granted permissions are remembered per session +**Dangerous Operations**: Always require confirmation (unless bypassed) + +#### Permission Levels + +| Level | Description | Risk | Use Case | +|-------|-------------|------|----------| +| **Interactive** | Prompt for each operation | **Low** | Development work | +| **Allowlist** | Pre-approved tools only | **Medium** | Automation scripts | +| **Auto-Accept** | Skip confirmations (`Shift+Tab`) | **High** | Trusted workflows | +| **Dangerous** | Skip all permissions | **CRITICAL** | Containers only | + +#### Tool Permission Patterns + +##### Basic Patterns +```bash +# Allow specific tools +claude --allowedTools "Edit,View" + +# Allow tool categories +claude --allowedTools "Edit,View,Bash" + +# Deny specific tools +claude --disallowedTools "Bash" +``` + +##### Advanced Patterns +```bash +# Scoped permissions (Git operations only) +claude --allowedTools "Bash(git:*)" + +# Multiple scopes +claude --allowedTools "Bash(git:*),Bash(npm:*)" + +# MCP tool permissions +claude --allowedTools "mcp__postgres__query,mcp__git__status" + +# Wildcard MCP permissions +claude --allowedTools "mcp__postgres__*" + +# Read-only patterns +claude --allowedTools "View,mcp__*__read,mcp__*__query" +``` + +##### Complex Permission Examples +```bash +# Development workflow +claude --allowedTools "Edit,View,Bash(git:*),Bash(npm:*),mcp__git__*" + +# Database analysis (read-only) +claude --allowedTools "View,mcp__postgres__query,mcp__postgres__schema" + +# CI/CD pipeline +claude --allowedTools "Edit,View,Bash(git:status),Bash(npm:test),mcp__git__status" + +# Security audit (read-only) +claude --allowedTools "View,mcp__*__read,mcp__*__list" +``` + +### Dangerous Mode (Critical Security Feature) + +#### ⚠️ `--dangerously-skip-permissions` + +**What it does**: Bypasses ALL security checks +**Risk Level**: **CRITICAL** - Can cause data loss, security breaches, system damage + +#### Safe Usage Guidelines + +**✅ Safe Environments:** +```bash +# Isolated Docker container +docker run --rm -it --network none claude-container \ + claude --dangerously-skip-permissions "fix all issues" + +# Dedicated VM +# Virtual machine with no sensitive data or network access + +# Disposable environment +# Environment that can be destroyed after use +``` + +**❌ NEVER Use With:** +- Production systems +- Systems with sensitive data +- Internet-connected systems +- Shared development machines +- Systems with important files + +#### Safer Alternatives to Dangerous Mode + +```bash +# Instead of dangerous mode, use specific allowlists +claude --allowedTools "Edit,View,Bash(git:*),Bash(npm:*)" + +# Use auto-accept mode for trusted workflows +claude "fix linting errors" +# Press Shift+Tab once for auto-accept + +# Use planning mode first +claude "analyze and suggest fixes" +# Press Shift+Tab twice for planning mode +# Review plan, then execute +``` + +### Security Best Practices + +#### 1. Principle of Least Privilege +```bash +# Good: Specific permissions +claude --allowedTools "Edit,View,Bash(git:status)" + +# Bad: Broad permissions +claude --allowedTools "Bash" + +# Good: Read-only analysis +claude --allowedTools "View,mcp__postgres__query" + +# Bad: Full database access +claude --allowedTools "mcp__postgres__*" +``` + +#### 2. Environment Isolation +```bash +# Development container +docker run --rm -v $(pwd):/workspace \ + -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \ + claude-container claude --allowedTools "Edit,View,Bash(git:*)" + +# Network isolation +docker run --rm --network none \ + claude-container claude --dangerously-skip-permissions +``` + +#### 3. Regular Security Audits +```bash +# Check current permissions +claude /permissions + +# Review configuration +claude config get allowedTools +claude config get disallowedTools + +# Security health check +claude /doctor + +# Review MCP servers +claude mcp status +``` + +#### 4. Sensitive Data Protection +```bash +# Use environment variables for secrets +export DB_PASSWORD="secret123" +claude mcp add postgres "postgres-mcp-server --password-env DB_PASSWORD" + +# Avoid embedding secrets in commands +# Good: +claude config set -g githubToken "${GITHUB_TOKEN}" + +# Bad: +claude config set -g githubToken "ghp_actual_token_here" +``` + +### MCP Security + +#### MCP Server Security +```bash +# Secure MCP configuration +claude config set mcpSecurity.requireAuth true +claude config set mcpSecurity.timeout 30000 +claude config set mcpSecurity.maxConnections 5 + +# Network restrictions +claude config set mcpSecurity.allowedHosts "localhost,*.company.com" +claude config set mcpSecurity.allowedPorts "3000-3999,5432" + +# SSL/TLS requirements +claude config set mcpSecurity.requireSSL true +claude config set mcpSecurity.verifySSL true +``` + +#### MCP Authentication +```bash +# Token-based authentication +export MCP_AUTH_TOKEN="your-secure-token" +claude mcp add secure-api "api-mcp-server --auth-token $MCP_AUTH_TOKEN" + +# Certificate-based authentication +claude mcp add secure-db "postgres-mcp-server \ + --ssl-cert /path/to/client.crt \ + --ssl-key /path/to/client.key \ + --ssl-ca /path/to/ca.crt" +``` + +### Network Security + +#### Proxy Configuration +```bash +# Corporate proxy (HTTP/HTTPS) +export HTTP_PROXY="http://proxy.company.com:8080" +export HTTPS_PROXY="https://proxy.company.com:8443" +export NO_PROXY="localhost,127.0.0.1,*.company.com" + +# SOCKS proxy +export ALL_PROXY="socks5://proxy.company.com:1080" + +# Authenticated proxy +export HTTP_PROXY="http://username:password@proxy.company.com:8080" +``` + +#### Network Restrictions +```bash +# Disable non-essential network traffic +export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 + +# Network timeout configuration +claude config set network.timeout 30000 +claude config set network.retries 3 + +# Restrict outbound connections +claude config set network.allowedDomains "api.anthropic.com,*.company.com" +``` + +### File System Security + +#### File Access Controls +```bash +# Restrict file operations to specific directories +claude --add-dir ./src ./tests --allowedTools "Edit,View" + +# Read-only file access +claude --allowedTools "View" + +# Specific file patterns +claude config set fileAccess.allowedPatterns "*.js,*.ts,*.json" +claude config set fileAccess.deniedPatterns "*.env,*.key,*.pem" +``` + +#### Sensitive File Protection +```bash +# Exclude sensitive files from Claude's access +echo "*.env +*.key +*.pem +secrets.json +.ssh/*" > .claude/ignored-files + +# Use .gitignore patterns +claude config set fileAccess.respectGitignore true +``` + +### Security Monitoring + +#### Audit Logging +```bash +# Enable comprehensive logging +export CLAUDE_CODE_LOG_LEVEL=debug +claude config set security.auditLog true +claude config set security.logFile "/var/log/claude-audit.log" + +# Monitor security events +tail -f ~/.claude/logs/security.log | grep "SECURITY" +``` + +#### Permission Tracking +```bash +# Track permission grants +claude config set security.trackPermissions true + +# Review permission history +claude /permissions history + +# Export permission report +claude config export-permissions > permissions-report.json +``` + +### Security Configuration Examples + +#### High-Security Environment +```json +{ + "security": { + "requireConfirmation": true, + "dangerousOperationsAllowed": false, + "auditLog": true, + "trackPermissions": true + }, + "allowedTools": ["View"], + "disallowedTools": ["Bash", "mcp__*__write", "mcp__*__delete"], + "network": { + "allowedDomains": ["api.anthropic.com"], + "timeout": 10000, + "retries": 1 + }, + "fileAccess": { + "readOnly": true, + "allowedPatterns": ["*.md", "*.txt", "*.json"], + "respectGitignore": true + } +} +``` + +#### Development Environment (Balanced Security) +```json +{ + "security": { + "requireConfirmation": true, + "dangerousOperationsAllowed": false + }, + "allowedTools": [ + "Edit", + "View", + "Bash(git:*)", + "Bash(npm:*)", + "mcp__git__*", + "mcp__postgres__query" + ], + "network": { + "timeout": 30000, + "retries": 3 + }, + "fileAccess": { + "allowedPatterns": ["src/**", "tests/**", "docs/**"], + "deniedPatterns": ["*.env", "*.key", ".ssh/*"] + } +} +``` + +#### CI/CD Environment +```json +{ + "security": { + "requireConfirmation": false, + "auditLog": true, + "maxExecutionTime": 300 + }, + "allowedTools": [ + "View", + "Edit", + "Bash(git:status)", + "Bash(npm:test)", + "mcp__git__status" + ], + "outputFormat": "json", + "maxTurns": 5 +} +``` + +### Security Incident Response + +#### Immediate Response +```bash +# Emergency stop +claude /exit +pkill claude + +# Review recent activity +claude config get sessions +tail -100 ~/.claude/logs/claude-code.log + +# Check file modifications +find . -mtime -1 -type f -exec ls -la {} \; +``` + +#### Security Reset +```bash +# Reset all permissions +claude config remove allowedTools +claude config remove disallowedTools + +# Reset MCP servers +claude mcp remove --all + +# Clear sensitive data +rm -rf ~/.claude/cache/* +rm -rf ~/.claude/sessions/* + +# Regenerate API keys +# Visit https://console.anthropic.com and rotate keys +``` + +#### Post-Incident Analysis +```bash +# Generate security report +claude config export-security-report > security-incident-report.json + +# Review audit logs +grep "SECURITY\|ERROR\|WARN" ~/.claude/logs/claude-code.log + +# Check for unauthorized changes +git log --since="1 day ago" --oneline +``` + +--- + +## 🤖 Automation & Scripting ### CI/CD Integration +#### GitHub Actions Integration -Build Pipeline Examples +**Setup GitHub Actions Workflow** (`.github/workflows/claude-review.yml`): +```yaml +name: Claude Code Review +on: + pull_request: + branches: [main, develop] +jobs: + claude-review: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '18' + + - name: Install Claude Code + run: npm install -g @anthropic/claude-code + + - name: Run Claude Code Review + env: + ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} + run: | + claude -p "Review the changes in this PR for security issues, bugs, and code quality" \ + --allowedTools "View,mcp__git__*" \ + --output-format json > review-results.json + + - name: Comment PR + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + const review = JSON.parse(fs.readFileSync('review-results.json', 'utf8')); + + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: `## 🤖 Claude Code Review\n\n${review.response}` + }); +``` + +#### GitLab CI Integration + +**GitLab CI Configuration** (`.gitlab-ci.yml`): +```yaml +stages: + - test + - review + - deploy + +claude-review: + stage: review + image: node:18 + before_script: + - npm install -g @anthropic/claude-code + script: + - | + claude -p "Analyze this merge request for security vulnerabilities and code quality issues" \ + --allowedTools "View,mcp__git__*" \ + --output-format json > review-results.json + - | + if jq -e '.issues[]' review-results.json > /dev/null; then + echo "Code review found issues:" + jq -r '.issues[].message' review-results.json + exit 1 + fi + artifacts: + reports: + codequality: review-results.json + expire_in: 1 week + only: + - merge_requests +``` + +#### Jenkins Pipeline Integration + +**Jenkinsfile**: +```groovy +pipeline { + agent any + + environment { + ANTHROPIC_API_KEY = credentials('anthropic-api-key') + } + + stages { + stage('Setup') { + steps { + sh 'npm install -g @anthropic/claude-code' + } + } + + stage('Code Review') { + steps { + script { + def reviewResult = sh( + script: ''' + claude -p "Review this codebase for security issues and suggest improvements" \ + --allowedTools "View,mcp__git__*" \ + --output-format json + ''', + returnStdout: true + ).trim() + + def review = readJSON text: reviewResult + + if (review.issues) { + currentBuild.result = 'UNSTABLE' + publishHTML([ + allowMissing: false, + alwaysLinkToLastBuild: true, + keepAll: true, + reportDir: '.', + reportFiles: 'review-results.html', + reportName: 'Claude Review Report' + ]) + } + } + } + } + + stage('Deploy') { + when { + branch 'main' + expression { currentBuild.result != 'UNSTABLE' } + } + steps { + sh ''' + claude -p "Execute deployment with safety checks" \ + --allowedTools "Edit,View,Bash(git:*),Bash(npm:*)" \ + --max-turns 10 + ''' + } + } + } + + post { + always { + archiveArtifacts artifacts: 'review-results.json', allowEmptyArchive: true + } + } +} +``` + +### Automated Code Analysis + +#### Pre-commit Hooks + +**Setup Pre-commit Hook** (`.git/hooks/pre-commit`): ```bash -# Automated fixing in build scripts -claude -p "fix linting errors" --dangerously-skip-permissions --output-format json +#!/bin/bash +# .git/hooks/pre-commit -# Controlled tool access -claude -p "run tests and fix failures" --allowedTools "Bash(npm:*),Edit" +set -e -# Pipeline integration -if claude -p "check code quality" --output-format json | jq -r '.passed'; then - echo "Quality checks passed" +# Get list of staged files +staged_files=$(git diff --cached --name-only --diff-filter=ACM) + +if [ -z "$staged_files" ]; then + exit 0 +fi + +echo "🤖 Running Claude Code analysis on staged files..." + +# Analyze staged files +analysis=$(echo "$staged_files" | xargs cat | \ + claude -p "Review these changes for issues before commit. Focus on security, bugs, and style." \ + --allowedTools "View" \ + --output-format json) + +# Check for critical issues +if echo "$analysis" | jq -e '.critical_issues[]' > /dev/null 2>&1; then + echo "❌ Critical issues found:" + echo "$analysis" | jq -r '.critical_issues[].message' + echo "" + echo "Commit blocked. Please fix these issues and try again." + exit 1 +fi + +# Check for warnings +if echo "$analysis" | jq -e '.warnings[]' > /dev/null 2>&1; then + echo "⚠️ Warnings found:" + echo "$analysis" | jq -r '.warnings[].message' + echo "" + read -p "Continue with commit? (y/N): " -n 1 -r + echo + if [[ ! $REPLY =~ ^[Yy]$ ]]; then + exit 1 + fi +fi + +echo "✅ Code analysis passed" +``` + +#### Automated Fix Scripts + +**Auto-fix Script** (`scripts/auto-fix.sh`): +```bash +#!/bin/bash +# scripts/auto-fix.sh + +set -e + +echo "🔧 Running automated fixes..." + +# Backup current state +git stash push -m "Before auto-fix $(date)" + +# Run Claude auto-fix +claude -p "Fix all linting errors, formatting issues, and simple bugs in this codebase" \ + --allowedTools "Edit,View,Bash(npm:*),Bash(git:*)" \ + --max-turns 20 \ + --output-format json > fix-results.json + +# Check if fixes were successful +if jq -e '.success' fix-results.json > /dev/null; then + echo "✅ Auto-fix completed successfully" + + # Show what was changed + git diff --stat + + # Commit fixes + git add -A + git commit -m "Auto-fix: $(jq -r '.summary' fix-results.json)" + + # Drop the stash + git stash drop else - echo "Quality issues found" - exit 1 + echo "❌ Auto-fix failed, restoring previous state" + git stash pop + exit 1 fi ``` +### Monitoring & Logging +#### System Monitoring Script -### Scripting Integration - - -Automation Scripts - +**Monitoring Script** (`scripts/monitor.sh`): ```bash -# Log analysis -cat error.log | claude -p "summarize errors" --output-format json > summary.json +#!/bin/bash +# scripts/monitor.sh -# Batch processing -for file in *.py; do - claude -p "review this Python file" < "$file" --output-format text >> review.txt +LOGFILE="/var/log/claude-monitor.log" +ALERT_EMAIL="admin@company.com" + +while true; do + # Collect system metrics + metrics=$(cat << EOF +{ + "timestamp": "$(date -Iseconds)", + "cpu_usage": $(top -bn1 | grep "Cpu(s)" | awk '{print $2}' | cut -d'%' -f1), + "memory_usage": $(free | grep Mem | awk '{printf "%.2f", $3/$2 * 100.0}'), + "disk_usage": $(df -h / | awk 'NR==2{print $5}' | cut -d'%' -f1), + "load_average": "$(uptime | awk -F'load average:' '{print $2}')", + "active_connections": $(netstat -an | grep ESTABLISHED | wc -l) +} +EOF + ) + + # Analyze metrics with Claude + analysis=$(echo "$metrics" | \ + claude -p "Analyze these system metrics and alert if anything is concerning" \ + --allowedTools "View" \ + --output-format json) + + # Log analysis + echo "$analysis" >> "$LOGFILE" + + # Check for alerts + if echo "$analysis" | jq -e '.alerts[]' > /dev/null; then + alert_message=$(echo "$analysis" | jq -r '.alerts[].message') + echo "ALERT: $alert_message" | mail -s "System Alert" "$ALERT_EMAIL" + fi + + # Wait 5 minutes + sleep 300 +done +``` + +#### Log Analysis Automation + +**Log Analysis Script** (`scripts/analyze-logs.sh`): +```bash +#!/bin/bash +# scripts/analyze-logs.sh + +# Analyze different types of logs +analyze_application_logs() { + echo "📊 Analyzing application logs..." + + tail -1000 /var/log/app.log | \ + claude -p "Analyze these application logs for errors, patterns, and issues" \ + --allowedTools "View" \ + --output-format json > app-log-analysis.json +} + +analyze_security_logs() { + echo "🔒 Analyzing security logs..." + + sudo tail -500 /var/log/auth.log | \ + claude -p "Analyze these security logs for suspicious activity" \ + --allowedTools "View" \ + --output-format json > security-log-analysis.json +} + +analyze_performance_logs() { + echo "⚡ Analyzing performance logs..." + + tail -500 /var/log/nginx/access.log | \ + claude -p "Analyze these access logs for performance issues and patterns" \ + --allowedTools "View" \ + --output-format json > performance-log-analysis.json +} + +# Generate comprehensive report +generate_report() { + echo "📄 Generating comprehensive report..." + + claude -p "Create a comprehensive system health report based on these log analyses" \ + --allowedTools "View,Edit" \ + app-log-analysis.json security-log-analysis.json performance-log-analysis.json +} + +# Run all analyses +analyze_application_logs +analyze_security_logs +analyze_performance_logs +generate_report +``` + +### Database Maintenance Automation + +#### Database Health Check + +**Database Monitoring** (`scripts/db-health.sh`): +```bash +#!/bin/bash +# scripts/db-health.sh + +export POSTGRES_URL="postgresql://user:pass@localhost:5432/mydb" + +# Setup PostgreSQL MCP +claude mcp add postgres "postgres-mcp-server --url $POSTGRES_URL" + +# Comprehensive database analysis +claude -p "Perform a comprehensive database health check including: +- Query performance analysis +- Index optimization suggestions +- Table statistics review +- Connection analysis +- Storage optimization recommendations" \ + --allowedTools "mcp__postgres__*,Edit,View" \ + --output-format json > db-health-report.json + +# Check for critical issues +if jq -e '.critical_issues[]' db-health-report.json > /dev/null; then + echo "🚨 Critical database issues found!" + jq -r '.critical_issues[].message' db-health-report.json + + # Send alert + mail -s "Critical Database Issues" admin@company.com < db-health-report.json +fi + +# Apply safe optimizations +if jq -e '.safe_optimizations[]' db-health-report.json > /dev/null; then + echo "🔧 Applying safe optimizations..." + + claude -p "Apply the safe optimizations identified in the health check" \ + --allowedTools "mcp__postgres__*" \ + --max-turns 10 +fi +``` + +### Deployment Automation + +#### Automated Deployment Pipeline + +**Deployment Script** (`scripts/deploy.sh`): +```bash +#!/bin/bash +# scripts/deploy.sh + +ENVIRONMENT=${1:-staging} +BRANCH=${2:-main} + +echo "🚀 Starting deployment to $ENVIRONMENT from $BRANCH" + +# Pre-deployment checks +claude -p "Perform pre-deployment checks: +- Verify all tests pass +- Check for security vulnerabilities +- Validate configuration +- Ensure database migrations are ready" \ + --allowedTools "View,Bash(git:*),Bash(npm:*),mcp__git__*" \ + --output-format json > pre-deployment-check.json + +# Check if pre-deployment passed +if ! jq -e '.ready_for_deployment' pre-deployment-check.json > /dev/null; then + echo "❌ Pre-deployment checks failed" + jq -r '.issues[].message' pre-deployment-check.json + exit 1 +fi + +# Execute deployment +case $ENVIRONMENT in + "staging") + deploy_to_staging + ;; + "production") + deploy_to_production + ;; + *) + echo "Unknown environment: $ENVIRONMENT" + exit 1 + ;; +esac + +# Post-deployment verification +claude -p "Verify deployment success: +- Check application health endpoints +- Verify database connectivity +- Test critical user flows +- Monitor error rates" \ + --allowedTools "mcp__http__*,mcp__postgres__*,View" \ + --output-format json > post-deployment-check.json + +# Report results +if jq -e '.deployment_successful' post-deployment-check.json > /dev/null; then + echo "✅ Deployment to $ENVIRONMENT completed successfully" + + # Send success notification + slack_notify "✅ Deployment to $ENVIRONMENT completed successfully" +else + echo "❌ Deployment verification failed" + jq -r '.issues[].message' post-deployment-check.json + + # Initiate rollback + echo "🔄 Initiating rollback..." + rollback_deployment +fi +``` + +### Batch Processing Scripts + +#### File Processing Automation + +**Batch File Processor** (`scripts/process-files.sh`): +```bash +#!/bin/bash +# scripts/process-files.sh + +DIRECTORY=${1:-.} +PATTERN=${2:-"*.js"} + +echo "📁 Processing files matching $PATTERN in $DIRECTORY" + +# Find and process files +find "$DIRECTORY" -name "$PATTERN" -type f | while read -r file; do + echo "Processing: $file" + + # Analyze and improve each file + claude -p "Analyze and improve this file: + - Fix any bugs or issues + - Improve code quality and readability + - Add documentation if missing + - Optimize performance where possible" \ + --allowedTools "Edit,View" \ + --max-turns 5 \ + < "$file" + + # Validate changes + if [[ "$file" == *.js ]]; then + # Validate JavaScript syntax + node -c "$file" || { + echo "❌ Syntax error in $file, reverting changes" + git checkout "$file" + } + fi done -# Monitoring integration -journal_errors=$(journalctl --since "1 hour ago" --priority=err) -echo "$journal_errors" | claude -p "analyze system errors" --output-format json > /tmp/error_analysis.json +echo "✅ Batch processing completed" ``` +#### Data Migration Automation +**Data Migration Script** (`scripts/migrate-data.sh`): +```bash +#!/bin/bash +# scripts/migrate-data.sh -## Troubleshooting +SOURCE_DB="postgresql://user:pass@old-server:5432/olddb" +TARGET_DB="postgresql://user:pass@new-server:5432/newdb" -### Health Checks +# Setup MCP servers for both databases +claude mcp add source_db "postgres-mcp-server --url $SOURCE_DB" +claude mcp add target_db "postgres-mcp-server --url $TARGET_DB" -| Command | Purpose | When to Use | -|---------|---------|-------------| -| `claude --help` | 📚 Show all options | Getting started | -| `/doctor` | 🩺 Health check | Something's wrong | -| `/status` | 📊 Current config | Check settings | -| `claude config list` | 📝 List all settings | Audit configuration | +# Plan migration +claude -p "Analyze both databases and create a comprehensive data migration plan: +- Compare schemas +- Identify data transformation needs +- Plan migration order to handle dependencies +- Estimate migration time and resources" \ + --allowedTools "mcp__source_db__*,mcp__target_db__*,Edit,View" \ + --output-format json > migration-plan.json -### Debug Mode +# Execute migration +if jq -e '.migration_approved' migration-plan.json > /dev/null; then + echo "🔄 Executing data migration..." + + claude -p "Execute the data migration plan with these requirements: + - Maintain data integrity + - Handle errors gracefully + - Provide progress updates + - Create rollback points" \ + --allowedTools "mcp__source_db__*,mcp__target_db__*,Edit,View" \ + --max-turns 50 \ + --output-format stream-json | tee migration-log.json + + # Verify migration + claude -p "Verify migration success: + - Compare record counts + - Validate data integrity + - Test application functionality + - Generate migration report" \ + --allowedTools "mcp__source_db__*,mcp__target_db__*,View" \ + --output-format json > migration-verification.json +else + echo "❌ Migration plan not approved" + jq -r '.issues[].message' migration-plan.json +fi +``` -Debug Commands +### Container & Docker Integration + +#### Docker Health Monitoring + +**Docker Monitor Script** (`scripts/docker-monitor.sh`): +```bash +#!/bin/bash +# scripts/docker-monitor.sh + +# Setup Docker MCP +claude mcp add docker "docker-mcp-server" + +# Monitor containers +while true; do + echo "🐳 Monitoring Docker containers..." + + claude -p "Monitor Docker environment: + - Check container health status + - Analyze resource usage + - Identify performance issues + - Suggest optimizations + - Alert on critical issues" \ + --allowedTools "mcp__docker__*,View" \ + --output-format json > docker-status.json + + # Check for alerts + if jq -e '.alerts[]' docker-status.json > /dev/null; then + echo "🚨 Docker alerts detected!" + jq -r '.alerts[].message' docker-status.json + + # Auto-remediation for common issues + claude -p "Automatically remediate common Docker issues found in the monitoring report" \ + --allowedTools "mcp__docker__*" \ + --max-turns 5 + fi + + sleep 300 # Check every 5 minutes +done +``` + +#### Automated Docker Builds + +**Docker Build Automation** (`scripts/docker-build.sh`): +```bash +#!/bin/bash +# scripts/docker-build.sh + +IMAGE_NAME=${1:-myapp} +TAG=${2:-latest} + +echo "🏗️ Building Docker image: $IMAGE_NAME:$TAG" + +# Optimize Dockerfile +claude -p "Analyze and optimize this Dockerfile: +- Improve build performance +- Reduce image size +- Enhance security +- Follow best practices" \ + --allowedTools "Edit,View" \ + Dockerfile + +# Build with analysis +docker build -t "$IMAGE_NAME:$TAG" . 2>&1 | tee build.log + +# Analyze build +claude -p "Analyze this Docker build log for issues and optimization opportunities" \ + --allowedTools "View" \ + --output-format json \ + build.log > build-analysis.json + +# Security scan +claude -p "Perform security analysis of the built Docker image" \ + --allowedTools "mcp__docker__*,View" \ + --output-format json > security-scan.json + +# Generate report +claude -p "Create comprehensive Docker build report including build analysis and security scan" \ + --allowedTools "Edit,View" \ + build-analysis.json security-scan.json > build-report.md + +echo "✅ Docker build completed. Report: build-report.md" +``` + +### Performance Optimization Automation + +#### Automated Performance Testing + +**Performance Test Script** (`scripts/performance-test.sh`): +```bash +#!/bin/bash +# scripts/performance-test.sh + +URL=${1:-"http://localhost:3000"} +DURATION=${2:-"5m"} + +echo "⚡ Running performance tests against $URL for $DURATION" + +# Setup monitoring +claude mcp add http "http-client-mcp-server" + +# Run performance test +claude -p "Execute comprehensive performance testing: +- Load testing with gradual ramp-up +- Stress testing to find breaking points +- Endurance testing for memory leaks +- Spike testing for traffic bursts +- Monitor response times and error rates" \ + --allowedTools "mcp__http__*,Edit,View" \ + --max-turns 30 \ + --output-format stream-json | tee performance-test.log + +# Analyze results +claude -p "Analyze performance test results and provide optimization recommendations" \ + --allowedTools "View,Edit" \ + --output-format json \ + performance-test.log > performance-analysis.json + +# Generate optimization plan +if jq -e '.performance_issues[]' performance-analysis.json > /dev/null; then + claude -p "Create detailed performance optimization plan based on test results" \ + --allowedTools "Edit,View" \ + performance-analysis.json > optimization-plan.md + + echo "📊 Performance issues found. See optimization-plan.md" +else + echo "✅ Performance tests passed without issues" +fi +``` + +--- + +## 🔧 Troubleshooting + +### Diagnostic Commands + +#### Essential Health Checks + +| Command | Purpose | When to Use | Expected Output | +|---------|---------|-------------|-----------------| +| `claude /doctor` | Complete system health check | First step for any issue | ✅ All systems operational | +| `claude /status` | Current configuration overview | Check settings and state | Configuration summary | +| `claude --help` | Show all available options | Get help with commands | Help documentation | +| `claude config list` | List all configuration settings | Audit configuration | All settings displayed | +| `claude --version` | Show Claude Code version | Version compatibility check | claude-code v1.0.25 | + +#### Advanced Diagnostics ```bash -# Detailed logging -claude --verbose +# Comprehensive diagnostic +claude /doctor --verbose -# Full debug mode -claude --debug +# Network connectivity test +claude -p "test connection" --verbose -# MCP-specific debugging -claude --mcp-debug +# MCP server diagnostics +claude --mcp-debug /doctor -# Combined debugging -claude --verbose --debug --mcp-debug +# Configuration validation +claude config validate + +# Permission audit +claude /permissions --detailed ``` +### Common Issues & Solutions +#### 1. Authentication Issues -### Reset & Recovery +**Problem**: `Authentication failed` or `Invalid API key` +**Diagnosis**: +```bash +# Check API key +echo $ANTHROPIC_API_KEY +# Should show: sk-ant-api03-... -Emergency Recovery +# Validate key format +if [[ $ANTHROPIC_API_KEY =~ ^sk-ant-api03-.{95}$ ]]; then + echo "✅ API key format is valid" +else + echo "❌ Invalid API key format" +fi +# Test API connection +claude -p "hello" --verbose +``` + +**Solutions**: ```bash # Reset authentication rm -rf ~/.config/claude-code/auth.json - -# Clean logout/login claude /logout claude /login -# Reset all settings -rm -rf ~/.claude.json -rm -rf .claude/settings.json +# Set correct API key +export ANTHROPIC_API_KEY="sk-ant-api03-your-correct-key" +echo 'export ANTHROPIC_API_KEY="sk-ant-api03-your-key"' >> ~/.bashrc -# Full health check after reset +# Verify permissions +claude -p "test authentication" +``` + +#### 2. MCP Server Issues + +**Problem**: `MCP server failed to start` or `Connection timeout` + +**Diagnosis**: +```bash +# Check MCP configuration +claude config get mcp +claude mcp status + +# Debug MCP servers +claude --mcp-debug + +# Test server manually +npx postgres-mcp-server --help +npx git-mcp-server --version + +# Check MCP logs +tail -f ~/.claude/logs/mcp-*.log +``` + +**Solutions**: +```bash +# Restart MCP servers +claude mcp restart --all + +# Reinstall problematic server +claude mcp remove postgres +npm install -g @anthropic/postgres-mcp-server +claude mcp add postgres "postgres-mcp-server --url $DATABASE_URL" + +# Increase timeout +export MCP_TIMEOUT=30000 +claude config set mcpTimeout 30000 + +# Check dependencies +npm list -g | grep mcp +``` + +#### 3. Permission Issues + +**Problem**: `Permission denied for tool X` or `Tool not allowed` + +**Diagnosis**: +```bash +# Check current permissions +claude /permissions +claude config get allowedTools +claude config get disallowedTools + +# Review permission history +claude /permissions history +``` + +**Solutions**: +```bash +# Allow specific tool +claude config add allowedTools "Edit" +claude config add allowedTools "mcp__git__*" + +# Reset permissions +claude config remove allowedTools +claude config remove disallowedTools + +# Use allowlist approach +claude --allowedTools "Edit,View,Bash(git:*)" + +# Check if tool is properly named +claude config get availableTools +``` + +#### 4. Performance Issues + +**Problem**: `Claude is slow` or `Response timeout` + +**Diagnosis**: +```bash +# Check thinking budget +echo $MAX_THINKING_TOKENS +claude config get thinkingBudget + +# Monitor resource usage +top -p $(pgrep claude) +htop + +# Check network latency +ping api.anthropic.com +curl -w "@curl-format.txt" -o /dev/null -s https://api.anthropic.com +``` + +**Solutions**: +```bash +# Optimize thinking budget +export MAX_THINKING_TOKENS=10000 +claude config set thinkingBudget 10000 + +# Use faster model for quick operations +export ANTHROPIC_SMALL_FAST_MODEL="claude-haiku-3" +claude config set smallFastModel "claude-haiku-3" + +# Disable non-essential features +export DISABLE_NON_ESSENTIAL_MODEL_CALLS=1 +export DISABLE_PROMPT_CACHING=1 + +# Clear cache +rm -rf ~/.claude/cache/* +claude config reset --cache + +# Reduce max turns for automation +claude config set maxTurns 5 +``` + +#### 5. Network Issues + +**Problem**: `Connection timeout`, `Network error`, or `Proxy issues` + +**Diagnosis**: +```bash +# Test basic connectivity +ping api.anthropic.com +nslookup api.anthropic.com +curl -I https://api.anthropic.com + +# Check proxy settings +echo $HTTP_PROXY +echo $HTTPS_PROXY +echo $NO_PROXY + +# Test with proxy +curl --proxy $HTTP_PROXY -I https://api.anthropic.com +``` + +**Solutions**: +```bash +# Configure proxy +export HTTP_PROXY="http://proxy.company.com:8080" +export HTTPS_PROXY="https://proxy.company.com:8443" +export NO_PROXY="localhost,127.0.0.1,*.company.com" + +# For authenticated proxy +export HTTP_PROXY="http://username:password@proxy.company.com:8080" + +# Increase network timeout +claude config set network.timeout 60000 +claude config set network.retries 5 + +# Disable non-essential traffic +export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 + +# Test without proxy +unset HTTP_PROXY HTTPS_PROXY +claude -p "test connection" +``` + +#### 6. Model Issues + +**Problem**: `Model not available`, `Rate limited`, or `Model error` + +**Diagnosis**: +```bash +# Check current model +claude config get model +claude /status | grep -i model + +# Check available models +claude /models + +# Check rate limits +claude /cost +``` + +**Solutions**: +```bash +# Switch to available model +claude config set model claude-sonnet-4 +claude config set model claude-haiku-3 + +# Use alternative provider +claude --use-bedrock "test query" +claude --use-vertex "test query" + +# Check API quota +# Visit https://console.anthropic.com/settings/limits + +# Implement rate limiting +claude config set rateLimiting true +claude config set requestDelay 1000 +``` + +#### 7. File Permission Issues + +**Problem**: `Cannot read/write files` or `Access denied` + +**Diagnosis**: +```bash +# Check file permissions +ls -la +pwd +whoami + +# Check working directories +claude /status | grep -i directory +claude config get addDirs + +# Test file access +touch test.txt +echo "test" > test.txt +cat test.txt +rm test.txt +``` + +**Solutions**: +```bash +# Fix file permissions +chmod 644 file.txt +chmod 755 directory/ + +# Add working directory +claude --add-dir $(pwd) +claude config add addDirs "$(pwd)" + +# Allow file operations +claude config add allowedTools "Edit" +claude config add allowedTools "View" + +# Check if files are ignored +cat .gitignore +cat .claude/ignored-files +``` + +### Debug Mode & Logging + +#### Enable Debug Mode + +```bash +# Enable all debugging +claude --verbose --debug --mcp-debug + +# Debug levels +export CLAUDE_CODE_LOG_LEVEL=debug # trace, debug, info, warn, error +export CLAUDE_CODE_LOG_LEVEL=trace # Most detailed + +# Debug specific components +export MCP_DEBUG=1 # MCP debugging +export MCP_TRACE=1 # MCP tracing +export CLAUDE_DEBUG_TOOLS=1 # Tool debugging +export CLAUDE_DEBUG_PERMISSIONS=1 # Permission debugging +``` + +#### Log Analysis + +```bash +# View recent logs +tail -f ~/.claude/logs/claude-code.log + +# Search for errors +grep -i error ~/.claude/logs/claude-code.log +grep -i "mcp" ~/.claude/logs/claude-code.log +grep -i "permission" ~/.claude/logs/claude-code.log + +# Analyze logs with Claude +tail -200 ~/.claude/logs/claude-code.log | \ + claude -p "analyze these logs for issues and patterns" \ + --allowedTools "View" + +# Log rotation +find ~/.claude/logs -name "*.log" -size +100M -exec gzip {} \; +``` + +#### Advanced Debugging + +```bash +# Trace API calls +export ANTHROPIC_LOG_LEVEL=debug +strace -e trace=network -p $(pgrep claude) + +# Monitor system calls +strace -o claude-trace.log claude -p "test" + +# Monitor file access +inotifywait -m -r --format '%w%f %e' ~/.claude/ + +# Network monitoring +tcpdump -i any host api.anthropic.com + +# Memory usage monitoring +valgrind --tool=memcheck claude -p "test" +``` + +### Recovery Procedures + +#### Complete System Reset + +```bash +# 1. Backup important data +cp ~/.claude.json ~/.claude.json.backup +cp -r .claude .claude.backup +cp -r ~/.config/claude-code ~/.config/claude-code.backup + +# 2. Stop all Claude processes +pkill claude +pkill -f mcp-server + +# 3. Reset configuration +rm -rf ~/.claude.json +rm -rf ~/.config/claude-code/ +rm -rf .claude/ + +# 4. Clear cache and logs +rm -rf ~/.claude/cache/* +rm -rf ~/.claude/logs/* +rm -rf ~/.claude/sessions/* + +# 5. Reinstall Claude Code +npm uninstall -g @anthropic/claude-code +npm install -g @anthropic/claude-code + +# 6. Reconfigure +claude config claude /doctor ``` +#### Session Recovery +```bash +# List available sessions +claude config get sessions +ls ~/.claude/sessions/ -## Beta Features +# Recover specific session +claude -r session_id -### Interactive Mode Controls +# Recover from backup +cp ~/.claude/sessions/session_backup.json ~/.claude/sessions/current.json +claude -c -| Shortcut | Action | Mode | -|----------|--------|------| -| `Shift+Tab` (1x) | Auto-Accept | Skip confirmations | -| `Shift+Tab` (2x) | Planning | Analyze without writing | -| `Escape` | Interrupt | Stop Claude anytime | -| `Escape` (2x) | History | Edit previous prompts | +# Clean corrupted sessions +rm -rf ~/.claude/sessions/* +claude /clear +``` -### Thinking Budget Control +#### MCP Recovery -> **Secret**: Special phrases control AI thinking depth +```bash +# Reset all MCP servers +claude mcp remove --all +rm -rf .claude/mcp.json +# Reinstall MCP servers +npm install -g @anthropic/git-mcp-server +npm install -g @anthropic/postgres-mcp-server +npm install -g @anthropic/puppeteer-mcp-server -Thinking Levels +# Reconfigure MCP +claude mcp add git "git-mcp-server" +claude mcp add postgres "postgres-mcp-server" +claude mcp status +``` -| Phrase | Thinking Budget | Use Case | -|--------|----------------|----------| -| `"think"` | 1,024 tokens | Basic analysis | -| `"think hard"` | Enhanced | Complex problems | -| `"think harder"` | Advanced | Deep analysis | -| `"think more"` | Alternative enhanced | Thorough review | -| `"ultrathink"` | 128K tokens | Maximum depth | -| `"megathink"` | Alternative max | Alternative maximum | +### Error Code Reference + +#### Common Error Codes + +| Error Code | Description | Solution | +|------------|-------------|----------| +| `AUTH_001` | Invalid API key | Check and reset API key | +| `AUTH_002` | Expired token | Refresh authentication | +| `NET_001` | Connection timeout | Check network/proxy | +| `NET_002` | DNS resolution failed | Check DNS settings | +| `MCP_001` | Server startup failed | Restart MCP server | +| `MCP_002` | Connection refused | Check server status | +| `PERM_001` | Tool not allowed | Update allowedTools | +| `PERM_002` | Permission denied | Grant tool permissions | +| `FILE_001` | File not found | Check file path | +| `FILE_002` | Permission denied | Fix file permissions | +| `MODEL_001` | Model not available | Switch model | +| `MODEL_002` | Rate limit exceeded | Wait or upgrade plan | + +#### Error Investigation + +```bash +# Get detailed error information +claude /doctor --error-details + +# Search for specific error +grep "AUTH_001" ~/.claude/logs/claude-code.log + +# Get error context +claude -p "explain error code AUTH_001" --allowedTools "View" + +# Report error +claude /bug # If bug reporting is enabled +``` + +### Performance Optimization + +#### System Performance + +```bash +# Monitor Claude performance +time claude -p "test performance" +/usr/bin/time -v claude -p "complex analysis" + +# Memory optimization +export NODE_OPTIONS="--max-old-space-size=4096" +ulimit -m 4194304 # 4GB memory limit + +# CPU optimization +nice -n 10 claude -p "background task" +taskset -c 0-3 claude -p "cpu intensive task" + +# Disk I/O optimization +ionice -c 3 claude -p "disk intensive task" +``` + +#### Configuration Optimization + +```bash +# Optimize for speed +claude config set thinkingBudget 5000 +claude config set maxTurns 5 +claude config set outputFormat text +export DISABLE_NON_ESSENTIAL_MODEL_CALLS=1 + +# Optimize for quality +claude config set model claude-opus-4 +claude config set thinkingBudget 128000 +claude config set maxTurns 30 + +# Optimize for cost +claude config set model claude-haiku-3 +claude config set thinkingBudget 1000 +export DISABLE_PROMPT_CACHING=1 +``` + +### Monitoring & Alerts + +#### Health Monitoring Script + +```bash +#!/bin/bash +# health-monitor.sh + +LOGFILE="/var/log/claude-health.log" +ALERT_THRESHOLD=5 + +check_claude_health() { + local start_time=$(date +%s) + + # Test basic functionality + if timeout 30 claude -p "health check test" > /dev/null 2>&1; then + local end_time=$(date +%s) + local duration=$((end_time - start_time)) + echo "$(date): Health check passed (${duration}s)" >> "$LOGFILE" + return 0 + else + echo "$(date): Health check failed" >> "$LOGFILE" + return 1 + fi +} + +main() { + local failures=0 + + while true; do + if check_claude_health; then + failures=0 + else + failures=$((failures + 1)) + + if [ $failures -ge $ALERT_THRESHOLD ]; then + echo "ALERT: Claude Code health check failed $failures times" | \ + mail -s "Claude Code Alert" admin@company.com + + # Attempt automatic recovery + systemctl restart claude-code 2>/dev/null || \ + service claude-code restart 2>/dev/null + + failures=0 + fi + fi + + sleep 60 # Check every minute + done +} + +main "$@" +``` + +#### Alert Integration + +```bash +# Slack integration +send_slack_alert() { + local message="$1" + local webhook_url="YOUR_SLACK_WEBHOOK_URL" + + curl -X POST -H 'Content-type: application/json' \ + --data "{\"text\":\"🚨 Claude Code Alert: $message\"}" \ + "$webhook_url" +} + +# Email alerts +send_email_alert() { + local subject="$1" + local message="$2" + + echo "$message" | mail -s "$subject" admin@company.com +} + +# PagerDuty integration +send_pagerduty_alert() { + local severity="$1" + local summary="$2" + + curl -X POST 'https://events.pagerduty.com/v2/enqueue' \ + -H 'Content-Type: application/json' \ + -d "{ + \"routing_key\": \"YOUR_ROUTING_KEY\", + \"event_action\": \"trigger\", + \"payload\": { + \"summary\": \"$summary\", + \"severity\": \"$severity\", + \"source\": \"claude-code\" + } + }" +} +``` + +--- + +## 🚀 Advanced Features + +### Context Management & Memory + +#### Understanding Claude's Memory System + +Claude Code uses a **multi-tiered memory system**: + +1. **Session Memory** - Current conversation context +2. **Project Memory** - Persistent project knowledge (`CLAUDE.md`) +3. **Working Memory** - Temporary context from files and tools +4. **Long-term Memory** - Compressed historical context + +#### CLAUDE.md - Project Memory File + +**Purpose**: Persistent context that Claude remembers across sessions + +**Location**: Project root directory + +**Example CLAUDE.md**: +```markdown +# Project: E-commerce Platform + +## Overview +This is a React/Node.js e-commerce platform with PostgreSQL database. + +## Architecture +- Frontend: React 18 with TypeScript +- Backend: Node.js with Express +- Database: PostgreSQL 14 +- Cache: Redis +- Queue: Bull (Redis-based) + +## Key Components + +### Frontend (`/src`) +- `/components` - Reusable UI components +- `/pages` - Route components +- `/hooks` - Custom React hooks +- `/services` - API integration +- `/utils` - Helper functions +- `/types` - TypeScript definitions + +### Backend (`/server`) +- `/routes` - API endpoints +- `/models` - Database models (Sequelize) +- `/middleware` - Express middleware +- `/services` - Business logic +- `/utils` - Server utilities + +### Database (`/database`) +- `/migrations` - Database migrations +- `/seeders` - Test data +- `/schemas` - Schema definitions + +## Current Sprint Goals +- [ ] Implement user authentication with JWT +- [ ] Add shopping cart functionality +- [ ] Set up payment processing with Stripe +- [ ] Implement order management system +- [ ] Add email notifications + +## Development Guidelines + +### Code Standards +- Use TypeScript for all new code +- Follow ESLint configuration +- Use Prettier for formatting +- Write tests for all new features +- Use conventional commits + +### Database Guidelines +- All migrations must be reversible +- Use transactions for multi-table operations +- Index foreign keys and frequently queried columns +- Use soft deletes for user data + +### API Guidelines +- RESTful endpoints +- Consistent error responses +- Rate limiting on public endpoints +- API versioning (v1, v2, etc.) + +## Known Issues +- Memory leak in WebSocket connections (Issue #234) +- Slow query on user dashboard (users table needs indexing) +- Cart persistence issues with Redis timeout + +## Recent Changes +- 2025-06-20: Added Redis for session storage +- 2025-06-19: Implemented JWT authentication +- 2025-06-18: Migrated from MySQL to PostgreSQL + +## Team Context +- John (Frontend Lead) - Working on React components +- Sarah (Backend Lead) - API development and database design +- Mike (DevOps) - Docker, CI/CD, and deployment +- Lisa (QA) - Test automation and quality assurance + +## External Integrations +- Stripe: Payment processing +- SendGrid: Email delivery +- AWS S3: File storage +- Cloudflare: CDN and security +- Sentry: Error tracking +``` + +#### Memory Management Commands + +```bash +# View current memory +claude /memory +claude /memory view + +# Edit project memory +claude /memory edit + +# Use custom memory file +claude --memory-file custom-context.md + +# Memory statistics +claude /cost # Shows memory token usage + +# Compress memory +claude /compact +``` + +#### Advanced Memory Configuration + +```json +{ + "memory": { + "projectFile": "CLAUDE.md", + "maxTokens": 128000, + "compression": { + "enabled": true, + "algorithm": "semantic", + "threshold": 0.8 + }, + "retention": { + "sessionDays": 7, + "projectDays": 30, + "compressionDays": 7 + }, + "indexing": { + "enabled": true, + "vectorSize": 1536, + "similarity": "cosine" + } + } +} +``` + +### Context7 Integration (Advanced Context Management) + +#### What is Context7? + +**Context7** is an advanced context management system that provides: +- **Extended memory windows** (up to 1M+ tokens) +- **Semantic context compression** +- **Intelligent context prioritization** +- **Multi-modal context handling** + +#### Setup Context7 + +```bash +# Install Context7 MCP server +npm install -g @context7/mcp-server + +# Add to Claude Code +claude mcp add context7 "context7-mcp-server --memory-size 1000 --window-size 128000" + +# Configure Context7 +claude config set context7.enabled true +claude config set context7.memorySize 1000 +claude config set context7.windowSize 128000 +``` + +#### Context7 Configuration + +```json +{ + "context7": { + "enabled": true, + "memorySize": 1000, + "windowSize": 128000, + "compressionAlgorithm": "semantic", + "priorityWeights": { + "recency": 0.3, + "relevance": 0.4, + "importance": 0.3 + }, + "indexing": { + "enabled": true, + "vectorSize": 1536, + "similarity": "cosine", + "updateFrequency": "realtime" + }, + "multiModal": { + "images": true, + "code": true, + "documents": true + } + } +} +``` + +#### Using Context7 + +```bash +# Analyze large codebase with Context7 +claude --context-window 128000 "analyze this entire codebase for architectural issues" + +# Multi-modal context +claude "analyze this screenshot alongside the related code files" + +# Long-term project analysis +claude "based on our 6-month development history, suggest architectural improvements" +``` + +### Extended Thinking Capabilities + +#### Thinking Control Phrases + +Claude's thinking depth can be controlled with special phrases: + +| Phrase | Budget | Tokens | Best For | +|--------|--------|--------|----------| +| `"think"` | Basic | 1,024 | Quick analysis | +| `"think about"` | Basic | 1,024 | Simple problems | +| `"think hard"` | Enhanced | ~5,000 | Complex problems | +| `"think harder"` | Advanced | ~10,000 | Deep analysis | +| `"think deeply"` | Advanced | ~10,000 | Thorough research | +| `"think more"` | Enhanced | ~5,000 | Additional consideration | +| `"ultrathink"` | Maximum | 128,000 | Extremely complex analysis | +| `"megathink"` | Maximum | 128,000 | Comprehensive research | + +#### Thinking Examples -**Examples:** ```bash # Basic thinking -claude "think about this algorithm" +claude "think about the best way to optimize this database query" # Enhanced thinking -claude "think hard about the security implications" +claude "think hard about the security implications of this authentication system" # Maximum thinking -claude "ultrathink about this database migration" +claude "ultrathink about the entire system architecture and provide a comprehensive analysis with detailed recommendations" + +# Thinking with tool use (experimental) +claude "ultrathink about this codebase and use tools as needed to understand it fully" ``` - - -### Extended Thinking Mode - - -Advanced Thinking Controls +#### Custom Thinking Budget ```bash -# Slash command trigger -/think +# Set custom thinking budget +export MAX_THINKING_TOKENS=50000 +claude config set thinkingBudget 50000 -# Custom budget (proposed) ---thinking-budget 50000 +# Per-command thinking budget +claude --thinking-budget 25000 "analyze this complex system" ``` +### Interactive Mode Advanced Features +#### Keyboard Shortcuts & Modes -### Permission Prompt Tool Integration +| Shortcut | Mode | Description | Use Case | +|----------|------|-------------|----------| +| `Shift+Tab` (1x) | **Auto-Accept** | Skip confirmations | Trusted workflows | +| `Shift+Tab` (2x) | **Planning** | Analyze without executing | Review before action | +| `Escape` | **Interrupt** | Stop immediately | Emergency stop | +| `Escape` (2x) | **History** | Edit previous prompts | Refine queries | +| `Ctrl+L` | **Clear Screen** | Clear display | Clean interface | +| `Ctrl+R` | **Search History** | Search commands | Find previous work | +#### Planning Mode Workflow -Custom Permission Handler +```bash +# Start Claude +claude "I need to refactor this user authentication system" -The `--permission-prompt-tool` expects an MCP tool that returns JSON: +# Enter planning mode (Shift+Tab twice) +# Claude analyzes and creates a plan without executing + +# Review the plan +# If satisfied, exit planning mode to execute +# If not, modify the request and plan again +``` + +#### Auto-Accept Mode + +```bash +# Start task +claude "fix all linting errors in this project" + +# Enable auto-accept (Shift+Tab once) +# Claude will execute all operations without asking for confirmation + +# Use carefully - only for trusted operations +``` + +### Multi-Directory Workspaces + +#### Working Across Multiple Projects + +```bash +# Add multiple directories +claude --add-dir ../frontend ../backend ../shared ../docs + +# Project-wide analysis +claude "analyze the entire application architecture across all directories" + +# Cross-project refactoring +claude "refactor the authentication system across frontend and backend" +``` + +#### Workspace Configuration -#### **Allow Execution** ```json { - "behavior": "allow", - "updatedInput": {...} // original or modified input + "workspace": { + "directories": [ + "../frontend", + "../backend", + "../shared", + "../infrastructure" + ], + "excludePatterns": [ + "node_modules", + "dist", + "build", + ".git" + ], + "includePatterns": [ + "*.js", + "*.ts", + "*.jsx", + "*.tsx", + "*.json", + "*.md" + ] + } } ``` -#### **Deny Execution** +### AI Model Management + +#### Model Selection Strategies + +```bash +# Development work (balanced) +claude config set model claude-sonnet-4 + +# Complex analysis (highest quality) +claude config set model claude-opus-4 + +# Quick tasks (fastest) +claude config set model claude-haiku-3 + +# Per-session model selection +claude --model claude-opus-4 "perform comprehensive security audit" +``` + +#### Model-Specific Configurations + ```json { - "behavior": "deny", - "message": "Reason for denial" + "models": { + "claude-opus-4": { + "thinkingBudget": 128000, + "maxTurns": 50, + "useFor": ["complex-analysis", "architecture-design"] + }, + "claude-sonnet-4": { + "thinkingBudget": 50000, + "maxTurns": 20, + "useFor": ["development", "code-review"] + }, + "claude-haiku-3": { + "thinkingBudget": 5000, + "maxTurns": 10, + "useFor": ["quick-tasks", "automation"] + } + } } ``` +#### Dynamic Model Switching +```bash +# Automatic model selection based on task complexity +claude config set autoModelSelection true -### GitHub Integration Features +# Custom model switching rules +claude config set modelRules '{ + "security-audit": "claude-opus-4", + "code-review": "claude-sonnet-4", + "linting": "claude-haiku-3" +}' +``` -| Feature | Status | Description | -|---------|--------|-------------| -| `@claude` mentions | **Beta** | PR/Issue mentions | -| GitHub Actions | **Beta** | Automated workflows | -| `gh` CLI integration | **Stable** | Repository operations | -| IDE extensions | **Beta** | VS Code & JetBrains | -| Inline edits | **Beta** | IDE interface edits | +### Advanced Permission System -### Experimental Features +#### Granular Permission Control +```bash +# File-type specific permissions +claude --allowedTools "Edit(*.js),Edit(*.ts),View(*)" -Cutting-Edge Capabilities +# Time-based permissions +claude --allowedTools "Edit" --permission-timeout 3600 # 1 hour -#### **AI Enhancements** -- **Extended thinking with tool use**: Claude uses tools during thinking -- **Parallel tool execution**: Multiple tools run simultaneously -- **128K output tokens**: 15x longer responses +# Context-aware permissions +claude --allowedTools "Edit(src/**),View(**),Bash(git:status)" -#### **Interactive Modes** -- **Planning mode**: `Shift+Tab` twice for analysis without writes -- **Auto-accept mode**: `Shift+Tab` once for autonomous implementation +# Conditional permissions +claude --allowedTools "Edit if review_approved,View" +``` -#### **Integrations** -- **IDE integrations**: VS Code and JetBrains extensions -- **Advanced memory system**: Multi-tiered contextual memory +#### Custom Permission Handlers +**MCP Permission Handler Example**: +```javascript +// permission-handler.js +import { Server } from '@modelcontextprotocol/sdk/server/index.js'; +const server = new Server({ + name: 'permission-handler', + version: '1.0.0' +}); + +server.setRequestHandler('tools/call', async (request) => { + const { name, arguments: args } = request.params; + + if (name === 'check_permission') { + const { tool, operation, context } = args; + + // Custom permission logic + if (tool === 'Edit' && operation.includes('package.json')) { + return { + behavior: 'deny', + message: 'package.json modifications require manual review' + }; + } + + if (tool === 'Bash' && !operation.startsWith('git')) { + return { + behavior: 'allow', + message: 'Non-git bash operations approved' + }; + } + + return { + behavior: 'allow', + updatedInput: args + }; + } +}); +``` + +#### Permission Policies + +```json +{ + "permissionPolicies": { + "development": { + "allowedTools": ["Edit", "View", "Bash(git:*)", "mcp__*__read"], + "requireConfirmation": ["Bash", "mcp__*__write"], + "autoApprove": ["View", "mcp__git__status"] + }, + "production": { + "allowedTools": ["View", "mcp__monitoring__*"], + "requireConfirmation": "*", + "autoApprove": ["View"] + }, + "security-audit": { + "allowedTools": ["View", "mcp__*__read"], + "requireConfirmation": [], + "autoApprove": "*" + } + } +} +``` + +### Integration with External Services + +#### GitHub Advanced Integration + +```bash +# Setup GitHub integration +claude mcp add github "github-mcp-server --token $GITHUB_TOKEN" + +# Advanced GitHub workflows +claude --allowedTools "mcp__github__*,View,Edit" \ + "review all open PRs and provide comprehensive feedback" + +# Automated PR management +claude "create PR for feature branch with appropriate reviewers and labels" + +# Repository analysis +claude "analyze repository health: code quality, security, documentation" +``` + +#### Database Advanced Integration + +```bash +# Multi-database analysis +claude mcp add prod_db "postgres-mcp-server --url $PROD_DB_URL" +claude mcp add dev_db "postgres-mcp-server --url $DEV_DB_URL" + +# Cross-database analysis +claude --allowedTools "mcp__prod_db__query,mcp__dev_db__*" \ + "compare production and development database schemas" + +# Performance optimization +claude "analyze database performance and suggest optimizations" +``` + +#### Cloud Infrastructure Integration + +```bash +# AWS integration +claude mcp add aws "aws-mcp-server --region us-east-1" + +# Infrastructure analysis +claude --allowedTools "mcp__aws__*,View,Edit" \ + "audit AWS infrastructure for cost optimization and security" + +# Automated deployments +claude "deploy application to staging environment with health checks" +``` + +### Power User Workflows + +#### Morning Development Routine + +```bash +#!/bin/bash +# morning-routine.sh + +echo "🌅 Starting development day..." + +# Update project context +claude /memory edit + +# Check system health +claude /doctor + +# Review overnight changes +claude --allowedTools "View,mcp__git__*" \ + "summarize all changes since yesterday and identify any issues" + +# Plan daily tasks +claude "based on current project state and recent changes, suggest priorities for today" + +echo "✅ Morning routine complete" +``` + +#### Code Review Workflow + +```bash +#!/bin/bash +# comprehensive-review.sh + +PR_NUMBER=${1:-"latest"} + +echo "🔍 Starting comprehensive code review for PR $PR_NUMBER..." + +# Setup review environment +claude mcp add github "github-mcp-server --token $GITHUB_TOKEN" +claude mcp add security "security-scanner-mcp-server" + +# Comprehensive review +claude --allowedTools "mcp__github__*,mcp__security__*,View" \ + "perform comprehensive code review for PR $PR_NUMBER including: + - Security vulnerability scan + - Code quality analysis + - Performance implications + - Test coverage review + - Documentation updates needed + - Architecture impact assessment" + +echo "✅ Code review complete" +``` + +#### Database Migration Workflow + +```bash +#!/bin/bash +# safe-migration.sh + +echo "🗄️ Starting safe database migration..." + +# Setup databases +claude mcp add source "postgres-mcp-server --url $SOURCE_DB" +claude mcp add target "postgres-mcp-server --url $TARGET_DB" + +# Plan migration +claude --allowedTools "mcp__source__*,mcp__target__*,Edit,View" \ + "create comprehensive database migration plan with: + - Schema comparison and mapping + - Data transformation rules + - Rollback procedures + - Validation steps + - Performance considerations" + +# Execute with monitoring +claude --allowedTools "mcp__source__*,mcp__target__*,Edit,View" \ + --max-turns 100 \ + "execute migration plan with continuous monitoring and validation" + +echo "✅ Database migration workflow complete" +``` --- -## Important Notes +## 💡 Tips & Best Practices +### Development Best Practices -Command Precedence & Behavior +#### Effective Prompting Techniques -### **Command Precedence** -``` -Query > Session > App Config > Environment Variables > Defaults +**1. Be Specific and Detailed** +```bash +# Good: Specific request +claude "Review the UserAuth.js file for security vulnerabilities, focusing on JWT handling and password validation" + +# Bad: Vague request +claude "check my code" ``` -### **Key Behaviors** -1. **Session Management**: Each command can specify session name for isolation -2. **Tool Names**: Use exact names like "Replace", "Edit", "Bash", "View" -3. **MCP Integration**: Model Context Protocol with SSE/HTTP support -4. **Version Updates**: Use `claude update` for latest features -5. **DMCA Notice**: Decompiled source repository was taken down -6. **Beta Features**: GitHub Actions, IDE extensions in beta -7. **Thinking Modes**: Special phrases trigger different thinking levels -8. **Latest Version**: 1.0.25 (June 2025) with improved reliability -9. **Real-time Features**: SSE transport enables real-time MCP communication +**2. Provide Context** +```bash +# Good: Context provided +claude "I'm working on a React e-commerce app. The shopping cart component is not updating properly when items are added. Here's the relevant code..." +# Bad: No context +claude "my component isn't working" +``` +**3. Use Progressive Disclosure** +```bash +# Start with analysis +claude "think hard about the architecture of this authentication system" + +# Then ask for implementation +claude "now implement the improvements you suggested" +``` + +#### Project Setup Best Practices + +**1. Initialize CLAUDE.md Early** +```bash +# Create comprehensive project context +claude /init +claude /memory edit + +# Keep it updated +claude "update the project memory with our recent architectural changes" +``` + +**2. Configure Appropriate Permissions** +```bash +# Development environment +claude config set allowedTools "Edit,View,Bash(git:*),Bash(npm:*),mcp__git__*" + +# CI/CD environment +claude config set allowedTools "View,Edit,Bash(git:status),mcp__git__status" +``` + +**3. Set Up Relevant MCP Servers** +```bash +# For web development +claude mcp add git "git-mcp-server" +claude mcp add postgres "postgres-mcp-server --url $DATABASE_URL" +claude mcp add browser "puppeteer-mcp-server" + +# For cloud development +claude mcp add aws "aws-mcp-server --region us-east-1" +``` + +### Security Best Practices + +#### Permission Management + +**1. Start Restrictive, Then Expand** +```bash +# Start with minimal permissions +claude config set allowedTools "View" + +# Add permissions as needed +claude config add allowedTools "Edit" +claude config add allowedTools "mcp__git__status" +``` + +**2. Use Environment-Specific Configurations** +```bash +# Development +export CLAUDE_ENV=development +claude config set allowedTools "Edit,View,Bash,mcp__*__*" + +# Production +export CLAUDE_ENV=production +claude config set allowedTools "View,mcp__monitoring__*" +``` + +**3. Regular Security Audits** +```bash +# Weekly security review +claude /permissions history +claude /doctor +claude config export > security-audit-$(date +%Y%m%d).json +``` + +#### Sensitive Data Protection + +**1. Use Environment Variables** +```bash +# Good: Environment variables +export DATABASE_URL="postgresql://user:pass@host/db" +claude mcp add postgres "postgres-mcp-server --url $DATABASE_URL" + +# Bad: Hardcoded credentials +claude mcp add postgres "postgres-mcp-server --url postgresql://user:password123@host/db" +``` + +**2. Exclude Sensitive Files** +```bash +# Create .claude/ignored-files +echo "*.env +*.key +*.pem +secrets.json +.ssh/* +config/secrets.yml" > .claude/ignored-files +``` + +**3. Use Read-Only Permissions for Audits** +```bash +# Security audits +claude --allowedTools "View,mcp__*__read,mcp__*__query" \ + "perform security audit of the application" +``` + +### Performance Optimization + +#### Efficient Resource Usage + +**1. Optimize Thinking Budget** +```bash +# For quick tasks +claude config set thinkingBudget 5000 + +# For complex analysis +claude config set thinkingBudget 50000 + +# For comprehensive research +claude config set thinkingBudget 128000 +``` + +**2. Use Appropriate Models** +```bash +# Quick fixes +claude --model claude-haiku-3 "fix these linting errors" + +# Code review +claude --model claude-sonnet-4 "review this pull request" + +# Architecture design +claude --model claude-opus-4 "design system architecture" +``` + +**3. Batch Similar Operations** +```bash +# Inefficient: Multiple separate calls +claude "fix file1.js" +claude "fix file2.js" +claude "fix file3.js" + +# Efficient: Batch operation +claude "fix all JavaScript files with similar issues: file1.js, file2.js, file3.js" +``` + +#### Memory Management + +**1. Regular Memory Cleanup** +```bash +# Compress long conversations +claude /compact + +# Clear old sessions +claude config set sessions "[]" + +# Clean cache periodically +rm -rf ~/.claude/cache/* +``` + +**2. Optimize Context Size** +```bash +# Use focused context +claude --add-dir src/components "analyze just the React components" + +# Rather than +claude "analyze entire codebase" # This loads everything +``` + +### Automation Best Practices + +#### CI/CD Integration + +**1. Use Non-Interactive Mode** +```bash +# CI/CD scripts should use -p flag +claude -p "run tests and generate report" --output-format json +``` + +**2. Implement Proper Error Handling** +```bash +#!/bin/bash +if ! claude -p "validate deployment readiness" --output-format json > validation.json; then + echo "Validation failed" + exit 1 +fi + +if jq -e '.ready' validation.json > /dev/null; then + echo "Deployment approved" +else + echo "Deployment blocked" + jq -r '.issues[].message' validation.json + exit 1 +fi +``` + +**3. Use Appropriate Timeouts** +```bash +# Set timeouts for automation +timeout 300 claude -p "analyze large codebase" || { + echo "Analysis timed out" + exit 1 +} +``` + +#### Monitoring & Alerting + +**1. Health Check Automation** +```bash +# Regular health checks +*/15 * * * * /usr/local/bin/claude /doctor > /dev/null || echo "Claude health check failed" | mail -s "Alert" admin@company.com +``` + +**2. Log Analysis** +```bash +# Daily log analysis +0 6 * * * tail -1000 /var/log/app.log | claude -p "analyze for issues" --output-format json > /tmp/daily-analysis.json +``` + +### Collaboration Best Practices + +#### Team Workflows + +**1. Shared Configuration Templates** +```bash +# Create team templates +mkdir -p ~/.claude/templates/ +cat > ~/.claude/templates/team-frontend.json << EOF +{ + "allowedTools": ["Edit", "View", "Bash(npm:*)", "mcp__git__*"], + "model": "claude-sonnet-4", + "systemPrompt": "You are working on our React frontend. Follow our coding standards and use TypeScript." +} +EOF + +# Use templates +claude config import ~/.claude/templates/team-frontend.json +``` + +**2. Documentation Automation** +```bash +# Automated documentation updates +claude "update README.md with recent changes to the API endpoints" +claude "generate TypeScript definitions from the new database schema" +``` + +**3. Code Review Standards** +```bash +# Standardized review process +claude --allowedTools "View,mcp__git__*" \ + "review PR #123 using our team standards: + - Security best practices + - Performance considerations + - Code style compliance + - Test coverage adequacy" +``` + +#### Knowledge Sharing + +**1. Create Project Runbooks** +```bash +# Generate runbooks +claude "create a deployment runbook for this application including all steps and troubleshooting" +claude "document the onboarding process for new developers" +``` + +**2. Architecture Documentation** +```bash +# Maintain architecture docs +claude "update architecture documentation to reflect recent microservices changes" +claude "create sequence diagrams for the new authentication flow" +``` + +### Common Pitfalls to Avoid + +#### Security Pitfalls + +**❌ Don't:** +- Use `--dangerously-skip-permissions` on production systems +- Hardcode secrets in commands or configuration +- Grant overly broad permissions +- Run with elevated privileges unnecessarily + +**✅ Do:** +- Use environment variables for secrets +- Start with minimal permissions +- Regular security audits +- Isolate sensitive operations + +#### Performance Pitfalls + +**❌ Don't:** +- Load entire large codebases unnecessarily +- Use maximum thinking budget for simple tasks +- Run multiple concurrent Claude instances +- Ignore memory and cache cleanup + +**✅ Do:** +- Use focused context with `--add-dir` +- Match thinking budget to task complexity +- Monitor resource usage +- Clean up regularly + +#### Workflow Pitfalls + +**❌ Don't:** +- Skip project context setup (CLAUDE.md) +- Use vague, ambiguous prompts +- Ignore error messages and logs +- Automate without testing first + +**✅ Do:** +- Maintain comprehensive project context +- Be specific and detailed in requests +- Monitor and analyze logs +- Test automation in safe environments --- -## ✅ Research Verification - -### **COMPLETE RESEARCH CONDUCTED** - -| Source | Status | -|--------|--------| -| Official Documentation | **Thoroughly Reviewed** | -| GitHub Repository & Issues | **Comprehensively Analyzed** | -| Community Discussions | **Extensively Searched** | -| CLI Reference | **Completely Documented** | -| Environment Variables | **Fully Catalogued** | -| Slash Commands | **Entirely Mapped** | -| Hidden Features | **Discovered & Documented** | -| 2025 Updates | **Latest Changelog Reviewed** | -| Source Code Analysis | **Completed (pre-DMCA)** | - -