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

---

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

• 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

---

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.

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

---

• 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

---

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.

---

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.

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

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.mdLinux: /etc/claude-code/CLAUDE.mdWindows: 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.

---

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
/tasks	List the current session's background shells, subagents, and tool calls
/teleport [session]	Pull a cloud session's branch and conversation into this terminal (/tp alias)
/tui [default|fullscreen]	Switch the terminal renderer and relaunch with the conversation intact; with no argument, print the active renderer
/usage	Show session cost and prompt-cache hits, plan usage limits, and activity stats, with one-line fixes for warnings (/cost, /stats aliases)
/usage-credits	Configure usage credits, or on Team/Enterprise request them from your admin, when you hit a limit (formerly /extra-usage)
/verify	Build, run, and observe your app to confirm a change works beyond tests and type checks (bundled skill; Claude runs it only when you invoke it)
/voice [hold|tap|off]	Toggle voice dictation or choose its mode; needs a Claude.ai login
/workflows	Inspect dynamic workflow runs and background orchestration

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 --verbose --include-partial-messages "query"
--include-hook-events	Include hook lifecycle events in stream-json output.	claude -p --output-format stream-json --verbose --include-hook-events "query"
--forward-subagent-text	Forward subagent text/thinking with parent_tool_use_id in stream-json.	claude -p --output-format stream-json --verbose --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; requires --verbose).	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 --verbose --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; exits at startup if a managed-mcp.json is deployed.	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; pass the full mcp__<server>__<tool> name of a tool on an MCP server the run loads.	claude -p --mcp-config ./mcp.json --permission-prompt-tool mcp__permissions__approve "query"
--permission-prompts <host|none>	Print mode: host (default) sends prompts to the SDK host or --permission-prompt-tool; none denies anything that would prompt, while the permission mode decides the rest.	claude -p --permission-mode auto --permission-prompts none "query"
--fallback-model <models>	Comma-separated fallback chain for when the primary model is overloaded or unavailable (interactive or print mode); the primary is retried each turn. Overrides fallbackModel.	claude --fallback-model sonnet,haiku
--effort <level>	Set effort to low, medium, high, xhigh, or max; ultracode starts at xhigh with ultracode turned on.	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. Most network paths (UNC shares, /net automounts) are refused; on Windows, use a mapped drive letter.	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 [id|name]	Resume by session ID, name, or .jsonl transcript path, or open the picker; resuming a still-running background session attaches to it.	claude -r auth-refactor
--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|file>	Define custom subagents dynamically via inline JSON or, with -p, a path to a JSON file (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"
-n, --name <name>	Set a display name for any session (prompt box, /resume picker, terminal title); resume it later with claude --resume <name>.	claude -n auth-refactor
--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 a cloud session on claude.ai; with -p and a session ID or URL, queue a message into an existing one.	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]	Pull a cloud session into your local terminal; with no ID it opens a picker.	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; can be combined with --append-system-prompt (the file's text comes first).	claude --append-system-prompt-file ./extra-rules.txt
--system-prompt-snapshot <on|off>	on (default) reuses the prompt recorded on the first request, even after --resume/--continue, until compaction; off rebuilds it each request (for iterating on prompt flags).	claude -c --append-system-prompt "Draft rules" --system-prompt-snapshot off
--plugin-dir <path>	Load a plugin directory, a .zip, or a folder of plugins (each child with a manifest loads) 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
--allow-dangerously-skip-permissions	Add bypass mode to the Shift+Tab cycle without starting in it.	claude --permission-mode plan --allow-dangerously-skip-permissions
--safe-mode	Disable customizations (CLAUDE.md, skills, plugins and installed mods, hooks, MCP servers, and more) for troubleshooting; authentication, models, built-in tools, permissions, and managed policy still apply.	claude --safe-mode
--restricted	Locked-down session (also CLAUDE_CODE_RESTRICTED=1): removes built-in tools that run commands or code, and WebFetch, unless named in --tools; confines file tools to the working directories; ignores user/project/local settings; refuses bypassPermissions.	claude --restricted -p "query"
--worktree [name], -w [name]	Start in <repo>/.claude/worktrees/<name>; omit the name to generate one, or pass #<number> or a GitHub PR / GitLab MR URL to branch from it. Add --tmux for a tmux session.	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 and SessionStart hooks, then exit without starting a conversation.	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.

For programmatic integrations, the former Claude Code SDK is now the Claude Agent SDK: TypeScript uses @anthropic-ai/claude-agent-sdk, and Python uses claude-agent-sdk / claude_agent_sdk. Use claude -p for headless CLI calls; --bare removes discovered customization and keychain/OAuth access for low-overhead API/provider automation.

## Claude Cheat Sheet

# Start and resume

claude # Start interactive REPL
claude "explain this project" # Start REPL seeded with a prompt
claude -p "summarize README.md" # Non-interactive headless print mode
cat logs.txt | claude -p "explain" # Pipe input to Claude and exit
claude -c # Continue most recent conversation
claude -r "<session-id>" "finish this" # Resume by ID or name
claude --model sonnet # Pick the Sonnet alias for this run
claude --model opus # Pick the Opus alias for harder tasks

# Install, update, and auth

claude update # Manually update Claude Code
claude doctor # Diagnose install/version & setup
claude install stable # Install/reinstall the native binary on the stable channel
claude auth login # Log in to your Anthropic account
claude auth status # Check authentication status
claude auth logout # Log out
claude setup-token # Generate a long-lived OAuth token for CI and scripts (subscription)

# Background, cloud, and Remote Control sessions

claude agents # Open the live session dashboard: running, blocked, completed
claude agents --json # Scriptable JSON list of live/background sessions
claude --bg "run the integration suite and summarize failures" # Start a background session
claude --bg --exec "npm test" # Run a shell command as an attachable background session
claude attach <id|name> # Attach to a background session (part of its name works)
claude logs <id|name> # Print recent background-session output
claude stop <id> # Stop a background session
claude rm <id> # Remove it from agent view and delete its worktree; transcript remains resumable
claude remote-control # Serve local sessions to web/mobile while this process stays alive
claude --cloud "Fix the bug" # Start a cloud session on claude.ai
claude --teleport <session-id> # Pull a cloud session into this terminal

# Config essentials

/config # Interactive settings
/config model=sonnet # Set a supported key directly
/config theme=dark
/config --help # Show settable keys and values
# For shared or managed settings, edit the appropriate settings.json file.

# MCP essentials

claude mcp list # List configured MCP servers
claude mcp get <name> # Show details for a server
claude mcp add <name> -- <command> [args...] # Add local stdio server; `--` separates Claude's options from the server's
claude mcp add --transport http <name> <url> # Add remote HTTP server
claude mcp login <name> # Complete OAuth without opening /mcp
claude mcp logout <name> # Clear saved OAuth credentials
claude mcp reset-project-choices # Reset approvals for project .mcp.json servers
claude mcp serve # Run Claude Code itself as an MCP stdio server

# High-value flags

claude --add-dir ../apps ../lib # Add additional working directories
claude --allowed-tools "Bash(git log *)" "Read" # Allow listed tools without permission prompts
claude --disallowed-tools "Edit" # Deny listed tools
claude -p "query" --output-format json # Structured one-shot output
claude --verbose # Verbose logging (turn-by-turn)
claude --dangerously-skip-permissions # Skip permission prompts (use with caution)
claude --permission-mode plan # Start in plan mode without source edits
claude --effort high # Set reasoning effort for this session
claude --bare -p "query" # Fast scripted call without discovered customization
claude --safe-mode # Troubleshoot with user/project customization disabled
claude --ax-screen-reader # Use the accessible flat-text renderer
claude --max-turns 3 -p "query" # Limit agentic turns (print mode only)
claude --json-schema '{"type":"object"}' -p "query" # Get validated JSON output
claude --chrome # Enable Chrome browser integration
claude --agent code-reviewer # Run this session with a named agent
claude ultrareview 123 --trust-workspace --json # Non-interactive cloud review of PR 123; in scripts/CI, --trust-workspace trusts an untrusted folder for this run

# Slash shortcuts

claude --fork-session -r abc123 # Fork instead of reusing original
claude -w feature-auth "implement feature" # Start in an isolated git worktree
/rename auth-refactor # Name current session
/resume # Open session picker
/export output.md # Export conversation to file
/branch experiment-nam