Claude Code: Beginner Tutorial

Based on Claude Code v2.1.89 (April 2026). Details may vary in newer releases.

Everything you need to go from zero to productive with Claude Code. By the end of this tutorial, you’ll understand the core concepts and be able to use Claude Code for everyday development tasks.

Table of Contents

1. What is Claude Code and Why Use It
2. Installation and First Run
3. Basic CLI Usage
4. Essential Slash Commands
5. Understanding the Context Window
6. Your First CLAUDE.md File
7. Plan Mode Basics
8. Basic Prompting Tips
9. Using Screenshots for UI Tasks
10. The /compact Command
11. Understanding Permissions
12. Model Selection
13. Terminal Setup Recommendations

What is Claude Code and Why Use It

Claude Code is an agentic coding assistant available in your terminal, VS Code, JetBrains IDEs, a standalone desktop app, and even in the browser at claude.ai/code. Unlike chat-based assistants that just give you code to copy-paste, Claude Code can:

• Read and write files directly in your project
• Run shell commands (with your permission)
• Navigate your codebase to understand context
• Execute multi-step tasks autonomously
• Remember project-specific context via CLAUDE.md files

When to Use Claude Code

When Not to Use Claude Code

• Quick one-off questions (use web Claude or IDE assistant)
• Highly repetitive tasks with known scripts (just run the script)

Installation and First Run

Install

# macOS/Linux (Recommended)
curl -fsSL https://claude.ai/install.sh | bash

# Homebrew (macOS)
brew install --cask claude-code

# Windows (PowerShell)
irm https://claude.ai/install.ps1 | iex

# WinGet (Windows)
winget install Anthropic.ClaudeCode

First Run

# Navigate to your project
cd /path/to/your/project

# Start Claude Code
claude

On first run, you’ll be prompted to authenticate. You can either:

• Sign in with a Claude.ai account (Pro/Max subscription)
• Use an Anthropic API key (pay-as-you-go)

Verify Installation

# Check version
claude --version

Once inside a session, run /doctor to diagnose issues:

> /doctor

Pro tip: Run /doctor periodically. It catches auth issues, outdated versions, and misconfigurations before they bite you.

Basic CLI Usage

Starting Claude Code

# Basic start in current directory
claude

# Start with an initial prompt
claude "explain this codebase"

# Start in a git worktree (isolated branch copy)
claude -w feature-auth

# Start with a named session
claude -n "auth-refactor"

# One-shot mode (no REPL)
claude -p "what does main.py do?" --output-format text

# Resume last session
claude --continue

# Enable Chrome integration
claude --chrome

The REPL Interface

When you run claude, you enter an interactive REPL (Read-Eval-Print Loop):

╭──────────────────────────────────────────╮
│ Claude Code                              │
╰──────────────────────────────────────────╯
>

Note: Context usage is not displayed in the prompt by default. To see it, configure a custom status line using /statusline (e.g., /statusline show model name and context percentage). You can always check context usage on demand with /context.

Type your request and press Enter. Claude will:

1. Read relevant files
2. Plan its approach
3. Execute changes (with permission)
4. Report results

Essential Keyboard Shortcuts

The @ File Mention

Reference specific files by typing @ followed by the path:

> explain @src/api/auth.py
> compare @config/dev.json with @config/prod.json
> add tests for @app/services/payment_service.py

The @ triggers autocomplete — start typing and Claude Code shows matching files. Use @/ to see the full file list.

The ! Bash Mode

Run shell commands and add their output to the conversation:

> ! git status
> ! pytest tests/test_auth.py -v
> ! ls -la src/

This is useful for showing Claude the current state of things without it having to run the command itself.

Essential Slash Commands

Slash commands are built-in operations. Type / to see all available commands.

Navigation & Information

Session Management

Configuration

Content Operations

Bundled Skills

These are bundled skills that ship with Claude Code and appear alongside built-in commands:

Advanced Features

Pro tip: Type / and start typing any letters to filter commands. You don’t need to remember exact names.

Understanding the Context Window

The context window is the single most important concept for effective Claude Code usage.

What is the Context Window?

The context window is Claude’s “working memory” — everything it can “see” at once:

• The system prompt
• Your CLAUDE.md files
• Conversation history
• File contents you’ve referenced
• Command outputs
• Tool results

Both Opus 4.6 and Sonnet 4.6 support a 1M token context window. On Max, Team, and Enterprise plans, Opus is automatically upgraded to 1M context. For Sonnet, use /model sonnet[1m] to enable it (may require extra usage depending on your plan). Without the [1m] suffix, the default context window is 200K tokens (~150K words).

Why Context Window Matters

Monitoring Context

Use /context to see a detailed breakdown of what’s consuming your context:

> /context
claude-sonnet-4-20250514 • 46k / 200k tokens (23%)

  System prompt       ████░░░░░░░░░░░░░░░░  4k
  System tools        ██░░░░░░░░░░░░░░░░░░  2k
  MCP tools           █░░░░░░░░░░░░░░░░░░░  1k
  Custom agents       █░░░░░░░░░░░░░░░░░░░  1k
  Memory files        ██░░░░░░░░░░░░░░░░░░  3k
  Messages            ███████░░░░░░░░░░░░░  35k

Optimization tips: ...

The breakdown shows what’s consuming your context across six categories: system prompt, system tools, MCP tools, custom agents, memory files (CLAUDE.md etc.), and messages (your conversation history). It also offers optimization tips when relevant.

Context Management Rules

Rule 1: One chat ≈ one task

# Finished implementing auth? Start fresh for the next feature.
/clear

Rule 2: Use /compact when context gets high

# Compress conversation, keep key facts
/compact

Rule 3: Don’t load entire directories unnecessarily

# Bad: "read all files in src/"
# Good: "read @src/api/auth.py to understand the login flow"

Rule 4: Don’t wait until 0%

Quality degrades before you hit the limit. Compact or switch chats when you see warnings.

Rule 5: Watch for the idle-return nudge

If you leave a session idle for 75+ minutes and come back, Claude Code will suggest running /clear. This isn’t a bug — stale sessions waste tokens re-caching old context. If you’re continuing the same task, ignore it. If you’re starting something new, take the hint.

Your First CLAUDE.md File

CLAUDE.md is a special file that Claude reads at the start of every session. It’s your project’s “briefing document.”

Where to Put It

Basic CLAUDE.md Structure

Create CLAUDE.md in your project root:

# Project: Invoice API

## Overview
A FastAPI backend for invoice management with PostgreSQL storage and Stripe integration.

## Tech Stack
- Python 3.12 / FastAPI
- PostgreSQL + SQLAlchemy 2.0
- Alembic for migrations
- pytest for testing
- Redis for caching

## Key Commands
- `make dev` — Start dev server with hot reload
- `make test` — Run test suite
- `make lint` — Run ruff + mypy
- `make migrate` — Run pending migrations

## Project Structure
- `app/api/` — Route handlers
- `app/services/` — Business logic
- `app/models/` — SQLAlchemy models
- `app/schemas/` — Pydantic schemas
- `tests/` — pytest test files

## Conventions
- Use dependency injection for services
- All endpoints return Pydantic models
- Tests use factory_boy for fixtures
- Async everywhere — no sync database calls

## Current Focus
Implementing webhook handling for Stripe payment events.

What to Include

Do include:

• Tech stack and versions
• Key commands (build, test, lint)
• Project structure overview
• Coding conventions
• Current work focus
• Known gotchas

Don’t include:

• Secrets or API keys
• Entire architecture docs (too verbose)
• Information Claude can infer from code

Auto-Generate a CLAUDE.md

> /init

Claude will scan your project and create a starter CLAUDE.md.

Auto Memory

Beyond CLAUDE.md, Claude Code also builds auto memory as it works. It saves learnings like build commands, debugging insights, and project patterns across sessions — without you writing anything. Think of CLAUDE.md as your explicit briefing, and auto memory as the notes Claude takes for itself.

Pro tip: Keep CLAUDE.md under 1000 words. It loads every session — bloated files waste context.

Pain-Driven Documentation

The best CLAUDE.md content comes from friction. When Claude:

• Makes the same mistake twice → document the correct pattern
• Searches too long for something → document where it lives
• Uses the wrong convention → document your actual conventions

Update your CLAUDE.md in the same session where you discover the issue — the context is fresh.

Plan Mode Basics

Plan mode is a thinking-before-doing mode. Claude describes what it would do without actually doing it.

Activating Plan Mode

Press Shift+Tab to cycle through modes:

• Default mode — Claude asks before file edits and shell commands
• Auto-accept edits mode — Claude edits files without asking, still asks for commands
• Plan mode — Claude uses read-only tools only, plans without executing

Or use the command:

> /plan

# Or jump straight in with a description:
> /plan fix the auth bug

When to Use Plan Mode

The Plan-Review-Execute Workflow

1. Enable plan mode (Shift+Tab twice)
2. Ask for the change — Claude outputs a detailed plan
3. Review the plan — Ask questions, refine
4. Disable plan mode (Shift+Tab)
5. Tell Claude to execute — “proceed with the plan”

Example:

> [Plan mode ON]
> add rate limiting to all API endpoints

Claude: Here's my plan:
1. Add slowapi to requirements.txt
2. Create app/middleware/rate_limit.py with limiter config
3. Add rate limit decorators to route files
4. Add Redis connection for distributed limiting
5. Add tests for rate limit behavior
...

> looks good, but use in-memory for dev, Redis only in prod

Claude: Updated plan:
...

> [Plan mode OFF]
> proceed with the plan

Basic Prompting Tips

How you phrase requests dramatically affects results.

Be Specific

Use Precise Terminology

Provide Context

# Bad
> this function is broken

# Good
> the calculate_tax function in @app/services/tax.py returns 0 for all inputs.
> Expected: 8.25% of subtotal for CA addresses
> Actual: always returns Decimal("0.00")

One Task at a Time

# Bad (too much at once)
> add auth, create admin dashboard, and implement payment processing

# Good (sequential)
> add JWT authentication with refresh tokens
# [complete, test]
> create admin dashboard layout
# [complete, test]
> implement Stripe checkout

Tell Claude What You Already Tried

> the tests are failing with "connection refused" on the Redis mock.
> I already checked that fakeredis is installed and the fixture is correct.
> The error only happens when running the full suite, not individual tests.

Using Screenshots for UI Tasks

Claude Code can analyze images. This is powerful for UI work.

Pasting Screenshots

1. Take a screenshot (Cmd+Shift+4 on Mac, Win+Shift+S on Windows)
2. Paste directly into Claude Code with Ctrl+V or Cmd+V

UI Task Examples

> [paste screenshot]
> recreate this dashboard layout in React with Tailwind CSS

> [paste screenshot]
> this form validation isn't showing errors correctly. fix the error display.

> [paste screenshot]
> the mobile nav is broken. diagnose and fix.

Design-to-Code Workflow

1. Screenshot the design (Figma, mockup, etc.)
2. Paste into Claude Code
3. Ask Claude to implement it
4. Iterate with more screenshots showing issues

Pro tip: Annotate screenshots before pasting. Circle problem areas in red — Claude understands visual annotations.

The /compact Command

/compact compresses your conversation to free up context space.

Basic Usage

> /compact

Claude summarizes the conversation, discarding verbose history while preserving key facts.

Compact with Focus

> /compact focus on the payment integration decisions

This tells Claude what to prioritize when summarizing.

When to Use /compact

• Context usage above 50%
• Switching focus within a long session
• Before starting a new phase of work
• After completing a major milestone

What Gets Preserved vs. Lost

Pro tip: Before /compact, explicitly state what’s important:
“Remember: we’re using SQLAlchemy 2.0 async sessions and all services use dependency injection.”
Then run /compact.

Autocompact Thrash Protection

Claude Code auto-compacts when context gets full. But sometimes the context fills right back up after compacting (e.g., a skill or CLAUDE.md that’s too large). If this happens three times in a row, Claude Code now stops with an actionable error instead of burning API calls in an infinite loop. If you see this, it means your context is structurally overloaded — trim your CLAUDE.md, reduce MCP tools, or start a fresh session with a narrower scope.

Understanding Permissions

Claude Code can read files, write files, and run commands. Permissions control what it’s allowed to do.

Permission Modes

Press Shift+Tab to cycle through:

The Permission Dialog

When Claude wants to do something, you’ll see a prompt with the proposed action and options to approve or deny it:

╭─ Claude wants to run a command ─────────────────────────────────────────────╮
│ pip install slowapi                                                         │
╰─────────────────────────────────────────────────────────────────────────────╯
  Yes  |  Yes, don't ask again  |  No

Options:

• Yes — Allow this once
• Yes, don’t ask again — Allow this and similar actions going forward. For bash commands, this persists permanently per project directory. For file edits, it lasts until the session ends.
• No — Deny and tell Claude what to do differently

The persistence of “don’t ask again” varies by tool type:

Pre-Configuring Permissions

Edit your settings.json:

{
  "permissions": {
    "allow": [
      "Read(*)",
      "Bash(pytest *)",
      "Bash(make *)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Read(.env*)",
      "Read(*.pem)"
    ]
  }
}

Or use the command:

> /permissions

The –dangerously-skip-permissions Flag

claude --dangerously-skip-permissions

This skips ALL permission checks. Only use for:

• Fully trusted, isolated environments
• Automated pipelines with controlled input
• Never with untrusted codebases

Warning: This flag does exactly what it says. Claude can rm -rf / if it decides to.

Model Selection

Claude Code supports multiple models. Choose based on your task.

Available Models

As shown in the /model picker:

Changing Models

# Interactive picker
> /model

# Direct selection via --model flag
claude --model sonnet

Effort Levels

Control how much reasoning Claude puts into responses:

The current effort level is displayed next to the logo/spinner (e.g., “with low effort”).

> /effort low    # Quick tasks
> /effort high   # Complex reasoning
> /effort max    # Maximum depth (Opus only)
> /effort auto   # Reset to model default

Fast Mode

For interactive work where speed matters more than cost, toggle fast mode:

> /fast

This makes Opus 4.6 responses 2.5× faster at higher per-token cost. Same model, same quality — just faster. Toggle off with /fast again.

Model Selection Strategy

Pro tip: Always bias toward the most powerful model you can afford. The cost difference is negligible compared to the quality difference.

Terminal Setup Recommendations

Claude Code works best with a properly configured terminal.

Recommended Terminals

Keybinding Setup

Some terminals (VS Code, Alacritty, Warp) need configuration for Shift+Enter (multiline input). iTerm2, WezTerm, Ghostty, and Kitty support it natively.

> /terminal-setup

This command installs the necessary keybindings. It only appears in terminals that need it.

Recommended Settings

Font: Use a monospace font with ligatures:

• JetBrains Mono
• Fira Code
• SF Mono

Color theme: Ensure good contrast. Run /theme to pick one that works for you.

Window size: Wide is better than tall. Claude outputs long lines.

Option as Meta (macOS)

For word navigation shortcuts (Alt+B, Alt+F):

iTerm2: Settings → Profiles → Keys → Set “Left/Right Option key” to “Esc+”

Terminal.app: Settings → Profiles → Keyboard → Check “Use Option as Meta Key”

Prevent Sleep During Long Tasks (macOS)

caffeinate -dimsu

Keep your laptop awake while Claude works on something lengthy.

Next Steps

You now understand the fundamentals:

• How to run Claude Code
• Essential commands and shortcuts
• Context window management
• CLAUDE.md for project memory
• Plan mode for safety
• Good prompting practices
• Permission model
• Model selection

Ready to level up? Continue to the Intermediate Tutorial where you’ll learn:

• Hierarchical CLAUDE.md configurations
• Subagents for parallel work
• Advanced context management
• Skills, MCP servers, and plugins
• Hooks and automation
• Multi-terminal workflows

Quick Reference Card

Startup

claude                    # Start interactive mode
claude "prompt"           # Start with prompt
claude -p "prompt"        # One-shot mode
claude -w feature-name    # Start in a git worktree
claude -n "name"          # Named session
claude --continue         # Resume last session
claude --chrome           # Enable Chrome integration

Essential Commands

/help        Show commands
/context     Check context usage (with optimization tips)
/compact     Compress conversation
/clear       Fresh start
/resume      Continue previous session
/init        Create CLAUDE.md
/model       Change model
/effort      Set reasoning effort (low/medium/high)
/fast        Toggle fast mode (2.5× faster Opus)
/loop        Schedule recurring prompts (bundled skill)
/rewind      Go back to checkpoint

Keyboard Shortcuts

Shift+Tab    Toggle modes (Default/Auto-accept/Plan)
Esc Esc      Open rewind menu
Ctrl+R       Search prompt history
Ctrl+C       Cancel
Ctrl+D       Exit
Ctrl+L       Clear screen
/            Commands
@            File autocomplete
!            Bash mode

Context Rules

1. Stay under 50%
2. /clear for new tasks
3. /compact when high
4. Don’t load entire directories

Credits & Attribution

This tutorial series draws from Claude Code’s official documentation and the generous knowledge-sharing of the Claude Code community including SilenNaihin, Peter Steinberger (steipete.me), Daniel Avila, Steve Kinney, and numerous others on X, Reddit, and Discord.