How to Set Up Claude Code: The Complete Guide (2026)

What Is Claude Code (and What Makes It Different)

Claude Code shipped in February 2025 as a research preview and went generally available in early 2026. It is Anthropic's answer to GitHub Copilot, Cursor, and Windsurf -- but with a different philosophy. Those tools are primarily autocomplete and inline suggestion engines. Claude Code is an autonomous agent that takes a task description and works through it end-to-end.

The difference matters. With an inline suggestion tool, you are still the driver -- it fills in the next line. With Claude Code, you describe a goal and it navigates the codebase, identifies what needs to change, makes the changes, runs the tests, and reports back. You review the output, give feedback, and iterate.

Installation

Three ways to install. Pick the one that matches how you work.

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

# Verify install
claude --version

brew install claude-code

First Run and Authentication

Run claude in your terminal. First launch triggers authentication. You have two options:

# Add to ~/.zshrc or ~/.bashrc
export ANTHROPIC_API_KEY="sk-ant-..."

# Reload and verify
source ~/.zshrc
claude --version

After authentication, Claude Code drops you into an interactive session. You will see a > prompt. Type a message and hit enter. That is the full interface -- everything else is configuration and skill.

CLAUDE.md -- The Feature That Changes Everything

CLAUDE.md is a plain Markdown file that Claude Code reads automatically at the start of every session. It is the single most important thing to set up correctly because it is how you give the agent persistent context -- things it needs to know about your project that you do not want to re-explain every time.

Claude Code looks for CLAUDE.md files in three places, in order:

1. ~/.claude/CLAUDE.md -- your global instructions, loaded in every project
2. ./CLAUDE.md -- project-level instructions in the current working directory
3. Subdirectory CLAUDE.md files -- loaded when the agent enters that directory

What to put in your global CLAUDE.md

Your global file should contain preferences that apply to every project -- your name, communication style, tools you always use, and behaviors you always want (or never want).

# ~/.claude/CLAUDE.md

## Who I Am
- Name: Alex
- I'm a senior fullstack engineer
- Preferred stack: TypeScript, React, Postgres, Node.js

## How I Work
- Always write tests alongside implementation
- Prefer explicit over implicit -- no magic
- Use conventional commits (feat:, fix:, chore:)
- Never use --force on git operations without asking

## Tools Available
- gh (GitHub CLI) is installed and authenticated
- pnpm is my package manager, not npm
- I use zsh, not bash

## Hard Rules
- Never commit .env files
- Never rm -rf without confirmation
- Ask before making API calls that cost money

What to put in your project CLAUDE.md

Project-level CLAUDE.md should cover everything specific to this codebase. Think of it as onboarding documentation for a new developer -- except the new developer can read 10,000 lines of Markdown in under a second.

# CLAUDE.md -- my-saas-app

## Project Overview
SaaS app for invoice management. Multi-tenant Postgres,
React frontend, Node/Express API, deployed on Railway.

## Architecture
- /apps/web -- React frontend (Vite, React Router v7)
- /apps/api -- Express API server
- /packages/db -- Prisma schema and migrations
- /packages/shared -- shared TypeScript types

## Key Commands
- pnpm test -- run all tests (vitest)
- pnpm lint -- ESLint + TypeScript check
- pnpm dev -- start dev servers (Turbo)
- pnpm db:migrate -- run pending migrations
- pnpm db:studio -- open Prisma Studio

## Database
- Local: postgresql://localhost:5432/myapp_dev
- Migrations in /packages/db/prisma/migrations
- Run migrations before testing any DB changes

## What to Avoid
- Never touch /apps/web/src/legacy -- deprecated, leaving for now
- Don't run pnpm db:reset -- will wipe local data
- Auth is handled by Clerk -- don't add custom auth logic

## Testing Conventions
- Unit tests: co-located with source files (*.test.ts)
- Integration tests: /tests/integration
- Always mock Stripe API calls in tests

Essential Settings -- Model, Permissions, Effort

Model selection

Claude Code supports multiple Claude models. Use /model inside a session to switch. Your options in 2026:

Permission levels

Claude Code asks for permission before taking actions that could have side effects -- writing files, running shell commands, installing packages. The default behavior is to ask every time. You can change this.

# Start a session that auto-approves safe actions
claude --dangerously-skip-permissions

# Or use the /permissions command inside a session
# to toggle specific permission categories

Extended thinking

Claude Code supports extended thinking -- a mode where the model spends extra tokens reasoning through a problem before responding. Use /think or /think harder to enable it for the next task. Extended thinking is genuinely useful for architectural decisions and debugging complex problems, but it costs significantly more -- use it selectively.

Your First Real Task

Do not start with "hello world." That tells you nothing useful about how Claude Code performs on your actual work. Start with something meaningful -- a task you were going to do anyway.

What makes a good first task

How to write a good task description

The quality of Claude Code's output is directly proportional to the quality of your task description. A vague prompt gets a vague result.

Key Concepts: Tools, Context, and Cost

How tools work

Claude Code has a set of built-in tools it can call during a session -- Read, Write, Edit, Bash, Glob, Grep, and others. When you give it a task, it decides which tools to use and in what order. You will see it call tools in the session output, which is how you can follow what it is actually doing.

You can extend the built-in tools with MCP servers -- adding GitHub, Slack, databases, browsers, or any custom integration. More on that in a later guide.

Context window

Claude Code has a context window -- a limit on how much information it can hold in a single session. For Claude Sonnet 4.5, this is 200,000 tokens. Each file it reads, each command it runs, each message in the conversation consumes context.

For most tasks this is not a problem. It becomes relevant when you are asking it to work across a large codebase. The agent is smart about reading only relevant files, but if you have it ingest 50 large files, you will hit limits. The fix is better task scoping and a good CLAUDE.md that tells it which files matter for each type of work.

Use /compact to compress the session history when you are deep in a long session and starting to feel the context limit. It summarizes earlier turns to free up room.

Cost awareness

Claude Code shows you token usage after each exchange. Pay attention to it. A typical focused 30-minute session on a medium-sized task costs $1-3 with Sonnet. A sprawling session where you throw everything at it can cost $10-20.

Common Mistakes (and How to Avoid Them)

These are the mistakes we see everyone make in the first week, including ourselves.

What to Learn Next

This guide covered the foundation -- installation, auth, CLAUDE.md, model selection, and your first task. Once you have the basics running, here is where the real leverage comes from:

All of these are covered in depth in the KaiShips Guide to Claude Code, along with real examples from production setups, annotated CLAUDE.md templates, and the workflows we use daily.

Frequently Asked Questions