Claude Code: how to install on macOS, Windows and Linux

What does this solve?

«Claude Code how to install” - a request for one command, but almost everything after it gets stuck: logging into your account, permissions to write files and launch bash, lost PATH, on Windows - a missing shell. Claude Code works in the terminal inside the project directory: reads and edits files, runs builds and tests, makes commits. The installation places an executable file and a local state directory, and access to the model is connected in a separate action - these two steps are most often confused. Most of the complaints “installed, nothing works” - an installed binary without a login.

How it works

Claude Code is a regular console program. After installation, the following appears on the machine:

executable file claude in PATH;
catalogue ~/.claude/ — settings, session history, local agents, skills, logs;
user settings file ~/.claude/settings.json;
when working in a project - .claude/settings.json (general, placed in the repository) and .claude/settings.local.json (personal, in .gitignore);
CLAUDE.md at the root of the project is a permanent instruction that is mixed into each session.

Delivery takes place through two channels. The native installer installs a self-contained binary and updates it itself. The npm package installs the same program as a global package, requires Node.js installed, and is updated by the package manager command. The channel does not affect the behavior of the agent - only the update method and the list of dependencies.

Access to the model is a separate circuit. The program runs either through logging into an account with a subscription (browser OAuth), or using an API key from the developer console, or through corporate cloud gateways. The installation does not select any of the options: the first launch will ask itself.

Agent tools - read, write, search, run commands - work in the directory from which it is launched claude. This directory is considered a workspace; going outside of it requires explicit permission. Before writing to a file and before executing a command, the program asks for confirmation until the rule is entered into the permission settings.

On Windows, some of the tools rely on bash. It comes from Git for Windows, path is specified by variable CLAUDE_CODE_GIT_BASH_PATH. The second option for Windows is to put everything inside WSL and work in a Linux environment, where there are no special features.

How to connect

Before the start

Terminal: Terminal or iTerm on macOS, Windows Terminal or WSL on Windows, any on Linux.
Installed git. Without it, the agent edits files, but there is nothing to show and roll back changes in the normal way.
The project is under version control, the working tree is clean at the time of the first run.
Paid access to the model: account with subscription or API key. The installation will work without it, but the first task will not.
None sudo. Installing as root breaks the rights to ~/.claude, and later it comes out with strange recording errors.

macOS and Linux

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

The script places the binary in the user directory and adds PATH to the shell profile. Next, restart the terminal or re-read the profile:

source ~/.zshrc   # или ~/.bashrc
which claude
claude --version

If which does not find anything, PATH is not picked up. See which profile the line was added to (~/.zprofile, ~/.bash_profile, ~/.profile), and add the directory manually.

Windows

In PowerShell:

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

After installation, open a new terminal window so that PATH is re-read. If tools that need bash complain about the lack of a shell, install Git for Windows and specify the path:

setx CLAUDE_CODE_GIT_BASH_PATH "C:\Program Files\Git\bin\bash.exe"

Path with spaces - must be in quotes. An option that solves the whole class of problems at once: install WSL, go to the distribution kit and install it there according to the instructions for Linux. The project must be located inside the WSL file system, and not on the C drive via /mnt/c, otherwise everything depends on the speed of file operations.

Via npm

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

Requires the latest LTS version of Node.js installed. Place without sudo. If npm responds EACCES, set your own prefix:

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

Add the line with PATH to the shell profile, otherwise it will live until the window is closed.

First launch

cd ~/projects/my-app
claude

The first session will prompt you to log in. /login opens the browser, after confirmation the code is returned to the terminal. Checking that the login has taken place:

/status

The command shows the account, access payment method, version, active model and working directory.

Immediately after logging in, there are two steps that will save hours later:

/init          # соберёт черновик CLAUDE.md: как собирать, как тестировать, где что лежит
/permissions   # разрешить рутину: чтение файлов, git status, запуск тестов

Draft from /init need to subtract and throw out the obvious. CLAUDE.md falls into the context of each session, so extra paragraphs in it are paid for again each time it is launched.

Editors

Extensions for VS Code and JetBrains are installed on top of the same installation. Under the hood the same process works, only the location where the diff is shown changes.

Useful scripts

Parsing an unfamiliar repository: claude at the root and the question “where the payment webhook is processed” is faster than manual search in the code.
Running run of linter and tests with crash fixes: the agent sees the entire command output and corrects the reason, not the line from the error message.
Non-interactive mode for scripts and CI: claude -p "проверь миграции на обратимость" —the response goes to stdout and is suitable for the pipeline.
One installation for a dozen projects: general rules in ~/.claude/settings.json, design - in .claude/settings.json next to the code.
Onboarding a new person: CLAUDE.md in the repository describes the build and tests once for both the agent and the people.
Working on a remote server: the same installation via ssh, the state remains in the user’s home directory.

Limitations

Installation does not provide access to the model - this is a separate payment and separate entrance. The agent does not have a free mode of operation.

The agent edits files on the disk for real. There is only one normal insurance: git. Clean tree before start, small commits, git diff before accepting the result. Flag --dangerously-skip-permissions resolves all questions at once; on a working machine with access to combat systems this is a bad idea, for a disposable container it’s a working one.

Windows without WSL remains second class: some of the tools go through git-bash, and paths with spaces and Cyrillic characters regularly break commands.

The native installer updates itself, npm installation can only be done manually (npm update -g @anthropic-ai/claude-code). Mixing both channels on one machine is harmful: there will be two binaries in PATH, and the number from --version will no longer correspond to what actually runs.

A long session consumes quota non-linearly - each turn resends the entire accumulated context. This has nothing to do with installation, but the bill comes precisely for this.

One line rule: consider the installation complete only after claude doctor clean, /status shows the completed input and the test edit is visible in git diff.

How to check the result

First from outside the session:

claude --version   # печатает номер — бинарь найден в PATH
claude doctor      # проверка установки: канал доставки, права, PATH, конфликт версий

claude doctor is the first thing that starts when any strangeness occurs. It catches the most common case: two installed instances, npm’s and native, and the wrong one is launched.

Further inside the session, in the project directory:

/status    # аккаунт, модель, рабочий каталог
/context   # что уже занимает контекст: системная часть, CLAUDE.md, инструменты MCP

The last test is combat, for one minute. Ask the agent to perform git status (the command launch tool will work), then add one line to the README and stop. After that, go out and look:

git diff
git checkout -- README.md

If the line appeared in the diff and was rolled back, the installation is completely working: the binary is in place, the login is complete, the rights to the files and to bash are granted, the changes are controlled by git. If the edit does not appear, and there is a question about permission in the terminal, return to /permissions and allow writing to the working directory.