\n\n_For reference and contributions, visit the [official Claude Code documentation](https://code.claude.com/docs/en/overview)_\n\n_Commands and provider model mappings change quickly; the linked official references remain authoritative._\n\n\n[](https://github.com/anthropics/claude-code)\n[](LICENSE)\n\n
\n\n**Enable completion alerts:** run `/config` inside Claude Code and choose a notification channel such as **Terminal bell**.\n\n
Quick Start
\n\n> [!TIP]\n> **Run claude in a project directory to start the interface.**\n>\n> **Go to [Help & Troubleshooting](#help--troubleshooting) to fix issues...**\n\n**Native installer (recommended; no Node.js required)**\n\nmacOS, Linux, or WSL:\n\n```bash\ncurl -fsSL https://claude.ai/install.sh | bash\n```\n\nWindows PowerShell:\n\n```powershell\nirm https://claude.ai/install.ps1 | iex\n```\n\nWindows CMD:\n\n```bat\ncurl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd\n```\n\nSupported package managers (manual updates by default):\n\n```bash\nbrew install --cask claude-code\nwinget install Anthropic.ClaudeCode\n```\n\nnpm distribution (supported; Node.js 22+ is required to install):\n\n```bash\nnpm install -g @anthropic-ai/claude-code\n```\n\nVerify the installation, then start Claude Code:\n\n```bash\nclaude --version\nclaude doctor\nclaude\n```\n\nNative 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](https://code.claude.com/docs/en/setup) 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`.\n\n---\n\n> [!Tip]\n> **Open Project Via Terminal Into VS Code / Cursor**\n>\n> ### $ - cd /path/to/project\n>\n> ### $ - code .\n>\n> **Make sure you have the (Claude Code extension) installed in your VS Code / Cursor**\n\n---\n\n
System Requirements
\n\n> - 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.\n\n> - Hardware: 4 GB+ RAM and an x64 or ARM64 processor\n\n> - 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.\n\n> - Internet: Connection for API calls\n\n---\n\n
Initial Setup
\n\nClaude 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:\n\n```bash\nclaude auth login # Claude subscription\nclaude auth login --console # Anthropic Console/API billing\nclaude auth status # Verify the active login\n```\n\nFor API automation or a provider/gateway deployment, inject credentials from an OS key store or secret manager instead of committing them:\n\n```bash\nexport ANTHROPIC_API_KEY=\"$SECRET_FROM_YOUR_STORE\" # bash/zsh: current process only\n```\n\n```powershell\n$env:ANTHROPIC_API_KEY = $secretFromYourStore # PowerShell: current process only\n```\n\n> [!Important]\n> A persistent `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, 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.\n\n---\n\n
Configuration & Environment
\n\n
Environment Variables
\n\n> **Environment values can also be stored as strings under the `env` key in a `settings.json` file. The [official environment-variable reference](https://code.claude.com/docs/en/env-vars) is the exhaustive source.**\n\n> [!Important]\n> **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.**\n\n```bash\n# Authentication and routing: set only when API/provider billing is intentional\nexport ANTHROPIC_API_KEY=\"$SECRET_FROM_YOUR_STORE\"\nexport ANTHROPIC_AUTH_TOKEN=\"$TOKEN_FROM_YOUR_STORE\"\nexport ANTHROPIC_BASE_URL=\"https://gateway.example.com\"\nexport ANTHROPIC_CUSTOM_HEADERS=\"X-Trace-Id: 12345\"\n\n# Model selection and provider alias overrides\nexport ANTHROPIC_MODEL=\"sonnet\"\nexport ANTHROPIC_DEFAULT_FABLE_MODEL=\"\"\nexport ANTHROPIC_DEFAULT_OPUS_MODEL=\"\"\nexport ANTHROPIC_DEFAULT_SONNET_MODEL=\"\"\nexport ANTHROPIC_DEFAULT_HAIKU_MODEL=\"\"\n\n# Third-party provider selection (enable only one deployment path)\n# export CLAUDE_CODE_USE_BEDROCK=1\n# export ANTHROPIC_BEDROCK_REGION_PREFIX=eu # Prefer eu/us/apac/jp/au/global cross-region inference on Bedrock\n# export CLAUDE_CODE_USE_VERTEX=1\n# export CLAUDE_CODE_USE_FOUNDRY=1\n\n# Timeouts and output budgets, in milliseconds/tokens\nexport API_TIMEOUT_MS=1200000\nexport BASH_DEFAULT_TIMEOUT_MS=120000\nexport BASH_MAX_TIMEOUT_MS=600000\nexport MCP_TIMEOUT=30000\nexport MCP_TOOL_TIMEOUT=60000\nexport MAX_MCP_OUTPUT_TOKENS=25000\nexport MAX_THINKING_TOKENS=0 # 0 disables fixed thinking where supported; positive values set a budget\n\n# Session, context, agents, and accessibility\n# export CLAUDE_CODE_SIMPLE=1\n# export CLAUDE_CODE_SAFE_MODE=1\nexport CLAUDE_CODE_DISABLE_1M_CONTEXT=1 # Clamp native-1M models to 200K via autocompaction; warns if the clamp is not enforced\nexport CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1 # Opt out of enforcing the assumed context window for unknown model IDs\nexport CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=20\nexport CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=3\nexport CLAUDE_CODE_FORWARD_SUBAGENT_TEXT=1\nexport CLAUDE_AX_SCREEN_READER=1\n\n# Feature and administration controls\nexport CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1\nexport CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1\nexport CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1\nexport CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1\nexport ENABLE_CLAUDEAI_MCP_SERVERS=false\n\n# Network routing\nexport HTTP_PROXY=\"http://proxy.example.com:8080\"\nexport HTTPS_PROXY=\"http://proxy.example.com:8080\"\nexport NO_PROXY=\"localhost,127.0.0.1\"\n\n# Privacy/network reduction: these are presence-based; unset them to turn them off\nexport CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1\nexport DISABLE_TELEMETRY=1\nexport DISABLE_ERROR_REPORTING=1\n```\n\nThe 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.\n\n
Global Config Options
\n\nUse `/config` for interactive settings, or pass one or more `key=value` pairs. Run `/config --help` for the keys supported by your installed build.\n\n```bash\n/config # Open the settings UI\n/config theme=dark model=sonnet # Update supported keys directly\n```\n\nFor version-controlled or managed configuration, edit JSON settings files directly:\n\n| Scope | File |\n| :---- | :--- |\n| User | `~/.claude/settings.json` |\n| Project (shared) | `.claude/settings.json` |\n| Project (private) | `.claude/settings.local.json` |\n| Managed | macOS: `/Library/Application Support/ClaudeCode/` Linux/WSL: `/etc/claude-code/` Windows: `C:\\Program Files\\ClaudeCode\\` |\n\n```json\n{\n \"model\": \"sonnet\",\n \"theme\": \"dark\",\n \"autoUpdatesChannel\": \"stable\",\n \"permissions\": {\n \"defaultMode\": \"default\"\n }\n}\n```\n\nSettings precedence is **managed policy → CLI arguments/`--settings` → local → project → user**. Permission arrays have their own merge rules, so read the [settings reference](https://code.claude.com/docs/en/settings) 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.\n\n
Configuration Files
\n\nClaude Code combines human-authored instructions from several locations:\n\n| Memory Type | Location | Purpose | Use Case Examples | Shared With |\n| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------- |\n| **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 |\n| **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 |\n| **User memory** | `~/.claude/CLAUDE.md` | Personal preferences for all projects | Code styling preferences, personal tooling shortcuts | Just you (all projects) |\n| **Project memory (local)** | `./CLAUDE.local.md` | Personal project-specific preferences (git-ignored) | Your sandbox URLs, preferred test data, personal overrides | Just you (current project) |\n| **Project rules** | `.claude/rules/**/*.md` | Modular project rules (loaded alongside CLAUDE.md) | Linting rules, API conventions, path-scoped standards | Team members via source control |\n\n> 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.\n\nUse `@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.\n\n#### `.claude/rules/` Directory\n\nThe `.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:\n\n- **Modular organization**: Separate concerns (e.g., `api-conventions.md`, `testing-rules.md`)\n- **Per-directory overrides**: Nested `rules/` directories can apply scoped rules\n- **Team collaboration**: Different team members can own different rule files via PR review\n\n#### Auto-Memory\n\nClaude can save useful working context under `~/.claude/projects//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.\n\nAuto-memory is most useful for context you would otherwise repeat across sessions:\n\n- Preferred build, test, and lint commands\n- Local conventions that are not obvious from code alone\n- Architecture decisions that influence future edits\n- Team preferences that should shape how Claude proposes changes\n\nKeep durable team rules in `CLAUDE.md` or `.claude/rules/`. Treat auto-memory as helpful working context, not as the only source of truth.\n\n---\n\n
Commands & Usage
\n\n
Slash Command Reference
\n\nType `/` 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](https://code.claude.com/docs/en/commands) for the live list.\n\n| Command | Purpose |\n| :------ | :------ |\n| `/add-dir ` | Grant this session access to another working directory |\n| `/advisor [model\\|off]` | Configure the experimental second-model advisor, save the selection, or turn it off |\n| `/agents` | Explain how to create or edit subagents; the old interactive agent wizard was removed in v2.1.198 |\n| `/background [prompt]` | Detach the current conversation as a background session (`/bg` alias) |\n| `/batch ` | Decompose a large change into worktree-isolated background units (bundled skill) |\n| `/branch [name]` | Switch into a new branch of the current conversation while preserving the original |\n| `/btw [question]` | Ask an ephemeral side question without adding it to conversation history |\n| `/cd ` | Move the current session to another working directory |\n| `/clear [name]` | Start a new conversation with empty context while preserving project memory |\n| `/code-review [level] [--fix] [--comment] [target]` | Run a local background review, or use level `ultra` for cloud review; levels run from `low` through `max` |\n| `/compact [instructions]` | Summarize the conversation to free context |\n| `/config [key=value ...]` | Open settings or update supported keys directly (`/settings` alias) |\n| `/context [all]` | Visualize what is using the context window |\n| `/diff` | Open the interactive current/per-turn diff viewer |\n| `/doctor` | Diagnose setup, configuration, hooks, memory, plugins, and MCP; can offer fixes (`/checkup` alias) |\n| `/effort [level|auto]` | Set model-dependent effort: `low`, `medium`, `high`, `xhigh`, `max`, or `ultracode` |\n| `/fast [on|off]` | Toggle fast mode where the selected Opus model and plan support it |\n| `/fork [prompt]` | Copy this conversation into a worktree-isolated background session and keep working here |\n| `/goal [condition|clear]` | Keep working across turns until a completion condition is met |\n| `/hooks` | Inspect configured hooks in the read-only hook browser |\n| `/import [codex|gemini]` | Preview or migrate supported configuration from another coding agent |\n| `/init` | Generate a starter `CLAUDE.md` for the project |\n| `/loop [interval] [prompt]` | Run a prompt repeatedly while the session remains open |\n| `/mcp` | Inspect, authenticate, enable, disable, or reconnect MCP servers |\n| `/memory` | Manage `CLAUDE.md`, rules, and auto-memory |\n| `/model [model]` | Switch model and normally save it as the default; press `s` in the picker for session-only selection |\n| `/permissions` | Manage allow, ask, and deny rules (`/allowed-tools` alias) |\n| `/plan [description]` | Enter plan mode, optionally with a task |\n| `/plugin [subcommand]` | Discover, install, enable, disable, and manage plugins |\n| `/reload-plugins [--force]` | Apply plugin changes without restarting when safe |\n| `/remote-control [name]` | Expose this local session to claude.ai/code or the Claude mobile app |\n| `/resume [session]` | Resume by ID/name or open the session picker |\n| `/review ...` | Alias for `/code-review` as of v2.1.223 |\n| `/rewind` | Restore or summarize code and conversation from a checkpoint |\n| `/sandbox` | View and configure Bash filesystem/network sandboxing on supported platforms |\n| `/security-review` | Review the current branch diff for security vulnerabilities |\n| `/simplify` | Review changed code for reuse, quality, and efficiency improvements |\n| `/subtask [prompt]` | Run the former in-session fork behavior as a subagent that reports back here |\n| `/tasks` | List the current session's background shells, subagents, and tool calls |\n| `/teleport [session]` | Copy a Claude Code web session into the local terminal |\n| `/usage` | Show subscription usage and rate-limit status |\n| `/workflows` | Inspect dynamic workflow runs and background orchestration |\n\n
Command Line Flags
\n\n| Flag / Command | Description | Example |\n| :--------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------- |\n| `-d, --debug` | Enable debug mode (shows detailed debug output). | `claude -d -p \"query\"` |\n| `--include-partial-messages` | Include partial streaming events; requires print mode and `stream-json`. | `claude -p --output-format stream-json --include-partial-messages \"query\"` |\n| `--include-hook-events` | Include hook lifecycle events in `stream-json` output. | `claude -p --output-format stream-json --include-hook-events \"query\"` |\n| `--forward-subagent-text` | Forward subagent text/thinking with `parent_tool_use_id` in `stream-json`. | `claude -p --output-format stream-json --forward-subagent-text \"query\"` |\n| `--verbose` | Override verbose mode setting from config (shows expanded logging / turn-by-turn output). | `claude --verbose` |\n| `-p, --print` | Print response and exit (useful for piping output). | `claude -p \"query\"` |\n| `--output-format ` | Output format (only works with `--print`): `text` (default), `json` (single result), or `stream-json` (realtime streaming). | `claude -p \"query\" --output-format json` |\n| `--input-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` |\n| `--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` |\n| `--allowedTools`, `--allowed-tools ` | Comma/space-separated permission rules to allow. | `claude --allowed-tools \"Bash(git *)\" \"Edit\"` |\n| `--disallowedTools`, `--disallowed-tools ` | Comma/space-separated permission rules to deny. | `claude --disallowed-tools \"Edit\"` |\n| `--mcp-config ` | Load MCP servers from JSON files or strings (space-separated). | `claude --mcp-config ./mcp-servers.json` |\n| `--strict-mcp-config` | Only use MCP servers from `--mcp-config`, ignoring other MCP configurations. | `claude --mcp-config ./a.json --strict-mcp-config` |\n| `--append-system-prompt ` | Append a system prompt to the default system prompt (useful in print mode). | `claude -p --append-system-prompt \"Do X then Y\"` |\n| `--autocompact ` | Override the auto-compaction window for this session. | `claude --autocompact 500k` |\n| `--ax-screen-reader` | Use a flat, screen-reader-friendly renderer without decorative borders or animations. | `claude --ax-screen-reader` |\n| `--bare` | Minimal scripted mode: skip discovered hooks, skills, plugins, MCP, auto-memory, and `CLAUDE.md`. | `claude --bare -p \"query\"` |\n| `--permission-mode ` | Start in `default`/`manual`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, or `plan`. | `claude --permission-mode plan` |\n| `--permission-prompt-tool ` | Specify an MCP tool to handle permission prompts in non-interactive mode. | `claude -p --permission-prompt-tool mcp_auth_tool \"query\"` |\n| `--fallback-model ` | In print mode, try a comma-separated fallback chain when the primary model is unavailable. | `claude -p --fallback-model sonnet,haiku \"query\"` |\n| `--effort ` | Set effort to `low`, `medium`, `high`, `xhigh`, or `max`, or start session-only `ultracode` mode where supported. | `claude --effort high` |\n| `--model ` | Model for the current session. Accepts aliases like `sonnet`/`opus` or a full model ID when pinning. | `claude --model sonnet` |\n| `--advisor ` | Set the experimental advisor for this session without changing `advisorModel`; intentionally omitted from `claude --help`. | `claude --advisor opus` |\n| `--settings ` | Load additional settings from a JSON file or a JSON string. | `claude --settings ./settings.json` |\n| `--add-dir ` | Additional directories to allow tool access to. | `claude --add-dir ../apps ../lib` |\n| `--ide` | Automatically connect to an IDE on startup if exactly one valid IDE is available. | `claude --ide` |\n| `-c, --continue` | Continue the most recent conversation in the current directory. | `claude --continue` |\n| `-r, --resume [sessionId]` | Resume a conversation; provide a session ID or interactively select one. | `claude -r \"abc123\"` |\n| `--session-id ` | Use a specific session ID for the conversation (must be a valid UUID). | `claude --session-id 123e4567-e89b-12d3-a456-426614174000` |\n| `--agents ` | Define custom subagents dynamically via JSON (see subagent docs for format). | `claude --agents '{\"reviewer\":{\"description\":\"Reviews code\",\"prompt\":\"...\"}}'` |\n| `--agent ` | Specify a specific agent for the current session. | `claude --agent my-custom-agent` |\n| `--bg` | Start or continue work as a background session that can be viewed from `claude agents`. | `claude --bg \"fix failing tests\"` |\n| `--bg --exec ` | Run a shell command as an attachable background session. | `claude --bg --exec \"npm test\"` |\n| `--name