tandem

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logotype-dark.png"> <img src="docs/assets/logotype-light.png" alt="Tandem" width="280"> </picture> </p>

<p align="center"> <a href="https://www.npmjs.com/package/tandem-editor"><img src="https://img.shields.io/npm/v/tandem-editor?label=npm" alt="npm version"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-BUSL--1.1-blue" alt="License: BUSL-1.1"></a> <a href="https://github.com/bloknayrb/tandem/releases/latest"><img src="https://img.shields.io/github/v/release/bloknayrb/tandem?label=release" alt="Latest release"></a> </p>

An editor where you and an AI work on the same document at the same time.

Tandem is a document editor that lets you and an AI work on the same file together. You highlight a passage. The AI sees what you highlighted and can ask about it, comment on it, or propose changes that appear as cards beside your document. You decide what to keep.

One thing to know up front: the AI side needs an AI client running on your own computer, plus the subscription behind it. Claude Code is the default, and a Claude Pro or Max subscription includes it. Clients connect over MCP — an open standard for letting an AI reach tools and files — so others can be used too. Connect your AI below covers the setup, which is a wizard rather than a config file. Without a client connected, Tandem is a capable local document editor and nothing more.

Tandem is approaching v1.0 and ships continuous improvements. See CHANGELOG.md for what is in the latest release.

Contents

• What Tandem does
• See it in action
• Who Tandem is for
• Getting started
• How you work with Tandem
• Privacy and trust
• Where Tandem is headed
• Documentation
• License
• For developers and contributors
• Architecture overview
• The MCP integration policy
• Cowork
• MCP tools at a glance
• Channel push and real-time updates
• Development setup
• Tech stack
• How to contribute

What Tandem does

Most people use AI on a document by copying a passage into a chat window, asking a question, and pasting the answer back. Tandem closes that loop: the AI sits beside the document you are editing and reads from it directly, so there is nothing to copy and nothing to paste back.

Ask it for a rewrite, a summary, a check on tone, or a second opinion. Its suggestions arrive as cards next to the document — accept them, reject them, or reply to ask for something different.

Tandem is built to work with Anthropic's Claude out of the box. Other AI tools can also connect. See the developer section below for the details of which clients work and which are tested first.

See it in action

<p align="center"> <img src="docs/screenshots/01-editor-overview.png" alt="The Tandem editor with a document open on the left and a panel of AI annotation cards on the right" width="800"> </p>

The main view. Your document fills the left side. The side panel on the right holds the AI's annotations and the chat conversation.

<p align="center"> <img src="docs/screenshots/03-side-panel.png" alt="A close-up of annotation cards beside the document, including a replacement card showing the original text in red strikethrough and the proposed text in green, with Accept and Reject buttons" width="500"> </p>

Annotations from the AI. Comments and suggestions appear as cards. For a replacement, your current text and the proposed wording show together — accept the change, reject it, or reply to ask for something different.

<p align="center"> <img src="docs/screenshots/02-chat-sidebar.png" alt="The chat panel showing a question from the user and a reply from the AI assistant about the document" width="460"> </p>

The chat panel. Ask a question about the document and the AI answers in place — it can read the file directly, so there is nothing to copy and paste.

<p align="center"> <img src="docs/screenshots/04-toolbar-actions.png" alt="The top of the editor showing several documents open in tabs, the formatting toolbar, a text selection, and the Solo and Tandem mode toggle" width="800"> </p>

Several documents open in tabs, with the formatting toolbar above the text. Highlight a passage and the AI sees the selection as you make it. The Solo / Tandem toggle on the right decides whether you are working alongside the AI or on your own — see Privacy and trust for what Solo holds back.

Who Tandem is for

• If you draft long-form writing — an essay, a report, a proposal, a design doc — and want a second reader for tone and structure.
• If you review what someone else wrote — a thesis chapter, a contract, a spec, an RFC — and want a faster pass.
• When a colleague hands you a document to mark up, or a design lands in your queue for sign-off.
• When the AI wrote a draft and you need to decide what to keep.

Tandem is built for individuals working on their own documents. The example document types above are just that — examples; the workflow is the same whatever you are writing or reviewing. The interface is English-only for now.

Getting started

System requirements

Windows 10 version 22H2 or Windows 11. macOS 12 (Monterey) or later. Linux with glibc 2.31 or later (Ubuntu 20.04+, Debian 11+, Fedora 34+). On Windows, the first launch may show a "Windows protected your PC" warning until the installer's signing certificate accumulates SmartScreen reputation. See docs/troubleshooting.md#windows-smartscreen-warning for the steps to dismiss it.

Download the desktop app (recommended)

Pick the installer for your platform from the latest release. Windows, macOS, and Linux builds are available.

The desktop app bundles the editor, the server it talks to, and storage for the connection token. Updates land automatically. Double-clicking a .md, .markdown, .txt, .html, or .docx file opens it directly in Tandem.

Connect your AI

Installing Tandem gives you the editor. The AI half needs one more thing: an AI client running on your machine, and the subscription behind it.

The default — and the one Tandem is tested against — is Claude Code, Anthropic's Claude that runs on your own computer rather than in a browser tab. A Claude Pro or Max subscription includes it, so if you already pay for Claude you are most likely already covered; pay-as-you-go API billing works too. See Anthropic's pricing for what each plan costs.

One thing worth knowing before you start: the Claude you use at claude.ai in a browser cannot connect to Tandem. A web page has no way to reach a document sitting on your disk. So a subscription is necessary but not sufficient — you also need Claude Code, or Claude Desktop, installed locally.

You do not have to configure any of this by hand. Tandem opens a setup wizard the first time you run it: if Claude Code is not installed, the wizard can install it for you in one click on Windows, macOS, and Linux, and it then writes the connection settings itself. You can reopen it any time from Settings → AI Assistant.

Prefer a different AI? Any MCP-capable client can connect to the same endpoint — see the compatibility table for what is supported and what is untested, and Cowork for connecting Claude Desktop on Windows.

How Claude starts matters. Tandem talks to Claude over two independent connections: one lets Claude read and edit your document, the other tells it the moment you comment or send a chat message. Sessions Tandem launches for you — including the desktop app's Relaunch Claude button — get both. A session you start yourself by typing claude gets only the first, unless you start it like this:

claude --dangerously-load-development-channels server:tandem-channel

Installing the Tandem plugin is the other way to get it, and needs no flag — see Channel push and real-time updates below. Use one or the other, not both: each delivers independently, so a session running both receives every event twice.

Without the flag nothing breaks and nothing is lost: your messages and comments are saved, and Claude sees them the next time it checks its inbox. But it will not react on its own, which reads as Claude ignoring you. If that is what you are seeing, this troubleshooting entry walks through it, and Settings → About → Copy Diagnostics (or tandem doctor, on npm installs) reports whether anything is listening. More detail in Channel push and real-time updates.

What you get

• Multiple documents open in tabs, with .md, .txt, .html, and .docx support (Word files are editable; the original is only written when you explicitly save).
• A scratchpad (Ctrl+N) for drafts you do not want to save to disk.
• A command palette (Ctrl+Shift+P) with fuzzy search, ranked by how well each result matches.
• Find and replace, including across all open tabs.
• An outline panel for navigating long documents.
• Paste that keeps its structure: Markdown tables and images arrive as real tables and images, and a URL pasted over selected text becomes a link.
• Suggestions shown as word-level diffs, so you can see exactly which words change.
• Optional smart typography (curly quotes, em dashes) and a spellcheck toggle, in Settings (Ctrl+,).
• Light and dark themes.
• Keyboard navigation through pending suggestions: Alt+] and Alt+[ to move between them, Ctrl+Enter to accept, Ctrl+Shift+Enter to reject.

Other ways to install

If you use a terminal, you can also install Tandem with npm install -g tandem-editor (Node.js 22.12 or newer required), then run tandem — it starts the server and prints a http://127.0.0.1:3479 URL to open the editor in your browser, where the first-run wizard connects Claude. (For a scripted, non-interactive setup, run tandem setup --apply once first.) This is mostly useful if you already have Node.js installed; the desktop app is the recommended experience.

Got stuck

Run the built-in diagnostics first — they check the setup problems that cause most first-launch failures. In the desktop app, that is Settings → About → Copy Diagnostics. If you installed from npm, run tandem doctor instead. (The desktop app does not install the tandem command, so use the button rather than the CLI.)

Then see docs/troubleshooting.md for common problems and how to resolve them.

How you work with Tandem

1. Open a document in Tandem. 2. Start your AI client — Claude Code, in the default setup. Once you have been through Connect your AI, Tandem and Claude find each other automatically; you do not reconnect them each time. 3. Type a question in the chat panel, or highlight text in the document to focus the AI on a passage. The AI sees what you highlight as you highlight it. 4. The AI's suggestions appear as cards beside the document. You decide what to accept. 5. Save when you are finished.

See docs/workflows.md for examples of how this looks in daily use.

Privacy and trust

• Tandem itself runs on your computer and stores your documents on your disk. We do not operate any servers that hold your files.
• When you ask the AI to do something, the text you share with it goes to whichever AI service you are using. For example, if you connect Claude, the text goes to Anthropic under their terms. Tandem does not relay or copy your document anywhere else.
• Tandem includes a private notes feature. Notes you mark as private are stripped from every response the AI sees (ADR-027).
• Solo mode holds your work back from the AI. The Solo / Tandem toggle in the title bar (Ctrl+Shift+M) is not just a notification setting: while you are in Solo, the comments and replies you write are withheld from what the AI is told and from what it can look up — its inbox, its reads of the annotation list, and the live updates pushed to it. Each held item shows an amber Held pill, the status bar keeps a running count, and switching back to Tandem releases the set together. One limit worth knowing: exporting an annotation report is a deliberate "give the AI everything" action and includes held comments. See the user guide for exactly what the hold does and does not cover.
• Tandem does not collect telemetry or analytics by default — no usage data, and crash reporting is off unless you turn it on. It activates only if you set TANDEM_SENTRY_DSN to a Sentry or self-hosted GlitchTip endpoint of your own; unset (the default), no crash data ever leaves your machine. Sent reports are scrubbed of home-directory paths, API keys, and document payloads — see docs/security.md for the details.
• When paid licensing arrives at v1.0, running the app will validate a signed license file on your own machine (no network call required); update checks will remain network-only, carry no analytics, and the update service will log only what it needs to authorize the download.

See docs/security.md for the full security model.

Where Tandem is headed

Tandem is on the way to a v1.0 release. Today the supported AI integration is Claude (Claude Code / Claude Desktop) over MCP, set up with a one-click in-app wizard. Local models (Ollama, LM Studio) are committed for v1.0 and in active development (#1123) — they'll use the same one-time license as everything else; cloud API-key providers (OpenAI, Gemini) follow in v1.1. Word documents round-trip: edit a .docx and save it back as a real Word file, with the comments you sent your AI written back as native Word comments — and Tandem snapshots a file before its first write, so you can restore the original from inside the app. Work still in progress covers turnkey setup on macOS and Linux, licensing, and final polish; pricing is covered under License below. The full plan lives in docs/roadmap.md, and CHANGELOG.md records what landed in each release.

Documentation

• docs/user-guide.md for a longer walkthrough of the editor.
• docs/workflows.md for daily usage patterns.
• docs/troubleshooting.md for when something goes wrong.
• docs/data-locations.md for where Tandem stores data and how to uninstall cleanly.
• docs/positioning.md for the longer story of why Tandem exists.
• docs/decisions.md for design decisions (ADRs).
• docs/roadmap.md for what is coming.
• docs/architecture.md for diagrams and the file map.
• docs/mcp-tools.md for the MCP tool reference.
• docs/security.md for the security model.
• docs/licensing-explained.md for how licensing will work at v1.0 — in plain English first, then in detail.
• docs/configuration.md for advanced configuration.
• docs/cli.md for CLI command reference.
• CHANGELOG.md for release notes.

License

Tandem is free during the public beta. At v1.0 it moves to a one-time paid license; existing beta users are grandfathered with a free license. It is licensed under the Business Source License 1.1 (BUSL-1.1); see LICENSE for the terms.

Claiming the beta license: Tandem has no telemetry, analytics, or signup, so there is no list of beta users to work from — we can only grandfather people who tell us they're here. If you've been using the beta, email <support@tandem.ink> with roughly when you first installed it, and you'll be sent a free license before enforcement turns on. Activate it as soon as it arrives (Settings → License) rather than filing it away: the pre-v1.0 build says licensing isn't enforced yet, which is true, and is exactly why an unactivated key is easy to lose.

---

For developers and contributors

Architecture overview

Three layers: the editor (Tiptap inside a Tauri desktop app or a browser), the Tandem server (Hocuspocus on port 3478 for collaborative edits and an MCP HTTP server on port 3479 for AI tool calls), and the AI client (Claude Code or any other MCP-capable client). The full file map and data flows live in docs/architecture.md.

The MCP integration policy

The Model Context Protocol (MCP) is an open standard for AI clients to talk to tools and data sources. Tandem exposes its document and annotation surface over MCP, which is how AI clients like Claude read and modify the file you are editing.

The integration policy is set by ADR-038:

> Tandem's integration contract is MCP. The default integration is Claude (Claude Code + Claude Desktop) — it's what we recommend, what we test against, and it ships with the channel push, cowork, plugin monitor, and auto-launcher features. Any MCP-capable client can connect to the same MCP HTTP endpoint and use the same MCP tools, but the Claude-specific transports don't apply. Other clients are best-effort, MCP-contract-compatible, not validated today. > > Integration setup runs through the integration setup wizard (#477 PR 3). The earlier transitional behavior — Tandem auto-writing its MCP entry to Claude's config files on Tauri startup — was removed in #477 PR 3c-ii-c. Every integration (Claude included) is now configured via the wizard, never silently; tandem setup --apply is the scriptable non-interactive equivalent.

Client compatibility:

| AI surface | Status | |---|---| | Claude Code (local CLI) | Default. Validated. Channel push supported. | | Claude Desktop (local app) | Supported via the Cowork plugin bridge (Windows today). Request/response only — channel push N/A. | | claude.ai web chat | Not supported. Would require exposing the local server publicly via a tunnel, which is outside scope. | | Other MCP-capable clients (Cursor, Continue.dev, LM Studio, Ollama, …) | Best-effort, MCP-contract-compatible, not validated. | | Non-MCP AIs | Not supported today. Local models (Ollama / LM Studio via OpenAI-compatible endpoints) are committed for v1.0 (ADR-039, tracked in #1123); cloud providers (ChatGPT direct, Gemini direct) follow in v1.1. |

Cowork

Cowork is Claude Desktop's local agent mode — Claude runs in an isolated VM on your machine. Tandem connects to it through Claude's plugin system, but you don't add a marketplace or run any /plugin commands yourself.

• How to enable (Windows desktop app): open the integration wizard (Settings → AI Assistant, or "Set up" next to Cowork) and click Enable Cowork, or toggle it on in Settings → Network. Tandem writes the plugin entry into every detected Cowork workspace and adds a Windows firewall rule so the VM can reach the Tandem server on this computer. That firewall step needs admin once — without it, the VM can't connect.
• Why it's automated, not a manual marketplace install: inside the VM the plugin must point at host.docker.internal:3479 and carry a per-machine secret auth token. A published marketplace plugin can't carry that token, so Tandem provisions the workspace entries directly. (The published tandem@tandem-editor marketplace plugin is for Claude Code running on the host, over 127.0.0.1 — see below.)
• Verify: in a Cowork session, ask Claude to open or list your documents — Tandem's tools should appear. If they don't, re-run Enable.
• Real-time updates: live annotation/chat push needs the Tandem desktop app plus one of the push transports (see Channel push); the Cowork connection itself is request/response.
• macOS / Linux: not yet — tracked in #316 / #317.

For Claude Code on the host, the published plugin can be added from the marketplace instead of the wizard:

claude plugin marketplace add bloknayrb/tandem
claude plugin install tandem@tandem-editor

This activates the MCP tools, the bundled skill, and — on Claude Code 2.1.212 or newer — a monitor that delivers real-time events with no extra flag. See Channel push for how that compares to the channel shim.

MCP tools at a glance

Tandem's MCP tools span five capability areas. Full reference: docs/mcp-tools.md.

• Document. Open, switch, list, close, and convert documents; read text content and outlines; save back to disk.
• Annotation. Create, resolve, remove, and edit annotations; query the annotation list; export a review report.
• Apply. Edit text ranges directly when an annotation is not the right surface.
• Navigation. Inspect the active selection, jump to ranges, and resolve internal links.
• Awareness. Read user presence and Solo/Tandem mode; check the inbox for selection events, chat messages, and annotation actions; reply in the chat sidebar.

Channel push and real-time updates

Real-time push delivers events (selections, annotation actions, chat messages) to the AI client over Server-Sent Events the moment they happen, so the AI does not have to poll. There are two transports.

The channel shim is the default and the one Tandem tests against (ADR-028). Sessions the desktop app launches for you already have it. To wire it up yourself:

tandem setup --apply --with-channel-shim                   # persistent setup
claude --dangerously-load-development-channels server:tandem-channel   # one-off

The --dangerously-load-development-channels flag is Claude Code's marker for unstable APIs; it becomes unnecessary when the Channels API stabilizes.

The plugin monitor is the alternative for sessions you start by hand, and it needs no flag. Installing the plugin (above) registers it, and every claude you start afterwards wakes on document changes. It requires Claude Code 2.1.212 or newer — on older versions the install still succeeds and the monitor simply never runs, with nothing to tell you so, which is why the version matters. Do not enable both: each transport delivers independently, so a session running the plugin and the channel flag receives every event twice.

Note that Solo mode suppresses annotation events on both transports by design — chat still comes through. If you are testing push and only chat arrives, check the mode toggle before debugging the transport.

Without either, the AI uses tandem_checkInbox to pull the same events on demand. You can also ask Claude to poll periodically with /loop 30s check tandem inbox and respond to any new messages.

Development setup

git clone https://github.com/bloknayrb/tandem.git
cd tandem
npm install
npm run dev:standalone   # backend (:3478, :3479) + frontend (:5173)

Open <http://127.0.0.1:5173>. The repo's .mcp.json configures Claude Code automatically when run from this directory.

Verify the server is up:

curl http://127.0.0.1:3479/health
# → {"status":"ok","version":"x.y.z","transport":"http","hasSession":false}

For exposing the server on a LAN, set TANDEM_BIND_HOST and use tandem rotate-token to rotate the auth token. See docs/security.md for the full network posture.

See docs/cli.md for the full list of npm scripts.

Tech stack

Tandem is built on Tiptap and ProseMirror (editor), Yjs and Hocuspocus (CRDT sync), Tauri 2 (desktop), and Svelte 5 (UI).

How to contribute

Open an issue first for non-trivial changes; for bug reports and small fixes, a PR is fine. Follow the workflow described in CLAUDE.md. Run npm run typecheck and npm test before opening a pull request.