Installing Claude Code

Installing Claude Code takes a couple of minutes. Most of this lesson is about the small number of things that go wrong, and about one difference between install methods that catches people out months later.

Pick the surface first

Claude Code runs in several places. There is a terminal command, extensions for VS Code and JetBrains IDEs, a desktop app, a version that runs in your browser at claude.ai/code, and integrations for Slack and CI pipelines.

They all connect to the same engine, and your configuration works across all of them. This course teaches the terminal, for two reasons. It is the surface where everything is visible — you can see each tool call and each permission prompt as it happens — and everything you learn there transfers to the others with almost no translation.

If you would rather have a graphical interface eventually, install the desktop app later. Learn it here first.

Install it

You need a paid Claude subscription — Pro, Max, Team or Enterprise — or a Claude Console account. The free Claude.ai plan does not include Claude Code. Some organisations run it through a cloud provider instead, which their administrator will have set up.

There are three install routes worth knowing.

The native installer. One command, and the one to use if you have no preference.

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

That is the macOS, Linux and WSL version. On Windows PowerShell it is irm https://claude.ai/install.ps1 | iex instead. There is a separate command for Windows CMD, so if you get an error about && not being a valid statement separator, you are in PowerShell and ran the CMD version. Your prompt tells you which you are in: PowerShell shows PS C:\ and CMD does not.

Homebrew, on macOS:

brew install --cask claude-code

There are two casks. claude-code follows the stable channel, which runs about a week behind and skips releases with major regressions. claude-code@latest gets new versions as soon as they ship.

WinGet, on Windows:

winget install Anthropic.ClaudeCode

There are also signed apt, dnf and apk repositories for Debian, Fedora, RHEL and Alpine, and a global npm package. Those are documented and supported; they are just not the shortest path for a first install.

The difference that matters later

This matters more than it sounds like it should. Claude Code ships very often, and features referred to in documentation and in courses like this one arrive in specific versions. A Homebrew install left alone for two months is not the tool being described anywhere.

If you used Homebrew, the upgrade is brew upgrade claude-code, or brew upgrade claude-code@latest if you installed that cask. On WinGet it is winget upgrade Anthropic.ClaudeCode. Put it somewhere you will see it.

Check it landed

claude --version

A working install prints a version number followed by (Claude Code). If you get command not found instead, the binary installed somewhere your shell does not look, and that is a solvable problem rather than a failed install — see below.

Start it on something real

Claude Code takes its working directory from wherever you launched it, and that directory is what it can read and edit. So you change into a project first, then start it:

cd your-project
claude

Getting this the wrong way round is the most common first-session mistake. Started in your home directory, Claude Code is looking at your home directory, and nothing you want to talk about is in reach.

On first run you will be prompted to log in, which opens your browser. Once you have authenticated, your credentials are stored and you will not be asked again. If you have an ANTHROPIC_API_KEY environment variable set, it skips the browser and asks you to approve that key instead. To change accounts later, type /login inside a running session.

The first thirty seconds

Above the prompt, Claude Code shows the version, the model it is using and the working directory. Read the working directory. It is the answer to a surprising number of later confusions.

Two commands are worth knowing immediately. /help lists what is available, and /resume reopens a previous conversation. Anything starting with / is a command handled by Claude Code itself rather than a message to Claude.

When it goes wrong

Two commands exist for this, and they are slightly different.

From your shell, before or instead of starting a session:

claude doctor

That prints read-only diagnostics without starting a session — install health, settings files that fail to parse, warnings with suggested fixes, and the result of the most recent update attempt. It is the right first move for command not found, for an install that will not update, or for a settings file you think is being ignored.

Inside a running session, /doctor runs a setup checkup that diagnoses installation and configuration problems and can fix some of them for you.

The other useful habit: Claude Code has access to its own documentation, so you can ask it. "How do I configure hooks?" or "why is my settings file not loading?" are reasonable things to type into the prompt, and you get a documentation-based answer rather than a guess.

What you have not done yet

You have installed a tool that can edit your files and run commands on your machine. What you have not yet done is decide how much of that happens without you being asked, or learn how to undo it when it goes somewhere you did not want.

Both of those are coming, and until then a reasonable precaution applies: work in a project where your changes are committed to git, or where losing them would not matter. Not because Claude Code is reckless, but because you are new to it, and the fastest way to get comfortable is to make the stakes low while you find out how it behaves.

What to take away

Install with the native installer unless you have a reason not to, and remember that Homebrew and WinGet installs stay where you left them until you upgrade them yourself. Start Claude Code by changing into a project directory and running claude, because that directory is what it can see. Log in once on first run. When something is broken, claude doctor from your shell and /doctor inside a session are the diagnostics, and Claude Code can answer questions about itself. The terminal is one of several surfaces onto the same engine, which is why learning it transfers.

Next: what actually happens between you pressing Enter and getting a result — the three-phase loop that everything else in this course sits on top of.