Installation and Setup

Getting Claude Code up and running takes just a few minutes. In this lesson, you will install the tool, authenticate with Anthropic, and verify that everything is working correctly. By the end, you will have Claude Code ready to use in any project on your machine.

What You'll Learn

Prerequisites for running Claude Code
How to install Claude Code via npm
Authentication options: API keys and Claude subscriptions
Terminal recommendations for the best experience
The first launch walkthrough
Basic configuration with claude config
How to troubleshoot common installation issues

Prerequisites

Before installing Claude Code, make sure you have the following:

Node.js 18 or Higher

Claude Code is distributed as an npm package, so you need Node.js installed. Version 18 or higher is required.

Check your current Node.js version:

node --version
# Should output v18.x.x or higher (e.g., v20.11.0)

If you do not have Node.js installed or need to upgrade, visit nodejs.org and download the LTS (Long Term Support) version. Alternatively, you can use a version manager like nvm:

# Install nvm (Node Version Manager)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

# Install the latest LTS version of Node.js
nvm install --lts

# Verify the installation
node --version

npm

npm comes bundled with Node.js, so if you have Node.js installed, you already have npm. Verify it:

npm --version
# Should output 9.x.x or higher

A Terminal Application

Claude Code runs in your terminal. Any terminal application will work, but some provide a better experience than others. We will cover terminal recommendations later in this lesson.

An Anthropic Account

You need either an Anthropic API key or an active Claude Pro/Max subscription. We will cover authentication options in detail below.

Installing Claude Code

Installation is a single npm command:

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

The -g flag installs Claude Code globally, which means you can run it from any directory on your machine.

If you see a permission error on macOS or Linux, you may need to use sudo:

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

However, the better long-term solution is to fix your npm permissions so that global installs do not require sudo. You can do this by changing npm's default directory:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

Then add ~/.npm-global/bin to your PATH by adding this line to your ~/.zshrc or ~/.bashrc:

export PATH=~/.npm-global/bin:$PATH

Reload your shell configuration:

source ~/.zshrc  # or source ~/.bashrc

Then run the install command again without sudo.

Verifying the Installation

After installation, verify that Claude Code is available:

claude --version

You should see output showing the installed version number. If you get a "command not found" error, make sure your npm global bin directory is in your PATH.

You can check where npm installs global packages:

npm config get prefix

Make sure the bin subdirectory of that path is in your shell's PATH.

Authentication

When you run Claude Code for the first time, it will walk you through authentication. There are two ways to authenticate.

Option 1: Claude Pro or Max Subscription

If you have a Claude Pro or Max subscription at claude.ai, you can authenticate directly through your browser. When you first run claude, it will open a browser window for OAuth authentication. Sign in with your existing Claude account, and you are set.

This is the simplest option for individual developers. Your usage is covered by your subscription.

# First run - opens browser for authentication
claude

# You'll see something like:
# Opening browser for authentication...
# Waiting for authentication...
# Successfully authenticated!

Option 2: API Key

If you prefer to use an API key (for example, if you are using Claude Code in a team setting or want usage-based billing), you can set the ANTHROPIC_API_KEY environment variable.

First, get an API key from the Anthropic Console:

Sign in to console.anthropic.com
Navigate to API Keys
Create a new key
Copy the key (it starts with sk-ant-)

Then set it in your environment:

# Add to your ~/.zshrc or ~/.bashrc for persistence
export ANTHROPIC_API_KEY="sk-ant-your-key-here"

# Reload your shell
source ~/.zshrc

With an API key, you pay per usage based on the tokens consumed. This can be more cost-effective for light usage or more predictable for heavy usage, depending on your patterns.

Which Option Should You Choose?

Claude Pro/Max subscription: Best for individual developers who want a simple setup with predictable monthly billing. Max subscriptions come with higher usage limits.
API key: Best for teams, CI/CD pipelines, or developers who want fine-grained control over usage and costs.

You can switch between methods at any time.

Terminal Recommendations

Claude Code works in any terminal, but some terminals provide a better experience. Here are recommendations by platform.

macOS

iTerm2 -- The most popular terminal for macOS developers. It supports true color, has excellent font rendering, and handles long output well. This is the recommended option.
The built-in Terminal.app works fine for basic usage.
Warp is another modern terminal that works well with Claude Code.

Windows

Windows Terminal -- Microsoft's modern terminal application. It supports tabs, true color, and multiple shells (PowerShell, Command Prompt, WSL). This is the recommended option.
WSL (Windows Subsystem for Linux) -- If you use WSL, run Claude Code inside your Linux terminal for the best experience.

Linux

Most modern terminal emulators work well: GNOME Terminal, Konsole, Alacritty, Kitty, and others.
Make sure your terminal supports 256 colors or true color for the best output formatting.

VS Code Integrated Terminal

The VS Code integrated terminal works with Claude Code. This can be convenient because you can see Claude Code's changes reflected immediately in your editor.

# In VS Code, open the integrated terminal with:
# Ctrl+` (backtick) on Windows/Linux
# Cmd+` (backtick) on macOS

# Then run Claude Code as usual:
claude

Terminal Settings Tips

For the best experience with Claude Code:

Use a monospace font with good Unicode support (e.g., JetBrains Mono, Fira Code, or SF Mono)
Enable true color if your terminal supports it
Set a reasonable scrollback buffer -- Claude Code can produce long output, so a scrollback of 10,000+ lines is helpful
Use a dark theme -- Claude Code's output is designed to be readable on dark backgrounds

First Launch Walkthrough

Let us walk through what happens the first time you launch Claude Code in a project.

Step 1: Navigate to a Project

Open your terminal and navigate to a project directory. Claude Code works best when you launch it from the root of a project:

cd ~/projects/my-project

Step 2: Launch Claude Code

claude

Step 3: Authentication (First Time Only)

If this is your first time, Claude Code will prompt you to authenticate. Follow the instructions on screen -- either opening a browser for OAuth or confirming your API key is set.

Step 4: Accept the Terms

On first launch, Claude Code will ask you to review and accept the terms of service. Read through them and type yes to continue.

Step 5: The Welcome Screen

After authentication, you will see the Claude Code welcome screen. It shows:

The current working directory
The model being used
A prompt where you can start typing

Step 6: Start a Conversation

You are now ready to go. Try typing a simple prompt:

What is this project? Give me a high-level overview.

Claude Code will read your project files and give you a summary.

Configuration Basics

Claude Code has a configuration system that lets you customize its behavior. You can access it with the claude config command.

Viewing Configuration

# View all current configuration
claude config list

Setting Configuration Values

# Set a configuration value
claude config set <key> <value>

Common Configuration Options

Some useful configuration options include:

Preferred editor -- If Claude Code needs to open a file for you to review
Theme preferences -- Light or dark mode output
Default permissions -- Which actions Claude Code can take without asking

You can also configure Claude Code through configuration files, which we will cover in the lesson on the permission model.

The `--help` Flag

To see all available commands and options:

claude --help

This shows you every flag and subcommand available in Claude Code.

Updating Claude Code

Claude Code is actively developed, with frequent updates that add features and fix bugs. To update to the latest version:

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

Check your current version and compare with the latest:

# Your installed version
claude --version

# Check the latest available version
npm view @anthropic-ai/claude-code version

It is a good practice to update regularly, as new versions often include significant improvements to code quality, speed, and capabilities.

Troubleshooting Common Issues

"command not found: claude"

This means your shell cannot find the Claude Code binary. Common causes:

# Check where npm installs global packages
npm config get prefix

# The binary should be at <prefix>/bin/claude
# Make sure <prefix>/bin is in your PATH
echo $PATH

# If it's missing, add it to your shell config:
# For zsh (~/.zshrc):
export PATH="$(npm config get prefix)/bin:$PATH"

# For bash (~/.bashrc):
export PATH="$(npm config get prefix)/bin:$PATH"

# Reload your shell
source ~/.zshrc  # or source ~/.bashrc

Node.js Version Too Old

If you see an error about Node.js version requirements:

# Check your version
node --version

# If it's below 18, upgrade:
nvm install --lts
nvm use --lts

Permission Errors During Installation

On macOS and Linux, you might see EACCES errors:

# Option 1: Use sudo (quick fix)
sudo npm install -g @anthropic-ai/claude-code

# Option 2: Fix npm permissions (recommended)
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
# Add ~/.npm-global/bin to your PATH (see above)

Authentication Failures

If authentication is not working:

# For API key auth, verify the key is set:
echo $ANTHROPIC_API_KEY
# Should print your key (starting with sk-ant-)

# If it's empty, set it:
export ANTHROPIC_API_KEY="sk-ant-your-key-here"

# For browser auth, try clearing the cached credentials:
claude logout
claude  # This will re-trigger authentication

Network or Proxy Issues

If you are behind a corporate proxy or firewall:

# Set proxy for npm
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

# You may also need to set the proxy for Claude Code itself
export HTTPS_PROXY=http://proxy.company.com:8080

Claude Code Starts but Hangs

If Claude Code launches but seems unresponsive:

Make sure you have a stable internet connection (Claude Code communicates with Anthropic's API)
Check if your API key has sufficient credits (for API key users)
Try running with verbose output to see what is happening: claude --verbose

Summary

You now have Claude Code installed and ready to use. The setup process is straightforward: install Node.js, install Claude Code globally via npm, authenticate with either a subscription or API key, and launch it in your project directory.

In the next lesson, you will have your first real conversation with Claude Code and learn how to interact with it effectively.

Key Takeaways

Claude Code requires Node.js 18+ and is installed via npm install -g @anthropic-ai/claude-code
Authentication supports both Claude Pro/Max subscriptions (browser OAuth) and API keys (environment variable)
Verify your installation with claude --version
Launch Claude Code by typing claude in any project directory
Use claude config to customize behavior and claude --help to explore all options
Update regularly with npm update -g @anthropic-ai/claude-code
Most installation issues come from PATH configuration or Node.js version mismatches

Installation and Setup

What You'll Learn

Prerequisites for running Claude Code
How to install Claude Code via npm
Authentication options: API keys and Claude subscriptions
Terminal recommendations for the best experience
The first launch walkthrough
Basic configuration with claude config
How to troubleshoot common installation issues

Prerequisites

Before installing Claude Code, make sure you have the following:

Node.js 18 or Higher

Claude Code is distributed as an npm package, so you need Node.js installed. Version 18 or higher is required.

Check your current Node.js version:

node --version
# Should output v18.x.x or higher (e.g., v20.11.0)

If you do not have Node.js installed or need to upgrade, visit nodejs.org and download the LTS (Long Term Support) version. Alternatively, you can use a version manager like nvm:

# Install nvm (Node Version Manager)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

# Install the latest LTS version of Node.js
nvm install --lts

# Verify the installation
node --version

npm

npm comes bundled with Node.js, so if you have Node.js installed, you already have npm. Verify it:

npm --version
# Should output 9.x.x or higher

A Terminal Application

Claude Code runs in your terminal. Any terminal application will work, but some provide a better experience than others. We will cover terminal recommendations later in this lesson.

An Anthropic Account

You need either an Anthropic API key or an active Claude Pro/Max subscription. We will cover authentication options in detail below.

Installing Claude Code

Installation is a single npm command:

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

The -g flag installs Claude Code globally, which means you can run it from any directory on your machine.

If you see a permission error on macOS or Linux, you may need to use sudo:

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

However, the better long-term solution is to fix your npm permissions so that global installs do not require sudo. You can do this by changing npm's default directory:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

Then add ~/.npm-global/bin to your PATH by adding this line to your ~/.zshrc or ~/.bashrc:

export PATH=~/.npm-global/bin:$PATH

Reload your shell configuration:

source ~/.zshrc  # or source ~/.bashrc

Then run the install command again without sudo.

Verifying the Installation

After installation, verify that Claude Code is available:

claude --version

You should see output showing the installed version number. If you get a "command not found" error, make sure your npm global bin directory is in your PATH.

You can check where npm installs global packages:

npm config get prefix

Make sure the bin subdirectory of that path is in your shell's PATH.

Authentication

When you run Claude Code for the first time, it will walk you through authentication. There are two ways to authenticate.

Option 1: Claude Pro or Max Subscription

This is the simplest option for individual developers. Your usage is covered by your subscription.

# First run - opens browser for authentication
claude

# You'll see something like:
# Opening browser for authentication...
# Waiting for authentication...
# Successfully authenticated!

Option 2: API Key

If you prefer to use an API key (for example, if you are using Claude Code in a team setting or want usage-based billing), you can set the ANTHROPIC_API_KEY environment variable.

First, get an API key from the Anthropic Console:

Sign in to console.anthropic.com
Navigate to API Keys
Create a new key
Copy the key (it starts with sk-ant-)

Then set it in your environment:

# Add to your ~/.zshrc or ~/.bashrc for persistence
export ANTHROPIC_API_KEY="sk-ant-your-key-here"

# Reload your shell
source ~/.zshrc

With an API key, you pay per usage based on the tokens consumed. This can be more cost-effective for light usage or more predictable for heavy usage, depending on your patterns.

Which Option Should You Choose?

Claude Pro/Max subscription: Best for individual developers who want a simple setup with predictable monthly billing. Max subscriptions come with higher usage limits.
API key: Best for teams, CI/CD pipelines, or developers who want fine-grained control over usage and costs.

You can switch between methods at any time.

Terminal Recommendations

Claude Code works in any terminal, but some terminals provide a better experience. Here are recommendations by platform.

macOS

iTerm2 -- The most popular terminal for macOS developers. It supports true color, has excellent font rendering, and handles long output well. This is the recommended option.
The built-in Terminal.app works fine for basic usage.
Warp is another modern terminal that works well with Claude Code.

Windows

Windows Terminal -- Microsoft's modern terminal application. It supports tabs, true color, and multiple shells (PowerShell, Command Prompt, WSL). This is the recommended option.
WSL (Windows Subsystem for Linux) -- If you use WSL, run Claude Code inside your Linux terminal for the best experience.

Linux

Most modern terminal emulators work well: GNOME Terminal, Konsole, Alacritty, Kitty, and others.
Make sure your terminal supports 256 colors or true color for the best output formatting.

VS Code Integrated Terminal

The VS Code integrated terminal works with Claude Code. This can be convenient because you can see Claude Code's changes reflected immediately in your editor.

# In VS Code, open the integrated terminal with:
# Ctrl+` (backtick) on Windows/Linux
# Cmd+` (backtick) on macOS

# Then run Claude Code as usual:
claude

Terminal Settings Tips

For the best experience with Claude Code:

Use a monospace font with good Unicode support (e.g., JetBrains Mono, Fira Code, or SF Mono)
Enable true color if your terminal supports it
Set a reasonable scrollback buffer -- Claude Code can produce long output, so a scrollback of 10,000+ lines is helpful
Use a dark theme -- Claude Code's output is designed to be readable on dark backgrounds

First Launch Walkthrough

Let us walk through what happens the first time you launch Claude Code in a project.

Step 1: Navigate to a Project

Open your terminal and navigate to a project directory. Claude Code works best when you launch it from the root of a project:

cd ~/projects/my-project

Step 2: Launch Claude Code

claude

Step 3: Authentication (First Time Only)

If this is your first time, Claude Code will prompt you to authenticate. Follow the instructions on screen -- either opening a browser for OAuth or confirming your API key is set.

Step 4: Accept the Terms

On first launch, Claude Code will ask you to review and accept the terms of service. Read through them and type yes to continue.

Step 5: The Welcome Screen

After authentication, you will see the Claude Code welcome screen. It shows:

The current working directory
The model being used
A prompt where you can start typing

Step 6: Start a Conversation

You are now ready to go. Try typing a simple prompt:

What is this project? Give me a high-level overview.

Claude Code will read your project files and give you a summary.

Configuration Basics

Claude Code has a configuration system that lets you customize its behavior. You can access it with the claude config command.

Viewing Configuration

# View all current configuration
claude config list

Setting Configuration Values

# Set a configuration value
claude config set <key> <value>

Common Configuration Options

Some useful configuration options include:

Preferred editor -- If Claude Code needs to open a file for you to review
Theme preferences -- Light or dark mode output
Default permissions -- Which actions Claude Code can take without asking

You can also configure Claude Code through configuration files, which we will cover in the lesson on the permission model.

The `--help` Flag

To see all available commands and options:

claude --help

This shows you every flag and subcommand available in Claude Code.

Updating Claude Code

Claude Code is actively developed, with frequent updates that add features and fix bugs. To update to the latest version:

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

Check your current version and compare with the latest:

# Your installed version
claude --version

# Check the latest available version
npm view @anthropic-ai/claude-code version

It is a good practice to update regularly, as new versions often include significant improvements to code quality, speed, and capabilities.

Troubleshooting Common Issues

"command not found: claude"

This means your shell cannot find the Claude Code binary. Common causes:

# Check where npm installs global packages
npm config get prefix

# The binary should be at <prefix>/bin/claude
# Make sure <prefix>/bin is in your PATH
echo $PATH

# If it's missing, add it to your shell config:
# For zsh (~/.zshrc):
export PATH="$(npm config get prefix)/bin:$PATH"

# For bash (~/.bashrc):
export PATH="$(npm config get prefix)/bin:$PATH"

# Reload your shell
source ~/.zshrc  # or source ~/.bashrc

Node.js Version Too Old

If you see an error about Node.js version requirements:

# Check your version
node --version

# If it's below 18, upgrade:
nvm install --lts
nvm use --lts

Permission Errors During Installation

On macOS and Linux, you might see EACCES errors:

# Option 1: Use sudo (quick fix)
sudo npm install -g @anthropic-ai/claude-code

# Option 2: Fix npm permissions (recommended)
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
# Add ~/.npm-global/bin to your PATH (see above)

Authentication Failures

If authentication is not working:

# For API key auth, verify the key is set:
echo $ANTHROPIC_API_KEY
# Should print your key (starting with sk-ant-)

# If it's empty, set it:
export ANTHROPIC_API_KEY="sk-ant-your-key-here"

# For browser auth, try clearing the cached credentials:
claude logout
claude  # This will re-trigger authentication

Network or Proxy Issues

If you are behind a corporate proxy or firewall:

# Set proxy for npm
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

# You may also need to set the proxy for Claude Code itself
export HTTPS_PROXY=http://proxy.company.com:8080

Claude Code Starts but Hangs

If Claude Code launches but seems unresponsive:

Make sure you have a stable internet connection (Claude Code communicates with Anthropic's API)
Check if your API key has sufficient credits (for API key users)
Try running with verbose output to see what is happening: claude --verbose

Summary

In the next lesson, you will have your first real conversation with Claude Code and learn how to interact with it effectively.

Key Takeaways

Claude Code requires Node.js 18+ and is installed via npm install -g @anthropic-ai/claude-code
Authentication supports both Claude Pro/Max subscriptions (browser OAuth) and API keys (environment variable)
Verify your installation with claude --version
Launch Claude Code by typing claude in any project directory
Use claude config to customize behavior and claude --help to explore all options
Update regularly with npm update -g @anthropic-ai/claude-code
Most installation issues come from PATH configuration or Node.js version mismatches

Installation and Setup

Installation and Setup

What You'll Learn

Prerequisites

Node.js 18 or Higher

npm

A Terminal Application

An Anthropic Account

Installing Claude Code

Verifying the Installation

Authentication

Option 1: Claude Pro or Max Subscription

Option 2: API Key

Which Option Should You Choose?

Terminal Recommendations

macOS

Windows

Linux

VS Code Integrated Terminal

Terminal Settings Tips

First Launch Walkthrough

Step 1: Navigate to a Project

Step 2: Launch Claude Code

Step 3: Authentication (First Time Only)

Step 4: Accept the Terms

Step 5: The Welcome Screen

Step 6: Start a Conversation

Configuration Basics

Viewing Configuration

Setting Configuration Values

Common Configuration Options

The --help Flag

Updating Claude Code

Troubleshooting Common Issues

"command not found: claude"

Node.js Version Too Old

Permission Errors During Installation

Authentication Failures

Network or Proxy Issues

Claude Code Starts but Hangs

Summary

Key Takeaways

Cuestionario

Discussion

Installation and Setup

Installation and Setup

What You'll Learn

Prerequisites

Node.js 18 or Higher

npm

A Terminal Application

An Anthropic Account

Installing Claude Code

Verifying the Installation

Authentication

Option 1: Claude Pro or Max Subscription

Option 2: API Key

Which Option Should You Choose?

Terminal Recommendations

macOS

Windows

Linux

VS Code Integrated Terminal

Terminal Settings Tips

First Launch Walkthrough

Step 1: Navigate to a Project

Step 2: Launch Claude Code

Step 3: Authentication (First Time Only)

Step 4: Accept the Terms

Step 5: The Welcome Screen

Step 6: Start a Conversation

Configuration Basics

Viewing Configuration

Setting Configuration Values

Common Configuration Options

The --help Flag

Updating Claude Code

Troubleshooting Common Issues

"command not found: claude"

Node.js Version Too Old

The `--help` Flag

The `--help` Flag