Getting Started with Claude Code:
Complete Beginner's Guide (2026)

What is Claude Code?

Claude Code is Anthropic's official command-line AI agent. While claude.ai is a browser chat interface, Claude Code runs directly inside your terminal — where your actual files, code, and tools live. It can read your entire project, write and edit files across multiple directories, execute shell commands, run tests, and autonomously complete multi-step tasks.

The difference is significant: claude.ai requires you to copy-paste code in and out. Claude Code works in your environment — it sees your actual codebase, understands your project structure, and can make changes end-to-end without you acting as an intermediary.

Claude Code vs. claude.ai — side-by-side

Installation: macOS, Linux & Windows

Claude Code is distributed as an npm package. You need Node.js 18 or higher installed first, then a single command installs the agent globally.

Step-by-step installation checklist

• 1
  Install Node.js 18+ Download from nodejs.org (LTS recommended). After install, verify with node --version — output should show v18 or higher.
• 2
  Install Claude Code globally Run the install command below. The -g flag makes claude available from any directory.
• 3
  Authenticate your Anthropic account On first run, Claude Code opens a browser for OAuth login. You need a Claude Pro or higher subscription — the free tier does not support Claude Code.
• 4
  Navigate to your project and launch cd into any project folder and type claude to start your first session.
• 5
  Verify permissions Claude Code will ask for permission before running commands or editing files. Review and approve on first use.

macOS / Linux

# Install Node.js via Homebrew (macOS)
brew install node

# Or download from nodejs.org and run the installer
# Then verify:
node --version
# v20.11.0 (or similar — must be 18+)

# Install Claude Code globally
npm install -g @anthropic-ai/claude-code

# Verify install
claude --version

# Launch (first run will open browser for auth)
cd ~/my-project
claude
Terminal

Windows

# Install Node.js from nodejs.org — use the Windows installer
# Open PowerShell or Windows Terminal, verify:
node --version

# Install Claude Code
npm install -g @anthropic-ai/claude-code

# Launch from any project folder
cd C:\Users\YourName\my-project
claude

# Windows Subsystem for Linux (WSL) users: use the Linux commands above
# WSL provides the best experience on Windows
PowerShell

Troubleshooting common install issues

# Permission error on macOS/Linux (EACCES)
sudo npm install -g @anthropic-ai/claude-code
# Or fix npm permissions: https://docs.npmjs.com/resolving-eacces-permissions-errors

# "claude: command not found" after install
# Add npm global bin to your PATH:
echo 'export PATH="$(npm bin -g):$PATH"' >> ~/.zshrc
source ~/.zshrc

# Check which Node version is active
node --version
# If < 18, install Node via nvm (Node Version Manager):
nvm install 20 && nvm use 20
Terminal

Your first session — what to type, what to expect

After typing claude in your terminal, you'll see a prompt. Here's exactly what you should do in your first session.

What you'll see on first launch

$ claude

╭───────────────────────────────────────────╮
│  Claude Code  v1.x.x                      │
│  Ready to help — type your request below  │
╰───────────────────────────────────────────╯

Working directory: /Users/you/my-project
Files in context: 0 (type /init to scan project)

You:
Terminal

First things to type

Start with commands that get Claude oriented in your project. Here are the most useful openers for a first session:

# Scan and summarize your project structure
You: Summarize this project — what does it do, how is it structured, and what are the main files?

# Ask Claude to explain any file
You: Read README.md and tell me the top 3 things I should know to work in this codebase.

# Start a real task
You: Look at src/auth.py and add input validation to the login function. Write the tests too.

# Initialize Claude's memory
You: /init
# This creates a CLAUDE.md file with a project summary Claude generates itself
Claude Code Prompt

What Claude Code can do on day 1

• Read any file: "Read package.json and list all dependencies that are outdated."
• Write new files: "Create a Python script that scrapes my competitor's pricing page."
• Edit existing files: "In utils/helpers.js, refactor the three date formatting functions into one."
• Run commands: "Run the test suite and fix any failing tests." (requires permission approval)
• Search across files: "Find every place the old API endpoint /v1/users is called and replace with /v2/users."
• Explain code: "Explain how the authentication middleware works in this Express app."
• Generate content: "Based on PRODUCT.md, write a 500-word product description for the landing page."

Approving and denying tool use

When Claude wants to run a command or write to a file, it asks for permission. You'll see a prompt like:

Claude wants to run:
  npm test -- --coverage

[A]llow once  [T]rust always  [D]eny  [C]ancel
Permission Prompt

Use [T]rust always for safe, repeatable commands like npm test. Use [A]llow once for commands you want to review each time. Use [D]eny if you're not sure — Claude will work around it.

The CLAUDE.md file explained

CLAUDE.md is the single most important file in your Claude Code setup. It lives in the root of your project directory and is automatically read by Claude at the start of every session — without you having to paste anything or repeat yourself.

Think of it as the standing briefing you give a new team member on day one: here's what we're building, here's how we do things, here are the rules. Except Claude reads it every single session and never forgets. Learn more in our Claude Code Memory Guide.

What goes in CLAUDE.md?

• Project overview — What the project does, tech stack, architecture summary
• Coding conventions — Naming patterns, file organization, style guide rules
• Key commands — How to run the app, run tests, build for production
• Laws and guardrails — Rules Claude must follow before taking any action
• Data sources — Where to find important files, configs, or context
• Off-limits areas — Files Claude should never modify, APIs to never call in production
• Session startup instructions — What Claude should do first at the start of every session

A minimal CLAUDE.md example

# My SaaS App — Claude Instructions

## Project Overview
B2B subscription analytics platform. Django backend, React frontend.
Main codebase in /src. Tests in /tests. Infra configs in /deploy.

## Tech Stack
- Backend: Python 3.12, Django 5, PostgreSQL 16
- Frontend: React 18, TypeScript, Tailwind CSS
- API: REST + OpenAPI spec at /docs/api.yaml
- Auth: Auth0 (never touch auth/views.py without asking)

## Critical Rules
1. Never modify migrations directly — always run `python manage.py makemigrations`
2. Never hardcode secrets — use os.getenv() for all credentials
3. All new features must have tests before marking done
4. Run `pytest --fast` before any git commit

## Key Commands
- Run app: `docker-compose up`
- Run tests: `pytest tests/`
- Build frontend: `cd frontend && npm run build`
- Deploy staging: `./scripts/deploy.sh staging`

## Session Startup
On every session: read /brain/daily_context.md for today's priorities
and /brain/open_issues.md for known blockers.
CLAUDE.md

CLAUDE.md is hierarchical

You can have CLAUDE.md files at multiple levels. A CLAUDE.md in /src/api/ is automatically loaded when Claude is working in that subdirectory, layering on top of the root-level file. This is useful for giving different instructions to different parts of a monorepo. See our full CLAUDE.md Templates library for role-specific starting points.

The brain/ directory — persistent memory & task management

CLAUDE.md holds standing instructions. The brain/ directory holds living state — the things that change session to session: current priorities, task queues, accumulated knowledge, decisions made, and context that would overflow a single CLAUDE.md file.

This is a pattern, not a Claude Code feature — you create it yourself. But it's one of the highest-leverage setups you can build. Power users treat the brain/ directory as Claude's long-term memory. For the full picture, see our Claude Code Memory Guide.

A typical brain/ structure

brain/
├── session_startup.md      # What Claude reads at the start of every session
├── daily_context.md        # Today's priorities, blockers, goals
├── task_queue.json         # Prioritized list of pending work items
├── open_issues.md          # Known bugs, blockers, questions
├── decisions.md            # Architecture decisions and why they were made
├── knowledge/
│   ├── api_notes.md        # Notes on external APIs used
│   ├── vendor_quirks.md    # Edge cases discovered in dependencies
│   └── performance.md      # Performance findings and benchmarks
└── session_log.jsonl       # Append-only log of what was done each session
Directory Structure

Reference brain/ files from CLAUDE.md

Add a session startup section to your CLAUDE.md that tells Claude to read the relevant brain files at the start of every session:

## Session Startup (MANDATORY — read before doing anything)
1. Read brain/session_startup.md for current context and locked decisions
2. Read brain/daily_context.md for today's priorities
3. Read brain/task_queue.json for the next 3 tasks to work on
4. Do NOT ask "what should I work on?" — check the queue
CLAUDE.md excerpt

.claude/rules/ — modular rule files for projects & teams

While CLAUDE.md holds your main project instructions, the .claude/rules/ directory lets you organize rules into separate, focused files. This is especially useful for teams (each member can add their own rules), for large projects (rules split by domain), and for keeping rules versioned separately from code.

.claude/
├── settings.json           # Claude Code configuration, hooks, permissions
├── settings.local.json     # Local overrides (add to .gitignore)
└── rules/
    ├── testing.md          # Rules for writing and running tests
    ├── api-design.md       # API naming, versioning, error format conventions
    ├── security.md         # Security rules — never commit secrets, never bypass auth
    └── deployment.md       # Deploy rules — staging first, no Friday pushes
Directory Structure

All .md files in .claude/rules/ are automatically included in Claude's context. You don't need to reference them from CLAUDE.md — Claude Code loads them automatically. Explore the full system in our Claude Code Context Guide.

A .claude/rules/ file example

# .claude/rules/security.md

## Security Rules (MANDATORY — applies to all code changes)

1. NEVER hardcode secrets, API keys, or passwords in any file
2. NEVER log sensitive user data (emails, passwords, PII)
3. All SQL queries must use parameterized queries — no string concatenation
4. Before any production deployment: verify CORS settings are restricted
5. All user inputs must be validated server-side before processing
6. Never disable SSL verification in HTTP clients, even for testing
.claude/rules/security.md

Essential commands: slash commands & keyboard shortcuts

Claude Code ships with a rich set of built-in slash commands and keyboard shortcuts. These are the ones you'll use every day. You can also create custom slash commands for your own workflows.

Built-in slash commands

Keyboard shortcuts

Creating custom slash commands

You can create your own slash commands by adding markdown files to .claude/commands/. The filename becomes the command name.

# Create .claude/commands/deploy.md
# Invoked with: /deploy

Run the deployment checklist:
1. Run the full test suite: `pytest tests/ -v`
2. Check for any TODO: BEFORE DEPLOY comments in changed files
3. Run `python scripts/pre_deploy_check.py`
4. If all pass, stage changes with `git add -A` and show me a diff summary
5. Wait for my approval before committing
.claude/commands/deploy.md

# Now you can run:
You: /deploy
# Claude runs the full checklist automatically
Claude Code Prompt

5 mistakes every beginner makes (and how to fix them)

These are the patterns we see most often in beginners. Each one quietly kills productivity and is easy to fix once you know about it.

From beginner to power user in 30 days

Here's a realistic progression path based on how experienced Claude Code users actually developed their workflows. Most people try to do too much too fast — this path is deliberately sequential.

FAQ — 10 beginner questions answered