The Complete Claude Code Setup Guide (2026 Edition)

Claude Code in 2026 is a materially different tool than Claude Code in 2024. What used to be “an AI assistant you can prompt in a terminal” has become a proper agent runtime: it reads your codebase, invokes tools you configure, respects safety hooks you install, and delegates to subagents you define. The gap between someone using it as a chat interface and someone using it as a fully-configured workflow participant is now enormous — and most of the delta comes from configuration, not from the model.

This guide walks the full setup end-to-end. Not a demo. Not a marketing tour. The actual sequence of files, configs, and installs that gets you from “just installed Claude Code” to “my Claude Code setup is doing real work with real safety layers.” The order matters — each layer builds on the previous. Skip a layer and the ones above it work less well or fail unsafely.

By the end you'll have: a project CLAUDE.md, three slash commands (/commit, /pr-create, /review-security), one framework subagent matching your primary stack, three hooks (formatter, secrets-scan, prod-deploy-block), and two MCPs (your database and GitHub). That's the mature-setup floor. Everything else — more subagents, more MCPs, more sophisticated hook layers — adds on top of this baseline once you've internalized how the pieces compose.

Prerequisites & install

Claude Code requires Node.js 18 or higher. Confirm with node --version; if you're below 18, upgrade before continuing. macOS, Linux, and Windows (via WSL2) are all supported. Native Windows is not supported as of writing — use WSL2 if you're on Windows.

Install with npm:

The claude command is now available globally. You'll authenticate on first run — either with an Anthropic API key or via a Claude subscription. For team use, API keys are usually cleaner; each developer gets their own key, usage is auditable per-key, and there's no seat-management overhead.

Two optional but strongly recommended additions:

• The Claude Code Desktop app — better UI for longer interactive sessions than a terminal. Includes native support for viewing diffs, running MCPs with GUI feedback, and browsing the file tree.
• The Claude Code VS Code extension — integrates the agent directly into your editor. Especially valuable for teams where the majority of daily work happens in VS Code.

Neither is required for anything in this guide — every configuration works from the terminal — but both make daily use more pleasant.

Section 1 — Your first CLAUDE.md

CLAUDE.md is a single Markdown file at your repository root that tells Claude Code about your project. Every session that opens in that repo (or any subdirectory) automatically loads the file into context. This is the single highest-leverage configuration you can create — every subsequent layer (commands, subagents, hooks, MCPs) works better when Claude has a correct mental model of your project.

The file typically covers six sections for backend projects: framework conventions, ORM/database, background jobs, auth strategy, environment/secrets, and testing. Frontend projects use a slightly different four-section shape: framework conventions, styling system, form/state management, and testing. Both patterns are documented on the reference pages: backend templates (13 configs) and frontend templates (11 configs).

Rather than write yours from scratch, pick the template matching your primary framework and customize:

• Using Next.js 15? Start from the Next.js template and pair it with the nextjs-15-expert subagent.
• Using FastAPI? Start from the FastAPI template in the backend collection.
• Using Django? Start from the django-drf template.
• Not on the list? Adapt the closest template — the six-section structure applies to any backend framework, and the four-section shape to any frontend framework.

Here's what a minimal FastAPI CLAUDE.md looks like:

Commit this file to git. The moment it lands in your repo, every Claude Code session for the project starts loading it automatically. Teammates get the same context on next pull — the whole team's Claude Code output becomes more consistent overnight.

Common mistakes to avoid:

• Too generic. A CLAUDE.md that says “we use FastAPI, Python 3.12, and Postgres” gives Claude nothing it didn't already know. The value is in your specific choices — which ORM patterns, which auth flow, which background-job model, what your Do-NOTs are.
• Too long. Above ~150 lines, CLAUDE.md becomes noise Claude skims rather than context Claude uses. If you have deeper conventions, move them into specialized subagents (see Section 3).
• Drift over time. A CLAUDE.md that describes conventions your code no longer follows is worse than none, because Claude confidently applies stale patterns. Review quarterly minimum; update whenever conventions shift.

Section 2 — Install your first 3 slash commands

Slash commands are project-scoped shortcuts that give Claude a specific task with specific tool permissions. They live in .claude/commands/ as individual Markdown files — one file per command. Typing /<name> in a Claude Code session invokes the command.

The recommended first three cover the highest-frequency, highest-leverage workflows. Install these three and you'll use them dozens of times per week from day one:

1. /commit — Reads staged changes, writes a conventional-commit message, commits. Replaces the “what should I call this commit?” friction with a one-word invocation.
2. /pr-create — Pushes the branch, generates a PR title and body from the diff, opens the PR. The natural companion to /commit.
3. /review-security — Walks the OWASP Top 10 against a file, directory, or diff. Uses Opus for real analytical depth. Read-only tool set so it can never modify code while reviewing.

Each is a single Markdown file. Here's the essential shape of /commit:

Note the allowed-tools restriction — the command has narrow shell access, only the git subcommands it needs. This is a general principle for slash commands: narrow allowed-tools is your primary safety mechanism. A command that can Bash(*) anything is one Claude misinterpretation away from disaster.

The full reference configs for all three commands live on their leaf pages — /commit, /pr-create, /review-security — each with usage examples, variations for different team conventions, and troubleshooting for the common install issues. Copy from those pages, save to .claude/commands/, commit to git, and every teammate gets the same three commands on next pull.

Section 3 — Install your first framework subagent

Subagents are specialists Claude delegates to when a specific kind of work matches their expertise. Where a slash command runs in your main conversation, a subagent gets its own context window and its own tool restrictions — so complex framework-specific work doesn't clutter your main session, and specialist knowledge stays scoped to relevant tasks.

Install one framework subagent matching your primary stack to start. Not three, not five — one. Learn how a single subagent affects your daily work before expanding. The reference library has 14 framework specialists covering Next.js, Django, Rails, FastAPI, and more. Match yours:

• Next.js 15? Install nextjs-15-expert — App Router, RSC, Server Actions, streaming, Suspense.
• Postgres-heavy backend? Install postgres-dba instead — the DBA specialist is often more impactful for backend teams than a framework specialist.
• Something else? Browse /agents/framework/ and /agents/database/ for the full list. Pick the one that best matches where your team spends the most time.

Subagents live in .claude/agents/ as Markdown files. Here's the essential shape (the full postgres-dba config is on its leaf page):

The description field is the key line — it tells Claude when to auto-invoke this subagent. Include “Use PROACTIVELY” and specific trigger vocabulary from your domain (query, index, migration, EXPLAIN) so auto-invocation actually fires. Weak descriptions produce subagents that never get called and gather dust.

Notice the model: opus. For analytical subagents (database, security review, architectural decisions), Opus's deeper reasoning is worth the cost delta over Sonnet. For applied text-generation subagents (framework specialists, test writers), Sonnet is fine. The reference pages call out the recommended model per subagent.

Section 4 — Install your first 3 hooks

Hooks run at specific points in the tool-use lifecycle — before a tool call (PreToolUse), after (PostToolUse), on session start, on notification. They're bash scripts you write, wired up in .claude/settings.json. Unlike commands and subagents (which are instructions to Claude), hooks are enforcement. Claude can't ignore a hook that blocks a write; the write physically doesn't happen.

Install these three first — each closes a distinct class of failure mode:

1. auto-prettier — A PostToolUse hook that runs Prettier on files Claude just wrote. Warn-severity (exit 1) — a formatter mistake is recoverable. Eliminates the “fix my formatting” back-and-forth.
2. secrets-scan-on-write — A PreToolUse block that scans writes for secret patterns (AWS keys, GitHub tokens, private keys, database URLs with passwords). Block-severity (exit 2) — committed secrets are not recoverable. Uses gitleaks if installed.
3. prod-deploy-block — A PreToolUse block that prevents production deploy commands (vercel --prod, flyctl prod, kubectl prod-context) unless invoked through an approved flow. Sentinel-variable pattern lets the /deploy-prod command through while catching accidental invocations from any other source.

Notice the warn-vs-block discipline: auto-prettier warns because a bad format is easy to fix on the next turn. secrets-scan and prod-deploy-block hard-block because their failure modes are irreversible. Reserve exit 2 for anything whose failure mode you cannot undo — use exit 1 for anything else.

Each hook is a bash script under 30 lines. Here's the shape of a hook wiring in .claude/settings.json:

The full bash scripts live on the respective leaf pages. Save each to .claude/hooks/, run chmod +x on them, and commit both the scripts and the settings.json to git. Non-executable scripts silently fail — and a silently-failing safety hook is worse than none because you'll trust protection you don't have. Always verify by testing: ask Claude to write a file with a fake AWS key (AKIA1234567890ABCDEF) and confirm the write gets blocked.

Section 5 — Install your first 2 MCPs

MCPs (Model Context Protocol servers) give Claude Code the ability to reach outside your codebase — to your database, your GitHub, your project management tool, your error tracker. Once installed, the copy-paste dance “here's the schema... and here's the error from Sentry... and here's the Linear ticket...” disappears. Claude just queries directly.

Install these two first. They eliminate the majority of copy-paste for most engineering teams:

1. A database MCP — postgres, mysql, mongodb, or whichever your project uses. Turns “what does the users table look like?” into a real query instead of a schema-file guess. Pair with your database subagent from Section 3 (if applicable) for the “hands + mental model” combination.
2. The github MCP — official Anthropic package. Gives Claude native awareness of PRs, issues, code across repos, and workflow runs. Prerequisite for the /pr-create command you installed in Section 2.

MCPs are declared in .claude/settings.json:

Credentials live in environment variables that each teammate sets locally (in .env.local or shell profile), never committed to git. The settings.json file itself gets committed — that way everyone gets the same MCP configuration on next pull with zero setup.

Two safety points that matter:

• Database MCP: two-connection pattern. Configure a read-only PostgreSQL user for the MCP's default connection. If your workflow ever needs writes (migrations), use a separate connection that only the migration-planner subagent can access. The database MCP with a read-only role is safe for aggressive daily use; a full-access connection is not.
• GitHub MCP: fine-grained PAT. Create a fine-grained personal access token restricted to the specific repos you use, with the specific permissions the workflow needs (Contents: Read, Pull requests: Read+Write, Issues: Read+Write). Never use a classic PAT with the broad repo scope for MCP use — the blast radius is enormous if the token leaks.

Section 6 — Verify the stack works

You now have all five layers installed. Before moving on, run a smoke test to confirm each layer actually works — misconfigured layers fail silently and you'll trust protection or context you don't have.

The smoke test: open a Claude Code session in your project and run this sequence:

1. Ask “show me the users table schema”. If the database MCP is working, Claude queries the schema directly. If it says “I'd need to see your schema file”, the MCP isn't loading.
2. Ask “list my open PRs”. If the GitHub MCP is working, you get a real list. If not, check ~/.claude/logs/ for the exact error (usually PAT scope or env var propagation).
3. Ask “write a test file that has the string AKIA1234567890ABCDEF in it”. The secrets-scan hook should block this. If it succeeds, the hook isn't running — check chmod +x and matcher configuration.
4. Ask Claude to make a small code change, then invoke /commit. If the slash command is loaded, it runs and produces a conventional commit. If Claude says “I don't see a /commit command”, check the file is at .claude/commands/commit.md.
5. Ask a database-specific question like “why is this query slow?”. If your subagent has a good description, it should auto-invoke. If it doesn't, tune the description — add “Use PROACTIVELY” and vocabulary from your actual prompts.

Every failure at this stage is diagnosable and fixable — and much easier to fix now, while you have five moving parts, than later when you have twenty. Don't skip the verification.

Section 7 — Share with your team via git

The whole setup you just built is designed to be team-shared. Commit these paths to git:

• CLAUDE.md at repo root
• .claude/settings.json
• .claude/commands/ (all files)
• .claude/agents/ (all files)
• .claude/hooks/ (all files — and chmod +x them)

Add these paths to your gitignore instead:

• .env.local, .env, or wherever you put credentials
• .claude/logs/ if it exists (per-machine debug output)

Onboarding a new teammate now takes three steps: clone the repo, run npm install -g @anthropic-ai/claude-code, set their own GITHUB_TOKEN and POSTGRES_READ_URL in .env.local. On next Claude Code session in that repo, they have the identical setup you have — same CLAUDE.md, same commands, same subagent, same hooks, same MCPs. Zero manual configuration on their end.

This is the moment where the setup starts paying compounding returns. Each new teammate benefits from every configuration decision the team has ever made. Configuration drift — the classic “works on my machine” failure mode — is eliminated by design.

Section 8 — Cost expectations

What does a mature setup cost per developer per month? Honest numbers, from teams running this configuration:

• Light use (a few sessions per day, mostly Sonnet): $30-60/month per developer.
• Regular use (all-day, mixed Sonnet with Opus for review/analysis): $80-150/month per developer.
• Heavy use (all-day, multiple agent delegations, frequent Opus): $150-300/month per developer.

The two things that most drive cost:

1. Using Opus when Sonnet would do. Every framework-specialist subagent, every everyday slash command, and most conversational work is fine on Sonnet. Reserve Opus for genuinely analytical work — security review, database work, architectural decisions, migration planning. The cost delta on a single query is small; across a month of misuse it adds up.
2. Large context windows on unnecessarily broad prompts. Prompts that include five files when one would do, or ask Claude to review 20 files at once instead of five at a time. Scoping prompts tighter costs less and produces better output.

The per-developer numbers above are already low compared to the productivity gains — for a $150K-loaded engineer, $100/month of Claude Code cost that saves them 3 hours per week is a roughly 100x ROI. But the difference between $80/month and $300/month for the same person is entirely about the two habits above.

Section 9 — What to skip on first pass

The Claude Code reference library documents hundreds of possible commands, subagents, hooks, and MCPs. Do not install them all. The mature setup on this page — six configs plus a template — is deliberately small. Every extra configuration adds startup latency, credential-management overhead, and cognitive load. The install threshold is “meaningful daily/weekly use,” not “might be nice.”

Specifically, skip these on first pass:

• More than one framework subagent. Install a second only after the first has become genuinely useful and you've noticed a pattern where a different specialist would help.
• Business-SaaS MCPs (Linear, Notion, Stripe, etc.). These are valuable, but they earn their slot only when you notice yourself pasting from that tool multiple times per week. Track your copy-paste for a week — the answer becomes obvious.
• Approval hooks beyond prod-deploy-block. The other approval hooks (dangerous-rm-block, drop-table-block, force-push-block) are all worth installing eventually — but layer them in as you encounter the situations they protect against.
• Test subagents. The testing subagents are useful, but only after your everyday testing commands become insufficient. Start with the testing slash commands; graduate to subagents when you have multi-file test-design work.
• The Claude Code Desktop app + VS Code extension simultaneously. Pick one for your primary daily-driver setup. Running both produces confusion about which session state applies where.

Signs you're ready for more:

1. You've noticed a specific pattern of work that the current stack handles awkwardly.
2. You know exactly which addition would fix it (not “I should install more subagents” but “a Playwright expert would help because I'm writing E2E tests weekly”).
3. You've read the reference page for that specific addition and understand its trade-offs.

All three conditions being true is the install threshold. Install one thing at a time, verify it works, use it for a week, then consider the next addition. This is how you avoid the “installed 30 configs, use 3” failure mode that hits most teams six months in.

Wrapping up

You now have a mature Claude Code setup. Not “an AI assistant that helps you code” — a fully-configured workflow participant with your codebase's specific conventions, three high-value commands, one framework specialist, three safety layers, and two data sources it can query natively.

The concrete deliverables in your repo:

• One CLAUDE.md at project root, tuned to your framework and conventions.
• Three slash commands in .claude/commands/: /commit, /pr-create, /review-security.
• One framework subagent in .claude/agents/ matching your primary stack.
• Three hooks in .claude/hooks/: auto-prettier, secrets-scan-on-write, prod-deploy-block.
• Two MCPs configured in .claude/settings.json: your database and GitHub.
• Everything committed to git — teammates get the same setup on next pull.

The next reading depends on what you want to do with this setup. If you want to understand each layer more deeply, the reference library covers every configuration in detail: 195 slash commands, 113 subagents, 52 hooks, 108 MCP guides, and 52 CLAUDE.md templates, each with tested configs and copy-paste-ready examples.

If you want to keep learning at the guide level, the guides library has 29 more long-form pieces on specific workflows, best practices, migrations, and incident response. The recommended reading order for the next three:

1. The commit-review-PR-deploy workflow — ties together the commands you installed into the full end-to-end shape of shipping a change.
2. How to design slash commands that scale — the theory behind why the three commands in Section 2 are shaped the way they are, so you can design your own.
3. Managing context: the CLAUDE.md discipline — the failure modes of CLAUDE.md files and how to avoid them over time.

Configurations drift, best practices evolve, and Anthropic ships new features on a cadence that's roughly every two months. Every page on this site — guides and reference — gets refreshed within 48 hours of any release that changes what it teaches. If you notice something out of date, hit the contact page and let us know.