Remargin
Enhanced inline review protocol and document access layer for markdown.
Remargin turns any markdown document into a multi-player collaboration surface with threaded comments, integrity verification, and a complete document access layer that guarantees comments are never lost or corrupted.
Why Remargin?
Collaborative document review in markdown is fragile. AI agents delete comments, break formatting, skip acknowledgments, or reply only in chat instead of inline. Manual comment conventions (<!-- TODO -->, custom fenced blocks) lack threading, identity, checksums, or any enforcement.
Remargin fixes this with:
- A protocol that defines a structured comment format inside standard markdown fenced code blocks
- A CLI tool that enforces the protocol, manages comments, and serves as the exclusive document access layer
- An MCP server that exposes the same capabilities to AI agents via Model Context Protocol
Documents remain valid markdown. Comments are human-readable. No proprietary formats, no databases, no lock-in.
Scope: what remargin manages
A remargin realm is any directory tree that contains a .remargin.yaml (discovered by walking upward from the current directory, like .git). Every .md file inside a realm is a remargin-managed document, full stop — there is no per-file opt-in, no "this file has comments so it is tracked and that one isn't." Once the config file is present, every markdown file under that tree is accessed through remargin (CLI or MCP), not through raw filesystem edits.
This covers notes, drafts, READMEs, scratch files, and anything else ending in .md. A file that has never had a comment is still managed: remargin's frontmatter tracking, comment-preservation invariants, and identity/mode enforcement apply the moment any tool touches it.
Features
- Threaded comments with reply chains, acknowledgments, and emoji reactions
- Multi-player identity with three enforcement modes (open, registered, strict)
- Cryptographic integrity via SHA-256 checksums and optional Ed25519 signatures
- Comment preservation guarantee -- writes never destroy or corrupt existing comments
- Batch operations for atomic multi-comment updates in a single write
- Cross-document queries to find pending comments, filter by author/recipient/date
- Full-text search across documents with regex support
- Document access layer with allowlisted file types, dotfile hiding, and path sandboxing
- Automatic frontmatter tracking pending comment counts and last activity
- Structural linting that validates markdown and comment block integrity
- Migration from older inline comment formats
- Dual interface -- works as a standalone CLI or as an MCP server for Claude Code
Installation
From Source
Requires Rust (1.85+):
git clone https://github.com/tixena/remargin.git
cd remargin
cargo build --release
The binary will be at target/release/remargin. Add it to your PATH:
# Copy to a directory in your PATH
cp target/release/remargin ~/.local/bin/
# Or install directly with cargo
cargo install --path .
Verify the installation:
remargin version
Quick Start
Initialize a Project
Create a .remargin.yaml config file in your project root. The
quickest path is remargin identity create, which prints a
ready-to-use YAML block to stdout so you can redirect it into place:
remargin identity create --identity your-name --type human > .remargin.yaml
# Or with a signing key for strict-mode realms:
remargin identity create --identity your-name --type human --key ~/.ssh/remargin_key > .remargin.yaml
Under the hood the file looks like:
identity: your-name
type: human
mode: is a tree property — set it at the realm level, not inside
the identity block. Enforcement modes and the registry file are
covered in Configuration.
Add a Comment to a Document
remargin comment docs/design.md "This section needs more detail."
Reply to a Comment
remargin comment docs/design.md "Good point, I'll expand this." --reply-to abc
Reply and Acknowledge in One Step
remargin comment docs/design.md "Addressed, see updated section." --reply-to abc --auto-ack
Read Comment Body from a File
remargin comment docs/design.md -F review-notes.md
echo "Quick note" | remargin comment docs/design.md -F -
List Comments
remargin comments docs/design.md
remargin comments docs/design.md --pretty
Acknowledge a Comment
# Ack in a specific file
remargin ack --file docs/design.md abc def
# Folder-wide ack (finds the comment by ID across the directory tree)
remargin ack abc
remargin ack abc --path docs/
React to a Comment
remargin react docs/design.md abc "👍"
Find Pending Comments Across Documents
