Up to this point in the thesis series, everything has been about writing — choosing a topic, drafting an outline, running the literature review. This post is a detour into tooling. I’d been using Claude through the web chat for a while, and I wanted to try Claude Code — the terminal-based version — alongside my actual thesis code, not as a replacement for the web chat but as something I could use directly in the project.
This is a walkthrough of what I did on a Mac, in the order I did it. The point is less about the software itself and more about the small decisions that come up when you plug any AI coding tool into an existing project. The mechanics took less time than I expected. The setup choices around it — which directory to launch from, what context to give the tool, what to ask it first — took more.
Before you install, check what’s there
The instinct is to run the installer first and figure things out later. Two quick checks save time. The first is whether Claude Code is already on your system, which is possible if you tried it before or if it came bundled with something else:
claude --version
If a version prints, it’s already installed and you can skip ahead to the health check. Otherwise, if you get command not found, you’re on a clean slate. If you get something ambiguous a weird error that isn’t “not found” run which claude to see whether the binary exists somewhere outside your PATH.
The second check is whether you have Homebrew, which is the easiest way to install Claude Code on macOS:
brew --version
If a version prints, you’re ready. If not, install Homebrew from brew.sh first — it’s a single command from their site.
Installing Claude Code
There are three supported installation paths on macOS. The native installer is the newest and what Anthropic currently recommends (a single curl command, auto-updates in the background, no dependencies). Homebrew is also supported and has the advantage that it fits into whatever package-management habits you already have. The older npm install is now deprecated, though it still works.
I used Homebrew because I already use it for everything else. Homebrew offers two casks:
claude-code — the stable channel, roughly a week behind the latest release, skips versions with known regressions.
claude-code@latest — the latest channel, newest build with no safety net.
For a thesis project I wanted stability over new features, so I installed the stable one:
brew install --cask claude-code
This downloads the binary and links the claude command into your PATH. Took about a minute. After installation:
claude –version
which claude
Both should print something sensible. If claude --version doesn’t work in the terminal tab you just installed from, open a new tab — PATH changes sometimes need a fresh shell.
One thing worth knowing: Homebrew installations don’t auto-update. When you want the newest features and fixes, you run brew upgrade claude-code manually. The native installer does update automatically, which is the main reason to prefer it if you don’t care about the Homebrew integration.
First launch: where you run it matters
The first time you run claude, it sets up a session for whatever directory you’re currently in. It asks whether it can trust that directory for file edits, and it opens a browser window for you to log in. Because of this, the directory you launch from matters. Launch from your project root — not your home folder, not Downloads, not anywhere else.
I launched from inside my project folder, after activating the right conda environment. The environment activation isn’t strictly required for the first login, but it’s a habit worth building: when Claude Code actually starts running code later, it uses whatever environment is active, so you want that to be the project’s environment from the start.
The first-launch sequence is short:
1. Theme prompt. Dark or light. Cosmetic. Changeable later with /config.
2. Login method. A short menu. For a paid Claude account (Pro or Max) pick the “Claude Account” option, not Anthropic Console and not a third-party provider. A browser tab opens.
3. Browser OAuth. If you’re already signed into claude.ai with the account you want to use, it’s a single click. If you have multiple Anthropic accounts — a trial and a paid one, say — slow down here. It’s easy to authorize the wrong account and then wonder later why quotas feel off.
4. “You can close this tab.” Back to the terminal. It’s already moved on.
5. Trust this directory? Answer yes. This grants permission to read and edit files in this directory only — not your home folder, not a sibling repo.
You land on a minimal prompt with a > and a banner. Don’t start real work yet.
Health check before doing anything real
Two slash commands confirm the session is wired up the way you expect.
/status
This prints a panel with the version, the current working directory, the login method and email, the default model, the IDE connection status, and any MCP server status. Two things surprised me when I ran it. First, the default model on the Max plan was Opus, not Sonnet. Opus is more capable but more expensive in token terms, and it has its own cap separate from Sonnet’s. For mechanical work — renames, docstring cleanup, small refactors — Sonnet is usually the right choice, and you can switch with the /model command. For statistical reasoning or auditing complex code, Opus earns its cost. I left it on Opus because the first real task I had in mind was an audit of existing code.
Second, the VS Code connection happened automatically. I hadn’t installed any extension manually, but the status line said the VS Code extension was connected. The cask ships the extension, and running claude from VS Code’s integrated terminal hooks them together with no setup on your side. If you start from an external terminal instead, there’s a /ide command to connect.
The MCP server warnings in the status panel can usually be ignored at this stage. MCP (Model Context Protocol) servers are optional bridges to external services like Gmail or Google Drive. If you haven’t configured any, they sit there doing nothing, which is fine.
The second command is broader:
/doctor
This runs a battery of sanity checks — install method, binary location, current version versus latest version, update channel. Mine confirmed I was on the stable cask and a few releases behind the bleeding edge, which was the point.
A small thing: the slash matters
Early on I typed status without the slash. Claude Code interpreted it as a natural-language request, read through my repository, noticed the file I had open, and wrote me a thoughtful summary of the project’s current state. Impressive, but not what I wanted — I wanted the meta-info panel. Slash commands are commands. Everything else is a prompt. Remember the slash.
Giving it context: CLAUDE.md
Claude Code doesn’t remember anything about your project between sessions. To avoid re-explaining the same setup every time — this is Python, the env is called X, write in English in code and comments — you create a file called CLAUDE.md in the project root. Claude Code loads this into context automatically at session start.
Location matters. It has to be at the project root, not in a subdirectory. Subdirectory CLAUDE.md files do exist for scoped rules, but they’re only pulled in lazily when Claude reads a file from that subdirectory — they won’t apply when you’re just talking to Claude from the project root.
I kept my first version short, roughly one page:
The tech stack (language, environment name, main pipeline outputs).
Language rules — what language the chat is in, what language code comments and filenames should be in, and keeping the two separate.
Workflow discipline — plan before coding, expect pushback on methodology, log any statistical decision somewhere concrete.
A short list of don’ts — no autonomous commits, no environment changes without asking, no direct notebook edits.
The advice I found most useful while writing this file was: don’t overstuff it. Models follow on the order of 150–200 instructions reliably, and past that, some get quietly ignored. Start minimal. Grow the file as patterns emerge.
Read before you edit
My project wasn’t green-field. There was already a fair amount of code across several modules, and I wanted to know whether there were methodological gaps before letting Claude Code touch anything. The natural first prompt wasn’t “write me something” — it was “read what’s there and tell me what’s wrong.”
This is worth stating plainly: when you bring any AI coding tool into an existing project, the first substantive prompt should be a read-only audit, not an edit. It forces the tool to load the actual code into context instead of guessing from file names, and it gives you a baseline you can act on.
My audit prompt had four parts:
File-structure audit. Are the module boundaries sensible, is there dead code, does naming match the conventions in CLAUDE.md.
Question-by-question check. For each question the current phase of the project was supposed to answer, is there a function that answers it, is the answer reported somewhere concrete, is there a note in the decision log.
Artifact status. Is every figure, table, and methods paragraph that was supposed to exist actually on disk.
Methodological red flags. Specific failure modes I wanted checked — subtle issues in formulas, handling of missing data, multiple-comparison concerns, numerical stability. Whatever a tough reviewer would catch first.
I ended the prompt with explicit constraints: don’t change any code, this is diagnostic only, ask before going deeper into any one function. Those constraints are what made the audit useful instead of disruptive. Without them, an AI tool that can edit files will often start editing.
The audit took a few minutes to run. Opus is slower than Sonnet for this kind of task because it’s reading files and reasoning through the questions, not just pattern-matching. A two-to-ten-minute wait is normal for an audit of this shape.
What was easy, what wasn’t
The mechanical install was under ten minutes. Authentication was two. The health checks were mostly me reading what each line in /status meant, not waiting on anything. The parts that took actual thought were writing CLAUDE.md and composing the audit prompt — maybe thirty-five minutes combined, and both worth every minute.
If I had to boil it down: the install is the easy part. The two things that repay the investment are writing a focused CLAUDE.md and resisting the urge to ask the tool to do something before you ask it to understand what’s already there. Commit your current state to git before any substantive edits start — Claude Code has its own rewind and checkpoint features, but neither is a substitute for a clean working tree you can fall back to.
Next post moves back to the thesis itself.
Leave a Reply