This guide provides an opinionated way to set up Claude Code on your Mac. It’s for anyone who wants to do real work with AI — read your files, edit them, run multi-step tasks across your computer — not just chat in a browser tab. You don’t need to know how to code.

By the end, you’ll have a working setup: Claude Code, the supporting tools it leans on for real work (a code editor, language runtimes, git), and a first persistent rule the agent has written for itself.

What Claude Code does

Claude Code is an agentic system that autonomously uses your computer the way you do. It reads your files, edits them, runs commands on your machine, installs tools, and works through multi-step tasks across many systems. Real work happens directly inside your files, not in a chat window. Things you can do immediately:

  • Working with documents you don’t want to read end to end. Point Claude Code at a folder of PDFs, transcripts, or reports and ask it to summarise each one, pull out specific facts, or compare them.
  • Drafting from your own past work. Hand the agent a folder of your old briefs, decks, or notes and ask it to draft a new one in the same shape. A chatbot can do this if you paste examples; the agent reads them straight from your folder.
  • Searching across your own notes and files. Ask questions about a body of saved material (meeting notes, PDFs, transcripts, exports) and the agent reads across them to find or stitch the answer. A chatbot can’t see any of this; the agent can.

As you get more comfortable:

  • Building a small thing from an idea. A landing page, a script that runs on a schedule, a small tool just for you. You describe what you want, the agent writes and tests the code, and you adjust together until it works.
  • Automating a recurring task. Pick something you do over and over by hand — drafting weekly status updates from your meeting notes, formatting exports from one tool for another, checking a feed for new entries. Describe it, the agent writes the script, and you can leave it running on a schedule.
  • Multi-step research projects. Read across sources you’ve collected, synthesize the findings, produce a deliverable (briefing memo, deck outline, comparison doc). The agent does each step; you review and direct.

As your practice deepens:

Setup overview

Here are the tools that we’ll install:

  • VS Code. A code editor for working with your project’s files. The Claude Code extension lives inside VS Code. Most LLM-related files are markdown (CLAUDE.md, skills, agent prompts, plans, notes), and VS Code renders markdown well.
  • Homebrew. A free, open-source package management system that simplifies installing software on macOS. You’ll use it to install most of the other tools below.
  • git. A version control system commonly used by software developers to track changes, collaborate on code, and roll back to earlier versions. The same capabilities are valuable for anyone working with files they care about: every change becomes a commit, a snapshot you can review, revert to, branch from, or share. With Claude Code in the loop, every edit it makes is captured automatically, so you can let it work freely knowing nothing is lost.
  • Node. A runtime for JavaScript programs. It ships with npm (Node Package Manager), the largest software registry in the world: millions of pre-built tools and libraries installable with one command. Many AI tools, deploy CLIs, and JavaScript-based utilities live in npm.
  • uv. A Python package and project manager for your Mac. It installs Python interpreters, manages versions, creates virtual environments, installs packages, and runs scripts. AI agents use Python often, for reading PDFs, working with spreadsheets, and running quick analyses; uv handles each of those tasks.
  • Claude Code. The AI agent this guide is about. Two ways to interact with it: a graphical sidebar inside VS Code (with plan review, inline diffs, @-mentions of files, and session history), or a terminal CLI.

If any of this is already on your Mac, skip ahead. Each step below is independent.

Install VS Code

VS Code is where the rest of this guide happens. You’ll use it to see your project’s files, open and edit them as needed, and host the Claude Code panel. It also handles markdown well, which matters because most agent work — CLAUDE.md, skill definitions, plans, notes — is markdown.

Go to code.visualstudio.com and click Download. When the download finishes, double-click the file to expand it, then drag the VS Code app into your Applications folder (the folder with all your Mac apps; you can open it from Finder by pressing Cmd+Shift+A). Open VS Code once. macOS may ask if you’re sure you want to open an app you downloaded from the internet. Click Open.

Three keyboard shortcuts worth committing to memory now:

  • Ctrl+` (Control plus the backtick key under Esc, top-left of your keyboard). Opens VS Code’s integrated terminal (a shell inside the editor). Useful when you need a terminal — for some install commands below, or to use Claude Code’s CLI directly.
  • Cmd+P. Opens a quick file finder. Start typing part of any filename in your project and it’ll find it.
  • Cmd+Shift+P. Opens the Command Palette (the “do anything in VS Code” entry point). Useful when you can’t remember a menu item or shortcut.

One opinionated config tweak: turn on auto-save. Press Cmd+, to open Settings, search for auto save, set “Files: Auto Save” to afterDelay. Why: when an AI agent edits a file you happen to have open, auto-save prevents an awkward “my unsaved version vs. its version” conflict. Worth enabling once and forgetting about.

Everything else (themes, extensions, code formatters) is taste.

Install Homebrew

Homebrew is how you install almost everything else on a Mac from the command line. Open VS Code’s integrated terminal (Ctrl+`) and paste this in:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Press Enter. It’ll ask for your Mac login password (the same one you use to log into your computer; the typing won’t be visible, that’s normal). It will also install Apple’s Xcode Command Line Tools if your Mac doesn’t have them already.

When the installer finishes, it prints two commands at the end of its output. The first adds Homebrew to your shell’s config so it persists across sessions; the second loads Homebrew into your current terminal. Copy and paste both exactly as the installer prints them. The exact paths differ between Intel and Apple Silicon Macs, so use what your installer outputs.

Install git

git is sometimes pre-installed on a Mac (it ships with Apple’s Xcode Command Line Tools), but the bundled version usually lags behind. We’ll install Homebrew’s current version directly:

brew install git

Verify it worked:

git --version

You should see a version number printed back.

Install Node and uv

brew install node uv

Verify both worked:

node --version
uv --version

You should see version numbers printed back.

A note on Python: macOS ships its own system Python, but it’s restricted — Apple locks it down so packages can’t be installed against it. uv installs and works with its own unrestricted Python, separate from Apple’s; you don’t have to think about which Python is which.

(If you already work on multiple projects with different Node versions, you may want a version manager like nvm or mise.)

Install Claude Code

The recommended path is the Claude Code extension for VS Code.

In VS Code, press Cmd+Shift+X to open the Extensions view, search for “Claude Code” (publisher: Anthropic), and click Install. Or click this direct install link.

Once installed, look for the Spark icon (✱) in the top-right of the editor — it appears when you have any file open. Click it to open the Claude Code panel.

The first time you open the panel, a sign-in screen appears. Click Sign in and complete authorization in your browser. You’re now talking to Claude Code.

Alternative — install the CLI directly. If you prefer terminal-first work, the standalone installer is one line:

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

Then claude in any terminal opens a session. Either install path gets you both surfaces: the extension bundles the CLI, and the CLI’s /ide command will install the extension when you run inside VS Code’s terminal.

Start your first session

You’re already signed in from the install step. To open the Claude Code panel: click the Spark icon (✱) in the top-right of VS Code’s editor (visible when any file is open), or click ✱ Claude Code in the bottom status bar. The panel is where you’ll talk to the agent.

The extension uses whatever folder VS Code has open as its working directory. No separate “where should the agent run” decision to make — open the folder you want to work in, and the extension follows.

Your first task: write a user-level CLAUDE.md

CLAUDE.md is a plain text file Claude Code reads at the start of every session. A user-level CLAUDE.md at ~/.claude/CLAUDE.md applies to every Claude Code session you run on this Mac, across every project. It’s where you keep the rules that should always apply.

The simplest first thing to set up is two short rules: one about Python tooling, one about keeping CLAUDE.md itself lean. Both are agent-side rules — things the agent should do or not do. (Other Anthropic-recommended practices like be specific in prompts or use Plan Mode for complex tasks are user-side; they live in your habits, not in your CLAUDE.md.)

You won’t write the file by hand. You’ll describe what you want, and Claude Code will write it for you. In the Claude Code prompt (where it’s waiting for your input), paste this:

Create ~/.claude/CLAUDE.md with two short rules. First: always use uv for all Python work (interpreter, venvs, packages, scripts), never use system python or pip. Second: when writing CLAUDE.md or similar rule files, keep entries terse — each line should answer "would removing this cause mistakes?" If not, cut. Group as two top-level headers; one bullet each.

Watch what happens. Claude Code reads your message, decides where to write the file, generates the rule’s content, and creates ~/.claude/CLAUDE.md. From now on, every session you start will carry those rules.

You’ve just done two things in one task: written your first persistent agent rule, and seen the agent do real file work for you.

A few things worth knowing about Claude Code

You don’t need all of this yet. Worth seeing the names now so you recognize them when they come up.

  • Slash commands. Type /help at the Claude Code prompt to see the full list. The ones you’ll actually use early: /clear (start a new conversation in the same project), /resume (pick up a previous session you closed), /model (switch which version of Claude is responding), /rewind (undo).
  • The safety net: Esc, Esc. Press the Escape key twice. A menu opens that lets you undo Claude’s file changes, undo the conversation, or both. This is how you experiment without fear of breaking something. Every prompt creates a save point you can return to.
  • Permission modes: Shift+Tab. Before Claude Code does anything destructive (deleting files, running risky commands), it asks you to confirm. Pressing Shift+Tab cycles between modes that change how often it asks. Default asks every time. Accept-edits auto-accepts ordinary file changes. Plan makes Claude write out a plan before doing anything at all.
  • @ to mention a file. While typing in the Claude Code prompt, type @ and start a file name. Claude Code autocompletes the path. Useful for pointing the agent at a specific file you want it to look at.

Where to go from here

The agent is installed, signed in, and following its first persistent rule. Two directions for what’s next:

  • Set up your practice with Claude Code. Pick a folder where your AI-agent projects will live, configure git, scaffold your first project by asking the agent, and learn the patterns that make agent-tier work pay off (Plan Mode, the safety net, prompting). The companion guide to this one.
  • Pick a use case from the bullets above. Each Tier 1 / Tier 2 / Tier 3 example in the WHY paragraph is its own short guide; pick what matches the work you actually want to do.

Both build on what you have now.