From 9c6b6f1cd3de113100c2cbe24a54da6fac850622 Mon Sep 17 00:00:00 2001 From: zebbern <185730623+zebbern@users.noreply.github.com> Date: Tue, 1 Jul 2025 19:05:43 +0200 Subject: [PATCH] Update README.md --- README.md | 3859 ++++------------------------------------------------- 1 file changed, 227 insertions(+), 3632 deletions(-) diff --git a/README.md b/README.md index 1748073..2499756 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,3 @@ -
- ---- - ### **Claude Code Guide** > This comprehensive guide covers **every discoverable Claude Code command** as of June 2025, @@ -94,23 +90,7 @@ claude mcp # Setup MCP servers ``` - ---- - -## 📋 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 - ---- - -## Installation & Setup +## 🚀 Installation & Setup **System Requirements:** - Node.js 16+ or standalone binary @@ -125,238 +105,89 @@ claude mcp # Setup MCP servers ### Installation Methods -#### Method 1: NPM Installation (Recommended) +#### Method 1: NPM Installation (Verified ✅) ```bash -# Install globally +# Install globally - CORRECT PACKAGE NAME npm install -g @anthropic-ai/claude-code # Verify installation claude --version -# Should show: claude-code v1.0.25 ``` -#### Method 2: Direct Binary Download -```bash -# Linux/macOS -curl -fsSL https://claude.ai/install.sh | sh - -# Windows (PowerShell) -iwr https://claude.ai/install.ps1 | iex - -# Manual download -# Visit: https://github.com/anthropics/claude-code/releases -``` - -#### Method 3: Package Managers -```bash -# macOS (Homebrew) -brew install anthropic/tap/claude-code - -# 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 - -# Arch Linux (AUR) -yay -S claude-code - -# Windows (Chocolatey) -choco install claude-code -``` ### Initial Setup -#### 1. API Key Configuration +#### 1. API Key Configuration (Verified ✅) ```bash # Required: Get your API key from https://console.anthropic.com -export ANTHROPIC_API_KEY="sk-ant-api03-your-key-here" +export ANTHROPIC_API_KEY="sk-your-key-here" # Make permanent (choose your shell) # Bash -echo 'export ANTHROPIC_API_KEY="sk-ant-api03-your-key"' >> ~/.bashrc +echo 'export ANTHROPIC_API_KEY="sk-your-key-here"' >> ~/.bashrc source ~/.bashrc # Zsh -echo 'export ANTHROPIC_API_KEY="sk-ant-api03-your-key"' >> ~/.zshrc +echo 'export ANTHROPIC_API_KEY="sk-your-key-here"' >> ~/.zshrc source ~/.zshrc # Fish -echo 'set -gx ANTHROPIC_API_KEY "sk-ant-api03-your-key"' >> ~/.config/fish/config.fish +echo 'set -gx ANTHROPIC_API_KEY "sk-your-key-here"' >> ~/.config/fish/config.fish ``` -#### 2. First-Time Configuration +#### 2. Basic Configuration (Mostly Verified ✅) ```bash # Interactive setup claude config -# Set global defaults +# Set basic 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 +claude /doctor ``` -#### 3. Recommended Initial Settings +#### 3. Settings i Turn Off ```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 +claude config set hasTrustDialogAccepted +claude config set hasCompletedProjectOnboarding +claude config set ignorePatterns +claude config set --global ``` -### Verification & Testing - -#### Health Check +### Health Check & Testing ```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 +# Basic functionality test claude "Explain what you can do" -# Print mode test +# 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 +# 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 +# health check ``` - -#### 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 - -#### Essential Shortcuts -```bash -# Add to ~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish - -# 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" - -# 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 - -#### Common Installation Issues -```bash -# Permission errors (Linux/macOS) -sudo npm install -g @anthropic-ai/claude-code - -# Node.js version issues -nvm install 18 -nvm use 18 - -# Path issues -echo $PATH -which claude - -# Clear npm cache -npm cache clean --force - -# Reinstall -npm uninstall -g @anthropic-ai/claude-code -npm install -g @anthropic-ai/claude-code -``` - -#### Windows-Specific Issues -```bash -# 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 +claude /doctor +Expected output might include: +# ✅ API Key: Valid +# ✅ Network: Connected +# ✅ Model Access: Available ``` --- @@ -366,34 +197,33 @@ wsl --install ### 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 extends Claude's capabilities by connecting to external services, databases, APIs, and tools. **MCP Architecture:** ``` 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 -#### Basic MCP Setup +#### Basic MCP Commands ```bash -# Interactive MCP configuration -claude mcp - -# Check current MCP servers -claude config get mcp - -# List available MCP servers (if registry exists) -claude mcp list-available +claude mcp # Interactive MCP configuration +claude mcp list # List configured servers # Check server health +claude mcp add # Add new server +claude mcp remove # Remove server ``` -#### MCP Configuration File -Create `.claude/mcp.json` in your project: +#### MCP Configuration File +**Location**:`~/.claude.json` + +### Scope-Based Configuration Files + +User/Global Scope: +Global MCP servers are configured in `~/.claude-code/mcp/global.json` +Project Scope: +Project-scoped servers are stored in a `.mcp.json` file at your project's root directory + ```json { "mcpServers": { @@ -403,366 +233,52 @@ Create `.claude/mcp.json` in your project: "env": {} }, "postgres": { - "command": "postgres-mcp-server", + "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) +### MCP Servers -#### Development & Git Tools +**Note**: The exact package names and installation commands below may not be accurate. Consult official MCP documentation for current server packages. -| 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:** +#### Development Tools ```bash -# Install and configure Git MCP -npm install -g @anthropic/git-mcp-server -claude mcp add git "git-mcp-server" +# npm install -g 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" +# claude mcp add git "git-mcp-server" +# claude mcp add github "github-mcp-server --token $GITHUB_TOKEN" ``` -#### Database Integration - -| 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:** +#### Database Integration ```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" +npm install -g postgres-mcp-server +npm install -g mysql-mcp-server +npm install -g sqlite-mcp-server -# 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 +# Setup examples +# export POSTGRES_URL="postgresql://user:password@localhost:5432/mydb" +# claude mcp add postgres "postgres-mcp-server --url $POSTGRES_URL" ``` ### MCP Tool Permissions -#### Permission Patterns for MCP Tools ```bash -# Allow specific MCP tools +# 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 +claude --allowedTools "Edit,View,mcp__git__*" ``` --- @@ -772,306 +288,76 @@ claude --memory-file custom.md # Use custom memory file ### 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 | +| Command | Description | Example | Status | +|---------|-------------|---------|--------| +| `claude` | Start interactive REPL | `claude` | +| `claude "query"` | REPL with initial prompt | `claude "help debug this"` | +| `claude -p "query"` | One-shot query (print mode) | `claude -p "explain function"` | -#### 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 | +#### Session Management +| Command | Description | Example | Status | +|---------|-------------|---------|--------| +| `claude -c` | Continue last session | `claude -c` | +| `claude -r ` | Resume specific session | `claude -r abc123` | +| `claude --resume ` | Resume named session | `claude --resume project-review` | #### 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 | +| Command | Description | Example | Status | +|---------|-------------|---------|--------| +| `claude config` | Interactive configuration | `claude config` | +| `claude config list` | List all settings | `claude config list` | +| `claude config get ` | Get specific value | `claude config get model` | +| `claude config set ` | Set value | `claude config set model sonnet` | ### CLI Flags & Options -#### Essential Flags +#### 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 +#### 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 +#### 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 +#### Advanced 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` | +| `--add-dir ` | Add working directories | `claude --add-dir ../lib ../src` | +| `--model ` | Set specific model | `claude --model sonnet` | +| `--verbose` | Enable detailed logging | `claude --verbose` | ### 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` | +#### Commands +| Command | Purpose | Status | +|---------|---------|--------| +| `/help` | Show all slash commands | +| `/clear` | Clear current conversation | +| `/exit` | Exit Claude safely | +| `/bug` | Report issues | -#### 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 +#### 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 +/doctor # Complete health check +/status # System information +/cost # Token usage stats +/config # Configuration menu +/permissions # Manage tool access +/memory # Edit memory files +/sessions # List all sessions ``` --- @@ -1080,929 +366,145 @@ claude -p "Create comprehensive code review report" \ ### Configuration System Overview -Claude Code uses a **hierarchical configuration system**: - +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`) +2. **Environment variables** +3. **Project configuration** (location may vary) +4. **Global configuration** (likely `~/.claude.json`) 5. **Built-in defaults** (lowest priority) ### Configuration Files #### Global Configuration -**Location**: `~/.claude.json` -**Scope**: All projects for current user +**Location**: `~/.claude.json` ```json { "model": "claude-sonnet-4", "verbose": true, - "outputFormat": "text", + "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 - } } ``` #### Project Configuration -**Location**: `.claude/settings.json` -**Scope**: Current project only +**Location**: `settings.json` OR similar ```json { - "model": "claude-opus-4", - "systemPrompt": "You are a senior developer working on this React application", + "model": "claude-sonnet-4", + "systemPrompt": "You are a senior developer working on this project", "allowedTools": [ "Edit", - "View", + "View", "Bash(git:*)", - "Bash(npm:*)", - "mcp__postgres__*" + "Bash(npm:*)" ], - "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 - -```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 | +#### Core Variables +| Variable | Required | 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` | +| `ANTHROPIC_API_KEY` | **YES** | API Authentication | `sk-ant-api03-xxx` | +| `ANTHROPIC_MODEL` | No | Default model | `claude-sonnet-4` | +| `ANTHROPIC_BASE_URL` | No | API endpoint override | `https://api.anthropic.com` | -#### 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 +#### Variables ```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_NON_ESSENTIAL_MODEL_CALLS=1 +export MAX_THINKING_TOKENS=50000 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 + + +# Cloud provider variables +export CLAUDE_CODE_USE_BEDROCK=1 +export CLAUDE_CODE_USE_VERTEX=1 +``` + +#### Network & Proxy +```bash +# Standard proxy variables +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" ``` --- -## 🔒 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 +## Security & Permissions ### 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) +**How it works**: +- Claude asks for permission before using tools +- Permissions are remembered per session +- Dangerous operations require confirmation #### 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 +#### Tool Permission Patterns ```bash # Allow specific tools claude --allowedTools "Edit,View" -# Allow tool categories +# 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 +### Dangerous Mode (CRITICAL Security Feature) ```bash -# Instead of dangerous mode, use specific allowlists -claude --allowedTools "Edit,View,Bash(git:*),Bash(npm:*)" +# DANGEROUS - Can cause data loss +claude --dangerously-skip-permissions -# 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 +# Only use in isolated environments: +# ✅ Safe: Isolated Docker container +# ❌ NEVER: Production systems, shared machines, systems with important data ``` ### Security Best Practices -#### 1. Principle of Least Privilege +#### 1. Start Restrictive ```bash # Good: Specific permissions claude --allowedTools "Edit,View,Bash(git:status)" -# Bad: Broad permissions +# 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 +#### 2. Protect Sensitive Data ```bash -# Development container -docker run --rm -v $(pwd):/workspace \ - -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \ - claude-container claude --allowedTools "Edit,View,Bash(git:*)" +# Good: Environment variables +export DATABASE_URL="postgresql://user:pass@host/db" -# Network isolation -docker run --rm --network none \ - claude-container claude --dangerously-skip-permissions +# Bad: Hardcoded credentials in commands +# claude "connect to postgresql://user:password123@host/db" ``` #### 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 +# Review configuration +claude config list ``` --- @@ -2011,9 +513,7 @@ git log --since="1 day ago" --oneline ### CI/CD Integration -#### GitHub Actions Integration - -**Setup GitHub Actions Workflow** (`.github/workflows/claude-review.yml`): +#### GitHub Actions Example ```yaml name: Claude Code Review on: @@ -2025,2109 +525,204 @@ jobs: 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-ai/claude-code - - - name: Run Claude Code Review + - name: Run 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__*" \ + claude -p "Review changes for security issues and bugs" \ + --allowedTools "View" \ --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 +### Automation Scripts -**GitLab CI Configuration** (`.gitlab-ci.yml`): -```yaml -stages: - - test - - review - - deploy - -claude-review: - stage: review - image: node:18 - before_script: - - npm install -g @anthropic-ai/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-ai/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`): +#### Pre-commit Hook Example ```bash #!/bin/bash # .git/hooks/pre-commit -set -e - -# Get list of staged files +# Get 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 +# Analyze with Claude analysis=$(echo "$staged_files" | xargs cat | \ - claude -p "Review these changes for issues before commit. Focus on security, bugs, and style." \ + claude -p "Review these changes for issues before commit" \ --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." + echo "❌ Critical issues found - commit blocked" 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 "❌ Auto-fix failed, restoring previous state" - git stash pop - exit 1 -fi -``` - -### Monitoring & Logging - -#### System Monitoring Script - -**Monitoring Script** (`scripts/monitor.sh`): -```bash -#!/bin/bash -# scripts/monitor.sh - -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 - -echo "✅ Batch processing completed" -``` - -#### Data Migration Automation - -**Data Migration Script** (`scripts/migrate-data.sh`): -```bash -#!/bin/bash -# scripts/migrate-data.sh - -SOURCE_DB="postgresql://user:pass@old-server:5432/olddb" -TARGET_DB="postgresql://user:pass@new-server:5432/newdb" - -# 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" - -# 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 - -# 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 -``` - -### 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 -# Comprehensive diagnostic -claude /doctor --verbose - -# Network connectivity test -claude -p "test connection" --verbose - -# MCP server diagnostics -claude --mcp-debug /doctor - -# Configuration validation -claude config validate - -# Permission audit -claude /permissions --detailed +# Basic health checks +claude --version +claude --help +claude config list +claude /doctor ``` ### Common Issues & Solutions #### 1. Authentication Issues - -**Problem**: `Authentication failed` or `Invalid API key` - -**Diagnosis**: ```bash # Check API key echo $ANTHROPIC_API_KEY -# Should show: sk-ant-api03-... -# 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 connection +claude -p "test" --verbose -# Test API connection -claude -p "hello" --verbose +# Reset authentication ``` -**Solutions**: +#### 2. Installation Issues ```bash -# Reset authentication -rm -rf ~/.config/claude-code/auth.json -claude /logout -claude /login +# Reinstall +npm uninstall -g @anthropic-ai/claude-code +npm install -g @anthropic-ai/claude-code -# 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 - -# 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 +# Check Node.js version +node --version # Should be 16+ ``` #### 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 +claude config set allowedTools "[]" +claude config set allowedTools '["Edit", "View"]' ``` -#### 4. Performance Issues - -**Problem**: `Claude is slow` or `Response timeout` - -**Diagnosis**: +#### 4. MCP Issues ```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 +# Debug MCP +claude --mcp-debug +claude mcp status +claude mcp restart --all ``` -**Solutions**: +### Debug Mode ```bash -# Optimize thinking budget -export MAX_THINKING_TOKENS=10000 -claude config set thinkingBudget 10000 +# Enable verbose logging +claude --verbose -# 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-ai/claude-code -npm install -g @anthropic-ai/claude-code - -# 6. Reconfigure -claude config -claude /doctor -``` - -#### Session Recovery - -```bash -# List available sessions -claude config get sessions -ls ~/.claude/sessions/ - -# Recover specific session -claude -r session_id - -# Recover from backup -cp ~/.claude/sessions/session_backup.json ~/.claude/sessions/current.json -claude -c - -# Clean corrupted sessions -rm -rf ~/.claude/sessions/* -claude /clear -``` - -#### MCP Recovery - -```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 - -# Reconfigure MCP -claude mcp add git "git-mcp-server" -claude mcp add postgres "postgres-mcp-server" -claude mcp status -``` - -### 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\" - } - }" -} +# Check logs (verify log location) ``` --- ## 🚀 Advanced Features -### Context Management & Memory +### Context Management -#### 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 +#### CLAUDE.md - Project Memory +**Purpose**: Store persistent project information that Claude remembers **Location**: Project root directory -**Example CLAUDE.md**: ```markdown -# Project: E-commerce Platform +# Project: My Application ## Overview -This is a React/Node.js e-commerce platform with PostgreSQL database. +This is a React/Node.js application with PostgreSQL database. ## Architecture - Frontend: React 18 with TypeScript -- Backend: Node.js with Express +- 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 +## Current Goals +- [ ] Implement authentication +- [ ] Add API documentation +- [ ] Set up CI/CD pipeline ## 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 +- Write tests for new features ``` -#### Memory Management Commands - +#### Memory 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 +claude /memory # Edit project memory +claude /memory view # View current memory ``` -#### 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 - +### Advanced Thinking ```bash -# Install Context7 MCP server -npm install -g @context7/mcp-server +# These "thinking" phrases may work: +claude "think hard about the security implications of this code" +claude "analyze this thoroughly and provide detailed recommendations" -# 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 - -```bash -# Basic thinking -claude "think about the best way to optimize this database query" - -# Enhanced thinking -claude "think hard about the security implications of this authentication system" - -# Maximum thinking -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" -``` - -#### Custom Thinking Budget - -```bash -# Set custom thinking budget -export MAX_THINKING_TOKENS=50000 -claude config set thinkingBudget 50000 - -# Per-command thinking budget -claude --thinking-budget 25000 "analyze this complex system" -``` - -### Interactive Mode Advanced Features - -#### Keyboard Shortcuts & Modes - -| 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 - -```bash -# Start Claude -claude "I need to refactor this user authentication system" - -# 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 +claude --add-dir ../frontend ../backend ../shared # 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 - -```json -{ - "workspace": { - "directories": [ - "../frontend", - "../backend", - "../shared", - "../infrastructure" - ], - "excludePatterns": [ - "node_modules", - "dist", - "build", - ".git" - ], - "includePatterns": [ - "*.js", - "*.ts", - "*.jsx", - "*.tsx", - "*.json", - "*.md" - ] - } -} -``` - -### 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 -{ - "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 - -# Custom model switching rules -claude config set modelRules '{ - "security-audit": "claude-opus-4", - "code-review": "claude-sonnet-4", - "linting": "claude-haiku-3" -}' -``` - -### Advanced Permission System - -#### Granular Permission Control - -```bash -# File-type specific permissions -claude --allowedTools "Edit(*.js),Edit(*.ts),View(*)" - -# Time-based permissions -claude --allowedTools "Edit" --permission-timeout 3600 # 1 hour - -# Context-aware permissions -claude --allowedTools "Edit(src/**),View(**),Bash(git:status)" - -# Conditional permissions -claude --allowedTools "Edit if review_approved,View" -``` - -#### 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" +claude "analyze the entire application architecture" ``` --- -## 💡 Tips & Best Practices +## 💡 Best Practices -### Development Best Practices - -#### Effective Prompting Techniques - -**1. Be Specific and Detailed** +### Effective Prompting ```bash -# Good: Specific request -claude "Review the UserAuth.js file for security vulnerabilities, focusing on JWT handling and password validation" +# Good: Specific and detailed +claude "Review UserAuth.js for security vulnerabilities, focusing on JWT handling" -# Bad: Vague request +# Bad: Vague claude "check my code" ``` -**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 +1. **Start with minimal permissions**: `claude --allowedTools "View"` +2. **Use environment variables**: `export API_KEY="secret"` +3. **Regular audits**: `claude config get allowedTools` +4. **Avoid dangerous mode**: Only use `--dangerously-skip-permissions` in containers -#### Permission Management +### Performance Tips +1. **Use appropriate output formats**: `--output-format json` for automation +2. **Be specific in prompts**: Better results, faster execution +3. **Clean up regularly**: Remove old sessions and cache -**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" -``` +## Getting Help -**2. Use Environment-Specific Configurations** -```bash -# Development -export CLAUDE_ENV=development -claude config set allowedTools "Edit,View,Bash,mcp__*__*" +- **Official Documentation**: https://docs.anthropic.com/en/docs/claude-code/overview +- **Report Issues**: Use `/bug` command (if it works) or file GitHub issues +- **Test First**: Always test commands in safe environments before relying on them -# 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 -} -``` +**Last Updated**: Based on package version 1.0.38 and available documentation. Many features require verification in your specific installation. #### Monitoring & Alerting