A Claude Code workspace for technical coursework — CS, math, physics, engineering.
Give it your lecture slides, homework, and study guides. It gives you back:
- Memorization tables — every topic explained in plain language without losing the technical content, followed by flashcard tables you can actually drill.
- Homework solutions and explanations — full reasoning, sanity checks, and a running log of what you struggled with.
- Study plans — day-by-day, built from the actual study guide, telling you which notes to review, which to skip, and where your notes have holes.
- A record of your own mistakes — every error logged as three bullets (what was asked, what went wrong, what to do next time), consolidated into one playbook of the patterns that actually cost you points.
- Optional spaced repetition — schedule the flashcards you've already built, and photo upload so your handwritten work gets checked step by step.
Everything is plain markdown in folders you own. No database, no lock-in.
Requires Claude Code and Python 3.9+.
cd coursework-assistant
claudeThen, inside Claude Code:
/setup
That creates a .venv and installs the document parsers (PyMuPDF, python-pptx,
python-docx, Pillow). Or do it yourself:
python scripts/setup.py # creates ./.venv
python scripts/setup.py --check # verify/class-new PHYS 2211 — Intro Physics I
It scaffolds classes/phys-2211/ and asks a few questions about how you want this class
handled. Then:
/ingest phys-2211 ~/Downloads/lecture-04.pdf
/memtable phys-2211 lecture-04
You now have classes/phys-2211/notes/01-<topic>.md — explained sections plus flashcards,
with any hand-drawn diagrams cropped out of the PDF and embedded inline.
| Command | What it does |
|---|---|
/setup |
Install dependencies, verify the workspace |
/class-new <name> [term] |
Create a class folder and set its preferences |
/class-note <class> <instruction> |
Add a handling preference for a class |
/status [class] |
What exists, what's missing, what to do next |
| Command | What it does |
|---|---|
/ingest <class> <file-or-folder> |
Add lecture material and extract it |
/ingest <class> <file> --kind hw --hw hw03 |
Add a homework assignment |
/ingest <class> <file> --kind exam --exam exam1 |
Add a study guide or practice test |
Accepts .pdf, .pptx, .docx, .md, .txt. You can pass a whole folder.
PDFs are rendered page by page, so diagrams, handwriting, and scanned pages are read as images rather than lost. PowerPoint files give up text, speaker notes, and embedded pictures — for a diagram-heavy deck, export it to PDF first and ingest that instead.
| Command | What it does |
|---|---|
/memtable <class> <doc> |
Build the memorization tables for a document |
/quiz <class> [topic] |
Drill your flashcards one card at a time |
/srs <class> on|off|status |
Turn spaced repetition on or off (off by default) |
/review <class> |
Run today's scheduled review session |
/memtable is the core feature. For each topic it writes:
- Concept bullets — the plain-language idea and the precise technical statement, every symbol defined, assumptions and edge cases spelled out, derivations kept.
- A two-column flashcard table — front and back, one idea per card, backs that stand alone.
- Step-by-step problem procedures, when the class calls for them.
- Cropped figures from the source, embedded where prose can't do the job.
- A coverage check mapping every source page to a section, so nothing is silently dropped.
Off unless you turn it on, per class:
/srs phys-2211 on
It asks how many new cards a day you want (default 15) and which files to schedule, then
tracks every flashcard row in your notes with an SM-2 schedule. It doesn't copy your cards —
it reads them from the notes, so editing a note edits the card. /review phys-2211 then
serves only what's due, one card at a time, and records how each went.
/review phys-2211
Cards you miss come back in the same session and get scheduled sooner; cards you know drift
further out. Anything missed twice lands in your mistake log. Turn it off any time with
/srs phys-2211 off — your history is kept. /quiz still works either way, for drilling
outside the schedule.
| Command | What it does |
|---|---|
/hw <class> <assignment> |
Work the assignment with full solutions |
/explain <class> <hw-id> <part> |
Walk through one part slowly |
/check <class> <photo of your work> |
Find the first place your reasoning breaks |
/struggle <class> <what was hard> |
Log a weak spot for later |
/explain focuses on how to recognize this problem type — the transferable part — not
just this problem's algebra. Anything you /struggle (and anything you ask /explain
about) lands in struggles.md and gets extra practice when you build a study plan.
Take a photo of your handwritten work and:
/check phys-2211 ~/Desktop/IMG_4821.HEIC --hw hw03
Photos get rotated, downscaled and read in page order (multiple photos, a scan, or a PDF all work; HEIC from an iPhone is handled). Then it follows your reasoning line by line and stops at the first step that breaks — quoting the line, saying what's wrong with it, giving the correct version of that step only, and telling you the check that would have caught it. It won't solve the rest for you, so you can fix it and resubmit.
If your method differs from the obvious one, that's not treated as an error. And if the work is right, it says so rather than inventing nitpicks — though it'll flag anything correct but fragile.
| Command | What it does |
|---|---|
/mistake <class> <what went wrong> |
Log one mistake as three bullets |
/postmortem <class> <exam> |
Debrief a graded exam |
/playbook <class> |
Consolidate everything into one document |
Every mistake — from homework, a quiz, a review session, a practice test, or a graded exam —
gets logged to mistakes.md in the same shape:
## 2026-09-14 — Gauss's law: chose a surface where |E| was not constant
- **Where:** hw03 P2b
- **Tags:** gauss-law, symmetry
- **Asking:** Find the field of a continuous charge distribution using symmetry.
- **Mistake:** Picked a spherical surface, so |E| varied over it and couldn't leave the integral.
- **Next time:** Match the surface to the symmetry before writing anything; check |E| is constant on every face.
- **Status:** openThree bullets, always: what the question was asking (generalized to the problem type, so you recognize the next one), what the mistake was (one precise sentence), and what to do next time (an action you can execute under time pressure — never "be more careful").
/postmortem runs after you get a graded exam back. Give it the exam — photos, a PDF, or
just your memory of what you lost points on — and it writes one mistake entry per miss, then
diagnoses the cause of each: didn't know it, knew it but chose the wrong method, execution
slip, misread the question, ran out of time. Those lead to opposite fixes, which is why
"careless" isn't accepted as an answer. It also grades your prep, comparing what was actually
tested against what plan.md assumed, so the next study plan is better calibrated.
/playbook folds all of it into playbook.md — one document to read before a problem set
and the night before an exam. It groups mistakes into patterns by cause and fix rather than
by topic, each with the trigger to recognize, the rule that prevents it, and the check that
catches it. Plus a short pre-submit and pre-exam checklist, general tips for the class, and
one-offs that haven't recurred yet. Anything you write under "Your own rules" is preserved
verbatim when it rebuilds.
| Command | What it does |
|---|---|
/testprep <class> <exam> --days N |
Build the study plan |
/cram <class> <exam> |
Narrow, exam-only memorization tables |
/practice-map <class> <exam> [test] |
Map each practice question to the notes |
/qbank <class> <exam|topics> |
Build a practice question bank |
/testprep reads the study guide, Canvas discussion post, syllabus, or practice test
you give it and produces tests/<exam>/plan.md containing:
- Coverage table — every tested topic, with the verbatim phrase it came from and how heavily it's weighted.
- Note triage — which of your notes to review, which to skim, and which to skip with the reason they're off-target for this exam.
- Gaps — topics the exam says are tested that nothing in your folder teaches, and how to close each one.
- Day-by-day plan — content days first, with the exact sections to open and a concrete "done when" check, then 1–2 practice days at the end.
/cram is the opposite of /memtable: only what you must produce from memory to
answer questions on that one exam. Everything explanatory stays behind in notes/. Each
row is justified by a coverage topic or a practice question, and it includes the
discrimination pairs the exam will try to trip you on. If your class allows a handwritten
note sheet, it shapes the table to fit the sheet.
Each class has a class.md that every command reads first. It's how you teach the tool the
shape of a class:
## Preferences — memorization tables
- Add a step-by-step written procedure to memorize for each problem type.
- Every formula card must state when the formula does NOT apply.
## Preferences — homework
- Show every algebra step. Keep units in every intermediate line.
- Code answers in Java 17 with complexity analysis under each part.
## Preferences — test prep
- Exams are closed book with one handwritten sheet; cram notes must fit one page.
- This professor tests conceptual multiple choice more than computation.Edit the file directly, or add to it as you go:
/class-note phys-2211 always write a step-by-step procedure for each problem type
These override the tool's defaults. It's the difference between generic notes and notes that match how your class actually works.
classes/phys-2211/
class.md your preferences for this class
index.md generated topic -> notes map
struggles.md topic-level: what felt hard
mistakes.md question-level: what went wrong, three bullets each
playbook.md generated: your patterns and rules, in one document
srs/ spaced repetition schedule (only if you turned it on)
source/lectures/ the originals you ingested
extracted/<doc>/ text.md, page renders, embedded images
notes/ memorization tables <- what you study
notes/assets/ figures cropped from slides
homework/hw03/ prompt/, solution.md, explanations/, work/
tests/exam1/ info/, plan.md, question-map.md, cram-notes.md, qbank.md,
postmortem.md, work/
extracted/ is regenerable and git-ignored. Everything else is yours to keep.
The commands call these, but they work standalone:
python scripts/status.py # dashboard
python scripts/index.py phys-2211 # rebuild the topic index
python scripts/ingest.py phys-2211 slides.pdf # copy in + extract
python scripts/extract.py slides.pdf # extract only
python scripts/snip.py slides.pdf --page 7 --bbox 0.1,0.3,0.6,0.7 --out fig.png
python scripts/srs.py enable phys-2211 --new-per-day 15
python scripts/srs.py due phys-2211 # what's due today
python scripts/srs.py stats phys-2211 # schedule overview
python scripts/prepwork.py phys-2211 photo.jpg --hw hw03 # normalize work photosSpaced repetition state is plain JSON in classes/<slug>/srs/ — delete the folder to reset.
Solutions are written to check your work against, and the tool is built around that:
/explain teaches the method, /struggle tracks what didn't stick, and test prep is
driven by both. Course policies on AI assistance vary — tell the tool if yours restricts
it on graded work and it will stick to explanation instead of worked answers.