name: claude-code description: Comprehensive reference for Claude Code — the agentic CLI coding tool by Anthropic. Use when helping with installation, CLI usage, CLAUDE.md configuration, settings.json, permissions, MCP server setup, hooks, subagents, session management, or troubleshooting Claude Code issues. Also use when the user asks how to use or configure Claude Code, automate workflows with it, or when answering questions about Claude Code features and best practices.

Claude Code Reference

Claude Code is an agentic coding tool that reads your codebase, edits files, and runs commands. It works in terminal, VS Code/JetBrains IDEs, desktop app, web, and CI/CD.

Installation

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

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

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

# WinGet
winget install Anthropic.ClaudeCode

Start in any project: cd your-project && claude

Login on first use with /login. Supports Claude.ai accounts, Console API key, and cloud providers (Bedrock, Vertex AI, Azure Foundry).

Core CLI Commands

| Command | Description | |---------|-------------| | claude | Start interactive REPL | | claude "task" | Start REPL with initial prompt | | claude -p "query" | Non-interactive (print mode), then exit | | cat file \| claude -p "query" | Process piped input | | claude -c | Continue most recent conversation | | claude -r [session] | Resume session by name/ID or show picker | | claude --from-pr 123 | Resume session linked to PR | | claude update | Update to latest version | | claude mcp | Configure MCP servers | | claude --remote "task" | Create new web session on claude.ai | | claude --teleport | Resume a web session locally | | claude commit | Create a Git commit |

Essential CLI Flags

| Flag | Description | |------|-------------| | --print, -p | Non-interactive print mode | | --continue, -c | Load most recent conversation | | --resume, -r | Resume session by ID/name | | --model | Set model (sonnet/opus/haiku or full name) | | --permission-mode | Start in plan/acceptEdits/dontAsk/bypassPermissions | | --dangerously-skip-permissions | Skip all permission prompts (use with caution) | | --output-format | text/json/stream-json (print mode only) | | --max-turns N | Limit agentic turns (print mode) | | --max-budget-usd N | Spending cap (print mode) | | --system-prompt | Replace entire system prompt | | --append-system-prompt | Add to default system prompt | | --add-dir PATH | Add extra working directories | | --allowedTools | Tools that run without prompting | | --disallowedTools | Tools to block | | --tools | Restrict to specific built-in tools | | --mcp-config FILE | Load MCP servers from JSON file | | --verbose | Enable verbose logging | | --debug | Debug mode with category filter | | --agents JSON | Define custom subagents for this session | | --agent NAME | Specify agent for session | | --fork-session | Create new session ID when resuming | | -v, --version | Show version |

See references/cli-flags.md for complete flag reference.

CLAUDE.md Memory Files

Claude loads these files at startup as persistent context/instructions.

| Location | Scope | |----------|-------| | /Library/Application Support/ClaudeCode/CLAUDE.md | Organization-wide (managed) | | ~/.claude/CLAUDE.md | All your projects (user) | | ./CLAUDE.md or ./.claude/CLAUDE.md | Project team (commit to git) | | ./CLAUDE.local.md | Your personal project overrides (gitignored) | | ./.claude/rules/*.md | Modular topic-specific rules |

Bootstrap: /init — auto-generates a CLAUDE.md from your codebase.

Imports: Use @path/to/file syntax to import other files:

See @README.md for overview. Git workflow: @docs/git-instructions.md

Path-specific rules (YAML frontmatter in .claude/rules/):

---
paths:
  - "src/api/**/*.ts"
---
# API Rules
- All endpoints must include input validation

Auto memory: Claude automatically saves learnings to ~/.claude/projects/<project>/memory/MEMORY.md. Manage via /memory. First 200 lines loaded each session.

See references/memory-guide.md for full memory system details.

Settings Files

| File | Scope | |------|-------| | ~/.claude/settings.json | User (all projects) | | .claude/settings.json | Project (committed) | | .claude/settings.local.json | Local project (gitignored) | | ~/.claude.json | Global state (OAuth, MCP servers) | | .mcp.json | Project MCP servers (committed) | | Managed: /Library/Application Support/ClaudeCode/managed-settings.json | Org-wide (macOS) |

Minimal example:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": ["Bash(npm run lint)", "Bash(npm run test *)"],
    "deny": ["Read(./.env)", "Read(./secrets/**)"]
  }
}

Key settings keys: model, permissions, env, hooks, language, cleanupPeriodDays, companyAnnouncements, attribution, sandbox, outputStyle, statusLine, alwaysThinkingEnabled, autoUpdatesChannel

See references/settings-reference.md for all settings keys and environment variables.

Permissions

Permission modes (set with --permission-mode or defaultMode in settings):

• default — prompts on first use
• acceptEdits — auto-accept file edits
• plan — read-only analysis only
• dontAsk — auto-deny unless pre-approved
• bypassPermissions — skip all prompts

Rule syntax in permissions.allow/ask/deny: | Rule | Matches | |------|---------| | Bash | All bash commands | | Bash(npm run *) | Commands starting with npm run | | Bash(git commit *) | Commands starting with git commit | | Read(./.env) | Reading .env file | | WebFetch(domain:example.com) | Fetches to example.com | | mcp__puppeteer__* | All puppeteer MCP tools | | Task(Explore) | Explore subagent |

Deny rules always take precedence over ask and allow.

See references/permissions-guide.md for full rule syntax and tool-specific patterns.

MCP (Model Context Protocol)

# Add remote HTTP server (recommended)
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Add remote SSE server
claude mcp add --transport sse asana https://mcp.asana.com/sse

# Add local stdio server
claude mcp add --env AIRTABLE_API_KEY=key airtable -- npx -y airtable-mcp-server

# Scopes: local (default), project, user
claude mcp add --scope project --transport http github https://api.githubcopilot.com/mcp/

# Manage
claude mcp list
claude mcp get github
claude mcp remove github

# Use Claude Code itself as MCP server
claude mcp serve

Common servers: github, sentry, notion, asana, slack, figma, postgresql

See references/mcp-guide.md for full MCP configuration, scopes, auth, and managed setup.

Interactive Mode — Slash Commands

| Command | Purpose | |---------|---------| | /help | Show commands | | /clear | Clear conversation history | | /compact [focus] | Compact history with optional instructions | | /config | Open settings interface | | /context | Visualize context window usage | | /cost | Show token usage stats | | /doctor | Check installation health | | /export [file] | Export conversation | | /init | Initialize CLAUDE.md for project | | /mcp | Manage MCP connections | | /memory | Edit CLAUDE.md files | | /model | Select or change model | | /permissions | View/update tool permissions | | /plan | Enter plan mode | | /rename NAME | Name current session | | /resume [session] | Resume conversation | | /rewind | Restore previous code/conversation state | | /stats | Usage stats and session history | | /vim | Enable vim editing mode | | ! command | Run bash directly (adds output to context) | | @path | Reference a file |

Key Keyboard Shortcuts

| Shortcut | Action | |----------|--------| | Ctrl+C | Cancel current operation | | Esc | Stop Claude mid-action | | Esc + Esc | Open rewind menu | | Shift+Tab | Cycle permission modes (Normal → AutoAccept → Plan) | | Ctrl+O | Toggle verbose output | | Ctrl+B | Background current bash task | | Ctrl+T | Toggle task list | | Ctrl+R | Reverse search history | | Option+T / Alt+T | Toggle extended thinking | | Option+P / Alt+P | Switch model |

Subagents

Custom subagent file (.claude/agents/name.md or ~/.claude/agents/name.md):

---
name: code-reviewer
description: Reviews code for quality and security. Use proactively after changes.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer. Focus on quality, security, and best practices.
Provide prioritized feedback: Critical → Warnings → Suggestions.

Built-ins: Explore (fast read-only), Plan (planning research), general-purpose

CLI subagents (session-only):

claude --agents '{"reviewer": {"description": "...", "prompt": "...", "tools": ["Read"]}}'

See references/sub-agents-guide.md for full configuration and patterns.

Hooks

Auto-run scripts at lifecycle events. Configure in .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{"type": "command", "command": "./scripts/lint.sh"}]
    }],
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{"type": "command", "command": "./scripts/security-check.sh"}]
    }]
  }
}

Events: SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Stop, SubagentStart, SubagentStop, PreCompact, SessionEnd

Hook scripts receive JSON via stdin and control flow via exit codes: 0 = allow, 2 = block, other = non-blocking error.

See references/hooks-guide.md for full events, input schemas, and output formats.

Best Practices

1. Explore → Plan → Code: Use Plan Mode (Shift+Tab) before implementing complex changes
2. Provide verification criteria: Give Claude tests/scripts/screenshots to verify work
3. Write an effective CLAUDE.md: Short, specific, no obvious info. /init to bootstrap
4. Use /clear between unrelated tasks to keep context clean
5. Use subagents for exploration — prevents main context from filling up
6. Add @file references instead of describing where code lives
7. Give specific context: file paths, constraints, example patterns
8. After 2 failed corrections: /clear and start fresh with better prompt
9. Use --permission-mode plan for safe analysis of unfamiliar code
10. Headless mode for automation: claude -p "task" --output-format json

Troubleshooting Quick Fixes

| Problem | Fix | |---------|-----| | Auth issues | /logout then restart claude | | Slow/incomplete search on WSL | Move project to Linux filesystem or use more specific searches | | Search not working | brew install ripgrep + set USE_BUILTIN_RIPGREP=0 | | Repeated permission prompts | Use /permissions to allowlist safe commands | | High CPU/memory | /compact regularly, restart between major tasks | | Claude ignoring CLAUDE.md rules | File is too long — prune it | | Node not found (WSL) | Install Node via Linux package manager or nvm | | JetBrains IDE not detected (WSL2) | Configure Windows Firewall or switch to mirrored networking | | MCP server not found | Check /mcp status, verify server config | | Reset to defaults | rm -rf ~/.claude/ ~/.claude.json |

Run /doctor for automated health checks (installation, settings, MCP, plugins, context warnings).

Configuration File Locations Reference

| File | Purpose | |------|---------| | ~/.claude/settings.json | User settings | | .claude/settings.json | Project settings (committed) | | .claude/settings.local.json | Local project settings | | ~/.claude.json | Global state (theme, OAuth, MCP) | | .mcp.json | Project MCP servers | | ~/.claude/CLAUDE.md | User memory | | ./CLAUDE.md | Project memory | | ~/.claude/agents/ | User subagents | | .claude/agents/ | Project subagents | | ~/.claude/projects/<project>/memory/ | Auto memory |

References

• references/cli-flags.md — Complete CLI flags and environment variables
• references/settings-reference.md — All settings.json keys and environment variables
• references/memory-guide.md — CLAUDE.md, auto memory, modular rules
• references/permissions-guide.md — Permission system, modes, rule syntax
• references/mcp-guide.md — MCP setup, scopes, auth, managed config
• references/hooks-guide.md — Hooks events, input/output schemas
• references/sub-agents-guide.md — Subagent creation, config, patterns
• references/best-practices.md — Extended best practices and workflows