Claude Code on Mac: Getting Started with Homebrew + Apple Silicon Setup

System Requirements for Mac — macOS 13.0 or Later, Apple Silicon and Intel Support, 4 GB RAM

Claude Code is Anthropic's official agentic coding environment that runs natively on Mac. It requires macOS 13.0 (Ventura) or later, at least 4 GB of RAM, and either an x64 or ARM64 processor (source). It works on both Apple Silicon Macs (M1/M2/M3/M4) and Intel Macs, so virtually all recent Mac models are supported.

It supports Bash, Zsh, PowerShell, and CMD shells. It works out of the box with macOS's default shell (Zsh) with no additional configuration, so even a fresh Mac without Homebrew or Xcode Command Line Tools can start an interactive session as soon as you log in via a browser (source).

A network connection is required, and usage is limited to countries and regions supported by Anthropic. Japan is among the supported countries, so no additional VPN setup is needed. ripgrep is bundled internally for search functionality, but if search isn't working, you can fix it separately with brew install ripgrep (source).

A Subscription is Required — It Won't Work with the Free Plan

One important thing to note is that Claude Code is not available on the Free plan (source). You need one of the following subscriptions: Pro ($20/month, USD before tax), Max ($100+), Team, or Enterprise. Authentication will not succeed with a free claude.ai account alone.

For those who want to use Claude Code seriously, the Max plan is often recommended. While the Pro plan allows installation and basic interaction, Max is essentially required if you want to fully utilize Opus 4.7 or run long agentic sessions. For pricing details, see Complete Guide to Claude Pricing Plans.

Three Installation Methods — Official Native (Recommended), Homebrew, and npm

There are three installation methods on Mac, and you choose based on your use case and update preferences. Anthropic recommends the official native installer, which ensures you always have the latest version through automatic updates (source).

Method 1: Official Native Installer (Recommended — Includes Auto-Updates)

Just run the following single line in your terminal. This is Anthropic's officially recommended method and the only one that auto-updates in the background.

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

Claude Code is installed to ~/.local/bin/claude, and on first install, the PATH is automatically added to your shell config file (e.g., ~/.zshrc) (source). Auto-updates are checked periodically at startup and during use — when a new version is available, it downloads in the background and takes effect on next launch. You can switch between the latest channel (always the newest) and stable channel (about one week behind to skip critical regressions) via the autoUpdatesChannel key in ~/.claude/settings.json.

Method 2: Homebrew (Familiar for Mac Users)

This is the most familiar method for Mac developers. Note, however, that it does not auto-update.

brew install --cask claude-code

There are two casks available via Homebrew: claude-code is the stable channel (stable release with regressions filtered out), and claude-code@latest is the latest channel (most recent release right after it ships) (source). Choose the former for stability, or the latter if you want to try the newest features immediately.

Since updates are not automatic, you'll need to manually upgrade periodically.

brew upgrade claude-code
# or if you installed the latest cask:
brew upgrade claude-code@latest

Homebrew keeps old versions on disk, so running brew cleanup occasionally will save disk space. If you don't have Homebrew installed, get it first from https://brew.sh.

Method 3: npm (For Those Already Using Node.js)

Developers who already use Node.js can also install via npm. Node.js 18 or later is required for a global install.

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

The npm package internally distributes the same binary as the native installer, going through platform-specific optional dependencies (e.g., @anthropic-ai/claude-code-darwin-arm64) to install the native binary (source). Apple Silicon gets darwin-arm64 and Intel Mac gets darwin-x64 automatically, so you don't need to worry about it.

One important note: do not use sudo npm install -g. This causes permission issues and security risks. It's safer to configure npm's global path to a user directory, or to install Node.js via a version manager like nvm or volta.

Which Method Should You Choose? — Official Native is Recommended

Here's a summary comparing the three methods. When in doubt, choose the official native installer — auto-updates will ensure you always have the latest version (source).

After installation, you can check the version with claude --version and run detailed diagnostics with claude doctor. The claude doctor command performs a comprehensive check of PATH settings, dependencies, authentication status, and network connectivity, making it a handy first-step diagnostic command when something goes wrong (source).

First Launch and Authentication — Login via Browser with claude, Pro or Higher Required

Once installed, simply navigate to your project directory and run the claude command to start an interactive session (source).

cd ~/projects/my-app
claude

On first launch, a browser will automatically open and display the Anthropic account login screen. Log in with a Pro, Max, Team, or Enterprise account. You can also authenticate with a Console account (API credit usage) (source).

After logging in, credentials are saved in the ~/.claude/ directory, and you won't need to log in again on subsequent sessions. To switch accounts, run the /login command within a session. Free plan users will be rejected at the authentication screen, so make sure to upgrade to Pro or higher before getting started.

5 Starter Questions to Try First

Once your session starts, rather than jumping straight into writing code, it's best practice to first have Claude understand your project (source). The following 5 questions are Anthropic's officially recommended starting patterns.

what does this project do?
what technologies does this project use?
where is the main entry point?
explain the folder structure
what can Claude Code do?

Claude Code automatically reads the necessary files based on your questions, so you don't need to manually add context. Building a shared understanding of the codebase with Claude in the first few minutes before moving on to specific editing tasks dramatically improves accuracy.

Quick Reference: Common Commands

Here's a summary of commonly used commands. Launching claude on its own is the basic approach, but there are different launch methods depending on whether you want a one-shot question, to continue a previous conversation, and so on (source).

Within a session, press ? for a list of keyboard shortcuts, Tab for command completion, Up arrow for history, and / for a list of commands and skills. See also Complete Guide to Claude Code for more features.

Mac-Specific Tips — Shift+Enter for Line Breaks, Notification Permissions, Keychain Integration

To use Claude Code comfortably on Mac, you need to configure both your terminal app settings and macOS system settings. Behavior varies slightly depending on whether you use Terminal.app, iTerm2, Warp, Ghostty, or another terminal, so start by checking your own environment.

Multi-Line Input with Shift+Enter — Prevent Enter from Sending Immediately

When writing long prompts, Shift+Enter for line breaks is essential. A plain Enter is treated as send, so get into the habit of holding Shift while pressing Enter when pasting multi-line code or instructions.

Some terminals may not recognize Shift+Enter as a line break. In that case, set Shift+Return to send \n in iTerm2's Profile → Keys, or switch to a modern terminal like Warp or Ghostty. Recent versions of Terminal.app (macOS's built-in terminal) also handle Shift+Enter naturally, so keeping macOS updated is also effective.

Allow macOS Notifications — Don't Miss Long Task Completions

When using Claude Code for long-running tasks (such as Routines or automated mode), enabling notification permissions in macOS System Settings will prevent you from missing task completions. Go to System Settings → Notifications → Terminal (or iTerm2/Warp, etc.) and turn on "Allow Notifications."

While Anthropic's official documentation doesn't have a dedicated macOS notifications section, you can control notification behavior by adding notification-related environment variables to the env key in ~/.claude/settings.json (source). For long agentic sessions or when using Routines, combining this with background notifications from your terminal app makes for a more comfortable workflow.

Credentials Stored in ~/.claude/ — Can Also Use Mac Keychain

After login, credentials are stored as plaintext JSON in the ~/.claude/ directory. If you want to integrate this with Mac's Keychain, you can use the enterprise managed settings feature or inject the ANTHROPIC_API_KEY as an environment variable via a third-party secrets management tool (source).

If you use multiple accounts, you can either swap out the entire ~/.claude/ directory or override settings with per-project .claude/ configs. For running both work and personal accounts on a single Mac, the practical approach is to either use separate user accounts or switch between them using the CLAUDE_CONFIG_DIR environment variable.

Uninstalling is Also Just Two Lines

When you want to completely remove Claude Code, just run these two lines in your terminal (source):

rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

If you installed via Homebrew, use brew uninstall --cask claude-code. If via npm, use npm uninstall -g @anthropic-ai/claude-code. If you also want to remove all settings and history, additionally run rm -rf ~/.claude && rm ~/.claude.json (note: this will delete all your settings).

Frequently Asked Questions (FAQ) — Common Sticking Points for Mac Users

Here are answers to common questions from people getting started with Claude Code on Mac.

Q. Does it work on M1/M2/M3/M4 Macs?

Yes, Apple Silicon (ARM64) is officially supported (source). It works on all Macs with M1 and later, running natively without Rosetta 2 for smooth performance. When installing via npm, the platform is detected automatically and the darwin-arm64 binary is selected.

Q. Does it work on Intel Macs?

Yes, Intel (x64) is supported (source). It works on macOS 13.0 or later with 4 GB of RAM. Basic functionality works fine on older Intel Macs, but you may run into memory issues during long agentic sessions.

Q. Can I use Claude Code with the Free plan?

No, you cannot. The free Claude.ai plan does not include Claude Code (source). You need either a Pro ($20/month) or higher subscription, or a Console account (pay-per-use API).

Q. I'm getting "command not found: claude"

This is likely a PATH issue. If you used the native installer, check whether ~/.local/bin is in your PATH by running echo $PATH. Running source ~/.zshrc to reload your shell config, or opening a new terminal session, often fixes it. Running claude doctor will give you detailed diagnostics (source).

Q. Should I choose Homebrew or the official installer?

The official native installer is recommended (source). Auto-updates mean you'll always have the latest version without any extra effort. If you prefer Homebrew, choose the claude-code@latest cask and set up a routine to regularly run brew upgrade.

Q. How do I check for updates?

With the native installer, updates are checked automatically at startup and downloaded in the background (source). To update manually, run the claude update command for an immediate update. Homebrew and npm installations require manual upgrades.

Q. Can I use it with VS Code or JetBrains?

Yes, official VS Code extension and JetBrains plugin are available (source). Using them alongside the CLI is standard practice — use the CLI for full codebase interaction and the IDE extension for inline edits of specific files. See Complete Guide to Claude Code for details.

Related Articles

• Complete Guide to Claude Code — Covers 9 features and pricing plans
• Claude Code April 2026 Major Updates Summary — Desktop redesign, Routines, xhigh, and more
• Introduction to Claude Code Harness Engineering — Design for stabilizing long-running tasks
• Getting Started with Claude in 5 Minutes — For non-developers
• Complete Guide to Claude Pricing Plans — Choosing between Pro and Max