1.1 Environment Setup
This section walks you through installing Claude Code and its dependencies.
Step 5 below signs Claude Code in against a Claude subscription. If you don't have one yet, complete 1.05 Setting Up Claude Max before you get there.
Steps 1–4 below (opening a terminal, Git, the GitHub CLI, and your Git identity) always happen in a terminal — that's true no matter how you plan to use Claude Code day-to-day. Steps 5–6 are where you actually install and authenticate Claude Code, and there you get a choice: the terminal CLI or the Claude Code Desktop app. Both tabs are provided there — pick whichever surface you want to use. Everything from 1.2 Verify Installation onward works the same either way.
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 + Spaceto open Spotlight, typeTerminal, and pressReturn. - Or open Finder → Applications → Utilities → Terminal.
Windows
- Open the Start menu, type
Windows Terminal(orPowerShell), and pressEnter. - On Windows 10 without Windows Terminal,
PowerShellworks fine.
Linux
- Press
Ctrl + Alt + T, or search forTerminalin 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: 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"
Step 5: Install Claude Code
- Terminal CLI
- Claude Code Desktop
Install 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.
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.
Download and install the Claude Desktop app from claude.ai/download (available for macOS, Windows, and Linux). This is a separate installer from the terminal CLI above — you don't need to run the native installer if you're only using the Desktop app.
Open the app, sign in, and click the Code tab in the sidebar — this is Claude Code running with a graphical interface instead of the terminal. The Desktop app requires a Pro, Max, Team, or Enterprise Claude subscription (or configured API access).
The terminal CLI and Desktop app aren't mutually exclusive — many people use both, since they share configuration (~/.claude/settings.json, MCP servers, CLAUDE.md files) and run the same underlying engine. If you're unsure which you'll prefer, it doesn't hurt to install both and decide later.
Step 6: 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.
- Terminal CLI
- Claude Code Desktop
Authenticating With A Subscription (Recommended)
Forge runs on a Claude Max subscription — see 1.05 Setting Up Claude Max if you haven't set one up yet.
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.
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.
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:
- Go to console.anthropic.com
- Sign in or create an account
- Navigate to API Keys
- Create a new key and copy it securely
- Set a spend limit under Settings > Billing before you use the key for anything
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
Authenticating With A Subscription (Recommended)
Forge runs on a Claude Max subscription — see 1.05 Setting Up Claude Max if you haven't set one up yet.
Open the Code tab and sign in with your Claude subscription account when prompted — this uses the same browser-based ("OAuth") login flow as the terminal CLI, just triggered automatically the first time you open the tab.
For this program, you do not need an Anthropic API key. The API key note below is only for people who don't have a qualifying Claude subscription, or who are told by a later lesson to use one specifically.
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, an API key can rack up significant, unexpected charges before anyone notices; a subscription cannot.
Using An API Key (Not Recommended)
The Desktop app doesn't have a dedicated screen for entering an API key directly — it authenticates through the same account sign-in as above. If a later lesson directs you to use an API key with the Desktop app (for example, for an Enterprise deployment), follow Anthropic's current documentation for the in-app configuration path, since this varies by deployment.
Troubleshooting
"command not found: claude"
If you see this error after installation:
- Ensure
~/.local/binis in your PATH - 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.