Introduction & Installation

What is Claude Code?

Claude Code is an official CLI (Command Line Interface) AI coding tool developed by Anthropic. You can write, edit, and analyze code by conversing with AI directly in your terminal.

Unlike web-based AI chat, Claude Code integrates directly into your local development environment, allowing you to access the file system, execute terminal commands, explore your codebase, and more—all using natural language.

Key Features

• Terminal-Native: Use it directly in your terminal without any IDE plugins
• Agentic Coding: AI directly performs file read/write, command execution, and Git operations
• Context-Aware: Understands your project structure and automatically explores relevant files
• Extensible: Infinitely expandable with MCP, sub-agents, and Hooks

System Requirements

Before installing Claude Code, verify that you meet the following requirements.

Notes for Windows Users

On Windows, WSL2 (Windows Subsystem for Linux 2) is required. Running directly in the native Windows Command Prompt or PowerShell is not supported.

# Install WSL2 (run in Administrator PowerShell)
wsl --install
 
# Install Node.js inside WSL2
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

Installation

Global Install via npm

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

Once installed, the claude command will be available globally.

Verify Installation

claude --version

Update

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

First Run

Running the claude Command

Navigate to your project directory and type claude.

cd ~/my-project
claude

Setting Up Your API Key

On first run, you need to configure your Anthropic API key. There are two ways to do this.

Method 1: Set an Environment Variable

export ANTHROPIC_API_KEY="sk-ant-api03-..."

For a permanent setting, add it to ~/.bashrc or ~/.zshrc.

echo 'export ANTHROPIC_API_KEY="sk-ant-api03-..."' >> ~/.bashrc
source ~/.bashrc

Method 2: Interactive Input on First Run

When you run claude, a prompt will automatically appear to guide you through entering your API key.

One-Shot Mode

You can also execute a single command without entering interactive mode.

claude -p "Explain the structure of this project"

Basic Usage

Interactive Mode

Running claude enters interactive REPL mode. Type your requests in natural language and Claude will respond.

> Find and clean up unused imports in this project

Claude explores the files and finds and removes unnecessary imports.

Tips for Writing Prompts

• Be specific: Instead of "fix the code," try "add null handling to the parseDate function in src/utils.ts"
• Provide context: "This project uses Next.js 14"
• Break it down: Split complex tasks into multiple steps

File Editing Workflow

Claude Code can directly modify files. Before making changes, it always shows a diff and waits for your approval.

> Add a loading state prop to src/components/Button.tsx

Claude reads the file, shows the changes as a diff, and applies them once you approve.

Model Selection Guide

Claude Code supports multiple Claude models. Choose the one that fits your task.

Claude Opus 4.6

Claude Sonnet 4.6

Claude Haiku 4.5

How to Switch Models

• Alt+P: Keyboard shortcut to switch models during a conversation
• /model: Model selection command
• /fast: Toggle Fast Mode (same model, faster output)

# Start with a specific model
claude --model claude-opus-4-6

Configuration File Structure

Claude Code uses multiple layers of configuration files.

~/.claude/settings.json (User Global Settings)

Global settings that apply to all projects.

{
  "permissions": {
    "allow": ["Bash(npm test)", "Read"],
    "deny": ["Bash(rm -rf)"]
  },
  "env": {
    "CLAUDE_MODEL": "claude-sonnet-4-6"
  }
}

CLAUDE.md (Project Memory)

Located at the project root, it provides project context to Claude.

# Project Rules
 
- Use TypeScript strict mode
- Write tests with Vitest
- Commit messages follow Conventional Commits format

.claude/ Directory

Stores project-specific settings, agents, and commands.

.claude/
  settings.json          # Project settings (shared with team)
  settings.local.json    # Local-only settings (excluded from Git)
  agents/                # Custom sub-agents
  commands/              # Custom slash commands

Keyboard Shortcuts

Key shortcuts available in interactive mode.

Main Slash Commands

Troubleshooting

Here are common issues and solutions that you may encounter while installing and using Claude Code.

Node.js Version Issues

Claude Code requires Node.js 18.0 or higher. It will not run if an older version is installed.

# Check current Node.js version
node --version
 
# Install the latest LTS version with nvm (recommended)
nvm install 20
nvm use 20
nvm alias default 20
 
# If nvm is not installed, install it first
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

Symptoms: error: Unsupported engine or SyntaxError: Unexpected token messages appear

Solution: Upgrade to Node.js 20.x LTS. Using nvm (Node Version Manager) makes it easy to manage multiple versions.

WSL2 Network Issues

Network connection errors that Windows users may experience in the WSL2 environment.

# Check DNS settings
cat /etc/resolv.conf
 
# Manually configure DNS if it's not working
sudo bash -c 'echo "nameserver 8.8.8.8" > /etc/resolv.conf'
 
# Reset WSL2 network (run in Administrator PowerShell)
# wsl --shutdown
# Then restart WSL

Symptoms: Network-related errors such as ETIMEDOUT, ENOTFOUND, getaddrinfo failed

Solution: Check the DNS settings in WSL2. If the issue persists, run wsl --shutdown and restart. If you're using a corporate VPN, WSL2 network settings may conflict—consider contacting your IT department.

API Key Authentication Failure

This happens when the API key is not set correctly or has expired.

# Check the environment variable
echo $ANTHROPIC_API_KEY
 
# If the key is empty, set it again
export ANTHROPIC_API_KEY="sk-ant-api03-..."
 
# Quick test to verify the key works
claude -p "hello"

Symptoms: 401 Unauthorized, Invalid API Key, Authentication failed errors

Solution Checklist:

1. Verify the API key starts with sk-ant-api03-
2. Ensure there are no extra spaces or line breaks in the key
3. Check that the key is active on Anthropic Console
4. Confirm the environment variable is loaded in the current shell session (source ~/.bashrc)

Permission Denied Errors

This occurs when you lack access permissions for files or directories.

# Check npm global directory permissions
ls -la $(npm config get prefix)/lib/node_modules/
 
# Change ownership to the current user
sudo chown -R $(whoami) $(npm config get prefix)/lib/node_modules/
sudo chown -R $(whoami) $(npm config get prefix)/bin/
 
# Or change the npm global path to a user directory (recommended)
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Symptoms: EACCES: permission denied, Error: EACCES errors

Solution: Running npm with sudo is not recommended. Instead, it's safer to change npm's global installation path to a user directory.

npm Global Installation Permission Issues

Permission issues that occur when installing npm global packages.

# Method 1: Use nvm (most recommended)
# Node.js installed via nvm goes in the user directory, so there are no permission issues
nvm install 20
 
# Method 2: Run temporarily with npx (use without installing)
npx @anthropic-ai/claude-code
 
# Method 3: Change the npm global directory
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
npm install -g @anthropic-ai/claude-code

Symptoms: npm ERR! code EACCES, npm WARN checkPermissions Missing write access

Solution: Using nvm installs Node.js and npm in your home directory, fundamentally solving permission issues. Even if Node.js is already installed on your system, adopting nvm is recommended.

Plans and Pricing

Using Claude Code requires a paid plan or an API key. The cost structure varies depending on how you use it.

Plan Comparison

Approximate Token Costs by Model (Direct API Usage)

Note: Token prices are subject to change. Check the Anthropic website for the latest pricing.

Estimated Monthly Cost (Direct API Usage)

These are rough monthly cost estimates based on usage patterns. Actual costs will vary depending on task complexity and codebase size.

Cost-Saving Tips:

• Use Sonnet as your default model for everyday coding tasks
• Leverage Haiku sub-agents for code exploration and search
• Regularly check your current session costs with the /cost command
• Compress context with the /compact command to reduce token usage
• The Max Plan is more economical than direct API usage if you use it actively every day

Next Steps

Now that you've completed installation and basic setup, explore these topics next.

• MCP Integration: Connect external tools and data sources to Claude Code
• Sub-Agents: Create specialized AI helpers to distribute work
• Hooks System: Build automated workflows