My Claude Code Setup

Actively maintained. A summary of how I use Claude Code for academic work — slides, papers, data analysis, and more — packaged so you can fork it for your own research. See CHANGELOG.md for the latest changes.

Live site: psantanna.com/claude-code-my-workflow

A ready-to-fork foundation for AI-assisted academic work. You describe what you want — lecture slides, a research paper, a data analysis, a replication package — and Claude plans the approach, runs specialized agents, fixes issues, verifies quality, and presents results. Like a contractor who handles the entire job. Extracted from a production PhD course and extended by a growing community.

---

Quick Start (5–10 minutes, plus ~30 min for first-time installs)

Before you start: Claude Code, git and Python 3 are the minimum. Python 3 runs the hooks, the gate suite (./scripts/backtest.sh — 10 checkers) and the quality scorer, and is pre-installed on macOS/Linux. To run the included HelloWorld demos end-to-end you also need XeLaTeX (Beamer sample) and Quarto (Quarto sample). R and the GitHub CLI are recommended. Full list in Prerequisites below. Fastest path: clone first, then run ./scripts/validate-setup.sh — it reports exactly what's missing with install links.

Only need Python/R/markdown? You don't need XeLaTeX or Quarto. The agents, rules, skills, and orchestration patterns work for any text/code artifact. Skip the HelloWorld demos and head straight to /data-analysis, /review-paper, /lit-review, or /review-r.

Session 2 onwards: MEMORY.md (committed) collects generic [LEARN] entries that help all forkers; machine-specific notes accumulate in Claude Code's native auto memory (~/.claude/projects//memory/, machine-local, never committed). See .claude/rules/meta-governance.md for the distinction.

1. Fork & Clone

# Fork this repo on GitHub (click "Fork" on the repo page), then:
git clone https://github.com/YOUR_USERNAME/claude-code-my-workflow.git my-project
cd my-project
./scripts/validate-setup.sh        # reports missing tools with install links

Replace YOUR_USERNAME with your GitHub username.

2. Start Claude Code and Paste This Prompt

claude

Using VS Code? Open the Claude Code panel instead. Everything works the same — see the full guide for details.

Avoid prompt fatigue. On Claude Code ≥ 2.1.283, new interactive sessions start in auto mode by default (classifier-gated — most actions run, risky ones prompt; on earlier versions this applied to Pro/Max/Team); where auto is unavailable, Manual mode prompts per risky tool call. If you still see too many prompts, toggle Auto-accept edits mode (a keybinding; see the permission modes section of the guide) or run claude --permission-mode acceptEdits. Bypass mode skips permission prompts and safety checks (deny rules still apply), and Anthropic scopes it to isolated containers and VMs; it takes effect from the CLI flag, --settings, or user/managed settings (~/.claude/settings.json) — a bypass default in a project's .claude/settings.json is not honoured (the session starts in Manual). The template's .claude/settings.json sets no default mode (terminal sessions get the platform's auto mode); its .vscode/settings.json carries two bypass keys, but the current VS Code extension ignores them (it reads claudeCode.initialPermissionMode and claudeCode.allowDangerouslySkipPermissions only from your VS Code user settings, and never reads the unprefixed allowDangerouslySkipPermissions key), so VS Code sessions also start in auto unless your user settings say otherwise — set both claudeCode. keys there if you want bypass in VS Code — and the .claude/settings.json ships broad catch-all allows (Bash(*), Edit(**), Write(**) — 7 wildcard rules, not a curated list), so in Manual mode almost nothing prompts; auto mode drops the blanket Bash(*) and routes shell commands through its classifier. Working with restricted data? Add deny rules — see TROUBLESHOOTING.

Then paste the starter prompt from the guide, filling in your project details:

I am starting to work on [PROJECT NAME] in this repo. [Describe your project in 2–3 sentences.] I've set up the Claude Code academic workflow... Please read the configuration files and adapt them for my project. Enter plan mode and start.

The full guide has the complete starter prompt with all the details.

What this does: Claude reads all the configuration files, fills in your project name, institution, and preferences, then enters contractor mode — planning, implementing, and (within the skill you invoke) running the review + verify loop. You approve the plan, invoke a skill, and the skill handles the rest within its scope.

Heavily adapting CLAUDE.md for a non-academic project? Anthropic's built-in /init command will re-derive a CLAUDE.md from your codebase as a starting point. The pre-shipped CLAUDE.md in this template already covers the academic setup — you only need /init if your fork diverges substantially (e.g., a Python/ML project that doesn't use LaTeX or Quarto).

3. Verify Your Setup

Before building real lectures, confirm your environment works:

./scripts/validate-setup.sh        # Checks XeLaTeX, Quarto, Python, git, etc.

Then inside Claude:

/compile-latex HelloWorld