Claude Code Guide

Claude Code is Anthropic's official CLI for Claude — a terminal-based coding agent that reads your project, makes multi-file edits, runs commands, and manages git.

Setup

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

# macOS (Homebrew)
brew install --cask claude-code

# Windows (PowerShell)
irm https://claude.ai/install.ps1 | iex

# Windows (WinGet)
winget install Anthropic.ClaudeCode

cd your-project
claude

See the official install docs for the latest canonical instructions.

Key Files

CLAUDE.md

The most important file for Claude Code. Place at your project root. It tells Claude about your project structure, conventions, and commands.

# My Project

## Commands

pnpm dev # Start dev server
pnpm test # Run tests
pnpm lint # Lint code

## Code Style

- TypeScript strict, no `any`
- Named exports, no barrel files
- Server Components by default

## Architecture

src/app/ # Next.js App Router
src/lib/ # Utilities
src/db/ # Database layer

Keep it under 200 lines. Every line competes for attention. See CLAUDE.md Best Practices for details.

.claude/settings.json

Project-level permissions and hooks:

{
  "permissions": {
    "allow": ["Bash(pnpm *)"],
    "deny": ["Bash(rm -rf *)"]
  }
}

Per-directory scoping

Drop a CLAUDE.md inside any subdirectory (e.g. src/api/CLAUDE.md) and Claude Code loads it automatically when working in that subtree. Combine a root CLAUDE.md with subdirectory ones for a layered memory hierarchy — the root defines project-wide rules, the subdirectory adds local context.

Personal overrides live in CLAUDE.local.md (gitignored). User-level memory lives in ~/.claude/CLAUDE.md and applies across every project.

MCP Integration

Claude Code supports MCP servers for extended capabilities:

// .mcp.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

Note: several 2024-era reference servers (Postgres, Slack, Sentry, GitHub, Puppeteer, SQLite, Redis, Google Drive, Brave Search) have been moved to modelcontextprotocol/servers-archived. Use community-maintained forks or the first-party replacements (Vercel MCP, GitHub Copilot MCP, etc.) instead.

Tips

• Use /init to auto-generate a CLAUDE.md from your codebase
• Use pnpm test -- path/to/file to run single test files (faster feedback)
• Add hooks in .claude/settings.json to auto-format code after edits
• Use background agents for long-running tasks (builds, migrations)
• The @file syntax in CLAUDE.md imports content from other files

Beyond CLAUDE.md

Claude Code has grown well past the CLAUDE.md + settings.json + MCP triad. Features to know:

• Skills — capabilities authored as markdown under .claude/skills/*/SKILL.md. Invoke with /skill-name in chat.
• Hooks — shell commands that fire on PreToolUse, PostToolUse, SessionStart, etc. Configured in .claude/settings.json.
• Sub-agents — delegate focused subtasks to specialized agents; parent tracks results.
• Agent SDK — the same agent loop as a library. npm install @anthropic-ai/claude-agent-sdk (TS) or pip install claude-agent-sdk (Python). Ideal for CI/CD and production automation.
• Slash commands — custom /commands from .claude/commands/*.md.
• Plugins — bundle skills, commands, agents, and MCP servers into installable packages.

Surfaces

Claude Code runs as: Terminal CLI, VS Code extension, JetBrains plugin, Desktop app (macOS / Windows), and Web app at claude.ai/code. Workflows translate between all five.