# The Ultimate Claude Code Guide

> Quick jump: Installation · First Workflow · Essential Commands · Permission Modes · Productivity Checklist · Migrating from Other Tools · Beginner Mistakes

- Skill: `tools-only/the-ultimate-claude-code-guide` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/the-ultimate-claude-code-guide`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/the-ultimate-claude-code-guide/raw
- Safety review: pending (external: skill-scanner PASS, skillspector FAIL)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-29
- Page: https://skillmd.com/skills/tools-only/the-ultimate-claude-code-guide

---


# The Ultimate Claude Code Guide

> A comprehensive, self-contained guide to mastering Claude Code - from zero to power user.

**Author**: Florian BRUNIAUX | Founding Engineer [@Méthode Aristote](https://methode-aristote.fr)

**Written with**: Claude (Anthropic)

**Reading time**: ~30-40 hours (full) | ~15 minutes (Quick Start only)

**Last updated**: January 2026

**Version**: 3.29.0

---

## Before You Start

**This guide is not official Anthropic documentation.** It's a community resource based on my exploration of Claude Code over several months.

**What you'll find:**
- Patterns that have worked for me
- Observations that may not generalize to your workflow
- Time estimates and percentages that are rough approximations, not measurements

**What you won't find:**
- Definitive answers (the tool is too new)
- Benchmarked performance claims
- Guarantees that any technique will work for you

**Use critically. Experiment. Share what works for you.**

> **⚠️ Note (Jan 2026)**: If you've heard about **ClawdBot** recently, that's a **different tool**. ClawdBot is a self-hosted chatbot assistant accessible via messaging apps (Telegram, WhatsApp, etc.), designed for personal automation and smart home use cases. Claude Code is a CLI tool for developers (terminal/IDE integration) focused on software development workflows. Both use Claude models but serve distinct audiences and use cases. [More details in Appendix B: FAQ](#appendix-b-faq).

---

## TL;DR - The 5-Minute Summary

If you only have 5 minutes, here's what you need to know:

### Essential Commands
```bash
claude                    # Start Claude Code
/help                     # Show all commands
/status                   # Check context usage
/compact                  # Compress context when >70%
/clear                    # Fresh start
/plan                     # Safe read-only mode
Ctrl+C                    # Cancel operation
```

### The Workflow
```
Describe → Claude Analyzes → Review Diff → Accept/Reject → Verify
```

### Context Management (Critical!)
| Context % | Action |
|-----------|--------|
| 0-50% | Work freely |
| 50-70% | Be selective |
| 70-90% | `/compact` now |
| 90%+ | `/clear` required |

*These thresholds are based on my experience. Your optimal workflow may differ depending on task complexity and working style.*

### Memory Hierarchy
```
~/.claude/CLAUDE.md       → Global (all projects)
/project/CLAUDE.md        → Project (committed)
/project/.claude/         → Personal (not committed)
```

### Power Features
| Feature | What It Does |
|---------|--------------|
| **Agents** | Specialized AI personas for specific tasks |
| **Skills** | Reusable knowledge modules |
| **Hooks** | Automation scripts triggered by events |
| **MCP Servers** | External tools (Serena, Context7, Playwright...) |
| **Plugins** | Community-created extension packages |

### The Golden Rules
1. **Always review diffs** before accepting changes
2. **Use `/compact`** before context gets critical
3. **Be specific** in your requests (WHAT, WHERE, HOW, VERIFY)
4. **Start with Plan Mode** for complex/risky tasks
5. **Create CLAUDE.md** for every project

### Quick Decision Tree
```
Simple task → Just ask Claude
Complex task → Use TodoWrite to plan
Risky change → Enter Plan Mode first
Repeating task → Create an agent or command
Context full → /compact or /clear
```

**Now read Section 1 for the full Quick Start, or jump to any section you need.**

---

## Table of Contents

- [1. Quick Start (Day 1)](#1-quick-start-day-1)
  - [1.1 Installation](#11-installation)
  - [1.2 First Workflow](#12-first-workflow)
  - [1.3 Essential Commands](#13-essential-commands)
  - [1.4 Permission Modes](#14-permission-modes)
  - [1.5 Productivity Checklist](#15-productivity-checklist)
  - [1.6 Migrating from Other AI Coding Tools](#16-migrating-from-other-ai-coding-tools)
  - [1.7 Trust Calibration](#17-trust-calibration-when-and-how-much-to-verify)
  - [1.8 Eight Beginner Mistakes](#18-eight-beginner-mistakes-and-how-to-avoid-them)
- [2. Core Concepts](#2-core-concepts)
  - [2.1 The Interaction Loop](#21-the-interaction-loop)
  - [2.2 Context Management](#22-context-management)
  - [2.3 Plan Mode](#23-plan-mode)
  - [2.4 Rewind](#24-rewind)
  - [2.5 Model Selection & Thinking Guide](#25-model-selection--thinking-guide)
  - [2.6 Mental Model](#26-mental-model)
  - [2.7 Configuration Decision Guide](#27-configuration-decision-guide)
  - [2.8 Structured Prompting with XML Tags](#28-structured-prompting-with-xml-tags)
  - [2.9 Semantic Anchors](#29-semantic-anchors)
  - [2.10 Data Flow & Privacy](#210-data-flow--privacy)
  - [2.11 Under the Hood](#211-under-the-hood)
- [3. Memory & Settings](#3-memory--settings)
  - [3.1 Memory Files (CLAUDE.md)](#31-memory-files-claudemd)
  - [3.2 The .claude/ Folder Structure](#32-the-claude-folder-structure)
  - [3.3 Settings & Permissions](#33-settings--permissions)
  - [3.4 Precedence Rules](#34-precedence-rules)
  - [3.5 Team Configuration at Scale](#35-team-configuration-at-scale)
- [4. Agents](#4-agents)
  - [4.1 What Are Agents](#41-what-are-agents)
  - [4.2 Creating Custom Agents](#42-creating-custom-agents)
  - [4.3 Agent Template](#43-agent-template)
  - [4.4 Best Practices](#44-best-practices)
  - [4.5 Agent Examples](#45-agent-examples)
- [5. Skills](#5-skills)
  - [5.1 Understanding Skills](#51-understanding-skills)
  - [5.2 Creating Skills](#52-creating-skills)
  - [5.3 Skill Template](#53-skill-template)
  - [5.4 Skill Examples](#54-skill-examples)
- [6. Commands](#6-commands)
  - [6.1 Slash Commands](#61-slash-commands)
  - [6.2 Creating Custom Commands](#62-creating-custom-commands)
  - [6.3 Command Template](#63-command-template)
  - [6.4 Command Examples](#64-command-examples)
- [7. Hooks](#7-hooks)
  - [7.1 The Event System](#71-the-event-system)
  - [7.2 Creating Hooks](#72-creating-hooks)
  - [7.3 Hook Templates](#73-hook-templates)
  - [7.4 Security Hooks](#74-security-hooks)
  - [7.5 Hook Examples](#75-hook-examples)
- [8. MCP Servers](#8-mcp-servers)
  - [8.1 What is MCP](#81-what-is-mcp)
  - [8.2 Available Servers](#82-available-servers)
  - [8.3 Configuration](#83-configuration)
  - [8.4 Server Selection Guide](#84-server-selection-guide)
  - [8.5 Plugin System](#85-plugin-system)
  - [8.6 MCP Security](#86-mcp-security)
- [9. Advanced Patterns](#9-advanced-patterns)
  - [9.1 The Trinity](#91-the-trinity)
  - [9.2 Composition Patterns](#92-composition-patterns)
  - [9.3 CI/CD Integration](#93-cicd-integration)
  - [9.4 IDE Integration](#94-ide-integration)
  - [9.5 Tight Feedback Loops](#95-tight-feedback-loops)
  - [9.6 Todo as Instruction Mirrors](#96-todo-as-instruction-mirrors)
  - [9.7 Output Styles](#97-output-styles)
  - [9.8 Vibe Coding & Skeleton Projects](#98-vibe-coding--skeleton-projects)
  - [9.9 Batch Operations Pattern](#99-batch-operations-pattern)
  - [9.10 Continuous Improvement Mindset](#910-continuous-improvement-mindset)
  - [9.11 Common Pitfalls & Best Practices](#911-common-pitfalls--best-practices)
  - [9.12 Git Best Practices & Workflows](#912-git-best-practices--workflows)
  - [9.13 Cost Optimization Strategies](#913-cost-optimization-strategies)
  - [9.14 Development Methodologies](#914-development-methodologies)
  - [9.15 Named Prompting Patterns](#915-named-prompting-patterns)
  - [9.16 Session Teleportation](#916-session-teleportation)
  - [9.17 Scaling Patterns: Multi-Instance Workflows](#917-scaling-patterns-multi-instance-workflows)
  - [9.18 Codebase Design for Agent Productivity](#918-codebase-design-for-agent-productivity)
  - [9.19 Permutation Frameworks](#919-permutation-frameworks)
  - [9.20 Agent Teams (Multi-Agent Coordination)](#920-agent-teams-multi-agent-coordination)
  - [9.21 Legacy Codebase Modernization](#921-legacy-codebase-modernization)
  - [9.22 Remote Control (Mobile Access)](#922-remote-control-mobile-access)
- [10. Reference](#10-reference)
  - [10.1 Commands Table](#101-commands-table)
  - [10.2 Keyboard Shortcuts](#102-keyboard-shortcuts)
  - [10.3 Configuration Reference](#103-configuration-reference)
  - [10.4 Troubleshooting](#104-troubleshooting)
  - [10.5 Cheatsheet](#105-cheatsheet)
  - [10.6 Daily Workflow & Checklists](#106-daily-workflow--checklists)
- [11. AI Ecosystem: Complementary Tools](#11-ai-ecosystem-complementary-tools)
  - [11.1 Why Complementarity Matters](#111-why-complementarity-matters)
  - [11.2 Tool Matrix](#112-tool-matrix)
  - [11.3 Practical Workflows](#113-practical-workflows)
  - [11.4 Integration Patterns](#114-integration-patterns)
  - [For Non-Developers: Claude Cowork](#for-non-developers-claude-cowork)
- [Appendix: Templates Collection](#appendix-templates-collection)
  - [Appendix A: File Locations Reference](#appendix-a-file-locations-reference)
  - [Appendix B: FAQ](#appendix-b-faq)

---

# 1. Quick Start (Day 1)

_Quick jump:_ [Installation](#11-installation) · [First Workflow](#12-first-workflow) · [Essential Commands](#13-essential-commands) · [Permission Modes](#14-permission-modes) · [Productivity Checklist](#15-productivity-checklist) · [Migrating from Other Tools](#16-migrating-from-other-ai-coding-tools) · [Beginner Mistakes](#17-eight-beginner-mistakes-and-how-to-avoid-them)

---

**Reading time**: 15 minutes

**Skill level**: Beginner

**Goal**: Go from zero to productive

## 1.1 Installation

Choose your preferred installation method based on your operating system:

```C
/*──────────────────────────────────────────────────────────────*/
/* 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

```bash
claude --version
```

### Updating Claude Code

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

```bash
# 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

### 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

```bash
cd your-project
claude
```

On first launch:

1. You'll be prompted to authenticate with your Anthropic account
2. Accept the terms of service
3. 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](https://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

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

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

```bash
# 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:

```bash
# 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**:

1. **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

2. **Drag and drop** (some terminals):
   - Drag image file into terminal window
   - Claude loads and processes the image

3. **Reference with path**:
   ```bash
   Analyze this mockup: /path/to/design.png
   ```

**Common use cases**:

```bash
# 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**:

```bash
# 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**:
```bash
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`):
```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**:

1. **Continue last session** (`--continue` or `-c`):
   ```bash
   # Automatically resumes your most recent conversation
   claude --continue
   # Short form
   claude -c
   ```

2. **Resume specific session** (`--resume <id>` or `-r <id>`):
   ```bash
   # Resume a specific session by ID
   claude --resume abc123def
   # Short form
   claude -r abc123def
   ```

3. **Link to a GitHub PR** (`--from-pr <number>`, v2.1.49+):
   ```bash
   # 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**:

```bash
# 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](../examples/scripts/session-search.sh) (bash, lightweight) and [cc-sessions.py](../examples/scripts/cc-sessions.py) (Python, advanced features: incremental index, partial ID resume, branch filter). Also: [Observability Guide](./observability.md#session-search--resume).

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

```bash
# 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%**: Warning - Start planning cleanup or handoff
  - **85%**: Manual handoff recommended - Prevent auto-compact degradation ([research-backed](../architecture.md#auto-compaction))
  - **95%**: Force handoff - Severe quality degradation
- **Session naming**: Use meaningful session IDs when available to identify different work streams

**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 (>90%) |
| 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:

```bash
# 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](https://cc.deeptoai.com/docs/en/best-practices/claude-code-comprehensive-guide)

## 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 | Claude Code |
|---------|---------------|--------|-------------|
| **Interaction** | Inline autocomplete | Chat + autocomplete | CLI + conversation |
| **Context** | Current file | Open files | Entire project |
| **Autonomy** | Suggestions only | Edit + chat | Full task execution |
| **Customization** | Limited | Extensions | Agents, skills, hooks, MCP |
| **Cost Model** | $10-20/month flat | $20/month flat | Pay-per-use ($0.10-$0.50/hour) |

**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](#from-chatbot-to-context-system).

### 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**:

```bash
# 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:

```bash
# 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

```markdown
□ 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

```markdown
□ 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

```markdown
□ 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 hig

…(truncated)