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 three buttons that change anything: New board, which saves the lesson and starts an empty one, 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 the Mac app

Download Math Board for macOS · macOS 12+ · Apple Silicon and Intel

Unzip Math-Board-macOS-universal.zip, move Math Board.app to Applications, and open it. Choose Help → Copy Agent Setup Prompt, then paste into your local agent. It will install the companion server and connect itself to the board. The app is a viewer; your agent supplies the lesson and runs the server.

Agent setup guide — instructions you can hand to an agent, including prerequisites, preserving existing boards, and testing the connection. No npm publication is needed: releases include the companion server package too.

The app is ad-hoc signed, not Apple-notarized. On first launch macOS may require System Settings → Privacy & Security → Open Anyway; see Apple's guidance. The app needs no compiler or Node installation; the companion server requires Node 22.19+.

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 `~/.lo

... View full README on GitHub