1.1 Environment Setup

This section walks you through installing Claude Code and its dependencies.

System Requirements

Before installing Claude Code, ensure your system meets these requirements:

Requirement	Details
Operating System	macOS 10.15+, Ubuntu 20.04+ / Debian 10+, or Windows via WSL2
Git	Version 2.0 or higher
RAM	4GB minimum (8GB recommended)
Internet	Required for API calls to Claude

Step 1: Open a Terminal

Before running any commands, you'll need a terminal — the app where you type commands and see their output.

macOS

• Press Cmd + Space to open Spotlight, type Terminal, and press Return.
• Or open Finder → Applications → Utilities → Terminal.

Windows

• Open the Start menu, type Windows Terminal (or PowerShell), and press Enter.
• On Windows 10 without Windows Terminal, PowerShell works fine.

Linux

• Press Ctrl + Alt + T, or search for Terminal in your app launcher.

Leave this window open — you'll use it for the rest of the setup steps.

Step 2: Verify Git Installation

Confirm Git is available:

git --version

If not installed:

macOS:

brew install git

Ubuntu/Debian:

sudo apt-get install git

Step 3: Install and Authenticate GitHub CLI

The GitHub CLI (gh) makes it easy to clone private repositories and interact with GitHub from the command line. Claude Code can use it for Git operations.

Install GitHub CLI

macOS:

brew install gh

Ubuntu/Debian:

sudo apt install gh

Authenticate with GitHub

gh auth login

Follow the prompts to authenticate. Choose:

• GitHub.com (unless you're using GitHub Enterprise)
• HTTPS for the preferred protocol
• Login with a web browser for the easiest authentication flow

Verify authentication:

gh auth status

You should see confirmation that you're logged in.

Step 4: Install Claude Code

Install Claude Code using the native installer:

macOS / Linux / WSL:

curl -fsSL https://claude.ai/install.sh | bash

Windows (PowerShell):

irm https://claude.ai/install.ps1 | iex

Homebrew (macOS/Linux):

brew install --cask claude-code

Verify the installation:

claude --version

You should see version information for Claude Code.

Already installed via npm?

The npm installation method (npm install -g @anthropic-ai/claude-code) is deprecated. To migrate to the native installer, run:

claude install

This switches you to the native binary with automatic background updates. Verify with claude doctor.

Step 5: Authenticate with Claude Code

Claude Code requires a subscription or an API key. For the purposes of this program, subscription login is recommended and API key login is not recommended unless directed otherwise.

Authenticating With A Subscription (Recommended)

Launch Claude Code in your terminal

claude

If you're already signed in, run the login command to reconfigure how you're signed in. Otherwise, you'll be prompted with login options automatically.

/login

Select login option (1) "Claude account with subscription". You'll be prompted to sign in to your Claude subscription account via your browser.

This is all you need

Signing in with your Claude subscription (above) uses your browser to securely connect Claude Code to your account — this is sometimes called an "OAuth" login. For this program, you do not need an Anthropic API key. The API key steps below are only for people who don't have a qualifying Claude subscription, or who are told by a later lesson to use one specifically.

Cost implications of API keys

Subscription login is a flat-rate seat — there's no metered usage to worry about. An API key is billed per token with no default spending cap. If a bug causes runaway usage (for example, a CI job stuck retrying, or an agent caught in a loop), an API key can rack up significant, unexpected charges before anyone notices; a subscription cannot.

If you do need an API key, set a spend limit at console.anthropic.com (Settings > Billing) before running anything unattended, especially in CI.

Using An API Key (Not Recommended)

Only follow this path if you don't have a qualifying Claude subscription, or a later lesson tells you to use a key specifically.

Getting an API key

Generating an Anthropic API key requires approval first — ask in #liatrio-forge before you create one. Once approved:

1. Go to console.anthropic.com
2. Sign in or create an account
3. Navigate to API Keys
4. Create a new key and copy it securely
5. Set a spend limit under Settings > Billing before you use the key for anything

Treat your API key like a password

An API key is a secret credential — anyone who has it can use your account and run up charges on your behalf.

• Never paste it into a chat, email, Slack message, or document
• Never commit it to a Git repository — even a private one. Once a secret is in Git history and pushed, assume it is compromised.
• Do not hardcode it into any file in your project — use environment variables or the config file options below
• If your key was exposed or you're unsure, rotate it immediately at console.anthropic.com under API Keys

With a key in hand, configure Claude Code using either option below — you do not need both.

Option A: Environment Variable

Set the ANTHROPIC_API_KEY environment variable:

export ANTHROPIC_API_KEY="your-api-key-here"

Add this to your shell profile (~/.bashrc, ~/.zshrc, etc.) to persist across sessions.

Option B: Configuration File

Claude Code can store your API key in its configuration. Run:

claude config set apiKey your-api-key-here

Step 6: Configure Git Identity (If Needed)

Claude Code creates commits on your behalf. Ensure Git knows who you are:

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Troubleshooting

"command not found: claude"

If you see this error after installation:

1. Ensure ~/.local/bin is in your PATH
2. Add it to your shell profile if needed:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

For Zsh users, replace ~/.bashrc with ~/.zshrc.

WSL2-Specific Issues

Ensure you're running commands inside WSL2, not Windows PowerShell or CMD. Your prompt should show a Linux path (e.g., ~/projects) not a Windows path (e.g., C:\Users\...).

Claude Code crashes with EAGAIN/pgrep errors on macOS

Symptoms: 100% CPU, hundreds of pgrep processes, and crashes like:

Uncaught exception (loop): Error: EAGAIN: resource temporarily unavailable,
posix_spawn '/opt/homebrew/bin/pgrep' at node:child_process:667:35
Uncaught exception loop detected (10 in 5000ms) — forcing shutdown

Cause: Homebrew's proctools installs a pgrep (at /opt/homebrew/bin/pgrep on Apple Silicon, /usr/local/bin/pgrep on Intel) that ignores -P, so Claude Code's child-process tracking walks the whole process tree until the OS runs out of resources.

Fix:

brew uninstall proctools

If you need proctools, ensure /usr/bin precedes Homebrew paths in PATH.

Verify: which pgrep should print /usr/bin/pgrep.

Next Steps

With Claude Code installed, proceed to the next section to verify everything works correctly and learn the basic commands.

Knowledge Check

Question 1 of 6

1.1 Environment Setup Knowledge Check

Q1. You've just installed Claude Code on a fresh Ubuntu machine and run `claude`, but the shell says 'command not found'. Git and the GitHub CLI both work fine. What is the most likely cause?

• The native installer did not complete successfully and needs to be re-run
• `~/.local/bin` is not in your PATH, so the shell cannot locate the `claude` binary
• Claude Code requires a full system restart before the binary becomes available
• Claude Code depends on Node.js, which has not been installed yet