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 | 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 |

Getting Started

Enable completion alerts: run /config inside Claude Code and choose a notification channel such as Terminal bell.

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
winget install Anthropic.ClaudeCode

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

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

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. 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

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

- Internet: Connection for API calls

Initial Setup

Claude Code requires a Pro, Max, Team, Enterprise, or Console account; 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

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

export ANTHROPICAPIKEY="$SECRETFROMYOUR_STORE" # bash/zsh: current process only

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

[!Important]

A persistent ANTHROPICAPIKEY, ANTHROPICAUTHTOKEN, or credential helper selects API/provider authentication even if you are logged in. Subscription-only features such as Remote Control, cloud sessions, claude.ai MCP connectors, and notification preferences then remain unavailable. 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 ANTHROPICAPIKEY="$SECRETFROMYOUR_STORE"
export ANTHROPICAUTHTOKEN="$TOKENFROMYOUR_STORE"
export ANTHROPICBASEURL="https://gateway.example.com"
export ANTHROPICCUSTOMHEADERS="X-Trace-Id: 12345"
Model selection and provider alias overrides
export ANTHROPIC_MODEL="sonnet"
export ANTHROPICDEFAULTFABLE_MODEL="<provider-fable-model-id>"
export ANTHROPICDEFAULTOPUS_MODEL="<provider-opus-model-id>"
export ANTHROPICDEFAULTS
export ANTHROPICDEFAULTHAIKU_MODEL="<provider-haiku-model-id>"
Third-party provider selection (enable only one deployment path)
export CLAUDECODEUSE_BEDROCK=1
export ANTHROPICBEDROCKREGION_PREFIX=eu # Prefer eu/us/apac/jp/au/global cross-region inference on Bedrock
export CLAUDECODEUSE_VERTEX=1
export CLAUDECODEUSE_FOUNDRY=1
Timeouts and output budgets, in milliseconds/tokens
export APITIMEOUTMS=1200000
export BASHDEFAULTTIMEOUT_MS=120000
export BASHMAXTIMEOUT_MS=600000
export MCP_TIMEOUT=30000
export MCPTOOLTIMEOUT=60000
export MAXMCPOUTPUT_TOKENS=25000
export MAXTHINKINGTOKENS=0 # 0 disables fixed thinking where supported; positive values set a budget
Session, context, agents, and accessibility
export CLAUDECODESIMPLE=1
export CLAUDECODESAFE_MODE=1
export CLAUDECODEDISABLE1MCONTEXT=1 # Clamp native-1M models to 200K via autocompaction; warns if the clamp is not enforced
export CLAUDECODEDISABLEUNKNOWNMODELWINDOWENFORCEMENT=1 # Opt out of enforcing the assumed context window for unknown model IDs
export CLAUDECODEMAXCONCURRENTSUBAGENTS=20
export CLAUDECODEMAXSUBAGENTSPAWN_DEPTH=3
export CLAUDECODEFORWARDSUBAGENTTEXT=1
export CLAUDEAXSCREEN_READER=1
Feature and administration controls
export CLAUDECODEEXPERIMENTALAGENTTEAMS=1
export CLAUDECODEADDITIONALDIRECTORIESCLAUDE_MD=1
export CLAUDECODEENABLEGATEWAYMODEL_DISCOVERY=1
export CLAUDECODEPACKAGEMANAGERAUTO_UPDATE=1
export ENABLECLAUDEAIMCP_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"
Privacy/network reduction: these are presence-based; unset them to turn them off
export CLAUDECODEDISABLENONESSENTIALTRAFFIC=1
export DISABLE_TELEMETRY=1
export DISABLEERRORREPORTING=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. Environment values in settings.json override the shell value at startup and when the file changes.

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 precedence is managed policy → CLI arguments/--settings → local → project → user. Permission arrays have their own merge rules, so read the settings reference before relying on ordinary last-writer-wins behavior. ~/.claude.json stores global state, session/trust data, and local/user MCP configuration; it is not the user settings file.

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-specific preferences (git-ignored) | 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 |

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. CLAUDE.md is context, not an enforcement boundary.

Use @path to import another file. Claude Code does not load AGENTS.md automatically; add @AGENTS.md to CLAUDE.md (or use a symlink where portable) when you want to share those instructions.

.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 overrides: Nested rules/ directories can apply scoped rules
• 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.

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

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; the old interactive agent wizard was removed in v2.1.198 | | /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 | | /clear [name] | Start a new conversation with empty context while preserving project memory | | /code-review [level] [--fix] [--comment] [target] | Run a local background review, or use level ultra for cloud review; levels run from low through max | | /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 | | /diff | Open the interactive current/per-turn diff viewer | | /doctor | Diagnose setup, configuration, hooks, memory, plugins, and MCP; can offer fixes (/checkup alias) | | /effort [level|auto] | Set model-dependent effort: low, medium, high, xhigh, max, or ultracode | | /fast [on|off] | Toggle fast mode where the selected Opus model and plan support it | | /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] | Preview or migrate supported configuration from another coding agent | | /init | Generate a starter CLAUDE.md for the project | | /loop [interval] [prompt] | Run a prompt repeatedly while the session remains open | | /mcp | Inspect, authenticate, enable, disable, or reconnect MCP servers | | /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 | | /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 | | /sandbox | View and configure Bash filesystem/network sandboxing on supported platforms | | /security-review | Review the current branch diff for security vulnerabilities | | /simplify | Review changed code for reuse, quality, and efficiency improvements | | /subtask [prompt] | Run the former in-session fork behavior as a subagent that reports back here | | /tasks | List the current session's background shells, subagents, and tool calls | | /teleport [session] | Copy a Claude Code web session into the local terminal | | /usage | Show subscription usage and rate-limit status | | /workflows | Inspect dynamic workflow runs and background orchestration |

Command Line Flags

| Flag / Command | Description | Example | | :--------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------- | | -d, --debug | Enable debug mode (shows detailed debug output). | claude -d -p "query" | | --include-partial-messages | Include partial streaming events; requires print mode and stream-json. | claude -p --output-format stream-json --include-partial-messages "query" | | --include-hook-events | Include hook lifecycle events in stream-json output. | claude -p --output-format stream-json --include-hook-events "query" | | --forward-subagent-text | Forward subagent text/thinking with parenttooluse_id in stream-json. | claude -p --output-format stream-json --forward-subagent-text "query" | | --verbose | Override verbose mode setting from config (shows expanded logging / turn-by-turn output). | claude --verbose | | -p, --print | Print response and exit (useful for piping output). | claude -p "query" | | --output-format <format> | Output format (only works with --print): text (default), json (single result), or stream-json (realtime streaming). | claude -p "query" --output-format json | | --input-format <format> | Input format (only works with --print): text (default) or stream-json (realtime streaming input). | claude -p --output-format stream-json --input-format stream-json | | --replay-user-messages | Re-emit user messages from stdin back to stdout for acknowledgment — only works with print mode plus stream-json input and output. | claude -p --verbose --input-format stream-json --output-format stream-json --replay-user-messages | | --allowedTools, --allowed-tools <tools...> | Comma/space-separated permission rules to allow. | claude --allowed-tools "Bash(git *)" "Edit" | | --disallowedTools, --disallowed-tools <tools...> | Comma/space-separated permission rules to deny. | claude --disallowed-tools "Edit" | | --mcp-config <configs...> | Load MCP servers from JSON files or strings (space-separated). | claude --mcp-config ./mcp-servers.json | | --strict-mcp-config | Only use MCP servers from --mcp-config, ignoring other MCP configurations. | claude --mcp-config ./a.json --strict-mcp-config | | --append-system-prompt <prompt> | Append a system prompt to the default system prompt (useful in print mode). | claude -p --append-system-prompt "Do X then Y" | | --autocompact <auto\|tokens> | Override the auto-compaction window for this session. | claude --autocompact 500k | | --ax-screen-reader | Use a flat, screen-reader-friendly renderer without decorative borders or animations. | claude --ax-screen-reader | | --bare | Minimal scripted mode: skip discovered hooks, skills, plugins, MCP, auto-memory, and CLAUDE.md. | claude --bare -p "query" | | --permission-mode <mode> | Start in default/manual, acceptEdits, auto, dontAsk, bypassPermissions, or plan. | claude --permission-mode plan | | --permission-prompt-tool <tool> | Specify an MCP tool to handle permission prompts in non-interactive mode. | claude -p --permission-prompt-tool mcpauthtool "query" | | --fallback-model <models> | In print mode, try a comma-separated fallback chain when the primary model is unavailable. | claude -p --fallback-model sonnet,haiku "query" | | --effort <level> | Set effort to low, medium, high, xhigh, or max, or start session-only ultracode mode where supported. | claude --effort high | | --model <model> | Model for the current session. Accepts aliases like sonnet/opus or a full model ID when pinning. | claude --model sonnet | | --advisor <model> | Set the experimental advisor for this session without changing advisorModel; intentionally omitted from claude --help. | claude --advisor opus | | --settings <file-or-json> | Load additional settings from a JSON file or a JSON string. | claude --settings ./settings.json | | --add-dir <directories...> | Additional directories to allow tool access to. | claude --add-dir ../apps ../lib | | --ide | Automatically connect to an IDE on startup if exactly one valid IDE is available. | claude --ide | | -c, --continue | Continue the most recent conversation in the current directory. | claude --continue | | -r, --resume [sessionId] | Resume a conversation; provide a session ID or interactively select one. | claude -r "abc123" | | --session-id <uuid> | Use a specific session ID for the conversation (must be a valid UUID). | claude --session-id 123e4567-e89b-12d3-a456-426614174000 | | --agents <json> | Define custom subagents dynamically via JSON (see subagent docs for format). | claude --agents '{"reviewer":{"description":"Reviews code","prompt":"..."}}' | | --agent <name> | Specify a specific agent for the current session. | claude --agent my-custom-agent | | --bg | Start or continue work as a background session that can be viewed from claude agents. | claude --bg "fix failing tests" | | --bg --exec <command> | Run a shell command as an attachable background session. | claude --bg --exec "npm test" | | --name <label> | Name a background or remote session for easier identification. | claude --bg --name nightly-check "run checks" | | --chrome | Enable Chrome browser integration for web automation and testing. | claude --chrome | | --no-chrome | Disable Chrome browser integration for this session. | claude --no-chrome | | --cloud [description\|session\|url] | Create or attach to a Claude Code web session on claude.ai. | claude --cloud "Fix the login bug" | | --remote | Deprecated alias for --cloud. | claude --remote "Fix the login bug" | | --remote-control, --rc | Start an interactive local session that can also be controlled from claude.ai or the Claude app. | claude --remote-control "My Project" | | --teleport [session] | Resume a web session in your local terminal. | claude --teleport <session-id> | | --fork-session | When resuming, create a new session ID instead of reusing the original. | claude --resume abc123 --fork-session | | --json-schema <schema> | Get validated JSON output matching a JSON Schema after agent completes (print mode only). | claude -p --json-schema '{"type":"object",...}' "query" | | --max-budget-usd <amount> | Maximum dollar amount to spend on API calls before stopping (print mode only). | claude -p --max-budget-usd 5.00 "query" | | --max-turns <n> | Limit the number of agentic turns (print mode only). Exits with error when limit reached. | claude -p --max-turns 3 "query" | | --betas <headers> | Beta headers to include in API requests (API key users only). | claude --betas interleaved-thinking | | --tools <tools> | Restrict which built-in tools Claude can use. Use "" to disable all, "default" for all, or specific tool names. | claude --tools "Bash,Edit,Read" | | --system-prompt <prompt> | Replace the entire system prompt with custom text (works in interactive and print modes). | claude --system-prompt "You are a Python expert" | | --system-prompt-file <file> | Load a system prompt from a file, replacing the default in interactive or print mode. | claude --system-prompt-file ./custom-prompt.txt | | --append-system-prompt-file <file> | Load additional system-prompt text from a file in interactive or print mode. | claude --append-system-prompt-file ./extra-rules.txt | | --plugin-dir <path> | Load a plugin directory or .zip for this session only (repeatable). | claude --plugin-dir ./my-plugin --plugin-dir ./other.zip | | --plugin-url <url> | Fetch a plugin .zip URL for this session only (repeatable). | claude --plugin-url https://example.com/plugin.zip | | --setting-sources <sources> | Comma-separated list of setting sources to load (user, project, local). | claude --setting-sources user,project | | --no-session-persistence | Disable session persistence so sessions are not saved to disk (print mode only). | claude -p --no-session-persistence "query" | | --disable-slash-commands | Disable all skills and slash commands for this session. | claude --disable-slash-commands | | --dangerously-skip-permissions | Skip normal permission prompts, subject to non-bypassable safety checks and managed policy. | claude --dangerously-skip-permissions | | --safe-mode | Disable user/project customizations for configuration troubleshooting while retaining authentication, models, tools, and permissions. | claude --safe-mode | | --worktree [name], -w [name] | Start in <repo>/.claude/worktrees/<name>; omit the name to generate one. | claude -w feature-auth | | --from-pr [value] | Filter/resume sessions by PR number or GitHub/GitLab/Bitbucket PR/MR URL, or open the picker. | claude --from-pr 123 | | --init | Run Setup hooks with the init matcher before a print-mode session. | claude -p --init "query" | | --init-only | Run Setup hooks and exit. | claude --init-only | | --maintenance | Run Setup hooks with the maintenance matcher before a print-mode session. | claude -p --maintenance "query" | | -v, --version | Show the installed claude CLI version. | claude --version | | -h, --help | Display help / usage. | claude --help |

This table highlights common and recently changed options; claude --help and the live CLI reference are authoritative. --output-format json is useful for one-shot automation; use stream-json for event-level integrations.