Installing Claude Code and getting it to actually run

The three things that block a first run: Node version, PATH, and the plan you are signed into.

Claude Code is a command-line tool, not an IDE plugin. Installation is short; the failures are almost always environmental.

1. Node version

It needs a modern Node LTS. If node -v prints something below version 18, upgrade before anything else. The quickest path on macOS or Linux is a version manager (nvm, fnm) rather than a system package, because system packages lag.

2. Install and check PATH

After installing, run the command in a new terminal window. If it says "command not found", the binary went somewhere your shell does not look — usually a global npm directory not on PATH. Fixing PATH is faster than reinstalling, and it is the single most common first-run failure.

3. Sign in with the right account

The tool uses the subscription you authenticate with. If you have two accounts, check which one is active: open the session, ask it who it is signed in as, or check the account page in the browser. A Max plan on one account does nothing for a session signed into the other.

4. Start inside the repository

Run it from the project root, not your home directory. The agent reads context from where it starts; launching from the wrong folder is why people conclude it "does not understand the project".

5. Give it a task you can verify

A first run should be small: "make this failing test pass", "explain what this module does", "add a flag to this command". Broad requests produce expensive wandering and a bad first impression of a tool that works fine on narrow tasks.

Common failures, ranked

• Old Node — installer fails or the binary exits immediately.
• PATH — command not found in a fresh shell.
• Wrong account — signs in, then reports no access.
• Wrong directory — edits files you did not expect.

Once it runs, the limits guide explains why a heavy afternoon stops early, and the plan list shows which tier fits your day.

Back to plans →