vitela-bridge

The agent bridge for Vitela, the editor for ExactTeX.

It is a small program that runs on your machine. Your coding agent talks to it over the Model Context Protocol (MCP); it talks to the Vitela tab open in your browser. Every tool the agent calls runs inside that tab — the project, the compiler and the TeX engine are all there — and the answer comes back. Nothing leaves your machine.

One rule makes it safe to hand an agent the keys: the agent never edits text. A change it proposes lands in your document as an ExactTeX revision, signed agent, that you accept or reject in Vitela's review margin like any other suggestion.

The full guide, with screenshots: https://vitela.artificialfallibility.com/agent.

Install

Node 20 or newer. No install step: npx fetches and runs it.

Claude Code

claude mcp add vitela-bridge -- npx -y github:camilochs/vitela-bridge

Codex

codex mcp add vitela-bridge -- npx -y github:camilochs/vitela-bridge

Cursor, Windsurf, Zed, Claude Desktop and other MCP clients — add to the client's MCP configuration:

{
  "mcpServers": {
    "vitela-bridge": {
      "command": "npx",
      "args": ["-y", "github:camilochs/vitela-bridge"]
    }
  }
}

Related MCP server: vscode-agent-bridge

Pair

1. Start your agent. The bridge starts with it. Ask the agent for the pairing code once — or for the pairing link (bridge_status returns both: code, and link of the form https://vitela.artificialfallibility.com/app?pair=123456, which pairs the tab by itself when opened).

2. Open Vitela, press Agent in the header, type the code (or open the link). The card says Connected and closes.

3. Work. The agent reads the project, runs the check, compiles, verifies the bibliography, and proposes changes you accept or reject in the margin. Reply on a card writes a note the agent reads; it withdraws that proposal and sends a better one.

The code is stable on this machine — made once, kept in ~/.config/vitela-bridge/code, reused on every start — and Vitela remembers it in the browser, so after the first time pressing Agent connects by itself. To get a new code, delete that file or set VITELA_BRIDGE_CODE.

Several sessions, one bridge

One machine runs one shared bridge, and every tab pairs with it using the same code — so two agent sessions can drive two papers at once, with no ports or codes to juggle.

1. Start each session as usual; both spawn the bridge with the same port and code. The first to start holds the port and becomes the shared bridge; the next finds the port busy and attaches to it. Nothing to configure.

2. Open a Vitela tab per paper and pair each with the same code (Agent button, or …/app?pair=123456).

3. In each session, open its paper with project_open(id). The bridge binds that session to the tab showing that paper; from then on the session's tools go to that tab. A lone session with a lone tab needs no project_open.

bridge_status says whether a session is the shared bridge or attached to it, and how many tabs the bridge holds. The bridge lives with the session that started it: if that session ends, an attached session loses it and must be restarted.

Editing through cards

The bridge tells the agent how to edit when it connects (the MCP server's instructions), and every refusal says what to do instead. The rules, for a human reader:

1. Few, large cards. One card per block the author reads as a unit: a paragraph, a section, the front matter, everything before or after a figure. Never a burst of small cards for one change; never one per sentence. A cut or rewrite of a paper is two substitutions, one before the figure and one after it.

2. A set when several pieces are one change (revision_propose_set): one card, one Accept. Not a way to bundle unrelated edits.

3. Anchor on exact live text, first occurrence; an anchor inside a pending card is refused.

4. What a card cannot carry, and the way round: a bare % on the last line of a piece (end the piece a line earlier, or escape it as \% — a comment line inside a long piece is fine); a -> inside a substitution (cut the piece around the figure, or send a deletion and an addition as one set); braces that do not balance (cut where they close); an anchor inside a command's argument or a braced group (propose the enclosing block whole, or force: true when the cut must start there — force reaches every piece of a set).

5. Pages and errors are measured in Vitela: compile after the author accepts. Nothing is compiled elsewhere first.

6. A reply on a card is feedback: revisions_list carries it as notes; withdraw and propose again, improved.

Tools

Configuration

From another machine

A Vitela tab served over HTTPS (production, in a browser on your laptop) can only open an encrypted socket, and "localhost" there is the laptop, not the machine running the agent. Three things make it work over a tailnet:

1. A certificate for the agent's machine. With Tailscale: tailscale cert <machine>.<tailnet>.ts.net (it needs HTTPS enabled for the tailnet). Keep the two files somewhere stable.

2. The bridge bound to the network and given the certificate, in .mcp.json:

   "env": {
     "VITELA_BRIDGE_HOST": "0.0.0.0",
     "VITELA_BRIDGE_CERT": "/path/to/machine.tailnet.ts.net.crt",
     "VITELA_BRIDGE_KEY": "/path/to/machine.tailnet.ts.net.key",
     "VITELA_BRIDGE_PUBLIC": "machine.tailnet.ts.net:4329"
   }

3. The link from bridge_status, opened on the laptop: https://vitela.artificialfallibility.com/app?pair=123456&bridge=machine.tailnet.ts.net:4329. The tab keeps the bridge address, so the next time the Agent button connects on its own.

The certificate expires; renew it with the same command and restart the agent. If the port is already held by another session's bridge, this one attaches to it (see Several sessions, one bridge); bridge_status says which role it has.

The tab connects to the bridge on the machine that serves the page for a plain-http dev server, and on 127.0.0.1 for localhost and for the published site.

License

MIT.

If the bridge is useful to you, a star on this repository helps others find it — and tells us it is worth the care.