Claude Code Setup Guide

Claude Code is Anthropic’s official CLI tool for AI-assisted software development. It’s not just another chatbot—it’s a coding partner that lives in your terminal, reads your files, runs commands, and helps you build software at the speed of thought.

By the end of this guide (15 min), you’ll have:

✅ Claude Code installed and authenticated
✅ Your first conversation with Claude
✅ A customized CLAUDE.md for your projects
✅ Knowledge of all key commands

Watch: Claude Code setup in 3 minutes

Why Claude Code?

Before we install, here’s why Claude Code stands out:

Feature	What it means for you
Terminal-native	No browser tab switching. Stay in your flow.
File-aware	It reads your actual codebase, not just snippets
Command execution	Can run tests, install packages, git operations
Session memory	Remembers your conversation context
Multi-file edits	Refactors across your entire project

Prerequisites

You’ll need:

Requirement	How to check	Where to get it
Node.js 18+	`node --version`	nodejs.org
npm	`npm --version`	Comes with Node.js
Terminal	You’re reading this, you have one	Built into your OS
Anthropic account	—	console.anthropic.com

Quick Prerequisites Check

Run this one-liner to verify everything:

node --version && npm --version && echo "✓ Ready to install Claude Code"

You should see version numbers (v18+ for Node) and the ready message.

Installation

Step 1: Install Claude Code

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

Windows users: Run your terminal as Administrator, or use the Node.js command prompt.

Mac/Linux: If you get permission errors, use sudo npm install -g @anthropic-ai/claude-code or fix your npm permissions.

Step 2: Verify Installation

claude --version

You should see something like:

claude-code v1.0.12

Step 3: Authenticate

claude login

This opens your browser for authentication. Sign in with your Anthropic account.

Alternative: API Key Authentication

If you prefer using an API key:

# Set for current session
export ANTHROPIC_API_KEY=sk-ant-your-key-here

# Or add to your shell profile for persistence
echo 'export ANTHROPIC_API_KEY=sk-ant-your-key-here' >> ~/.zshrc
source ~/.zshrc

Step 4: First Run Test

claude --help

If you see the help output, you’re ready to go! 🎉

Your First Session

Let’s build something real to see Claude Code in action.

Create a Test Project

mkdir vibecode-test && cd vibecode-test

Start Claude Code

claude

You’ll see the Claude Code prompt:

Claude Code v1.0.12
Type your message or /help for commands

>

Build Something

Type this prompt:

Create a Node.js CLI tool that fetches the current weather for a city.
Use the wttr.in API (no API key needed). Accept the city as a command
line argument. Handle errors gracefully.

Watch what happens:

Claude thinks through the approach
Creates files (shows you what it’s writing)
Explains the code structure
Suggests how to run it

Try running the result:

node weather.js "San Diego"

Iterate on It

Now ask for improvements:

Add colored output using chalk. Show temperature in both
Fahrenheit and Celsius.

Claude Code remembers the context and modifies the existing file.

Essential Commands

In-Session Commands

Command	What it does
`/help`	Show all available commands
`/clear`	Clear conversation history
`/compact`	Summarize and condense the conversation
`/cost`	Show token usage for this session
`Ctrl+C`	Cancel current operation
`Ctrl+D` or `/exit`	End session

CLI Flags

# Start with a specific model
claude --model claude-sonnet-4-20250514

# Run a one-shot command (no interactive session)
claude -m "Explain what this repo does" --no-interactive

# Start in a specific directory
claude --cwd /path/to/project

# Show verbose output (debugging)
claude --verbose

Real-World Workflows

Workflow 1: Exploring a New Codebase

Just cloned a repo you’ve never seen before?

cd unfamiliar-project
claude

Ask:

Give me a high-level overview of this codebase:
1. What does this project do?
2. What's the tech stack?
3. Where's the entry point?
4. What are the main modules?

Then dive deeper:

Walk me through what happens when a user logs in.
Start from the frontend and trace through to the database.

Workflow 2: Building a Feature

I need to add password reset functionality. We're using:
- Next.js 14 with App Router
- Prisma with PostgreSQL
- Resend for emails

Create the full flow:
1. "Forgot password" form
2. Email with reset link
3. Reset page with new password form
4. Actual password update

Use our existing auth patterns in src/lib/auth.ts

Claude Code will:

Read your existing auth code for patterns
Create multiple files (API routes, components, email template)
Suggest database schema changes if needed
Show you everything before writing

Workflow 3: Debugging

This test is failing:

[paste the failing test output]

The test file is at src/__tests__/checkout.test.ts
The implementation is at src/lib/checkout.ts

Find the bug and fix it.

Claude Code will:

Read both files
Analyze the failure
Propose a fix
Optionally run the test again to verify

Workflow 4: Code Review Mode

Review the changes in my last 3 commits for:
- Security issues
- Performance problems  
- Code style inconsistencies
- Missing error handling

Be critical. I want to catch issues before they ship.

Configuration Deep Dive

Project Configuration

Create .claude/settings.json in your project root:

{
  "model": "claude-sonnet-4-20250514",
  "permissions": {
    "allowFileWrites": true,
    "allowCommands": ["npm", "node", "git", "pnpm"],
    "denyCommands": ["rm -rf", "sudo"]
  },
  "context": {
    "includePatterns": ["src/**/*", "package.json", "README.md"],
    "excludePatterns": ["node_modules/**", "dist/**", ".git/**"]
  }
}

Global Configuration

Create ~/.claude/settings.json for defaults across all projects:

{
  "theme": "dark",
  "autoConfirm": false,
  "verboseMode": false,
  "defaultModel": "claude-sonnet-4-20250514"
}

CLAUDE.md: Your Project’s AI Instructions

Create a CLAUDE.md file in your project root. Claude Code reads this automatically:

# Project Context

## What This Is
A SaaS platform for managing restaurant reservations.

## Tech Stack
- Next.js 14 (App Router)
- TypeScript (strict mode)
- Prisma + PostgreSQL
- Tailwind CSS
- Clerk for auth

## Conventions
- Use server components by default
- Client components only when needed for interactivity
- All API routes return `{ data, error }` format
- Use Zod for all input validation
- Prefer named exports over default exports

## Commands
- `npm run dev` - Start dev server
- `npm run build` - Production build
- `npm test` - Run tests
- `npm run db:push` - Push schema changes

## Current Focus
Working on the reservation management dashboard.

This context makes Claude Code significantly more helpful because it knows your patterns.

Power User Tips

Tip 1: Reference Files by Name

Instead of pasting code, reference files:

Look at src/lib/api.ts and src/hooks/useApi.ts.
They have duplicate error handling logic. Consolidate into
a shared utility.

Tip 2: Ask for Options First

I need to implement real-time notifications. Before you
write any code, give me 3 architecture options with pros
and cons. I'll pick one, then you implement.

Tip 3: Iterative Verification

After each change, run the tests and tell me the results.
Don't move on until tests pass.

Tip 4: Use Git Context

Look at my unstaged changes (git diff). Review them before
I commit. Flag anything concerning.

Tip 5: Multi-Step Tasks

For complex work, ask Claude to create a plan first:

I want to migrate from REST to GraphQL. Don't start coding.
First, create a migration plan with phases. Each phase
should be small enough to complete and test independently.

Keyboard Shortcuts

Shortcut	Action
`Ctrl+C`	Cancel current generation
`Ctrl+D`	Exit session
`Ctrl+L`	Clear screen
`Up/Down`	Navigate prompt history
`Tab`	Autocomplete (when available)

Troubleshooting

”Command not found: claude”

Add npm’s global bin to your PATH:

# Find where npm installs global packages
npm bin -g

# Add to your PATH (in ~/.zshrc or ~/.bashrc)
export PATH="$PATH:$(npm bin -g)"

# Reload your shell
source ~/.zshrc

Authentication Errors

# Clear existing auth and re-login
claude logout
claude login

# Or verify your API key is set
echo $ANTHROPIC_API_KEY

”Rate limit exceeded”

You’ve hit your API usage limit. Options:

Wait a few minutes and try again
Upgrade your Anthropic plan
Use /compact to summarize conversation and reduce tokens

Claude Code Hangs or Freezes

# Force quit with Ctrl+C (maybe twice)
# If that fails, find and kill the process
pkill -f claude

# Start fresh
claude

Files Not Being Read

Check your project’s .gitignore and .claude/settings.json. Claude Code may be excluding files you need. Also ensure the files exist and you have read permissions.

Still having issues? See our AI Debugging Checklist or ask in the Community.

What to Build Next

Now that you’re set up, try these progressively harder challenges:

Easy: Create a CLI tool that converts Markdown to HTML
Medium: Build a REST API with authentication using your preferred framework
Hard: Refactor an existing codebase to add TypeScript types throughout

Resources

Official Claude Code Docs — Full reference
Anthropic Console — Manage your account
VibeWerks Discord — Ask questions, share tips
Prompting Fundamentals — Improve your prompting

Quick Reference

Command	What It Does
`claude`	Start new session
`claude -c`	Continue last session
`claude -r`	Resume specific session
`claude -p "..."`	Print mode (no interactive)
`/help`	Show commands
`/clear`	Clear context
`/compact`	Summarize conversation
`/cost`	Show token usage
`Ctrl+C`	Cancel current operation

Next Steps

Guides:

Prompting Fundamentals — Communicate effectively with Claude
Project Scaffolding — Start projects from scratch
Iterative Development — Master the build-review-refine loop

Cheatsheets:

Claude Code Shortcuts — Power user tips
AI Tool Shortcuts — All tools compared
Quick Wins — Copy-paste prompts

Practice:

Build an AI App in 30 Minutes — Hands-on tutorial
10 First Project Ideas — What to build

Frequently Asked Questions

How do I use Claude Code?

Claude Code runs in your terminal. After installing with npm install -g @anthropic-ai/claude-code, run claude in any project directory. Describe what you want to build or change in natural language, and Claude reads your files, generates code, and applies changes directly. Use /help to see all available commands. See the full setup guide above for step-by-step instructions.

Is Claude Code free?

Claude Code itself is free to install, but it requires an Anthropic API key with credits. You pay per token used — typical usage costs $5–20/month for active developers. Anthropic occasionally offers free credits for new accounts. There’s no monthly subscription; you only pay for what you use.

What can Claude Code do?

Claude Code can read your entire codebase, generate new files, edit existing code across multiple files, run terminal commands, debug errors, write tests, refactor code, and explain how things work. It’s an agentic AI coding assistant — meaning it can plan and execute multi-step tasks autonomously. It’s especially powerful for scaffolding new projects, implementing features across many files, and debugging complex issues.

You’re ready. Start building. 🚀