Claude Code: Setup and the Four Ways to Use It

Claude Code is Anthropic's AI coding assistant. It can read your files, run shell commands, edit code, and execute long multi-step research tasks — locally, on your data. This tutorial shows you how to install and use it on macOS and Windows in both the terminal and the desktop app.

1. Installation

macOS — Terminal (CLI)

# Easiest: with Homebrew
brew install --cask claude-code

# Or, with npm (works on any platform)
npm install -g @anthropic-ai/claude-code

# Verify
claude --version

macOS — Desktop App

Download Claude.app from claude.ai/download, drag it to Applications, and open it. Claude Code is available inside the desktop app as a side panel for any project folder you open. The desktop and CLI share the same login (your Claude account), so a tool that you've authorised in one is authorised in the other.

Windows — Terminal (CLI)

# PowerShell, as Administrator
winget install Anthropic.ClaudeCode

# Or via npm
npm install -g @anthropic-ai/claude-code

# Verify
claude --version

On Windows you'll get the smoothest experience using Windows Terminal (not the legacy cmd.exe). If you're a developer, install WSL2 + Ubuntu and run Claude Code from inside WSL — many ML tools assume a UNIX environment and "just work" there.

Windows — Desktop App

Download Claude for Windows from claude.ai/download and run the installer. Same integration as on macOS — open any project folder and Claude Code is a side panel.

First-run login

The very first time you run claude from a terminal it'll open your browser to log in. After that your credentials are cached in ~/.claude/ (macOS/Linux) or %USERPROFILE%\.claude\ (Windows). The desktop app uses the same credentials.

2. The four ways to use Claude Code

Way 1 · Terminal, one-off prompt

# Print a single answer and exit
claude -p "Summarize the columns in detections.csv as a markdown table"

Use for: quick lookups, scripts and pipelines, CI/cron jobs ("run this every Monday and summarize the new detections").

Way 2 · Terminal, interactive session

# From your project root
cd ~/research/oregon_critters_2025
claude

Drops you into a REPL where Claude can read your files, edit them, run commands, and ask you follow-ups. Useful keystrokes:

Use for: actual day-to-day coding work, debugging, refactoring, "do this whole thing".

Way 3 · Desktop app, file-picker chat

Open Claude.app, click New conversation, attach the file(s) you want to talk about, and chat. This is what most non-coders use first.

Use for: quickly asking Claude to look at a CSV and propose a model, summarize a paper PDF, or convert a Word document into a table.

Way 4 · Desktop app, project workspace

Click Open folder and pick your project directory. The right-hand panel is a full Claude Code conversation with read/write access to that folder. The middle pane shows file diffs as Claude edits them — you click Approve or Reject on each one.

Use for: long sessions where you want a visual diff to review, side-by-side with the code.

3. Choosing between them

4. Plan mode — the most important feature for research

When you ask Claude Code to do something non-trivial, you almost always want it to plan before it acts. Press Shift+Tab until you see plan mode in the status bar (or use /plan). In plan mode Claude will:

1. Read the relevant files,
2. Write out a step-by-step plan with files it intends to create/modify,
3. Stop and wait for your approval,
4. Then execute the plan.

For everything statistical in this course — simulations, model fitting, report generation — always start in plan mode. The cost is 30 seconds; the upside is catching wrong approaches before they cost you an hour.

5. CLAUDE.md — your project context file

Drop a file called CLAUDE.md at the root of your project. Claude reads it automatically every time it starts a session in that folder. Use it to record:

• What the project is and what the biology question is.
• Where the data lives and what its columns mean.
• Conventions you want followed ("use unmarked, not ubms, for occupancy fits").
• Anything that's gone wrong before that you don't want repeated.

Example for a camera-trap project:

# Oregon Critters — Crater Lake 2024

This project analyzes camera-trap data from 24 cameras deployed at Crater Lake
National Park, July–September 2024.

## Data
- `data/raw/`              raw images, one folder per camera
- `data/detections.csv`    output of MegaDetector v5 (animal/person/vehicle)
- `data/classifications.csv` output of our YOLOv8 species classifier
- `data/sites.csv`         per-camera covariates (elevation, NDVI, distance to road)

## Conventions
- Use R + `unmarked` for occupancy modelling. Not `ubms`.
- All plots use `ggplot2` with `theme_bw()` and viridis colour scales.
- Random seed for any simulation: 42.
- Site IDs are strings like "CL_A12", never integers.

## Known issues
- Camera CL_B07 had a stuck shutter on 2024-08-12; drop that day.
- The species "elk" includes both Roosevelt and Rocky Mountain elk — not
  separable from imagery.

6. Permissions and safety

Claude Code asks before doing anything risky. The default policy is:

• Read any file in the project: allowed without asking.
• Edit a file: prompts for approval the first time per session, then runs freely.
• Run shell commands: prompts every time unless you've granted blanket permission for a command class.
• Network access / outside the project folder: always prompts.

You can pre-approve patterns by adding them to .claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(python *)",
      "Bash(Rscript *)",
      "Bash(git status)",
      "Bash(ls *)"
    ]
  }
}

7. MCP servers (optional, for advanced users)

The Model Context Protocol (MCP) lets Claude talk to outside services as if they were tools. Useful MCP servers for ecology work:

• R via mcptools — lets Claude execute R code in your active R or RStudio session and inspect your data frames and models. Pure R, no Node.js needed. See the Claude Code in RStudio tutorial for a slow walkthrough.
• SQLite MCP — for camera-trap projects with detection databases.
• Filesystem MCP — lets Claude read files outside the project directory (e.g., a shared archive drive).
• GitHub MCP — rich interaction with GitHub issues, PRs, and repository contents (Node.js required — this one is launched with npx).

For most R users, the only one worth setting up early is mcptools. Install in R with install.packages("mcptools"), then add this block to ~/.claude.json:

{
  "mcpServers": {
    "r": {
      "command": "Rscript",
      "args": ["-e", "mcptools::mcp_server()"]
    }
  }
}

Full configuration and the live-R-session workflow are in the Claude Code in RStudio tutorial.

8. Driving Git and GitHub through Claude Code

This section assumes you have worked through the Git & GitHub tutorial at least far enough that you have git installed, a GitHub account, and either the gh CLI authenticated or an SSH key set up. If not, go do that first — Claude Code is great at using git, but it can't install it for you, and it can't log into GitHub on your behalf.

The promise of pairing Claude Code with GitHub is that you can stay in plain English for almost everything. You describe what you want; Claude runs the right commands and shows you the diff. We'll walk through this in slow motion.

Step 1 — tell Claude Code about your project

Open a terminal and navigate to a folder you want to put under version control:

cd ~/research/oregon_critters_lab3
ls
# detect.py  data.yaml  results.csv  figs/

Start a Claude Code session:

claude

At the prompt, type:

"This folder isn't a git repo yet. Initialize it, write a sensible .gitignore for a Python/PyTorch + camera-trap project (no images, no model weights, no Anthropic credentials), make an initial commit, and stop. Don't push anywhere yet."

Claude will (a) propose the commands, (b) ask permission to run git init, (c) write .gitignore, (d) git add the source files but not the data/weights, (e) git commit -m "initial commit". Watch the .gitignore diff carefully: this is the file most likely to leak something later if it's wrong now.

Step 2 — create the GitHub repo from inside Claude Code

If you have gh installed and authenticated, you don't need to leave the terminal:

"Create a private GitHub repo called oregon-critters-lab3 under my account using gh repo create, then push the current branch."

Claude will run something like:

gh repo create oregon-critters-lab3 --private --source=. --remote=origin --push

You'll see the repo URL in the output. Open it in a browser to confirm.

Step 3 — the everyday "commit and push" loop with Claude

After you've made changes, ask Claude:

"Show me git status and git diff --stat. Then group the changes into 2–3 logical commits, write a clear commit message for each, and push. Don't include anything in data/ or any .pt files."

Claude will:

1. Run git status — you see what's changed.
2. Run git diff --stat — you see how many lines per file.
3. Propose grouped commits: "commit 1: detect.py — lower confidence threshold to 0.2"; "commit 2: figs/pr_curves.png — refreshed plots"; "commit 3: README.md — document the threshold change".
4. Stage, commit, and push each group.

This is much better than letting Claude pile every change into one giant commit, because your git log stays useful.

Step 4 — cloning and exploring someone else's repo

Say you want to use Zach Ruff's pycnet-audio package and you want a tour before you run anything. From a fresh terminal:

cd ~/research
git clone https://github.com/zjruff/pycnet-audio.git
cd pycnet-audio
claude

Then ask:

"Read the README, the docs/ folder, and pyproject.toml. Summarize in 5 bullets: (1) what this package does, (2) what the main CLI commands are, (3) what its Python and SoX version requirements are, (4) how the spectrogram pipeline is parallelised, and (5) anything that would trip me up on macOS / Apple Silicon. Don't run anything — just read."

You'll get a tight orientation in a minute or two. This is one of the biggest wins of pairing Claude Code with GitHub: you don't have to read every repo cover-to-cover before you know whether it's worth installing.

Step 5 — branches and pull requests

For any non-trivial change, work on a branch:

"Make a branch called fix-threshold-doc, change the default confidence threshold in detect.py from 0.25 to 0.20, update the README to match, commit, and push the branch."

Then open a PR against your main branch (great for code review with a TA or advisor) without leaving Claude:

"Open a pull request from fix-threshold-doc to main using gh pr create. The title should be 'Lower default MD threshold to 0.20'. Write a description with three sections: Motivation, Changes, Testing."

Claude will produce the PR with a heredoc'd body and show you the URL. Reviewers can comment line-by-line on GitHub, and you can keep pushing commits to the same branch — they'll appear in the PR automatically.

Step 6 — contributing back to pycnet-audio (the real workflow)

You found a small bug in someone else's repo. The fork-PR cycle in Claude Code:

"I want to contribute a fix to zjruff/pycnet-audio. Fork it under my account with gh repo fork, clone the fork into ~/research/, create a branch called fix-readme-typo, change line 42 of README.md from 'reqiures' to 'requires', commit with a clear message, push, and open a PR upstream. Walk me through each step before you run it."

The "walk me through each step before you run it" suffix is important: it forces Claude into a checkpointed mode where you approve each command. For a workflow that touches someone else's repo, you absolutely want that.

Step 7 — reading and resolving merge conflicts

When a git pull fails with a conflict, you'll see something like CONFLICT (content): Merge conflict in detect.py. Don't panic. Tell Claude:

"I have a merge conflict in detect.py. Show me the conflicted sections, explain in plain English what each side did, and propose a resolution that keeps both my new threshold logic and the upstream logging change. Don't auto-resolve — show me the diff and wait for me to approve."

This is where AI-assisted git pays off: merge conflicts are tedious but conceptually simple, and Claude is very good at them — provided you make it explain rather than auto-resolve.

Common pitfalls when mixing Claude Code with git

9. A 5-minute first session

1. Create a new folder: mkdir cc_demo && cd cc_demo
2. Drop a small CSV into it (e.g., one site's BirdNET output).
3. Run claude.
4. Type: "Look at the CSV in this folder. Tell me which species had the most detections and plot the diel activity pattern for the top 3 species. Use Python and save the figures to PNG."
5. Watch it plan, write the script, run it, and show you the output. Approve each edit.

→ Continue to Claude Code: Dos & Don'ts