book2sim turns a textbook or paper PDF into a static website: the PDF on one side, and on the other an interactive simulation that follows the text as you scroll. When the reader reaches a passage about, say, a pendulum's period, the panel beside it shows a pendulum with the parameters that passage discusses, a short note on what to look at, and controls to try other values.
It is inspired by the Hugging Face Space mishig/feynman-interactive, where every simulation and every switch point was written by hand for one book. book2sim does that work for any book, with Claude Code subagents writing the plans and the simulation code.
book2sim runs inside Claude Code as the /book2sim
skill. The Claude Code session you start it from coordinates the run. Python and Node scripts
handle every step that needs no language model, and subagents handle the rest:
- Read the PDF (Python, no model): table of contents, section and figure positions, page text with coordinates. Scanned pages are run through Tesseract OCR.
- Plan each chapter (one subagent per chapter): decide which simulations the chapter needs, one per distinct topic, and where in the text the panel should change to a new simulation or new settings. Each change point is anchored by a short quote from the book.
- Locate the quotes (Python): find each quote in the PDF and turn it into a page position. A quote that cannot be found sends the plan back.
- Write each simulation (one subagent per simulation): JavaScript code against a small
drawing and plotting API (
.claude/skills/book2sim/api.md). An automatic check runs the code outside the browser at every change point and with every control, and rejects exceptions, invalid coordinates, empty or off-screen frames, slow frames, and parameters the plan did not declare. - Check the result on screen (a separate subagent): screenshots of every change point are compared with the note shown to the reader. A mismatch goes back to the plan or to the code.
- Build the site (Python): the viewer, the data, the simulation code and a copy of the PDF, in one folder you can serve from any static file host.
Every intermediate result is a file in work/<book>/, so an interrupted run continues
where it stopped. The design and the reasons behind it are in docs/design.md.
- Claude Code. A whole book uses a lot of model time; see Cost.
- conda (Miniconda or Miniforge) for the Python environment, including Tesseract.
- Node.js 20 or later.
- Linux. Developed and tested only on Ubuntu under WSL2; macOS should work but is untested.
git clone https://github.com/ccy5123/book2sim.git
cd book2sim
conda env create -f environment.yml
bin/b2s setup
bin/b2s testbin/b2s setup installs the viewer and checker dependencies, builds the viewer, and
downloads the headless Chromium that takes the screenshots. bin/b2s looks for the book2sim conda environment under
your conda installation; set B2S_PYTHON to use another Python interpreter.
Open Claude Code in the repository folder and run:
/book2sim path/to/book.pdf --title "Book Title"
Options:
--lang <language>: language of the notes and labels shown beside the PDF (default English). Quotes from the book stay in the book's language.--chapters ch1,ch2: limit the run to some chapters. Trying two chapters first is a good way to judge quality and cost before committing to a whole book.--resume work/<book>: continue an interrupted run.
When the run finishes, the site is in site/<book>/. View it with any static file server:
python3 -m http.server -d site/<book> 8000The PDF is copied into the site, so do not publish a site built from a book you have no right to redistribute.
Every step is a bin/b2s command and can be run without Claude Code, which helps when
debugging a PDF that does not parse well:
| command | what it does |
|---|---|
bin/b2s extract book.pdf work/<book> --title T |
analyse the PDF |
bin/b2s status work/<book> |
progress, and the next actions |
bin/b2s validate work/<book> plan/<ch>.json |
check a chapter plan |
bin/b2s resolve work/<book> |
locate quotes and write the viewer data |
bin/b2s viewer work/<book>/book 5174 |
development viewer with live reload |
bin/b2s check work/<book>/book <demo> |
run the headless check on one simulation |
bin/b2s capture <viewer-url> work/<book>/book <out> <demo> |
screenshots for review |
bin/b2s build work/<book> site/<book> |
assemble the static site |
examples/feynman/ holds three hand-written simulations and their data, used while
developing the viewer (cd runtime && npx vite). Its PDF is not included; the data
expects a 138-page PDF of chapters 1–14 of The Feynman Lectures on Physics, Vol. I, at
examples/feynman/book.pdf.
Measured on two complete runs with Claude Code on a Claude Max plan:
| book | chapters | simulations | subagents | output tokens |
|---|---|---|---|---|
| Feynman Lectures, Vol. I | 14 | 102 | 304 | 7.7 M |
| Kooijman, Dynamic Energy Budget Theory, 3rd ed. | 11 | 120 | 264 | 9.0 M |
The 11-chapter book used a little over 14% of a weekly Max limit. Writing simulation code
accounts for about 85% of the output tokens. The models used for each role are set in
.claude/agents/ and in the table in .claude/skills/book2sim/SKILL.md.
- Input is PDF only. Chapters are found from the PDF outline (bookmarks) or, failing that,
from numbered headings set in a distinct type style; a PDF with neither yields no
chapters, and the run stops. Outline titles with typos or odd hyphenation are carried
into the site as they are; fix them in
work/<book>/book.jsonafter extraction. - Equations come out of PDF text extraction scrambled. The planning subagent is told to read equations from the page images instead, which works but costs more.
- Simulations are written fresh for every book. Their quality depends on the model, and the on-screen check catches most but not all mismatches between a note and what the simulation shows.
bin/b2s entry point for every command
.claude/skills/ the /book2sim skill and the simulation API reference
.claude/agents/ chapter planner, simulation writer, screenshot reviewer
pipeline/ Python steps: extract, validate, resolve, status, build
runtime/ viewer and simulation runtime (TypeScript, Vite, three.js, pdf.js)
checker/ headless checks and screenshots (Node, Playwright)
tests/ Python tests
eval/ scripts that compare a run with the original Feynman Space and tally cost
examples/feynman/ hand-written sample simulations for viewer development
docs/ design document
AGPL-3.0, matching PyMuPDF, which book2sim uses to read PDFs. See LICENSE.