Claude Code 101: The Complete Guide to AI-Powered Coding in Your Terminal

Claude Code is Anthropic's AI coding agent. It lives in your terminal, reads your entire codebase, edits files, runs commands, manages git, and iterates on failures — all from natural language instructions. You describe what you want, and Claude figures out how to build it.

Unlike autocomplete tools that suggest the next line of code, Claude Code operates at the project level. It understands how your files connect, plans multi-file changes, runs your test suite, and fixes what breaks. Eight months after launch, it hit a 46% "most loved" rating among developers — overtaking GitHub Copilot's four-year lead.

This guide covers everything from installation to advanced workflows. Whether you're evaluating Claude Code for the first time or looking to go deeper, this is the reference you'll want bookmarked.

Installation and Setup

Claude Code requires a paid Claude account — Pro ($20/mo), Max ($100 or $200/mo), Team, or Enterprise. The free Claude.ai plan does not include access.

Native Install (Recommended)

The native installer auto-updates, so you always run the latest version.

macOS / Linux / WSL:

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell:

irm https://claude.ai/install.ps1 | iex

Windows CMD:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Windows native setups require Git for Windows installed first.

Alternative Installation Methods

First Launch

cd your-project
claude

Your browser opens for authentication on first run. Once signed in, you're dropped into an interactive session. Start with something exploratory:

> What does this project do? Summarize the architecture and key dependencies.

Claude reads your file structure, package files, and source code, then gives you a structured overview. From here, you can start asking it to make changes.

How Claude Code Works

Understanding the execution model helps you work with Claude Code effectively instead of fighting it.

Tools, Not Magic

Claude Code operates through a set of discrete tools: Read (read files), Edit (modify files), Write (create files), Bash (run shell commands), Grep (search content), Glob (find files by pattern), and more. When you give Claude a task, it decides which tools to use and in what order.

Every tool call is visible to you. Claude proposes an action — "I want to edit src/auth/login.ts" — and you approve or deny it. This approval loop is the core interaction model. You stay in control while Claude does the heavy lifting.

Context Window

Claude Code runs on models with up to a 200K token context window (1M in beta for Max and Enterprise plans). That context holds your conversation, the files Claude has read, tool outputs, and system instructions. When context fills up, Claude's responses degrade. Managing context is a skill you'll develop over time.

Permission Modes

You can adjust how much autonomy Claude gets:

Switch modes mid-session with Shift+Tab. Start in default mode until you're comfortable, then graduate to auto for faster workflows.

CLAUDE.md — Teaching Claude About Your Project

CLAUDE.md is a markdown file that Claude reads at the start of every session. Think of it as persistent project memory — it tells Claude your conventions, build commands, architecture decisions, and anything else it should know without being asked.

Where to Put It

Claude loads CLAUDE.md files from multiple locations, all at once:

What to Include

The most impactful things to put in CLAUDE.md:

# Project

Next.js 14 app with App Router, TypeScript, Tailwind CSS, and Supabase.

# Commands

- `npm run dev` — start dev server on port 3000
- `npm run build` — production build
- `npm run test` — run Jest test suite
- `npm run lint` — ESLint check

# Conventions

- Use named exports, not default exports
- Components go in `src/components/{feature}/`
- API routes go in `src/app/api/{resource}/route.ts`
- Always use server actions for form submissions
- Write tests for all new utility functions

# Git

- Branch naming: `feature/description`, `fix/description`
- Commit messages: imperative mood, under 72 characters
- Always run tests before committing

What Not to Include

• Standard language conventions Claude already knows
• Obvious advice ("write clean code")
• API keys or secrets
• Long tutorials (link to them instead)
• Information that changes frequently

If Claude starts ignoring your CLAUDE.md rules, the file is probably too long. Keep it focused.

Quick Start

Run /init in your project directory. Claude generates a starter CLAUDE.md based on your detected tech stack, package files, and project structure.

Essential Slash Commands

Slash commands are typed directly into the Claude Code prompt. Here are the ones that matter most for daily use.

/compact — Compress Your Context

When your context window fills up, Claude's quality drops. The /compact command summarizes the conversation to free up tokens.

The key trick: pass focus instructions to control what the summary retains.

/compact Focus on the database migration changes and the failing test

Without guidance, /compact makes its own choices about what matters. With a focus instruction, you keep exactly the context you need.

/plan — Think Before Acting

Toggle Plan Mode where Claude analyzes your codebase without making changes. Perfect for understanding a problem before committing to a solution.

The recommended workflow: Explore (Plan Mode) -> Plan -> Implement (Normal Mode) -> Commit.

/clear — Fresh Start

Resets your conversation context entirely. Use this between unrelated tasks. Context pollution — leftover context from a previous task bleeding into the current one — is the number one cause of degraded Claude Code performance.

/btw — Side Questions

Ask a question without adding anything to the conversation history:

/btw what was the name of that config file we discussed?

The response appears in a dismissible overlay. It has full visibility into your current conversation but leaves no trace in the context window. You can even use /btw while Claude is actively working on something else.

/cost — Track Your Usage

Shows session cost, duration, and token usage. Useful for understanding how different tasks consume your quota.

/context — Visualize Token Usage

Displays a colored grid showing how your context window is allocated across conversation history, tool outputs, and system instructions. The diagnostic tool for understanding why Claude starts forgetting things.

/diff — Review Changes

Opens an interactive viewer showing all uncommitted changes Claude has made. Useful before committing to make sure everything looks right.

/rewind — Surgical Rollback

Opens a checkpoint menu where you can restore previous states. Three options:

• Rewind code only — reverts file changes but keeps conversation history. Claude remembers what it tried.
• Rewind conversation only — keeps code changes but resets what Claude remembers.
• Summarize from here — condenses messages from a selected point forward. Precision context management.

Also accessible by double-tapping Escape.

Keyboard Shortcuts Worth Learning

Claude Code's terminal interface is richer than it looks.

Important: Escape stops generation. Ctrl+C exits the session entirely. Learn this distinction early.

On macOS, the Alt shortcuts require setting Option as Meta in your terminal. In iTerm2: Settings > Profiles > Keys > set Left Option to "Esc+". In VS Code terminal: set "terminal.integrated.macOptionIsMeta": true.

Input Tricks

Bash Mode

Prefix any input with ! to run a shell command directly:

! npm test
! git log --oneline -5
! docker ps

The output gets added to Claude's context without going through tool approval. Faster than asking Claude to run a command for you.

@ File Mentions

Type @ to trigger file path autocomplete:

Look at @src/auth/middleware.ts and fix the token validation

More precise than hoping Claude finds the right file on its own.

Image Pasting

Press Ctrl+V to paste a screenshot from your clipboard. Claude sees the image and can reference it in its analysis. Useful for UI bugs, error screenshots, and design references.

CLI Flags for Power Users

The command-line flags available when launching Claude Code unlock workflows beyond interactive sessions.

--continue and --resume

# Resume the most recent session — no questions asked
claude --continue

# Pick from a list of previous sessions
claude --resume

--continue is for speed. --resume is for choosing a specific session. Both restore full context.

--name — Tag Sessions

claude --name "feature-auth-redesign"

Named sessions are easy to find when using --resume. Adopt a convention like feature-, fix-, refactor- and your session list becomes scannable.

-p — Headless Mode

claude -p "Find all TODO comments and list them by priority"

Runs Claude non-interactively: process one prompt, print the result, exit. This turns Claude Code into a composable CLI tool for scripts and pipelines.

# Restrict tool access
claude -p "Fix lint errors" --allowedTools "Read,Edit,Bash"

# Get JSON output for parsing
claude -p "List all API endpoints" --output-format json

# Cap spending
claude -p "Refactor the auth module" --max-budget-usd 5

--worktree — Isolated Branches

claude --worktree

Starts Claude in a temporary git worktree — an isolated copy of your repo. Changes happen on a separate branch without touching your working directory. Useful when you want Claude to experiment without risk.

Working with MCP Servers

MCP (Model Context Protocol) is an open standard that connects Claude Code to external tools and data sources. MCP servers give Claude access to databases, APIs, file systems, and third-party services.

Adding an MCP Server

claude mcp add github -- npx -y @modelcontextprotocol/server-github
claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres
claude mcp add slack -- npx -y @anthropic/mcp-server-slack

What MCP Enables

With MCP servers configured, Claude can:

• Query your PostgreSQL database directly
• Read and comment on GitHub issues and PRs
• Pull context from Google Drive documents
• Update Jira tickets
• Search Slack conversations
• Automate browser actions via Puppeteer

Type @ in your prompt to see available resources from connected MCP servers. Claude discovers tools from MCP servers automatically and uses them when relevant to your task.

Configuration File

MCP servers are configured in .mcp.json at your project root or in ~/.claude/settings.json for global access:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "your-token-here"
      }
    }
  }
}

Customizing with Hooks

Hooks are shell commands that run automatically at specific lifecycle events. Unlike CLAUDE.md instructions (which Claude follows when it remembers to), hooks are deterministic — they always execute.

The Most Common Hook: Auto-Format

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx prettier --write \"$TOOL_INPUT_FILE_PATH\""
      }
    ]
  }
}

This runs Prettier on every file Claude edits. No more reminding Claude to format — it happens automatically, every time.

Security Gate: Block Dangerous Commands

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "bash -c 'read input; cmd=$(echo \"$input\" | jq -r \".tool_input.command\"); case \"$cmd\" in *\"rm -rf /\"*|*\"DROP TABLE\"*|*\"--force\"*) echo \"Blocked\" >&2; exit 2;; *) exit 0;; esac'"
      }
    ]
  }
}

PreToolUse hooks that exit with code 2 block the action before it happens.

Where to Configure

Subagents and Agent Teams

For complex tasks, Claude Code can spawn additional agents that work in parallel.

Subagents

Claude automatically creates subagents for independent subtasks — like researching a library's API while simultaneously writing test scaffolding. Each subagent gets its own context window and tool access. Results flow back to the main session.

Press Ctrl+B to background a running task and continue working on something else.

Agent Teams

Agent Teams take parallel work further. Multiple Claude instances coordinate through shared task lists and work on different parts of a project simultaneously. One agent might implement a feature while another writes tests for it.

Agent Teams are useful for large-scale refactoring, multi-service changes, and projects where work can be cleanly divided.

Using Claude Code in Your IDE

Claude Code isn't limited to the terminal.

VS Code Extension

The VS Code extension (2M+ installs) integrates Claude Code directly into your editor:

• Inline diff reviews for proposed changes
• @ mentions to reference files and symbols
• Conversation history with full context
• Checkpoint system for reverting changes
• Plan Mode for read-only analysis

Install from the Extensions marketplace (search "Claude Code") or run code --install-extension anthropic.claude-code.

JetBrains Plugin

Available for IntelliJ IDEA, PyCharm, and WebStorm via the JetBrains Marketplace. Supports interactive diff viewing and selection-based context sharing.

Web IDE

Visit claude.ai/code for a browser-based environment. No local setup required. Supports long-running tasks, parallel sessions, and working on repos without cloning them locally.

Prompting Tips for Better Results

The quality of Claude Code's output depends heavily on how you prompt it. Here are patterns that consistently produce better results.

Be Specific

Bad: "Fix the login bug"

Good: "The login form at @src/components/auth/LoginForm.tsx throws a 401 error when the email contains a + character. The issue is likely in the URL encoding of the email parameter sent to the /api/auth/login endpoint."

Reference files with @, mention constraints, and point to the specific behavior you expect.

Use the Explore-Plan-Implement Pattern

For non-trivial tasks, don't jump straight to implementation:

1. Explore: "Look at the authentication system and explain how sessions are managed"
2. Plan: "Propose a plan to migrate from session-based auth to JWT tokens"
3. Implement: "Implement the plan, starting with the token generation module"

This pattern produces dramatically better results than a single "migrate to JWT" prompt.

Give Claude Verification Tools

The single most impactful thing you can do: tell Claude how to check its own work. Add this to your CLAUDE.md:

After making changes, always run `npm test` to verify nothing is broken.

Claude then runs tests after every change and fixes failures before moving on. This one instruction measurably improves output quality.

Clear Between Unrelated Tasks

If you were debugging a CSS issue and now want to add an API endpoint, run /clear first. Leftover context from the previous task confuses Claude's reasoning about the new one.

Start Fresh Instead of Spiraling

If you've corrected Claude three or more times and it's still not getting it right, don't keep pushing. Run /clear or start a new session. Rephrase your request with more context about what you actually want. A fresh start with a better prompt beats a long correction chain every time.

Pricing and Plans

What This Means in Practice

The $20 Pro tier works well for moderate use — a few complex tasks per day with lighter work in between. Heavy users who run Claude Code for hours of complex debugging or multi-file refactoring regularly hit the usage ceiling and need to upgrade to Max.

A common strategy: keep Pro ($20/mo) for Claude Code and pair it with a lighter autocomplete tool like GitHub Copilot ($10/mo) for inline suggestions. Total cost of $30/month covers most workflows.

If you need Claude Code for CI/CD pipelines or automated workflows, the API pay-per-token model through the Console gives you precise cost control with flags like --max-budget-usd.

Key Takeaways

• Claude Code is a terminal-native AI coding agent that reads, edits, and tests your entire codebase — not just individual files.
• Install with curl -fsSL https://claude.ai/install.sh | bash (macOS/Linux) and authenticate through your browser.
• CLAUDE.md is your most important configuration file. Include build commands, conventions, and architecture decisions. Run /init to generate a starter file.
• Master context management: use /clear between tasks, /compact with focus instructions, and /btw for side questions that don't pollute context.
• Start in default permission mode, then graduate to auto once comfortable. Use plan mode for exploring unfamiliar codebases.
• Hooks guarantee execution of formatting, security checks, and notifications — unlike CLAUDE.md instructions which depend on model compliance.
• MCP servers connect Claude to external tools: databases, GitHub, Slack, Jira, and more. Add them with claude mcp add.
• Headless mode (-p flag) turns Claude Code into a scriptable CLI tool for pipelines, CI/CD, and batch processing.
• The Explore -> Plan -> Implement -> Commit workflow produces consistently better results than single-shot prompts.
• Give Claude a way to verify its own work ("always run tests after changes") — this single instruction measurably improves output quality.