From ad72db02dc493c056e0646b13c976b0c32695687 Mon Sep 17 00:00:00 2001 From: zebbern <185730623+zebbern@users.noreply.github.com> Date: Mon, 23 Jun 2025 02:48:57 +0200 Subject: [PATCH] Update README.md --- README.md | 455 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 453 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 86f1a3a..d1a4878 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,454 @@ -## Decided to make a website of this instead +# Claude Code: Complete Cheat Sheet & Power User Guide -# https://zebbern.github.io +> AI coding assistant that lives in your terminal. Understands your codebase, writes code, fixes bugs, handles git workflows through natural language. + +[![npm](https://img.shields.io/npm/v/@anthropic-ai/claude-code)](https://www.npmjs.com/package/@anthropic-ai/claude-code) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) + +## Quick Start + +```bash +# Install +npm install -g @anthropic-ai/claude-code + +# Start +cd your-project +claude +``` + +## 📋 Installation & Setup + +### System Requirements +- **OS**: macOS 10.15+, Ubuntu 20.04+, Windows (via WSL only) +- **Node.js**: 18+ (recommended: 20+) +- **Account**: Claude Max subscription OR Anthropic API key + +### Installation Options + +```bash +# Method 1: NPM (recommended) +npm install -g @anthropic-ai/claude-code + +# Method 2: UV (Python users) +uv tool install @anthropic-ai/claude-code + +# Method 3: Binary download from GitHub releases +``` + +### API Configuration + +```bash +# Set API key +export ANTHROPIC_API_KEY=your_key_here + +# Add to shell profile +echo 'export ANTHROPIC_API_KEY=your_key' >> ~/.bashrc +``` + +**Tip**: Claude Max subscription is more economical for regular users than pay-per-use API. + +## 🎯 Core Usage + +### Usage Modes + +| Mode | Command | Use Case | +|------|---------|----------| +| **Interactive** | `claude` | Normal development | +| **One-shot** | `claude -p "question"` | Quick tasks | +| **Headless** | `claude -p "task" --output-format stream-json` | CI/Automation | +| **Planning** | `Shift+Tab Shift+Tab` | Plan without executing | + +### Model Selection + +```bash +claude --model claude-opus-4 # Most capable +claude --model claude-sonnet-4 # Balanced (default) +claude --model claude-haiku-3.5 # Fastest/cheapest +``` + +## 🔧 All Interactive Commands + +| Command | Purpose | Example | +|---------|---------|---------| +| `/add-dir` | Add working directory | `/add-dir ~/projects` | +| `/bug` | Report issues | `/bug describe_problem` | +| `/clear` | Clear context (saves tokens) | `/clear` | +| `/compact` | Keep summary, clear context | `/compact [instructions]` | +| `/config` | Open config panel | `/config` | +| `/cost` | Show session cost | `/cost` | +| `/doctor` | Check installation health | `/doctor` | +| `/exit` | Exit REPL | `/exit` | +| `/help` | Show all commands | `/help` | +| `/ide` | Connect to IDE | `/ide` | +| `/init` | Generate CLAUDE.md docs | `/init` | +| `/install-github-app` | Setup GitHub Actions | `/install-github-app` | +| `/login` | Switch accounts | `/login` | +| `/logout` | Sign out | `/logout` | +| `/mcp` | Manage MCP servers | `/mcp` | +| `/memory` | Edit memory files | `/memory` | +| `/model` | Change AI model | `/model claude-opus-4` | +| `/permissions` | Manage tool permissions | `/permissions` | +| `/pr-comments` | Get PR comments | `/pr-comments 123` | +| `/release-notes` | View updates | `/release-notes` | +| `/resume` | Resume conversation | `/resume session_id` | +| `/review` | Review pull request | `/review 123` | +| `/status` | Show system status | `/status` | +| `/terminal-setup` | **Hidden**: Optimize terminal | `/terminal-setup` | +| `/upgrade` | Upgrade to Max plan | `/upgrade` | +| `/vim` | Toggle vim mode | `/vim` | + +## 🔥 Hidden Power Features + +### 1. Dangerous Mode (Automation) +```bash +# Skip all permission prompts +claude --dangerously-skip-permissions -p "fix all linting errors" + +# Recommended: Use in Docker container +docker run --rm -v $(pwd):/workspace claude-container +``` + +### 2. Terminal Setup (Hidden Command) +```bash +/terminal-setup +# Enables: Shift+Enter for newlines, bell notifications, optimized settings +``` + +### 3. Pre-commit Hook Integration +```yaml +# .pre-commit-config.yaml +repos: + - repo: local + hooks: + - id: claude-lint + name: Claude Auto-lint + entry: claude + args: ["-p", "fix linting and formatting", "--dangerously-skip-permissions"] + language: system + files: \.(js|ts|py)$ +``` + +### 4. Permission Management +```bash +# Allow specific tools without prompts +/permissions add Edit +/permissions add "Bash(git commit:*)" +/permissions deny "Bash(rm*)" + +# Session-specific permissions +claude --allowedTools Edit,Bash +``` + +### 5. Planning Mode +```bash +# Press Shift+Tab twice for planning mode (no file writes) +Shift+Tab Shift+Tab +``` + +## 🌐 Cross-Platform Setup + +### Windows (WSL Required) + +```bash +# 1. Install WSL2 +wsl --install Ubuntu + +# 2. Access Windows projects +cd /mnt/c/Users/YourUsername/Projects +cursor . # or code . + +# 3. Install Claude Code in WSL +npm install -g @anthropic-ai/claude-code +``` + +### macOS +```bash +# Use Homebrew +brew install node +npm install -g @anthropic-ai/claude-code + +# For M1/M2 Macs +arch -arm64 npm install -g @anthropic-ai/claude-code +``` + +### Linux (Ubuntu/Debian) +```bash +# Install Node.js 20 +curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - +sudo apt-get install -y nodejs + +# Install Claude Code +npm install -g @anthropic-ai/claude-code + +# Fix PATH if needed +echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc +``` + +## 🔌 IDE Integration + +### VS Code +```bash +# Install extension +code --install-extension anthropic.claude-code + +# Connect +/ide +``` + +### Cursor +```bash +cursor . # Launch in project +# In integrated terminal: claude +``` + +### Universal Access +- **Shortcuts**: `Cmd+Esc` (Mac) / `Ctrl+Esc` (Windows/Linux) +- **Context sharing**: Open files, selections, linter errors +- **Visual diffs**: Apply changes directly in IDE + +## 🛠️ MCP (Model Context Protocol) Setup + +### Essential MCP Servers + +```bash +# Quick install script +claude mcp add sequential-thinking -s user -- npx -y @modelcontextprotocol/server-sequential-thinking +claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Projects +claude mcp add puppeteer -s user -- npx -y @modelcontextprotocol/server-puppeteer +claude mcp add fetch -s user -- npx -y @kazuph/mcp-fetch +``` + +### API-Based Servers +```bash +# GitHub (requires token) +claude mcp add github -s user -- env GITHUB_TOKEN=token npx -y @modelcontextprotocol/server-github + +# Brave Search (requires API key) +claude mcp add brave-search -s user -- env BRAVE_API_KEY=key npx -y @modelcontextprotocol/server-brave-search +``` + +### Manual Configuration (Better Method) + +Create `.claude.json`: +```json +{ + "mcpServers": { + "filesystem": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "~/Projects"] + }, + "github": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-github"], + "env": {"GITHUB_TOKEN": "your_token"} + } + } +} +``` + +### MCP Scopes + +| Scope | Location | Usage | +|-------|----------|-------| +| `local` | `./.claude.json` | Current directory only | +| `project` | `./.claude/settings.json` | Shareable with team | +| `user` | `~/.claude.json` | All your projects | + +### Popular MCP Servers + +| Server | Purpose | Package | +|--------|---------|---------| +| Sequential Thinking | Multi-step reasoning | `@modelcontextprotocol/server-sequential-thinking` | +| Filesystem | File operations | `@modelcontextprotocol/server-filesystem` | +| Puppeteer | Browser automation | `@modelcontextprotocol/server-puppeteer` | +| GitHub | Git operations | `@modelcontextprotocol/server-github` | +| Sentry | Error monitoring | `@sentry/mcp-server` | +| Linear | Project management | `@linear/mcp-server` | +| DigitalOcean | Cloud deployment | `@digitalocean/mcp` | + +## 📝 Custom Commands & Templates + +### Slash Commands + +Create `.claude/commands/fix-issue.md`: +```markdown +Fix GitHub issue: $ARGUMENTS + +Steps: +1. `gh issue view $ARGUMENTS` +2. Search codebase for relevant files +3. Implement fix +4. Write tests +5. Create PR +``` + +Usage: `/project:fix-issue 123` + +### Personal Commands +Add to `~/.claude/commands/` for global availability. + +## 💡 Pro Tips & Tricks + +### 🎯 Workflow Hacks + +```bash +# Error interruption +Esc # Stop Claude immediately +> "Revert last changes and try different approach" + +# Context management +/clear # Between major tasks (saves tokens) +/compact # Keep summary, reduce context + +# UV package manager fix (Claude struggles with uv) +> "Use uv add, not pip install. Always use uv commands." +``` + +### 🚀 Rapid Development Pattern + +1. Describe project in natural language +2. Let Claude create plan (8-12 steps typical) +3. Use `/clear` between major sections +4. Press `↑` + "continue" for next steps +5. 30-45 minutes for most projects regardless of complexity + +### 📚 Documentation Before Code +```bash +# Best practice for new frameworks +> "Read the Next.js 14 docs at https://nextjs.org/docs then create project with latest best practices" +``` + +### 🎨 CLAUDE.md Personalization +```markdown +# Custom CLAUDE.md +## Team +- Lead: [Your Name/Nickname] +- Package Manager: uv (NOT pip!) +- Test Runner: pytest + +## Project Notes +- Ask [Your Name] for deployment access +- Always use feature branches +``` + +## 🔧 Advanced Configuration + +### User Config (`~/.claude.json`) +```json +{ + "defaultModel": "claude-sonnet-4", + "permissions": { + "allowedTools": ["Edit", "Bash(git*)"], + "deniedTools": ["Bash(rm*)"] + }, + "preferences": { + "autoCompact": true, + "compactThreshold": 50000 + } +} +``` + +### Environment Variables +```bash +export ANTHROPIC_API_KEY=your_key +export CLAUDE_MODEL=claude-sonnet-4 +export MCP_DEBUG=true +export CLAUDE_DEBUG=true +``` + +## 🏢 Enterprise Features + +### Amazon Bedrock +```bash +export AWS_PROFILE=your-profile +claude --provider bedrock --model anthropic.claude-3-5-sonnet +``` + +### Google Vertex AI +```bash +export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json +claude --provider vertex --model claude-3-5-sonnet +``` + +## 🐛 Common Issues & Fixes + +### Installation Problems +```bash +# Command not found +echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc +source ~/.bashrc + +# Permission denied (don't use sudo!) +mkdir ~/.npm-global +npm config set prefix '~/.npm-global' +``` + +### WSL Issues +```bash +# Wrong npm (using Windows instead of WSL) +which npm # Should show /usr/bin/npm + +# Performance issues +# Edit %USERPROFILE%\.wslconfig +[wsl2] +memory=8GB +processors=4 +``` + +### MCP Debugging +```bash +claude --mcp-debug # Debug MCP issues +/mcp # Check server status +claude mcp list # List configured servers +``` + +### Rate Limiting +```bash +/cost # Check usage +/clear # Clear context to save tokens +/upgrade # Get Claude Max for higher limits +``` + +## 🎥 Quick Commands Reference + +```bash +# Project setup +claude /init # Generate docs +claude /ide # Connect to IDE + +# Development +claude -p "fix all TypeScript errors" # Quick fixes +claude -p "add tests for auth module" # Add functionality +claude -p "optimize this component" # Improvements + +# Git workflows +claude -p "review this PR and suggest improvements" +claude -p "create commit message for current changes" +claude -p "resolve merge conflicts" + +# Automation +claude --dangerously-skip-permissions -p "lint and format all files" +``` + +## 📚 Resources + +- **Docs**: https://docs.anthropic.com/claude-code +- **GitHub**: https://github.com/anthropics/claude-code +- **NPM**: https://www.npmjs.com/package/@anthropic-ai/claude-code +- **Best Practices**: https://www.anthropic.com/engineering/claude-code-best-practices + +### Community Guides +- [Harper Reed's Workflow](https://harper.blog/2025/05/08/basic-claude-code/) +- [Philipp Spiess's Tips](https://spiess.dev/blog/how-i-use-claude-code) +- [MCP Setup Guide](https://scottspence.com/posts/configuring-mcp-tools-in-claude-code) + +--- + +## 🎯 The Claude Code Mindset + +1. **Think conversations, not commands** - Use natural language +2. **Iterate rapidly** - First attempt won't be perfect +3. **Context is king** - Be specific, clear frequently +4. **Monitor & interrupt** - Use `Esc` when things go wrong +5. **Document everything** - Future you will thank you + +**Need help?** Use `/bug` in Claude Code or join community discussions. Happy coding! 🚀