Claude Code Setup Guide: Install, Configure, and Start Coding in Minutes

Overview

Claude Code is Anthropic’s agentic coding tool that runs directly in your terminal. It reads your codebase, edits files, runs commands, and handles multi-step engineering tasks — all through natural language. No IDE plugin required. No browser tab to manage.

This guide walks through installation on macOS, Linux, and Windows, initial configuration, your first project session, and practical tips that save time once you’re running.

Tool

Claude Code

Latest Version

1.x

Price

Free with Claude Pro ($20/mo), Team ($30/mo), Max ($100–200/mo)

Platforms

macOS, Linux, Windows

Last Checked

2026-04-10

Prerequisites

Before installing Claude Code, confirm you have the following:

• Node.js 18+ — Claude Code is distributed via npm. Run node --version to check. If missing, grab it from nodejs.org or use a version manager like nvm.
• An Anthropic account — You need an active Claude Pro, Team, or Max subscription. Free-tier accounts do not include Claude Code access.
• A terminal — macOS Terminal or iTerm2, any Linux shell, or Windows with WSL2. Native Windows Command Prompt is not supported.
• Git (recommended) — Claude Code works best in git repositories. It uses git context to understand project structure and can create commits on your behalf.

Step 1: Install Claude Code

Open your terminal and run:

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

This installs the claude binary globally. Verify the installation:

claude --version

You should see a version number in the 1.x range. If you get a “command not found” error, ensure your npm global bin directory is in your PATH. Check it with:

npm config get prefix

Then add <prefix>/bin to your shell profile (~/.bashrc, ~/.zshrc, or equivalent).

For users who prefer not to install globally:

npx @anthropic-ai/claude-code

This runs Claude Code without a permanent install. Useful for trying it out or CI environments.

Step 2: Authenticate

On first run, Claude Code needs to link to your Anthropic account. Navigate to any project directory and launch:

cd ~/your-project
claude

Claude Code opens an authentication flow in your browser. Sign in with your Anthropic account credentials and authorize the CLI. The token is stored locally in ~/.claude/ — you only authenticate once per machine.

After authentication succeeds, you drop straight into an interactive session. You’ll see a prompt waiting for your input.

Step 3: Configure Your Project

Claude Code reads project context automatically from your codebase, but you can fine-tune its behavior with a CLAUDE.md file in your project root.

Create one:

touch CLAUDE.md

Add project-specific instructions:

# Project Instructions

- This is a Python 3.12 project using FastAPI
- Run tests with: pytest tests/
- Use conventional commits
- Never modify files in the migrations/ directory without asking

Claude Code loads CLAUDE.md at session start and follows these instructions throughout the conversation. Think of it as a system prompt scoped to your repository.

You can also create a personal ~/.claude/CLAUDE.md for global preferences that apply across all projects — editor style, commit conventions, language preferences.

Step 4: Run Your First Session

With authentication done and optional configuration in place, start a session:

claude

Try these commands to get oriented:

> Explain the project structure
> Find all API endpoints and list them
> Add input validation to the /users POST endpoint
> Run the test suite and fix any failures

Claude Code reads files, proposes edits, and asks permission before writing changes. Each file modification shows a diff you can approve or reject.

To run a one-shot command without entering interactive mode:

claude -p "explain what this project does" | cat

The -p flag sends a single prompt and prints the response to stdout. Useful for scripting and pipelines.

Step 5: Understand Permission Modes

Claude Code operates in three permission tiers:

Start with the default mode. As you build trust with the tool’s behavior in your specific codebase, you can allow more autonomy. Configure permissions per-project in .claude/settings.json or set them interactively during a session.

Step 6: Use IDE Integration (Optional)

Claude Code integrates with VS Code and JetBrains IDEs as an extension, giving you terminal-based Claude Code inside your editor.

VS Code:
1. Open the Extensions panel
2. Search for “Claude Code”
3. Install the official Anthropic extension
4. Open the Claude Code terminal panel with Ctrl+Shift+P → “Claude Code: Open”

JetBrains (IntelliJ, PyCharm, WebStorm):
1. Go to Settings → Plugins → Marketplace
2. Search “Claude Code” and install
3. Access via the tool window at the bottom panel

The IDE extensions run the same Claude Code CLI underneath. Your CLAUDE.md configuration, authentication, and project context all carry over. The advantage is tighter editor integration — clicking file paths in Claude’s output jumps to that location.

Tips and Best Practices

• Use CLAUDE.md aggressively. The more context you provide — test commands, coding standards, off-limits directories — the fewer corrections you’ll need mid-session. Projects with a well-written CLAUDE.md see noticeably better first-attempt results.

• Scope your requests. “Refactor the auth module to use JWT” works better than “improve the codebase.” Claude Code performs best with clear, bounded tasks.

• Leverage git integration. Start sessions in a clean git state. Claude Code can create commits with descriptive messages, making it easy to review or revert changes.

• Chain tasks with / commands. Built-in slash commands like /commit and /review streamline common workflows without typing full instructions.

• Check context usage. Long sessions accumulate context. If responses slow down or lose accuracy, start a fresh session with claude rather than continuing indefinitely.

Troubleshooting Common Issues

“command not found: claude” — Your npm global bin isn’t in PATH. Run npm config get prefix and add the resulting path’s bin/ subdirectory to your shell profile.

Authentication loop — Delete ~/.claude/ and re-run claude to trigger a fresh auth flow. This resolves most token-related issues.

Slow responses on large repos — Claude Code scans your repository for context. Add a .claudeignore file (same syntax as .gitignore) to exclude node_modules/, build outputs, and other directories that don’t need analysis.

WSL2 networking issues — If the browser auth redirect fails on WSL2, copy the auth URL manually and paste the token back. Ensure your WSL2 instance has proper network access to api.anthropic.com.

FAQ