Getting Started with Claude Code: Complete Setup Guide

What Is Claude Code and Why Should You Care?

Before we dive into the installation details, let's clarify what Claude Code actually is. It's not just another ChatGPT wrapper. Claude Code gives you access to Claude (Anthropic's flagship AI model) directly from your terminal or IDE, with context awareness about your actual codebase, file system, and project structure.

Here's why that matters: Claude Code can read your files, understand your project architecture, search across your codebase, and propose changes that actually fit your existing code patterns. It's not making educated guesses about your code structure-it's reading the real thing.

You get two main ways to interact with it:

• CLI (Command-Line Interface): Type commands directly in your terminal for maximum flexibility and control
• IDE Extensions: Visual Studio Code and JetBrains IDEs (IntelliJ, PyCharm, etc.) with inline suggestions and file browser integration

Most developers find themselves using both, depending on the task. We'll cover both setups today.

Prerequisites: What You Actually Need

Before you install anything, let's make sure you have the basics covered.

Required:

• A Claude account (free or paid-we'll explain the differences in a moment)
• Node.js 18 or higher (for npm installation) OR just a terminal (for native binaries)
• 50MB of disk space minimum

Optional but helpful:

• Familiarity with your terminal or command prompt
• VS Code or a JetBrains IDE if you want IDE integration

That's it. You don't need Docker, special Python environments, or anything fancy. This is intentionally straightforward.

Understanding Account Types: Console vs Pro/Max

Here's a decision point that trips up a lot of people: what kind of Claude account do you actually need?

Free Console Plan: You get access to Claude through Claude.ai in your web browser. You can use Claude Code with this account, but you'll be rate-limited and can't use it in automation or CI/CD pipelines.

Claude Pro or Max: These are paid subscriptions ($20/month or custom) that unlock higher rate limits and priority access to newer models. Most serious developers using Claude Code at work opt for one of these.

Important: You don't need Pro to use Claude Code-the free plan works perfectly fine for learning and experimentation. But if you're building something in production, you'll want the higher limits.

To check which account you have:

1. Go to console.anthropic.com
2. Click your profile icon (top right)
3. Your plan type is listed under "Usage"

We'll use your account type in the authentication step later, so make note of it.

Installation Method 1: npm (Recommended for Most People)

If you have Node.js installed (or don't mind installing it), this is the simplest path. The npm package manager handles all the complexity for you.

Step 1: Verify Node.js is installed

Open your terminal and run:

node --version
npm --version

You should see version numbers like v18.17.0 and 9.6.7. If you get "command not found," head to nodejs.org, download the LTS version, and run the installer.

Step 2: Install Claude Code globally

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

This command downloads the Claude Code package and makes it available everywhere on your computer. The -g flag means "global"-you can use it from any folder.

Expected output (slightly different depending on your system):

added 142 packages, and audited 143 packages in 3.8s

Step 3: Verify the installation

claude --version

You should see something like @anthropic-ai/claude-code/1.2.0.

If you see "command not found," your npm global path might not be in your system PATH. We'll cover that in the troubleshooting section.

Why npm if you're not using Node.js in your project?

Great question. npm is just a package manager-think of it like "AppStore for developers." Installing Claude Code via npm is simple because it handles dependency management and updates automatically. When a new version comes out, you just run npm update -g @anthropic-ai/claude-code and you're done.

Installation Method 2: Native Binary (For the Platform-Specific)

If you prefer not to install Node.js, or you're on a system where npm feels overkill, Anthropic provides native binaries for macOS, Linux, and Windows.

macOS

Download the appropriate binary for your architecture:

# For Apple Silicon (M1/M2/M3)
curl -L https://github.com/anthropics/claude-code/releases/download/v1.2.0/claude-code-darwin-arm64 -o /usr/local/bin/claude
chmod +x /usr/local/bin/claude
 
# For Intel Mac
curl -L https://github.com/anthropics/claude-code/releases/download/v1.2.0/claude-code-darwin-x64 -o /usr/local/bin/claude
chmod +x /usr/local/bin/claude

The chmod +x command makes the binary executable. After this, test it:

claude --version

Linux

curl -L https://github.com/anthropics/claude-code/releases/download/v1.2.0/claude-code-linux-x64 -o /usr/local/bin/claude
chmod +x /usr/local/bin/claude
claude --version

Windows PowerShell

$DownloadUrl = "https://github.com/anthropics/claude-code/releases/download/v1.2.0/claude-code-win32-x64.exe"
$OutputPath = "$env:LOCALAPPDATA\Programs\claude\claude.exe"
New-Item -ItemType Directory -Path "$env:LOCALAPPDATA\Programs\claude" -Force | Out-Null
Invoke-WebRequest -Uri $DownloadUrl -OutFile $OutputPath
[Environment]::SetEnvironmentVariable("Path", "$env:Path;$env:LOCALAPPDATA\Programs\claude", "User")

Close and reopen PowerShell, then verify:

claude --version

Note: Check the Claude Code releases page for the latest version number-the examples above use v1.2.0 as an example.

Authentication: Connecting Your Claude Account

Now that Claude Code is installed, it needs to know who you are. This is where your Claude account comes in.

Getting Your API Key

1. Go to console.anthropic.com
2. Navigate to API Keys (usually left sidebar)
3. Click Create Key
4. Give it a name like "Claude Code CLI"
5. Copy the key (you'll only see it once)

Store this key somewhere safe-treat it like a password. Don't commit it to GitHub or post it in Slack.

Setting Up Authentication: Two Options

Option A: Environment Variable (Recommended for most workflows)

This stores your API key in your system environment, and Claude Code picks it up automatically.

macOS/Linux:

export ANTHROPIC_API_KEY="sk-ant-your-actual-key-here"
echo 'export ANTHROPIC_API_KEY="sk-ant-your-actual-key-here"' >> ~/.zshrc

The first line sets it for your current terminal session. The second line adds it to your shell configuration file (.zshrc for newer Macs, or .bash_profile for older ones) so it persists.

Close and reopen your terminal, then verify:

echo $ANTHROPIC_API_KEY

You should see your key (not empty).

Windows PowerShell:

[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-your-actual-key-here", "User")

Close and reopen PowerShell, then verify:

echo $env:ANTHROPIC_API_KEY

Option B: Config File (For more control)

Create a file at ~/.claude/config.yaml (macOS/Linux) or %APPDATA%\Claude\config.yaml (Windows):

api_key: sk-ant-your-actual-key-here
model: claude-3-5-sonnet-20241022
max_tokens: 4096

Claude Code reads this on startup. This is particularly useful if you want different settings for different projects.

First Authentication Test

claude --version

If this works without errors, you're authenticated. If you see an "invalid API key" error, double-check:

1. Your API key is copied exactly (watch for trailing spaces)
2. It starts with sk-ant-
3. You've set the environment variable or config file correctly

Creating Your First Project: The CLAUDE.md File

Here's something special about Claude Code that separates it from generic AI tools: it uses a file called CLAUDE.md to understand your project, your preferences, and how you want Claude to help.

Think of it as an instruction manual for Claude, written by you.

Initializing CLAUDE.md

Navigate to your project directory and run:

cd /path/to/your/project
claude init

This launches an interactive setup that asks you questions about your project:

? What's the name of your project?
> My Awesome App

? What's your primary tech stack?
> TypeScript + React + Node.js

? Are there any specific coding standards or style guides?
> ESLint config, Prettier for formatting

? Any folders or files Claude should avoid?
> node_modules, .env, dist/

After answering the prompts, Claude Code creates a CLAUDE.md file in your project root with your answers. Here's what it looks like:

# My Awesome App
 
## Project Overview
 
TypeScript + React + Node.js application
 
## Coding Standards
 
- ESLint config
- Prettier for formatting
- TypeScript strict mode enabled
 
## Ignore Patterns
 
- node_modules/
- .env
- dist/
 
## Technology Stack
 
- Frontend: React 18+
- Backend: Node.js + Express
- Database: PostgreSQL

Claude reads this file before every interaction, so it understands your project structure and preferences without you having to repeat yourself.

Pro tip: You can edit CLAUDE.md anytime. Add project context, architectural decisions, links to documentation-anything that helps Claude understand your codebase better.

First Commands: Getting Started with Plan Mode

Now you've got Claude Code installed, authenticated, and a project initialized. Let's actually use it.

Command 1: Ask Claude a question

claude ask "How should I structure my TypeScript React project?"

Claude will analyze your project and provide an answer. This is straightforward-just like asking a question in ChatGPT, but with access to your codebase.

Command 2: Generate a plan

This is where Claude Code gets interesting. Instead of just answering questions, you can ask it to plan out work:

claude plan "Add authentication to my app using JWT"

What you'll see:

Claude will break down the task into steps, showing you:

1. What needs to change
2. Which files are affected
3. What new files might need to be created
4. Estimated complexity

For example:

## Plan: Add JWT Authentication

### Phase 1: Backend Setup
- [ ] Install jsonwebtoken and express-jwt
- [ ] Create auth routes (login, register)
- [ ] Update User model with password hashing
- [ ] Add middleware for route protection

### Phase 2: Frontend Integration
- [ ] Create login form component
- [ ] Store JWT in localStorage
- [ ] Add Authorization header to API calls
- [ ] Create protected route wrapper

### Phase 3: Testing
- [ ] Write auth middleware tests
- [ ] Test login/logout flow

You can review this plan, ask for adjustments, and only when you're satisfied, move forward.

Command 3: Write code based on a plan

claude code "Implement Phase 1 of the authentication plan"

Claude will:

1. Read your existing code
2. Understand your project structure
3. Generate appropriate code changes
4. Show you the diffs before applying them

This is intentional-Claude Code doesn't just modify files blindly. It shows you what's about to change so you can review, suggest modifications, or reject changes entirely.

VS Code Extension Setup

If you spend most of your time in VS Code, the Claude Code extension makes the experience even smoother. You get inline suggestions, file browser integration, and context awareness without switching to the terminal.

Installation

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for "Claude Code"
4. Click Install on the official Anthropic extension

Configuration

After installing, the extension auto-detects your authentication (it uses the same API key you set up earlier). If it doesn't, VS Code will prompt you to set ANTHROPIC_API_KEY in your user settings.

To verify it's connected:

1. Open VS Code's Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
2. Type "Claude Code: Status"
3. You should see a confirmation that you're authenticated

First IDE Command

Right-click any file in your project and select Ask Claude Code. A side panel opens where you can ask questions or request changes. Claude can see the file you clicked on and its surrounding context.

For example, right-click auth.ts and ask: "Add error handling to this authentication function."

Claude will read the file, understand the existing code style, and suggest appropriate changes.

JetBrains IDE Setup (IntelliJ, PyCharm, etc.)

JetBrains users get the same experience through their official Claude Code plugin.

Installation

1. Open your JetBrains IDE
2. Go to Preferences/Settings → Plugins
3. Search for "Claude Code"
4. Click Install
5. Restart your IDE

Authenticating in JetBrains

Go to Preferences/Settings → Tools → Claude Code and enter your API key. The extension will test the connection and confirm when you're authenticated.

Using It in JetBrains

Right-click any file or code selection and choose Ask Claude Code. A tool window opens (usually bottom of screen) where you can have back-and-forth conversations with Claude about your code.

Unlike the terminal, where you're executing commands, the IDE interface is more conversational. You can ask follow-up questions, request iterations, and see diffs side-by-side.

Common Beginner Mistakes and How to Fix Them

You've made it through setup, which is great. But there are a few stumbling blocks that catch most people early on. Let's address them now so you don't hit them later.

Mistake 1: API Key Not Found

Symptom: Running claude commands gives "No API key found" error.

Solution:

1. Verify your key is set: echo $ANTHROPIC_API_KEY (macOS/Linux) or echo $env:ANTHROPIC_API_KEY (Windows)
2. If empty, you didn't set it correctly. Go back to the Authentication section and follow Option A
3. Make sure you closed and reopened your terminal after setting it

Mistake 2: "command not found: claude"

Symptom: You installed Claude Code, but your terminal doesn't recognize the claude command.

Solution:

1. If you used npm, run npm list -g @anthropic-ai/claude-code to verify it's installed
2. Check your npm global path: npm config get prefix
3. Make sure that path is in your system PATH environment variable
4. On macOS/Linux, you might need to use the full path: /usr/local/bin/claude --version

Mistake 3: Forgetting the CLAUDE.md File

Symptom: Claude seems to give generic advice instead of understanding your specific project.

Solution: Create a CLAUDE.md file with project context. Even a basic one helps:

# My Project
 
- Tech Stack: Node.js + TypeScript
- Main goal: Build an API
- Avoid: node_modules, .env

Mistake 4: Treating Claude Code Like ChatGPT

Symptom: You ask vague questions and get vague answers.

Important distinction: Claude Code has access to your files, but that doesn't mean you can be lazy with questions. Be specific:

Bad: "How should I structure this?" Good: "Looking at my /src folder structure, should I move the auth logic into a separate service folder?"

The more context you provide, the better Claude understands your actual situation.

Mistake 5: Accepting Code Changes Without Review

Symptom: Claude generates code, you click "apply," something breaks.

Solution: Always review diffs before applying changes. Read through what's being modified. Ask Claude to explain any changes you don't understand. This is your codebase-Claude is a helper, not an autopilot.

Next Steps: What to Do After Setup

You're now fully set up and ready to actually use Claude Code. Here are the natural next steps:

1. Start with small tasks: Ask Claude to add a simple feature or refactor a small function. Get comfortable with how it works before tackling larger tasks.

2. Build your CLAUDE.md: Spend 15 minutes expanding your CLAUDE.md with architecture diagrams, links to docs, and any team standards. This investment pays off in every future interaction.

3. Learn the common commands: Bookmark the Claude Code documentation and spend time with claude help.

4. Explore Plan Mode: This is where Claude Code really shines. Use claude plan for complex features and review the plans before implementing.

5. If using an IDE: Spend a session purely in VS Code or JetBrains getting comfortable with the right-click workflow and side panel interaction pattern.

Summary

You've now got Claude Code installed, authenticated, and ready to use-regardless of which platform you're on or how you prefer to work. You understand the difference between the CLI and IDE approaches, you know how to set up authentication securely, and you've learned from the mistakes other people have made so you don't have to repeat them.

The key takeaway: Claude Code is powerful because it understands your actual codebase, not because it's magic. The more context you give it (through CLAUDE.md, clear questions, and specific requests), the better it works.

Start small, expand your CLAUDE.md over time, and review changes carefully. In a few days of using it, you'll wonder how you ever coded without it.

Got questions or hit a wall? Check out the official docs or search for your specific error-the community's already solved most of the edge cases.

Now get out there and build something great.