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 — 11 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/<project>/memory/, machine-local, never committed). See .claude/rules/meta-governance.md for the distinction.

1. Fork & Clone

Unpublished work? Choose before you copy. GitHub keeps a fork of a public repository public, and its visibility cannot be changed. For a paper, data or anything not yet public, click Use this template on the repository page instead, set the new repository to Private, and clone that one: git clone https://github.com/YOUR_USERNAME/YOUR_REPO.git my-project. Fork only for work that can be public.

# 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.

Using Codex (now also a tab in the ChatGPT desktop app) or Antigravity? Start with AGENTS.md. Those agents read the skills in .agents/skills/: generated wrappers that point to the real instructions in .claude/skills/, for every skill one agent can run end to end. Claude Code's deny rules and guard hooks do not apply to them, so AGENTS.md lists what they must do by hand; the pre-commit gate and CI still apply. Skills built on several independent reviewers (/review-paper --peer, /seven-pass-review, /verify-claims) and the ones that manage Claude Code itself stay Claude-only — the list and the reasons are in scripts/sync-agent-skills.py.

Avoid prompt fatigue. On Claude Code ≥ 2.1.283, new interactive terminal and VS Code sessions start in auto mode by default (a classifier approves routine actions and prompts on risky ones). Where auto mode is unavailable, this template's .claude/settings.json ships broad allow rules (Edit(**), Write(**), Bash(*)), so routine work inside the repo runs unprompted. It does not set permissions.blockWritesOutsideWorkingDirectories (removed in v2.9.1), so Claude can change .claude/settings*.json itself. To turn that block on, add "blockWritesOutsideWorkingDirectories": true under permissions (Claude Code ≥ 2.1.314): Claude's file tools then refuse writes outside the working directories and every write to a Claude Code settings file, even inside the repository, and the worktree tools (EnterWorktree, ExitWorktree) leave the session. A true in any settings file applies, and lifting it takes a restart. If you still see prompts, press Shift+Tab to switch to Auto-accept edits (claude --permission-mode acceptEdits). For container/VM Bypass mode or restricted-data deny rules, see TROUBLESHOOTING.md.

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.

This is the beginning of the README. Read the rest at the original. Read the full README ↗