Skip to content
jhudsyPublic

About

Local-first collaborative LaTeX editor: E2E-encrypted sync through a tiny relay, in-browser or local compilation, folder sync for agents

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

TeXLoom

Local-first, collaborative LaTeX. Every collaborator has a full copy of the project, in the browser or as a plain folder on disk, and can keep working offline. A small server passes end-to-end encrypted changes between people and can be told to keep no copy at all. No accounts: you share a link. (The command-line tools are called texloom.)

  • Live editing with other people's cursors (click someone's avatar to jump to them); offline edits merge automatically on reconnect. Two files created under the same name while apart are both kept (one as name (conflict).tex), and a paragraph two people both changed while apart gets a ⚠ Check merge note in the Review tab, since word-by-word merging can leave it reading oddly. Installs as an offline-capable app.
  • Compile in the browser (TeX Live 2026 in WebAssembly), or with your own TeX installation. Errors are listed with clickable locations; SyncTeX jumps between source and PDF (the → / ← arrows on the editor/PDF divider, ⌘⌥→ / ⌘⌥←, or double-click / right-click the PDF).
  • History without git: automatic and named versions (name any version later, e.g. the one you submitted), compare with now, restore a file or everything, and see who wrote each line.
  • Comments and suggested changes (tracked changes) that collaborators accept or reject.
  • Edit the project as an ordinary folder, so Claude Code, vim or VS Code can work on it directly; changes flow both ways, live. Chrome and Edge can sync a folder with nothing installed.
  • Agents as collaborators: an MCP server (texloom mcp) lets Claude Code or any MCP client read, edit, comment, suggest and compile, visible to everyone by name and cursor. A built-in assistant does the same with Claude, any OpenAI-compatible API, or a local model (LM Studio, Ollama).
  • LaTeX-aware editor: completion of environments, commands, files, citation keys and labels; a preview of the equation under the cursor; a checker for common mistakes, with one-click fixes; spell check that skips LaTeX; search and replace across files; an outline with word counts; paste or drop images; add references from a DOI or arXiv id.
  • In English, French, German, Spanish, Brazilian Portuguese or Simplified Chinese: the browser's language is used, or choose one in Settings (the desktop app follows the system language, or the one chosen in its Settings).
  • Start from templates, or import a .zip (e.g. from Overleaf) or an arXiv paper's source.
  • Read-only links, and personal edit links that can be revoked one by one.
  • The server is a single Python process with PostgreSQL (INSTALL.md).

See DESIGN.md for how it works.

How this was made: an AI note

TeXLoom was vibe coded: nearly all of the code, tests, deployment scripts and documentation were written by an AI assistant (Anthropic's Claude, working in Claude Code), directed and reviewed by the author through conversation. The author chose the design and the features; the AI wrote the implementation, ran the tests, and deployed it.

Its security review was also AI-performed: an independent AI audit, followed by fixes that were verified by testing. That is not the same as a professional audit.

Treat this as an early prototype: keep your own copies of important work, and read the security model below before relying on it.

Using TeXLoom: nothing to install

One person runs a TeXLoom server, for example at https://texloom.example.org. Everyone else just opens a link in a browser. No accounts, no software. The first time someone opens a link, they're asked:

  • their name;
  • whether to keep a copy in a folder;
  • how to compile: in the browser, with their own TeX, or not at all;
  • whether to sync live or manually.

If you work only in the browser, your copy lives in the browser's storage. Clearing the site's data (or history and site data) deletes it, and Safari may delete a site's data after about 7 days without a visit. A project stored on the server can be reopened from its link. One that isn't (marked not on server, with a warning in the editor) survives only on devices, so keep a folder copy or download a .zip.

A project's ⚙ Settings has tabs: Project (main file, engine, bibliography, spelling language, and removing it: shared with everyone in it), Compiling and Editor (this device), Sync & storage (syncing on this device; the server's copy and creation code; a copy in a folder), Integrations (Zotero and GitHub; your accounts are yours, the links are the project's) and You (your name and the interface language, in every project). It opens on the tab you used last.

The start page lists the projects you've opened in that browser (your name and the language are under ⚙ at the top):

  • each shows the document's \title, who started it and who else you've seen in it, and is marked read-only if that's all your link allows;
  • each has a short project code (the same one texloom links prints), shown beside the name when two projects share a name, and otherwise when you point at the name;
  • the folder icon keeps the project in a folder through the TeXLoom app (highlighted once the app does); ✎ gives a project a private label that only you see;
  • tick boxes, shown when you point at a project, select several to tag or remove together;
  • ✕ (or ⚙ Settings → Project → Remove…) asks what to remove: from this browser only (the server's and collaborators' copies stay; the link brings it back), or, for the owner, from the server too (the server deletes its encrypted copy and stops storing the project; collaborators keep their copies and can still work together while online at the same time), or for everyone: the server deletes its copy and refuses the project from then on, so nobody can sync it or open it from a link again. Collaborators' browsers and apps keep a read-only copy, with a notice and a download button. This can't be undone. Files in folders on your computer are never deleted.

The server can't read or recover links, so keep important links somewhere safe; a password manager works well.

Sharing and revoking

Share shows the links. Whoever created the project holds the owner link. From it they can make a personal edit link for each collaborator (by name), and later revoke one: the server and everyone's browsers then refuse that person's changes, and their app reopens read-only. The list shows the start of each link's key, so two people with the same name can be told apart; only the owner can switch off server storage. A revoked person can still read new changes, because the link holds the encryption key. To shut them out completely, Move to new keys: the project (with history and comments) is copied into a new project with new keys, files are re-encrypted, the old server copy is deleted, and you send new links to the people who should keep access. The plain read-only link works as before.

Send links from Share, not the address bar. In the web app the address bar shows only the project's id. The keys stay in the browser, so a copied address opens nothing for anyone else (it says to ask for a link), and only works in the browser that opened the project. Links from Share work as usual, and old links and bookmarks that contain keys still open.

Email… next to a personal or read-only link opens your own email app with an invitation and the link filled in. The link travels in that email, never through the TeXLoom server (which must not see its keys), so anyone who can read the email can open the project. A personal link is shown, and can be emailed, only when you create it.

Your project list on other devices

The start page lists the projects opened in that browser, and only there. To take the list with you, choose Sync this list…: the list is kept on the server, encrypted, and merged between every browser and computer you connect. The server can't read it. Removing a project from the list on one device removes it on the others.

Copies on several servers. Under Copies of this list (web app: Manage sync…; desktop app: Project list), tick other servers to keep a copy of the list there too, encrypted like the first. Every device keeps all the copies up to date, a copy that was offline catches up, and the list lives on if one of its servers closes. The sync link works on any of them (change its address), and so does a password; a passkey only works on the server where you added it.

A list is opened by a sync link (https://server/#sync=…). Keep that link in a password manager, because it opens every project on the list. You can also add a passkey, which your phone or password manager carries between devices; passkeys need a browser with the WebAuthn PRF feature and belong to the server's address. Or set a username and password in the web app: both stay on your device, and only a value worked out from them (with scrypt) reaches the server. Only use a sync link that's yours, since using one adds your projects to that list.

If a link gets out, Replace the sync link… moves the list to a new one. The old link stops working, and so do passkeys and the password, which you then add again. Delete this list… removes it for every device. Passkeys and the password can each be removed in the same dialog.

A lost list can't be recovered. The server can't read it, so nobody, including whoever runs the server, can reset access for you. A forgotten password can only be replaced using the sync link or a passkey. If you lose the link and every passkey, and forget any password, the list is gone for good. Your projects aren't deleted, but you'll need each project's own link to open it. A password is also the one way in that can be guessed, by someone with the server's data, so make it long.

In the desktop app, use File ▸ Project list… (also in Settings), which also keeps the list up to date while the app runs; or, in the web app's list dialog, Use in the TeXLoom app sends the list to the app on this computer, which asks before using it. For the helper, see texloom projects below (use --password unlocks with a password). Starting a list counts as creating something on the server, so servers that require a creation code ask for one. Servers can turn lists off with --no-project-lists.

Projects on other servers. A list can hold projects from any TeXLoom server, not just the one keeping it. Paste another server's project link under Paste a project link…: the project opens here and syncs with its own server, straight from this page, and the start page marks it with that server's name. Only encrypted data goes there, as here; the keys stay in your browser. The desktop app lists its folders with their own servers too, and its Project list shows each project's server. Your creation codes travel with the list, one per server. When you know more than one server, Create project (and Make a copy, and the desktop app's New project from a folder…) asks which to keep the new project on, starting with the one you used last; Another server… takes any address. To move another server's project to new keys, open it on that server.

Your creation code travels with the list too: the latest one entered in any browser or in the app is filled in when you make a project elsewhere, such as New project from a folder… in the app. Anyone with your sync link can see it, as they can every project on the list.

Finding and copying projects

The box above your projects searches their names and tags, and the menu beside it sorts them by when they were last opened or changed, when they were added, or name. Long lists are split into pages of 25, 50 or 100, or shown on one page, as you choose. Give a project tags with + Tag beneath it or Tags in the editor's header, and click a tag at the top to show only projects that have it (several tags narrow it further). Manage tags… renames, recolours and deletes them, for every project at once. Tick projects to change their tags or remove them together, or use the box at the top to tick everything found. Tags are yours alone: they aren't stored in the project, so collaborators never see them. With a synced list they follow you to your other devices, encrypted; otherwise they stay in that browser.

Make a copy (the copy icon next to a project, or in the editor's header) starts a new project of your own from the current files and settings, which suits templates. The copy has its own links and none of the original's history, comments or collaborators, and it counts towards your storage.

Editor

⌘S / Ctrl+S compile
⌘B / Ctrl+B, ⌘I / Ctrl+I wrap the selection in \textbf{} / \textit{} (or insert an empty one; press again to unwrap)
⌘/ / Ctrl+/ comment or uncomment lines
\begin{…} + Enter adds the matching \end{…} (and \item for lists)
typing \ completes commands and environments; \begin{table}, figure, itemize, align, … come with their usual contents. Tab moves between the fields to fill in
inside \includegraphics{, \cite{, \ref{, \input{, \usepackage{ suggests the project's images, bibliography keys (with titles), labels, files and common packages

| ⌘⇧F / Ctrl+Shift+F | search (and replace) across all files | | ⌘⌥M / Ctrl+Alt+M | comment on the selection | | ⌘⌥E / Ctrl+Alt+E | suggest mode on or off | | ⌘⌥→ / Ctrl+Alt+→ | show the current line in the PDF | | ⌘⌥← / Ctrl+Alt+← | go to the source of the spot last clicked in the PDF (or the middle of the view); double-clicking or right-clicking the PDF does the same | | paste or drop an image | adds it to figs/ and inserts \includegraphics (a whole figure on an empty line) | | \cite{ + a DOI or arXiv id | fetches the BibTeX entry and adds it to your .bib |

Images, citation keys and labels that don't exist in the project are underlined, as are lines with compile errors and common mistakes: environments that aren't closed or are closed by the wrong \end, stray or unclosed braces, \label before \caption in a figure (its \ref gives the section number), straight quotes, ... for \dots, a space instead of ~ before \ref/\cite, e.g. followed by a sentence space, $$…$$, sin for \sin, repeated words, \bf-style font commands and \cite{a}\cite{b}. Most have a fix in the hint; Settings turns them off. Spelling is checked with the browser's dictionary (language in Settings), skipping commands, maths, labels and the preamble. With the cursor in maths ($…$, \[…\], equation, align, …), a preview shows it typeset by KaTeX, using the project's \newcommand, \def and \DeclareMathOperator macros (Settings turns it off).

  • Left panel: Files, Search (match case, whole words, regular expressions with $1), and Outline (sections in document order through \input/\include, with word counts; the total excludes maths and commands).
  • Right panel: PDF, Assistant, Review (comments and suggestions: reply, resolve, accept, reject) and History (versions, compare, restore, "who wrote this").
  • Suggest mode: ✎ Suggest mode in the Review tab (⌘⌥E / Ctrl+Alt+E, or right-click → Suggest changes) makes what you type into suggestions instead of changes, like tracked changes. You edit as usual; each changed stretch becomes a suggestion in the Review tab, shown word by word (removed words struck through in red, new ones green), for someone to accept or reject. Until then the file, the PDF and everyone else's copy stay as they were. ⚙ Settings → Editor → Suggested changes in the editor also shows them in the editor, underlined or in full; by default the editor shows just the text. Undo takes a suggestion back. Search and replace, and adding a package for a symbol, suggest too while it's on. It's remembered per project in that browser, and a bar across the editor says when it's on. Suggestions are blue in the Review tab and comments amber. You can go back to suggestions you typed on an earlier visit, in the same browser, and keep editing them (one tab at a time per file). If someone changes the very words you're replacing, your suggestion stays and accepting it asks first.
  • Problems: after compiling, errors and warnings are listed under the PDF with their file and line; click one to go there. Biber and BibTeX errors (a missing .bib, say) are listed too. Raw log shows the whole log. Compile from scratch deletes LaTeX's working files (.aux, .bbl, …) first: in-browser compiles always start from scratch, so it matters when a texloom helper compiles with your own TeX (it keeps them in .texloom/build).
  • Create project starts from a template (article, paper with bibliography, Beamer, thesis with chapters, letter) or an import: a .zip (Overleaf: Menu → Download → Source; a GitHub "Download ZIP"; any zipped folder) or an arXiv paper's LaTeX source. From a folder on this computer… hands over to the TeXLoom app, which asks for the folder, uploads it and keeps it in sync, with this server and your creation code filled in. New → Import… in the file list does the same for an existing project. From git: clone it and run texloom new in the folder.
  • Submission (next to Source; under ⋯ in small windows) downloads a .zip for arXiv or a journal: only the files the main document uses (followed through \input, \include, \includegraphics, \usepackage, … and \graphicspath), with the compiled bibliography (.bbl, from a compile in the browser) instead of the .bib, and without build files. Remove comments (on by default: arXiv publishes the source) keeps what follows % in verbatim, \verb and URLs; One .tex file merges the \input and \include files into the main one, and with BibTeX the bibliography too. When everything is inside the main file's folder, that folder is the .zip's top level. Web app only.
  • New → Reference… in the file list adds a bibliography entry with a readable key such as vaswani2017attention, and cites it at the cursor. Type words from the title and authors to search (Crossref for published work, DataCite for arXiv preprints) and pick the paper, or paste a DOI, a doi.org or arXiv link, or an arXiv id. The entry comes from doi.org.
  • Zotero: project ⚙ Settings → Integrations → Zotero keeps a .bib file in step with a Zotero collection (or a whole library, yours or a group's). Connect once with a Zotero API key (made at zotero.org/settings/keys, read access is enough): it stays in your browser, and with a project list it travels with the list, encrypted, like the creation code; it never enters a project. Link a collection… picks the collection, BibTeX or BibLaTeX and the file, and fetches it; Refresh there (or right-click the file → Refresh from Zotero) fetches it again, changing only what changed. The link is part of the project, so collaborators see that the file is generated, by whom and when; anyone whose key can read the collection (say, a shared Zotero group) can refresh it. Keys are Zotero's own (smithtitle2020). Edit entries in Zotero: a refresh replaces hand edits to a linked file.
  • Zotero with Better BibTeX, through a folder: with the TeXLoom app keeping the project in a folder, Zotero's Better BibTeX plugin can do this without the web app: right-click a collection in Zotero → Export Collection… → Better BibTeX (or Better BibLaTeX), tick Keep updated, and save the file into the project's folder. Better BibTeX rewrites it whenever the collection changes, and the app syncs it to everyone. Better BibTeX's citation keys are stable and configurable, which some people prefer to Zotero's own.
  • Offline: after the first visit the app (and, after one compile, the TeX engine) works offline; browsers offer to install it as an app.
  • Files: the tree has folders. New (file, folder, reference, import) and Upload work in the selected folder, you can drag to move, and dropping files or whole folders from your computer onto a folder uploads them there (you're asked first if files would be replaced, or if it's a very large amount).
  • Panes: drag the dividers between the file list, the editor and the PDF/assistant panel; ☰ and ▥ hide the side panes.
  • PDF in its own window: the window button above the PDF opens it in a separate window, for example on another screen. It updates when you compile, double-clicking it jumps to the source, and it stays in step if you reload the editor.
  • Word counts: the Outline tab counts the document and each section; selecting text shows its count in the corner of the editor. LaTeX commands, citations, maths and comments aren't counted. Chinese and Japanese are counted by the character. Detailed count… there runs TeXCount on your device for a breakdown of text, headers, captions and maths (the desktop app's Word count… uses your own TeX installation's copy).
  • Symbols: the Ω tab beside Files, Search and Outline (⌘⌥S / Ctrl+Alt+S from the editor) holds mathematical and text symbols. Clicking one types it at the cursor, in $…$ if you aren't already in maths. Hovering shows the command and any package it needs, and using it adds that package to your preamble if it's missing.
  • Compiling another file: Compile compiles the open file if it has its own \documentclass (a figure or a separate document), and otherwise the main file; right-click a file to compile it. Only the main file's PDF is shared with collaborators.
  • PDF zoom: − and + above the PDF change its size, and the percentage goes back to normal size; ⌘ or Ctrl + scroll, or pinching on a trackpad, does the same. The zoom is remembered.
  • Pages and printing: the box above the PDF shows the current page; type a number and press Enter to go there. The printer button opens your browser's print dialog, with pages drawn at 200 dpi. For a print that keeps the PDF's own text, download it and print that.
  • Compile log: Log shows it under the PDF; drag its top edge to resize.
  • Downloads: the download button above the PDF, and Source (a .zip) in the header.

Phones and tablets. In small windows the editor and the PDF take turns on screen, the file list opens over them from ☰, and the other commands are under ⋯. On touch screens a bar above the keyboard has the characters LaTeX needs.

Right-click. On selected text: show it in the PDF, comment, suggest changes (suggest mode), search the project or ask the assistant. On a LaTeX command: go to a \ref's label or a \cite's bibliography entry, find the uses of a \label, open an \input or \includegraphics file, or show that line in the PDF. Anywhere else you get the browser's own menu with its spelling suggestions, and Shift + right-click always does. The file list has its own menu (preview, insert into the document, download, rename, delete), and so does the PDF (go to source, download, compile).

Preview. Choosing a Markdown file, image or PDF in the file list shows it in the PDF panel, in place of the compiled document; Compiled PDF switches back, as does choosing a .tex file or compiling. Markdown updates as you type, with no compile, and can show the project's own images and math in $…$ or $$…$$. Raw HTML appears as plain text, and images from other websites aren't loaded.

Running a server

A server is one small Python process with PostgreSQL. INSTALL.md covers installing one (a script does it on Ubuntu or Debian), its settings file, stored files in a folder or an S3-compatible bucket, creation codes and storage allowances, private servers, and backups.

Working on a project as a folder

Use this for Claude Code or any other tool, and to compile with your own TeX installation.

In Chrome or Edge, nothing to install: ⚙ Settings → Sync & storage → Keep a copy in a folder → Choose a folder…. The tab keeps the folder in sync both ways while it is open. After a browser restart, click 📁 Reconnect folder once.

How a folder copy (browser or app) takes in an edit made on disk: only what changed since the file was last synced is applied, on top of collaborators' edits made meanwhile (lines changed on both sides take the folder's version; the other stays in History). An older version reappearing in the file (an editor saving or reloading a stale copy) is not an edit: the project's text is written back. Sync a folder with one TeXLoom at a time: the browser stops if it finds the app or texloom run keeping the same folder.

With the TeXLoom app (macOS, Windows, Linux): download it from the releases page, or install it with uv tool install 'texloom[app] @ git+https://github.com/jhudsy/texloom' and run texloom app. It keeps all your project folders in sync from the menu bar or tray. The first time, it shows two choices; afterwards they are under Add project in the toolbar (and the File menu):

  • New project from a folder… turns a folder you already have into a project: its files are uploaded, encrypted, to app.texloom.org (or the server you type) and the folder stays in step.
  • Join a project with a link… takes a link (from the Share dialog or an email), shows the project's name and your access, and puts it in a folder you choose (~/TeXLoom/<name> by default). In the web app, Sync to a folder… next to a project on the start page does the same in one click, as does ⚙ Settings → Sync & storage → Keep a copy in a folder → Open in the TeXLoom app. The app asks before joining, and says if the project already has a folder on this computer. A project the app opens in the browser (Open in browser, or one made from the web app's Create project ▸ From a folder…) shows In the TeXLoom app there instead of Sync to a folder…, and isn't asked where its files should live.
  • Add a TeXLoom folder from this computer… brings back one set up earlier (e.g. left, or cloned on the command line).

Choosing a folder in the list shows whether it is up to date, offline or sending changes, with Open folder, Open in browser and Share… (the read-only link, your own edit link, and for owners edit links for others: one per person or group, to copy or email; revoking one is in the web app's Share dialog). More (also the Project menu and the right-click menu) has Tags…, Make a copy… (a new project, in a new folder, from this one's files), Word count…, Connect an AI tool via MCP… (how to connect a tool you already use through MCP) and Leave…, which stops syncing a folder (its files stay).

  • Compiling: compile with your own TeX when files change. Once that's on, Running programs when compiling is Never (default), TeX Live's safe list, or Anything the document asks, once I allow it, with Review lines… to see and allow them (as texloom allow), and Compile from scratch first deletes LaTeX's working files. The web app's With my own TeX installation (⚙ Settings → Compiling) uses this: pressing Compile in the browser asks the app, which runs latexmk (with BibTeX or Biber, makeindex and as many passes as the references need) and the PDF and log appear in the browser. If latexmk can't be found, the project pane says so, and so does a browser that asked. A project opened from the app uses it by default.
  • Git: keep the folder's git repository in step (commit, pull, push).
  • Activity unfolds the folder's recent log.
  • The search box finds folders by name or tag; the ⇅ button beside it (or the View menu) sorts them and filters by tag. Tags show in colour, which Manage tags… lets you change. Select several (Shift or ⌘/Ctrl-click) to change their Tags… or Leave… them together. Tags are the same ones as in the web app, through your project list.
  • Settings (TeXLoom ▸ Settings… or ⌘, on a Mac; the toolbar elsewhere): start at login, so folders keep syncing; the language, used from the next start (TEXLOOM_LANG=fr or en overrides it); the project list; and checking for a new version once a day (also Help ▸ Check for updates…), which shows Update to … in the toolbar and offers the download.
  • Quit TeXLoom (menu, ⌘Q / Ctrl+Q, tray) asks first, since folders then stop syncing, and offers to keep running in the background instead (Settings can stop it asking).
  • Closing the window keeps TeXLoom syncing in the menu bar or tray. On a Mac it then leaves the Dock and ⌘-Tab; click its menu-bar icon, or open TeXLoom again, to bring the window back. On Linux desktops without a tray, closing asks whether to minimise instead, since quitting stops syncing.

The downloads aren't signed with paid certificates yet, so the first time:

  • macOS: unzip the download and move TeXLoom to Applications. Open it once and close the warning, then go to System Settings → Privacy & Security, scroll down to the message about TeXLoom, click Open Anyway and confirm. (On older versions of macOS, right-click the app → Open also works.)
  • Windows: extract the .zip first (right-click → Extract All), then run TeXLoom.exe in the extracted folder. If Windows says it protected your PC, click More info → Run anyway.

The app is the same helper as below, with a window: it and texloom start share the folder list, and only one of them syncs a given folder at a time.

With the texloom helper (any OS, works without a browser, can compile): install it once with uv (or pipx):

uv tool install git+https://github.com/jhudsy/texloom
texloom clone '<link>' ~/papers/demo      # quote the link: it contains '&'
texloom run ~/papers/demo --compile       # live two-way sync + latexmk

Or share an existing folder: texloom new ~/papers/existing --server https://your.server. On Windows, quote paths with spaces: texloom run "C:\Users\Bob Smith\Desktop\paper". texloom run prints the full path of the folder it syncs. (From a source checkout, prefix the commands with uv run.)

Several folders, and starting at login. clone and new add the folder to this computer's folder list. One texloom start then keeps every folder on the list in sync: each with its own settings (.texloom/config.json: compile, git, …), log lines labelled with the folder's name, and folders added or left while it runs picked up within seconds. texloom autostart on starts it at login (a launchd agent on macOS, a systemd user service on Linux, a hidden script in the Startup folder on Windows) and writes a log (texloom autostart status says where). A folder is only ever synced by one texloom at a time: a second texloom run on it says so and stops.

While run is going, edits to the files are merged character by character with what collaborators type in their browsers. With --compile:

  • it runs latexmk after changes and shares the PDF with everyone;
  • browsers set to Compile with my own TeX send their compile requests to it.
command
texloom start sync every folder on this computer's list, in one process
texloom autostart on|off|status run texloom start at login (macOS, Linux, Windows)
texloom list / add <dir> / leave <dir> the folder list (clone and new add to it; leaving keeps the files)
texloom projects / new --server URL / use '<sync link>' / off your encrypted project list on the server: what's on it (--links prints each project's link), start one, use one from elsewhere, stop on this computer
texloom new <dir> --server URL [--code C] share an existing folder as a new project; prints both links
texloom clone <link> <dir> check out a project
texloom run <dir> [--compile] [--shell-restricted | --shell-escape] keep the folder in sync, live
texloom run <dir> --git also keep the folder's git repository in step with the project (below)
texloom sync <dir> [--git] sync once and exit (manual sync)
texloom storage <dir> server|relay keep an encrypted copy on the server, or nothing
texloom links <dir> print the project code and the edit / read-only links
texloom allow <dir> review lines that run programs; allow them for --shell-escape compiles

Per-folder options are in <dir>/.texloom/config.json, which only you can read. They are never shared:

{ "compile": false, "engine": null, "latexmk_args": [], "shell_escape": false, "confine": true, "label": "", "create_code": "" }

Collaborators write the document, so compiling is locked down by default:

  • No running programs: TeX may not run programs (-no-shell-escape).

  • No writing outside the project: TeX's "paranoid" file access.

  • No reading outside the project: a compile may read only the project, TeX's own files and fonts, and not the project's .texloom folder (which holds its keys). TeX's paranoid mode doesn't ensure this (TeX Live 2026 reads \input{../../notes}, absolute paths and dot files; LuaLaTeX can read anything), so two more layers do:

    • A sandbox hides home folders and mounted volumes, except those places: macOS's sandbox-exec, or on Linux bwrap (bubblewrap) when it is installed and allowed to run. Windows has none.
    • A check, everywhere: each TeX, BibTeX and biber run records what it read. If a compile read anything else, its PDF and log aren't shared with collaborators (they could contain what was read) and its working files are deleted.

    "confine": false turns both off, for projects whose collaborators you trust.

  • No rc files: latexmk ignores rc files (-norc), because a latexmkrc is Perl.

  • Unsafe files aren't written: neither the helper nor the browser's folder sync writes files such as latexmkrc or texmf.cnf, anything in .git, .vscode or .idea (however it's capitalised), nor any path outside the folder.

Running programs. Some packages need TeX to run programs (shell escape). Choose how much with "shell_escape" in .texloom/config.json, or on the command line:

  • false (default): nothing runs. Browser compiles are always like this.
  • "restricted" / --shell-restricted: only TeX Live's list of safe programs (enough for e.g. epstopdf, not for minted).
  • true / --shell-escape: anything the document asks for, e.g. minted. Because anyone with an edit link writes the document, lines that run programs must be approved first: texloom allow <dir> lists them (\write18, minted, pythontex, Lua os.execute, …) and allows exactly those. When a line is new or changed, that compile runs in restricted mode instead, and the log says which line is waiting. The check sees commands written out plainly; macros can hide one, so use true only for projects whose editors you trust.

When a collaborator's change writes such a line into your folder, or an % arara: directive or % !TeX program comment (which your own LaTeX editor may follow), the helper and the browser's folder sync point it out once.

Using TeXLoom with git

A synced folder can also be a git repository: run git init in it (or clone your repo and run texloom new in it). The working files sync with collaborators as usual. With server storage (the default) they needn't be online at the same time: changes wait on the server until they next open the project.

What stays out of the project:

  • .git/ is never synced, and collaborators can't write into it.
  • .texloom/ holds the project link, keys included, and has its own .gitignore, so git won't commit it and the edit link can't end up on GitHub by accident.
  • Build files (.aux, .log, the compiled PDF, …) aren't synced; add them to your .gitignore if you don't want them in git either. The .gitignore itself is a project file and is shared.

Safe: git add, commit, diff, log, push. They only read the working files.

Changes the project for everyone: any git command that rewrites the working files: git checkout <branch>, pull, merge, rebase, stash, reset --hard. The helper sees the rewritten files as your edits and shares them. (History can undo it.) Stopping texloom run first doesn't help: it picks up the changed files when it starts again.

Recommended:

  • Treat the synced folder as one branch: commit snapshots there and push them.
  • For other branches or experiments, use a separate checkout that isn't synced, e.g. git worktree add ../paper-experiment, and merge back when you mean to share.
  • Pull others' commits into the synced folder only when you want them shared, ideally when nobody is typing in the same paragraph.
  • Do rebases and conflict resolution in the separate checkout: collaborators' edits can arrive in the synced folder mid-operation and look like unexpected changes to git.

Keeping a GitHub repository in step automatically (like Overleaf's GitHub sync, but continuous): run the helper with --git on a folder that is also a git clone, on any computer that stays on (a desktop, a server, a Raspberry Pi).

texloom run ~/papers/demo --git
  • Project → git: once the project's files have been quiet for 2 minutes, they are committed (only project files: no build output, no .texloom) and pushed to the branch's upstream.
  • git → project: every minute it fetches. New commits are merged into the folder and shared with collaborators.
  • Clashes: if the same lines changed on both sides, nothing is merged and the project stays as it is; the helper prints the commands to combine them in a separate worktree. A pushed "resolution" that still contains conflict markers is refused too, so they never reach collaborators.
  • Credentials: git uses your own setup (SSH key or credential helper). The TeXLoom server isn't involved, so the project stays end-to-end encrypted.
  • Options in .texloom/config.json: "git": {"interval": 60, "quiet": 120, "push": true}. texloom sync <dir> --git does one round and exits (e.g. from cron).

To set it up from an existing repository: git clone <repo> ~/papers/demo, then texloom new ~/papers/demo --server https://your.server and share its links. From an existing project: texloom clone '<link>' ~/papers/demo, then in that folder git init, git add -A, git commit, git remote add origin <repo> and git push -u origin main. (To join an existing project with an existing, different repository, combine them by hand once.) Lines that ask to run programs, arriving from git, are pointed out as they are for collaborators' changes.

Keeping a GitHub repository in step from the browser (nothing to install, nothing left running): project ⚙ Settings → Integrations → GitHub.

  • Connect once with a GitHub token: a fine-grained token (github.com → Settings → Developer settings → Personal access tokens) for just the repositories you'll use, with Contents: Read and write. It stays in your browser, and with a project list it follows the list, encrypted; it never goes into a project.
  • Link a repository…: the repository (owner/name or its address), the branch, and optionally a folder in it that holds the project. Files only in the repository come into the project and files only in the project go to the repository; where both have a file that differs, you choose whose version stays. An empty repository gets the project as its first commits.
  • Then, while the project is open: new commits come in every minute, merged with collaborators' edits (each file three ways); the project's changes go up as one commit once it has been quiet for 2 minutes. Sync now does both at once.
  • Clashes: if GitHub and the project changed the same lines, nothing comes in, and Settings says which files. Make one side match the other, or press Keep the project's version, which brings in the rest of GitHub's changes and sends the project's version of the clashing lines.
  • One at a time: everyone in the project sees the link, and it syncs from the browser of whoever has connected GitHub (or the TeXLoom app, below), one copy at a time, so the same commit is never brought in twice. Settings says who it is; if they close the project, another takes over within two minutes.
  • The same repository in a folder too: turn on Keep this folder's git repository in step (--git) for that folder in the TeXLoom app. It then takes turns with browsers. Pulling into a synced clone of the linked repository by hand, while a browser syncs it, could bring the same changes in twice; the app warns about such a folder.

Agents (MCP)

texloom mcp is an MCP server, so Claude Code, Claude Desktop or any MCP client can work on a project directly, without a folder:

claude mcp add texloom -- texloom mcp ~/papers/demo        # a folder from texloom clone/new
claude mcp add texloom -- texloom mcp '<edit link>'         # or straight from a link

The agent appears to everyone as Claude (agent) (change with --name), with its own cursor and its lines credited in "who wrote this". Its tools: list, read, search, write and edit files; suggest changes and comment (shown in the Review tab for people to accept or reject); list, reply to and resolve comments; and compile (with local latexmk) or read the latest compile log.

Asking it to "suggest" rather than "edit" is only a request. To enforce it, add --suggest-only: the agent then has no way to change files directly, and every change is a suggestion people accept or reject. With a read-only link it can't change the project at all.

claude mcp add texloom -- texloom mcp --suggest-only ~/papers/demo

Each tool is labelled with the standard MCP annotations (read-only, destructive), so clients can decide when to ask you first. write_file and edit_file are marked destructive.

Two things to keep in mind:

  • claude mcp add saves its command in your client's settings, including any link you give it. An edit link there is a full key to the project: anything that can read that file can edit it. Prefer a folder (texloom mcp ~/papers/demo), or a read-only link if the agent only needs to read.
  • Project files and comments are text other people wrote, and the agent reads them. Someone with access could write instructions aimed at it. Use --suggest-only on projects you share with people you don't fully trust, and be careful about what else that agent can reach.

Assistant

The Assistant tab next to the PDF is a chat that works on the project like a collaborator:

  • it can list, read and search files, read the comments and suggestions in the Review tab and reply to or resolve them, make targeted edits, create or delete files, compile, and read the compile log;
  • with Ask before applying edits (the default), each change appears word by word, like a suggestion, to apply or reject; deleting a file always asks, even with this turned off;
  • every request's edits can be undone in one click, and they reach collaborators like anyone else's.

Providers (pick one in the tab; settings via ⚙):

  • Anthropic (Claude): uses the official SDK from the browser; the default model is claude-opus-5-5. Effort is adjustable, thinking summaries are shown, and if a safety classifier declines a request it is retried on Anthropic's recommended fallback model.
  • OpenAI, OpenRouter, or any OpenAI-compatible endpoint (vLLM, llama.cpp, LiteLLM, …).
  • LM Studio / Ollama, running locally. Enable CORS in LM Studio (lms server start --cors). Ollama accepts localhost pages by default; from another site, set OLLAMA_ORIGINS. Use a model with tool calling (for example a Qwen 3.x model).

Conversations are saved in your browser, per project: Past conversations lists them to read, continue (on the provider and model they used) or delete, and they're removed if you remove the project from this browser. To keep none at all (on a shared computer, say), untick Keep past conversations in this browser there; it offers to delete those already kept, for this project or every project.

Your instructions, in ⚙, are standing instructions of your own ("write in British English", "use \cref"): they're sent with the assistant's own on every request, to every model and provider, and are never summarised away. They're kept only in your browser. What the assistant is sent… next to them shows everything sent besides the conversation itself: the assistant's instructions with yours, the tools it can use, the context block in front of each message, and roughly how many tokens they and the current conversation take.

Each request sends the whole conversation, so a long one would eventually outgrow what the model can take in at once (its context). Before that happens, at 70% of the context (or of 200,000 tokens, if that's less), the assistant asks the model to summarise the earlier messages and carries on from the summary: "Earlier messages summarised to make room" shows what it kept, and the messages themselves stay on screen. If a request is too long anyway, it makes room the same way and tries once more. The context size comes from Anthropic, LM Studio (as the model is loaded), Ollama or OpenRouter; you can also enter it under ⚙ Context window. Local models are often loaded with a small context: 16,000 tokens or more leaves room to work, since the assistant's own instructions take a few thousand. A model that thinks before answering can take a few minutes over a summary.

Connect an AI tool via MCP… in the tab shows how to connect a tool you already use through MCP instead, such as Claude Code. It runs under your own account with that tool, so it needs no API key here.

API keys and provider settings are stored only in your browser. They are not part of the project and never pass through the TeXLoom server: requests go straight from your browser to the provider.

Settings

Project settings are shared with everyone who has an edit link:

  • main file
  • engine (pdfLaTeX, XeLaTeX or LuaLaTeX; if none is chosen, documents using ctex, xeCJK or fontspec compile with XeLaTeX in the browser, so Chinese works without changing anything)
  • bibliography tool (detect automatically, BibTeX, Biber or none)
  • server storage:
    • Keep an encrypted copy (default)
    • Don't store anything: this deletes the server's copy

Device settings apply only in your browser:

  • your name
  • creation code
  • live or manual sync. Manual keeps changes on your device until you press Sync now.
  • where to compile, and whether to recompile automatically after you stop typing.

The in-browser TeX engine is cached once per browser and shared by all projects (about 125 MB up front; larger package sets load only if a document needs them).

Security model

What's protected

  • Server storage is encrypted. Project content, file names and compiled PDFs are encrypted in the browser or the folder helper with a key that is only in the link (after #, which browsers never send to servers). The server stores and relays ciphertext.
  • Edits are signed. Writes are signed with the owner's key or a personal key the owner granted (the grant travels with each signature), and the server and every peer reject unsigned, wrongly signed or revoked changes, so read-only links can't edit.
  • The server can't tamper with content. Files fetched from it are checked against their content hash.

What isn't

  • The web app trusts the server that serves it. A malicious or compromised operator could serve modified JavaScript that reads the keys from the link. Use a server you trust (or run your own); the folder helper doesn't have this exposure. The server sends a strict Content-Security-Policy, and the install script pins the in-browser TeX download by checksum.
  • Links can't be un-shared. Personal edit links can be revoked, but revoking stops editing, not reading: use Move to new keys to stop reading too. Owner and read-only links can only be retired by moving to new keys. Read-only holders see everything, including the names and presence of other collaborators.
  • Editors are trusted with the project. A malicious editor can delete or vandalise content, or tell the server to drop its copy. Keep your own copies (folder copy, zip, or your own git) of work that matters.
  • The project ID is not secret. It appears in server logs. It lets someone connect and see encrypted traffic sizes and presence, but not content.
  • Compiling with your own TeX runs TeX on documents others wrote. The defaults above close the known ways to read your files or run commands. For untrusted collaborators, run the helper in a container or VM.

Found a problem? Please open an issue.

Development

uv sync --extra server
uv run python scripts/pg.py data/pg -- uv run texloom-server --data data   # terminal 1: a database of its own, and the server
cd web && npm run dev                                                      # terminal 2 -> http://localhost:5173 (proxies to :8787)

scripts/pg.py needs PostgreSQL's programs (brew install postgresql@17, apt install postgresql); it runs a database of its own from the folder, nothing installed as a service.

path what
server/relay.py relay (aiohttp): connections, signatures, storage modes, allowances, limits, the command line
server/store.py what the relay stores, in PostgreSQL: edit logs, projects, which files are stored
server/files.py where stored files' content goes: a folder or an S3-compatible bucket
server/config.py the server's settings: the settings file, TEXLOOM_* variables, the command line
texloom/crypto.py keys, links, AES-GCM, Ed25519 (mirrors web/src/crypto.ts)
texloom/replica.py folder helper's replica: pycrdt document, outbox, peer handshake, blobs
texloom/folder.py two-way folder ⇄ CRDT sync, path safety, locked-down latexmk
texloom/gitsync.py --git: a synced folder's git repository kept in step, taking turns with browsers
texloom/cli.py command line
texloom/mcp.py MCP server (stdio JSON-RPC): tools, presence, comments and suggestions
server/arxiv.py, server/admin.py arXiv source import proxy; read-only admin page
web/src/main.ts start page and project view wiring
web/src/replica.ts browser replica: Yjs + IndexedDB, outbox, peer handshake, awareness, blobs
web/src/filetree.ts, projectfiles.ts folders and files, moves, zip export
web/src/editor.ts, latex.ts CodeMirror editor; LaTeX completion, shortcuts, reference checks
web/src/output.ts, compile.ts, pdfview.ts compiling (in browser or via the helper), PDF view, log
web/src/settings.ts, storagenotice.ts, projects.ts, layout.ts setup and settings, storage warnings, start-page list, panes
web/src/assistant/ assistant: provider adapters (llm.ts), tools (tools.ts), chat panel (panel.ts)
web/src/history.ts, diff.ts versions, compare, restore, line authors
web/src/review.ts, worddiff.ts comments and suggested changes, shown word by word
web/src/suggestmode.ts, suggestcore.ts suggest mode: typing that becomes suggestions
web/src/navigate.ts, spell.ts, mathpreview.ts, checks.ts search and replace, outline, word count; spell check; equation preview; common mistakes
web/src/clashes.ts keeps both files when two people create the same name while apart
web/src/merges.ts, texloom/merges.py notes paragraphs two people changed while apart, to check
web/src/latexlog.ts, synctex.ts log parsing into problems; SyncTeX
web/src/templates.ts, references.ts, pasteimage.ts templates and import; DOI/arXiv references; pasted images
web/src/zotero.ts, github.ts (and *ui.ts) integrations: a .bib file from Zotero; keeping a GitHub repository in step
web/src/sharing.ts, crypto.ts links, personal links, revocation, moving to new keys
web/src/foldersync.ts folder sync from the browser (File System Access API)
web/sw-template.js service worker (offline app)
deploy/ install script (PostgreSQL, nginx, certbot, systemd, settings file), Caddy config

Checks

The project list has to match exactly between the Python and web clients. Both are checked against the same data, scripts/listsync-vectors.json:

python scripts/check_listsync.py
cd web && npm run check-listsync
npm run check-versions  # saved versions: every one opens exactly, and storing them stays small
npm run check-suggest   # suggest mode: random typing and collaborators' edits keep the view and suggestions in step
npm run check-chars     # edits never cut an emoji (or any character outside the BMP) in two
npm run check-packing   # compressed snapshots: both apps read the same cases (scripts/packing-vectors.json; also scripts/check_packing.py)
npm run check-submission  # the arXiv / journal .zip: files followed, comments removed, files merged
npm run check-props     # random texts and edits (Windows line endings, emoji): the editor and the shared text stay identical, merges and line endings behave
cd .. && uv run --with hypothesis python scripts/check_props.py   # the same for the desktop, and its merge agrees with the web app's
uv run --with mypy python scripts/check_textpos.py               # character, byte and UTF-16 positions can't be mixed up (texloom/textpos.py)
uv run --with hypothesis python scripts/check_folder_model.py     # the desktop's folder sync through random steps: saves, refused writes, restarts, stale copies
uv run python scripts/check_folder_deletions.py                   # a file deleted or renamed in the folder isn't brought back by a change arriving just then
uv run --extra server python scripts/check_files.py               # the server's file store: a folder, and Garage (S3) if installed
uv run --extra server python scripts/check_config.py              # texloom.example.toml lists every server setting, and parses
(cd web && npm run check-folder-model)                           # the same for the browser's folder sync, on a fake clock and folder

The server's checks need PostgreSQL's programs: each starts a throwaway database of its own (scripts/pg.py).

Sync-only projects end to end: uv run --extra server python scripts/check_synconly.py starts its own throwaway server (which keeps nothing without a creation code) and two copies of texloom run, as two computers, then edits through their folders: every file arriving, edits both ways and at once, a burst of edits, one computer off for a while, pictures, renames and deletions, and that the server stored nothing. Each computer plays an operating system for line endings (files saved on "windows" end lines with \r\n), and every pairing is run: unix/unix, windows/windows, and windows/unix both ways. With Playwright it also runs the web app in headless Chromium, typing for real against a Unix and a Windows desktop (unix/browser, windows/browser); see the script's own description. With CHECK_REFUSE_WRITES=0.3, 30% of the desktops' file writes are refused, as on Windows when another program has a file open, and everything must still end in step (CI runs this on Linux too). A few minutes; --keep leaves the folders and logs:

uv run --with playwright python -m playwright install chromium   # once
uv run --extra server --with playwright python scripts/check_synconly.py

The quick checks run on every push (.github/workflows/checks.yml). The sync-only check takes a few minutes, so it runs when the desktop app's sync or the server changes, every night, and on demand (Actions → Sync-only check), on Linux, macOS and a real Windows (sync-only.yml).

To see what a relay can take, uv run --extra server python scripts/loadtest.py all starts its own throwaway server and reports latency, CPU and memory for each scenario. Results depend on the machine.

Translations

Interface text is written in English inside t('…') (web) or _('…') (desktop app); the English is the key, and text without a translation shows in English. Each language has web/src/locales/<code>/<module>.ts (one file per source file) and texloom/locales/<code>.py. A count is keyed by its English plural form and holds the language's forms: ['{{n}} fichier', '{{n}} fichiers'], or one per plural category for languages with more (Polish: { one, few, many, other }).

The German, Spanish, Brazilian Portuguese and Simplified Chinese translations were drafted by AI and haven't yet been read by native speakers; corrections are very welcome.

To add a language (it, say):

  1. Web: copy web/src/locales/fr/ to web/src/locales/it/ and translate the values; add 'it' to Lang and LANGUAGES in web/src/i18n.ts so it can be chosen.
  2. Desktop app: copy texloom/locales/fr.py to it.py, translate it, and add it to CATALOGS in texloom/locales/__init__.py. If its plurals aren't "one for 1, other otherwise", add the rule to PLURAL_RULES in texloom/i18n.py.
  3. Check: npm run check-i18n in web/ and python scripts/check_i18n.py. Both list missing or unused text, wrong plural forms and {{placeholder}} mismatches for every language (name languages to check only those; --allow-missing for one in progress).

Status

Early prototype. What's planned or considered next, with links to the issues, is in ROADMAP.md.

License

AGPL-3.0-or-later. In-browser TeX uses texlyre-busytex (AGPL-3.0); the equation preview uses KaTeX (MIT). Everything the web app bundles, with its licence, is listed at /licenses.txt on every server (made by the build; linked at the foot of the start page and in Settings), and the desktop app's under Help ▸ About TeXLoom ▸ Licences… (texloom/assets/third-party.txt, made by scripts/licences.py when the app is built). The TeX engine is patched at deploy time (deploy/patch-busytex.py); those changes are part of this repository, as the AGPL asks.

web/public/vendor/texcount.pl is TeXcount 3.1.1 by Einar Andreas Rodland, included unmodified under the LaTeX Project Public License.

About

Local-first collaborative LaTeX editor: E2E-encrypted sync through a tiny relay, in-browser or local compilation, folder sync for agents

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages