Claude Code: The Complete Guide

Claude Code is my daily driver. I use it more than any other tool, more than my IDE, more than my browser, more than Codex. I have shipped this entire website with it, built MCP servers, refactored sprawling codebases, and let it diagnose why my MacBook was overheating. It is not perfect. It is lazy in the same way a human engineer is lazy, and it will half-finish tasks if you let it. But for the speed at which you can go from idea to working code, nothing else comes close right now.

This guide covers everything I know about using Claude Code effectively, from installation to agent teams. It is based on months of daily use across real projects, not a weekend of kicking the tires.

What Claude Code Actually Is

Claude Code is a coding agent that lives in your terminal. You give it a task in plain English and it figures out which files to read, what changes to make, and what commands to run. It lives on your computer, so it has access to your codebase the same way you do, so no more copy-pasting code into ChatGPT.

But calling it a “coding agent” undersells it. Claude Code is really a general-purpose agent that happens to be great at coding. It has access to your filesystem, your terminal, your browser, and whatever MCP servers you connect to it. I have used it to diagnose why my MacBook was overheating, control Chrome to test UIs, run SEO analysis scripts, and manage git workflows across multiple repos. It can interact with your computer in ways that go well beyond editing source files.

It uses Claude Opus and Claude Sonnet to power it, though you can swap in other models through third-party applications. It usually works at around a 200k context window, so it cannot hold your entire codebase in context, but it is pretty good at searching for the relevant parts. 1 million token context windows are available, but too expensive for daily use. And because it lives in your terminal, it works in pretty much any IDE: VS Code, JetBrains, Cursor, the Claude desktop app, or just a plain terminal window.

Installation and Pricing

Install Steps

If you are on macOS or Linux, installation is one command:

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

Then run claude in any project directory. It will walk you through authentication on first launch. On Windows, Claude Code runs via WSL, so install WSL first, then the same command inside your WSL terminal.

You can also use Claude Code through the VS Code extension (search “Claude Code” in the extensions marketplace), the JetBrains plugin, or the Claude desktop app. The CLI is the most full-featured option, but the VS Code extension is solid if you prefer a graphical interface.

Pricing

Claude Code requires a Claude Pro subscription at minimum ($20/month). The Pro plan includes standard usage limits which are enough for light to moderate use. If you are using it all day, you will hit the limits.

The Max plans remove that constraint: Max 5x is $100/month and Max 20x is $200/month. I am on the $100/month Max plan and it has been reasonable so far. I use Claude Code heavily every day and rarely hit the ceiling.

You can also use Claude Code with API keys for pay-per-token pricing, but fair warning: it is unsustainably expensive. The Max plans are heavily subsidized compared to raw API costs. A heavy day of coding through the API can easily run $50-100+. The problem is that if you are building with the Claude Agent SDK to run Claude Code programmatically, you are forced onto API pricing, since the subsidized plans are only for interactive use. Something to factor in if you are planning automated workflows.

One more thing on pricing: Anthropic is aggressively anti-user about how you use your Max subscription. If they detect you are routing the inference for anything other than Claude Code itself, they will ban you. Do not get too comfortable relying on their subsidized pricing for anything creative.

In general, try not to become overly tied to Anthropic as a company. They make the best coding model right now, but their track record as a software company is terrible. Every single piece of software they ship has been written by Claude Code, so it is all riddled with bugs, including several showstoppers I have experienced firsthand. Their uptime is bad. Their desktop app is broken more often than it works. Use Claude Code because it is the best tool available today, but do not bet your entire workflow on Anthropic keeping things stable.

CLAUDE.md: The Most Important File You Will Write

CLAUDE.md is a special file that Claude reads at the start of every session. Think of it as persistent instructions: your project conventions, build commands, architectural decisions, and anything else Claude needs to know to work effectively in your codebase. If you only do one thing after installing Claude Code, write a CLAUDE.md.

You can generate a starter one by running /init inside a Claude Code session. It will scan your project and produce a reasonable starting point. Then you iterate on it over time as you notice Claude making the same mistakes or missing the same context.

What to Put in CLAUDE.md

• Build and test commands. Anything Claude cannot guess from your package.json or Makefile. pnpm dev, pnpm test, pnpm lint.
• Code style rules that differ from defaults. If you use tabs instead of spaces, if you prefer named exports over default exports, if you use a specific import ordering, state it explicitly.
• Architecture decisions. “We use the App Router, not Pages Router.” “All API routes stream responses.” “State lives in React context, not Redux.”
• Testing philosophy. What framework you use, how to run individual tests, whether you want mocks or real services.
• Repo etiquette. Commit message format, PR conventions, branch naming.

You can emphasize critical rules with “IMPORTANT” or “YOU MUST”, and Claude pays more attention to emphasized instructions. The project structuring guide I wrote covers this in more detail with example prompts for generating these files.

What to Leave Out

Do not dump your entire API documentation into CLAUDE.md. Do not describe every file in the repo. Do not include standard language conventions that Claude already knows. The file should be as short as possible while still preventing mistakes. Every line you add dilutes the lines that matter.

A good test: for each line, ask “would removing this cause Claude to make a mistake?” If the answer is no, cut it.

Multiple CLAUDE.md Files

Claude Code supports CLAUDE.md files at multiple levels:

• ~/.claude/CLAUDE.md: applies to every project on your machine. Good for personal preferences like “use pnpm” or “never auto-commit.”
• ./CLAUDE.md: project root, committed to git. Your team shares this.
• ./CLAUDE.local.md: project root, gitignored. Your personal overrides for this project.
• Parent and child directories: automatically loaded for monorepo setups.

Nested CLAUDE.md files are important for larger codebases. If you have a monorepo with a frontend and a backend, the root CLAUDE.md covers shared conventions, while frontend/CLAUDE.md and backend/CLAUDE.md cover the specific patterns for each part. Claude loads the relevant one based on which directory it is working in.

CLAUDE.md files can also import other files with @path/to/file syntax. I use this to pull in my README and architecture docs without duplicating content.

One habit that pays off: whenever Claude keeps making the same mistake or going in a direction you do not want, that is a signal to update CLAUDE.md. Tell Claude to add a rule about it. “Add to CLAUDE.md that we never use default exports for components.” Next session, the mistake stops.

That said, you really should be manually reviewing this file. Let Claude write the initial draft and propose additions, but direct the edits yourself, or just edit the file by hand. CLAUDE.md is the single highest-leverage file in your project for controlling Claude Code's behavior. If it drifts or gets bloated, everything downstream gets worse. Treat it like code you own, not something you delegate entirely.

Plan Mode

Plan Mode is when Claude reads your codebase and thinks through an approach before making any changes. Toggle it with Shift+Enter in the CLI or the permission mode selector in VS Code. In Plan Mode, Claude will explore files, trace call paths, and present a plan. You can edit the plan directly, ask questions, and only switch to Normal Mode when you are satisfied.

I use Plan Mode for anything non-trivial: multi-file refactors, unfamiliar codebases, features where I am not sure which files to touch. For quick fixes and one-file changes, skip it. The overhead is not worth it for a typo.

One thing people miss: you can edit the plan file directly in your editor while Claude is in Plan Mode. Hit Ctrl+G in the CLI to open it. This is faster than describing changes to the plan in chat.

Skills: Custom Slash Commands

Skills are reusable instructions you package as slash commands. Create a folder at .claude/skills/my-skill/ with a SKILL.md file inside, and you get a /my-skill command you can invoke anytime.

A basic SKILL.md looks like this:

---
name: deploy
description: Deploy the current branch to production
disable-model-invocation: true
allowed-tools: Bash(vercel deploy *)
---
Deploy the current branch to Vercel production.

1. Run `pnpm build` and verify no errors
2. Run `vercel deploy --prod`
3. Report the deployment URL

The disable-model-invocation: true flag is important for skills like deploy and commit, since it prevents Claude from triggering them automatically. Without it, Claude might decide to deploy your code unprompted.

Skills follow the open Agent Skills standard, so they work across multiple AI tools, not just Claude Code. You can store skills globally at ~/.claude/skills/ to share them across all your projects. I have skills for committing, creating PRs, running my SEO tools, and generating blog post scaffolding.

Skills also support dynamic context injection. You can embed shell commands that run before the skill content is sent to Claude. Put a command inside ! backticks and its output gets inlined:

---
name: pr-summary
description: Summarize the current PR
context: fork
agent: Explore
---
## PR Context
- Diff: !`gh pr diff`
- Comments: !`gh pr view --comments`

MCP Servers: Giving Claude New Abilities

MCP (Model Context Protocol) servers are plugins that give Claude access to external tools and data sources. Claude cannot browse the web, query databases, or interact with third-party APIs on its own. MCP servers close that gap.

Adding an MCP server takes one command:

# HTTP transport (recommended for hosted servers)
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# Local process (for self-hosted servers)
claude mcp add --transport stdio my-server -- node /path/to/server.js

# With environment variables
claude mcp add -s user -e API_KEY=xxx my-server -- npx my-mcp-server

The -s user flag makes the server available across all your projects. Without it, the server is scoped to the current project only. You can also use -s project to create a .mcp.json file that gets committed to git, so your whole team gets the same MCP servers.

I have written about setting up MCP servers in detail. The YouTube MCP server guide walks through the full setup process and the Image Generation MCP Server is another example of what you can do with MCP.

Use /mcp inside a Claude Code session to check which servers are connected, reconnect dropped connections, and handle OAuth authentication flows.

If you want Claude Code to configure its own MCP servers, you have to specifically ask it to look up the instructions using the Claude Code guide subagent, and then it will find the right commands. Or you can point it directly at the MCP server's docs. In general, Claude Code is quite stupid at doing its own configuration. It will confidently run the wrong claude mcp add command with made-up flags if you do not give it the actual documentation to reference.

Subagents: Delegating Work

Subagents are specialized Claude instances that handle specific tasks in their own context window. Claude Code comes with several built-in subagents: Explore (fast, read-only codebase search), Plan (research during Plan Mode), and a general-purpose agent with full tool access.

If you are tackling a refactor that touches many files, or anything that can be parallelized, just ask Claude Code to use subagents. You do not need to configure anything. Say “use subagents to refactor all the API routes to use the new error handler” and it will spin up multiple agents, divide the work, and merge the results. It handles this surprisingly well out of the box.

You can also define custom subagents by creating Markdown files in .claude/agents/ if you want specialized agents for recurring tasks like code review or test writing. But honestly, the built-in subagents cover most use cases. The main thing to know is that the feature exists and you should ask for it when a task is big enough to benefit from parallel work.

Agent Teams

Agent teams are the most advanced feature in Claude Code right now. They are still experimental, so you need to opt in by setting an environment variable:

// In ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

The idea is simple: instead of one Claude instance doing everything, you have a team lead that creates tasks, spawns teammates, and coordinates work. Each teammate is a separate Claude Code instance with its own context window. They communicate through a shared task list and a messaging system.

This is powerful for large tasks that touch many parts of a codebase simultaneously. The team lead can spin up a frontend teammate and a backend teammate working in parallel, each in their own worktree, and merge the results when both are done. I wrote about the architectural implications of this pattern in Architecture in the Age of AI Agents.

Fair warning: agent teams use significantly more tokens than a single session. Each teammate is a separate Claude instance burning through context. Use them for genuinely parallelizable work, not for tasks a single agent could handle sequentially.

Hooks: Automation and Safety Rails

Hooks are shell commands that run at specific points in Claude Code's lifecycle. They are deterministic and guaranteed to execute, unlike CLAUDE.md instructions which Claude can ignore. This makes hooks the right tool for hard rules: things that must always happen or must never happen.

The most useful hook events:

• PreToolUse: runs before Claude executes a tool. Use this to block dangerous commands, enforce code style, or add safety checks. Exit code 2 blocks the action.
• PostToolUse: runs after a tool call succeeds. Good for auto-formatting code after edits or logging changes.
• Stop: runs when Claude finishes responding. Use this to run linters or tests automatically after every change.
• SessionStart: runs when a session begins. Good for setting up environment variables or checking prerequisites.

A practical example: I have a PreToolUse hook on the Bash tool that blocks any command containing rm -rf. Claude is generally well-behaved, but accidents happen, and this one is not reversible.

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/block-destructive.sh"
          }
        ]
      }
    ]
  }
}

Hooks also come in prompt and agent types. A prompt hook sends the context to Claude and gets back a pass/fail decision. An agent hook spawns a subagent with tool access for multi-step verification. These are useful for code review gates and compliance checks.

A word of warning: do not put expensive operations in hooks. I once tried running a full TypeScript type check as a PostToolUse hook after every edit, and my CPU usage spiked to the point where my machine was unusable. Claude Code makes a lot of small edits in rapid succession, so any hook that takes more than a second or two will compound fast. Keep hooks lightweight. Quick lint checks and simple validation scripts are fine, but save full builds and type checks for the Stop hook or run them manually.

Worktrees: Parallel Work Without Conflicts

Git worktrees let you have multiple copies of your repo checked out to different branches simultaneously. Claude Code has native worktree support. Start a session with claude -w feature-name and it creates an isolated worktree with its own branch. Your main working directory stays untouched.

This is essential when you are running multiple Claude Code sessions on the same repo. Without worktrees, two sessions editing the same files will step on each other. With worktrees, each session has its own copy of the codebase.

I use Superset.sh for managing worktrees visually. It is simple: it just creates worktrees and lets you run terminals in them. But that is exactly what you need to run Claude Code and Codex side by side on different tasks without them interfering with each other. I talked more about worktree management in my Claude Code vs Codex vs Cursor comparison.

IDE Integrations

Claude Code works in multiple environments. Here is what I have tried:

• CLI (terminal): the most full-featured option. Every feature works here. This is what I use 90% of the time.
• VS Code extension: graphical chat panel, inline diffs, plan review, @-mentions with line ranges. Cannot configure MCP servers (use the CLI for that, then they work in both).Cmd+Esc toggles focus between the editor and Claude.
• JetBrains plugin: similar to VS Code, works in IntelliJ, WebStorm, PyCharm, etc.
• Claude desktop app: has worktree support and a friendlier UI, but Anthropic builds their software with Claude Code, so it tends to be buggy. The VS Code extension is more stable.
• Browser (claude.ai): runs Claude Code on Anthropic's cloud in isolated VMs. You can kick off sessions from your phone. Sessions are resumable in VS Code via the Remote tab.

One tool I use more than any IDE for reviewing Claude's changes is GitHub Desktop. The diff view is cleaner and faster to scan than anything built into an editor. When agents are making changes across dozens of files, being able to quickly see exactly what changed matters more than fancy editor integration.

How I Actually Use Claude Code

My daily workflow is Claude Code in the terminal plus an IDE open for file browsing. I keep GitHub Desktop open for reviewing diffs. That is the whole setup.

For most tasks, I describe what I want in plain English and let Claude figure out the implementation. “Add a share button to all blog posts that copies the URL to clipboard.” “Refactor the data layer to use a single content registry.” “Find why the terminal animation stutters on mobile.” Claude reads the relevant files, makes changes, and I review in GitHub Desktop.

For bigger features, I start in Plan Mode. Let Claude explore the codebase, present an approach, and I adjust the plan before any code gets written. This saves a lot of time compared to letting Claude charge ahead with the wrong approach and having to undo everything.

I start a new chat for each distinct task. Long conversations degrade Claude's performance as the context fills up. A fresh session with clear instructions almost always produces better results than continuing a conversation that has been going for an hour.

When Claude gets stuck or starts going in circles, I switch models. For most work, Opus is my default. For particularly tricky debugging or complex multi-system tasks, I sometimes reach for Codex with GPT 5.3 which is slower but more thorough.

Power User Patterns

These are patterns I picked up after hundreds of sessions. They are not in any official documentation. They come from watching Claude waste my time in predictable ways and figuring out how to prevent it.

Front-Load Context to Prevent Wrong Turns

The single biggest time waster with Claude Code is wrong-path investigation. Claude will confidently dive into the wrong file, the wrong component, or the wrong code path. It makes changes, you realize it is editing the wrong thing, and you have to redirect it. Sometimes two or three times before it finds the actual target. I tracked this over a couple of months and it accounted for nearly half of all the friction in my sessions.

The fix is dead simple: tell Claude exactly where to look before it starts working. Instead of “fix the sidebar,” say “fix the sidebar widget in src/components/sidebar-widget.tsx, not the article body sidebar.” If your codebase has ambiguous names (and they all do), be explicit about which one you mean. The five seconds you spend typing the file path saves the five minutes of wrong-turn investigation.

For larger codebases, add a component map to your CLAUDE.md: a quick reference of which files handle which functionality. Something like “sidebar means SidebarWidget in src/components/, not the aside in article layouts.” This is especially valuable when the same concept, like “sidebar” or “header,” maps to multiple things in your code. Claude does not guess well when there is ambiguity. Remove the ambiguity.

Batch Related Work

If you find yourself doing edit, commit, push, new session, edit, commit, push for related changes, you are paying a context-loading tax every time. Each new session means Claude has to re-read your CLAUDE.md, re-scan the relevant files, and rebuild its understanding of the task from scratch.

Bundle related changes instead. “Update all the API routes to use the new error handler, then update the tests for each one, then commit once at the end.” One session, one commit, no repeated context loading. I went from doing five small sessions in an afternoon to one session that handles all five tasks, and the output quality is actually better because Claude maintains context across the related changes. It sees the pattern it established in route one and carries it through routes two through five without you having to re-explain anything.

CLAUDE.md as a Feedback Loop

I already covered what to put in CLAUDE.md and what to leave out. But there is a broader pattern worth calling out: treat CLAUDE.md as a living feedback loop between you and your AI agent, not a static configuration file.

After every session where something went wrong, ask yourself: could a CLAUDE.md rule have prevented this? If Claude keeps targeting the wrong files, add a location guide. If it uses the wrong API pattern, add an example of the correct one. If it keeps trying to install dependencies with npm when your project uses pnpm, add a rule. The most productive CLAUDE.md files I have written are not style guides. They are collections of mistakes Claude made that I never want to see again.

Then review the file weekly and cut anything stale. Rules about a library you no longer use, patterns from a section you have since refactored, instructions that Claude follows correctly without being told. The file should evolve constantly: new rules added after bad sessions, old rules pruned when they are no longer needed. This is how you compound the quality of your AI-assisted work over time.

Agent Teams for Bulk Operations

I covered agent teams as a feature earlier, but the practical pattern is worth spelling out. Agent teams are at their best when you have the same type of change across many files. I have used them to update metadata across 30+ files, add consistent error handling to every API route, and run audits across an entire codebase. One session tackled five distinct tasks across 70+ files in about the time it would have taken to do one of those tasks by hand.

The pattern is straightforward: describe the change once, tell Claude to use agent teams, and let it figure out the parallelization. Each agent gets its own context window and optionally its own worktree, makes its changes, and the results merge back. For a 30-file update, this takes minutes instead of the hour it would take going file by file in a single session.

The catch is token cost. Each teammate is a separate Claude instance burning through context. Do not use agent teams for a task that touches three files. That is just expensive parallelism with no real benefit. Save them for genuinely large operations where the time savings justify the cost. A good rule of thumb: if the task would take you more than 10 manual file edits, agent teams are probably worth it.

Custom Agents for Recurring Tasks

If you find yourself giving Claude the same multi-paragraph instructions every session, create a custom agent. Drop a Markdown file in .claude/agents/ that describes the task, the constraints, and the expected output format. Then you can spawn that agent by name instead of re-explaining everything from scratch.

# .claude/agents/code-audit.md
---
name: code-audit
description: Audit code for quality and consistency issues
---
You are a code auditor for this project.

Check the specified file(s) for:
- Missing or incomplete metadata
- Broken internal references
- Inconsistent patterns vs. the rest of the codebase
- Missing error handling at system boundaries
- Dead code or unused imports

Report findings as a checklist with file paths and line numbers.

Custom agents are particularly useful for domain-specific work where Claude needs context it would not have by default. The agent definition can include your project's conventions, file structure, and quality standards. Every time you spawn it, it already knows the rules. No more pasting the same five paragraphs of instructions at the start of every session.

Combine this with custom skills and you get a workflow where typing /audit spawns a pre-configured agent that knows your codebase inside and out. That is the level of automation where Claude Code stops feeling like a chat assistant and starts feeling like a team member.

Tips That Took Me Months to Learn

• Keep CLAUDE.md short and ruthless. Every unnecessary line dilutes the lines that matter. I review mine monthly and cut anything Claude has not needed.
• Watch Claude's edits. It will occasionally delete large chunks of working code to “simplify” things. Review diffs before committing. GitHub Desktop makes this fast.
• New chat for each task. Long contexts make Claude worse, not better. Start fresh.
• Use /compact before your context fills up. If you are deep in a task and cannot start fresh, run /compact Focus on the auth changes to summarize earlier context with specific instructions about what to preserve.
• Commit early and often. Before asking Claude to make big changes, commit what you have. If Claude makes a mess, you can revert cleanly.
• Be specific about what you want. “Make the homepage look better” produces slop. “Increase the heading font size on the homepage hero section and add 24px of bottom margin” produces exactly what you described.
• Use Esc+Esc to access checkpoints. Claude Code saves checkpoints at every step. If something goes wrong, you can rewind to any previous state, both the conversation and the code.
• Do not let Claude auto-commit or auto-push. Always review changes before they leave your machine. Set disable-model-invocation: true on any commit or deploy skill.
• Use the permission system. Run /permissions to allowlist specific commands (like npm run lint) so Claude does not ask every time, and denylist commands you never want it running.
• Use subagents for research. If you need to understand a codebase before making changes, spawn an Explore subagent. It uses Haiku (fast, cheap) and does not pollute your main context with search results.
• Tell Claude to verify targets before changing them. If Claude keeps charging ahead with wrong approaches, add a rule to your CLAUDE.md: “Before making changes to a component, confirm the target file with me first.” The 5-second confirmation costs nothing compared to the 5-minute redirect when Claude picks the wrong file.
• Run /insights to find your blind spots. Claude Code tracks how you use it and can generate a report of your session patterns, recurring friction points, and workflow habits. I discovered that wrong-path investigation accounted for nearly half my friction, something I would not have quantified without the data. The report also suggests CLAUDE.md additions and workflow improvements based on your actual usage.

Claude Code is the kind of tool where the difference between a novice and a power user is not speed, it is knowing which guardrails to put in place so you can trust the output. A well-configured CLAUDE.md, good hooks, and the discipline to review diffs will save you more time than any clever prompt.

For a deeper comparison with other AI coding tools, see my Claude Code vs Codex vs Cursor breakdown. If you want to learn how to structure your projects so AI agents can work on them effectively, I covered that too.