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.

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

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

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