Claude Code: The Complete Setup Guide (2026)

Why Claude Code Changes Everything

Claude Code is not an autocomplete tool. It is an autonomous coding agent that runs in your terminal, reads your codebase, writes files, runs tests, commits code, and manages entire features end-to-end. If you have used Copilot or Cursor, forget what you know. Claude Code operates at a fundamentally different level — it thinks in projects, not in lines.

This guide takes you from zero to a fully configured Claude Code setup with hooks, MCP servers, agent teams, and productivity shortcuts. By the end, you will have a system that makes you 5-10x more productive on real engineering work.

---

Step 1: Installation

Claude Code runs in three environments. Pick the one that fits your workflow, or use all three.

CLI (Primary — Recommended)

The CLI is where Claude Code is most powerful. Full terminal access, background tasks, and agent teams all work here.

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

# Verify installation
claude --version

# Start a session in your project directory
cd your-project
claude

Requirements: Node.js 20+ and an Anthropic API key (or a Claude Pro/Team/Enterprise subscription).

VS Code Extension

The VS Code extension gives you Claude Code inside your editor with inline diffs and a chat panel.

1. Open VS Code
2. Go to Extensions (Cmd+Shift+X)
3. Search "Claude Code"
4. Install the official Anthropic extension
5. Open the command palette (Cmd+Shift+P) and run "Claude Code: Start Session"

Desktop App

The standalone desktop app (macOS and Windows) provides a dedicated window for Claude Code without needing a terminal or editor open.

# macOS — install via Homebrew
brew install --cask claude-code

---

Step 2: CLAUDE.md — Your Project's Brain

CLAUDE.md is the single most important file in your Claude Code setup. It is a markdown file that lives at your project root and tells Claude everything it needs to know about your project: conventions, architecture, rules, and preferences.

Think of it as onboarding documentation for an AI teammate that actually reads and follows every word.

Where CLAUDE.md Files Live

Claude Code reads instructions from three locations, in order of priority:

Location	Scope	Example Use
~/.claude/CLAUDE.md	Global (all projects)	Your personal coding style, security rules, communication preferences
./CLAUDE.md (project root)	Project-wide	Architecture decisions, tech stack, naming conventions
./src/CLAUDE.md (subdirectory)	Directory-specific	Module-specific rules, API patterns for that folder

What to Put in CLAUDE.md

A good CLAUDE.md answers these questions:

• What is this project? Tech stack, purpose, deployment target.
• What are the conventions? Naming, file structure, import patterns.
• What should Claude never do? Forbidden patterns, deprecated APIs, security rules.
• What should Claude always do? Testing requirements, commit message format, PR templates.

Example: CLAUDE.md for a Next.js Project

# Project: Acme Dashboard

## Tech Stack
- Next.js 16 with App Router (TypeScript)
- Tailwind CSS 4 + shadcn/ui
- Drizzle ORM + Turso (SQLite)
- Clerk for authentication
- Vercel for deployment

## Conventions
- All components in `src/components/` use named exports
- API routes live in `src/app/api/` and return typed responses
- Database schema in `src/db/schema.ts` — use Drizzle migrations
- Environment variables: `.env.local` for dev, Vercel dashboard for prod

## Rules
- NEVER use `any` type — always define proper TypeScript interfaces
- ALWAYS use server components by default; add "use client" only when needed
- ALWAYS run `npm run lint` before committing
- Test files live next to source files: `component.test.tsx`
- Commit messages follow conventional commits: feat, fix, refactor, docs, test

## File Size
- Maximum 400 lines per file
- Extract utilities when files exceed 300 lines

## Security
- No hardcoded API keys or secrets
- All user input validated with Zod schemas
- SQL injection prevention via Drizzle parameterized queries

---

Step 3: Hooks — Automated Behaviors

Hooks let you run custom logic before or after Claude uses a tool, or when a session ends. They are defined in your .claude/settings.json file.

Hook Types

Hook	When It Runs	Common Use
PreToolUse	Before Claude calls a tool	Validate parameters, block dangerous commands, add context
PostToolUse	After a tool returns a result	Auto-format code, run linters, save state
Stop	When Claude finishes responding	Final verification, session summary, cleanup

Setting Up Hooks

Create or edit .claude/settings.json in your project:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
      }
    ],
    "Stop": [
      {
        "command": "echo 'Session complete' >> .claude/session.log"
      }
    ]
  }
}

Practical Hook Examples

Auto-format after every file write:

{
  "matcher": "Write|Edit",
  "command": "npx prettier --write \"$CLAUDE_FILE_PATH\""
}

Run ESLint after editing TypeScript files:

{
  "matcher": "Write|Edit",
  "command": "npx eslint --fix \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
}

Block dangerous shell commands:

{
  "matcher": "Bash",
  "command": "echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'rm -rf|DROP TABLE|format' && echo 'BLOCKED: Dangerous command detected' && exit 1 || exit 0"
}

---

Step 4: MCP Servers — Extending Claude's Reach

MCP (Model Context Protocol) is an open standard by Anthropic that lets Claude connect to external tools and data sources. An MCP server exposes tools, resources, and prompts that Claude can call during a session.

What MCP Servers Do

Without MCP, Claude can only read files, write files, and run shell commands. With MCP servers, Claude can:

• Query databases directly (SQLite, PostgreSQL, DuckDB)
• Search the web (Tavily, Exa, Perplexity)
• Manage GitHub issues and PRs
• Read and write Google Docs, Sheets, and Slides
• Send Slack messages
• Access memory systems across sessions

Adding MCP Servers

MCP servers are configured in ~/.claude.json (global) or .claude/settings.json (per-project):

{
  "mcpServers": {
    "sqlite": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-sqlite"],
      "env": {}
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Recommended MCP Servers for 2026

Server	Purpose	Install
@anthropic-ai/mcp-sqlite	Local database queries	npx -y @anthropic-ai/mcp-sqlite
@modelcontextprotocol/server-github	GitHub integration	npx -y @modelcontextprotocol/server-github
@anthropic-ai/mcp-filesystem	Scoped file access	npx -y @anthropic-ai/mcp-filesystem
mcp-server-fetch	HTTP requests	npx -y mcp-server-fetch
superlocalmemory	Persistent memory	npx -y superlocalmemory

You can discover more servers at smithery.ai and glama.ai.

---

Step 5: Skills and Slash Commands

Skills are reusable prompts that Claude loads on demand. They package domain expertise into repeatable workflows.

Built-in Slash Commands

Command	What It Does
/commit	Stage changes, write commit message, commit
/review	Code review the current changes
/plan	Create an implementation plan before coding
/tdd	Test-driven development workflow (RED → GREEN → REFACTOR)
/debug	Structured debugging session

Using Skills

Type the slash command in your Claude Code session:

> /commit

Claude will analyze your changes, draft a commit message following your conventions, and create the commit.

Custom Skills

You can create custom skills by adding markdown files to your .claude/skills/ directory or installing them from plugins. A skill file defines a trigger pattern, instructions, and optional tool requirements.

---

Step 6: Agent Teams — Parallel Execution

Agent teams are the most powerful feature introduced with Opus 4.6. Instead of Claude working sequentially, it can spawn multiple parallel agents that work on independent tasks simultaneously.

When to Use Agent Teams

• Implementing features across multiple files that do not depend on each other
• Running code review on several modules at once
• Researching multiple topics in parallel
• Writing tests for different components simultaneously

How Agent Teams Work

When Claude detects independent work streams, it can dispatch sub-agents. Each agent gets its own context, works independently, and reports back to the orchestrating session.

You: "Add authentication to the API, create the user dashboard, and write tests for the payment module."

Claude (orchestrator):
  → Agent 1: Implements API authentication
  → Agent 2: Builds user dashboard
  → Agent 3: Writes payment tests
  ← All three report back, orchestrator merges

Enabling Agent Teams

Set the environment variable before starting Claude Code:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude

Or add it to your shell profile (~/.zshrc or ~/.bashrc) to enable it permanently.

---

Step 7: Keyboard Shortcuts and Productivity Tips

Essential Shortcuts

Shortcut	Action
Ctrl+C	Cancel current operation
Ctrl+D	End session
Tab	Accept suggestion
Esc	Dismiss suggestion
Up Arrow	Previous message

Productivity Tips

1. Start every session with context. Tell Claude what you are working on. "I'm implementing the user settings page" is better than "help me code."

2. Use fast mode for simple tasks. When you need quick edits without deep reasoning:

claude --fast "fix the TypeScript error in src/utils/auth.ts"

3. Reference files directly. Claude works better when you point it at specific files:

> Look at src/db/schema.ts and add a "subscriptions" table with userId, plan, and expiresAt columns

4. Let Claude run tests. Do not manually verify — tell Claude to run the test suite and fix failures:

> Run npm test and fix any failures

5. Use model selection strategically.

Model	Best For	Cost
Haiku 4.5	Quick edits, boilerplate, simple questions	Lowest
Sonnet 4.6	Day-to-day development, most coding tasks	Medium
Opus 4.6	Architecture decisions, complex debugging, agent teams	Highest

Set the default model:

claude --model sonnet  # For everyday work
claude --model opus    # For complex sessions

---

Step 8: Performance Settings

Context Window Management

Claude Code works best when it has relevant context without noise. Keep your CLAUDE.md concise. Use .claudeignore (same syntax as .gitignore) to exclude large directories:

# .claudeignore
node_modules/
dist/
.next/
coverage/
*.min.js

Cost Control

Set spending limits to avoid surprise bills:

# Set a session budget (in USD)
claude --max-cost 5.00

Caching

Claude Code caches file reads and tool results within a session. For large codebases, this means the first few interactions may be slower as Claude builds its understanding, but subsequent operations are fast.

---

Putting It All Together

Here is the complete setup checklist:

1. Install Claude Code — CLI (npm install -g @anthropic-ai/claude-code)
2. Create CLAUDE.md at your project root with tech stack, conventions, and rules
3. Add hooks in .claude/settings.json for auto-formatting and safety
4. Configure MCP servers for database access, GitHub, and any external tools you use
5. Learn the slash commands — /commit, /review, /plan, /tdd
6. Enable agent teams for parallel work on complex tasks
7. Create .claudeignore to keep context clean
8. Set cost limits to stay within budget

The difference between a beginner Claude Code user and a power user is not talent — it is configuration. Spend 30 minutes setting up your environment properly, and every session after that will be dramatically more productive.

---

Further Reading

• Model Context Protocol Specification
• Claude Code Documentation
• MCP Server Registry on Smithery
• Building Custom Skills