Math board

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 you watch, step back through the lesson, pan and zoom. You never draw on it. The model does. (The page has two buttons that change anything: Clear, which wipes the board after asking, and Save.)

A terminal tutor has no visual channel, and much of what people learn needs a picture. This gives it one. It's an extension for pi, a terminal coding agent, and the same tools run as an MCP server for Claude Code and other MCP clients. It's local and free (no cloud, no extra API keys). A survey of about a hundred existing tools found none that was view-only, local, lesson-structured and agent-driven at once.

Install for pi

You need pi and Node 22.19 or later. It works on macOS and Linux. 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:

pi install npm:pi-math-board

From a checkout:

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, board_snapshot 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, $XDG_STATE_HOME/math-board (usually ~/.local/state/math-board) on Linux, %LOCALAPPDATA%\math-board on Windows. MATH_BOARD_DATA_DIR overrides both (PI_MATH_BOARD_DATA_DIR, 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:

/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 /board export [name] write the lesson to ./viz/: board.json, PNGs, lesson.md /board clear clear everything (or /board clear equations|scene) /board stop stop the server

The server starts on first use and listens only on 127.0.0.1. The URL carries a private #token=…; don't share it. After /reload or /board stop the next board in the same pi session reuses the port and token, so a tab that's still open reconnects by itself. If the server is gone for good, the page says so after about 10 seconds and keeps trying in the background.

Use it from Claude Code and other MCP clients

The same tools run as a stdio MCP server, mcp/server.mjs. Both the pi extension (index.ts) and the MCP server are thin adapters over one implementation, tools.mjs, so the model gets the same tool names, descriptions, schemas and results either way, and the board_teaching rhythm (read, draw one step, ask one check question) is the server's instructions. One learner workflow, whichever agent is teaching.

Register it with Claude Code once:

claude mcp add math-board -- npx -y pi-math-board              # from npm, once published

claude mcp add math-board -- node ~/math-board/mcp/server.mjs # from a checkout, after npm ci

That registers it for the folder you run it in (scope local), so the board and its instructions exist only there; add --scope user for every project. claude mcp list should show ✔ Connected, and /mcp inside Claude Code reconnects it after you change the code. In pi, use the extension rather than pi mcp add: with both you'd get two separate boards.

Other MCP clients take the same command as a stdio server:

{

"mcpServers": { "math-board": { "command": "npx", "args": ["-y", "pi-math-board"] } } }

For a checkout, use "command": "node" and "args": ["/absolute/path/to/math-board/mcp/server.mjs"].

• Tools: the seven in Model tools. All seven are listed from the start (MCP has no lazy activation like pi's); the model calls board_open to show the board. board_snapshot returns the PNG as an MCP image block, followed by the text summary.
• Browser: board_open opens the board in your default browser unless a browser already shows it. The URL, with its token, goes into the model's context only when no browser could be opened; then the model passes it on to you. With MATH_BOARD_NO_BROWSER=1 it never opens one and always returns the URL: claude mcp add math-board -e MATH_BOARD_NO_BROWSER=1 -- npx -y pi-math-board.
• Separate boards: same tools, separate boards. The MCP server hosts its own board server, started by the first tool call that needs it, on 127.0.0.1 with its own token, and keeps its saves in the mcp/ subfolder of the data folder (see Install for pi), apart from pi's, so the two never overwrite each other's autosave. MATH_BOARD_DATA_DIR overrides it; if you set it for both, give each its own. To continue a lesson in the other agent, copy saves/ .json across and load it with board_save.
• Lifecycle and privacy: stdout carries only JSON-RPC (diagnostics go to stderr), nothing listens beyond loopback, and there is no telemetry. When the client disconnects, or on SIGINT, SIGTERM or SIGHUP, the server flushes the autosave, closes the headless browser and exits. /board and /board export are pi commands; the MCP server has no counterpart.

What the tutor can draw

• Math: KaTeX equations (\color, \boxed, \cancel, …) and chemistry with \ce{…} (mhchem).
• Plots: function graphs, parametric curves, shaded areas, points, asymptotes. Expressions go through a small parser, never eval.
• Sliders: a plot can carry up to six params, each a slider row under it that you drag or play (▶ sweeps it back and forth), and the curves, areas, points and markers that use its name redraw live. A point bound to a slider can be dragged on the plot. The values stay in your tab: the tutor sees each slider at the value it set, and when you click the plot, the reference you copy says what you set (step 3, wave (chapter c1) with w = 4.5, a = 3.00).
• HTML artifacts (off by default): with MATH_BOARD_HTML=1 the tutor can also write its own HTML and JavaScript, for what no format above can show: a 3D model you can turn, a pendulum that swings. Each one runs in a sandboxed frame that blocks ordinary network requests and has no access to the board page, and can use the libraries the board ships (three.js with OrbitControls, d3, matter.js, lil-gui, fft.js, KaTeX). A new one is loaded in the headless layout check first, and your browser only gets it once it was ready there, which catches mistakes like an endless loop (not code written to slip past it; if a frame ever freezes the tab, open the board's address with &html=off added). Frames can't write the clipboard. Script errors, with the line, come back to the tutor in the layout check. Turn it on per agent: MATH_BOARD_HTML=1 pi, or claude mcp add math-board -e MATH_BOARD_HTML=1 -- …; /board status says whether it's on. Turning it on means model-written code runs in your browser: the sandbox can't close every network path (WebRTC from a nested frame still gets out), so a prompt-injected artifact could leak its own contents, and a nested frame could still put text on the clipboard when clicked: read what you paste into the terminal. SECURITY.md has what the sandbox does and doesn't cover.
• Molecules: 2D structures from SMILES strings (SmilesDrawer).
• Science illustrations: about 2000 offline Bioicons (anatomy, organs, cells, organelles, blood and immunology, microbes, viruses, DNA, plants, animals, lab equipment), searchable by keyword.
• Diagrams: hand-written SVG (markers, gradients, symbols, CSS, SMIL animation) and Mermaid (flowcharts, sequence, class, state, ER, gantt, mind maps, graphs; automatic layout).
• Marks: lines, arrows, curves, rectangles, ellipses and text (a LaTeX-style serif by default).

Not just math

The name says math, but the board doesn't know what it's teaching. It puts up equations, plots, molecules, illustrations, diagrams and text, and most subjects need some mix of those. What that looks like by subject:

• Physics and math: derivations one line per step, function and parametric plots, free-body and vector diagrams in SVG.
• Chemistry: 2D structures from SMILES, reactions and equilibria with \ce{…}.
• Biology and medicine: anatomy, organ and cell illustrations from the offline library, pathways and mechanisms as flowcharts.
• Computer science: algorithms as flowcharts, state machines, complexity plots, sequence and class diagrams.
• History and the humanities: timelines, mind maps of causes and effects, argument maps built from boxes and arrows.
• Languages: syntax trees as Mermaid graphs.

Three chapters from the sample lessons (node scripts/demo-lessons.mjs renders all five):

*Chemistry: salicylic acid to aspirin, both drawn from SMILES, and the reaction in \ce{…}.*

*Computer science: binary search as a flowchart, and what n lookups cost with and without it.*

*History: an argument map made of rectangles, text and arrows.*

How lessons are built

• Coordinates: each chapter, and the home board, is a 1200×800 space with the origin top-left. Text y is the baseline; equation x,y is the top-left of its box; rect, ellipse and artifact x,y is the top-left corner.
• Chapters: named 1200×800 regions placed left to right on an unbounded canvas (a chapter without x goes to the right of the rightmost one; one given x or y keeps it). Items with chapter: id use chapter-local coordinates, so moving a chapter moves its content. Overlapping chapters are reported. Deleting a chapter erases its items unless keepItems.
• Equations without `x,y` are stacked down the left side of their own chapter (x 88, 115 px apart), and the position is stored, so they never move when something else changes.
• Camera: `camera: