Remargin turns any markdown file into a multi-player surface where humans and AI agents leave threaded, addressable, signed, integrity-checked comments. Mutating operations are gated to preserve the conversation. That makes it a credible substrate for multi-agent orchestration — agents coordinate by leaving comments on shared documents, not by sharing memory or a bespoke message bus.
Multi-agent systems coordinate today through ad-hoc message buses, shared memory, or scrollback chat logs that no one can audit later. Every team rebuilds the same plumbing, badly.
Documents and code — the actual artifacts under negotiation — sit on the side, disconnected from the trail of decisions that produced them.
# spec.md
<!-- TODO eduardo: should the column be by name or index? -->
<!-- planner @ 14:32: name. update -->
<!-- engineer @ 14:35: ack -->
## API
The CLI sorts a CSV by a column... Should the column be addressed by name or index? Picking name — updating the spec.
A tiny structured comment format inside standard markdown fenced code blocks. Carries identity, timestamp, threading, recipients, content checksum, optional Ed25519 signature, acks, reactions, and free-form remargin_kind labels.
This claim needs a source.
A Rust CLI that enforces the protocol and an MCP server that exposes the same surface to any MCP client. File access (get, write, ls), commenting (comment, ack, react, query), all comment-preserving.
$ remargin comment spec.md "Needs source." \
--reply-to abc --auto-ack Identity, signatures, addressing, and a comment-preservation guarantee that physically refuses to drop context. Multiple agents can share a document as their coordination surface — no message bus, no shared memory.
$ remargin query . \
--pending-for-me --pretty
Every field is load-bearing. Standard markdown renderers ignore the remargin fenced block; the CLI and MCP server parse and verify it.
Should the column be addressed by name or index? Name is friendlier but breaks on headerless CSVs. Index is brittle to reordering. Pick one and stay consistent across the spec and the implementation.
“This is the entire protocol. Standard markdown renderers ignore the remargin fenced block; the CLI and MCP server parse and verify it.”
Agents coordinate by leaving comments on a shared document. Threading is structural; addressing is explicit; every block is Ed25519-signed and SHA-256-checksummed.
Two open choices for the CSV sort CLI:
1. column addressed by name vs index
2. in-place rewrite vs streaming output
Vote on each — I'll commit the spec to whatever you pick.
1. name — friendlier; if a row has no header, error out with a clear message.
2. streaming — predictable memory for large files.
Spec updated. QA, please draft the acceptance tests covering:
— name-based column selection
— streaming sort behavior on a 10M-row file
— error on a headerless CSV
“Every comment Ed25519-signed and SHA-256-checksummed (shortened here for legibility). Run remargin comments spec.md --pretty to render the thread as ASCII; remargin query . --pending-for-me for your inbox across the realm.”
“Every mutating operation runs a comment-preservation check before commit. If an agent's write would silently drop a comment another participant left behind, the write is rejected with exit code 5.”
A permissions: block in .remargin.yaml declares which paths agents can mutate and which Bash commands can run on those paths.
Two enforcement layers consume it: remargin's CLI/MCP rejects ops outside the allow-list per-op, and remargin claude restrict <path> projects the same rules into Claude Code's native tool permissions.
One source of truth. Two layers of enforcement.
permissions:
trusted_roots:
- ~/src/myproject
- path: ~/src/myproject/secure
also_deny_bash: [curl, wget]
deny_ops:
- path: ~/src/myproject/signed_archive
ops: [purge, delete]
allow_dot_folders: ['.github'] # Requires Rust 1.85+
$ cargo install --git https://github.com/tixena/remargin
$ remargin version # Create an identity (prints YAML to stdout)
$ remargin identity create \
--identity your-name --type human \
> .remargin.yaml
# Verify
$ remargin identity # Add a comment
$ remargin comment docs/spec.md "Needs source." --after-line 42
# List pending comments addressed to you across the project
$ remargin query . --pending-for-me --pretty
# Install the MCP server (Claude Code integration)
$ remargin mcp install That's the entire surface area. Full reference: README.md. Strict mode (Ed25519 signatures, registered participants only) and the Obsidian plugin are documented there.
Remargin is open source and shipping. The protocol and CLI are stable enough for daily use; ergonomics and UI affordances are landing each week.
Shipped: protocol spec, comment-preservation guarantee, threaded comments, identity & signatures (open / registered / strict), permissions layer, MCP server, Obsidian plugin, activity feed, sandbox staging, plan-based dry-run.
In flight: editor widget rendering for comments inside Obsidian, comment-kind filters in the UI, an update-check mechanism for the plugin, pretty-print of comments in the editor view.
Open invitations: protocol critique, alternative client implementations (we have CLI, MCP, Obsidian — VS Code or a web UI would be welcome PRs), integration patterns for multi-agent frameworks.