All posts

How to Set Up Claude Code on a Mac (2026)

·Terminal Candy ·6 min read

claude-codesetupmacosguideagents

This is the setup I run on a fresh Mac. It takes about twenty minutes, and roughly fifteen of those are font and terminal decisions that pay you back every day after.

Order matters a little. Install first, make it pretty second, make it quiet third.

1. Check your Node

Claude Code needs a current Node. Check first:

node --version

If that prints something starting with 18 or lower, update before you do anything else. Homebrew is fine, nvm is better if you juggle projects:

brew install node
# or
nvm install --lts && nvm use --lts

Apple Silicon is the assumption throughout this post. If you are on an Intel Mac in 2026, most of this still works, but you are swimming upstream in general.

2. Install Claude Code

Two paths. The npm one:

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

Or the native installer, which sidesteps Node entirely and is what I use now:

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

Read the script before you pipe it to bash. That is not paranoia, that is just Tuesday. Anthropic moves the install line occasionally, so if the above 404s, get the current one from the official docs rather than from a blog post.

Verify:

claude --version
claude doctor

claude doctor is the underrated one. It checks your install, your auth state, and your shell integration, and it tells you which of the three is broken instead of making you guess.

3. Authenticate

Run claude in any directory. First launch walks you through auth in the browser.

Two options. A Claude subscription (Pro or Max) covers usage under a flat monthly rate, which is what most individual developers want. Or an API key from the Anthropic Console, which bills per token and is the right call if you are wiring Claude Code into something automated.

You can switch later with /login. Check what you are currently on with /status. If you share a Mac with a work profile, know which account you are burning tokens on before you kick off a long refactor.

4. Pick a terminal, seriously

Claude Code is a TUI. It draws boxes, it redraws them constantly, it streams output for minutes at a time. The terminal underneath it is not cosmetic.

What actually matters:

  • Rendering speed under heavy redraw. A slow terminal makes a fast agent feel slow.
  • True color. 24-bit, not 256. Diffs look wrong otherwise.
  • Correct mouse and selection handling. You will be copying code out of the TUI constantly.
  • Notifications. More on this in step 8.

Terminal.app renders fine and is right there, but it is thin on everything else. iTerm2 is the safe veteran. Ghostty is very fast. Terminal Candy is what I build and use, native AppKit with SwiftTerm underneath, Apple Silicon only, with skins and agent alerts. I compare all of them without pulling punches in the best terminal for Claude Code on Mac.

5. Install a Nerd Font

Do this before you touch your prompt or status line, or you will spend an afternoon debugging tofu boxes that were never a bug.

brew install --cask font-jetbrains-mono-nerd-font

Then set it in your terminal's font settings. Not your editor's. The terminal's.

Nerd Fonts are normal fonts patched with several thousand extra glyphs: git branch icons, file type icons, powerline separators. Every modern prompt and status line assumes you have them. My picks and the tradeoffs live in best Nerd Fonts for the terminal, and if you want the Mac-native angle specifically, SF Mono vs JetBrains Mono vs Monaspace covers why SF Mono is the awkward one here.

6. Give it a CLAUDE.md

In each project you care about, run:

/init

That writes a CLAUDE.md at the repo root. It is loaded into context every session. Put in it the things a new senior hire would need on day one and could not infer from the code: how to run the tests, which directories are generated, what the deploy command is, what not to touch.

Keep it short. A 400-line CLAUDE.md is a 400-line tax on every single message. Mine are usually under 60 lines and mostly commands.

You can also put a global one at ~/.claude/CLAUDE.md for preferences that follow you everywhere. Coding style, comment density, the fact that you hate emoji in commit messages. That kind of thing.

7. Set up a status line

The status line is the strip at the bottom of the Claude Code TUI. By default it is quiet. You can point it at any shell command and it will render the output, refreshed as you work.

Easiest path:

/statusline

Claude will write the config for you if you describe what you want. Under the hood it lands in ~/.claude/settings.json as a statusLine entry with a command it runs. Mine shows the model, the current git branch, and the directory. Context usage is the one people ask for most, and it is genuinely useful when you are deep in a long session.

Full walkthrough with copy-paste scripts: the Claude Code status line guide.

8. Hooks, the basics

Hooks are shell commands Claude Code runs at defined points in its lifecycle. They live in ~/.claude/settings.json (global) or .claude/settings.json (per project). The events you will actually use:

  • PreToolUse fires before a tool runs. Can block it. This is where you stop an agent from running git push on main.
  • PostToolUse fires after. This is where you auto-format edited files.
  • Notification fires when Claude needs your input.
  • Stop fires when it finishes a response.

The classic starter hook is a formatter on PostToolUse so every file the agent edits comes back clean. The second classic is a sound on Stop:

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

That is macOS built-in, no dependencies. Check the current hook schema in the docs before you paste, since the shape has changed at least once.

9. Know when it is done, without a hook

The Stop hook above works, but it only knows about Claude Code. If you also run Aider, Codex, or anything else, you are writing the same plumbing again per tool. And a sound tells you something finished, not which window.

This is why Terminal Candy has agent alerts. Since v1.1.0 it watches for nine CLI agents, Claude Code included, and fires a native macOS notification when one finishes or stalls waiting on you. Nothing to configure per agent. Details on the Claude Code page and the Aider page.

10. Make it look like yours

Last, because it is the fun part and you will not do the rest afterward.

Colors are the floor. Most terminals give you 16 ANSI values and a background, and that is where theming stops. Terminal Candy skins the whole window instead: frame, texture, title bar, colors, all as one click in the built-in gallery. There are CRT scanlines and phosphor glow if that is your thing, and a global off switch if it is not.

Free for 14 days, then $10 once, no subscription, no account. If you spend your day staring at a TUI, it is worth ten dollars to like looking at it. Browse the skins and see if any of them are you.

The checklist

  1. Node current
  2. claude installed, claude doctor clean
  3. Authenticated, know which plan
  4. Terminal chosen deliberately
  5. Nerd Font installed and set
  6. CLAUDE.md per project, short
  7. Status line configured
  8. One formatter hook, one notification hook
  9. Agent alerts so you stop babysitting
  10. A skin you do not hate

Keep reading