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?"

OpenCode is an open source AI coding agent. It works in your terminal with a wide selection of LLM providers (Claude, GPT, Gemini, local models, and 75+ others).

⚠️ Recommended: Use Windows Subsystem for Linux (WSL) for the best experience on Windows.

Method 1: WSL (RECOMMENDED)

wsl --install

Restart, then in your WSL terminal run:

curl -fsSL https://opencode.ai/install | bash

Method 2: Chocolatey

choco install opencode

Method 3: Scoop

scoop install opencode

Method 4: npm (cross-platform)

npm install -g opencode-ai

Windows Verification​

opencode --version
OpenCode Prerequisites

OpenCode runs best in modern terminal emulators like WezTerm, Alacritty, Ghostty, or Kitty. You also need API keys for at least one LLM provider (configured during first run).

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)

OpenCode is published as a Node package and can also be installed via Bun, pnpm, or Yarn:

# npm
npm install -g opencode-ai

# Bun
bun install -g opencode-ai

# pnpm
pnpm install -g opencode-ai

# Yarn
yarn global add opencode-ai

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.

OpenCode does not ship a doctor subcommand. To verify your setup:

opencode --version
opencode auth list

opencode auth list shows the providers you've authenticated. Use this if a provider isn't appearing in /models after running /connect.

🎓 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

macOS/Linux/WSL:

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

Homebrew:

brew uninstall opencode

npm:

npm uninstall -g opencode-ai

Chocolatey (Windows):

choco uninstall opencode

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

macOS/Linux/WSL:

rm -rf ~/.local/share/opencode
rm -rf ~/.config/opencode

OpenCode stores credentials at ~/.local/share/opencode/auth.json and config under ~/.config/opencode/.

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.

OpenCode uses a single /connect flow inside the TUI. From there you pick the provider (Anthropic, OpenAI, OpenCode Zen, GitHub Copilot, OpenRouter, and many more) and either authenticate via OAuth/browser or paste an API key. Credentials are stored in ~/.local/share/opencode/auth.json.

You can authenticate with multiple providers in the same OpenCode install and switch between them via /models.

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.

Decision Tree:

Which provider do you want to use?
├─ New to LLM providers / want curated models
│   └─ OpenCode Zen (recommended starter)
│
├─ Anthropic API key or Claude Pro/Max subscription
│   └─ Anthropic provider via /connect
│
├─ ChatGPT Plus/Pro or OpenAI API key
│   └─ OpenAI provider via /connect
│
├─ GitHub Copilot subscription
│   └─ GitHub Copilot via /connect (device flow)
│
├─ Enterprise (Bedrock, Vertex AI, Azure)
│   └─ Environment variable auth
│
└─ Local models (Ollama, llama.cpp, LM Studio)
    └─ Configure baseURL in opencode.json

If you're new: start with OpenCode Zen. It's the curated set of models the OpenCode team has tested.

🎓 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.

Who this is for: Anyone wanting to start fast with a curated, tested model set, or developers with an API key for any of the 75+ supported providers.

Recommended starter (OpenCode Zen):

Launch OpenCode:

opencode

In the TUI, run the connect command:

/connect

Select OpenCode Zen, then visit opencode.ai/zen to sign in, add billing, and copy your API key. Paste it in the terminal:

┌ API key
│
│
└ enter

Then list and pick a model:

/models

Alternative: Anthropic provider via API key:

/connect

Select Anthropic, choose Manually enter API Key, then paste an API key from console.anthropic.com.

Claude Pro/Max in OpenCode

Anthropic does not authorize using Claude Pro/Max subscriptions outside Claude Code. For OpenCode, use Anthropic API keys (Console billing) or pick a different provider.

Test your setup by asking a question in the TUI:

Hello! Can you confirm OpenCode is working?

🤝 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

Who this is for: Developers using API keys directly with any of the 75+ supported providers (Anthropic, OpenAI, Groq, DeepSeek, OpenRouter, etc.).

Use case: Pay-per-use across multiple providers, programmatic access, usage-based billing, mixing models per task.

Launch OpenCode and run /connect:

opencode
/connect

Search for your provider (for example, Groq, DeepSeek, OpenRouter, Cerebras, Fireworks AI), and paste your API key when prompted:

┌ API key
│
│
└ enter

Then pick a model:

/models

Special flow: GitHub Copilot (device flow):

/connect

Select GitHub Copilot, then visit github.com/login/device and enter the displayed code:

┌ Login with GitHub Copilot
│
│ https://github.com/login/device
│
│ Enter code: 8F43-6FCF
│
└ Waiting for authorization...

Special flow: ChatGPT Plus/Pro browser auth:

Run /connect, select OpenAI, then ChatGPT Plus/Pro. Your browser opens for authentication.

⚠️ Important for OpenCode API Users:

  • Each provider has its own billing dashboard. Set usage limits there.
  • Token usage is reported per request inside the TUI.
  • Run opencode auth list to see all configured providers.
  • You can configure multiple providers and switch between them with /models.

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.

Who this is for: Enterprise teams running OpenCode against Amazon Bedrock, Google Vertex AI, Azure OpenAI, or SAP AI Core.

Use case: Compliance-bound deployments, regional data residency, dedicated capacity, or unified billing through a cloud provider.

Amazon Bedrock:

# Option 1: AWS access keys
AWS_ACCESS_KEY_ID=XXX AWS_SECRET_ACCESS_KEY=YYY opencode

# Option 2: Named AWS profile
AWS_PROFILE=my-profile opencode

# Option 3: Bedrock bearer token
AWS_BEARER_TOKEN_BEDROCK=XXX opencode

Or persist via ~/.bash_profile:

export AWS_PROFILE=my-dev-profile
export AWS_REGION=us-east-1

For project-specific configuration, use opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "amazon-bedrock": {
      "options": {
        "region": "us-east-1",
        "profile": "my-aws-profile"
      }
    }
  }
}

Google Vertex AI:

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
export GOOGLE_CLOUD_PROJECT=your-project-id
export VERTEX_LOCATION=global
opencode

Or authenticate with the gcloud CLI:

gcloud auth application-default login

Azure OpenAI:

Run /connect, search for Azure, paste your API key, then set the resource name:

export AZURE_RESOURCE_NAME=your-resource-name

📚 Enterprise Documentation: See opencode.ai/docs/providers for full provider configuration including SAP AI Core, Cloudflare AI Gateway, and Vercel AI Gateway.

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​