Claude Code: The Complete Guide

01 What is Claude Code?

According to Anthropic's official documentation, Claude Code represents a paradigm shift in how developers interact with AI assistants. Unlike web-based chatbots, Claude Code operates within your actual development environment, understanding your codebase context and executing real actions.

Claude Code in the Claude Desktop App

Anthropic's docs say: "In the Claude Desktop app, Claude Code is the Code tab. The app also has chat and Cowork, which handles Dispatch and longer agentic work." (Desktop docs). The desktop app includes Claude Code, so the Code tab needs no separate CLI install, but a paid subscription is required. Computer use is a research preview on macOS and Windows that requires a Pro, Max, or Ultra plan, and it is not available on Team or Enterprise plans. Section 2 has the download links and section 9 covers the Code tab itself.

Why Claude Code Matters

Traditional AI coding assistants require you to copy-paste code snippets back and forth. Claude Code eliminates this friction by:

• Direct File Access: Read, write, and edit files in your project without manual copying
• Git Integration: Create commits, branches, and pull requests directly
• Terminal Execution: Run commands, tests, and build scripts
• Context Awareness: Understand your entire codebase structure
• Extensibility: Connect to external tools via MCP servers

Claude Code vs Other AI Assistants

02 Installation & Setup

According to the Claude Code getting started guide, the recommended installation method is using the native binary installer, which provides the most stable experience.

System Requirements

Installation Methods

macOS / Linux / WSL (Recommended)

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

Windows PowerShell

irm https://claude.ai/install.ps1 | iex

Windows CMD

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Alternative Methods

On Debian, Fedora, RHEL and Alpine you can also install with apt, dnf or apk (see the Linux package manager steps).

Prefer No Terminal? The Desktop App

Download the Claude desktop app for macOS (Intel and Apple Silicon), Windows x64 or Windows ARM64. On Ubuntu or Debian the app is in beta and installs with apt (Linux instructions). Launch Claude, sign in, and click the Code tab. The desktop quickstart says you do not need to install Node.js or the CLI to use the Code tab.

Authentication Setup

After installation, run claude to start the authentication process. Claude Code supports multiple authentication methods:

Verify Installation

# Check installation
claude doctor

# Start Claude Code
claude

# Start with initial prompt
claude "explain this codebase"

# Resume last conversation
claude -c

Configuration Files

03 Core Features & Commands

Claude Code provides a rich set of slash commands that enable powerful interactions. Here are the essential commands every user should know.

Essential Slash Commands

The Claude 5 Model Family & Effort Levels

Claude Code runs on the Claude 5 model family. Use /model to switch between them, or pass --model on the command line. Anthropic's models overview lists these four as the current models on 9 November 2026:

Haiku 5.5 is priced by prompt length: prompts over 100,000 tokens pay the higher rates (see Anthropic's pricing page). Per the model configuration docs, default is Opus 5.5 on Pro, Max, Ultra, Team, Enterprise and the Anthropic API, and "No Fable model is the account-type default on any plan or provider." Older models such as Fable 5.1, Opus 5, Sonnet 5 and Haiku 4.5 are listed as legacy models that are still available. Claude Platform on AWS, Amazon Bedrock, Google Cloud's Agent Platform and Microsoft Foundry can map sonnet and haiku to different versions, so check the alias table for your provider.

Additional model aliases include default, best (the same model as opus), opus[1m], sonnet[1m] (long-context variants; no effect when the alias already resolves to a model with the native 1M window), and opusplan (Opus during plan mode, then Sonnet for execution).

Keyboard Shortcuts

File References with @

Use the @ symbol to reference files directly in your prompts:

# Reference specific files
> Analyze @src/auth.ts and suggest improvements

# Compare multiple files
> Compare @package.json with @package-lock.json

# Reference directories
> Explain the architecture in @src/components/

# Reference with line ranges (VS Code)
> Fix the bug in @src/utils.ts:42-58

Checkpointing & Recovery

Claude Code automatically tracks file edits, allowing you to undo changes. Access the checkpointing feature by pressing Escape twice or using /rewind.

04 File Operations

Claude Code provides specialized tools for file operations that are more reliable than bash commands. Understanding these tools helps you work more effectively.

Built-in File Tools

When to Use Each Tool

Example Workflows

# Find all TypeScript files
> Find all .ts files in the src directory

# Search for function definitions
> Search for "function authenticate" in the codebase

# Read and analyze a file
> Read @src/auth/login.ts and explain the authentication flow

# Create a new component
> Create a new React component called UserProfile in src/components/

05 MCP (Model Context Protocol)

The Model Context Protocol (MCP) is an open standard introduced by Anthropic that allows Claude Code to connect to external tools, databases, and APIs without custom integrations.

What is MCP?

MCP Transport Types

Adding MCP Servers

HTTP Server (Recommended)

# Add Notion integration
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Add GitHub integration
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# Add Sentry integration
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Local Stdio Server

# Add PostgreSQL database
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub --dsn "postgresql://user:pass@host/db"

# Add Airtable
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable -- npx -y airtable-mcp-server

Managing MCP Servers

MCP Installation Scopes

Popular MCP Integrations

06 Agents & Subagents

According to Anthropic's subagents documentation, subagents are specialized AI assistants that operate independently for specific tasks, enabling parallel execution and isolated context management.

What Are Subagents?

Built-in Subagent Types

The Agent Tool

The Agent tool is how Claude delegates work to subagents (it was named the Task tool before version 2.1.63, and existing Task(...) references still work as aliases). It can run multiple agents in parallel for operations like:

• File reads: Reading multiple files in parallel
• Code searches: Searching different patterns simultaneously
• Web fetches: Gathering information from multiple sources
• Pattern matching: Finding code patterns across the codebase

How Subagents Work

Creating Custom Subagents

You can create custom subagents by placing markdown files (with YAML frontmatter) in the .claude/agents/ directory. The easiest way is to simply ask Claude to create one for you — for example, "create a subagent that reviews SQL queries for performance" — or edit the files in .claude/agents/ directly:

# Create agents directory
mkdir -p .claude/agents

# View available subagents
/agents

# Then ask Claude in plain language:
# "Create a subagent named sql-reviewer that checks queries for performance issues"

Agent Teams, Background Agents & Claude Code Everywhere

Recent releases extend the agent model well beyond single subagents:

• Agent teams: Spin up multiple named agents that collaborate on a larger task, each with its own context, and message them mid-task to course-correct
• Background agents: Long-running tasks can execute in the background while you keep working; you're notified when they finish
• Claude Code on the web and desktop: The same agentic workflows are available in the browser and in the Claude desktop app (the Code tab), in addition to the terminal and IDE integrations

07 Git Workflows

Claude Code has deep Git integration that makes version control seamless. According to the Git workflow documentation, you can manage branches, commits, and pull requests directly through natural language.

Common Git Operations

# Create and switch to a new branch
> Create a branch feature/rate-limiting and switch to it

# Implement a feature
> Implement rate limiting on auth endpoints

# Run tests
> Run the tests

# Commit changes
> Commit these changes

# Push and create PR
> Push and create a PR to main with a summary of changes

Pull Request Creation

Claude Code uses the gh CLI for GitHub operations. When you ask Claude to create a PR, it will:

GitHub Actions Integration

Claude Code can be integrated with GitHub Actions for automated workflows:

# Install GitHub App
/install-github-app

Once installed, you can:

• @claude mentions: Tag Claude in PRs and issues for automated responses
• Automated reviews: Get code review feedback on pull requests
• Bug fixes: Request fixes that Claude implements directly
• Changelog generation: Automatically generate release notes

Git Worktrees for Parallel Work

Git worktrees allow checking out multiple branches in separate directories while sharing Git history. This is useful for parallel development tasks where you need to work on multiple features simultaneously.

Commit Best Practices

Claude Code naturally respects Conventional Commits format:

# Good commit message format
feat: add rate limiting to auth endpoints
fix: resolve memory leak in connection pool
docs: update API documentation
refactor: simplify authentication flow
test: add unit tests for user service

08 Advanced Configuration

Claude Code offers extensive configuration options through settings files, hooks, and custom commands. Understanding these enables powerful automation and team-wide conventions.

Settings Hierarchy

Settings apply in order of precedence (higher overrides lower):

Sample Local Settings (Whitelist MCP & Git)

Here's a sample .claude/settings.local.json file that whitelists MCP tools and common Git operations for uninterrupted workflow:

{
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(git push *)",
      "Bash(git pull *)",
      "Bash(git checkout *)",
      "Bash(git branch *)",
      "Bash(git merge *)",
      "Bash(git log *)",
      "Bash(git diff *)",
      "Bash(gh pr *)",
      "Bash(gh issue *)",
      "Bash(npm *)",
      "Bash(npx *)",
      "Bash(yarn *)",
      "Bash(pnpm *)",
      "mcp__notion__*",
      "mcp__github__*",
      "mcp__postgres__*",
      "mcp__sentry__*"
    ],
    "deny": [
      "Bash(rm -rf /)",
      "Bash(sudo *)",
      "Bash(chmod 777 *)"
    ]
  },
  "enableAllProjectMcpServers": true
}

Hooks

Hooks allow you to run custom commands before or after Claude's tool execution. According to the hooks documentation, available hook events include:

These are the core events — current releases document a much larger set (around 31 events), including HTTP hooks that POST event payloads to a URL instead of running a local command.

Example Hook Configuration

Hook commands receive the event details (including tool input) as JSON on stdin, so use a tool like jq to extract fields. The documented environment variable $CLAUDE_PROJECT_DIR gives you the project root:

{
  "hooks": {
    "SessionStart": [{
      "matcher": "startup",
      "hooks": [{
        "type": "command",
        "command": "echo \"Session started in $CLAUDE_PROJECT_DIR at $(date)\" >> ~/.claude/session.log"
      }]
    }],
    "PostToolUse": [{
      "matcher": "Write",
      "hooks": [{
        "type": "command",
        "command": "jq -r '.tool_input.file_path' | { read -r f; prettier --write \"$f\"; }"
      }]
    }]
  }
}

In the PostToolUse example above, jq reads the JSON payload from stdin, extracts the path of the file Claude just wrote, and runs Prettier on it automatically.

Custom Slash Commands

Create custom slash commands by adding markdown files to .claude/commands/. These still work well, though skills (.claude/skills/, covered below) are now the promoted path for packaged, reusable workflows:

# Create commands directory
mkdir -p .claude/commands

# Create a custom command
echo "Analyze this code for performance issues and suggest optimizations:" > .claude/commands/optimize.md

# Now you can use /optimize in Claude Code

Skills Structure

For more complex custom behaviors, create a skill as a directory inside .claude/skills/ (skills docs):

.claude/skills/
└── <skill-name>/
    ├── SKILL.md      # Main instructions (required)
    ├── templates/    # Templates for Claude to fill
    ├── examples/     # Expected output examples
    └── scripts/      # Executable scripts

Memory Management with CLAUDE.md

CLAUDE.md files provide persistent context that Claude remembers across sessions. The memory system uses a hierarchy:

CLAUDE.md files can also import other files with @path/to/file syntax, letting you keep the main file short and pull in details on demand.

09 IDE Integrations

Claude Code integrates with popular IDEs to provide a seamless development experience. The VS Code extension is the most feature-rich integration.

VS Code Extension

Installation

Key VS Code Features

Permission Modes

Claude Code ships with a set of documented permission modes — press Shift+Tab to cycle through them, or set them via --permission-mode:

Claude Code Desktop App

The desktop app is the graphical way to run Claude Code. Per the desktop docs, "each conversation is a session: it has its own chat history and project folder, independent of any other session. The sidebar lists your sessions and lets you run several in parallel." Click + New in the sidebar or press Cmd+N (macOS) or Ctrl+N (Windows). In a Git repository you can turn on Worktree before you start a session to run it in its own Git worktree, an isolated copy of the project; by default it is off.

• Plan mode: "Claude reads files and runs commands to explore, then proposes a plan without editing your source code." Once you approve the plan, switch to Accept edits or Manual to execute it.
• GitHub and pull requests: review and comment on diffs, then watch the resulting pull request through CI. Turn on Auto-fix or Merge when ready to have Claude fix failing checks or have GitHub merge the pull request. PR monitoring requires the GitHub CLI (gh) to be installed and authenticated.
• Side chat: press Cmd+; (macOS) or Ctrl+; (Windows), or type /btw, to ask a question that uses the session's context without adding anything to the main conversation.

JetBrains Integration

Claude Code supports the entire JetBrains family including IntelliJ IDEA, PyCharm, WebStorm, and more:

CLI to IDE Connection

Connect your terminal Claude session to VS Code:

# Connect to VS Code from external terminal
/ide

10 Best Practices & Tips

Based on Anthropic's best practices guide, here are proven strategies for getting the most out of Claude Code.

Performance Optimization

Cost Management

Subscription Options

Security Best Practices

Sandbox Mode

Enable sandbox mode for enhanced security:

/sandbox

Benefits of sandboxing:

• Filesystem isolation: Access only to specific directories
• Network isolation: Only approved servers can be reached
• Fewer permission prompts: Anthropic reports that "in our internal usage, we've found that sandboxing safely reduces permission prompts by 84%" (Anthropic's sandboxing post); your results will vary
• OS-level security: Uses Linux bubblewrap, macOS Seatbelt (not available on native Windows — use WSL2 for sandboxing)

Security Recommendations

Effective Prompting Tips

Running Claude Uninterrupted (Auto-Accept Mode)

For experienced users who want Claude to work autonomously without confirmation prompts, there are several ways to enable uninterrupted execution:

Method 1: Bypass Permissions (CLI Flag)

# Start Claude with all permission prompts bypassed
claude --dangerously-skip-permissions

# Equivalent documented permission mode
claude --permission-mode bypassPermissions

Method 2: Allowlist Specific Commands

A safer approach is to pre-approve specific commands in your settings file:

// .claude/settings.local.json
{
  "permissions": {
    "allow": [
      "Bash(git *)",
      "Bash(npm run *)",
      "Bash(npx *)",
      "Read",
      "Write",
      "Edit",
      "Glob",
      "Grep"
    ]
  }
}

Method 3: VS Code Auto-Accept Mode

In the VS Code extension, you can enable auto-accept mode from the settings:

Method 4: Headless Mode for CI/CD

For automation pipelines, use headless mode with streaming output:

# Run Claude in headless mode (non-interactive)
claude -p "run tests and fix any failures" --output-format stream-json

# With permissions bypassed for full automation
claude -p "refactor auth module" --permission-mode bypassPermissions --output-format json

11 Frequently Asked Questions

12 Abbreviations & Glossary