How to Use Claude Code on a Mac, Start to Finish

The first thing Claude Code did on my Mac was nothing. I typed a prompt, pressed Option+Enter to start a second line, and the cursor sat there. Fifteen minutes later I had convinced myself the install was broken. The fix was a checkbox in Terminal.app's preferences.

That is what learning how to use Claude Code on a Mac actually feels like. The model side works out of the box; the Mac side has settings nobody mentions until they bite. So this is the guide I wanted on day one — installer, account, first session, CLAUDE.md, terminal keys, the macOS sandbox, parallel sessions, costs, and the pile of markdown it leaves behind. I read mine in MacMD Viewer, the $19.99 one-time read-only viewer I build, because I needed it for this job.

Everything below was checked against code.claude.com/docs on 28 July 2026, on Claude Code v2.1.220, macOS 26.3. It ships weekly: treat these versions and defaults as a dated snapshot, not permanent behaviour.

How Do You Use Claude Code on a Mac? The Short Version

Install the native binary, sign in with a paid Claude plan, cd into a repository and run claude. Then do the three things the quickstart skips: make your terminal send Option as a meta key, write a short CLAUDE.md, and pick a permission posture before you need one. The rest is habit.

The commands for the first hour (Anthropic, Quickstart, 28 July 2026): claude for an interactive session, claude "fix the failing test" to start with the task stated, claude -p "query" for a one-shot, claude -c to continue, claude -r to resume. And this is not only a terminal tool: Anthropic ships it on the web, as a macOS desktop app, in VS Code and JetBrains IDEs, in Slack, and in CI.

Which Installer Should You Use on macOS?

The native installer, in almost every case. It is the documented recommendation, it involves no Node at all, and it updates itself in the background. Homebrew and npm work too, but each surprises people later: one lags a week, the other demands a modern Node runtime for a binary that never uses it.

The native installer

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

Requirements are modest — macOS 13.0 or later, 4 GB of RAM, x64 or ARM64 (Anthropic, Advanced setup, 28 July 2026). It symlinks ~/.local/bin/claude into ~/.local/share/claude/versions/; autoUpdatesChannel takes "latest" (default) or "stable". Uninstall with rm -f ~/.local/bin/claude && rm -rf ~/.local/share/claude.

The binaries are signed as Anthropic PBC and notarised by Apple — verify rather than trust, with codesign --verify --verbose ./claude.

Homebrew, and why it is behind

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

The claude-code cask tracks the stable channel, "typically about a week behind" in Anthropic's words, and Homebrew installs do not auto-update — that is on you, via brew upgrade claude-code. Proof from 28 July 2026: the Homebrew Formulae API listed the cask at 2.1.212 while claude --version printed 2.1.220 here. That API is also the best public read on Mac adoption I found: 83,886 installs of claude-code in 30 days, 1,060,591 over 365 days (Homebrew Formulae analytics, 28 July 2026) — installs, not people, but a number you can re-check yourself.

npm, and what changed

npm install -g @anthropic-ai/claude-code still works, with two changes most tutorials predate: since v2.1.198 the package requires Node.js 22+, and it installs the same native binary anyway — "The installed claude binary does not itself invoke Node." Any guide saying Claude Code needs Node 18 describes a product that no longer exists.

Then confirm with claude --version, and claude doctor for read-only diagnostics.

Which Account Do You Actually Need?

A paid one. Anthropic's setup page is explicit: "The free Claude.ai plan does not include Claude Code access." You need Pro, Max, Team, Enterprise, or a Console account billed through the API. There is no free tier and no trial route into the terminal tool, whatever older write-ups suggest.

Listed on claude.com on 28 July 2026: Pro at $20/month, or $17/month paid $200 annually up front; Max from $100/month at 5x or 20x Pro usage. If you plan to run several sessions at once, Pro's ceiling arrives sooner than you expect.

What Happens in Your First Session?

You cd into a repository, run claude, and describe a task. Claude reads files, runs shell commands to explore, proposes changes, and asks before touching anything. The documented loop is Explore, Plan, Implement, Commit. Your first session is about deciding how much of that you want to watch.

Start with /init: it analyses the repository and writes a starting CLAUDE.md, and if one exists it proposes improvements rather than overwriting it (Anthropic, Memory, 28 July 2026). Shift+Tab cycles permission modes — default, acceptEdits, plan. Plan mode has its own page here: Claude Code plan mode covers what it blocks and what it does not. When the approval prompt appears and the plan runs past one screen, read the plan before you approve it — Ctrl+G opens it as a file instead of scroll-back.

Two rules from the best-practices page have saved me more time than any prompt trick. The two-correction rule: "After two failed corrections, /clear and write a better initial prompt." And its counterweight: "If you could describe the diff in one sentence, skip the plan." Both follow from one documented constraint — "Claude's context window fills up fast, and performance degrades as it fills."

How delegated this gets shows in Anthropic's June 2026 Economic Index report (data from 10 April to 10 June 2026): the median chat conversation producing an article takes 13 rounds of back-and-forth, "while the median blog-producing Claude Code session contains a single human prompt."

How Big Should Your CLAUDE.md Be?

Under 200 lines. That is Anthropic's documented target, and the reason is mechanical rather than stylistic: "Longer files consume more context and reduce adherence." The best-practices page is blunter: "Bloated CLAUDE.md files cause Claude to ignore your actual instructions!"

The trap is that it is never one file. CLAUDE.md loads from four scopes — managed policy, user, project, local — and they concatenate rather than override, so "my project file is 120 lines" is not the whole story. Two neighbouring facts live in the same corner of the docs: @path imports pull further files in, and Claude Code reads CLAUDE.md and not AGENTS.md. I have set out the exact paths, the import depth and the AGENTS.md workarounds in what Claude Code leaves on disk, so I will not repeat them here. What belongs in a setup guide is the habit: verify with /context, which lists what actually loaded under Memory files, instead of assuming.

The editing test comes from the docs and works line by line: would removing this cause Claude to make mistakes? If not, cut it. My file for MacMD Viewer is 120 lines and deliberately a router — it points at state files rather than restating them. When it grows, the bulk goes to .claude/rules/, where a paths: frontmatter key means a rule only loads for the files it applies to.

The Mac Terminal Settings Nobody Warns You About

This is where my first fifteen minutes went, and it is the most Mac-specific part of the setup. Anthropic documents all of it on one page, "Configure your terminal" (28 July 2026) — but nothing tells you that page exists until you go looking.

Terminal.app: Settings → Profiles → Keyboard → tick "Use Option as Meta Key". Without it every Option shortcut silently does nothing, including Option+Enter for a newline and Option+P to switch models.

iTerm2: Settings → Profiles → Keys → General → set Left and Right Option key to "Esc+". Then run /terminal-setup, which also enables clipboard access for /copy. Restart required.

Shift+Enter is a compatibility matrix, not a feature:

Desktop notifications arrive by default only in Ghostty, Kitty and iTerm2. Everywhere else, set "preferredNotifChannel": "terminal_bell" in ~/.claude/settings.json. iTerm2 also needs Profiles → Terminal → Notification Center Alerts → Filter Alerts → "Send escape sequence-generated alerts". To hear it instead, a Notification hook running afplay /System/Library/Sounds/Glass.aiff takes one line. And tmux breaks both Shift+Enter and notifications until you set allow-passthrough on, extended-keys on and terminal-features 'xterm*:extkeys'.

How Do Permissions and the macOS Sandbox Work?

Claude Code asks before it acts, and macOS gives it a real boundary to work inside. /sandbox turns on sandboxed Bash, which on a Mac needs nothing installed: it uses Seatbelt, the sandboxing framework already in the OS. That is the honest alternative to turning permissions off entirely.

By default a sandboxed command writes only to the working directory and the session temp directory. Reads stay broad, and that is the part to look at — ~/.aws/credentials and ~/.ssh/ are readable unless you restrict them via sandbox.credentials.

The frictions are documented, and knowing them stops you concluding the sandbox is broken: open and osascript fail with error -600 because Apple Events are blocked by default (allowAppleEvents re-enables them); Go-based CLIs like gh, gcloud and terraform can fail TLS verification under Seatbelt; docker is incompatible; jest needs --no-watchman. And the flag people reach for first, --dangerously-skip-permissions, is blocked under root or sudo.

Can You Run Several Sessions at Once?

Yes, and there is a built-in flag for it that most guides predate. claude --worktree <name> (or -w) creates an isolated git worktree and starts Claude inside it. Without a name, one is generated for you — the example in Anthropic's worktrees documentation is bright-running-fox. Each session gets its own HEAD, index and working tree.

The worktree lands in .claude/worktrees/<name>/ on a branch called worktree-<name>. Set up once: add .claude/worktrees/ to .gitignore, and create a .worktreeinclude file (same syntax as .gitignore) listing gitignored files like .env each new worktree needs. Subagents can get their own tree too, via isolation: worktree in a .claude/agents/ frontmatter.

This matters more than it sounds: two sessions in the same directory share HEAD and the index, so one reset --hard destroys the other's work.

What It Costs, and Whether It Makes You Faster

Anthropic's cost management documentation (checked 28 July 2026) reports around $13 per developer per active day across enterprise deployments, roughly $150 to $250 per developer per month, and under $30 per active day for 90% of users. The line that changes behaviour is on the same page: agent teams consume around 7x more tokens than a standard session.

Speed is murkier. METR's randomised study, published 10 July 2025, put 16 experienced open-source developers through 246 tasks on repositories they knew, and with AI tools they were 19% slower — having expected a 24% speedup, and still believing afterwards they had gained 20%. The surveys point the other way: Google Cloud's DORA State of AI-assisted Software Development 2025 (23 September 2025, around 5,000 professionals) found 90% using AI at work and more than 80% reporting higher productivity, with 30% holding little or no trust in the generated code.

The Stack Overflow Developer Survey 2025 quantifies that scepticism — 46% actively distrust the accuracy of AI tools against 33% who trust them (n = 33,244) — and shows why a guide like this still has a job: 14.1% use AI agents daily, 37.9% have no plans to adopt them (n = 31,877). The gap between the optimism and the METR stopwatch is review time. Generation is fast; reading the result well enough to be responsible for it is not.

Reading Everything Claude Code Writes

Which brings me to the part nobody warns you about. Claude Code writes markdown constantly — plans, memory files, session notes, specs, CLAUDE.md, READMEs, rule files. It accumulates far faster than it gets read. Numbers from my machine, re-counted on 29 July 2026 with the commands beside them:

• 15,580 .md files under ~/.claude — find ~/.claude -name "*.md" | wc -l — about 142 MB of markdown, inside a directory that du -sh puts at 17 GB in total
• 230 project directories in ~/.claude/projects/, and 50 skills in ~/.claude/skills/
• 196 tracked .md files in the MacMD Viewer repository — git ls-files '*.md' | wc -l

Reading all that raw in a pager is possible and mostly not done, which is the actual problem. A plan with nested lists, a table of affected modules and a Mermaid diagram is a structured document: rendered, the structure tells you where to look; raw, every section costs the same attention. With two or three --worktree sessions running, what I actually need is one window that belongs to none of them: .md set to open in the viewer by default, so whatever a session just wrote arrives rendered, and reloads in place the next time that session rewrites it.

I use MacMD Viewer for that, the tool I build: read-only by design, Mermaid without an extension, a Quick Look extension so Space in Finder works on .md, and 12 document themes. Read-only is the point — the window I read an agent's plan in should be structurally unable to edit the file that agent is about to execute.

What that costs: there is no editing surface, so a typo you spot in a spec gets fixed in your editor or by asking the agent, not in the window where you found it. That is the trade a viewer makes — it sits beside an editor rather than replacing one. For everything else an agent leaves behind, see reading AI-generated markdown on a Mac.

Frequently Asked Questions

How do I install Claude Code on a Mac?

Use the native installer: curl -fsSL https://claude.ai/install.sh | bash. It needs macOS 13.0 or later and 4 GB of RAM. The binaries are signed as Anthropic PBC and notarised by Apple, verifiable with codesign --verify --verbose ./claude.

Does Claude Code work with a free Claude account?

No. Anthropic's setup documentation states that the free Claude.ai plan does not include Claude Code access. You need Pro, Max, Team, Enterprise, or a Console account with API billing.

Why doesn't Option+Enter work in Claude Code on macOS?

Your terminal is not sending Option as a meta key. In Terminal.app, tick Settings → Profiles → Keyboard → Use Option as Meta Key. In iTerm2, set the Option key to "Esc+".

Is the Homebrew claude-code cask the latest version?

No, by design. The cask follows the stable channel, typically about a week behind, and does not auto-update. On 28 July 2026 it served 2.1.212 while my native install ran 2.1.220.

How do I run two Claude Code sessions at once?

Use claude --worktree <name> (or -w). It creates an isolated git worktree under .claude/worktrees/<name>/, on a branch named worktree-<name>, and starts Claude there.

How much does Claude Code cost per day?

Anthropic's cost management documentation reports roughly $13 per developer per active day across enterprise deployments, and under $30 for 90% of users (checked 28 July 2026).

How big should my CLAUDE.md file be?

Under 200 lines is Anthropic's documented target, because longer files consume more context and reduce adherence. Bloated files, per the best-practices page, cause Claude to ignore your instructions.

Where does Claude Code store the markdown it writes?

All on disk as plain .md, split between your home directory and your repositories: instructions in ./CLAUDE.md and ~/.claude/CLAUDE.md, extra rules in .claude/rules/, per-project memory under ~/.claude/projects/. Nothing sits in a database, so any Markdown viewer opens it. On my machine that is 15,580 .md files under ~/.claude alone, counted on 29 July 2026.