How to Set Up Claude Code on macOS

What you'll build / learn

By the end of this tutorial you'll have Claude Code — Anthropic's agentic coding tool — installed on your Mac, authenticated, and running inside one of your own projects. You'll also know the essential slash commands and settings to be productive on day one.

Prerequisites

• macOS (Apple Silicon or Intel — both work).
• Node.js 18 or newer. Check with node --version. If you don't have it, the easiest route is Homebrew: brew install node.
• A terminal (the built-in Terminal.app, or iTerm2).
• An Anthropic account. You can authenticate either with a Claude Pro/Max subscription or with API billing from the Anthropic Console. Either works; pick one.
• Basic comfort running commands in a terminal. No prior CLI-tooling experience assumed.

Step 1 — Install Claude Code

The stable, documented way to install is via npm. Open Terminal and run:

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

Don't use sudo. If you get an EACCES permission error, your npm global directory needs fixing rather than escalating privileges. The cleanest fix is to point npm at a user-owned directory:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

Then re-run the install command.

Confirm it installed:

claude --version

You should see a version number printed.

Step 2 — Authenticate

Claude Code authenticates on first run. Navigate into any folder and start it:

cd ~/code/my-project   # any project directory
claude

The first launch walks you through:

1. Pick a theme (light/dark) — purely cosmetic.
2. Sign in. Claude Code opens your browser. Choose the method that matches your account:
   • Claude account — if you have a Pro or Max subscription, log in and authorize.
   • Anthropic Console — if you're paying per-token via the API, this links your Console billing.
3. Approve the connection in the browser, then return to the terminal.

Your credentials are stored securely in the macOS Keychain, so you only do this once. To change accounts later, run /login or /logout from inside Claude Code.

Step 3 — Run Claude Code in a project

Claude Code is most useful when launched from your project root, because it reads your files for context. Inside a real repo, try:

claude

Then, at the prompt, type a natural-language request, for example:

Explain what this project does and list the main entry points.

Claude reads relevant files and answers. When it wants to edit a file or run a command, it asks for your approval first — read the diff, then accept or reject. This permission step is the main safety guardrail; don't blanket-approve things you don't understand.

You can also pipe a one-off prompt without entering the interactive session:

claude -p "Summarize the README in three bullet points"

Step 4 — Create a project memory file

Claude Code looks for a CLAUDE.md file in your repo and treats it as persistent project context (coding conventions, how to run tests, architecture notes). Generate a starter one from inside the session:

/init

This scans your project and writes a CLAUDE.md you can edit and commit. Keeping it in version control means every contributor — and every Claude session — shares the same context.

Step 5 — Essential slash commands

Inside the interactive session, commands start with /. These are the ones you'll use daily:

To exit, type /exit or press Ctrl+C twice.

Step 6 — Useful settings

Claude Code reads settings from JSON files, in increasing priority:

• User settings: ~/.claude/settings.json (applies everywhere)
• Project settings: .claude/settings.json (commit this to share team config)
• Local project settings: .claude/settings.local.json (personal, git-ignored)

You can edit these directly, or use the config command. For example, set the theme globally:

claude config set -g theme dark

Run /config inside a session to browse current values interactively.

Verify it works

Run the built-in health check:

claude doctor

It reports your version, install method, and any problems. A healthy setup shows no errors. Then start a session, ask a question about your code, and confirm Claude can read your files and respond. Seeing an answer that references your actual filenames means context loading is working.

Troubleshooting

• command not found: claude — npm's global bin directory isn't on your PATH. Run npm config get prefix, then ensure <that-path>/bin is in your PATH (see the ~/.npm-global fix in Step 1). Restart your terminal afterward.
• EACCES / permission denied during install — you tried installing into a system directory. Don't use sudo; reconfigure npm's prefix to a user-owned folder as shown in Step 1.
• Authentication loop or "unauthorized" — run /logout, then /login to redo the browser flow. Make sure you pick the method (subscription vs. Console) that matches an account in good standing.
• Node version errors — Claude Code requires Node 18+. Check with node --version and upgrade via brew upgrade node if needed.

To update Claude Code later, run:

claude update

Next steps

• Flesh out your CLAUDE.md with build/test commands and code style so answers get sharper.
• Explore custom slash commands and project settings in the official Claude Code documentation.
• Try Claude Code's IDE integrations for VS Code, and learn its permission settings to tune how much autonomy you grant it.