Claude Code on Mac: install, Keychain and terminal setup

To install Claude Code on a Mac, open Terminal and run curl -fsSL https://claude.ai/install.sh | bash, or use Homebrew with brew install --cask claude-code. Open a new terminal window, run claude --version, then start it with claude and sign in through your browser. It needs macOS 13.0 or later.

This guide covers both install methods and how they differ, how Claude Code uses the macOS Keychain, terminal settings worth changing, the built-in macOS sandbox, and fixes for Mac-specific errors. It draws on Anthropic's advanced setup docs, terminal configuration docs and install troubleshooting page, read on 26 October 2026.

What do you need to run Claude Code on a Mac?

From the system requirements:

• macOS 13.0 or later
• 4 GB or more of RAM, on an x64 (Intel) or ARM64 (Apple silicon) processor
• An internet connection and a supported shell (the docs list Bash, Zsh, PowerShell or CMD across all platforms)
• A Pro, Max, Team, Enterprise or Console account; the free claude.ai plan does not include Claude Code

The macOS binary is signed by "Anthropic PBC" and notarized by Apple. You can check it with codesign --verify --verbose ./claude.

If you'd rather not use a terminal at all, Claude Code also runs in the Claude desktop app for macOS. See the Claude Code desktop guide.

How do you install Claude Code on a Mac?

Native installer (recommended by Anthropic):

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

Homebrew:

brew install --cask claude-code         # stable channel
brew install --cask claude-code@latest  # latest channel

npm (alternative): npm install -g @anthropic-ai/claude-code, with Node.js 22 or later. It installs the same native binary. Don't use sudo npm install -g.

Whichever you choose, open a new terminal window afterward and check the install:

claude --version
claude doctor

Then cd into a project and run claude. The first run opens your browser to sign in. The Claude Code setup guide covers the first session step by step.

Should you use the native installer or Homebrew?

Both give you the same program. The difference is how it updates:

The stable channel is "typically about a week behind and skips releases with major regressions." Homebrew keeps old versions on disk after upgrades, so run brew cleanup now and then.

If you prefer Homebrew but want hands-off updates, set the CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE environment variable to 1. Claude Code then runs the upgrade for you in the background and shows a restart prompt. The Claude Code update guide covers channels, version pins and disabling updates.

How does Claude Code use the macOS Keychain?

According to the authentication docs, Claude Code stores your credentials in the encrypted macOS Keychain. When the Keychain rejects the write, such as when it's locked in an SSH session or its password is out of sync with your account password, Claude Code saves your login to ~/.claude/.credentials.json with file mode 0600 instead, which is the same storage it uses on Linux.

To move your login back into the Keychain:

1. Run claude doctor. A warning starting with macOS Keychain is not writable means the Keychain is rejecting writes.

2. Unlock it in the shell you run Claude Code from:

   security unlock-keychain ~/Library/Keychains/login.keychain-db
   

3. If unlocking doesn't help, open Keychain Access, select the login keychain and choose Edit > Change Password for Keychain "login" to resync it.

4. Run /logout and then /login. Logging out removes all stored credentials, including saved MCP server logins, so expect to sign in to those again.

A login that can't be saved shows Couldn't save your login. If your Mac's keychain is locked, unlock it and log in again. The same fix applies. For other sign-in problems, see the Claude Code login issues guide.

How should you set up your Mac terminal for Claude Code?

A few settings make Claude Code nicer to use on macOS. All come from Anthropic's terminal configuration page.

Turn on Option as Meta. Shortcuts such as Option+Enter (newline) and Option+P (switch models) do nothing until your terminal sends Option as a modifier.

• Apple Terminal: Settings → Profiles → Keyboard, check "Use Option as Meta Key"
• iTerm2: Settings → Profiles → Keys → General, set Left and Right Option key to "Esc+"
• VS Code terminal: add "terminal.integrated.macOptionIsMeta": true to your settings

If you accepted Claude Code's first-run terminal setup prompt in Apple Terminal, this is already done: that prompt runs /terminal-setup, which also turns off the audible bell.

Multiline prompts. Shift+Enter adds a newline without setup in Apple Terminal, iTerm2, Ghostty, Kitty, WezTerm and Warp. Ctrl+J, or \ then Enter, works everywhere.

Notifications. Claude Code sends desktop notifications by default only in Ghostty, Kitty and iTerm2. Elsewhere, set "preferredNotifChannel": "terminal_bell" in ~/.claude/settings.json, or add a Notification hook that plays a sound:

{
  "hooks": {
    "Notification": [
      {
        "hooks": [{ "type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff" }]
      }
    ]
  }
}

Clipboard in iTerm2. Running /terminal-setup in iTerm2 enables "Applications in terminal may access clipboard" so /copy can write to your clipboard. Restart iTerm2 afterward.

Pasting screenshots. Press Ctrl+V to paste an image from the clipboard, or Cmd+V in iTerm2. The Claude Code images guide covers formats and limits.

More options, including tmux and themes, are in the Claude Code terminal setup guide.

How does the Claude Code sandbox work on macOS?

On macOS the sandbox uses Apple's built-in Seatbelt framework, so there is nothing to install. The sandboxing docs say you can go straight to running /sandbox and choosing a mode. When on, shell commands Claude runs can only write to the working directory and a few allowed paths, and network access goes through a proxy that checks each host.

To confirm it works, ask Claude to run touch ~/sandbox-probe. Inside the sandbox it fails with Operation not permitted. Mac-specific issues the docs list:

• Go-based CLIs such as gh, gcloud and terraform may fail TLS verification under Seatbelt. Add a pattern such as gh * to excludedCommands so they run outside the sandbox.
• open, osascript and browser-based auth flows fail with error -600 because the sandbox blocks Apple Events. You can set allowAppleEvents to true in user settings, but that removes code-execution isolation; excluding open * is the narrower option.
• docker is incompatible with the sandbox, so exclude the specific Docker commands you need.

See the Claude Code sandbox guide for modes and settings.

How do you fix common Claude Code install problems on Mac?

If claude still isn't found, remember that a terminal window opened before the change keeps its old PATH, and a terminal inside an editor takes its PATH from the editor. Open a new window or restart the editor. The Claude Code troubleshooting guide covers problems that start after install.

To uninstall a native install, run rm -f ~/.local/bin/claude and rm -rf ~/.local/share/claude. For Homebrew, run brew uninstall --cask claude-code (or claude-code@latest).

How do you get your skills onto a new Mac?

A new machine starts with no Agent Skills. If you keep your prompts and skills in Kipt, they're stored as Markdown in a private GitHub repo you own, and you can install every skill into Claude Code with one command: npx skills add https://github.com/<you>/<repo>.git --all -g. The Claude Code skills guide explains how they load.