Claude Code: The Complete Setup Guide for macOS, Windows, and Linux

Claude Code is Anthropic's official command-line agent for software engineering. It lives in your terminal, reads your repository, runs commands on your behalf, and edits files with a level of context awareness that no autocomplete can match. This guide walks you through installing it on macOS, Windows, and Linux, signing in, configuring your first project, and getting to a productive flow before lunch.

We'll skip the marketing and focus on the parts that actually matter — the install steps that fail silently if you skip them, the settings worth tweaking on day one, and the workflow patterns that make Claude Code feel like a senior engineer pairing with you instead of a fancier autocomplete.

What you'll learn

• Installing Claude Code via the official installer or npm
• Signing in with an Anthropic account or API key
• Trusting your first project and running your first prompt
• Configuring permissions, hooks, and MCP servers
• A workflow checklist for daily use

Prerequisites

You need a working terminal, Node.js 18 or newer if you choose the npm install path, and an Anthropic account. A paid Claude.ai subscription gets you generous usage; otherwise an API key works the same way and bills per token.

• macOS: any modern Mac (Apple Silicon or Intel) with Terminal or iTerm2.
• Windows: Windows 10 or 11 with WSL2 strongly recommended for the Linux-flavored tooling.
• Linux: any major distro with a recent shell.

Install on macOS

The fastest path on macOS is the official one-liner. It downloads the binary, places it in ~/.local/bin, and adds the directory to your shell PATH if it isn't already there.

# Official installer (recommended)
curl -fsSL https://claude.ai/install.sh | sh

# Verify
claude --version

If you prefer to keep all your CLIs managed by a package manager, you can use Homebrew or npm:

# Homebrew (community formula)
brew install anthropic/claude/claude

# Or via npm (works on every OS)
npm install -g @anthropic-ai/claude-code

Install on Windows

On Windows you have two reasonable options: native PowerShell or WSL2. Most teams pick WSL2 because the rest of the developer experience — Docker, Git, Node — works more smoothly there. Inside WSL2, follow the Linux steps below. For native Windows, install Node 18+ and run:

# In an Admin PowerShell
npm install -g @anthropic-ai/claude-code
claude --version

Note: If claude isn't found after install, restart your shell so the new PATH entry takes effect.

Install on Linux

# Recommended
curl -fsSL https://claude.ai/install.sh | sh

# Or with npm
npm install -g @anthropic-ai/claude-code

# Confirm
claude --version

Sign in for the first time

Run claude inside any terminal and follow the browser prompt. You'll authenticate against Anthropic, your local CLI will receive a session token, and subsequent runs won't need to log in again.

claude
# → opens a browser tab → sign in → return to the terminal

Prefer using a raw API key (e.g., for headless servers or CI)? Export it before launching:

export ANTHROPIC_API_KEY=sk-ant-...
claude

Trust your first project

Open a real repository — not your home folder — and start claude from inside it. The first time, Claude Code asks for permission to read and edit files in that directory. Approve it for the project root and you're ready to prompt.

cd ~/code/my-project
claude

Try a small, observable task first. Ask Claude to summarize the project, identify the entry points, or fix a tiny bug. The point is to see Claude read files, run commands, and propose edits before you trust it with larger work.

Configure on day one

Three settings pay for themselves immediately:

1. Permissions: in ~/.claude/settings.json, allow safe shell tools by default and require confirmation for destructive ones (anything that touches Git history, deletes files, or pushes to remotes).
2. Hooks: add a hook that runs your formatter and tests after every edit. The model gets immediate feedback when it breaks something.
3. MCP servers: wire up a database MCP server so Claude can read your schema, and a docs MCP server for your framework of choice.

A first-day workflow

Once installed, the actual productivity move is treating Claude Code like a junior engineer who happens to be very fast. Brief it like a colleague: explain the goal, point at the right files, share constraints, and review its diffs the way you'd review a teammate's pull request. Don't dump bare instructions and expect magic — context is what makes this work.

• Start each session by orienting Claude: "Here is what we're working on, here is the relevant file, here is what success looks like."
• Have it write tests before the implementation when you can — it forces the spec into the open.
• Run a tight feedback loop: edit, test, commit. Don't let it stack ten changes without verification.

Troubleshooting

Most install failures fall into three buckets — corporate proxies blocking the install script, stale shell cache hiding the new PATH, or Node version mismatches when using the npm install path. Restart the shell, check which claude, and try the official installer if npm misbehaves.

Where to go next

Once you're set up, learn three concepts: slash commands for repeatable workflows, hooks for automatic verification after edits, and MCP servers for giving Claude access to data sources beyond the file system. We cover each in dedicated tutorials on the blog.