Claude Code: The Complete Guide (2026)

What Is Claude Code?

Claude Code is an agentic coding tool that runs in your terminal and operates on your whole project rather than the line you're typing. You give it a goal in plain language. It reads the relevant files, decides what to do, edits code, runs tests, reads the output, and keeps going until the task is done or it needs your input.

That "keeps going on its own" part is the difference from inline assistants. An autocomplete tool predicts the next few tokens at your cursor. Claude Code plans across many files, runs commands, and reacts to what it sees. It's closer to handing a task to a junior engineer than to using a fancy snippet expander.

It runs on Anthropic's Claude models, usually Opus for planning and heavier reasoning and Sonnet for faster execution, and you can switch between them mid-session. Crucially, it asks permission before running commands or editing files unless you've pre-approved those actions, so you stay in control of anything destructive.

Once you're comfortable with the basics, you extend it. Reusable shortcuts become Claude Code skills, external data and APIs come in through Claude Code MCP servers, and specialized roles become subagents. Each of those gets its own section below.

Installing & First Run

Installation is one command. Claude Code ships as an npm package, so you need Node installed, then:

npm install -g @anthropic-ai/claude-code
cd your-project
claude

On first launch it walks you through authentication, either with your Anthropic account (Pro or Max) or an API key. From there you're in an interactive session inside your project. Type a request in plain English and it goes to work.

The first thing I do in any new repo is run /init. That generates a starter CLAUDE.md by reading your project structure, so the agent has baseline context from session one. The second thing I do is drop in a subagent team. Both are covered below.

How Claude Code Works: The Agent Loop

Under the hood, Claude Code runs an agent loop. Every turn follows the same pattern: the model decides what to do, calls a tool, reads the result, and decides again. It repeats until the task is done or it needs you.

Tools, Permissions, and Context

Three concepts make the loop work, and understanding them is what turns Claude Code from a toy into a tool:

Permissions are where most teams either feel safe or get burned. By default Claude Code asks before it runs a command or edits a file. You can loosen that with an allowlist for safe, repetitive actions (like running tests) and tighten it for anything outward-facing. The right setup lets the agent move fast on chores while still stopping to ask before it deploys or deletes.

Context is the other lever, and it's the one that costs you money. Every file the agent reads and every tool result stays in the window and gets re-sent on the next turn. That's why a tidy CLAUDE.md and tight task scoping matter so much, which is the next section.

CLAUDE.md & Context Engineering

CLAUDE.md is a Markdown file that Claude Code reads automatically at the start of every session. It's your project's memory. Build commands, naming conventions, the deploy method, and the gotchas that bit you last week all live here, and the agent picks them up without you re-explaining anything.

This is the single highest-leverage thing you can set up. A project with a good CLAUDE.md gets fewer wrong assumptions, fewer "wait, we don't use that library" corrections, and more changes that match how your code already works. A project without one makes the agent guess every session.

What Belongs in CLAUDE.md

• Commands: how to build, test, lint, and run the project
• Deploy method: exactly how this project ships, so the agent never guesses
• Conventions: naming, file structure, the patterns to match
• Gotchas: the non-obvious traps and the bugs you've already fixed once
• What to ignore: generated folders, vendor code, anything not worth reading

"Context engineering" is just the discipline of deciding what the agent should and shouldn't be carrying. CLAUDE.md is the persistent layer; clearing the conversation between unrelated tasks is the per-session layer. Get both right and the agent stays sharp and cheap. Our full CLAUDE.md guide walks through a template and real examples.

MCP Servers: Giving Claude Code New Tools

Out of the box, Claude Code can read files, edit them, and run shell commands. MCP servers extend that. MCP, the Model Context Protocol, is an open standard for connecting an agent to external tools and data: a database, a browser, a design tool, a third-party API, your file system.

Once an MCP server is configured, its tools show up alongside the built-in ones and the agent calls them like any other action. Want Claude Code to query your Postgres database, drive a real browser, or pull live docs for a library? That's an MCP server. It's the difference between an agent that can only touch local files and one that can reach into the systems your work actually depends on.

Common MCP Servers

• Filesystem & shell control: broader file and process access than the defaults
• Databases: query and inspect Postgres, Supabase, and others directly
• Browsers: drive a real browser to test pages and scrape content
• Docs: pull current library documentation instead of relying on training data

One MCP server worth knowing early is Desktop Commander, which gives the agent deeper control over your machine's files and terminal. I walk through it in the Desktop Commander MCP guide. For the full setup process and a shortlist of servers worth installing, see the Claude Code MCP servers guide.

Subagents & Agent Teams

Subagents are specialized agents defined as Markdown files in your project's .claude/agents/ folder. Each one has its own system prompt, its own tool permissions, and, importantly, its own context window. The main thread delegates a single step to a subagent, the subagent does that one job in isolation, and only the distilled result comes back.

That isolation is the whole point. A research sweep that reads 40k tokens of code stays in the researcher's context. The implementer never sees that noise, only the clean summary of what it needs to change. You get specialist focus on each step and a main thread that stays uncluttered. You also pin each subagent to a model, so a planning agent runs on Opus while a routine research agent runs on cheaper Sonnet.

A Concrete 5-Agent Team

Here's the team I actually run, which is the same one in the free starter pack:

The flow is research → implement → review → ship, one step at a time. The orchestrator never writes code; it passes the actual artifact forward, not a paraphrase. The review step is what catches the plausible-but-wrong changes a single pass would have shipped.

Slash Commands & Hooks

Two more features turn Claude Code from an assistant into something you can shape around your own workflow: slash commands and hooks.

Slash Commands

A slash command is a saved prompt you trigger with /name. Instead of retyping "review the current diff for bugs and check it against our conventions" every time, you save it once and call /review. Built-ins like /init and /clear ship with it; the more advanced versions are what Anthropic now packages as skills. Our Claude Code skills guide covers building your own.

Hooks

Hooks are shell commands that fire automatically on events, like after the agent edits a file or before it finishes a turn. The classic use is running your formatter or linter on every edit so the agent's output is always clean, or blocking a commit that fails a check. Anything you'd describe as "every time X happens, do Y" belongs in a hook, because the harness runs it deterministically rather than relying on the model to remember.

You don't need either to get started. But once a workflow repeats more than a few times, turning it into a slash command or a hook is what keeps your sessions fast and consistent.

Managing Token Cost

Claude Code bills against a Claude subscription or API credits, and most of the cost is input tokens. The agent re-reads files and re-sends conversation history on every turn, so a long, messy session gets expensive fast. The good news: the same habits that cut cost also improve output quality, because a focused context produces better reasoning.

Where the Tokens Go, and How to Cut Them

• Trim CLAUDE.md. It loads every turn, so every extra paragraph is a recurring tax.
• Clear between tasks. Run /clear when you switch to something unrelated so old context stops re-sending.
• Scope tightly. Point the agent at the files that matter instead of letting it explore the whole repo.
• Right-size the model. Let Sonnet handle routine edits and reserve Opus for planning and hard reasoning.
• Use subagents. A heavy research sweep stays in the subagent's window instead of bloating your main thread.

I go deep on this, including how to read your usage and where the spend actually hides, in the Claude Code token optimization guide. If you're hitting usage limits on a Pro or Max plan, the Claude Code credits breakdown explains how the limits and credits actually work.

Claude Code vs Other AI Coding Tools

Claude Code isn't the only AI coding tool, and it isn't the right one for every moment. The useful distinction is between inline assistants and agents.

In practice these aren't mutually exclusive. Plenty of developers keep an IDE assistant for the tight loop of writing code by hand and reach for Claude Code when they want to delegate a whole feature or chore. The full breakdown, including where each one wins and loses, is in our Claude Code vs Cursor comparison.

Common Workflows

Theory aside, here's what using Claude Code looks like day to day. Two patterns cover most of my work.

Ship a Feature

For anything more than a one-liner, I hand the task to the orchestrator and let the team run. The orchestrator restates the goal, lists acceptance criteria, then sends the researcher to map the relevant files. The implementer makes the change in the smallest diff, the reviewer checks it against the plan, and the shipper runs the tests, builds, and (with my confirmation) deploys. My job shrinks to writing a clear request and reviewing the result.

> use the orchestrator to add email verification to the signup flow

orchestrator → researcher  (maps auth + signup files)
            → implementer  (writes the change)
            → reviewer     (checks vs acceptance criteria)
            → shipper      (test, build, deploy — asks first)

Automate a Repetitive Task

The other big win is chores: bumping dependencies, migrating a config format across dozens of files, generating boilerplate, cleaning up dead code. These are exactly the tasks a single autonomous pass handles well, because the steps are mechanical and verifiable. Describe the chore, let it run, and check the diff. Wrap the ones you repeat in a slash command so next time it's one word.

Best Practices

After a few hundred sessions, the habits that consistently produce good results come down to a handful of rules.

• Invest in CLAUDE.md first. It's the highest-leverage setup step. Every wrong assumption you fix once belongs in it.
• Delegate, don't micromanage. For 3+ step work, hand it to an orchestrator and review the output rather than driving each edit by hand.
• Keep the review step. A second adversarial pass catches the plausible-but-wrong changes a single pass ships.
• Require evidence. Make the agent run the check and paste the output. Never accept "the build passed" without seeing it.
• Confirm before destructive actions. Deploys, deletes, and anything outward-facing should require an explicit yes.
• Clear between tasks. A fresh context is cheaper and sharper than a long, drifting one.
• Stay in scope. Out-of-scope discoveries get reported back, not silently expanded into the change.

None of these are exotic. They're the same standards you'd expect from a careful engineer, encoded into how you set the agent up. The starter pack bakes them into every agent's prompt so you don't have to remember them.

Frequently Asked Questions