​
System requirements

  • Operating Systems: macOS 10.15+, Ubuntu 20.04+/Debian 10+, or Windows via WSL
  • Hardware: 4GB RAM minimum
  • Software:
    • Node.js 18+
    • git 2.23+ (optional)
    • GitHub or GitLab CLI for PR workflows (optional)
  • Network: Internet connection required for authentication and AI processing
  • Location: Available only in supported countries

​
Install and authenticate

1

Install Claude Code

Install NodeJS 18+, then run:

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

Do NOT use sudo npm install -g as this can lead to permission issues and security risks. If you encounter permission errors, see configure Claude Code for recommended solutions.

2

Navigate to your project

cd your-project-directory
3

Start Claude Code

claude
4

Complete authentication

Claude Code offers multiple authentication options:

  1. Anthropic Console: The default option. Connect through the Anthropic Console and complete the OAuth process. Requires active billing at console.anthropic.com.
  2. Claude App (with Pro or Max plan): Subscribe to Claude’s Pro or Max plan for a unified subscription that includes both Claude Code and the web interface. Get more value at the same price point while managing your account in one place. Log in with your Claude.ai account. During launch, choose the option that matches your subscription type.
  3. Enterprise platforms: Configure Claude Code to use Amazon Bedrock or Google Vertex AI for enterprise deployments with your existing cloud infrastructure.

​
Initialize your project

For first-time users, we recommend:

1

Start Claude Code

claude
2

Run a simple command

> summarize this project
3

Generate a CLAUDE.md project guide

/init
4

Commit the generated CLAUDE.md file

Ask Claude to commit the generated CLAUDE.md file to your repository.

​
Troubleshooting

​
Troubleshooting WSL installation

Currently, Claude Code does not run directly in Windows, and instead requires WSL.

You might encounter the following issues in WSL:

OS/platform detection issues: If you receive an error during installation, WSL may be using Windows npm. Try:

  • Run npm config set os linux before installation
  • Install with npm install -g @anthropic-ai/claude-code --force --no-os-check (Do NOT use sudo)

Node not found errors: If you see exec: node: not found when running claude, your WSL environment may be using a Windows installation of Node.js. You can confirm this with which npm and which node, which should point to Linux paths starting with /usr/ rather than /mnt/c/. To fix this, try installing Node via your Linux distribution’s package manager or via nvm.

​
Optimize your terminal setup

Claude Code works best when your terminal is properly configured. Follow these guidelines to optimize your experience.

Supported shells:

  • Bash
  • Zsh
  • Fish

​
Themes and appearance

Claude cannot control the theme of your terminal. That’s handled by your terminal application. You can match Claude Code’s theme to your terminal during onboarding or any time via the /config command

​
Line breaks

You have several options for entering linebreaks into Claude Code:

  • Quick escape: Type \ followed by Enter to create a newline
  • Keyboard shortcut: Press Option+Enter (Meta+Enter) with proper configuration

To set up Option+Enter in your terminal:

For Mac Terminal.app:

  1. Open Settings → Profiles → Keyboard
  2. Check “Use Option as Meta Key”

For iTerm2 and VSCode terminal:

  1. Open Settings → Profiles → Keys
  2. Under General, set Left/Right Option key to “Esc+”

Tip for iTerm2 and VSCode users: Run /terminal-setup within Claude Code to automatically configure Shift+Enter as a more intuitive alternative.

​
Notification setup

Never miss when Claude completes a task with proper notification configuration:

​
Terminal bell notifications

Enable sound alerts when tasks complete:

claude config set --global preferredNotifChannel terminal_bell

For macOS users: Don’t forget to enable notification permissions in System Settings → Notifications → [Your Terminal App].

​
iTerm 2 system notifications

For iTerm 2 alerts when tasks complete:

  1. Open iTerm 2 Preferences
  2. Navigate to Profiles → Terminal
  3. Enable “Silence bell” and Filter Alerts → “Send escape sequence-generated alerts”
  4. Set your preferred notification delay

Note that these notifications are specific to iTerm 2 and not available in the default macOS Terminal.

​
Handling large inputs

When working with extensive code or long instructions:

  • Avoid direct pasting: Claude Code may struggle with very long pasted content
  • Use file-based workflows: Write content to a file and ask Claude to read it
  • Be aware of VS Code limitations: The VS Code terminal is particularly prone to truncating long pastes

​
Vim Mode

Claude Code supports a subset of Vim keybindings that can be enabled with /vim or configured via /config.

The supported subset includes:

  • Mode switching: Esc (to NORMAL), i/I, a/A, o/O (to INSERT)
  • Navigation: h/j/k/l, w/e/b, 0/$/^, gg/G
  • Editing: x, dw/de/db/dd/D, cw/ce/cb/cc/C, . (repeat)