Categories
Blockchain

How to Set Up Claude Code From Scratch

Claude Code turns your terminal into an AI coding partner that reads your codebase, writes and edits files, and runs commands on your behalf. This guide walks you through installation to first working session in under 15 minutes.

By the end of this guide, you’ll have Claude Code running in your terminal, authenticated to your account, and ready to read, write, and run code inside any project you point it at. The whole process takes about 15 minutes if you already have a subscription. If you don’t, add 2 minutes to sign up.

What you’ll need

  • macOS 13.0 or later, Ubuntu 20.04+, Debian 10+, or Windows 10 (1809+)
  • 4 GB RAM minimum
  • A Claude Pro subscription ($20/month) or a Max, Team, or Enterprise plan. The free Claude.ai tier doesn’t include Claude Code access. Alternatively, you can authenticate through the Anthropic Console if you have API credits there.
  • A project directory. Claude Code works best when it has actual code to look at.

Step 1: Install the native binary

Anthropic provides a native installer that handles everything and sets up auto-updates. This is the recommended path. The old npm install -g @anthropic-ai/claude-code method still works but requires Node.js 18+ and doesn’t auto-update. Skip it.

On macOS or Linux (and WSL on Windows):

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

On Windows PowerShell (native, not WSL):

irm https://claude.ai/install.ps1 | iex

If you’re on macOS and prefer Homebrew, brew install --cask claude-code also works, though you’ll need to run brew upgrade claude-code manually for updates.

The installer takes under a minute. When it finishes, open a new terminal window and confirm the binary is on your path:

claude --version

You should see a version string. If the command isn’t found, close and reopen the terminal. On some systems the PATH update only takes effect in a fresh shell.

Windows users: The native installer requires Git for Windows to be installed first. WSL 2 is an alternative and skips that requirement, but comes with some feature differences in sandboxing.

Step 2: Authenticate

Run claude from any directory to trigger the browser login flow:

claude

Your default browser opens with an Anthropic authentication page. Log in with the account tied to your Pro or Max subscription. After you approve access, the browser closes and the terminal session picks up with your account connected.

You won’t see an API key anywhere in this flow. Claude Code uses OAuth, so there’s no key to copy, paste, or accidentally commit. If you’d rather use Amazon Bedrock, Google Vertex AI, or Microsoft Foundry as the backend instead of Anthropic-hosted endpoints, you can configure that in your settings after authentication.

Step 3: Navigate to your project and start a session

Claude Code’s core loop is simple: you cd into a project, type claude, and start talking.

cd ~/code/my-project
claude

On first run in a project, Claude Code reads the directory structure and picks up any CLAUDE.md file at the root if one exists. That file is how you give it persistent instructions about your project (more on that below). If there’s no CLAUDE.md, Claude Code just asks you what you want to do.

Try something concrete to confirm it’s working:

> What's the entry point for this app?

Claude Code will scan your files and answer based on what it actually finds, not what it guesses. It can also open files, make edits, run commands, and ask before doing anything destructive.

Step 4: Create a CLAUDE.md for your project

This step is optional, but it’s the highest-value thing you can do after setup.

CLAUDE.md is a plain text file you add to your project root. Claude Code reads it at the start of every session. You use it to capture things you’d otherwise repeat out loud every time: your tech stack, your naming conventions, which commands to run tests, things you don’t want Claude touching.

A minimal example:

# My Project

- Stack: Next.js 15, Supabase, Tailwind
- Test command: `npm run test`
- Lint: `npm run lint`
- Never modify /migrations directly. Always create new migration files.
- API routes live in /app/api/

You can also add project-level permissions here, like which shell commands Claude is allowed to run without asking first. The official docs on CLAUDE.md cover the full spec, but the file is just freeform markdown. Write what would help a smart contractor who’s new to your codebase.

Verifying it works

Two commands help confirm everything is healthy:

claude --version    # Should print version number
claude doctor       # Runs a detailed install check

claude doctor checks auth status, binary integrity, shell integration, and a few other things. If anything is misconfigured, it tells you what’s wrong and points to the fix.

Common pitfalls

  • Using sudo npm install -g @anthropic-ai/claude-code: This is the old method. It creates permission problems, doesn’t auto-update, and ties you to Node.js version management headaches. Use the native installer. If you already have the npm version installed, uninstall it (sudo npm uninstall -g @anthropic-ai/claude-code) and reinstall with the curl script.
  • Launching from the wrong directory: Claude Code’s understanding of your project depends on what directory you’re in. If you run claude from your home folder, it won’t have context about any specific codebase. Always cd into the project first.
  • Expecting it to work on the free tier: The free Claude.ai plan does not include Claude Code. You need at least Pro. If authentication succeeds but Claude Code immediately errors out on usage, check your subscription.
  • Homebrew installs that stop updating: If you used Homebrew, auto-updates are off by default. You get no notifications that a new version exists. Add brew upgrade claude-code to a periodic maintenance routine or switch to the native installer.

Next steps

Once you have a working session, the useful directions to go from here are: learning how to write effective CLAUDE.md files, setting up Claude Code Routines for scheduled agent tasks that run without you present, and exploring permission settings that let you control exactly what Claude is and isn’t allowed to do autonomously. The official documentation covers all of these. Start with the routines feature if you want to understand where AI-assisted development is heading.

Sources