Claude Code Setup: Install and Configure in 5 Minutes

Most Claude Code setup guides give you 2 steps: "install Node.js" and "run npm install." Then you hit a permission error, a PATH issue, or an authentication problem and you're Googling for 45 minutes.

This guide covers the actual installation plus the 5 problems every beginner hits and how to fix each one in 30 seconds. I've watched over 100 people set up Claude Code in ClaudeFluent. I know exactly where people get stuck.

Prerequisites

You need 2 things:

• Node.js 18 or higher. Check by running node --version in your terminal. If you see v18.x.x or higher, you're good. If not, grab the LTS version from nodejs.org. On Mac, you can also install via Homebrew: brew install node.
• A terminal. On Mac, use the built-in Terminal app or iTerm2. On Windows, use PowerShell or Windows Terminal. On Linux, anything works. If you've never opened a terminal before, don't sweat it. Claude Code's interface is the terminal, so you'll get comfortable fast.

That's it. You don't need VS Code, Python, Docker, or any other dev tool. Claude Code runs in your terminal and that's all it needs.

Installation

Open your terminal and run:

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

This installs Claude Code globally so you can run it from any directory. Takes about 30 seconds.

Alternative (Mac only, Homebrew):

brew install claude-code

Both methods work identically. If you already have Homebrew set up, the brew method is slightly cleaner because it handles PATH configuration for you.

First Run and Authentication

Navigate to any project directory (or create a new empty folder) and run:

claude

On first run, Claude Code asks you to authenticate. You have 2 options:

• Claude Pro/Max subscription: What most people use. You'll log in with your Anthropic account. Claude Code uses your subscription's usage allowance: Pro ($20/month) for moderate use, Max ($100 or $200/month) for heavy use.
• API key: Pay per-token rather than a flat subscription. More common for teams and enterprise users.

Follow the prompts. It'll open a browser window for login. Once authenticated, you're set. Claude Code remembers your credentials.

Setting Up Your Environment

Claude Code works out of the box. But 5 minutes of environment setup makes everything smoother.

Create a Global CLAUDE.md

Create a file at ~/.claude/CLAUDE.md (in your home directory). This applies to every Claude Code session, regardless of project. Put your global preferences here:

# Global Preferences
- Always use TypeScript, never JavaScript
- Default to Next.js with App Router for web projects
- Use Tailwind CSS for styling
- Prefer Supabase for database needs
- Keep code simple — avoid over-engineering

Create a Project-Level CLAUDE.md

For each project, create a CLAUDE.md in the project root. This extends your global settings with project-specific context:

# My Project Name
Description of what this project does.

## Stack
- Next.js 14, TypeScript, Tailwind, Supabase

## Conventions
- Use server components by default
- API routes go in app/api/
- Shared components go in components/

Understanding the .claude/ Directory

Claude Code creates a .claude/ directory in your project for its own configuration. Inside you'll find:

• settings.json: permissions and tool configuration
• skills/: markdown files that teach Claude specific workflows (more on this in the best practices guide)

You can commit .claude/ to git so your team shares the same Claude Code configuration. The CLAUDE.md in your project root should also be committed. It's documentation that happens to also configure your AI agent.

Configuring Permissions

On first run in a project, Claude Code asks for permissions to read files, write files, and run commands. You have 3 options:

• Allow once: approve this specific action
• Allow for session: approve this type of action for the current session
• Allow always: approve this type of action permanently for this project

My recommendation: for personal projects, use "allow always" for read, write, and common commands like npm install, git, and npx. For work projects or shared codebases, be more selective. You can always change permissions later in .claude/settings.json.

Setting Up MCP Servers (Optional)

MCP (Model Context Protocol) servers give Claude Code access to external tools: databases, design files, browsers, and more. You don't need these to get started, but they're powerful once you're comfortable with the basics.

Common MCP servers to set up:

• Playwright: lets Claude control a browser for testing and screenshots
• Postgres/Supabase: direct database access for queries and migrations
• Figma: read design files and generate code from designs
• File system: extended file operations beyond the basics

MCP configuration goes in your .claude/settings.json. Each server has its own setup instructions. Start without MCP, bolt on servers as you need them.

IDE Integration

Claude Code has a VS Code extension that lets you run it inside the VS Code terminal with some IDE integration. It's fine, but I want to be direct: the terminal-first experience is better.

Why? Claude Code is designed to be an autonomous agent, not an IDE plugin. When you run it in a standalone terminal, you're in the right mindset: directing an agent rather than editing code. The VS Code extension bolts on a layer of abstraction that can actually slow you down.

That said, if you live in VS Code and can't imagine working outside it, the extension works. Install it from the VS Code marketplace and run Claude Code from the integrated terminal. Same capabilities either way.

Troubleshooting: The 5 Problems Every Beginner Hits

Here's where most setup guides end and where most beginners get stuck. These are the 5 issues I see constantly in training sessions.

Problem 1: "command not found: claude"

Cause: Your terminal can't find the Claude Code binary. PATH issue: the directory where npm installed Claude Code isn't in your system's PATH variable.

Fix: Run npm list -g --depth=0 to verify Claude Code is installed. If it is, find where npm installs global packages: npm config get prefix. Add that path's bin subdirectory to your PATH. On Mac/Linux, add this to your ~/.zshrc or ~/.bashrc:

export PATH="$(npm config get prefix)/bin:$PATH"

Then run source ~/.zshrc (or restart your terminal). If this feels like too much, just use Homebrew: brew install claude-code handles PATH automatically.

Problem 2: Authentication Errors

Cause: Your login session expired, or you're trying to use an API key that's invalid or has no credits.

Fix: Run claude logout then claude to re-authenticate. If using an API key, verify it at https://console.anthropic.com. Make sure your subscription (Pro or Max) is active. Claude Code doesn't work on the free tier.

Problem 3: Permission Errors on Mac (Gatekeeper)

Cause: macOS Gatekeeper blocks unrecognized software. You might see a popup saying the app "can't be opened because Apple cannot check it for malicious software."

Fix: Open System Settings, then Privacy & Security. Scroll to the Security section. You'll see a message about Claude Code being blocked; click "Allow Anyway." If you're getting filesystem permission errors instead, run: sudo npm install -g @anthropic-ai/claude-code.

Problem 4: npm Permission Errors

Cause: npm doesn't have permission to install packages globally. Common on Mac and Linux when Node was installed via the system package manager.

Fix: Quick fix is sudo npm install -g @anthropic-ai/claude-code. Proper fix is to configure npm to use a directory you own:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH="~/.npm-global/bin:$PATH"

Add that export line to your ~/.zshrc or ~/.bashrc to make it permanent. Or just use Homebrew, which sidesteps this entirely.

Problem 5: Slow First Run

Cause: First time you run Claude Code in a project, it indexes your codebase. For large projects (thousands of files), this takes a minute or 2.

Fix: This is normal. Just wait. Subsequent runs are much faster because Claude Code caches the index. If you want to speed it up, add a .claudeignore file (works like .gitignore) to exclude directories Claude doesn't need to read: node_modules, dist, .next, and other build artifacts. Claude Code usually handles these automatically, but being explicit doesn't hurt.

Verify Everything Works

Create a test folder and run a quick check:

mkdir claude-test
cd claude-test
claude

Once Claude Code starts, type:

"Create a file called hello.txt that says 'Claude Code is working!'"

If Claude creates the file, you're fully set up. Verify with cat hello.txt in another terminal window. Delete the test folder when you're done.

What to Do Next

You're set up. Here's your learning path:

1. Read the how to use Claude Code guide: covers the core concepts and workflow patterns
2. Follow the hands-on tutorial: build a real project from scratch in 30 minutes
3. Study the best practices: the patterns that separate beginners from power users
4. Join ClaudeFluent: live, guided sessions where you go from setup to shipping with expert instruction

The setup is the easy part. The real skill is learning to work with Claude Code effectively: giving clear instructions, building incrementally, and knowing when to step in. That's what the rest of these guides (and our training) are for.