brainBRIDGE

Your handwritten notes, written up in LaTeX by your coding agent.
braiNOTES and TeXbrain, connected to Claude Code, Codex, Cursor or VS Code.

braiNOTES → notes.swimmingbrain.dev
TeXbrain → tex.swimmingbrain.dev

Your agent reads your handwritten notes, writes them up in LaTeX and compiles them, while you watch it happen in your browser tabs.

braiNOTES is for handwritten notes, TeXbrain is a LaTeX editor, both run entirely in the browser. This is a small MCP server that connects your agent to both tabs at once. It gets tools like notes_page, notes_transcribe, tex_write, tex_compile and tex_pdf_page: it can look at a page of your notes, turn it into LaTeX, put it into your project, compile it and look at the PDF.

you                    your agent                  brainbridge                               your browser tabs
"write up page 3" ───> picks a tool ── stdio ────> this server ── ws://127.0.0.1:7332 ──┬──> braiNOTES
                                                                                        └──> TeXbrain

Nothing leaves your machine. The server only listens on the loopback address and the tabs only talk to it. The one exception is transcription with an API key, see below.

Use it

1. Build the server and add it to Claude Code, see Setup: claude mcp add brainbridge -- node /absolute/path/to/brainbridge/dist/index.js
2. Open notes.swimmingbrain.dev/?bridge and tex.swimmingbrain.dev/editor?bridge, allow the local connection, both Bridge segments turn green.
3. Say "transcribe page 3 of my notebook Linear algebra into main.tex of my project Thesis".

Claude Code opens the notebook, looks at page 3, writes it into main.tex as LaTeX exactly as you wrote it, compiles the project and checks the PDF. You see every step in the two tabs, and every change is one undo step.

Setup

1. Build the server (Node 20 or newer, and pnpm):

git clone https://github.com/swimmingbrain/brainbridge
cd brainbridge
pnpm install
pnpm build

2. Tell your agent about it. Claude Code, from any terminal:

claude mcp add brainbridge -- node /absolute/path/to/brainbridge/dist/index.js

On Windows the path looks like C:\Users\you\brainbridge\dist\index.js. Cursor (~/.cursor/mcp.json) and a .mcp.json in your project use this:

{
  "mcpServers": {
    "brainbridge": {
      "command": "node",
      "args": ["/absolute/path/to/brainbridge/dist/index.js"]
    }
  }
}

VS Code (.vscode/mcp.json):

{
  "servers": {
    "brainbridge": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/brainbridge/dist/index.js"]
    }
  }
}

Codex: codex mcp add brainbridge -- node /absolute/path/to/brainbridge/dist/index.js, or in ~/.codex/config.toml:

[mcp_servers.brainbridge]
command = "node"
args = ["/absolute/path/to/brainbridge/dist/index.js"]

3. Open the apps with the bridge on: https://notes.swimmingbrain.dev/?bridge and https://tex.swimmingbrain.dev/editor?bridge

Chrome and Edge ask once whether the site may connect to apps on your device, allow it. Each app gets a Bridge segment in its status bar: amber while it waits for the server, green when it is connected. The switch is remembered. In braiNOTES it lives under Preferences, General, in TeXbrain in the command palette as "Bridge: connect" and "Bridge: disconnect".

node dist/index.js status in the brainbridge folder tells you which apps are connected.

Try these

Look at page 2 of my Analysis notebook and write it up as LaTeX at the end of main.tex in the analysis project. Compile it and check the PDF.

Transcribe the last page of my notes to markdown.

Which formulas on page 4 did I write? Zoom in on the second block.

Link the Analysis notebook to the analysis project, then switch to the project.

Put a summary of this page as text under the last line.

The tools

Pages of a notebook count from 0, pages of a PDF from 1. Positions on a page are in page units from the top left, an A4 page is 595 x 842. There is also an MCP prompt transcribe with the instructions the transcription uses.

Transcription

With ANTHROPIC_API_KEY set for the server, notes_transcribe sends the page and zoomed crops of its formulas to Haiku through the Anthropic API, checks every formula with KaTeX, has the broken ones read again on sharper crops and gives a page that still fails to Sonnet. Without a key it hands the page, its layout and the same instructions to your agent, which then reads the page itself.

The key goes to the server like this: claude mcp add -e ANTHROPIC_API_KEY=your-key brainbridge -- node /absolute/path/to/brainbridge/dist/index.js. Only then do page pictures leave your machine, to the Anthropic API.

Good to know

• One tab per app. A second braiNOTES tab takes over from the first one, which says so. A braiNOTES and a TeXbrain tab work side by side.
• Every edit is one undo step in the tab, so you can step back through what your agent did.
• Projects in a folder on your disk cannot be opened from here, the browser only reaches them through its folder picker. Open the folder in TeXbrain yourself, then the tools work on it.
• Running the apps locally? Open http://localhost:5173/?bridge or http://localhost:5173/editor?bridge, localhost is allowed too.
• Another port. Start the server with --port 7400 (or BRAINBRIDGE_PORT=7400) and open the apps with ?bridge=7400. BRAINBRIDGE_ORIGINS adds more page origins that may connect, comma separated.
• Links between notebooks and projects are kept in links.json in %APPDATA%\brainbridge on Windows and ~/.config/brainbridge elsewhere. Nothing else is stored.

Development

pnpm dev     # runs the server from source with tsx
pnpm test    # fake braiNOTES and TeXbrain tabs answer every tool
pnpm smoke   # drives the two real tabs end to end, after pnpm build

The wire protocol is src/protocol.ts, both apps keep a copy of it in src/lib/bridge/protocol.ts.

License

MIT, see LICENSE.

Built by Braian Plaku