Getting Started with Claude Code Install on macOS

Claude code install is straightforward on macOS and Linux if Node.js is already in place. The fastest path for Claude code install is npm, and that is better than ad hoc wrappers because updates stay tied to the official package instead of a third-party script.

Outcome

After this setup, the machine can launch Claude Code from a terminal, authenticate with Anthropic, and attach it to a project directory. That is enough to start codebase-aware prompts, targeted edits, and shell-assisted workflows without adding editor plugins first.

This quickstart focuses on the shortest reliable path. Teams that need pinned versions or managed workstation images can add that later, but the install itself should stay close to the official package because fewer moving parts means fewer onboarding failures.

Prerequisites

Use a supported shell on macOS or Linux and install a current Node.js release with npm available on PATH. An Anthropic account is required for sign-in; check the official pricing page for current Claude plan details.

Most failed installs come from shell configuration, not from Claude Code. If node, npm, or global npm binaries are missing from PATH, the package may install correctly but still appear broken from the terminal.

Requirement	Why it matters	How to verify
Node.js + npm	The official install path uses npm.	node -v and npm -v
macOS or Linux shell	Claude Code is built for terminal use.	echo $SHELL
Anthropic account	Sign-in is required before the CLI can access Claude.	Log in on the official Anthropic site
Project directory	Running inside a repo gives the tool useful context.	pwd inside the target folder

Step 1: Install Node.js if it is missing

Skip this if node -v and npm -v already work. Node from the official installer or a version manager is the safer choice because broken npm paths cause more install failures than Claude Code itself.

On macOS, many teams use Homebrew or nvm. On Linux, a version manager is usually cleaner than distro packages because distro repositories often lag behind current Node releases and can split npm behavior in ways that confuse global CLI installs.

Verification matters more than the installation method. If node -v returns a version but npm -v fails, fix Node before touching Claude Code, because the official Claude code install path depends on npm and there is no benefit in debugging two broken layers at once.

Step 2: Run the claude code install command

The official package is installed with npm:

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

Global install is the right default for a CLI. Local project installs add path friction and solve nothing unless a team is pinning tool versions very aggressively for a locked-down build environment.

This is where many internal docs get too clever. Wrapper scripts, copied binaries, and shell aliases create extra failure points, while the direct npm command keeps the source of truth obvious and makes updates predictable.

If the shell throws permission errors during global install, fix npm’s global prefix or use a Node version manager instead of forcing sudo into the workflow. A CLI that needs elevated privileges to update is a bad default on developer machines.

Step 3: Confirm the binary is on PATH

Run:

claude --version

If the shell cannot find claude, npm probably installed the binary into a directory that is not exported on PATH. That is a shell problem, not a Claude problem, so fix npm’s global bin path before trying to reinstall.

A reinstall rarely helps if the binary directory is invisible to the shell. Check the npm prefix and global bin configuration, then confirm that the matching directory is loaded by the current shell startup file such as .zshrc, .bashrc, or the shell config used by the workstation image.

Testing with a fresh terminal is the simplest sanity check. If claude --version works only in one session, the path change was applied manually instead of being persisted in shell configuration.

Step 4: Authenticate and open a project

Change into the repository you want Claude Code to inspect, then start the CLI:

cd /path/to/project
claude

The CLI will prompt for authentication if the machine is not signed in yet. Running it from the target repo is better than opening it elsewhere because file awareness depends on the current working directory.

This is the first place where install quality meets actual usefulness. A successful launch from the wrong directory proves only that the binary works, while a launch inside the repo proves the tool can see the files that matter.

Authentication should be treated as a separate checkpoint from installation. If claude starts but sign-in fails, the package is installed correctly and the next fix belongs in account access, network policy, or browser-based auth flow rather than npm.

Step 5: Give it one bounded task

Start with a narrow prompt such as reviewing a module, explaining a failing test, or proposing a refactor for one file. Small tasks expose permission issues, repo access problems, and prompt quality faster than broad requests like “improve this codebase.”

A good first prompt is: “Summarize the architecture of this repo and identify the safest place to add a new API endpoint.” That tests repository reading, code understanding, and practical output in one pass.

Bounded prompts are better because they create a clear success condition. If the answer misidentifies entry points, ignores tests, or invents files, the team learns immediately that context or permissions need work before trusting edits.

Broad prompts hide bad setup behind vague output. A precise task forces the CLI to prove that the Claude code install is not just complete, but actually useful in the repository where developers plan to use it.

First thing to try

Ask Claude Code to inspect the current repo and produce a short map of directories, entry points, and test commands. That is better than asking for edits first because teams can verify context quality before the tool writes anything.

Example prompt: “Read this repository and list the main services, the local dev command, and the highest-risk area to change.”

A read-only orientation task is the safest first run because it reveals how well the CLI understands structure, naming, and developer workflows. If the summary matches the repo, the environment is ready for higher-trust tasks like patch proposals, test fixes, or refactors.

This also gives teams a baseline prompt for onboarding. Reusing the same first task across machines makes it easier to spot whether a problem comes from the repo, the account, or one developer’s shell setup.

Common mistakes

• Installing Node but not exposing npm’s global bin directory. If claude --version fails after npm install, check the npm prefix and global bin setup instead of reinstalling the package repeatedly.
• Using sudo npm install -g as the first fix. That can leave root-owned files in the global package path and make later updates harder than the original problem.
• Running Claude outside the repo. The CLI works best with the project as the current directory; otherwise file references become vague or useless.
• Starting with a huge task. “Audit this entire monolith” is a poor first prompt because it hides setup issues behind generic output.
• Hardcoding plan details into internal docs. Check the official Anthropic pricing page instead: https://www.anthropic.com/pricing.

Official package names, commands, and docs can change, so verify the current Claude code install command on Anthropic’s documentation before rolling this into team onboarding. For most dev teams, npm is the correct default because it is simple, scriptable, and easier to audit than custom wrappers or copied binaries.