Claude Code Guide

Claude Code Guide

For reference and contributions, visit the official Claude Code documentation

Commands and provider model mappings change quickly; the linked official references remain authoritative.

Section	Status	Other Resources
Getting Started	✅	Claude-Code Docs
Configuration & Environment Variables	✅	Claude-Code via Discord
Commands & Usage	✅	70+ Skills & Agent pack
Interface & Input	✅	Goal Creator SKILL.md
Advanced Features	✅	1,900+ Agent Skills
Automation & Integration	✅	No cost ai resources
Help & Troubleshooting	✅	240+ Mermaid templates
Third-Party Integrations	✅	Discord Communication MCP

---

Contents

Fast paths: Install · Commands · Config · MCP · Agents · Troubleshoot

Area	Start here	Also useful
Getting Started	Quick Start	Initial Setup, System Requirements
Configuration	Environment Variables	Configuration Files
Commands	Slash Commands	Command Line Flags, CLI Quick Reference
Interface	Keyboard Shortcuts	Vim Mode
Advanced Features	Plan Mode, Auto Mode, MCP	Sub Agents, Skills, Hooks
Security	Security & Permissions	Dangerous Mode, Best Practices
Automation	Automation & Scripting	PR Review, Issue Triage
Help	Troubleshooting	Best Practices, Monitoring
Third-Party Integrations	DeepSeek Integration	Provider Setup Examples, Cloud Providers and Gateways

Full content map

• Getting Started

  • Quick Start
  • System Requirements
  • Initial Setup

• Configuration & Environment

  • Environment Variables
  • Global Config Options
  • Configuration Files

• Commands & Usage

  • Slash Command Reference
  • Command Line Flags
  • CLI Quick Reference

• Interface & Input

  • Keyboard Shortcuts
  • Vim Mode
  • Command History

• Advanced Features

  • Thinking Mode
  • Effort Levels
  • Advisor Tool
  • Fast Mode
  • Auto Mode
  • Plan Mode
  • Background Tasks
  • Workflows & Scheduling
  • Cloud Sessions
  • Claude in Chrome
  • Desktop and IDEs
  • Sandbox Mode
  • LSP Tool
  • Sub Agents
  • Agent Teams
  • Skills
  • Plugin System
  • Worktree Isolation
  • Native Installer
  • Authentication CLI
  • Agent Management CLI
  • Remote Control
  • Managed Settings
  • Model Updates
  • Theming & Customization
  • Code Review
  • Insights
  • Artifacts
  • MCP Integration
  • Hooks System

• Security & Permissions

  • Dangerous Mode
  • Security Best Practices

• Automation & Integration

  • Automation & Scripting
  • Auto PR Review
  • Security Review on Every PR
  • Issue Triage

• Help & Troubleshooting

  • Debug Quick Commands
  • Path Temp Fix
  • Windows Path Perm Fix
  • Installation Issues
  • Authentication Issues
  • Permission Issues
  • MCP Issues
  • Repair or Reinstall
  • One-Shot Health Check
  • Useful Paths
  • Best Practices
  • Effective Prompting
  • Performance Tips
  • Monitoring & Alerting
  • Collaboration Best Practices
  • Common Pitfalls to Avoid

• Third-Party Integrations

  • Provider Setup Examples
  • Cloud Providers and Gateways
  • DeepSeek Integration

---

Getting Started

Enable completion alerts: Ghostty, Kitty, and iTerm2 (once its alert settings are on) show desktop notifications by default. Elsewhere, choose Terminal bell under /config → Local notifications, or set "preferredNotifChannel": "terminal_bell" in ~/.claude/settings.json.

Quick Start

[!TIP] Run claude in a project directory to start the interface.

Go to Help & Troubleshooting to fix issues...

Native installer (recommended; no Node.js required)

macOS, Linux, or WSL:

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

Supported package managers (manual updates by default):

brew install --cask claude-code          # stable channel; claude-code@latest tracks latest
winget install Anthropic.ClaudeCode

npm distribution (supported; Node.js 22+ is required to install):

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

[!Warning] npm 12 skips Claude Code's postinstall step by default, leaving a placeholder claude that prints Error: claude native binary not installed. (on Windows, the shell can't run it at all). Use the native installer, or allow the step as shown in Installation / Node.js Issues. The binary ships as an optional dependency, so don't use --omit=optional or optional=false in .npmrc.

Verify the installation, then start Claude Code:

claude --version
claude doctor
claude

Native installs update themselves. Homebrew, WinGet, and the signed apt, dnf, and apk repositories follow their package manager's update flow; set CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 to let Claude Code run the Homebrew or WinGet upgrade itself. See the official setup guide for channels, version pinning, Linux repository setup, and signature verification. For an npm install, upgrade with npm install -g @anthropic-ai/claude-code@latest; do not use sudo npm install -g.

---

[!Tip] Open Project Via Terminal Into VS Code / Cursor

$ - cd /path/to/project

$ - code .

Make sure you have the (Claude Code extension) installed in your VS Code / Cursor

---

System Requirements

• OS: macOS 13+, Windows 10 1809+/Windows Server 2019+, Ubuntu 20.04+, Debian 10+, or Alpine Linux 3.19+. Native Windows, WSL 1, and WSL 2 are supported.

• Hardware: 4 GB+ RAM and an x64 or ARM64 processor

• Shell: Bash, Zsh, PowerShell, or CMD

• Software: Git is optional on native Windows; without Git for Windows, Claude uses the PowerShell tool instead of Bash, and the Monitor tool is unavailable. Node.js 22+ is required only to install through npm; the installed CLI is a native binary.

• Alpine/musl: run apk add bash curl libgcc libstdc++ ripgrep (ripgrep is in the community repository), then set "USE_BUILTIN_RIPGREP": "0" under env in settings.json.

• Internet: Connection for API calls from an Anthropic supported region

---

Initial Setup

Claude Code requires a Pro, Max, Team, Enterprise, or Console account, or access through Amazon Bedrock, Google Cloud's Agent Platform (Vertex AI), or Microsoft Foundry; the free Claude.ai plan does not include Claude Code. The normal first-party flow is browser sign-in:

claude auth login             # Claude subscription
claude auth login --console   # Anthropic Console/API billing
claude auth status            # Verify the active login

At the /login prompt, Console users can pick Sign in with your Console account to skip creating an API key; Bedrock and Agent Platform users can pick 3rd-party platform (or run /setup-bedrock / /setup-vertex) for a setup wizard.

For API automation or a provider/gateway deployment, inject credentials from an OS key store or secret manager instead of committing them:

export ANTHROPIC_API_KEY="$SECRET_FROM_YOUR_STORE" # bash/zsh: current process only

$env:ANTHROPIC_API_KEY = $secretFromYourStore # PowerShell: current process only

To run CI or scripts on a Pro, Max, Team, or Enterprise subscription, run claude setup-token once and store the one-year token it prints (it is not saved) as CLAUDE_CODE_OAUTH_TOKEN. It only makes model requests (no Remote Control or claude.ai connectors), and --bare ignores it; see Authentication CLI.

[!Important] ANTHROPIC_AUTH_TOKEN, an approved ANTHROPIC_API_KEY, apiKeyHelper, and CLAUDE_CODE_OAUTH_TOKEN take precedence over your /login sign-in. Interactive sessions ask once before using ANTHROPIC_API_KEY (change the answer with Use custom API key in /config); -p always uses it. While an API key, auth token, or credential helper is in use, subscription-only features such as Remote Control, /schedule, claude.ai MCP connectors, and notification preferences remain unavailable. Authentication Issues lists the full precedence order; run /status to see which credential is active. Do not commit credentials; use your platform's secret storage.

---

Configuration & Environment

Environment Variables

Environment values can also be stored as strings under the env key in a settings.json file. The official environment-variable reference is the exhaustive source.

[!Important] On PowerShell, use $env:NAME = "value" for the current process. Persist secrets through an OS key store or secret manager, not a checked-in settings file.

# Authentication and routing: set only when API/provider billing is intentional
export ANTHROPIC_API_KEY="$SECRET_FROM_YOUR_STORE"
export ANTHROPIC_AUTH_TOKEN="$TOKEN_FROM_YOUR_STORE"
export ANTHROPIC_BASE_URL="https://gateway.example.com"
export ANTHROPIC_CUSTOM_HEADERS="X-Trace-Id: 12345"

# Model selection and provider alias overrides
export ANTHROPIC_MODEL="sonnet" # Wins over the model setting and a saved /model choice
# export ANTHROPIC_DEFAULT_MODEL="sonnet" # Alternative: starting model only; any model setting or saved /model choice wins
export ANTHROPIC_DEFAULT_FABLE_MODEL="<provider-fable-model-id>"
export ANTHROPIC_DEFAULT_OPUS_MODEL="<provider-opus-model-id>"
export ANTHROPIC_DEFAULT_SONNET_MODEL="<provider-sonnet-model-id>"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="<provider-haiku-model-id>"

# Third-party provider selection (enable one deployment path; only Bedrock and Mantle combine)
# export CLAUDE_CODE_USE_BEDROCK=1
# export ANTHROPIC_BEDROCK_REGION_PREFIX=eu # Prefer eu/us/apac/jp/au/global cross-region inference on Bedrock
# export CLAUDE_CODE_USE_MANTLE=1 # Amazon Bedrock Mantle endpoint; may be combined with CLAUDE_CODE_USE_BEDROCK
# export CLAUDE_CODE_USE_ANTHROPIC_AWS=1 # Claude Platform on AWS; also set ANTHROPIC_AWS_WORKSPACE_ID and AWS_REGION
# export CLAUDE_CODE_USE_VERTEX=1 # Google Cloud's Agent Platform (formerly Vertex AI)
# export CLAUDE_CODE_USE_FOUNDRY=1
# export CLAUDE_CODE_MODEL_CATALOG=off # Cloud providers: don't fetch signed model settings from downloads.claude.ai
# export CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT=0 # Full system prompt on any model, including custom deployment names/ARNs

# Timeouts, retries, and output budgets, in milliseconds/tokens
export API_TIMEOUT_MS=1200000
export BASH_DEFAULT_TIMEOUT_MS=120000
export BASH_MAX_TIMEOUT_MS=600000
export MCP_TIMEOUT=30000
export MCP_TOOL_TIMEOUT=600000 # Overall MCP tool limit (default ~28h); above 60000 it also raises remote servers' 60 s per-request limit
export MAX_MCP_OUTPUT_TOKENS=25000
export MAX_THINKING_TOKENS=0 # 0 disables thinking on the Anthropic API, except Opus/Sonnet/Haiku 5.5 and Fable; adaptive models ignore a positive budget (use effort)
# export CLAUDE_CODE_RETRY_WATCHDOG=1 # Unattended runs (CI, workers): keep retrying 429/529 capacity errors
# export CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS=1800000 # Cap each request's 429/529 wait under the watchdog

# Session, context, agents, and accessibility
# export CLAUDE_CODE_SIMPLE=1
# export CLAUDE_CODE_SAFE_MODE=1
export CLAUDE_CODE_DISABLE_1M_CONTEXT=1 # Clamp native-1M models to 200K via autocompaction; warns if the clamp is not enforced
export CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1 # Opt out of enforcing the assumed context window for unknown model IDs
export CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=20
export CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=3
export CLAUDE_CODE_FORWARD_SUBAGENT_TEXT=1
export CLAUDE_AX_SCREEN_READER=1

# Feature and administration controls
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
export CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1
export CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1
export ENABLE_CLAUDEAI_MCP_SERVERS=false

# Network routing
export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="http://proxy.example.com:8080"
export NO_PROXY="localhost,127.0.0.1"
export NODE_EXTRA_CA_CERTS="/path/to/corporate-ca.pem" # Only if a TLS-inspecting proxy's CA isn't in the OS trust store (or npm installs on Node < 22.15)

# Privacy/network reduction: these are presence-based; unset them to turn them off
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
export DISABLE_TELEMETRY=1
export DISABLE_ERROR_REPORTING=1

The block is a catalog, not a recommended profile—do not enable mutually exclusive provider variables together. Boolean variables usually accept 1/true and 0/false, but the three presence-based variables shown at the end treat any non-empty value, including 0, as enabled. CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC and DISABLE_TELEMETRY also stop feature-flag fetching, which disables /import, the advisor tool, claude.ai skill and plugin sync, and idle compaction; the first also turns off Remote Control, auto-updates, and /feedback.

An env value in settings.json replaces the shell's value; set it to "" to cancel a stale shell export (removing the key takes effect at the next launch). Most values from .claude/settings.json and .claude/settings.local.json apply only after you trust the workspace, and those files cannot set variables a repository shouldn't control, such as CLAUDE_CONFIG_DIR, TMPDIR, OpenTelemetry exporter variables, or CLAUDE_AX_SCREEN_READER; put those in your shell, user, or managed settings (claude --debug logs any it drops). Sessions launched by the Claude Desktop app keep the app's launch value for variables it sets.

Global Config Options

Use /config for interactive settings, or pass one or more key=value pairs. Run /config --help for the keys supported by your installed build.

/config                         # Open the settings UI
/config theme=dark model=sonnet # Update supported keys directly

For version-controlled or managed configuration, edit JSON settings files directly:

Scope	File
User	~/.claude/settings.json
Project (shared)	.claude/settings.json
Project (private)	.claude/settings.local.json
Managed	macOS: /Library/Application Support/ClaudeCode/ Linux/WSL: /etc/claude-code/ Windows: C:\Program Files\ClaudeCode\

{
  "model": "sonnet",
  "theme": "dark",
  "autoUpdatesChannel": "stable",
  "permissions": {
    "defaultMode": "default"
  }
}

Settings-file precedence is managed policy → --settings → local → project → user. Other flags and environment variables are not levels in this stack; each key decides whether they win (--model and ANTHROPIC_MODEL beat any model setting, even a managed one, which is only a starting default). List keys such as permissions.allow merge across files, so read settings precedence before relying on last-writer-wins behavior; All settings lists every key. With no permission mode configured, interactive sessions start in auto mode; permissions.defaultMode overrides that, but auto and bypassPermissions apply only from user or managed settings (or --settings / --permission-mode). ~/.claude.json stores global state, session/trust data, and local/user MCP configuration; it is not the user settings file.

To hide all commit and PR attribution, set "attribution": false. Versions before v2.1.281 skip a settings file that contains it, so in files they also read use "attribution": { "commit": "", "pr": "", "sessionUrl": false }.

Configuration Files

Claude Code combines human-authored instructions from several locations:

Memory Type	Location	Purpose	Use Case Examples	Shared With
Enterprise policy	macOS: /Library/Application Support/ClaudeCode/CLAUDE.md Linux: /etc/claude-code/CLAUDE.md Windows: C:\Program Files\ClaudeCode\CLAUDE.md	Organization-wide instructions managed by IT/DevOps	Company coding standards, security policies, compliance requirements	All users in organization
Project memory	./CLAUDE.md or ./.claude/CLAUDE.md	Team-shared instructions for the project	Project architecture, coding standards, common workflows	Team members via source control
User memory	~/.claude/CLAUDE.md	Personal preferences for all projects	Code styling preferences, personal tooling shortcuts	Just you (all projects)
Project memory (local)	./CLAUDE.local.md	Personal project preferences (add to .gitignore)	Your sandbox URLs, preferred test data, personal overrides	Just you (current project)
Project rules	.claude/rules/**/*.md	Modular project rules (loaded alongside CLAUDE.md)	Linting rules, API conventions, path-scoped standards	Team members via source control
User rules	~/.claude/rules/**/*.md	Personal rules, loaded before project rules	Preferred tools, personal workflow conventions	Just you (all projects)

Instruction files are concatenated rather than overriding one another. User and ancestor-project files load at startup; CLAUDE.md files in subdirectories load lazily when Claude works there. In monorepos, skip other teams' or unrelated ancestor files with the claudeMdExcludes setting (glob patterns; a managed CLAUDE.md can't be excluded). CLAUDE.md is context, not an enforcement boundary. Run /doctor prompt-audit for a report of outdated, broken, or conflicting instructions; it edits nothing until you approve.

Use @path to import another file. When no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md exists in the working directory or above it, Claude Code reads AGENTS.md instead; user and managed CLAUDE.md files and .claude/rules/ still load. If any of those project files exists (even just CLAUDE.local.md), AGENTS.md is skipped: import it with @AGENTS.md, or set Project instructions to claude-md-and-agents-md in /config to load both.

.claude/rules/ Directory

The .claude/rules/ directory lets you break project instructions into separate Markdown files instead of one large CLAUDE.md. Markdown files are discovered recursively. Add paths frontmatter with glob patterns when a rule should load only for matching files. This is useful for:

• Modular organization: Separate concerns (e.g., api-conventions.md, testing-rules.md)
• Per-directory scoping: paths-scoped rules and rules in a subdirectory's .claude/rules/ load on demand when Claude reads, writes, or edits files they cover, adding to other rules rather than overriding them
• Team collaboration: Different team members can own different rule files via PR review

Auto-Memory

Claude can save useful working context under ~/.claude/projects/<project>/memory/. It loads the first 200 lines or 25 KB of MEMORY.md; use /memory to inspect, edit, disable, or remove saved memories. Auto-memory is machine-local and shared across worktrees for the same repository. Turn it off for one project with "autoMemoryEnabled": false in that project's settings, or everywhere with CLAUDE_CODE_DISABLE_AUTO_MEMORY=1; autoMemoryDirectory moves where it is stored.

Auto-memory is most useful for context you would otherwise repeat across sessions:

• Preferred build, test, and lint commands
• Local conventions that are not obvious from code alone
• Architecture decisions that influence future edits
• Team preferences that should shape how Claude proposes changes

Keep durable team rules in CLAUDE.md or .claude/rules/. Treat auto-memory as helpful working context, not as the only source of truth.

---

Commands & Usage

Slash Command Reference

Type / to see what your installed build, plan, platform, plugins, MCP servers, and skills actually provide. The table below is a high-value snapshot; use the official command reference for the live list.

Command	Purpose
/add-dir <path>	Grant this session access to another working directory
/advisor [model|off]	Configure the experimental second-model advisor, save the selection, or turn it off
/agents	Explain how to create or edit subagents; hidden from the / menu, and the old interactive wizard was removed in v2.1.198
/artifacts	List artifacts you own or that are shared with you; attach one to the session, open it, or copy its link
/auto-mode-setup	Draft autoMode.environment entries from your project and recent sessions, then review and save them to user settings
/autocompact [auto|tokens]	Set the auto-compact window per model (e.g. /autocompact 200k if your gateway stops at 200K); auto restores the default
/background [prompt]	Detach the current conversation as a background session (/bg alias)
/batch <instruction>	Decompose a large change into worktree-isolated background units (bundled skill)
/branch [name]	Switch into a new branch of the current conversation while preserving the original
/btw [question]	Ask an ephemeral side question without adding it to conversation history
/cd <path>	Move the current session to another working directory; its project settings, hooks, skills, agents, and .mcp.json servers (after approval) apply immediately
/clear [name]	Start a new conversation with empty context while preserving project memory
/code-review [level] [--fix] [--comment] [--max-findings n|all|default] [target]	Run a local background review, or use level ultra for cloud review; levels run from low through max. --comment posts to a GitHub PR or GitLab MR; a --max-findings choice sticks until you pass default
/compact [instructions]	Summarize the conversation to free context
/config [key=value ...]	Open settings or update supported keys directly (/settings alias)
/context [all]	Visualize what is using the context window
/copy [N]	Copy the last (or Nth-latest) response; a picker selects single code blocks, and w writes to a file instead (useful over SSH)
/diff	Open the interactive current/per-turn diff viewer; in fullscreen mode, toggle a panel of uncommitted changes beside the conversation
/doctor [prompt-audit [path]]	Diagnose setup, configuration, hooks, memory, plugins, and MCP; can offer fixes (/checkup alias). prompt-audit checks CLAUDE.md, skills, agents, and commands for stale paths and prompting patterns written for older models
/effort [level|auto|status|ultracode [on|off]]	Set model-dependent effort (low to xhigh save per model; max, or s in the picker, is session-only). status prints the level; ultracode [on|off] toggles ultracode at any effort level
/fast [on|off]	Toggle fast mode where the selected Opus model and plan support it
/focus	Toggle focus view (fullscreen rendering only): your last prompt, a one-line tool summary, and the final response
/fork [prompt]	Copy this conversation into a worktree-isolated background session and keep working here
/goal [condition|clear]	Keep working across turns until a completion condition is met
/hooks	Inspect configured hooks in the read-only hook browser
/import [codex|gemini|cursor] [--dry-run] [--yes]	Bring instruction files, MCP servers, commands, subagents, and skills over from OpenAI Codex, Gemini CLI, or Cursor; --dry-run previews and --yes skips the picker
/init	Generate a starter CLAUDE.md for the project
/keybindings	Open ~/.claude/keybindings.json to customize shortcuts (see Keyboard Shortcuts)
/loop [interval] [prompt]	Run a prompt repeatedly while the session remains open
/mcp [reconnect|enable|disable] [server|all]	Inspect, authenticate, enable, disable, or reconnect MCP servers; /mcp reconnect all retries every server that failed or needs authentication
/memory	Manage CLAUDE.md, rules, and auto-memory
/model [model]	Switch model and normally save it as the default; press s in the picker for session-only selection
/output-style [style]	List output styles or switch to one, such as /output-style concise
/permissions	Manage allow, ask, and deny rules (/allowed-tools alias)
/plan [description]	Enter plan mode, optionally with a task
/plugin [subcommand]	Discover, install, enable, disable, and manage plugins
/reload-plugins [--force]	Apply plugin changes without restarting when safe
/remote-control [name]	Expose this local session to claude.ai/code or the Claude mobile app
/resume [session]	Resume by ID/name or open the session picker
/review ...	Alias for /code-review as of v2.1.223
/rewind	Restore or summarize code and conversation from a checkpoint; Bash edits such as sed -i are not checkpointed unless Claude already edited that file with its file tools (/undo alias)
/sandbox	View and configure OS-level filesystem/network sandboxing for Bash, PowerShell, and Monitor commands on supported platforms
/schedule [description]	Create, update, list, or run cloud scheduled tasks, formerly routines (/routines alias)
/security-review	Review the current branch diff for security vulnerabilities
/simplify	Review changed code for reuse, quality, and efficiency improvements
/skill-doctor	Show what each skill costs in context and how often it is used, so you can turn off unused ones
/skills	List skills; press t to sort by token cost and Space/Enter to change a skill's visibility
/status	Show version, model, account, and connectivity on the Settings Status tab; works while Claude is responding
/statusline [description]	Configure the status line from a description, or from your shell prompt when run without arguments
/subtask [prompt]	Run the former in-session fork behavior as a subagent that reports back here

…