A home for the documents that are bigger than one repo.

Install

mdio is a server you run on your own docs — and every mdio server ships its own client, so the binary always matches the server it talks to.

macOS (Apple Silicon), Linux and Windows (irm <server>/install.ps1 | iex). Already installed? Run mdio update — it self-updates from your server. A Dockerfile is included for running the server anywhere.

The problem

One GitHub repo is one project — that's the deal. But my most important documents don't respect that boundary: product briefs, architecture notes, specs and decisions that cover several projects at once. Committed to one repo, they're invisible from the others. Copied into each, they drift apart. Parked in a wiki or a Google Doc, my agents can't work with them at all.

And these are exactly the documents that deserve to be really read and reviewed — questioned, annotated and kept current by the humans and agents who work from them. A plain file sitting in a git repo gets none of that.

The solution

mdio gives those documents a home of their own: a vault of markdown, served as live collaborative documents over CRDTs. Humans read and review in a web editor with live cursors; agents — from whichever project they're working in — connect over MCP as first-class peers, with named presence, a visible cursor, and edits anchored to positions that survive concurrent changes.

The files stay plain markdown on disk. Authorship, comment threads and edit history ride alongside in sidecars — line-level blame tells you which words the human wrote and which the agent did, and a replay slider shows how the document got there.

When to use it

Use mdio when you and your agents need to:

• Keep foundational documents — briefs, specs, architecture, decisions — in one vault that agents from every project can reach
• Have an agent review a spec by leaving comments instead of rewriting it
• Draft a document together and watch the agent write, in real time
• Leave a comment mentioning the agent and have it pick the thread up
• Keep authorship visible — who wrote which line, human or agent

Features

• Real-time collaborative editing over the standard y-websocket protocol (Yjs)
• Web editor with remote cursors, author-attributed change highlights, markdown + mermaid preview
• MCP server for agents: open, search, stepwise writing, one-shot replace — all anchored with relative positions that survive concurrent edits
• Comment threads with ranges and @mentions; agents can open, answer and resolve them
• Line-level blame and a full history replay slider per document
• Plain markdown files stay the source of truth — the vault is just a folder
• The server ships its own client: curl <server>/install.sh | sh installs the mdio binary; mdio mcp install and mdio skill install wire up a project in seconds

Source

Source, documentation, and examples: github.com/plosson/mdio