Introduction & Getting Started

What You’ll Learn

This chapter covers Claude Code from the ground up. We’ll walk through the agentic loop that drives every interaction, get Claude Code installed on your platform, explore the different interfaces where it runs, dig into the core tools it uses to read and modify your codebase, and run through your first session from start to finish.

By the end, you’ll know how to install Claude Code, start a session, ask questions about a codebase, request changes, and safely undo anything that goes wrong. This foundation sets you up for Chapter 2, where you’ll learn how to configure Claude Code with project-specific instructions.

What Is Claude Code?

Claude Code is an agentic coding tool that lives in your terminal. It reads your entire codebase, edits files, and executes commands, all directly on your local filesystem. Unlike hosted IDE extensions or cloud-based editors, it operates on the same files you see in your file manager and commits to the same Git history you push to your remote.

You describe what you want in plain English. Claude Code figures out which files to read, what changes to make, and how to verify the result. It works iteratively: reading, editing, running commands, checking output, and repeating until the task is done or it needs your input.

Here’s an important distinction: chat-based AI assistants answer questions about code you paste into them. Claude Code is different. It operates on your actual project, reading your files, understanding your directory structure, running your test suite, and modifying source code in place. The context isn’t a snippet you copy; it’s your entire repository.

Claude Code is available across multiple interfaces. The terminal CLI is the primary experience with all features available. VS Code and JetBrains extensions provide inline integration. There’s a desktop app for macOS and Windows, a web interface at console.anthropic.com, and Slack integration for team conversations. This guide focuses on the terminal CLI since it’s the most complete interface and the one every other interface builds on.

The Agentic Loop

Every Claude Code interaction follows a three-phase cycle that repeats until the task is done.

Phase 1: Gather context. Claude Code reads files, searches your codebase for patterns, examines project structure, checks documentation, and builds up an understanding of the relevant code. It decides what to read based on your request and whatever it discovers along the way. Say you ask it to fix a bug in the authentication module. It will search for auth-related files, read them, follow imports to understand dependencies, and check test files to understand expected behavior.

Phase 2: Take action. Armed with that understanding, Claude Code edits files, creates new ones, runs shell commands, installs dependencies, or performs whatever other operations are needed. Each action is deliberate and targeted. It doesn’t rewrite entire files. Instead, it makes surgical edits to the specific sections that need to change.

Phase 3: Verify results. After making changes, Claude Code checks its own work. It runs tests, reads compiler output, validates that files were created correctly, and confirms the changes achieve what you asked for. If something doesn’t look right, it loops back to gather more context and tries again. This self-correction is what lets Claude Code handle complex, multi-step tasks without constant supervision.

The diagram above shows these three phases connected in a continuous cycle. Claude Code enters the loop when you submit a prompt and exits when the task is complete, when it needs clarification from you, or when you stop it. A simple question might trigger just one pass through the loop, while a complex refactoring could take dozens.

This autonomous looping is what makes Claude Code “agentic” rather than a simple question-and-answer tool. You describe the goal, and Claude Code figures out the steps.

How many iterations happen depends on the task. A straightforward question (“What does this function do?”) might need just one gather-context phase with no action or verification at all. A multi-file refactoring, on the other hand, might loop dozens of times as Claude Code reads files, makes changes, runs tests, discovers a failing test, reads more context, fixes the issue, and verifies again.

Understanding this loop is foundational. Every feature covered in this guide, from project context configuration to hooks and automation, builds on top of this cycle.

Installation

The easiest way to install Claude Code is with the native install script. It handles all dependencies and platform-specific configuration for you.

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

On macOS, you can also install via Homebrew.

brew install --cask claude-code

On Windows, use the Windows Package Manager.

winget install Anthropic.ClaudeCode

An npm package (@anthropic-ai/claude-code) also exists, but installing via npm is deprecated as a method. Stick with the native installer. It provides better platform integration, automatic updates, and the correct system-level dependencies.

Once installation finishes, verify it worked by checking the version.

claude --version

Then start Claude Code by running the claude command from within any project directory.

cd your-project
claude

The first time you run Claude Code, it’ll prompt you to authenticate with your Anthropic account. Just follow the on-screen instructions to complete setup. You’ll need either an Anthropic API key or a Claude Max/Team/Enterprise subscription.

There are two billing models: direct API usage (pay-per-token via an Anthropic API key) and subscription plans (Claude Max, Team, or Enterprise) that include Claude Code access with usage limits. Check out the Models & Costs chapter for detailed pricing, model selection, and cost optimization strategies.

Available Interfaces

Claude Code runs across several interfaces, each suited to different workflows.

Terminal CLI is the primary interface and the focus of this guide. Every feature is available here. You type natural language prompts and Claude Code responds with actions, explanations, and code changes.

VS Code extension brings Claude Code into the editor with inline suggestions, a chat panel, and access to the same agentic loop without leaving your IDE.

JetBrains plugin provides similar integration for IntelliJ IDEA, WebStorm, PyCharm, and other JetBrains IDEs.

Desktop app runs on macOS and Windows as a standalone application, giving you a dedicated window for Claude Code sessions without needing a terminal.

Web interface at console.anthropic.com offers browser-based access for quick tasks or when you’re away from your development machine.

Slack integration brings Claude Code into team channels, letting your team prompt collaboratively and share context across the organization.

All interfaces share the same underlying capabilities. A task started in VS Code uses the same agentic loop, the same tools, and the same context management as one run from the terminal. The only difference is the surrounding experience: inline editor integration versus a dedicated prompt.

The terminal CLI is where you’ll spend most of your time. All examples in this guide use it unless otherwise noted. Later chapters cover remote access and headless automation for CI/CD pipelines, but the core interaction model is always the same agentic loop described above.

Core Tools

Claude Code uses five categories of tools autonomously during the agentic loop. You don’t invoke these directly; Claude Code picks the right tool for each step on its own.

File operations cover reading file contents, writing new files, and making targeted edits to existing ones. When Claude Code needs to understand your code, it reads files. When it needs to make changes, it writes or edits them. Edits are surgical, replacing specific sections rather than rewriting entire files.

Search includes two complementary tools. Glob finds files by name patterns (like locating all TypeScript files in a directory). Grep searches file contents for text patterns (like finding every function that calls a specific API). Together, they let Claude Code navigate codebases of any size efficiently.

Execution means running shell commands via Bash. Claude Code uses this to install packages, run tests, start development servers, check Git status, and perform any other command-line operation your workflow requires.

Web access through WebFetch lets Claude Code pull up documentation, API references, and other URLs when it needs information from the web. This comes in handy when working with third-party libraries or when you paste a URL in your prompt for Claude Code to reference.

Code intelligence is the ability to understand project structure, follow imports, navigate symbol definitions, and grasp how different parts of your codebase relate to each other. This isn’t a single tool but a capability that emerges from combining file reading, search, and Claude’s understanding of programming languages.

These tools work together seamlessly. When you ask Claude Code to refactor a function, it might Glob to find all files importing that function, Grep to find every call site, Read each file to understand the usage context, Edit the function and all its callers, then Bash to run the test suite and verify nothing broke. You never need to tell it which tools to use; it picks them based on the task.

Claude Code also asks for your permission before doing anything potentially destructive, like writing files or running shell commands. You can configure these permission rules to match your workflow, covered in detail in the Models, Costs & Permissions chapter.

Checkpoints and Undo

Claude Code creates checkpoints before making any changes to your files. If something goes wrong, whether an edit breaks your build, a refactoring heads in the wrong direction, or you simply change your mind, you can rewind to the previous state.

Press Esc twice (Esc-Esc) to open the rewind menu. This gives you a scrollable list of each prompt from your session. Select one and you’ll get options to restore code and conversation to that point, restore just the conversation (keeping current code), restore just the code (keeping the conversation), or summarize from that point to free up context. Since file snapshots are created before edits, reverting is safe and instantaneous. You won’t lose any uncommitted work that existed before Claude Code started editing.

You can also type /rewind at any time to open the same menu. This is handy when you want to review the output first and then decide whether to keep it.

Here’s a quick summary of the undo mechanisms:

• Esc-Esc or /rewind: opens the rewind menu with options to restore code, conversation, or both to a previous point
• Git (always available): your normal Git workflow provides an additional safety net since Claude Code works on your actual files

Here’s what the rewind menu looks like in practice:

  > /rewind

Select a point to rewind to:

3. Add input validation to registration
2. Refactor database connection module
1. What does the auth middleware do?

Selected: Refactor database connection module

What would you like to do?
> Restore code and conversation

Rewound to checkpoint 2. Code and conversation restored.

This checkpoint system makes it safe to let Claude Code work autonomously. Give it complex tasks, watch it iterate through the agentic loop, and rewind if the result isn’t what you wanted. Start with small tasks to build confidence, then gradually increase scope as you get a feel for what Claude Code handles well.

Your First Session

The best way to understand Claude Code is to actually use it. Let’s walk through a complete first interaction, from starting a session to requesting a code change.

Open your terminal, navigate to a project, and fire up Claude Code.

cd ~/projects/my-app
claude

Claude Code will show a prompt where you can type natural language instructions. On first startup, it reads your project structure and any CLAUDE.md configuration file (covered in the next chapter).

Try asking a question about your codebase first. This triggers the “gather context” phase without making any changes, so it’s a safe way to get started.

Here’s what a typical first interaction looks like. Claude Code reads the relevant files, follows imports, and gives you an explanation grounded in your actual code.

$ cd projects/my-app
$ claude

Claude Code v1.0.33

Model: claude-sonnet-4-20250514
Context: 200,000 tokens (used: 1,247)

> What does the auth middleware do in this project?

Searching codebase...
Read src/middleware/auth.ts
Read src/middleware/index.ts
Read src/types/auth.ts

The auth middleware in this project handles JWT-based authentication.
Here's what it does:

1. Extracts the Bearer token from the Authorization header
2. Validates the JWT signature using the secret from env.JWT_SECRET
3. Decodes the payload and attaches req.user with the user's ID and role
4. Returns 401 Unauthorized if the token is missing or invalid

The middleware is applied to all routes under /api/ except
/api/auth/login and /api/auth/register.

Cost: $0.003 | Tokens: 1,842 in / 247 out

Now try asking it to make a change. This triggers the full agentic loop: gather context, take action, and verify results.

Here’s what the full agentic loop looks like in action, gathering context, making a targeted edit, and verifying with tests:

  > Add input validation to the user registration endpoint.
> Validate email format and password is at least 8 characters.

Searching codebase...
Read src/routes/auth.ts
Read src/schemas/user.ts
Read src/middleware/validate.ts

Edit src/routes/auth.ts
  - const { email, password } = req.body;
  + const { email, password } = req.body;
  + if (!email || !/^[^@]+@[^@]+\.[^@]+$/.test(email)) {
  +   return res.status(400).json({ error: 'Invalid email format' });
  + }
  + if (!password || password.length < 8) {
  +   return res.status(400).json({ error: 'Password must be at least 8 characters' });
  + }

Bash npm test

Tests: 14 passed, 0 failed
Done. Added email format and password length validation to POST /api/auth/register.

Here’s what happened in that recording, step by step:

1. Claude Code searched the codebase and read three relevant files to understand the registration endpoint.
2. It made a surgical edit to src/routes/auth.ts, adding validation logic.
3. It ran npm test to verify nothing broke. All 14 tests passed.

You’ll see each step in your terminal. Claude Code shows you what it’s reading, what changes it proposes, and what commands it runs. You stay in control the whole time.

As you gain confidence, try more complex prompts that require multiple steps.

Refactor the database connection module to use connection pooling.
Update all files that import the old connection helper.
Run the existing tests to make sure nothing breaks.

This kind of multi-step task is where the agentic loop really shines. Claude Code iterates through the gather-action-verify cycle multiple times, handling each step and verifying along the way.

When you’re done with a session, type /quit or press Ctrl+C to exit. Your conversation history is saved automatically, and you can resume later with claude --continue to pick up where you left off.

Best Practices

These practices will help you get the most out of Claude Code from day one.

• Start with small, well-defined tasks to learn how Claude Code operates. Ask it to add a function, fix a bug, or write a test before handing it large refactoring jobs.

• Review diffs before approving changes. Claude Code shows you exactly what it plans to modify. Read the diff carefully, especially when changes touch critical code paths.

• Use /rewind if something goes wrong. Reverting is fast and safe. It’s better to rewind and re-prompt with more specific instructions than to manually fix a bad edit.

• Keep commits small and focused. After Claude Code completes a task, commit the changes before starting the next one. This gives you clear rollback points and a readable Git history.

• Be specific in your prompts. “Fix the bug” is vague. “Fix the null pointer exception in the user service when email is missing” gives Claude Code the context it needs to find and fix the right issue.

• Use Git as your safety net. Commit before starting a new Claude Code task so you always have a clean baseline to return to. Since Claude Code works on your real files, Git discipline matters more than ever.

Slash Commands Quick Reference

Claude Code provides several slash commands you can type at the prompt. Here are the ones worth knowing right away:

• /help: show available commands and usage information
• /rewind: open the rewind menu to restore code and/or conversation to a previous point (alias: /checkpoint)
• /clear: reset the conversation and start fresh (useful between unrelated tasks)
• /compact: compress the conversation to free up context window space
• /cost: show token usage and cost for the current session (API users)
• /stats: visualize daily usage, session history, and model preferences (subscribers)
• /usage: show plan usage limits and rate limit status (subscribers)

Note: /cost is most relevant if you’re on direct API billing (pay-per-token). If you’re on a Claude Max, Pro, or Team subscription, use /stats to see your usage patterns and /usage to check your plan limits and rate limit status.

Here’s a quick look at some of these commands in action:

  > /help

Available commands:

/help            Show this help message
/rewind          Rewind conversation/code to a previous point
/clear           Reset conversation history
/compact         Compact conversation to free context
/cost            Show token usage and cost (API users)
/stats           Show usage stats (subscribers)
/model           Change the AI model
/diff            Show uncommitted changes
/quit            Exit Claude Code
  ... and more. Type / to see all commands.

> /cost

Session Cost

Total cost:            $0.12
Total duration (API):  2m 14.3s
Total duration (wall): 18m 5.7s
Total code changes:    42 lines added, 8 lines removed
Tokens in:             24,571
Tokens out:            3,842

> /compact

Compacting conversation...
Done. Compressed 28,413 tokens to 4,207 tokens.

You’ll encounter more commands throughout this guide. The Context Management chapter covers /compact and /clear in depth, and the Models & Costs chapter explains cost tracking and model selection.

Further Reading

For more detail on the topics covered in this chapter, check out the official Claude Code documentation:

• Claude Code Overview: official documentation covering all features and interfaces
• Quickstart Guide: Anthropic’s official getting-started walkthrough
• How Claude Code Works: deep dive into the agentic loop, tools, and context management

Next, learn how to give Claude Code project-specific instructions and manage the context window in Project Context & Memory.