Skip to main content

Installing and Authenticating Your Terminal Agent

In Lesson 1, you learned why Claude Code is revolutionary, and how OpenCode brings the same agentic, terminal-first model to the open-source world. Now comes the crucial step: getting one (or both) working on your machine.

This isn't just about following installation commands. It's about crossing the bridge from "interesting concept" to "tool I can actually use." By the end of this lesson, you will have your chosen terminal agent installed, authenticated, and ready to work with you on real tasks.

Pick one or install both

Claude Code is the general agent taught as the default in this chapter. OpenCode is the open-source coding agent shown as a parity track. Use the tabs in each section to follow the tool you choose; install commands, authentication paths, and verification steps all live under the right tab. You can also install both side by side; they don't conflict.

🔀 Two Setup Paths Available​

This lesson covers the official Claude subscription setup (Pro $20/month or Max $200/month). If you prefer a free/minimal cost alternative, see Lesson 3: Free Claude Code Setup.

Both paths teach identical Claude Code skills (subagents, skills, MCP, hooks covered in this chapter).

PathCostWhat You Get
This Lesson (Official)Pro: $20/month
Max: $200/month		Official Anthropic models (Claude Sonnet/Opus), direct integration, official support
Lesson 3 (Free/Minimal)$0 (free tier)
Pay-as-you-go option		Use Claude Code agent with any LLM (Gemini, GPT, local models), backend abstraction architecture

Key difference: Official path uses Anthropic's Claude models. Free path lets you use Claude Code's agentic architecture with any LLM backend through production-grade API routing.

Free Claude.ai Plan Does Not Include Claude Code

The free Claude.ai plan does not include Claude Code access. You need at least a Pro subscription ($20/month) to authenticate Claude Code with your Claude.ai account. Alternatively, use a Console API account with pay-per-use credits, or follow Lesson 3 for free backend options.

Prerequisites: What You Need Before Installing​

Before we begin, verify you have the following:

1. Terminal Access

  • Windows: Command Prompt, PowerShell, or Windows Terminal
  • macOS: Terminal app (Applications → Utilities → Terminal)
  • Linux: Any terminal emulator (GNOME Terminal, Konsole, etc.)
  • WSL Users: Any WSL 2 terminal with Ubuntu 20.04+ or Debian 10+

2. Claude Account (one of the following):

3. System Requirements

  • macOS: 13 (Ventura) or later
  • Windows: Windows 10 or later
  • Linux: Ubuntu 20.04+ / Debian 10+
  • RAM: 4 GB minimum

4. Optional (for npm installation only)

  • Node.js: Version 18 or later (only required if using npm installation method)
  • Deprecated: NPM installation is deprecated. Use the native installation method when possible.

Installation​

Claude Code installation has been simplified with official installers for each platform. Choose your tool tab, then your operating system tab below to see platform-specific installation methods.

Choose your operating system tab below.

⚠️ Important: Claude Code requires a bash-compatible shell to run. On Windows, you need either WSL or Git for Windows installed: the installer downloads Claude Code, but it runs inside a bash shell.

Decision Tree:

Which shell environment do you have (or want to install)?
├─ WSL (Windows Subsystem for Linux)
│   └─ Method 1 (WSL) - RECOMMENDED for best experience
│
├─ Git for Windows (Git Bash)
│   └─ Method 2 (Git Bash + PowerShell installer)
│
├─ Neither installed yet
│   └─ Install WSL first (see below), then use Method 1
│
└─ I have Node.js 18+ in WSL or Git Bash
    └─ Method 3 (npm) - See Cross-Platform npm section below

Why recommended: Full Linux environment, best compatibility, recommended by Anthropic.

Step 1: If you don't have WSL, install it first (run in PowerShell as Administrator):

wsl --install

Restart your computer after installation.

Step 2: Open your WSL terminal (Ubuntu) and run:

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

What this does: Downloads and executes the official installer script in your Linux environment.

Requirements: Windows 10 version 2004+ or Windows 11, WSL 1 or WSL 2

Method 2: Native Windows (PowerShell or CMD)​

When to use: You want to run Claude Code natively on Windows without WSL.

Option A - PowerShell:

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

Option B - Command Prompt (CMD):

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Requirements: Windows 10+, Git for Windows (provides the bash shell Claude Code needs)

Step 1: Install Git for Windows if not already installed.

Step 2: Run one of the install commands above.

Step 3: For portable Git installations, configure the bash path (run in PowerShell):

$env:CLAUDE_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"

To make this permanent, add to your PowerShell profile:

notepad $PROFILE
# Add the line: $env:CLAUDE_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"

Step 4: Run Claude Code:

claude

What this does: The installer downloads Claude Code; Git for Windows provides the bash shell it runs in.

Windows Installation Guide

For a detailed step-by-step Windows installation guide with screenshots, see: Claude Code Installation for Windows

Method 3: WinGet​

When to use: You prefer Windows Package Manager for installations.

winget install Anthropic.ClaudeCode

Requirements: Windows 10 1709+ with App Installer (pre-installed on Windows 11)

Windows Verification​

Open your shell (WSL terminal, Git Bash, or PowerShell) and check your installation:

claude --version

Expected output:

X.X.XX (Claude Code)

(Your version number will differ: Claude Code auto-updates frequently.)

💬 AI Colearning Prompt​

"Explain the difference between WSL and Git Bash for Windows developers. When would you choose one over the other for AI-native development workflows?"

Cross-Platform: npm Installation​

When to use this method:

  • You already have Node.js 18+ installed
  • You prefer npm-based workflows
  • You need to manage tool versions via package.json
  • Your platform isn't officially supported by platform-specific installers

Platforms: Windows, macOS, Linux, WSL

Deprecated

NPM installation is deprecated for Claude Code. Use the native installation method when possible.

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

What this does: Installs Claude Code globally via npm package manager.

Requirements: Node.js 18 or later (includes npm)

Check Node.js version:

node --version

If you see v18.0.0 or higher, you're good to go.

💬 AI Colearning Prompt​

"Explain the trade-offs between platform-specific installers (Homebrew, PowerShell) vs npm. When would a developer choose npm over the platform installer?"

Auto-Update Configuration​

Native Claude Code installations automatically check for updates and prompt you to install them. To disable auto-updates (useful for corporate environments or version pinning):

Recommended: settings.json (persistent, cross-platform):

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

Place this in your Claude Code settings file (~/.claude/settings.json on macOS/Linux, or %USERPROFILE%\.claude\settings.json on Windows).

Alternative: environment variable:

# macOS/Linux/WSL — add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export DISABLE_AUTOUPDATER=1
# Windows PowerShell — add to your PowerShell profile ($PROFILE)
$env:DISABLE_AUTOUPDATER=1

Manual update check:

claude update
Homebrew Users

Homebrew installations do not auto-update at all. Run brew upgrade claude-code to update manually.

Advanced: System Diagnostics​

After installation, verify your system configuration:

claude doctor

What this checks:

  • Installation integrity
  • Authentication status
  • System compatibility
  • Network connectivity to Claude API

Use this command if you encounter issues during installation or authentication.

🎓 Expert Insight​

In AI-native development, terminal comfort is a skill multiplier. The 5 minutes you invest learning basic terminal commands unlocks 10x productivity with AI tools. You're not becoming a "terminal expert": you're removing the friction between intent and execution.

Uninstallation​

If you need to remove your tool (for reinstallation or troubleshooting):

macOS/Linux/WSL (Native Install):

rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

Windows PowerShell:

Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force
Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force

Homebrew:

brew uninstall --cask claude-code

npm:

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

Optional: Remove Configuration Files

To also remove your settings and credentials:

macOS/Linux/WSL:

rm -rf ~/.claude
rm ~/.claude.json

Windows PowerShell:

Remove-Item -Path "$env:USERPROFILE\.claude" -Recurse -Force
Remove-Item -Path "$env:USERPROFILE\.claude.json" -Force

Authentication: Connecting Your Tool to a Provider​

Once installed, your tool needs to authenticate. Claude Code authenticates with your Claude account (subscription or Console API). OpenCode authenticates with whichever LLM provider(s) you choose: Anthropic, OpenAI, Google, OpenRouter, or 75+ others.

Claude Code has three authentication paths depending on your account type and use case.

Which Authentication Method Should I Use?​

Decision Tree:

What type of Claude access do you have?
├─ Claude.ai subscription (Pro, Max, Team)
│   └─ Method 1: Claude App Authentication (MOST COMMON)
│
├─ Claude Console account with API credits
│   └─ Method 2: Console API Authentication
│
└─ Enterprise account (Bedrock, Vertex AI, Foundry)
    └─ Method 3: Enterprise Authentication

If you have both subscription and Console API: Use Method 1 (Claude App): it's simpler and provides unified access.

🎓 Expert Insight​

In AI-native development, authentication isn't just about access: it's about resource management. Claude.ai (subscription) vs Console API (pay-per-use) vs Enterprise (dedicated capacity) represents different cost models and usage patterns. Understanding your workflow determines which path saves money.

Method 1: Subscription / Browser Authentication (Most Common)​

Who this is for: Users with Claude Pro ($20/month), Claude Max ($200/month), or Team subscriptions.

Benefits: Unified access across Claude web app and Claude Code, simpler authentication flow.

In your terminal, run:

claude

Expected output:

 Claude Code can be used with your Claude subscription or billed based on API usage through your
 Console account.

 Select login method:

 ❯ 1. Claude account with subscription · Pro, Max, Team, or Enterprise

   2. Anthropic Console account · API usage billing

Select Option 1. Your default browser opens to Claude.ai authentication. Log in, review permissions, and authorize.

Return to your terminal. You should see:

Logged in as mr.abc@gmail.com
Login successful. Press Enter to continue

Test your setup:

claude "Hello! Can you confirm Claude Code is working?"

Expected output: Claude responds confirming the connection works.

🤝 Practice Exercise​

Ask your AI: "I just installed Claude Code. Create a simple 'Hello World' workflow that: (a) shows me Claude can read a file, (b) proposes a small change, (c) explains what it did. Use a safe test file."

Expected Outcome: Confidence that Claude Code can read, propose changes, and explain actions: plus understanding of the approval workflow.

Method 2: API Key / Pay-Per-Use Authentication (Developers)​

Who this is for: Developers with Claude Console API credits but no Claude.ai subscription. Pay-per-use model based on token consumption.

Use case: API-first workflows, programmatic access, usage-based billing.

In your terminal, run:

claude

Expected output:

 Claude Code can be used with your Claude subscription or billed based on API usage through your
 Console account.

 Select login method:

   1. Claude account with subscription · Pro, Max, Team, or Enterprise

 ❯ 2. Anthropic Console account · API usage billing

Select Option 2. Go to https://console.anthropic.com/settings/keys, create an API key, copy it, and paste when prompted.

You should see:

API key validated successfully
Login successful. Press Enter to continue

Test your setup:

claude "Hello! Can you confirm Claude Code is working?"

Expected output: Claude responds confirming the connection works.

⚠️ Important for Console API Users:

  • Set usage limits in Console: https://console.anthropic.com/settings/limits
  • Monitor token usage (displayed after each interaction)
  • Console authentication uses API billing, not subscription credits
  • Consider cost management strategies for high-volume usage

Method 3: Enterprise Authentication (Advanced)​

Who this is for: Enterprise customers using Amazon Bedrock, Google Vertex AI, or Microsoft Foundry (dedicated capacity).

Use case: Organizations with existing cloud infrastructure, compliance requirements, or dedicated capacity needs.

Platform Options:

Amazon Bedrock Integration​

Claude Code can authenticate with Claude via AWS Bedrock:

Requirements:

  • AWS account with Bedrock access
  • Claude models enabled in Bedrock
  • AWS CLI configured with appropriate credentials

Configuration: Contact your Enterprise administrator for Bedrock configuration details specific to your organization.

Google Vertex AI Integration​

Claude Code can authenticate with Claude via Google Cloud Vertex AI:

Requirements:

  • Google Cloud account with Vertex AI access
  • Claude models enabled in Vertex AI
  • Google Cloud SDK configured

Configuration: Contact your Enterprise administrator for Vertex AI configuration details specific to your organization.

Microsoft Foundry​

Claude Code can connect to dedicated Claude capacity via Microsoft Foundry:

Requirements:

  • Microsoft Foundry account with dedicated capacity
  • Enterprise API keys

Configuration: Contact your Enterprise support team for Foundry setup.

📚 Enterprise Documentation: For detailed enterprise configuration, see https://docs.anthropic.com/en/api/claude-on-amazon-bedrock or contact your Enterprise administrator.

Security and Best Practices​

Before moving forward, let's address important security considerations:

1. File System Access

  • Claude Code can read and write files in directories where you run it
  • Best Practice: Start Claude Code sessions in project directories, not system directories
  • Review file changes Claude proposes before approving them

2. Command Execution

  • Claude Code can execute terminal commands with your permissions
  • Best Practice: Review commands Claude suggests, especially sudo or administrative commands
  • Claude Code will ask for approval before executing destructive actions

3. Cost Management (Console API Users)

Try With AI​

Now that Claude Code is installed, let's build confidence through safe exploration and establish good security practices.

🛡️ Establish Safety Boundaries:

"I just installed Claude Code and I'm nervous about file access and command execution. Help me set up safe boundaries: What directories should I AVOID running Claude Code in? What commands should I NEVER approve without careful review? Create a practical safety checklist I can follow until I'm more comfortable."

🎯 Practice First Commands:

"I completed installation successfully! Give me 3-5 safe 'Hello World' style prompts I can try RIGHT NOW that will: (a) verify Claude Code works, (b) won't modify important files, (c) demonstrate basic capabilities. Include what I should expect to see for each prompt."

🧪 Test Your Installation:

"Walk me through testing my Claude Code installation step-by-step. Start with checking the version, then test file reading (on a safe test file), then test a simple command execution (like checking current directory). Explain what each output means and how to know if something's wrong."

🚀 Configure for Your Workflow:

"I work primarily with [describe your tech stack: Python/JavaScript/Go/etc.]. Help me verify Claude Code can handle my environment: check for required tools, test reading my project structure, and suggest first productive task I could try that's relevant to my actual work."

Flashcards Study Aid​