How to Set Up Claude Code (2026 Step-by-Step Guide)

Claude Code shipped as a research preview in early 2025 and became Anthropic's flagship terminal agent through 2026. By now most engineering teams are no longer asking whether to try it — they are asking how to install it correctly, plug it into the rest of their stack, and avoid the rough edges that come with a tool moving this fast.

The install command itself is one line. The interesting part is everything after: picking an auth method, writing a CLAUDE.md the agent will actually respect, wiring up MCP servers without leaking credentials, adding sub-agents that stay in scope, and locking down permissions so the agent does not run rm -rf on a tired Friday. None of that is hard, but skipping it is the difference between a tool that helps and a tool that gets uninstalled in a week.

This guide walks through the full 2026 setup end-to-end. Prerequisites, install, auth, first-run configuration, CLAUDE.md template, MCP servers, sub-agents, hooks, permissions, and a sanity test. Copy-paste commands throughout, with notes for macOS, Linux, and Windows (WSL). By the end you will have a working ~/.claude/ and a project-level .claude/ that you can commit to git.

Prerequisites

Before installing, confirm the basics. Claude Code is a Node-based CLI that talks to Anthropic's API (or an enterprise cloud provider), so you need a terminal, a runtime, and a credential.

• A modern terminal. macOS Terminal, iTerm2, Warp, Ghostty, Alacritty, WezTerm, Windows Terminal, or anything that supports ANSI colors and Unicode. Avoid the legacy Windows console host.
• Node.js 18 or newer. Verify with node --version. If you do not have it, install via nvm, fnm, volta, or your package manager. As of 2026 the recommended floor is Node 20 LTS. If you do not want Node on your machine at all, Anthropic also ships a standalone binary — covered below.
• An Anthropic API key or a Claude Pro/Max subscription or an AWS Bedrock / Google Vertex setup with Claude models enabled. Pick one, you do not need all three.
• Git. Not strictly required, but Claude Code is dramatically more useful in a git repo because it reads diffs, branches, and history natively.
• Roughly 200 MB of disk. The CLI plus its cache fits in well under that on a fresh install.

On Windows, install through WSL2 (Ubuntu or Debian). Native Windows install works for casual use but breaks subtly around shell hooks, file watchers, and MCP servers that expect POSIX paths. WSL is the supported path in 2026.

Step 1: Install

The default install path is npm, globally:

npm install -g @anthropic-ai/claude-code

Confirm it landed:

claude --version

You should see something like claude-code 2.x.x. If claude is not found, your global npm prefix is not on your PATH — add $(npm prefix -g)/bin to your shell rc file and reopen the terminal.

Alternative: standalone binary. If you do not want Node, Anthropic ships prebuilt binaries:

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

This drops a single binary at ~/.local/bin/claude and adds it to PATH. The binary is self-contained — no Node, no npm, no global packages to maintain. For containers, CI runners, and locked-down workstations this is the cleaner option.

Alternative: Homebrew. A community-maintained tap exists on macOS (brew install claude-code). It works, but lags behind the official npm release by a few days. Use it only if you already manage your CLIs with brew.

Alternative: Docker. Anthropic publishes anthropic/claude-code images. Useful for sandboxed agents and CI jobs where you do not want the CLI touching the host. Mount your repo in as a volume and pass the API key via env var.

Pick one install method and stick with it — mixing npm-global and brew installs causes PATH confusion that wastes an afternoon to debug.

Step 2: Authenticate

Claude Code supports three auth modes in 2026. Pick the one that matches how you already pay for Claude.

Option A — Anthropic API key (most common for individual devs). Generate a key at console.anthropic.com → Settings → API Keys. Then either run claude login and paste it interactively, or set the env var:

export ANTHROPIC_API_KEY="sk-ant-..."

Put that line in ~/.zshrc, ~/.bashrc, or a per-project .envrc if you use direnv. The CLI reads it on every launch.

Option B — Claude Pro / Max subscription. If you already pay for Claude.ai personally, you can sign in with the same account and your Claude Code usage counts against your subscription's message limits instead of metered API billing. Run:

claude login

It opens a browser for OAuth. This is the cheapest path for solo developers — typically a flat $20/month vs. $50–200/month in API usage for heavy users.

Option C — AWS Bedrock or Google Vertex. For teams with existing cloud contracts, data-residency requirements, or VPC-only policies. Set:

# Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
# Vertex
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project

Your normal AWS / GCP credentials (via aws configure or gcloud auth) are picked up automatically. Billing flows through your cloud account, not Anthropic.

Test the auth by running claude in any directory. If you see the prompt and can type a message, you are in.

Step 3: First-run config

On first launch Claude Code creates ~/.claude/ and walks you through a short config wizard. Most defaults are fine, but a few are worth setting deliberately.

• Working directory. The agent operates inside the directory you launched it from. Always launch from your repo root, not your home directory — running claude at ~ gives the agent access to dotfiles, SSH keys, and browser profiles. Don't.
• Default model. As of 2026 the options are Claude Opus 4.7, Sonnet 4.5, and Haiku 4. Opus is the default and is what you want for code generation. Sonnet is the fast/cheap option for chat and small edits. You can switch mid-session with /model.
• Theme. Dark, light, or auto. Cosmetic only.
• Telemetry. Opt-in. Off by default. Leave it off unless your team has a reason to share usage data.
• Editor. The CLI shells out to your $EDITOR for multi-line input. Set export EDITOR=nvim (or code -w, or whatever you use) in your shell rc.

Config lives at ~/.claude/settings.json. You can edit it directly:

{
  "model": "claude-opus-4-7",
  "theme": "dark",
  "autoUpdate": true,
  "telemetry": false
}

For a project-level override, create .claude/settings.json in your repo. Project settings beat user settings. Commit this file — it is how your team shares the same defaults.

Step 4: Write your first CLAUDE.md

CLAUDE.md is the single most important file in your setup. It is the project memory the agent reads at the start of every session. A good CLAUDE.md cuts your token usage in half and stops the agent from re-discovering your stack on every turn.

Drop a CLAUDE.md in your repo root. Start minimal:

# Project: <name>

## Stack
- Next.js 16 (App Router), TypeScript, Tailwind v4
- Supabase (Postgres + Auth), Vercel hosting
- pnpm workspaces, Turbo for build orchestration

## Conventions
- All routes live under `src/app/`
- Server actions under `src/app/_actions/`
- Types co-located: `Foo.tsx` + `Foo.types.ts`
- No default exports except for Next.js pages/layouts

## Commands
- `pnpm dev` — local dev on :3000
- `pnpm build` — production build, must pass before commit
- `pnpm lint` — eslint + typecheck

## Do not
- Edit anything in `/generated` — it is regenerated from schema
- Touch `next.config.mjs` without flagging the change
- Add new dependencies without asking

That is enough to start. The agent will read it on every launch and stay inside your conventions. You can grow it over time — most mature projects end up with 100–300 lines covering architecture, naming, testing patterns, and the things you've already had to correct the agent on twice.

For inspiration on what mature CLAUDE.md files look like in production, see our Claude Code best practices guide — it covers the patterns we use across our Claude Code agency engagements and what to put in CLAUDE.md vs. what belongs in a skill or sub-agent.

Step 5: Add an MCP server

The Model Context Protocol (MCP) is how Claude Code talks to external systems — filesystems, databases, APIs, browsers, design tools. By 2026 there are hundreds of MCP servers, but the canonical "hello world" is the filesystem server.

Install the filesystem MCP server:

claude mcp add filesystem npx -- -y @modelcontextprotocol/server-filesystem /Users/you/projects

That registers a server named filesystem that gives the agent read/write access to /Users/you/projects. Restart claude and run /mcp — you should see filesystem listed as connected, with tools like read_file, write_file, list_directory, and search_files.

The general shape of an mcp add command is:

claude mcp add <name> <command> -- <args>

You can configure servers at three scopes:

• User scope (--scope user): available in every project. Good for personal tools (Linear, Notion).
• Project scope (--scope project): committed to .mcp.json in the repo, shared with the team. Good for project-specific tools (your Supabase, your GitHub repo).
• Local scope (default): only this machine, this project, your config only.

For a curated list of MCP servers worth installing — Postgres, GitHub, Playwright, Sentry, Linear, Figma, and more — see the best Claude Code MCP servers roundup. Most teams end up with 5–10 servers configured and pick which to enable per session.

A small note on security: MCP servers run with your full local permissions. Treat the mcp add command like installing a CLI tool — only add servers from sources you trust, and read the config they write to ~/.claude.json or .mcp.json before running anything sensitive.

Step 6: Add a sub-agent

Sub-agents are scoped specialists you can invoke from the main session. They run with their own system prompt, their own tool allowlist, and they cannot see your main context — which is the point. Use them to parallelize, isolate risky tasks, or enforce a specific role like "code reviewer" or "test writer."

Create .claude/agents/code-reviewer.md in your repo:

---
name: code-reviewer
description: Reviews pull requests and recent diffs for bugs, security issues, and style violations. Invoke after writing or modifying code.
tools: Read, Grep, Bash(git diff:*), Bash(git log:*)
---

You are a senior code reviewer for this codebase.

When invoked, follow this protocol:
1. Run `git diff` to see the current changes
2. Read the affected files in full for context
3. Check for: security issues, type errors, performance regressions, missing error handling, missing tests, and violations of conventions in CLAUDE.md
4. Output a concise report grouped by severity: BLOCKER, WARNING, NIT

Do not write code. Do not run tests. Review only.
Be specific — quote line numbers and code snippets.

That is the complete file. The frontmatter declares the agent, the body is its system prompt, and the tools field locks down what it can do (read, grep, and two specific git commands — nothing else).

In your main session, invoke it explicitly:

Use the code-reviewer subagent on my last commit.

Or it gets invoked automatically when its description matches what you are doing. The agent runs in a fresh context, returns its report, and disappears — no token cost on your main thread for the review itself.

Common sub-agents to start with: code-reviewer, test-writer, debugger, doc-writer, migration-helper. Build the ones you actually need, not the ones from a tutorial.

Step 7: Add a hook

Hooks are shell commands the CLI runs automatically at specific lifecycle events — before a tool call, after a file edit, when the session stops, etc. They are how you wire Claude Code into your existing dev workflow without trusting the agent to remember.

The classic example is auto-format on edit. Add this to .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "if [ \"${CLAUDE_FILE_PATHS##*.}\" = \"ts\" ] || [ \"${CLAUDE_FILE_PATHS##*.}\" = \"tsx\" ]; then pnpm prettier --write \"$CLAUDE_FILE_PATHS\" 2>/dev/null; fi"
          }
        ]
      }
    ]
  }
}

Now any time the agent writes a .ts or .tsx file, Prettier formats it immediately. The agent does not need to remember, you do not need to ask, and your diffs stay clean.

Other hooks worth setting up:

• PreToolUse on Bash — block dangerous commands (rm -rf /, git push --force, sudo) before they run.
• PostToolUse on Write — run eslint --fix on the modified file.
• Stop — play a sound or send a desktop notification when the agent finishes a long task.
• SessionStart — log session metadata to a file for later auditing.

Hooks are powerful and run with your shell permissions. Test them with echo "..." first before wiring up anything destructive.

Step 8: Set permissions

By default, Claude Code asks before running shell commands or modifying files. That gets annoying fast. The fix is a project-level allowlist that says "yes, automatically run these specific things; ask me about everything else."

In .claude/settings.json:

{
  "permissions": {
    "allow": [
      "Read",
      "Grep",
      "Glob",
      "Bash(pnpm test:*)",
      "Bash(pnpm lint:*)",
      "Bash(pnpm typecheck)",
      "Bash(git status)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Bash(git add:*)",
      "Edit",
      "Write"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(git push:*)",
      "Bash(git reset --hard:*)",
      "Bash(sudo:*)",
      "Bash(npm publish:*)"
    ],
    "ask": [
      "Bash(git commit:*)",
      "Bash(pnpm install:*)"
    ]
  }
}

The allow list runs without prompting. The deny list is blocked outright, even if you try to approve. The ask list always prompts — useful for commits, installs, and other "I want to know before this happens" actions.

Tune this file as you go. A good rule: anything you'd happily watch the agent do unsupervised goes in allow. Anything you want a one-time approval prompt for goes in ask. Anything you'd fire someone for goes in deny.

Test the setup

You should now have:

• claude installed and on your PATH
• A working auth credential (API key, Pro, or Bedrock/Vertex)
• ~/.claude/settings.json with your user defaults
• .claude/settings.json in your repo with project defaults + permissions + hooks
• A CLAUDE.md at the repo root
• At least one MCP server registered
• At least one sub-agent in .claude/agents/

Smoke test it. From your repo root:

claude

Then in the session, try:

Read CLAUDE.md, then list the top-level directories in this repo and explain what each one is for.

If the agent reads the file without prompting for permission, lists the directories, and references your CLAUDE.md conventions in its answer — your setup is wired correctly.

Try the sub-agent:

Use the code-reviewer subagent to review the last commit.

And the hook — make the agent edit a .ts file and confirm Prettier runs on it automatically:

Open src/lib/utils.ts and add a one-line JSDoc comment to the first exported function.

If all three pass, you are done. Everything past this point is iteration — adding more MCP servers as you need them, growing CLAUDE.md as the agent makes mistakes, and tuning permissions as you get bolder.

Common installation errors

A short tour of the errors most people hit in their first hour.

command not found: claude — your global npm bin is not on PATH. Run npm prefix -g to find it, then add <that path>/bin to your shell rc. Re-open the terminal.

Error: Cannot find module '@anthropic-ai/claude-code' — install failed silently. Re-run with npm install -g @anthropic-ai/claude-code --verbose and check for permission errors. On macOS/Linux, prefer nvm/fnm over system Node to avoid needing sudo for global installs.

401 Unauthorized on first message — auth not set. Check echo $ANTHROPIC_API_KEY returns your key, or run claude login again. If using Bedrock/Vertex, confirm your cloud credentials work with aws sts get-caller-identity or gcloud auth list.

MCP server failed to start — usually a missing dependency for the server itself. Run the server's command manually (npx -y @modelcontextprotocol/server-filesystem /path) and check stderr. Most MCP servers need Node 20+ even if Claude Code itself runs on Node 18.

Agent ignores CLAUDE.md — make sure the file is at the repo root, not a subdirectory, and that you launched claude from the root. The agent reads CLAUDE.md from cwd and walks up to find a git root.

Hooks not firing — JSON syntax error in .claude/settings.json. Run claude /config to validate the file, or jq . .claude/settings.json to pretty-print and catch missing commas.

Slow first response — first call after install loads the full system prompt and MCP server manifests. Subsequent calls in the same session reuse the cached prefix. If it stays slow, you have too many MCP servers enabled — disable the ones you don't use this session with /mcp disable <name>.

If you're past these and still stuck, the official issue tracker on GitHub is well-maintained and the team responds quickly.

---

Setting up Claude Code well takes about thirty minutes and pays for itself in the first day. The hard part is not the install — it is keeping the configuration honest as your project grows, your team adopts the tool, and the agent's capabilities expand. That is the work that turns "I tried Claude Code" into "we ship with Claude Code." If your team wants help going from a working install to a production setup with sub-agents, MCP servers, and CI integration tuned to your codebase, AY Automate builds and ships Claude Code workflows for engineering teams every week. Book a free consultation and we'll walk through your current setup, what's missing, and what to build first.

FAQ

Do I need an Anthropic API key if I have Claude Pro?

No. Claude Pro and Max subscriptions cover Claude Code usage directly — sign in with claude login and your sessions count against your subscription's limits instead of metered API billing. For most solo developers, Pro is the cheaper path.

Can I use Claude Code without Node.js?

Yes. Anthropic ships a standalone binary at claude.ai/install.sh (macOS and Linux). It is a single executable, no Node runtime required. The npm install is still the most common path because it auto-updates cleanly, but the binary is a valid choice for containers and locked-down workstations.

Does Claude Code work on Windows?

Officially through WSL2. Native Windows works for casual use but breaks around shell hooks, file watchers, and POSIX-path MCP servers. If you are on Windows in 2026, install Ubuntu via WSL and run Claude Code from there — it is the supported path.

How much does Claude Code cost in 2026?

Two pricing models. Subscription: $20/month (Pro) or $200/month (Max), flat. API: metered per token — heavy users typically spend $50–500/month depending on model choice and prompt size. Bedrock/Vertex bills through your cloud account at similar rates. Switch with /model to control cost mid-session.

What is the difference between CLAUDE.md and a system prompt?

CLAUDE.md is project memory — it loads at every session start from your repo and stays in context. A system prompt is set once at the API level and applies to all conversations. For Claude Code specifically, you write CLAUDE.md, you do not write a system prompt. The CLI handles the system prompt for you.

Should I commit .claude/ to git?

Yes for settings.json, agents/, and any project-level MCP config. No for transient files (sessions, caches) — those go in .gitignore. Sharing .claude/ is how your team gets the same defaults, sub-agents, and hooks without each developer setting it up manually.

Can I run multiple Claude Code sessions at once?

Yes. Each terminal window is an independent session. Sub-agents run in their own context inside a session. Many teams run two or three sessions in parallel — one for the main feature, one for tests, one for docs — and tile them in their terminal multiplexer.

How do I update Claude Code?

npm update -g @anthropic-ai/claude-code for the npm install, or re-run the install script for the standalone binary. Anthropic ships updates roughly weekly in 2026 — the CLI will tell you on launch if there is a new version. Auto-update is on by default; turn it off in settings.json with "autoUpdate": false if you need version-pinned environments.