Skip to content
Back to search

brainboard

A minimal, near-infinite whiteboard for notes, images, sketches and flow charts. Real-time collaboration, vim keys, and an MCP server so AI agents can read and edit your boards.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ai-armageddon--brainboard/badge.svg)](/listings/ai-armageddon--brainboard)

HTML

<a href="/listings/ai-armageddon--brainboard"><img src="/api/listings/ai-armageddon--brainboard/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires Node 22.18 or newer. The server runs its TypeScript directly, with no build step for the backend.

git clone https://github.com/ai-armageddon/brainboard.git
cd brainboard
npm install
npm run dev

Open http://localhost:5317. A short tour walks you through the basics the first time, and you can replay it from the menu with **Quick tour**.

| Command | What it does | |---|---| | `npm run dev` | Development server with live reload, on this computer only | | `npm start` | Production build, on this computer only | | `npm run share` | Production build that people on your network can reach | | `npm run prod` | Production build in hosted mode for https://brainboard.ink (see [Deploy](#deploy)) | | `npm run mcp` | The MCP server on stdio, for AI agents |

Boards are saved in `~/.brainboard/`, with images next to them. Set `BRAINBOARD_DIR` to use another folder. Deleted boards go to `~/.brainboard/trash/`.

To keep the dev server running in the background and across restarts, run it under [pm2](https://pm2.keymetrics.io):

pm2 start node_modules/.bin/vite --name brainboard-dev
pm2 save

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 223 lines
  1. # brainboard
  2. [![Brainboard: think it through, together. An infinite whiteboard for notes, images, sketches and flow charts, live with your team and your agents.](public/og.png)](https://brainboard.ink)
  3. A minimal, near-infinite whiteboard for notes, images, sketches and flow charts. Invite people to edit with you in real time, drive it from the keyboard with vim keys, and let AI agents read and edit your boards over MCP.
  4. Live at **[brainboard.ink](https://brainboard.ink)**, or run your own: boards are plain JSON files on the server's disk.
  5. ## Features
  6. - **Infinite canvas.** Pan and zoom freely. Paste or drop images, write sticky notes and text, and sketch with a pen.
  7. - **Flow charts.** Bubbles, boxes, pills and decisions with curved, labelled connectors. Press `Tab` to grow the next step.
  8. - **Live collaboration.** Invite links that can edit or only view. Everyone's cursor, selection and typing shows up live. Talk over built-in voice chat, follow someone, or present to the room.
  9. - **Vim keys.** A `:` command line with completion, `/` search, find and replace, and an optional vim mode with `hjkl` navigation.
  10. - **Agent friendly.** A built-in MCP server lets Claude, Cursor and other agents list, read, render and edit boards. Their edits appear live in your tab.
  11. - **No sign-up wall.** Start drawing straight away. Create an account (with a passkey, or email and password) when you want to keep your boards and open them anywhere.
  12. - **Export anywhere.** PNG, PDF, SVG, a Markdown outline, or a full brainboard file, saved wherever you choose.
  13. - **Yours.** Self-host it in one command. Light and dark themes and per-user undo.
  14. ![A brainboard with a flow chart, notes, images and two collaborators](docs/screenshots/board-dark.png)
  15. ## Quick start
  16. Requires Node 22.18 or newer. The server runs its TypeScript directly, with no build step for the backend.
  17. ```sh
  18. git clone https://github.com/ai-armageddon/brainboard.git
  19. cd brainboard
  20. npm install
  21. npm run dev
  22. ```
  23. Open http://localhost:5317. A short tour walks you through the basics the first time, and you can replay it from the menu with **Quick tour**.
  24. | Command | What it does |
  25. |---|---|
  26. | `npm run dev` | Development server with live reload, on this computer only |
  27. | `npm start` | Production build, on this computer only |
  28. | `npm run share` | Production build that people on your network can reach |
  29. | `npm run prod` | Production build in hosted mode for https://brainboard.ink (see [Deploy](#deploy)) |
  30. | `npm run mcp` | The MCP server on stdio, for AI agents |
  31. Boards are saved in `~/.brainboard/`, with images next to them. Set `BRAINBOARD_DIR` to use another folder. Deleted boards go to `~/.brainboard/trash/`.
  32. To keep the dev server running in the background and across restarts, run it under [pm2](https://pm2.keymetrics.io):
  33. ```sh
  34. pm2 start node_modules/.bin/vite --name brainboard-dev
  35. pm2 save
  36. ```
  37. ## Using the canvas
  38. | | |
  39. |---|---|
  40. | **Pan** | Scroll or drag with two fingers, hold `⌘` and drag (`Ctrl` on Windows), hold `Space` and drag, or press `H` |
  41. | **Zoom** | Pinch or `⌘` + scroll · `⇧1` fits everything · `⌘0` resets to 100% |
  42. | **Images** | `⌘V` to paste, drag files in, or press `I` |
  43. | **Write** | Double-click anywhere for text · `N` for a sticky note · `Enter` edits the selection |
  44. | **Draw** | `P` pen · `E` eraser |
  45. | **Flow charts** | `O` bubble · `R` box · `D` decision · `C` connector |
  46. | | Drag a shape's dot onto another shape to connect them, or onto empty space to grow a new bubble. `Tab` adds a connected bubble to the right, even while you type. |
  47. | **Organise** | `⌘D` duplicate · `]` / `[` bring to front or send to back · `⌫` delete |
  48. | **Boards** | Open the menu at the top left · `⌥N` new board · double-click the board name to rename it |
  49. | **Export** | `⇧⌘E`, or **Export…** in the menu: PNG (1–3×, transparent if you like), PDF, SVG, a Markdown outline of the text and flow, or a brainboard file you can import again. Pick the whole board or just the selection, and a light or dark theme. **Save as…** lets you choose the folder and file name in Chrome, Edge and Opera. Other browsers save to Downloads |
  50. | **Undo** | `⌘Z` / `⇧⌘Z` undo only *your* changes, never anyone else's |
  51. Press `?` in the app for every shortcut.
  52. ![The same board in the light theme, with a shape selected](docs/screenshots/board-light.png)
  53. ## Accounts and saving
  54. Nobody has to sign in. Every browser gets its own private, anonymous space, and the boards you make there are yours.
  55. - **Not saved yet.** Until you create an account, your boards are tied to this browser. If you clear its data or switch devices, they're gone. A **Save** button in the top right shows when this applies. If you head for the tab bar with unsaved work, brainboard shows a short in-app reminder. `⌘S` and `:w` save too.
  56. - **Create an account** with a **passkey** (Face ID, Touch ID or your device PIN, with no password) or with **email and password**. Everything you made in this browser moves into the account.
  57. - **Sign in anywhere** with the same passkey or email to see all your boards. Add more passkeys, rename yourself or sign out from your avatar in the top right.
  58. Passwords are hashed with scrypt, and sessions are random tokens stored only as hashes. Sign-in attempts are rate-limited.
  59. ## Collaborate in real time
  60. Click **Share** to create invite links. Each link either **can edit** or **can view**, and you can change or revoke it at any time. Changes apply instantly to everyone using that link. Collaborating doesn't need an account, just a **screen name**: brainboard asks for one before you share or present, and guests pick theirs when they join. Guests see only the board they were invited to.
  61. ![The share dialog with two invite links and live session controls](docs/screenshots/share.png)
  62. - **Presence.** Everyone's cursor, selection and "typing" marker appear in their colour. Click an avatar to follow that person's view.
  63. - **Present.** Everyone follows your view while you walk through the board. You can lock the view so nobody wanders off.
  64. - **Voice chat.** Click the headphones to join. Audio goes directly between browsers. Avatars light up and cursors show sound bars while someone talks. The board owner and the presenter can mute anyone, mute everyone, or turn on **Stage mode** in Share so only they can talk. Mutes apply on every listener's side, not just the muted person's. Peer-to-peer audio suits small groups of up to about 8 people.
  65. - **Cinematic follow.** Followers get a calm camera by default. Instead of mirroring every twitch, it frames what the presenter is working on: the note they're typing in, what they just selected, or the item their cursor rests on. It holds still while that's already in view, eases over when it isn't, and flies across the board for long jumps. Switch to **Exact** in the follow banner to mirror their screen instead.
  66. - **Session controls.** *Pause editing* makes everyone else view-only. *Show viewers' cursors* can be turned off for big audiences. Each person has a **Remove** button.
  67. - **Reaching people.** On brainboard.ink, links just work. When you run it yourself, `npm run dev` and `npm start` listen only on your computer. For people on the same Wi-Fi, run `npm run share` and the Share dialog picks your network address. For anyone else, run `npm start` behind a tunnel, for example `cloudflared tunnel --url http://localhost:5317`, and paste the tunnel's address into **Link address**.
  68. - **Security.** Each board belongs to the account or browser that made it. Everyone else needs an invite link. Cross-site requests are refused, and roles are enforced on the server, not just in the UI. When you run it locally, your own computer also sees boards that have no owner, such as older boards and ones AI agents create over MCP.
  69. ## Vim keys
  70. ![The command line, completing commands that start with f](docs/screenshots/vim.png)
  71. These work all the time, because they don't clash with the regular shortcuts:
  72. | | |
  73. |---|---|
  74. | `:` or `;` | Command line. `Tab` completes and `↑` / `↓` scroll through history |
  75. | `/` | Search the board's text as you type. `Enter` keeps the match |
  76. | `u` · `⌃R` | Undo / redo |
  77. | `w` `b` · `gg` `G` | Next or previous item, first or last item, in reading order |
  78. | `a` | Edit the selected item with the cursor at the end |
  79. | `yy` · `x` | Yank or cut the selection |
  80. | `zz` · `zi` `zo` | Centre the selection, zoom in or out |
  81. | `ma` · `'a` · `''` | Mark this view as `a`, jump back to it, return to where you were |
  82. | `gt` · `gT` | Next or previous board |
  83. Turn on **vim mode** with `:set vim` or **Vim keys** in the menu. It adds the keys that normally pick a tool, so the tools move to commands such as `:pen`, `:note` and `:bubble`.
  84. | | |
  85. |---|---|
  86. | `h` `j` `k` `l` | Jump to the nearest item in that direction |
  87. | `H` `J` `K` `L` | Pan the view |
  88. | `i` · `cc` | Edit text with the cursor at the start, or replace it |
  89. | `o` · `O` | New connected bubble below or above |
  90. | `dd` · `p` `P` | Delete (and yank), put after or before the selection |
  91. | `n` · `N` | Next or previous search match |
  92. Some useful commands:
  93. - `:e {board}` opens a board, with name completion. `:new`, `:file {name}`, `:bn` and `:bp` manage boards.
  94. - `:%s/old/new/g` finds and replaces across the whole board, and `:s/old/new/` does it in the selection. Patterns are JavaScript regular expressions, and `&` and `\1` work in the replacement.
  95. - `:color red`, `:shape decision`, `:zoom 150`, `:fit`, `:theme dark`, `:follow Sam`, `:present`, `:share`, `:export`, `:marks` and `:help`.
  96. - `:w` and `:q` work too, but there's nothing to save: brainboard saves as you go.
  97. ## Use it with AI agents (MCP)
  98. brainboard ships an MCP server, so agents such as Claude Code, Claude Desktop and Cursor can list, read, look at and edit your boards. Their edits appear live in your open tab, and you can undo them.
  99. **Claude Code** picks it up automatically inside this folder through `.mcp.json`. To use it from anywhere:
  100. ```sh
  101. claude mcp add brainboard --scope user -- node /absolute/path/to/brainboard/server/mcp.ts
  102. ```
  103. **Claude Desktop, Cursor and other clients** use this config:
  104. ```json
  105. { "mcpServers": { "brainboard": { "command": "node", "args": ["/absolute/path/to/brainboard/server/mcp.ts"] } } }
  106. ```
  107. | Tool | What it does |
  108. |---|---|
  109. | `list_boards` | All boards, most recent first |
  110. | `read_board` | An outline of every note, shape, image and arrow, with ids, positions and the flow between them (or `format: "json"`) |
  111. | `render_board` | A PNG of the board, including drawings and images (`show_ids` overlays ids) |
  112. | `view_image` | Look at a pasted image |
  113. | `add_items` | Add notes, text, bubbles, boxes, decisions and arrows in one call, with automatic layout |
  114. | `update_items` / `delete_items` | Edit or remove items by id |
  115. | `add_image` | Put an image on a board from a file path, URL or base64 |
  116. | `create_board` / `rename_board` | Manage boards |
  117. Try asking: *"Read my Q3 launch plan board and add the next steps as a flow chart"* or *"Look at the screenshot I pasted and summarise it in a sticky note next to it."*
  118. ## Empty boards
  119. New boards open with a small animated scene instead of a blank page. It stops as soon as you add something, and holds still if your system asks for reduced motion.
  120. ![An empty board showing an animated preview of collaborators moving photos and typing](docs/screenshots/empty.png)
  121. ## Deploy
  122. Production runs at **https://brainboard.ink**. Hosted mode turns on when `BRAINBOARD_PUBLIC_URL` is set. It switches off the "this computer is the owner" shortcut, issues `Secure` cookies, and uses the domain for passkeys and invite links.
  123. ```sh
  124. npm ci
  125. npm run prod # builds, then serves on $PORT (default 5317) with BRAINBOARD_PUBLIC_URL=https://brainboard.ink
  126. ```
  127. | Variable | Default | Purpose |
  128. |---|---|---|
  129. | `BRAINBOARD_PUBLIC_URL` | unset (local mode) | The public address, e.g. `https://brainboard.ink` |
  130. | `PORT` | `5317` | Port to listen on |
  131. | `HOST` | `0.0.0.0` when hosted | Interface to listen on |
  132. | `BRAINBOARD_DIR` | `~/.brainboard` | Boards, images, accounts and sessions. Back this up |
  133. | `BRAINBOARD_ICE_SERVERS` | Google's public STUN server | JSON list of WebRTC ICE servers for voice chat. Add a TURN server (for example coturn) so voice works on strict corporate networks |
  134. Put it behind HTTPS. A reverse proxy must forward WebSockets and keep the original `Host` header. With [Caddy](https://caddyserver.com):
  135. ```
  136. brainboard.ink {
  137. reverse_proxy 127.0.0.1:5317
  138. }
  139. ```
  140. Passkeys only work on the real domain (and on `localhost` in development), not on raw IP addresses. Email sign-in works everywhere.
  141. ### Link previews
  142. `index.html` carries Open Graph, X (Twitter) and JSON-LD tags, so a pasted brainboard.ink link unfurls with the card at the top of this README in Slack, iMessage, Discord, LinkedIn and X. The tags point at `https://brainboard.ink`; if you host it on another domain, change the `canonical`, `og:url`, `og:image` and `twitter:image` addresses to yours.
  143. The card (`public/og.png`, 1200×630) is a web page, `scripts/og.html`, drawn with the app's own fonts and colours. Edit it, then redraw the PNG with headless Chrome:
  144. ```sh
  145. node scripts/og.ts # set CHROME=/path/to/chrome if it isn't in the default macOS location
  146. ```
  147. App icons and the favicon come from the brand mark in `src/brand.ts`: `node scripts/icons.ts` regenerates them.
  148. ## How it works
  149. - **App** (`src/`): vanilla TypeScript and Vite, no framework. The canvas is DOM elements and SVG inside one transformed layer.
  150. - **Server** (`server/`): a small Node HTTP and WebSocket server. Each open board is a room. Clients send item-level changes, the server keeps the room authoritative, and it writes the board file shortly after each change.
  151. - **Agents**: the MCP server edits the same files. The live server notices the change and merges it into the room, so agent edits show up in open tabs.
  152. | File | Role |
  153. |---|---|
  154. | `src/state.ts` · `src/net.ts` | Board state and per-user undo · server connection and live sync |
  155. | `src/render.ts` · `src/input.ts` · `src/actions.ts` · `src/ui.ts` | Canvas, input, operations, interface |
  156. | `src/collab.ts` · `src/vim.ts` · `src/tour.ts` | Presence, follow and sharing · vim keys · first-run tour |
  157. | `src/account.ts` | Sign-in sheet, save reminders, screen names |
  158. | `src/voice.ts` · `src/director.ts` | Voice chat (WebRTC) · cinematic follow camera |
  159. | `server/store.ts` · `server/api.ts` · `server/realtime.ts` | Board and image files · HTTP API · live rooms |
  160. | `server/mcp.ts` · `server/agent.ts` · `server/render.ts` | MCP server · outlines and auto-layout · PNG rendering |
  161. | `server/auth.ts` · `server/sharing.ts` | Who is asking (account, anonymous browser, guest) · board owners and invite links |
  162. | `server/accounts.ts` · `server/passkeys.ts` · `server/config.ts` | Accounts, passwords and sessions · passkeys (WebAuthn) · hosted vs local mode |
  163. | `scripts/og.ts` · `scripts/icons.ts` | Social share card · app icons and favicon |

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.