smdesai27/math-board

A black chalkboard in the browser that a terminal tutor draws on while it explains, like a professor at a blackboard. The conversation stays in the terminal. The board is view-only: the model puts up equations, plots, molecules, diagrams and science illustrations through tools, one step at a time, and I watch, step back through the lesson, pan and zoom. I never draw on it. The model does. (The page has two buttons that change anything: Clear, which wipes the board after asking, and Save.)
I study physics, MRI physics (k-space, spins and signal), neuroscience, chemistry and biology for medicine. I tutor myself with pi, a terminal coding agent, running Eero Alvar's learn setup: question-based, one concept at a time. A terminal tutor has no visual channel, and most of what I learn needs a picture, so I built one. It's local and free (no cloud, no extra API keys). It's a separate extension, so Eero's tools stay as he wrote them. And the same tools run as an MCP server, so Claude Code can teach on the same kind of board. Before and after building it I checked about a hundred existing tools (survey); none was view-only, local, lesson-structured and agent-driven at once.
## Install for pi
You need pi and Node 22.19 or later. I use it on macOS; Linux works too. On Windows the board runs, but nothing opens the browser for you, so open the URL from /board yourself.
From npm, once it's published:
sh
pi install npm:pi-math-board
From a checkout, which is how I run it:
sh
git clone https://github.com/smdesai27/math-board ~/math-board
cd ~/math-board && npm ci
pi install ~/math-board
pi loads a local package in place, without copying it, so the checkout is what runs. It doesn't install a local package's dependencies, which is why npm ci comes first. Then run /reload in pi, or restart it.
Two things worth knowing first:
The layout check after each update, boardsnapshot and the PNGs from /board export need a headless Chromium: Playwright's or the system Chrome. For Playwright's, install the build the package expects with npx -y playwright-core@1.64.1 install chromium (the error message names the exact command). Without one the board still works, and those report why they can't. Chromium runs with its OS sandbox; where the sandbox can't start (some Linux containers) it runs without it, and the results say so.
Where the boards live: a checkout keeps them in .data/ next to the code (git-ignored). An installed copy, from npm or pi's git installs, gets replaced or cleaned on update, so it keeps them in a per-user folder instead: ~/Library/Application Support/math-board on macOS, $XDGSTATEHOME/math-board (usually ~/.local/state/math-board) on Linux, %LOCALAPPDATA%\math-board on Windows. MATHBOARDDATADIR overrides both (PIMATHBOARDDATADIR, the old name, still works). /board status shows which folder is in use.
## Use it in pi
Ask the tutor to explain something "on the board". Or:
text
/board open the board in your browser (also /board open)
/board status server URL, revision, data folder, viewers, autosave problems
/board save named snapshot (several words become one name: my lesson -> my-lesson)
/board load restore it