gjuoun/blackboard

A local web app for reviewing markdown documents (with mermaid diagrams) and leaving comments
on the text, so a person and a coding agent can go back and forth on a plan.
A session is one markdown file, anywhere on disk. You open it with blackboard open ;
the browser shows the doc with where it lives (repo and path) and which git branch it is on.
You select text and comment; an agent reads the file from disk and takes part through the
same blackboard CLI (see CLI for agents).
## Install
sh
npm install -g @gjuoun/blackboard # or: bun add -g @gjuoun/blackboard
blackboard open docs/design.md # starts the web app the first time, then opens the doc
Runs on Node 20.9+ or Bun 1.3+ (the blackboard command uses Node when it is on PATH, else
Bun). macOS and Linux; browsers: Chrome/Edge and Safari 17.2+ (CSS Custom Highlight API). It is a
Next.js app, shipped as a pre-built standalone server: about 8 MB to download, 37 MB on disk, and
no dependencies to install.
The web app runs in the background on http://127.0.0.1:38770:
sh
blackboard serve start [--port 4000] # start it (open does this for you on first use)
blackboard serve status # url, pid and log file; exit code 3 when not running
blackboard serve restart
blackboard serve stop
blackboard serve start --foreground # run in this terminal until Ctrl-C (containers, services)
serve stop only stops an app that serve start / open started (its pid is in
$BLACKBOARDHOME/server.json, its output in server.log). If something else already answers
at the address, for example bun dev in a clone, open uses it and leaves it alone.
## Run it from a clone
sh
bun install
bun dev # http://127.0.0.1:38770
bun link # once: puts blackboard on PATH (~/.bun/bin)
blackboard open docs/design.md # registers the file and opens its tab
bun run build && bun run build:server makes the production app that blackboard serve start
runs (server/); bun run build:cli bundles the command for Node (dist/). All three run on
npm pack / npm publish.
| Variable | Default | Meaning |
| BLACKBOARDHOME | ~/.blackboard | Blackboard's own folder: the session list, each session's comments, the scratchpad. |
| PORT | 38770 | Port for bun dev / bun start (serve start takes --port or the port in BLACKBOARDURL). |
| BLACKBOARDNOSERVER | off | 1: blackboard open never starts the web app. |
| BLACKBOARDURL | http://127.0.0.1:38770 | Where blackboard open points the browser, and the base of the share-card URLs in each page. Set it to your public address if the app is reachable from outside. |
The server binds 127.0.0.1 and answers only localhost / 127.0.0.1 / [::1] Host
headers; writes from another site's Origin get a 403. It serves only files that were
registered with blackboard open, and re-checks on every request that the path is still a
markdown file (a file swapped for a symlink to somewhere else is refused).
Checks: bun run typecheck, bun run lint, bun test, bun run build.
## What it does
Home — the scratchpad card on top, then every session as a card grouped by Today,
This week and Earlier: title (front matter title, else the first # heading, else the
file name), its location (repo/path inside git, the full path outside; cut from the left so the