AI Tools 6 min read ·

How to Set Up Claude Code on Mac: A Complete Guide

We earn commissions when you shop through the links below.

If you’ve been wondering how to set up Claude Code on Mac, you’re in the right place. Claude Code is Anthropic’s terminal-based AI coding agent that lets you delegate real development tasks — writing code, running tests, editing files, and navigating your project — all from the command line. Unlike chat-based tools, it operates directly in your environment. This guide walks you through everything from installation to your first working session.

What Is Claude Code?

Claude Code is a CLI tool built by Anthropic that brings Claude’s capabilities directly into your terminal. It can read and write files, execute shell commands, search your codebase, and iterate on tasks autonomously. It’s especially useful for refactoring sessions, debugging, and generating boilerplate across a real project structure — not just snippets in a chat window.

It pairs well with editors like Cursor, but it’s completely standalone and works in any terminal on macOS.

Prerequisites

Before you start, make sure you have the following:

  • Node.js 18 or higher — Claude Code is distributed as an npm package
  • An Anthropic account with API access enabled
  • macOS 12 Monterey or later (it will work on earlier versions but Monterey+ is recommended)

To check your Node version, open Terminal and run:

node --version

If you’re on an older version or don’t have Node installed, the easiest way to manage it on Mac is via nvm:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install --lts
nvm use --lts

Step 1: Install Claude Code

Once Node is ready, installing Claude Code is a single command:

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

The -g flag installs it globally so you can run claude from any directory. After installation, verify it worked:

claude --version

You should see the current version number printed in your terminal. If you get a permissions error during the global install, avoid using sudo with npm. Instead, configure npm to use a local directory:

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

Add that export line to your ~/.zshrc or ~/.bash_profile so it persists across sessions, then re-run the install.

Step 2: Get Your Anthropic API Key

Claude Code requires an API key to authenticate with Anthropic’s servers. Here’s how to get one:

  1. Go to console.anthropic.com
  2. Sign in or create a free account
  3. Navigate to API Keys in the left sidebar
  4. Click Create Key, give it a name, and copy it immediately — it won’t be shown again

Note that Claude Code usage is billed through your Anthropic account at standard API rates. There’s no separate subscription; you pay per token used.

Step 3: Set Your API Key

The cleanest way to configure your API key on Mac is via an environment variable. Add this to your shell config file (~/.zshrc for zsh, which is the default on modern Macs):

export ANTHROPIC_API_KEY=sk-ant-your-key-here

Then reload your shell:

source ~/.zshrc

Alternatively, Claude Code will prompt you to enter the key interactively on first run and can store it for you. But setting it as an env variable is the more reliable approach if you’re working across multiple projects.

Step 4: Run Claude Code for the First Time

Navigate to a project directory and launch it:

cd ~/Projects/my-app
claude

On first launch, it will walk you through a brief setup: confirming your API key, reviewing permissions (what it’s allowed to read and execute), and agreeing to usage terms. Read through the permission prompts carefully — Claude Code can execute shell commands, so understanding what you’re authorizing matters.

Once inside, you’ll see an interactive prompt. Try a simple task:

> explain the structure of this project

Claude Code will scan your directory and give you a real breakdown of what it finds. From here, you can ask it to write tests, fix a bug, or refactor a module.

Step 5: Configure Allowed Tools (Optional)

Claude Code uses a concept called “tools” — discrete capabilities like reading files, writing files, running bash commands, and searching. By default, it asks for confirmation before executing shell commands, which is the safe default.

You can create a claude.json config file in your project root to control behavior per-project:

{
  "allowedTools": ["read", "write", "bash"],
  "autoApprove": false
}

Setting autoApprove to true lets it run without confirmation prompts, which speeds things up but removes the safety check. I keep it off for any project with sensitive data or deployment scripts.

Tips for Getting the Most Out of Claude Code on Mac

Now that you know how to set up Claude Code on Mac, here are a few things I’ve learned from using it daily:

  • Be specific with tasks. Instead of “improve this file”, say “refactor the AuthService class to use dependency injection and add unit tests”. The more context, the better the output.
  • Use it inside git repos. Claude Code can read your git history and diffs. Asking it to “fix the failing tests from the last commit” gives it real context.
  • Combine with Cursor. I use Cursor as my main editor and drop into Claude Code via the integrated terminal for heavier multi-file tasks. They complement each other well.
  • Watch your token usage. Long sessions with big codebases can consume tokens quickly. Use /clear to reset context when switching tasks.

Troubleshooting Common Issues

Command not found: claude

This usually means the npm global bin directory isn’t in your PATH. Run npm bin -g to find where global packages are installed, then add that path to your ~/.zshrc.

Authentication errors

Double-check that your ANTHROPIC_API_KEY variable is set correctly. Run echo $ANTHROPIC_API_KEY in your terminal — if it returns empty, the export didn’t load. Re-source your shell config.

Permission denied on file operations

Claude Code respects your file system permissions. If it can’t write to a directory, check that your user has write access to that path. This is common when working in system directories.

Final Thoughts

Knowing how to set up Claude Code on Mac is genuinely one of the more useful things you can do if you’re serious about AI-assisted development. It’s not a chat toy — it’s a proper agentic tool that operates on your actual codebase. The setup takes under ten minutes if your Node environment is already in order, and the payoff is immediate once you start offloading real tasks to it.

If you’re also looking for a reliable place to deploy what you build, DigitalOcean remains my go-to for straightforward VPS and managed app hosting — simple pricing, solid performance, and a control panel that doesn’t get in the way.

Start with a real project, give Claude Code a concrete task, and see how far it gets without you intervening. You’ll adjust your workflow fast.