Claude Code on macOS: The Working Setup Guide

What macOS gets right out of the box

Claude Code runs natively on macOS. No compatibility layer, no virtualisation, no workarounds. The binary is compiled for both Apple Silicon (M1, M2, M3, M4) and Intel, so whatever Mac you are on, you get the full-speed native experience.

This is the complete macOS setup guide for 2026: choosing the right install method, getting your shell configured correctly, picking a terminal that works with Claude Code's interface, and writing the CLAUDE.md file that makes every session productive from the first message. If you are brand new to Claude Code and want the conceptual overview first, read what is Claude Code before continuing.

System requirements for macOS: version 13.0 (Ventura) or later, 4 GB RAM minimum, and an internet connection. If you are on Monterey (12.x) or earlier, you need to update macOS first.

Choosing your install method

There are three ways to install Claude Code on macOS. They produce the same binary. The difference is how updates work and which toolchain you prefer.

Native installer (recommended for most users)

The native installer is what Anthropic recommends and tests most thoroughly. Open Terminal and run:

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

The installer drops the binary at ~/.local/bin/claude and handles PATH configuration automatically. It also sets up background auto-updates, so you stay on the latest version without manual intervention. Restart your terminal after installing, then verify:

claude --version

If you see a version number, the install worked. If you see command not found, jump to the PATH fix in the troubleshooting section below.

Homebrew (recommended if you manage all tools with Homebrew)

If Homebrew is your package manager for everything else on your Mac, keep Claude Code in the same place:

brew install --cask claude-code

One important difference: Homebrew installations do not auto-update. You update manually when you want new features:

brew upgrade claude-code

Homebrew also offers a claude-code@latest cask that tracks the rolling channel rather than the stable channel. If you want new features as soon as they ship:

brew install --cask claude-code@latest

The tradeoff: @latest can occasionally ship a regression that claude-code (stable) would skip. For most developers, the stable cask is the right default.

npm (for pinned versions and CI environments)

The npm install path still works and is useful when you need to pin a specific version or work in an environment where npm is already managing your global toolchain:

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

Node 18 or later is required. Note: avoid sudo npm install -g as it creates permission issues. If you get a permission error, fix your npm prefix to point inside your home directory rather than using sudo.

Shell configuration on macOS

macOS ships with zsh as the default shell since Catalina (2019). If you have been on macOS for a while and never changed your shell, you are almost certainly running zsh. Check:

echo $SHELL

The output will be /bin/zsh (default), /bin/bash (legacy), or something else if you have installed fish, nushell, or another shell manually.

zsh setup

The native installer configures PATH automatically for zsh. If it works, you do not need to change anything. If claude is not found after install, add this line to ~/.zshrc:

export PATH="$HOME/.local/bin:$PATH"

Then reload:

source ~/.zshrc

If you use Oh My Zsh, Starship, or another zsh framework, the PATH export goes in the same ~/.zshrc, before the framework is loaded. Frameworks do not override PATH, but ordering matters if any plugin modifies PATH itself.

bash setup

If you are still on bash (you can check with echo $SHELL), add the same PATH line to ~/.bash_profile rather than ~/.zshrc:

export PATH="$HOME/.local/bin:$PATH"

Then reload:

source ~/.bash_profile

fish setup

Fish shell uses a different syntax for PATH. Open ~/.config/fish/config.fish and add:

fish_add_path $HOME/.local/bin

Fish's fish_add_path is idempotent, so calling it multiple times does not produce duplicates.

Terminal choice on macOS

Claude Code works in any terminal that supports standard ANSI colours and Unicode. On macOS you have several good options, each with different tradeoffs.

Terminal.app (built-in). Ships with every Mac. Functional for running Claude Code. The main limitations are no GPU-accelerated rendering (slower on very long outputs), no tabs-per-window by default (pre-Sequoia), and no ligature support. Completely usable, just not the best experience.

iTerm2. The most popular macOS terminal for developers. Relevant Claude Code benefits: split panes (keep Claude Code in one pane, your editor output in another), instant replay (scroll back through Claude Code's full session output), and shell integration that gives you timestamps on commands. Download from iterm2.com. The free version has everything you need.

Warp. A newer terminal built with GPU rendering and a command palette. Claude Code runs in Warp without any configuration. The agent panel Warp ships with is separate from Claude Code (they do not conflict). Warp is worth trying if you find traditional terminal workflows limiting.

Ghostty. Fast, minimal, GPU-accelerated, and native on macOS. No special configuration needed for Claude Code. A good choice if you want something lightweight that stays out of the way.

The honest answer: Claude Code does not care which terminal you use. Pick the one you are comfortable in. The productivity gains from Claude Code come from configuration (CLAUDE.md, memory, skills), not from terminal choice.

Authentication

After install, authenticate by running Claude Code from any project directory:

cd ~/your-project
claude

Claude Code opens a browser tab (Safari or your default browser) pointing to a Anthropic authentication URL. Log in with your Anthropic account. The credential is stored locally and persists across sessions. You will not be asked to log in again unless you explicitly sign out or delete the credential file.

Required account tier: Pro ($20/month), Max ($100/month), Teams, or Enterprise. The free Claude.ai plan does not include Claude Code access.

The CLAUDE.md file: where macOS users get ahead

Installation is five minutes. The configuration that makes Claude Code genuinely productive takes another thirty. The instrument is CLAUDE.md.

CLAUDE.md is a markdown file at the root of your project. Claude Code reads it at the start of every session. It tells Claude how your project is structured, what commands to use, and what conventions to follow. Without it, Claude Code produces generic code that needs retrofitting. With it, output fits your project from the first message.

A minimal but effective CLAUDE.md for a macOS development environment:

# Project rules

## Environment
- macOS Sequoia (15.x), Apple Silicon
- Node: 20 (via nvm, `nvm use 20`)
- Package manager: pnpm
- Run dev server: `pnpm dev`

## Code conventions
- TypeScript strict mode. No implicit any.
- Formatting: Prettier (runs automatically on save via VS Code extension)
- Linting: ESLint with project config at .eslintrc.js
- Tests: Vitest, run with `pnpm test`

## Project structure
- src/ (application code)
- tests/ (test files, mirroring src/ structure)
- scripts/ (one-off utility scripts, not part of the build)

## Hard rules
- Never commit with failing tests
- Environment variables go in .env.local (gitignored), never hardcoded
- Do not modify package.json directly, use `pnpm add` or `pnpm remove`

This is a starting point, not a template to copy verbatim. The goal is to answer the questions Claude Code would otherwise have to guess at: which test runner, which formatter, which package manager, which version of Node. Every answered question is a potential error that never happens.

Read CLAUDE.md explained for a full breakdown of what you can put in this file and how it affects Claude Code's behaviour.

Common macOS issues and fixes

"command not found: claude" after install. The installer tried to configure PATH, but your shell config was not reloaded. Run source ~/.zshrc (or source ~/.bash_profile for bash), then try claude --version again. If that fails, verify the binary exists: ls -la ~/.local/bin/claude. If it is there but still not found, the ~/.local/bin is not in your PATH. Add the export line from the shell configuration section above.

Two conflicting installations. If you installed Claude Code via npm at some point and then installed via the native installer (or Homebrew), you can end up with two binaries that shadow each other. Check: which -a claude. If it shows more than one path, you have a conflict. Remove the npm version: npm uninstall -g @anthropic-ai/claude-code. The native binary at ~/.local/bin/claude takes precedence once the npm one is removed.

Slow startup on first run. Normal. Claude Code authenticates and downloads initial configuration on first run. Subsequent starts are fast.

macOS Gatekeeper blocking the binary. If macOS shows a warning that claude cannot be opened because the developer cannot be verified, run this once: xattr -d com.apple.quarantine ~/.local/bin/claude. The binary is signed by Anthropic, so this is a first-run Gatekeeper caution, not an actual security issue. Verifying the signature: codesign --verify --verbose ~/.local/bin/claude should report "valid on disk" and "satisfies its Designated Requirement".

Auth browser tab does not open. Some terminal configurations (particularly SSH tunnels or remote desktop sessions) suppress browser opens. Run claude with the --print-login-url flag to get the URL and open it manually:

claude --print-login-url

Homebrew install is behind the latest version. Stable cask is typically one week behind latest. If you need a specific feature that just shipped, either switch to claude-code@latest or use the native installer instead.

Update management

If you installed via the native installer, Claude Code handles updates in the background. You do not need to do anything. New versions download while Claude Code is running and take effect on the next launch.

To check which channel you are tracking (latest vs. stable), run:

claude config

Switch channels via /config inside a Claude Code session. Most developers should stay on "latest" unless they have experienced regressions.

If you need to stay on a specific version (common in teams where everyone must match), set minimumVersion in your user settings.json:

{
  "autoUpdatesChannel": "stable",
  "minimumVersion": "2.1.100"
}

The settings.json for macOS lives at ~/.claude/settings.json.

Connecting Claude Code to your editor

Claude Code is a terminal tool, but it works alongside every macOS editor without integration plugins required. The pattern:

Open two windows side by side. On the left: your editor (VS Code, Zed, Nova, or whatever you use). On the right: a terminal running Claude Code in the same project directory. Claude Code reads and edits the files; your editor shows the changes in real time with its normal syntax highlighting and diff view.

If you use VS Code, the built-in terminal works for this. Open a terminal inside VS Code (Control + backtick), navigate to your project, and run claude. The VS Code file explorer updates as Claude Code makes changes.

For developers who use Zed: Zed's integrated terminal runs Claude Code cleanly. The combination is fast and lightweight.

What comes next

Once Claude Code is installed and running on your Mac, the next leverage point is learning how to configure it for your specific work. Two resources worth reading immediately:

Claude Code memory systems explains how to build project memory that persists across sessions, so Claude Code retains context about your codebase without you repeating it every time.

Claude Code best practices covers the workflow habits that separate effective Claude Code users from occasional ones: how to structure prompts, when to use headless mode, how to build a skill library.

The macOS install is the easy part. The configuration is where the real productivity gains are. Start with a CLAUDE.md, add memory, build skills as you find recurring patterns, and let the system compound over time.

Claudify ships a pre-built Claude Code operating system with memory architecture, skill libraries, and audit hooks already configured. Run npx create-claudify from your project to inherit the full setup without building it from scratch.

Quick reference

Task	Command
Install (native)	curl -fsSL https://claude.ai/install.sh | bash
Install (Homebrew stable)	brew install --cask claude-code
Install (Homebrew latest)	brew install --cask claude-code@latest
Verify install	claude --version
Diagnose issues	claude doctor
Update (native, auto)	Automatic
Update (Homebrew)	brew upgrade claude-code
Start a session	claude (from project directory)
Shell config file (zsh)	~/.zshrc
User settings file	~/.claude/settings.json
Uninstall (native)	rm -f ~/.local/bin/claude && rm -rf ~/.local/share/claude
Uninstall (Homebrew)	brew uninstall --cask claude-code