Claude Code Tutorial 2026: Complete Setup and Workflow Guide

Claude Code is a terminal-native AI coding agent built by Anthropic that plans, edits, and executes multi-step coding tasks autonomously — it’s not a snippet autocomplete tool, it’s a full workflow partner. Install it in under five minutes with npm install -g @anthropic-ai/claude-code, point it at your codebase, and it can read files, edit code, run tests, and commit changes with minimal hand-holding.

Introduction to Claude Code: The AI Coding Agent Revolution

Claude Code is a command-line AI coding agent that uses Anthropic’s Claude models to understand codebases, plan multi-file changes, and execute them autonomously. Unlike GitHub Copilot, which suggests inline completions, Claude Code operates at the task level: you describe what you want, and it reads relevant files, reasons through the problem, writes the code, runs tests, and reports back. By January 2026, 18% of developers worldwide used Claude Code at work — up from roughly 3% in April–June 2025, a 6x increase in under a year. Claude Code reached $1B annualized revenue by November 2025, the fastest such milestone in the AI coding market. It holds the highest satisfaction scores among AI coding tools: 91% CSAT and an NPS of 54. What separates it from autocomplete assistants is its agentic loop — it can chain hundreds of tool calls, recover from errors mid-task, and maintain context across an entire project rather than a single function. For developers who’ve lived in a terminal workflow (vim, tmux, git CLI), Claude Code feels like a native colleague rather than an IDE plugin parachuted into the shell.

Step-by-Step Installation Guide for 2026

Claude Code installs as a global npm package and runs in any terminal where Node.js 18+ is present — macOS, Linux, and Windows WSL are all supported as of 2026. The installation takes under two minutes on a standard internet connection and requires no IDE setup or extension marketplace. Here is the complete installation sequence:

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

# Verify the installation
claude --version

# Launch Claude Code in any project directory
cd ~/my-project
claude

After running claude for the first time, you’ll be prompted to authenticate via browser OAuth or an API key. The CLI creates a ~/.claude/ directory that stores your preferences, memory files, and skill definitions. On macOS and Linux, add the npm global bin to your PATH if it isn’t there already: export PATH="$PATH:$(npm bin -g)". For corporate networks with strict proxies, set HTTPS_PROXY before installing. Claude Code ships with its own bundled Node runtime for subprocess calls, so the only hard dependency is Node 18+ for the initial install itself.

System Requirements

Node.js 18 or higher is required. Git must be installed for commit-related features. An Anthropic API key or Claude.ai Pro/Max subscription is required for model access. No GPU or local model is needed — all inference runs on Anthropic’s servers.

Configuring Your API Key and Environment

Claude Code authenticates using either a Claude.ai subscription (recommended for most developers) or a direct Anthropic API key for teams and CI/CD pipelines. The subscription route uses OAuth and requires no key management; the API key route gives you programmatic control and the ability to run Claude Code in headless mode. To set an API key, export it in your shell profile so it persists across sessions: export ANTHROPIC_API_KEY="sk-ant-...". Claude Code reads this variable at startup and skips the browser auth prompt automatically. For team environments, store the key in a secrets manager (AWS Secrets Manager, Vault, GitHub Actions secrets) and inject it at runtime rather than baking it into shell profiles on shared machines. The CLAUDE_MODEL environment variable lets you pin a specific model version: export CLAUDE_MODEL="claude-opus-4-7" for the most capable reasoning, or claude-haiku-4-5-20251001 for faster, cheaper runs on routine tasks. Cost awareness matters: complex agentic runs on Opus can consume millions of tokens per session, so use /cost inside a session to monitor spend in real time.

Creating Your First CLAUDE.md File (The Most Important Step)

The CLAUDE.md file is Claude Code’s primary project context document — a Markdown file you place at the repository root that tells the agent everything it can’t infer from code alone: stack conventions, testing commands, banned patterns, architectural decisions, and team norms. Every time Claude Code starts a session, it reads CLAUDE.md first and holds that context in its system prompt for the entire conversation. Without CLAUDE.md, Claude Code guesses your conventions; with it, the agent behaves like a senior engineer who already knows the project. A well-written CLAUDE.md typically covers: how to run tests (npm test, pytest -x, go test ./...), the build command, the linting/formatting stack, any directories that are off-limits (generated code, vendor), naming conventions, and any non-obvious architectural constraints. At Anthropic, internal teams report that a 300-word CLAUDE.md reduces back-and-forth prompting by 60% on new tasks. Here is a minimal but effective template:

# Project Context
Stack: Next.js 15, TypeScript, PostgreSQL via Prisma
Tests: `npm test` (Jest + Playwright for E2E)
Lint: `npm run lint` (ESLint + Prettier — fix before committing)
Build: `npm run build`

# Conventions
- Use named exports, not default exports
- All DB queries go through `src/lib/db.ts`
- Never commit .env files

# Architecture
- `src/app/` — Next.js App Router pages
- `src/lib/` — shared utilities and DB layer
- `src/components/` — UI components (shadcn/ui base)

CLAUDE.md also supports nested files: place a CLAUDE.md inside any subdirectory for module-specific context that only applies when Claude Code is working in that subtree.

Understanding Claude Code’s Tools: Read, Edit, Write, Bash, and More

Claude Code operates through a set of typed tools that map directly to development actions — it doesn’t call generic shell commands blindly, it uses purpose-built tools with guardrails. Understanding these tools helps you predict what Claude Code will do and how to prompt it effectively. The core tools are: Read (reads a file with line numbers, used before any edit), Edit (makes precise string replacements in existing files — requires reading first), Write (creates new files or does full rewrites), Bash (executes shell commands — tests, builds, git operations), Glob (finds files matching a pattern like src/**/*.tsx), Grep (searches file content with regex, powered by ripgrep), and Agent (spawns a sub-agent for parallel or isolated work). Each tool call is visible to you in the terminal — Claude Code never acts invisibly. Edit is preferred over Write for existing files because it sends only the diff, preserving unchanged lines and reducing the chance of accidentally deleting content. Bash is the power tool: Claude Code uses it to run your test suite after each edit so it can verify that changes don’t break anything before moving on. The Agent tool enables parallelism: Claude Code can fan out research across multiple files simultaneously and merge the results, dramatically speeding up large codebase analysis.

Setting Up Persistent Memory for Cross-Session Continuity

Claude Code’s memory system solves the “new session amnesia” problem — the fact that every fresh terminal session starts with a blank slate. By writing facts to ~/.claude/projects/<path>/memory/ as Markdown files, Claude Code can recall project-specific context across days, weeks, or team handoffs. The memory system has two layers: user memory (~/.claude/projects/...) stores per-project facts like architectural decisions and team preferences; project memory (committed files like docs/decisions.md) is readable by any team member. Effective memory entries focus on what’s non-obvious from the code: “We use Zod for validation everywhere — never yup or joi”, “The database migration was split in March 2026 for compliance, not refactoring”, “API v2 is deprecated but still in production — don’t remove it”. Bad memory entries repeat what the code already shows. Claude Code reads memory files at session start and treats them as authoritative context. To trigger a memory save during a session, just tell Claude Code: “Remember that X”. It will write the file immediately and confirm. On a project with 3+ developers, commit the CLAUDE.md and any shared memory files to version control so everyone benefits from accumulated context.

Creating Reusable Skills for Common Tasks

Skills are named, reusable procedures stored in ~/.claude/skills/ (or .claude/skills/ for project-level sharing) that Claude Code can invoke with a slash command. They eliminate repetitive prompt engineering: instead of writing “run the tests, check for TypeScript errors, format the code, and then commit” every single time, you define a /pre-commit skill that does all four steps automatically. A skill file is a Markdown document with a YAML frontmatter header and natural-language instructions. Here is a working example:

---
name: pre-commit
description: Run tests, lint, type-check, then commit staged changes
---

1. Run `npm test -- --passWithNoTests`
2. Run `npm run lint:fix`
3. Run `npx tsc --noEmit`
4. If all pass, run `git commit` with a conventional commit message summarizing staged changes
5. If any step fails, report the error and stop

Invoke it by typing /pre-commit inside any Claude Code session. Skills can also accept arguments, branch on conditions, and call other Claude Code tools — making them a lightweight automation layer on top of the agent. Teams that invest one hour defining 5–10 core skills report that day-to-day Claude Code sessions feel dramatically more consistent and less prone to the agent improvising its way through routine operations.

Configuring Automation Hooks for Guardrails

Hooks are shell commands that Claude Code runs automatically at specific lifecycle events — before a tool call, after a tool call, when a session starts, or when it stops. They are configured in .claude/settings.json and execute in the project’s working directory. Hooks are the right mechanism for enforcing guardrails that must never be skipped: running a security scanner before every file write, sending a Slack notification when a session ends, blocking commits to protected branches, or automatically formatting code after every edit. A hook that blocks the agent (exits non-zero) prevents the triggering action from proceeding and shows the exit message to the agent, which then adapts. Here is a typical hooks configuration:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npm run lint:fix -- $CLAUDE_FILE_PATH 2>&1 | head -20" }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "echo 'Session ended at $(date)' >> ~/.claude/session-log.txt" }
        ]
      }
    ]
  }
}

The key insight is that hooks run in the harness, not in Claude Code’s reasoning loop — they are reliable, deterministic guardrails that the agent cannot reason its way around. Use them for anything that must always happen, not for things that should usually happen.

Integrating MCP Servers to Extend Capabilities

MCP (Model Context Protocol) servers extend Claude Code’s built-in toolset with connections to external systems — databases, APIs, SaaS tools, internal services — without writing custom agent code. An MCP server is a lightweight process that exposes typed tools over a local socket; Claude Code discovers and calls them just like its native Read or Bash tools. As of 2026, the MCP ecosystem has hundreds of community servers: GitHub, Slack, Notion, PostgreSQL, Stripe, Linear, and more. To add an MCP server, register it in your Claude Code settings:

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

After restarting Claude Code, the GitHub tools (create_pr, list_issues, merge_branch) appear alongside native tools. The practical value is significant: instead of telling Claude Code to “edit the code and then I’ll manually create a PR,” you can say “fix the bug and open a PR against main with a description of what changed” — and it does both. For enterprise teams, internal MCP servers expose internal APIs (deployment pipelines, monitoring dashboards, internal DBs) so Claude Code becomes a unified interface to your entire infrastructure rather than just a code editor.

Essential Slash Commands Every Developer Should Know

Slash commands are in-session shortcuts for common Claude Code operations — they modify behavior, query state, or trigger specific workflows without breaking your conversational flow. The most useful commands for daily work are: /help (shows available commands and current config), /compact (compresses the conversation to reduce token usage when context is getting long), /plan (enters Plan Mode where Claude Code outlines its approach and waits for approval before executing), /cost (shows token usage and estimated cost for the current session), /model (switches the active model mid-session — useful for switching from Haiku to Opus for a complex task), /clear (resets the conversation without exiting the CLI), and /memory (opens the memory file for the current project). For teams, /review triggers a code review skill if one is defined. /fast toggles Fast Mode on Opus, which uses the same model but with faster output streaming. A habit worth building: run /compact proactively when you’ve completed a major subtask and are about to start a new one. This keeps the active context focused and reduces the chance of Claude Code getting confused by stale information from earlier in the session.

Agentic Workflows vs Traditional Autocomplete

Agentic AI coding means the tool plans and executes multi-step tasks autonomously, including reading files, running commands, verifying results, and recovering from failures — without waiting for human input at each step. Traditional autocomplete tools like early GitHub Copilot predict the next token or line based on the current cursor position; they react to what you type rather than reason about what you want. The practical difference emerges on tasks with more than two steps: adding a new API endpoint with tests, refactoring a module across twenty files, or debugging a flaky test by reading logs and tracing through multiple call stacks. An autocomplete tool suggests code snippets at each step; an agentic tool like Claude Code does the whole task, checks its own work, and reports completion. The tradeoff is control vs. speed: autocomplete keeps the developer in the driver’s seat on every line; agentic tools require trusting the agent to make decisions autonomously, which demands good CLAUDE.md configuration and a habit of using Plan Mode for risky changes. Developers who’ve made the shift report writing 70–80% less boilerplate code, spending more time on architecture, and catching bugs earlier because the agent runs tests automatically.

Claude Code vs GitHub Copilot vs Cursor: 2026 Comparison

Claude Code, GitHub Copilot, and Cursor each target a different part of the developer workflow spectrum — choosing the wrong tool for your working style costs more in friction than it saves in assistance.

GitHub Copilot wins on seamless IDE integration and low friction for line-level suggestions. Cursor wins for developers who want a powerful GUI with good multi-file context. Claude Code wins on complex, multi-step, agentic tasks — especially for backend engineers, DevOps engineers, and anyone who already lives in the terminal. The trend in 2026 is toward using all three: Copilot for autocomplete while typing, Cursor for visual file navigation, and Claude Code for “do this whole thing” tasks.

Advanced Tips: Multi-File Operations and Headless Mode

Multi-file operations are where Claude Code’s architecture pays off — by using Glob to find files and Agent to process them in parallel, it can refactor dozens of files in minutes while a developer reviews the plan. The key is using /plan before any large-scale operation: type /plan rename all Button components from PascalCase to kebab-case filenames, review the list of files Claude Code intends to touch, then approve. Headless mode (claude --print "your task" or claude -p "task") runs Claude Code non-interactively, making it composable with CI/CD pipelines, cron jobs, and scripts. A common pattern is a nightly headless run that checks for deprecated dependencies, opens GitHub issues for anything found, and assigns them to the relevant codeowners — zero human time, full agent execution. For large codebases, use --context to pre-load specific files without scanning the whole repo: claude --context src/api/ "add rate limiting to all endpoints". This reduces token usage and keeps the agent focused on the right subtree.

Cost Management and Performance Optimization

Claude Code cost management starts with model selection: Haiku is roughly 15x cheaper than Opus per million tokens and handles routine tasks (read a file, make a small edit, run tests) equally well. Reserve Opus for complex reasoning tasks: architecture planning, debugging subtle concurrency issues, or tasks that require understanding deep context across many files. The /cost command shows live token usage; set a session budget by checking it after major tasks and switching to /compact or a lighter model if you’re trending high. For teams, use the Anthropic API with usage tiers and set spending alerts in the Anthropic console. Headless mode with Haiku for routine CI tasks can cut costs by 80% vs. using Opus interactively. CLAUDE.md quality directly impacts cost: a well-written CLAUDE.md means fewer back-and-forth clarifying turns, which means fewer tokens per task. An agent that guesses at conventions and gets corrected three times costs 4x more than one that gets it right the first time.

Common Beginner Mistakes and How to Avoid Them

The most common beginner mistake with Claude Code is skipping CLAUDE.md entirely — without it, every session starts with the agent guessing your stack, naming conventions, and test commands, which burns tokens and produces inconsistent results. The second most common mistake is running long agentic tasks without using /plan first: the agent makes reasonable assumptions, but assumptions on a 50-file refactor can cascade into a mess that’s hard to revert. Always use Plan Mode for changes affecting more than 5 files. Third: treating Claude Code like a chatbot and writing conversational prompts instead of task specifications. “Can you maybe look at the auth system and see if there’s anything wrong?” produces wandering exploration; “Read src/auth/middleware.ts, identify why the JWT expiry check fails for tokens issued before March 2026, and fix it” produces a precise result. Fourth: ignoring hook output. Hooks fail silently if you don’t check the terminal; set up a hook that writes failures to a log file so nothing slips through. Fifth: not committing CLAUDE.md to git — this file is team infrastructure, not personal config.

Real-World Use Cases and Success Stories

Claude Code’s highest-value use cases in 2026 cluster around tasks that are time-consuming for humans but well-defined enough for an agent. Database migration scripting: Claude Code reads the ORM models, generates the migration SQL, runs it against a test DB, and verifies the schema matches expectations — a task that takes a senior engineer 45 minutes takes Claude Code 4 minutes. API integration: given an OpenAPI spec and a target framework, Claude Code writes the client, types, error handling, and tests in a single agentic run. Codebase archaeology: “find all places we’re calling the deprecated v1 auth endpoint and replace them with v2” across 200 files — Claude Code does this in under 10 minutes with a full audit log of every change. Incident response: during an outage, developers use Claude Code in headless mode to scan logs, correlate timestamps, and produce a structured incident timeline in seconds. These aren’t cherry-picked demos — they’re the daily workflows of teams that have integrated Claude Code into their development process. The pattern is consistent: tasks with clear inputs, verifiable outputs, and no ambiguity about what “done” means are where Claude Code delivers the most value with the least supervision.

FAQ

Q: Is Claude Code free to use? A: Claude Code requires either a Claude.ai Pro or Max subscription (which includes Claude Code access) or a direct Anthropic API key. There is no free tier. Pro costs $20/month as of 2026; Max costs $100/month with higher rate limits. API key billing is pay-per-token with no monthly minimum.

Q: Does Claude Code work offline or with local models? A: No. Claude Code sends all inference requests to Anthropic’s servers. It does not support local LLM backends (Ollama, LM Studio, etc.) as of April 2026. An internet connection and valid API credentials are required for every session.

Q: How is CLAUDE.md different from a .cursorrules file? A: Both serve as context documents for their respective tools, but CLAUDE.md is richer in scope: it covers shell commands, architecture decisions, memory pointers, and skill definitions, not just coding style rules. CLAUDE.md is also read recursively — subdirectory CLAUDE.md files add module-specific context on top of the root file, which .cursorrules does not support.

Q: Can multiple developers share Claude Code configuration? A: Yes. Commit CLAUDE.md, .claude/settings.json, and .claude/skills/ to version control. Each developer installs Claude Code locally, but they all benefit from the shared context and skills. Personal preferences (API key, preferred model) stay in ~/.claude/ which is not committed.

Q: How do I stop Claude Code from making changes automatically without approval? A: Use /plan to enter Plan Mode, which makes Claude Code describe its intended changes and wait for your approval before executing. You can also configure hooks to require confirmation before any Write or Edit tool call. For highly sensitive codebases, run Claude Code with --permission-mode read-only to allow reads but block all file modifications and shell commands until you explicitly approve each one.