1. Quick Start
1.1 Installation
Choose your preferred installation method based on your operating system:
/*──────────────────────────────────────────────────────────────*/ /* Universal Method */ npm install -g @anthropic-ai/claude-code /*──────────────────────────────────────────────────────────────*/ /* Windows (CMD) */ npm install -g @anthropic-ai/claude-code /* Windows (PowerShell) */ irm https://claude.ai/install.ps1 | iex /*──────────────────────────────────────────────────────────────*/ /* macOS (npm) */ npm install -g @anthropic-ai/claude-code /* macOS (Homebrew) */ brew install claude-code /* macOS (Shell Script) */ curl -fsSL https://claude.ai/install.sh | sh /*──────────────────────────────────────────────────────────────*/ /* Linux (npm) */ npm install -g @anthropic-ai/claude-code /* Linux (Shell Script) */ curl -fsSL https://claude.ai/install.sh | sh
Verify Installation
Updating Claude Code
Keep Claude Code up to date for the latest features, bug fixes, and model improvements:
Available maintenance commands:
| Command | Purpose | When to Use |
|---|---|---|
claude update | Check and install updates | Weekly or when encountering issues |
claude doctor | Verify auto-updater health | After system changes or if updates fail |
claude --version | Display current version | Before reporting bugs |
claude auth login | Authenticate from the command line | CI/CD, devcontainers, scripted setups |
claude auth status | Check current authentication state | Verify which account/method is active |
claude auth logout | Clear stored credentials | Shared machines, security cleanup |
Update frequency recommendations:
- Weekly: Check for updates during normal development
- Before major work: Ensure latest features and fixes
- After system changes: Run
claude doctorto verify health - On unexpected behavior: Update first, then troubleshoot
Desktop App: Claude Code Without the Terminal
Claude Code is available in two forms: the CLI (what this guide focuses on) and the Code tab in the Claude Desktop app. Same underlying engine, graphical interface instead of terminal. Available on macOS and Windows — no Node.js installation required.
What the desktop adds on top of standard Claude Code:
| Feature | Details |
|---|---|
| Visual diff review | Review file changes inline with comments before accepting |
| Live app preview | Claude starts your dev server, opens an embedded browser, auto-verifies changes |
| GitHub PR monitoring | Auto-fix CI failures, auto-merge once checks pass |
| Parallel sessions | Multiple sessions in the sidebar, each with automatic Git worktree isolation |
| Connectors | GitHub, Slack, Linear, Notion — GUI setup, no manual MCP config |
| File attachments | Attach images and PDFs directly to prompts |
| Remote sessions | Run long tasks on Anthropic’s cloud, continue after closing the app |
| SSH sessions | Connect to remote machines, cloud VMs, dev containers |
When to choose Desktop vs CLI:
| Use Desktop when… | Use CLI when… |
|---|---|
| You want visual diff review | You need scripting or automation (--print, output piping) |
| You’re onboarding colleagues | You use third-party providers (Bedrock, Vertex, Foundry) |
| You want session management in a sidebar | You need dontAsk permission mode |
| You’re doing a live demo or pair review | You need agent teams / multi-agent orchestration |
| You want file attachments (images, PDFs) | You’re on Linux (Desktop is macOS + Windows only) |
What’s NOT available in Desktop (CLI only): third-party API providers, scripting flags (--print, --output-format), --allowedTools/--disallowedTools, agent teams, --verbose, Linux.
Shared configuration: Desktop and CLI read the same files — CLAUDE.md, MCP servers (via ~/.claude.json or .mcp.json), hooks, skills, and settings. Your CLI setup carries over automatically.
Migration tip: run /desktop in the terminal to move an active CLI session into the Desktop app. On macOS and Windows only.
Note on MCP servers: MCP servers configured in claude_desktop_config.json (the Chat tab) are separate from Claude Code. To use MCP servers in the Code tab, configure them in ~/.claude.json or your project’s .mcp.json. See Section 8.1 — MCP.
Full reference: code.claude.com/docs/en/desktop
Platform-Specific Paths
| Platform | Global Config Path | Shell Config |
|---|---|---|
| macOS/Linux | ~/.claude/ | ~/.zshrc or ~/.bashrc |
| Windows | %USERPROFILE%\.claude\ | PowerShell profile |
Windows Users: Throughout this guide, when you see ~/.claude/, use %USERPROFILE%\.claude\ or C:\Users\YourName\.claude\ instead.
First Launch
On first launch:
- You’ll be prompted to authenticate with your Anthropic account
- Accept the terms of service
- Claude Code will index your project (may take a few seconds for large codebases)
Note: Claude Code requires an active Anthropic subscription. See claude.com/pricing for current plans and token limits.
1.2 First Workflow
Let’s fix a bug together. This demonstrates the core interaction loop.
Step 1: Describe the Problem
Step 2: Claude Analyzes
Claude will:
- Search your codebase for relevant files
- Read the login-related code
- Identify the issue
- Propose a fix
Step 3: Review the Diff
💡 Critical: Always read the diff before accepting. This is your safety net.
Step 4: Accept or Reject
- Press
yto accept the change - Press
nto reject and ask for alternatives - Press
eto edit the change manually
Step 5: Verify
Claude will run your test suite and report results.
Step 6: Commit (Optional)
Claude will create a commit with an appropriate message.
1.3 Essential Commands
These 7 commands are the ones I use most frequently:
| Command | Action | When to Use |
|---|---|---|
/help | Show all commands | When you’re lost |
/clear | Clear conversation | Start fresh |
/compact | Summarize context | Running low on context |
/status | Show session info | Check context usage |
/exit or Ctrl+D | Exit Claude Code | Done working |
/plan | Enter Plan Mode | Safe exploration |
/rewind | Undo changes | Made a mistake |
/voice | Toggle voice input | Speak instead of type |
Quick Actions & Shortcuts
| Shortcut | Action | Example |
|---|---|---|
!command | Run shell command directly | !git status, !npm test |
@file.ts | Reference a specific file | @src/app.tsx, @README.md |
Ctrl+C | Cancel current operation | Stop long-running analysis |
Ctrl+R | Search command history | Find previous prompts |
Esc | Stop Claude mid-action | Interrupt current operation |
Shell Commands with !
Execute commands immediately without asking Claude to do it:
When to use ! vs asking Claude:
Use ! for… | Ask Claude for… |
|---|---|
Quick status checks (!git status) | Git operations requiring decisions |
View commands (!cat, !ls) | File analysis and understanding |
| Already-known commands | Complex command construction |
| Fast iteration in terminal | Commands you’re unsure about |
Example workflow:
File References with @
Reference specific files in your prompts for targeted operations:
Why use @:
- Precision: Target exact files instead of letting Claude search
- Speed: Skip file discovery phase
- Context: Signals Claude to read these files on-demand via tools
- Clarity: Makes your intent explicit
Working with Images and Screenshots
Claude Code supports direct image input for visual analysis, mockup implementation, and design feedback.
How to use images:
- Paste directly in terminal (macOS/Linux/Windows with modern terminal): Copy screenshot or image to clipboard (
Cmd+Shift+4on macOS,Win+Shift+Son Windows) In Claude Code session, paste withCmd+V/Ctrl+VClaude receives the image and can analyze it - Drag and drop (some terminals): Drag image file into terminal window Claude loads and processes the image
- Reference with path: Terminal window
Analyze this mockup: /path/to/design.png
Common use cases:
Supported formats: PNG, JPG, JPEG, WebP, GIF (static)
Best practices:
- High contrast: Ensure text/diagrams are clearly visible
- Crop relevantly: Remove unnecessary UI elements for focused analysis
- Annotate when needed: Circle/highlight specific areas you want Claude to focus on
- Combine with text: “Focus on the header section” provides additional context
Example workflow:
Limitations:
- Images consume significant context tokens (equivalent to ~1000-2000 words of text)
- Use
/statusto monitor context usage after pasting images - Consider describing complex diagrams textually if context is tight
- Some terminals may not support clipboard image pasting (fallback: save and reference file path)
💡 Pro tip: Take screenshots of error messages, design mockups, and documentation instead of describing them textually. Visual input is often faster and more precise than written descriptions.
When designing UI before implementation, low-fidelity wireframes help Claude understand intent without over-constraining the output. Here are recommended tools that work well with Claude Code:
| Tool | Type | Price | MCP Support | Best For |
|---|---|---|---|---|
| Excalidraw | Hand-drawn style | Free | ✓ Community | Quick wireframes, architecture diagrams |
| tldraw | Minimalist canvas | Free | Emerging | Real-time collaboration, custom integrations |
| Pencil | IDE-native canvas | Free* | ✓ Native | Claude Code integrated, AI agents, git-based |
| Frame0 | Low-fi + AI | Free | ✓ | Modern Balsamiq alternative, AI-assisted |
| Paper sketch | Physical | Free | N/A | Fastest iteration, zero setup |
Excalidraw (excalidraw.com):
- Open-source, hand-drawn aesthetic reduces over-specification
- MCP available:
github.com/yctimlin/mcp_excalidraw - Export: PNG recommended (1000-1200px), also SVG/JSON
- Best for: Architecture diagrams, quick UI sketches
tldraw (tldraw.com):
- Infinite canvas with minimal UI, excellent SDK for custom apps
- Agent starter kit available for building AI-integrated tools
- Export: JSON native, PNG via screenshot
- Best for: Collaborative wireframing, embedding in custom tools
Frame0 (frame0.app):
- Modern Balsamiq alternative (2025), offline-first desktop app
- Built-in AI: text-to-wireframe, screenshot-to-wireframe conversion
- Native MCP integration for Claude workflows
- Best for: Teams wanting low-fi wireframes with AI assistance
Pencil (pencil.dev):
- IDE-native infinite canvas (Cursor/VSCode/Claude Code)
- AI multiplayer agents running in parallel for collaborative design
- Format:
.penJSON, git-versionnable with branch/merge support - MCP: Bi-directional read+write access to design files
- Founded by Tom Krcha (ex-Adobe XD), funded a16z Speedrun
- Export: .pen JSON native, PNG via screenshot, Figma import (copy-paste)
- Best for: Engineer-designers wanting design-as-code paradigm, teams on Cursor/Claude Code workflows
⚠️ Note: Launched January 2026, strong traction (1M+ views, FAANG adoption) but still maturing. Currently free; pricing model TBD. Recommended for early adopters comfortable with rapid iteration.
Paper + Photo:
- Seriously, this works extremely well
- Snap a photo with your smartphone → paste directly in Claude Code
- Tips: Good lighting, tight crop, avoid reflections/shadows
- Claude handles rotations and hand-drawn artifacts well
Recommended export settings: PNG format, 1000-1200px on longest side, high contrast
Figma provides an official MCP server (announced 2025) that gives Claude direct access to your design files, dramatically reducing token usage compared to screenshots alone.
Setup options:
Available tools via Figma MCP:
| Tool | Purpose | Tokens |
|---|---|---|
get_design_context | Extracts React+Tailwind structure from frames | Low |
get_variable_defs | Retrieves design tokens (colors, spacing, typography) | Very low |
get_code_connect_map | Maps Figma components → your codebase | Low |
get_screenshot | Captures visual screenshot of frame | High |
get_metadata | Returns node properties, IDs, positions | Very low |
Why use Figma MCP over screenshots?
- 3-10x fewer tokens: Structured data vs. image analysis
- Direct token access: Colors, spacing values are extracted, not interpreted
- Component mapping: Code Connect links Figma → actual code files
- Iterative workflow: Small changes don’t require new screenshots
Recommended workflow:
Example session:
Prerequisites:
- Figma account (Free tier works for remote MCP)
- Dev Mode seat for desktop MCP features
- Design file must be accessible to your account
MCP config file (examples/mcp-configs/figma.json):
Understanding Claude’s image processing helps optimize for speed and accuracy.
Resolution guidelines:
| Range | Effect |
|---|---|
| < 200px | Loss of precision, text unreadable |
| 200-1000px | Sweet spot for most wireframes |
| 1000-1568px | Optimal quality/token balance |
| 1568-8000px | Auto-downscaled (wastes upload time) |
| > 8000px | Rejected by API |
Token calculation: (width × height) / 750 ≈ tokens consumed
| Image Size | Approximate Tokens |
|---|---|
| 200×200 | ~54 tokens |
| 500×500 | ~334 tokens |
| 1000×1000 | ~1,334 tokens |
| 1568×1568 | ~3,279 tokens |
Format recommendations:
| Format | Use When |
|---|---|
| PNG | Wireframes, diagrams, text, sharp lines |
| WebP | General screenshots, good compression |
| JPEG | Photos only—compression artifacts harm line detection |
| GIF | Avoid (static only, poor quality) |
Optimization checklist:
- Crop to relevant area only
- Resize to 1000-1200px if larger
- Use PNG for wireframes/diagrams
- Check
/statusafter pasting to monitor context usage - Consider text description if context is >70%
💡 Token tip: A 1000×1000 wireframe uses ~1,334 tokens. The same information as structured text (via Figma MCP) might use 200-400 tokens. Use screenshots for visual context, structured data for implementation.
Session Continuation and Resume
Claude Code allows you to continue previous conversations across terminal sessions, maintaining full context and conversation history.
Two ways to resume:
- Continue last session (
--continueor-c): Terminal window# Automatically resumes your most recent conversationclaude --continue# Short formclaude -c - Resume specific session (
--resume <id>or-r <id>): Terminal window# Resume a specific session by IDclaude --resume abc123def# Short formclaude -r abc123def - Link to a GitHub PR (
--from-pr <number>, v2.1.49+): Terminal window# Start a session linked to a specific PRclaude --from-pr 123 # Sessions created via gh pr create during a Claude session# are auto-linked to that PR — use --from-pr to resume themgh pr create --title "Add auth" --body "..."# Later:claude --from-pr 123 # Resumes the session context for this PRUseful for continuing work on a feature exactly where you left off relative to a specific PR — no need to remember session IDs.
Finding session IDs:
Session Search Tools: For fast session search, see session-search.sh (bash, lightweight) and cc-sessions.py (Python, advanced features: incremental index, partial ID resume, branch filter, and discover for automated pattern analysis — GitHub). Also: Observability Guide.
Common use cases:
| Scenario | Command | Why |
|---|---|---|
| Interrupted work | claude -c | Pick up exactly where you left off |
| Multi-day feature | claude -r abc123 | Continue complex task across days |
| After break/meeting | claude -c | Resume without losing context |
| Parallel projects | claude -r <id> | Switch between different project contexts |
| Code review follow-up | claude -r <id> | Address review comments in original context |
Example workflow:
Best practices:
- Use
/exitproperly: Always exit with/exitorCtrl+D(not force-kill) to ensure session is saved - Descriptive final messages: End sessions with context (“Ready for testing”) so you remember the state when resuming
- Proactive context management: Monitor with
/statusand use research-backed thresholds: < 70%: Optimal — full reasoning capacity 75%: Good time to/compactmanually — before quality degrades 85%: Auto-compact territory — Claude Code will compress automatically once remaining context drops below its fixed buffer (~6-7% of window). Manual handoff recommended before this point (research-backed) 95%: Force handoff — severe quality degradation, reset immediately - Session naming: Use
/renameto give sessions descriptive names — critical when running multiple sessions in parallel (see Auto-Rename Pattern below)
Resume vs. fresh start:
| Use Resume When… | Start Fresh When… |
|---|---|
| Continuing a specific feature/task | Switching to unrelated work |
| Building on previous decisions | Previous session went off track |
| Context is still relevant (< 75%) | Context is bloated (> 85%) |
| Multi-step implementation in progress | Quick one-off questions |
Limitations:
- Sessions are stored locally (not synced across machines)
- Very old sessions may be pruned (depends on local storage limits)
- Corrupted sessions can’t be resumed (start fresh with
/clear) - Cannot resume sessions started with different model or MCP config
Context preservation:
When you resume, Claude retains:
- ✅ Full conversation history
- ✅ Files previously read/edited
- ✅ CLAUDE.md and project settings
- ✅ MCP server state (if Serena is used)
- ✅ Uncommitted code changes awareness
Combining with MCP Serena:
For advanced session management with project memory and symbol tracking:
💡 Pro tip: Use claude -c as your default way to start Claude Code in active projects. This ensures you never lose context from previous sessions unless you explicitly want a fresh start with claude (no flags).
Source: DeepTo Claude Code Guide - Context Resume Functions
Session Pattern Discovery (cc-sessions discover) {#session-pattern-discovery}
Your session history is a data source. Every time you ask Claude to do the same kind of thing across multiple sessions, that’s a signal: extract it as a skill, command, or CLAUDE.md rule and stop paying the context tax on every request.
cc-sessions discover automates this analysis. It reads your session history, finds recurring patterns in user messages, and tells you what to extract.
Two modes:
| Mode | How | Cost | Speed |
|---|---|---|---|
| N-gram (default) | Tokenizes messages, builds frequency index of 3-6 word phrases | Free, local | ~3s for 12 projects |
--llm | Deduplicates messages, sends batch to claude --print | Uses your subscription | ~15s |
Example output:
cc-sessions discover — 847 sessions · 12 project(s) · since 90d
📋 CLAUDE.md RULE
────────────────────────────────────────────────────────────
write tests before implementation
234 sessions (28%) · 891 occurrences · score 0.416
→ 3a72f1c4-...
🧩 SKILL
────────────────────────────────────────────────────────────
security review authentication flow
71 sessions (8%) · 203 occurrences · score 0.084
→ 9f1c3a22-...
⚡ COMMAND
────────────────────────────────────────────────────────────
generate prisma migration rollback script
18 sessions (2%) · 44 occurrences · score 0.021
→ 44aab71c-...The 20% rule built into scoring: patterns above 20% of sessions become CLAUDE.md rule suggestions (always load), 5-20% become skill suggestions (load on demand), below 5% become command suggestions (explicit invocation). The cross-project bonus (1.5×) prioritizes patterns that recur across different codebases — those are worth extracting even at lower frequency.
See also: §5.1 Understanding Skills for the distinction between CLAUDE.md rules, skills, and commands, and the 20% rule for the decision framework.
GitHub: FlorianBruniaux/cc-sessions
Session Auto-Rename
When running multiple Claude Code sessions in parallel (split terminals, WebStorm tabs, parallel workstreams), the /resume picker shows sessions by timestamp or truncated first prompt — impossible to distinguish at a glance.
Two complementary approaches solve this. Use one or both together.
Approach A: CLAUDE.md behavioral instruction (mid-session)
A behavioral instruction in ~/.claude/CLAUDE.md makes Claude call /rename automatically after 2-3 exchanges. No tooling required, works across all IDEs and terminals.
This works well during active sessions but depends on Claude following the instruction consistently.
Approach B: SessionEnd hook (automatic, AI-generated)
A SessionEnd hook reads the session’s JSONL file directly from ~/.claude/projects/, extracts the first few user messages as context, and calls claude -p --model claude-haiku-4-5-20251001 to generate a 4-6 word descriptive title. If Haiku is unavailable, it falls back to a sanitized version of the first message.
The hook updates both sessions-index.jsonl (for custom session browsers) and the slug field in the JSONL file (for native /resume compatibility).
Requirements: claude CLI on PATH, python3 for JSON parsing. Set SESSION_AUTORENAME=0 to disable for a specific session.
After the session ends, the /resume picker shows "fix auth middleware" instead of "2026-03-04T14:23...".
Using both together
The two approaches handle different moments in a session’s lifecycle. Approach A renames early so the session is identifiable while it’s still running. Approach B renames at the end with a title that reflects the full session scope, potentially overwriting the mid-session name with something more accurate.
Limitation (both approaches): Terminal tab names in WebStorm and iTerm2 are not affected. JetBrains filters ANSI escape sequences. The Claude session is renamed, not the OS tab.
See full template: examples/claude-md/session-naming.md See hook template: examples/hooks/bash/auto-rename-session.sh
1.4 Permission Modes
Claude Code has five permission modes that control how much autonomy Claude has:
Default Mode
Claude asks permission before:
- Editing files
- Running commands
- Making commits
This is the safest mode for learning.
Auto-accept Mode (acceptEdits)
Claude auto-approves file edits but still asks for shell commands. Use when you trust the edits and want speed.
⚠️ Warning: Only use auto-accept for well-defined, reversible operations.
Plan Mode
Claude can only read and analyze, no modifications allowed. Perfect for:
- Understanding unfamiliar code
- Exploring architectural options
- Safe investigation before changes
Exit with /execute when ready to make changes.
Don’t Ask Mode (dontAsk)
Auto-denies tools unless pre-approved via /permissions or permissions.allow rules. Claude never interrupts with permission prompts: if a tool isn’t explicitly allowed, it’s silently denied.
Use for restrictive workflows where you want tight control over which tools run, without interactive confirmation.
Bypass Permissions Mode (bypassPermissions)
Auto-approves everything, including shell commands. No permission prompts at all.
⚠️ Warning: Only use in sandboxed CI/CD environments. Requires --dangerously-skip-permissions to enable from CLI. Never use on production systems or with untrusted code.
Safety invariant — some paths always prompt, even in bypassPermissions mode:
Certain writes are considered too sensitive to auto-approve under any configuration. Claude Code always prompts before modifying:
| Protected target | Examples |
|---|---|
.git/ directory | git hooks, refs, config inside the repo |
.claude/ directory | agents, skills, hooks, settings — except .claude/worktrees/ |
| Shell config files | .bashrc, .zshrc, .bash_profile, .profile |
| VCS and tool configs | .gitconfig, .mcp.json, .claude.json |
Content-specific allow rules (e.g., Bash(npm publish:*)) defined in settings.json or CLAUDE.md also survive bypassPermissions — they continue to apply as additional filters on top of any permission mode. This lets you build precise guardrails (e.g., “always ask before publishing to npm”) that hold regardless of how the session is launched.
Permission Fatigue (anti-pattern)
A common trap: you’re deep in a task, prompts keep appearing, you start approving them without reading. This is permission fatigue — and it defeats the purpose of the permission system entirely.
The fix is to pick the right mode upfront rather than clicking through prompts one by one:
| Situation | Right mode | Why |
|---|---|---|
| Exploratory work, unfamiliar codebase | Plan mode | Can’t accidentally change anything |
| Trusted local edits, no shell ops | acceptEdits | Approves edits silently, still gates commands |
| Automated pipeline, sandboxed env | bypassPermissions | No prompts at all — but only safe in isolation |
| You need one tool auto-approved | permissions.allow in CLAUDE.md | Granular, not all-or-nothing |
| Default new session | Default mode | Explicit review of each action |
The failure mode to avoid: reaching for --dangerously-skip-permissions on a dev machine with SSH keys, API tokens, or production access in scope. The permissions system only adds value if you actually read what you’re approving — or configure a mode that matches your real trust level.
1.5 Productivity Checklist
You’re ready for Day 2 when you can:
- Launch Claude Code in your project
- Describe a task and review the proposed changes
- Accept or reject changes after reading the diff
- Run a shell command with
! - Reference a file with
@ - Use
/clearto start fresh - Use
/statusto check context usage - Exit cleanly with
/exitorCtrl+D
1.6 Migrating from Other AI Coding Tools
Last updated: March 2026. AI coding tools evolve rapidly; verify pricing and features on official sites.
Switching from GitHub Copilot, Cursor, or other AI assistants? Here’s what you need to know.
Why Claude Code is Different
| Feature | GitHub Copilot | Cursor | Windsurf | Zed | Claude Code |
|---|---|---|---|---|---|
| Interaction | Agent + Chat + Autocomplete | Agent + Chat + Autocomplete | Cascade agent | Agent panel + Zeta2 | CLI + conversation |
| Context | Full codebase (agent mode) | Codebase-aware (Composer) | ~200K tokens (IDE) | Up to 1M tokens | Entire project (agentic) |
| Autonomy | Agent mode + coding agent | Agent + Background Agents | Cascade (Cognition AI) | Agent + subagents | Full task execution |
| Customization | MCP, custom agents, AGENTS.md | MCP Apps, .cursorrules | Cascade hooks | ACP Registry, MCP | Agents, skills, hooks, MCP |
| MCP support | ✅ GA (auto-approve) | ✅ MCP Apps v2.6 | Not documented | ✅ OAuth | ✅ Native |
| Inline autocomplete | ✅ Native | ✅ Tab | ✅ Supercomplete | ✅ Zeta2 | ❌ Use alongside |
| Offline/local | ❌ | ❌ | ❌ | BYO providers | ❌ |
| Best for | IDE-native, GitHub teams | IDE-native AI UX | Multi-agent IDE | Speed + open-source | Terminal/CLI, large refactors |
Pricing comparison (March 2026)
| Tool | Free | Pro | Power/Plus | Teams | Enterprise |
|---|---|---|---|---|---|
| GitHub Copilot | ✅ (2K completions) | $10/mo | Pro+ $39/mo | Business $19/seat | $39/seat |
| Cursor | ✅ (2K completions) | $20/mo | Ultra $200/mo | $40/seat | — |
| Windsurf | ✅ (25 prompts) | $20/mo | $200/mo | $30/seat | $60/seat |
| Zed | — | $10/mo | — | — | — |
| Claude Code | — | $20/mo | Max $100-200/mo | — | Via Anthropic |
Key mindset shift: Claude Code is a structured context system, not a chatbot or autocomplete tool. You build persistent context (CLAUDE.md, skills, hooks) that compounds over time — see §2.5.
What Copilot Does Well
- Inline suggestions - Fast autocomplete as you type
- Familiar workflow - Works inside your editor
- Low friction - No context switching
- Agent mode - Multi-file edits, terminal commands, autonomous iteration (GA in VS Code + JetBrains)
- Free tier - 2K completions + 50 premium requests at $0/month
- Model choice - Claude, Codex, GPT models selectable since Feb 2026
What Claude Code Does Better
- Terminal-native workflow - No IDE dependency; works over SSH, in CI/CD, in any terminal
- Persistent context system - CLAUDE.md + skills + hooks compound over time; Copilot’s custom instructions are newer and less granular
- Agent orchestration - Agent teams, sub-agents, parallel execution with deterministic multi-file coordination
- Pay-per-use model - No premium request quotas; Copilot agent mode is constrained by monthly premium limits (300/mo on Pro, 1500/mo on Pro+)
- Headless/CI mode - Run in pipelines, automation, non-interactive contexts
- Deep customization - Custom slash commands, event hooks, skill modules, MCP server composition
Hybrid Approach (Recommended)
Use Copilot for:
- Quick autocomplete while typing
- Boilerplate code generation
- Simple function completions
- Straightforward multi-file tasks within your IDE (agent mode)
- Quick chat questions about visible code
Use Claude Code for:
- Feature implementation spanning multiple repos or cutting across architectures
- Systematic debugging requiring deep codebase traversal
- CI/CD automation and headless execution
- Code reviews and refactoring at scale
- Understanding unfamiliar codebases
- Writing tests for entire modules
Workflow example:
What Cursor Does Well
- Inline editing - Direct code modifications in editor
- GUI interface - Familiar VS Code experience
- Chat + autocomplete - Both modalities in one tool
- Agent mode - Autonomous multi-file editing (GA March 2026)
- Background Agents - Delegated tasks on remote VMs, parallel execution
What Claude Code Does Better
- Terminal-native workflow - Better for CLI-heavy developers
- Advanced customization - Agents, skills, hooks, commands
- MCP ecosystem maturity - Native MCP with broader server compatibility and deeper integration
- Cost transparency - Direct API billing, no credit system or opaque quotas
- Git integration - Native git operations, commit generation
- CI/CD integration - Headless mode for automation
When to Switch
Stick with Cursor if:
- You strongly prefer GUI over CLI
- You want all-in-one IDE experience
- You prefer GUI-first workflow with integrated agent mode
- You don’t need advanced customization
Switch to Claude Code if:
- You’re comfortable with terminal workflows
- You want deeper customization (agents, hooks)
- You work with complex, multi-repo projects
- You want to integrate AI into CI/CD
- You want direct API billing without credit pools
Running Both
You can use both tools simultaneously:
Week 1: Learning Phase
Week 2: Establishing Workflow
Week 3-4: Advanced Usage
Common Migration Issues
Issue 1: “I miss inline suggestions”
- Solution: Keep using Copilot/Cursor for autocomplete, use Claude Code for complex tasks
- Alternative: Request Claude to generate code snippets you can paste
Issue 2: “Context switching is annoying”
- Solution: Use split terminal (editor on left, Claude Code on right)
- Tip: Set up keyboard shortcut to toggle terminal focus
Issue 3: “I don’t know when to use which tool”
- Rule of thumb: <5 lines of code → Use Copilot/autocomplete 5-50 lines, single file → Either tool works >50 lines or multi-file → Use Claude Code
Issue 4: “Claude Code is slower than autocomplete”
- Reality check: Claude Code solves different problems
- Don’t compare: Autocomplete vs. full task execution
- Optimize: Use specific queries, manage context well
Issue 5: “Costs are unpredictable”
- Solution: Track costs in Anthropic Console
- Budget: Set mental budget per session ($0.10-$0.50)
- Optimize: Use
/compact, be specific in queries
Transition Strategies
Strategy 1: Gradual (Recommended)
Strategy 2: Cold Turkey
Strategy 3: Task-Based
Measuring Success
You know you’ve successfully migrated when:
- You instinctively reach for Claude Code for complex tasks
- You understand context management without thinking
- You’ve created at least 2-3 custom commands/agents
- You can estimate costs before starting a session
- You prefer Claude Code’s explanations over inline docs
- You’ve integrated Claude Code into your daily workflow
Subjective productivity indicators (your experience may vary):
- Feeling more productive on complex tasks
- Spending less time on boilerplate and debugging
- Catching more issues through Claude reviews
- Better understanding of unfamiliar code
1.7 Trust Calibration: When and How Much to Verify
AI-generated code requires proportional verification based on risk level. Blindly accepting all output or paranoidly reviewing every line both waste time. This section helps you calibrate your trust.
The Problem: Verification Debt
Research consistently shows AI code has higher defect rates than human-written code:
| Metric | AI vs Human | Source |
|---|---|---|
| Logic errors | 1.75× more | ACM study, 2025 |
| Security flaws | 45% contain vulnerabilities | Veracode GenAI Report, 2025 |
| XSS vulnerabilities | 2.74× more | CodeRabbit study, 2025 |
| PR size increase | +18% | Jellyfish, 2025 |
| Incidents per PR | +24% | Cortex.io, 2026 |
| Change failure rate | +30% | Cortex.io, 2026 |
Key insight: AI produces code faster but verification becomes the bottleneck. The question isn’t “does it work?” but “how do I know it works?”
Nuance on downstream maintainability: A 2-phase blind RCT (Borg et al., 2025, n=151 professional developers) found no significant difference in the time needed for downstream developers to evolve AI-generated vs. human-generated code. The defect rates above are real — but they do not systematically translate into higher maintenance burden for the next developer. The risk is more narrowly scoped than commonly assumed. (arXiv:2507.00788)
The Verification Spectrum
Not all code needs the same scrutiny. Match verification effort to risk:
| Code Type | Verification Level | Time Investment | Techniques |
|---|---|---|---|
| Boilerplate (configs, imports) | Light skim | 10-30 sec | Glance, trust structure |
| Utility functions (formatters, helpers) | Quick test | 1-2 min | One happy path test |
| Business logic | Deep review + tests | 5-15 min | Line-by-line, edge cases |
| Security-critical (auth, crypto, input validation) | Maximum + tools | 15-30 min | Static analysis, fuzzing, peer review |
| External integrations (APIs, databases) | Integration tests | 10-20 min | Mock + real endpoint test |
Solo vs Team Verification
Solo Developer Strategy:
Without peer reviewers, compensate with:
- High test coverage (>70%): Your safety net
- Vibe Review: An intermediate layer between “accept blindly” and “review every line”: Read the commit message / summary Skim the diff for unexpected file changes Run the tests Quick sanity check in the app Ship if green
- Static analysis tools: ESLint, SonarQube, Semgrep catch what you miss
- Time-boxing: Don’t spend 30 min reviewing a 10-line utility
Team Strategy:
With multiple developers:
- AI first-pass review: Let Claude or Copilot review first (catches 70-80% of issues)
- Human sign-off required: AI review ≠ approval
- Domain experts for critical paths: Security code → security-trained reviewer
- Rotate reviewers: Prevent blind spots from forming
The “Prove It Works” Checklist
Before shipping AI-generated code, verify:
Functional correctness:
- Happy path works (manual test or automated)
- Edge cases handled (null, empty, boundary values)
- Error states graceful (no silent failures)
Security baseline:
- Input validation present (never trust user input)
- No hardcoded secrets (grep for
password,secret,key) - Auth/authz checks intact (didn’t bypass existing guards)
Integration sanity:
- Existing tests still pass
- No unexpected file changes in diff
- Dependencies added are justified and audited
Code quality:
- Follows project conventions (naming, structure)
- No obvious performance issues (N+1, memory leaks)
- Comments explain “why” not “what”
Anti-Patterns to Avoid
| Anti-Pattern | Problem | Better Approach |
|---|---|---|
| ”It compiles, ship it” | Syntax ≠ correctness | Run at least one test |
| ”AI wrote it, must be secure” | AI optimizes for plausible, not safe | Always review security-critical code manually |
| ”Tests pass, done” | Tests might not cover the change | Check test coverage of modified lines |
| ”Same as last time” | Context changes, AI may generate different code | Each generation is independent |
| ”Senior dev wrote the prompt” | Seniority doesn’t guarantee output quality | Review output, not input |
| ”It’s just boilerplate” | Even boilerplate can hide issues | At minimum, skim for surprises |
Calibrating Over Time
Your verification strategy should evolve:
- Start cautious: Review everything when new to Claude Code
- Track failure patterns: Where do bugs slip through?
- Tighten critical paths: Double-down on areas with past incidents
- Relax low-risk areas: Trust AI more for stable, tested code types
- Periodic audits: Spot-check “trusted” code occasionally
Mental model: Think of AI as a capable junior developer. You wouldn’t deploy their code unreviewed, but you also wouldn’t rewrite everything they produce.
Putting It Together
┌─────────────────────────────────────────────────────────┐ │ TRUST CALIBRATION FLOW │ ├─────────────────────────────────────────────────────────┤ │ │ │ AI generates code │ │ │ │ │ ▼ │ │ ┌──────────────┐ │ │ │ What type? │ │ │ └──────────────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ Boiler Business Security │ │ -plate logic critical │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ Skim Test + Full review │ │ only review + tools │ │ │ │ │ │ │ └──────┴────────┘ │ │ │ │ │ ▼ │ │ Tests pass? ──No──► Debug & fix │ │ │ │ │ Yes │ │ │ │ │ ▼ │ │ Ship it │ │ │ └─────────────────────────────────────────────────────────┘
“AI lets you code faster—make sure you’re not also failing faster.” — Adapted from Addy Osmani
Attribution: This section draws from Addy Osmani’s “AI Code Review” (Jan 2026), research from ACM, Veracode, CodeRabbit, and Cortex.io.
1.8 Eight Beginner Mistakes (and How to Avoid Them)
Common pitfalls that slow down new Claude Code users:
1. ❌ Skipping the Plan
Mistake: Jumping straight into “fix this bug” without explaining context.
Fix: Use the WHAT/WHERE/HOW/VERIFY format:
2. ❌ Ignoring Context Limits
Mistake: Working until context hits 95% and responses degrade.
Fix: Watch Ctx(u): in the status line. /compact at 70%, /clear at 90%.
3. ❌ Using Vague Prompts
Mistake: “Make this code better” or “Check for bugs”
Fix: Be specific: “Refactor calculateTotal() to handle null prices without throwing”
4. ❌ Accepting Changes Blindly
Mistake: Hitting “y” without reading the diff.
Fix: Always review diffs. Use “n” to reject, then explain what’s wrong.
5. ❌ No Version Control Safety
Mistake: Making large changes without commits.
Fix: Commit before big changes. Use feature branches. Claude can help: /commit
6. ❌ Overly Broad Permissions
Mistake: Setting Bash(*) or --dangerously-skip-permissions
Fix: Start restrictive, expand as needed. Use allowlists: Bash(npm test), Bash(git *)
8. ❌ Treating Claude Code Like a Chatbot
Mistake: Typing ad-hoc instructions every session. Repeating project conventions, re-explaining architecture, manually enforcing quality checks.
Fix: Build structured context that compounds over time:
- CLAUDE.md: Your conventions, stack, and patterns — loaded every session automatically
- Skills: Reusable workflows (
/review,/deploy) for consistent execution - Hooks: Automated guardrails (lint, security, formatting) — zero manual effort
Start with CLAUDE.md in Week 1. See §2.6 Mental Model for the full framework.
Quick Self-Check
Before your next session, verify:
- I have a clear, specific goal
- My project has a CLAUDE.md file (see §2.5)
- I’m on a feature branch (not main)
- I know my context level (
/status) - I’ll review every diff before accepting
Tip: Bookmark Section 9.11 for detailed pitfall explanations and solutions.
2. Core Concepts
Quick jump: The Interaction Loop · Context Management · Plan Mode · Rewind · Model Selection · Mental Model · Config Decision Guide · Data Flow & Privacy
Experienced with Claude Code? Jump to 2.6 Mental Model — the highest-ROI section in this chapter.