md-redline

Comentarios de revisión en línea para especificaciones markdown, prompts y documentos de diseño.

Resalta texto en un documento renderizado, deja comentarios y tu agente de IA podrá leerlos y abordarlos directamente. Los comentarios se almacenan como marcadores HTML invisibles en el propio archivo .md. Sin archivos auxiliares, sin bases de datos, sin servicios externos. El archivo markdown sigue siendo la fuente de verdad.

Con el servidor MCP integrado, tu agente puede solicitar una revisión a mitad de la tarea y pausarse hasta que hagas clic en Enviar revisión. Tú dejas tus comentarios, el agente retoma donde lo dejó. Sin copiar y pegar, sin cambios de contexto.

Mira el flujo de trabajo de revisión completo en 30 segundos:

https://github.com/user-attachments/assets/7f493201-3aca-489c-86f0-3a7df454f693

Funciona con Claude Code, Claude Desktop, Codex CLI, Gemini CLI y cualquier otro cliente MCP que admita servidores stdio. Como argumenta Sean Grove en specs are the new code, las especificaciones se están convirtiendo en la unidad de trabajo principal en el desarrollo con agentes. mdr proporciona a ese flujo de trabajo herramientas de revisión similares a la revisión de código.

Inicio rápido

Requisito previo: Node 20 o superior.

npx md-redline /path/to/spec.md

Esto inicia la aplicación local si es necesario y la abre en tu navegador.

O instálalo globalmente:

npm install -g md-redline
mdr /path/to/spec.md        # Open a file
mdr /path/to/dir             # Open a directory
mdr --stop                   # Stop the running server

md-redline también funciona como alias para mdr.

Related MCP server: md-feedback

Configuración de MCP

Registra el servidor MCP con tu agente para que pueda solicitar revisiones a mitad de la tarea.

Claude Code o Claude Desktop

mdr mcp install                   # register with both clients (default)
mdr mcp install --claude-code     # just Claude Code (via `claude mcp add`)
mdr mcp install --claude-desktop  # just Claude Desktop (JSON config file)

Codex CLI

codex mcp add md-redline -- mdr mcp

Gemini CLI

gemini mcp add --scope user md-redline mdr mcp

La bandera --scope user es importante. Gemini utiliza por defecto un ámbito por proyecto, lo que solo registra mdr para el directorio actual.

Otros clientes MCP

Añade esta entrada de servidor al archivo de configuración MCP de tu cliente:

{
  "mcpServers": {
    "md-redline": {
      "command": "mdr",
      "args": ["mcp"]
    }
  }
}

Requisito previo: mdr debe estar en tu PATH (por ejemplo, mediante npm install -g md-redline). Si tu cliente genera subprocesos sin heredar el PATH de tu shell, utiliza la ruta absoluta de which mdr como valor de command.

Flujo de trabajo de revisión

Con MCP (recomendado)

Una vez registrado, pide a tu agente que solicite una revisión:

"Déjame revisar docs/specs/feature-x.md en mdr antes de continuar."

El agente llama a mdr_request_review, mdr abre el archivo, tú resaltas el texto y dejas comentarios, luego haces clic en Enviar revisión. El agente recibe tus comentarios como un prompt estructurado y comienza a abordar tus observaciones. La revisión es opcional por solicitud. El agente solo se pausa cuando tú lo pides.

Sin MCP

1. Abre un archivo markdown con mdr /ruta/al/spec.md.

2. Resalta texto y deja comentarios en línea.

3. Copia el prompt de entrega.

4. Pega el prompt en tu agente de IA.

5. El agente edita el archivo, aborda los comentarios y elimina los marcadores de comentario que gestionó.

6. Revisa el resultado en la vista de diferencias (diff).

Opcional: flujo de trabajo de resolución

Habilita el modo de resolución en Ajustes para la revisión humana con estados explícitos de open (abierto) y resolved (resuelto).

Para quién es esto

• Personas que escriben especificaciones, prompts o documentos de diseño localmente con agentes de IA basados en archivos.

• Equipos que revisan documentos antes de que sean confirmados (committed) o enviados para una revisión más amplia.

• Cualquier persona en un bucle de edición humano + agente que desee comentarios estructurados en línea en archivos de texto plano.

Objetivos no incluidos

• No es una herramienta de edición colaborativa multiusuario.

• No es un reemplazo para las revisiones de PR de GitHub (úsalas una vez que el archivo esté en git).

• No está diseñado para contenido no confiable. Esta es una herramienta de desarrollo local para tus propios archivos.

Cómo se almacenan los comentarios

Los comentarios se almacenan como marcadores HTML invisibles directamente en el markdown, inmediatamente antes del texto al que se refieren, para que tanto humanos como agentes puedan trabajar desde el mismo archivo.

Some text <!-- @comment{
  "id":"uuid",
  "anchor":"highlighted text",
  "text":"Rewrite this section to be clearer.",
  "author":"User",
  "timestamp":"2026-03-26T12:00:00.000Z",
  "replies":[]
} -->highlighted text continues here.

Esto hace que los comentarios sean:

• visibles para los agentes de IA mediante una lectura de archivo simple

• portátiles con el archivo markdown

• invisibles en renderizadores normales (GitHub, vista previa de VS Code)

Características

Revisión y comentarios

• Comentarios en línea anclados al texto renderizado, incluidos comentarios superpuestos

• Respuestas en hilo y estados de revisión opcionales open / resolved

• Anclas ajustables con controladores de arrastre

• Vistas renderizada, sin formato y de diferencias (diff)

• Copia de prompts de entrega para uno o varios archivos

Navegación y edición

• Edición con múltiples pestañas con persistencia de sesión y menús contextuales de pestañas

• Explorador de archivos, archivos recientes y selector de archivos nativo del SO

• Buscar en el documento (Cmd+F) con navegación de coincidencias

• Tabla de contenidos con seguimiento de desplazamiento

• Paleta de comandos (Cmd+K), atajos de teclado y panel de ajustes (Cmd+,)

• Paneles redimensionables y menús contextuales con clic derecho

Renderizado e integraciones

• Recarga en tiempo real mediante SSE cuando los archivos cambian externamente

• Renderizado de diagramas Mermaid con texto comentable

• Incrustación de imágenes locales y enlaces clicables entre archivos markdown

• Plantillas de comentarios personalizables

• 8 temas: Light, Dark, Sepia, Nord, Solarized, GitHub, Rosé Pine, Catppuccin

Plataformas compatibles

• macOS: compatible

• Linux: compatible; el selector de archivos del sistema requiere zenity

• Windows: compatible; el selector de archivos del sistema utiliza PowerShell

Permisos

Por defecto, md-redline puede leer cualquier archivo markdown en tu directorio personal. La primera vez que ejecutas mdr (o la primera vez después de actualizar desde una versión sin la función de raíces confiables), tu carpeta personal se añade a una lista de raíces confiables en ~/.md-redline.json. Los archivos fuera de tu carpeta personal (/tmp, volúmenes montados, rutas del sistema) requieren una concesión de permiso explícita a través del selector de carpetas del SO la primera vez que los abres. Las carpetas concedidas se recuerdan tras los reinicios.

Para utilizar el modelo estricto por carpeta, ejecuta mdr --restrict una vez después de la instalación. Esto crea un ~/.md-redline.json sin confianza predeterminada, y concederás cada carpeta explícitamente la primera vez que abras un archivo en ella.

Los guardados de archivos utilizan escritura atómica seguida de cambio de nombre y detección de conflictos basada en mtime para evitar la pérdida de datos por ediciones concurrentes. La salida SVG de Mermaid se desinfecta mediante DOMPurify antes de renderizarse. Solo ejecuta md-redline en entornos en los que confíes.

Desarrollo

Desde el código fuente

git clone https://github.com/dejuknow/md-redline.git
cd md-redline
npm install
npm run dev

Abre la URL local impresa por Vite (normalmente http://localhost:5188).

Scripts

npm run dev          # Start dev server
npm run lint         # Lint
npm test             # Production build + unit tests
npm run test:e2e     # Playwright E2E tests
npm run build        # Production build

Evaluación de agentes

El arnés de evaluación prueba si los agentes de IA leen, abordan y eliminan correctamente los comentarios en línea.

• npm run eval:dry valida los accesorios de evaluación

• npm run eval ejecuta el arnés de evaluación completo

• Consulta eval/README.md para más detalles

Arquitectura

bin/md-redline             CLI entry point (invoked as `mdr` or `md-redline`)
server/index.ts            Hono server for file I/O, browsing, SSE, and local integrations
src/App.tsx                Main application shell
src/components/            Viewer, sidebar, raw view, diff view, TOC, explorer, settings, etc.
src/hooks/                 State, persistence, selection, file watching, drag handles, tabs
src/lib/comment-parser.ts  Inline comment parsing and mutation helpers
src/markdown/pipeline.ts   Markdown rendering pipeline
eval/                      Eval harness for agent behavior against inline comments
e2e/                       Playwright end-to-end coverage

Licencia

MIT