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

claude --version

Updating Claude Code

Keep Claude Code up to date for the latest features, bug fixes, and model improvements:

# Check for available updates
claude update

# Alternative: Update via npm
npm update -g @anthropic-ai/claude-code

# Verify the update
claude --version

# Check system health after update
claude doctor

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 doctor to 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

cd your-project
claude

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

You: There's a bug in the login function - users can't log in with email addresses containing a plus sign

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

const emailRegex = /^[a-zA-Z0-9._-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
const emailRegex = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;

💡 Critical: Always read the diff before accepting. This is your safety net.

Step 4: Accept or Reject

Press y to accept the change
Press n to reject and ask for alternatives
Press e to edit the change manually

Step 5: Verify

You: Run the tests to make sure this works

Claude will run your test suite and report results.

Step 6: Commit (Optional)

You: Commit this fix

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:

# Quick status checks
!git status
!npm run test
!docker ps

# View logs
!tail -f logs/app.log
!cat package.json

# Quick searches
!grep -r "TODO" src/
!find . -name "*.test.ts"

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:

You: !git status
Output: Shows 5 modified files

You: Create a commit with these changes, following conventional commits
Claude: [Analyzes files, suggests commit message]

File References with `@`

Reference specific files in your prompts for targeted operations:

# Single file
Review @src/auth/login.tsx for security issues

# Multiple files
Refactor @src/utils/validation.ts and @src/utils/helpers.ts to remove duplication

# With wildcards (in some contexts)
Analyze all test files @src/**/*.test.ts

# Relative paths work
Check @./CLAUDE.md for project conventions

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

Example:

# Without @
You: Fix the authentication bug
Claude: Which file contains the authentication logic? [Wastes time searching]

# With @
You: Fix the authentication bug in @src/auth/middleware.ts
Claude: [Reads file on-demand and proposes fix]

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+4 on macOS, Win+Shift+S on Windows)
- In Claude Code session, paste with Cmd+V / Ctrl+V
- Claude 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:

Analyze this mockup: /path/to/design.png

Common use cases:

# Implement UI from mockup
You: [Paste screenshot of Figma design]
Implement this login screen in React with Tailwind CSS

# Debug visual issues
You: [Paste screenshot of broken layout]
The button is misaligned. Fix the CSS.

# Analyze diagrams
You: [Paste architecture diagram]
Explain this system architecture and identify potential bottlenecks

# Code from whiteboard
You: [Paste photo of whiteboard algorithm]
Convert this algorithm to Python code

# Accessibility audit
You: [Paste screenshot of UI]
Review this interface for WCAG 2.1 compliance issues

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:

You: [Paste screenshot of error message in browser console]
This error appears when users click the submit button. Debug it.

Claude: I can see the error "TypeError: Cannot read property 'value' of null".
This suggests the form field reference is incorrect. Let me check your form handling code...
[Reads relevant files and proposes fix]

Limitations:

Images consume significant context tokens (equivalent to ~1000-2000 words of text)
Use /status to 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.

Wireframing Tools for AI Development

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: .pen JSON, 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 MCP Integration

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:

# Remote MCP (all Figma plans, any machine)
claude mcp add --transport http figma https://mcp.figma.com/mcp

# Desktop MCP (requires Figma desktop app with Dev Mode)
claude mcp add --transport http figma-desktop http://127.0.0.1:3845/mcp

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:

1. get_metadata          → Understand overall structure
2. get_design_context    → Get component hierarchy for specific frames
3. get_variable_defs     → Extract design tokens once per project
4. get_screenshot        → Only when visual reference needed

Example session:

You: Implement the dashboard header from Figma
Claude: [Calls get_design_context for header frame]
→ Returns: React structure with Tailwind classes, exact spacing
Claude: [Calls get_variable_defs]
→ Returns: --color-primary: #3B82F6, --spacing-md: 16px
Claude: [Implements component matching Figma exactly]

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):

{
  "mcpServers": {
    "figma": {
      "transport": "http",
      "url": "https://mcp.figma.com/mcp"
    }
  }
}

Image Optimization for Claude Vision

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 /status after 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 (--continue or -c):

# Automatically resumes your most recent conversation
claude --continue
# Short form
claude -c

Resume specific session (--resume <id> or -r <id>):

# Resume a specific session by ID
claude --resume abc123def
# Short form
claude -r abc123def

Link to a GitHub PR (--from-pr <number>, v2.1.49+):

# Start a session linked to a specific PR
claude --from-pr 123

# Sessions created via gh pr create during a Claude session
# are auto-linked to that PR — use --from-pr to resume them
gh pr create --title "Add auth" --body "..."
# Later:
claude --from-pr 123  # Resumes the session context for this PR

Useful 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:

# Native: Interactive session picker
claude --resume

# Native: List via Serena MCP (if configured)
claude mcp call serena list_sessions

# Recommended: Fast search with ready-to-use resume commands
# See examples/scripts/session-search.sh (bash, zero dependencies, 15ms list, 400ms search)
# See examples/scripts/cc-sessions.py (Python, incremental index, partial resume, branch filter)
cs                    # List 10 most recent sessions
cs "authentication"   # Full-text search across all sessions

# Sessions are also shown when you exit
You: /exit
Session ID: abc123def (saved for resume)

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). 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:

# Day 1: Start implementing authentication
cd ~/project
claude
You: Implement JWT authentication with refresh tokens
Claude: [Analysis and initial implementation]
You: /exit
Session ID: auth-feature-xyz (27% context used)

# Day 2: Continue the work
cd ~/project
claude --continue
Claude: Resuming session auth-feature-xyz...
You: Add rate limiting to the auth endpoints
Claude: [Continues with full context of Day 1 work]

Best practices:

Use /exit properly: Always exit with /exit or Ctrl+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 /status and use research-backed thresholds:
- < 70%: Optimal — full reasoning capacity
- 75%: Auto-compact triggers — Claude Code compresses automatically
- 85%: Manual handoff recommended — start a session handoff before auto-compact degrades quality (research-backed)
- 95%: Force handoff — severe quality degradation, reset immediately
Session naming: Use /rename to 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:

# Initialize Serena memory for the project
claude mcp call serena initialize_session

# Work with full session persistence
You: Implement user authentication
Claude: [Works with Serena tracking symbols and context]

# Exit and resume later with full project memory
claude -c
Claude: [Resumes with Serena's persistent project understanding]

💡 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 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.

# Session Naming (auto-rename)

## Expected behavior

1. **Early rename**: Once the session's main subject is clear (after 2-3 exchanges),
   run `/rename` with a short, descriptive title (max 50 chars)
2. **End-of-session update**: If scope shifted significantly, propose a re-rename before closing

## Title format

`[action] [subject]` — examples:
- "fix whitepaper PDF build"
- "add auth middleware + tests"
- "refactor hook system"
- "update CC releases v2.2.0"

## Rules

- Max 50 characters, no "Session:" prefix, no date
- Action verb first (fix, add, refactor, update, research, debug...)
- Multi-topic: dominant subject only, not an exhaustive list
- Do NOT ask for confirmation on early rename (just do it)

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).

{
  "hooks": {
    "SessionEnd": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/auto-rename-session.sh"
          }
        ]
      }
    ]
  }
}

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`)

You: Turn on auto-accept for the rest of this session

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

/plan

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.

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 /clear to start fresh
Use /status to check context usage
Exit cleanly with /exit or Ctrl+D

1.6 Migrating from Other AI Coding Tools

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	Inline autocomplete	Chat + autocomplete	Cascade agent	Agent panel + inline	CLI + conversation
Context	Current file	Open files	~200K tokens (IDE)	200-400K tokens	Entire project (agentic search)
Autonomy	Suggestions only	Edit + chat	Multi-agent (Wave 13)	Agent panel	Full task execution
Customization	Limited	Extensions	Hooks Cascade	BYO providers + Ollama	Agents, skills, hooks, MCP
Cost Model	$10-20/month flat	Credit-based ($20 Pro incl. + overages)	Credit-based ($15/mo Pro, 500 credits)	Token-based ($10/mo + list price +10%)	Subscription (Pro $20, Max 5x $100, Max 20x $200)
Inline autocomplete	✅ Native	✅ Tab	✅ Supercomplete	✅ Zeta	❌ Use Copilot/Cursor alongside
Offline/local models	❌	❌ (via LiteLLM)	❌	✅ Ollama	❌
Best for	Quick suggestions	IDE-native AI UX	Multi-agent IDE	Speed + local models	Terminal/CLI workflows, large refactors

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.

Migration Guide: GitHub Copilot → Claude Code

What Copilot Does Well

Inline suggestions - Fast autocomplete as you type
Familiar workflow - Works inside your editor
Low friction - No context switching

What Claude Code Does Better

Multi-file refactoring - Copilot: one file at a time | Claude: reads and edits across files
Complex tasks - Copilot: suggests lines | Claude: implements features
Understanding context - Copilot: current file | Claude: can search and read project-wide
Explaining code - Copilot: limited | Claude: detailed explanations
Debugging - Copilot: weak | Claude: systematic root cause analysis

Hybrid Approach (Recommended)

Use Copilot for:

Quick autocomplete while typing
Boilerplate code generation
Simple function completions

Use Claude Code for:

Feature implementation (multi-file changes)
Debugging complex issues
Code reviews and refactoring
Understanding unfamiliar codebases
Writing tests for entire modules

Workflow example:

# Morning: Plan feature with Claude Code
claude
You: "I need to add user authentication. What's the best approach for this codebase?"
# Claude analyzes project, suggests architecture

# During coding: Use Copilot for inline completions
# Type in VS Code, Copilot autocompletes

# Afternoon: Debug with Claude Code
claude
You: "Login fails on mobile but works on desktop. Debug this."
# Claude systematically investigates

# End of day: Review with Claude Code
claude
You: "Review my changes today. Check for security issues."
# Claude reviews all modified files

Migration Guide: Cursor → Claude Code

What Cursor Does Well

Inline editing - Direct code modifications in editor
GUI interface - Familiar VS Code experience
Chat + autocomplete - Both modalities in one tool

What Claude Code Does Better

Terminal-native workflow - Better for CLI-heavy developers
Advanced customization - Agents, skills, hooks, commands
MCP servers - Extensibility beyond what Cursor offers
Cost efficiency - Pay for what you use vs. flat $20/month
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 use it >4 hours/day (flat rate is better)
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 prefer pay-per-use pricing

Running Both

You can use both tools simultaneously:

# Cursor for editing and quick changes
# Claude Code in terminal for complex tasks

# Example workflow:
# 1. Use Cursor to explore and make quick edits
# 2. Open terminal: claude
# 3. Ask Claude Code: "Review my changes and suggest improvements"
# 4. Apply suggestions in Cursor
# 5. Use Claude Code to generate tests

Migration Checklist

Week 1: Learning Phase

□ Complete Quick Start (Section 1)
□ Understand context management (critical!)
□ Try 3-5 small tasks (bug fixes, small features)
□ Learn when to use /plan mode
□ Practice reviewing diffs before accepting

Week 2: Establishing Workflow

□ Create project CLAUDE.md file
□ Set up 1-2 custom commands for frequent tasks
□ Configure MCP servers (Serena, Context7)
□ Define your hybrid workflow (when to use Claude Code vs. other tools)
□ Track costs and optimize based on usage

Week 3-4: Advanced Usage

□ Create custom agents for specialized tasks
□ Set up hooks for automation (formatting, linting)
□ Integrate into CI/CD if applicable
□ Build team patterns if working with others
□ Refine CLAUDE.md based on learnings

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)

Week 1: Use Claude Code 1-2 times/day for specific tasks
Week 2: Use Claude Code for all debugging and reviews
Week 3: Use Claude Code for feature implementation
Week 4: Full workflow integration

Strategy 2: Cold Turkey

Day 1: Disable Copilot/Cursor, force yourself to use only Claude Code
Day 2-3: Frustration period (learning curve)
Day 4-7: Productivity recovery
Week 2+: Full proficiency

Strategy 3: Task-Based

Use Claude Code exclusively for:
- All new features
- All debugging sessions
- All code reviews

Keep Copilot/Cursor for:
- Quick edits
- Autocomplete

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

Solo workflow:
Generate → Vibe Review → Tests pass? → Ship
                ↓
        Tests fail? → Deep review → Fix

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

Team workflow:
Generate → AI Review → Human Review → Merge
              ↓              ↓
         Flag issues    Final approval

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:

WHAT: Fix login timeout error
WHERE: src/auth/session.ts
HOW: Increase token expiry from 1h to 24h
VERIFY: Login persists after browser refresh

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 *)

7. ❌ Mixing Unrelated Tasks

Mistake: “Fix the auth bug AND refactor the database AND add new tests”

Fix: One focused task per session. /clear between different tasks.

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.

1. Quick Start

1.1 Installation

Verify Installation

Updating Claude Code

Desktop App: Claude Code Without the Terminal

Platform-Specific Paths

First Launch

1.2 First Workflow

Step 1: Describe the Problem

Step 2: Claude Analyzes

Step 3: Review the Diff

Step 4: Accept or Reject

Step 5: Verify

Step 6: Commit (Optional)

1.3 Essential Commands

Quick Actions & Shortcuts

Shell Commands with !

File References with @

Working with Images and Screenshots

Wireframing Tools for AI Development

Figma MCP Integration

Image Optimization for Claude Vision

Session Continuation and Resume

Session Auto-Rename

Approach A: CLAUDE.md behavioral instruction (mid-session)

Approach B: SessionEnd hook (automatic, AI-generated)

Using both together

1.4 Permission Modes

Default Mode

Auto-accept Mode (acceptEdits)

Plan Mode

Don’t Ask Mode (dontAsk)

Bypass Permissions Mode (bypassPermissions)

1.5 Productivity Checklist

1.6 Migrating from Other AI Coding Tools

Why Claude Code is Different

Migration Guide: GitHub Copilot → Claude Code

What Copilot Does Well

What Claude Code Does Better

Hybrid Approach (Recommended)

Migration Guide: Cursor → Claude Code

What Cursor Does Well

What Claude Code Does Better

When to Switch

Running Both

Migration Checklist

Week 1: Learning Phase

Week 2: Establishing Workflow

Week 3-4: Advanced Usage

Common Migration Issues

Transition Strategies

Measuring Success

1.7 Trust Calibration: When and How Much to Verify

The Problem: Verification Debt

The Verification Spectrum

Solo vs Team Verification

The “Prove It Works” Checklist

Anti-Patterns to Avoid

Calibrating Over Time

Putting It Together

1.8 Eight Beginner Mistakes (and How to Avoid Them)

1. ❌ Skipping the Plan

2. ❌ Ignoring Context Limits

3. ❌ Using Vague Prompts

4. ❌ Accepting Changes Blindly

5. ❌ No Version Control Safety

6. ❌ Overly Broad Permissions

7. ❌ Mixing Unrelated Tasks

8. ❌ Treating Claude Code Like a Chatbot

Quick Self-Check

2. Core Concepts

Shell Commands with `!`

File References with `@`

Auto-accept Mode (`acceptEdits`)

Don’t Ask Mode (`dontAsk`)

Bypass Permissions Mode (`bypassPermissions`)