Open-source · Apache-2.0 · self-hostable

Human-in-the-loop review for agent-written markdown.

An agent publishes a markdown spec, PRD, or runbook — the format its drafts already come in. A human reviews it and comments right on the page — inline comments, suggested edits with Accept/Reject, sign-off. The agent reads that feedback back over MCP and revises. Repeat until it's signed off.

View on GitHub mdloop on npm →
npx mdloop open ./my-project

Markdown

migration-runbook.md · v3

We should confirm the fallback plan if the migration script fails midway through, since that's the step most likely to need a human in the loop before we commit to a date.

The rollout targets three regions in the first phase, starting with the ones where support coverage already overlaps trading hours.

Everything after that follows the runbook from the last two migrations.

Comments

Priya 1 open

What's the rollback checkpoint if this fails after step 3? Let's add one before we ship this.

The loop

Three steps, repeated until the document is signed off.

01

Agent publishes

The agent uploads a markdown document as a new version and requests review.

02

Human reviews on the doc

A person reads the document itself and leaves inline comments, suggested edits, or sign-off directly on the page.

03

Agent reads feedback, revises

The agent reads the comments and suggestions back over MCP and publishes the next version.

What you get

Sentence-level anchoring

Comments track the sentence they were made on, not a line number, so they survive edits. When a revision moves the text too far, mdloop shows the comment as orphaned rather than silently reattaching it to the wrong sentence.

Built for reading prose

The review surface renders your markdown as a document, in a serif typeface sized for reading, not as a code diff — because a PRD or a design doc is meant to be read, not diffed.

Agent in the loop via MCP

The agent that wrote the document is a first-class participant: it publishes versions, requests review, and reads comments and suggested edits back over MCP so it can revise without a human relaying feedback by hand.

Nothing is ever overwritten

Every upload creates a new immutable version. Earlier versions and their comment threads stay intact, so nothing a reviewer said gets lost when the next revision lands.

Your data, exportable anytime

Full version history and every comment export as plain JSON on demand, so the review record is never locked inside mdloop.

Two ways to run it

Just you, on your laptop

npx mdloop open ./my-project spins up an embedded Postgres (PGlite, a real wire-protocol socket), mints an admin key, opens the app in your browser, and links the folder.

  • Requires Node.js ≥22 and npm.
  • mdloop serve start runs the same server detached.
  • Covers the local, single-user path — this is what the current npm release (0.1.0) is built for.

Your team or company

Team and self-hosted use means building from source and running your own infrastructure — that's a real current limitation of the npm package, not a restriction we're smoothing over.

  • SSO via MDLOOP_AUTH_MODE=oidc against Keycloak, Authentik, Dex, Google, Okta, Entra ID, or any OIDC-compliant provider; first sign-in becomes bootstrap admin.
  • Sharing at read, comment, share, or edit, plus org-admin project grants and time-limited guest invites capped at read/comment.
  • One container from the provided Dockerfile, your own Postgres ≥14, local disk or any S3-compatible store (S3, MinIO, R2, B2). MCP runs as a second container.
Read the self-hosting guide

Connect your agent

mdloop speaks MCP over streamable HTTP. Pick your client.

claude plugin marketplace add mdloop/mdloop
/plugin install mdloop-sync@mdloop

A SessionStart hook starts the server, links the current folder, and registers the MCP connection automatically for a local instance.

20 MCP tools, grouped by stage
Stage Tools
Publish upload_document, request_review
Check on review get_review_status, submit_review
Read feedback get_feedback_bundle, list_versions, get_diff
Respond create_comment, reply_to_comment, resolve_comment, accept_suggestion, reject_suggestion
Find your way around list_projects, create_project, list_documents, get_document, get_document_status, search_documents, get_org_usage, export_org

Open source

mdloop is Apache-2.0 licensed and self-hostable on your own infrastructure.

The Apache-2.0 license conveys the code — you can run it, modify it, and self-host it. It does not convey the right to call a hosted or distributed derivative "mdloop"; see the project's NOTICE file for the exact scope.

Architecture, current status, and the reasoning behind mdloop's design decisions live in the repository itself, not reproduced here: docs/ARCHITECTURE.md, docs/STATUS.md, and docs/adr/.

GitHub repository npm package

Frequently asked questions

What is mdloop?

mdloop is an open-source (Apache-2.0), self-hostable review tool for agent-written markdown. An agent publishes a markdown document, a human reviews it and leaves inline comments, suggested edits, and sign-off directly on the page, and the agent reads that feedback back over MCP and revises — repeating until the document is signed off.

How do I try it locally?

Run npx mdloop open ./my-project in a terminal. It starts an embedded Postgres database (PGlite, a real wire-protocol socket), mints an admin API key, opens the app in your browser, and links that folder — no separate database or account setup required. It requires Node.js 22 or later and npm. mdloop serve start runs the same server detached in the background.

Can I self-host it for my team?

Yes. Self-hosting for a team means building mdloop from source rather than using the npm package's local single-user path (the published npm package, currently 0.1.0, only covers running it solo on your own machine). A self-hosted deployment runs as one container from the provided Dockerfile against your own Postgres 14 or later and local disk or any S3-compatible object store (S3, MinIO, R2, or B2), with a second container for the MCP server, and supports SSO via OpenID Connect (Keycloak, Authentik, Dex, Google, Okta, Entra ID, or any OIDC-compliant provider) plus named-teammate sharing at read, comment, share, or edit levels.

How does it connect to my coding agent?

mdloop exposes an MCP (Model Context Protocol) server over streamable HTTP. The Claude Code plugin (claude plugin marketplace add mdloop/mdloop, then /plugin install mdloop-sync@mdloop) starts the server, links your folder, and registers the MCP connection automatically for a local instance. Cursor and Codex CLI connect via their own MCP config files, and any MCP client that speaks streamable HTTP can connect directly to the default local endpoint, http://127.0.0.1:58744/mcp, using an Authorization: Bearer mdloop_... API key.

Is my data private, and can I export it?

Every tenant table in mdloop's database is protected by Postgres row-level security plus composite (id, org_id) foreign keys, and the application connects as a non-superuser role that structurally cannot bypass that isolation — this is proven against a real Postgres in CI, never a mock. Every upload creates a new immutable version rather than overwriting anything, and the full version history plus all comments can be exported as plain JSON at any time.

What happens when the underlying document text changes around a comment?

mdloop's comments track the sentence they were made on, not a line number. When a document is revised, each comment is re-anchored with a confidence score; if that confidence drops too low (below 0.6), the comment is shown honestly as orphaned rather than silently jumping to the wrong spot.

What license is mdloop under?

mdloop is licensed under Apache-2.0. That license conveys the code itself — anyone can run, modify, and self-host it — but it does not convey the right to call a hosted or distributed derivative "mdloop"; see the project's NOTICE file for the exact scope.