md-redline

Comentários de revisão inline para especificações markdown e documentos de design. Agentes solicitam revisão humana durante a tarefa via MCP e pausam até que você envie feedback.

GitHub

Experimente este MCPPatrocinado

Documentação

md-redline

Comentários de revisão inline para especificações em markdown, prompts e documentos de design.

Destaque texto em um documento renderizado, deixe comentários, e seu agente de IA pode lê-los e respondê-los diretamente. Os comentários são armazenados como marcadores HTML invisíveis no próprio arquivo .md. Sem arquivos auxiliares, sem banco de dados, sem serviço externo. O arquivo markdown continua sendo a fonte da verdade.

Com o servidor MCP integrado, a revisão funciona nas duas direções. Seu agente pode solicitar sua revisão no meio da tarefa e pausar até você enviar seu feedback, ou revisar um documento que você escreveu e deixar comentários ancorados para você. De qualquer forma: sem copiar e colar, sem troca de contexto.

md-redline screenshot

Veja o fluxo completo de revisão em cerca de 30 segundos:

https://github.com/user-attachments/assets/8b9b3546-a895-42e1-b3cc-5ee5b2c00398

Funciona com Claude Code, Claude Desktop, Codex CLI, Gemini CLI e qualquer outro cliente MCP que suporte servidores stdio. Como Sean Grove argumenta em especificações são o novo código, as especificações estão se tornando a unidade primária de trabalho no desenvolvimento agêntico. mdr dá a esse fluxo de trabalho ferramentas de revisão mais próximas da revisão de código.

Início rápido

Pré-requisito: Node 20 ou mais recente.

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

Isso inicia o aplicativo local, se necessário, e o abre no seu navegador.

Ou instale 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
mdr sessions                 # List open review sessions (--kill ID ends one)

md-redline também funciona como um alias para mdr.

Isso oferece o visualizador e os comentários. A integração com o agente (revisões nas duas direções, perguntas ancoradas) vem do servidor MCP, registrado na próxima seção.

Atualização

O mdr verifica o npm uma vez por dia (a partir do seu servidor local, sem nunca bloquear nada) e mostra um pequeno aviso no visualizador e no terminal quando uma nova versão está disponível. Atualizar é um único comando:

npm install -g md-redline@latest

O servidor em execução reinicia sozinho na próxima invocação de mdr após uma atualização. Para desativar completamente as verificações de atualização, defina NO_UPDATE_NOTIFIER=1 (ou execute em CI, que é detectado automaticamente). Observe que isso é uma verificação de presença, seguindo a convenção do ecossistema: qualquer valor, até mesmo 0 ou vazio, desativa as verificações.

Configuração do MCP

Registre o servidor MCP com seu agente para que ele possa solicitar revisões no meio da tarefa.

Claude Code ou 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

A flag --scope user é importante. O Gemini usa como padrão o escopo por projeto, que registra o mdr apenas para o diretório atual.

Outros clientes MCP

Adicione esta entrada de servidor ao arquivo de configuração MCP do seu cliente:

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

Pré-requisito: mdr deve estar no seu PATH (por exemplo, via npm install -g md-redline). Se o seu cliente iniciar subprocessos sem herdar o PATH do seu shell, use o caminho absoluto de which mdr como o valor de command.

Após instalar, reinicie seu cliente MCP; a maioria dos clientes só descobre novos servidores na inicialização. Para verificar, pergunte ao seu agente "quais ferramentas mdr você tem?" e ele deve listar mdr_request_review, mdr_comment, mdr_ask, mdr_wait, mdr_baseline e mdr_add_files. (mdr_comment era chamado de mdr_review antes da versão 0.9; o nome antigo ainda funciona se você o tiver salvo em um prompt, mas os agentes não o recebem mais como opção.)

Fluxo de revisão

Com o MCP registrado, a revisão funciona nas duas direções. Escolha com base em quem está dando o feedback:

	Você revisa o documento do agente	O agente revisa o seu documento
Momento típico	O agente acabou de redigir ou editar uma especificação; você quer marcá-la antes que ele continue	Você escreveu um PRD (ou recebeu um) e quer uma crítica
O que você diz	"Deixe-me revisar specs/feature-x.md no mdr antes de você continuar."	"Use o mdr para revisar prd.md e deixar comentários."
Quem comenta	Você	O agente
Como termina	Você clica em Enviar e finalizar	Você clica em Encerrar revisão

1. Você revisa o documento do agente

O fluxo comum logo após o agente redigir um documento. Diga ao agente:

"Deixe-me revisar docs/specs/feature-x.md no mdr antes de você continuar."

O agente chama mdr_request_review e pausa. O mdr abre o arquivo, você destaca o texto e deixa comentários, depois clica em Enviar N comentários. O agente recebe seu feedback como um prompt estruturado e começa a responder aos seus comentários. Você pode continuar enviando lotes de acompanhamento enquanto ele trabalha; Enviar N e finalizar envia o último lote e encerra o ciclo. A revisão é opcional por solicitação. O agente só pausa quando você pede. Se o agente editar o documento antes de pedir sua revisão, ele chama mdr_baseline primeiro, para que o diff mostre suas alterações na primeira rodada.

Cópias automáticas antes. Um agente capaz chama mdr_baseline por conta própria, mas um menor ou apressado pula isso, e então o botão de diff fica esmaecido na rodada em que você mais quer. Um hook torna isso automático. Adicione isto ao ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [{ "type": "command", "command": "mdr baseline --hook --agent Claude" }]
      }
    ]
  }
}

Ele age apenas em arquivos markdown. Ele mantém a primeira cópia que faz de um arquivo em vez de substituí-la a cada edição, para que o diff cubra toda a sessão de edição. Ele inicia o mdr se nada estiver em execução. Adicione --no-start ao comando se preferir que ele pule a captura em vez de iniciar uma, para quando você não quiser que uma edição markdown em qualquer lugar da sua máquina inicie o mdr. De qualquer forma, ele nunca bloqueia uma edição: cada falha sai do caminho silenciosamente.

2. O agente revisa o seu documento

A direção inversa, para documentos que o agente não acabou de escrever: seu próprio rascunho, o PRD de um colega, uma especificação de outro repositório. Diga ao agente:

"Use o mdr para revisar prd.md e deixar comentários."

O agente chama mdr_comment. Suas descobertas aparecem como comentários inline ancorados ao texto exato, e o navegador abre para que você possa lê-los conforme chegam. O agente então espera (via mdr_wait) enquanto você trabalha no feedback: responda em qualquer cartão, edite o documento, exclua comentários com os quais você discorda. Quando terminar, clique em Encerrar revisão no banner. Esse clique é o sinal para o agente reler o arquivo e captar suas respostas e edições, então a sessão permanece aberta até você pressioná-lo. O agente não está travado; ele está ouvindo.

https://github.com/user-attachments/assets/a695017d-ed59-4fe8-8a29-e5306dab788c

Em qualquer direção: o agente pode fazer perguntas a você

Dentro de qualquer sessão ativa, o agente pode chegar a uma bifurcação onde sua resposta muda o que ele deve fazer em seguida. Em vez de adivinhar, ele pode chamar mdr_ask para publicar perguntas ancoradas no documento e bloquear até você responder:

Você recebe um toast com um botão Ver, um chip no banner ("N perguntas aguardando sua resposta") e um título de aba "(N perguntas)", para que você perceba mesmo de outra janela.
Cada pergunta é um cartão de comentário normal ancorado à frase sobre a qual ela trata. Responda diretamente no cartão.
No momento em que todas as perguntas tiverem uma resposta, o agente é desbloqueado com o texto da sua resposta. Não é necessário Encerrar revisão.

Isso brilha durante transferências. Deixe um comentário como "isso conflita com o que decidimos, corrija", e em vez de adivinhar, o agente pergunta "qual decisão: por assento ou taxa fixa?" ancorado onde importa. Você também pode solicitar o padrão diretamente:

"Revise prd.md com o mdr. Para suas 2 principais perguntas em aberto, use mdr_ask e incorpore minhas respostas antes de resumir."

Perguntas e revisões sobrevivem no arquivo como marcadores de comentário comuns, então nada se perde se uma sessão terminar cedo: o agente é sempre instruído a reler o arquivo.

Sem MCP

Abra um arquivo markdown com mdr /path/to/spec.md.
Destaque o texto e deixe comentários inline.
Copie o prompt de transferência.
Cole o prompt no seu agente de IA.
O agente edita o arquivo, responde ao feedback e remove os marcadores de comentário que ele tratou.
Revise o resultado na visualização de diff.

Opcional: fluxo de resolução

Ative o modo de resolução nas Configurações para revisão humana com estados explícitos de open e resolved.

Para quem é isso

Pessoas escrevendo especificações, prompts ou documentos de design localmente com agentes de IA baseados em arquivos
Equipes revisando documentos antes de serem commitados ou enviados para revisão mais ampla
Qualquer pessoa em um ciclo de edição humano + agente que queira feedback inline estruturado em arquivos simples

Não-objetivos

Não é uma ferramenta colaborativa de edição multiusuário.
Não é um substituto para revisões de PR do GitHub (use-as quando o arquivo estiver no git).
Não é projetado para conteúdo não confiável. Esta é uma ferramenta de desenvolvimento local para seus próprios arquivos.

Como os comentários são armazenados

Os comentários são armazenados como marcadores HTML invisíveis diretamente no markdown, imediatamente antes do texto ao qual se referem, para que humanos e agentes possam trabalhar a partir do mesmo arquivo.

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.

Isso torna o feedback:

visível para agentes de IA por meio de uma leitura simples de arquivo
portátil com o arquivo markdown
invisível em renderizadores normais (GitHub, visualização do VS Code)

Recursos

Revisão e comentários

Comentários inline ancorados ao texto renderizado, incluindo comentários sobrepostos
Revisão de agente bidirecional via MCP: agentes solicitam sua revisão, revisam seus documentos e fazem perguntas ancoradas
Respostas em tópicos e estados de revisão opcionais open / resolved
Âncoras ajustáveis com alças de arrastar
Comentários por toque e caneta: selecione com as alças nativas e toque no botão flutuante Comentar quando terminar (nada aparece enquanto você ajusta)
Visualizações renderizada, bruta e de diff
Cópia de prompt de transferência para um ou vários arquivos

Navegação e edição

Edição em múltiplas abas com persistência de sessão e menus de contexto de aba
Explorador de arquivos, arquivos recentes e seletor de arquivos nativo do sistema operacional
Localizar no documento (Cmd+F) com navegação entre correspondências
Sumário com rolagem espionada
Paleta de comandos (Cmd+K), atalhos de teclado e painel de configurações (Cmd+,)
Painéis redimensionáveis e menus de contexto com clique direito

Renderização e integrações

Recarga em tempo real via SSE quando arquivos mudam externamente
Renderização de diagramas Mermaid com texto comentável
Frontmatter YAML e TOML renderizado como conteúdo comentável, não oculto
Comentários HTML renderizados atenuados e monoespaçados na visualização renderizada (com  visíveis), não descartados
Incorporação de imagens locais e links clicáveis entre arquivos markdown
Modelos de comentário personalizáveis
8 temas: Claro, Escuro, Sépia, Nord, Solarized, GitHub, Rosé Pine, Catppuccin

Plataformas suportadas

macOS: suportado
Linux: suportado; o seletor de arquivos do sistema requer zenity
Windows: suportado; o seletor de arquivos do sistema usa PowerShell
Navegadores de toque (iPad Safari e similares): suportados para revisão e comentários; seleções feitas por toque ou caneta usam o fluxo do botão flutuante Comentar

Permissões

Por padrão, o md-redline pode ler qualquer arquivo markdown no seu diretório inicial. Na primeira vez que você executar mdr (ou na primeira vez após atualizar de uma versão sem o recurso de raízes confiáveis), sua pasta inicial é adicionada a uma lista de raízes confiáveis em ~/.md-redline.json. Arquivos fora do seu diretório inicial (/tmp, volumes montados, caminhos do sistema) exigem uma concessão explícita de permissão via seletor de pastas do sistema operacional na primeira vez que você os abrir. As pastas concedidas são lembradas entre reinicializações.

Para usar o modelo estrito por pasta, execute mdr --restrict uma vez após a instalação. Isso cria um ~/.md-redline.json sem confiança padrão, e você concederá cada pasta explicitamente na primeira vez que abrir um arquivo nela.

Os salvamentos de arquivo usam gravação atômica de substituir-e-renomear e detecção de conflito baseada em mtime para evitar perda de dados por edições concorrentes. A saída SVG do Mermaid é sanitizada via DOMPurify antes da renderização. Execute o md-redline apenas em ambientes nos quais você confia.

Configuração

Todas essas variáveis de ambiente são opcionais.

Variável	Padrão	Finalidade
`MD_REDLINE_BROWSER`	Navegador padrão do SO	Comando usado para abrir a URL de revisão. Defina-o para um binário de navegador específico (por exemplo, `MD_REDLINE_BROWSER=firefox`); ele é iniciado com a URL como argumento. O antigo `MDR_BROWSER` ainda funciona: é usado sempre que este não estiver definido ou estiver em branco.
`MD_REDLINE_PORT` (ou `PORT`)	`6373`	Porta para o servidor da API. Se não estiver definida, ele verifica até 10 portas acima de 6373 se essa estiver ocupada. Definida por meio de `MD_REDLINE_PORT`, significa apenas aquela instância: `mdr` usa ou inicia um servidor exatamente nessa porta, e `mdr --stop` interrompe apenas essa. `PORT` também a define, mas permanece tolerante, já que outros aplicativos também a exportam. `MD_REDLINE_PORT` vence quando ambas estão definidas; uma em branco cede para `PORT`.
`MD_REDLINE_VITE_PORT`	`5188`	Porta para o cliente de desenvolvimento Vite (somente desenvolvimento).
`MD_REDLINE_HOME`	diretório inicial do seu SO	Diretório base para o arquivo de preferências do md-redline (`.md-redline.json`, que armazena raízes confiáveis e o cache de verificação de atualizações).
`MD_REDLINE_CLIENT_ID`	um novo ID para cada processo `mdr mcp`	Identifica uma sessão de agente para `mdr mcp`. Defina-o uma vez por sessão de agente quando uma ferramenta iniciar um novo `mdr mcp` para cada chamada (por exemplo, mcp2cli ou um loop de shell), para que reabrir os mesmos arquivos reutilize a revisão desse agente em vez de iniciar outra. Não o defina em toda a máquina (em um perfil de shell, por exemplo): todos os agentes compartilhariam então uma única revisão. No máximo 256 caracteres.
`MD_REDLINE_REGISTRY_URL`	registro npm público	URL base do registro usada para a verificação de atualizações em segundo plano.
`MD_REDLINE_ALLOWED_HOSTS`	não definido	Nomes de host extras separados por vírgula aceitos pela verificação do cabeçalho Host, para que o servidor vinculado ao loopback possa ficar atrás de um proxy reverso confiável. Leia Alcançando o md-redline de outro dispositivo antes de defini-lo.
`NO_UPDATE_NOTIFIER` ou `CI`	não definido	Se qualquer um estiver presente (qualquer valor, incluindo vazio), a verificação de atualizações em segundo plano é desativada.

Alcançando o md-redline de outro dispositivo

O md-redline vincula-se a 127.0.0.1 e não tem autenticação de nenhum tipo. Isso é seguro hoje porque apenas sua própria máquina pode alcançá-lo.

MD_REDLINE_ALLOWED_HOSTS permite colocar um proxy reverso na frente dele (tailscale serve, nginx, Caddy) e revisar de um tablet. Isso não altera o endereço de vinculação, então o proxy ainda roda na mesma máquina. Isso altera a fronteira de segurança, de "minha máquina" para "qualquer coisa que possa alcançar o proxy".

O que alcançar o proxy pode ler e escrever em todos os arquivos markdown sob suas raízes confiáveis, navegar nesses diretórios, ver seus caminhos absolutos e seus arquivos recentes, abrir seletores de arquivos nativos e revelar arquivos no Finder na sua máquina, responder a sessões de revisão de agentes e desligar o servidor. Não há login.

Portanto, se você o definir:

Prefira tailscale serve, alcançável apenas pela sua própria tailnet. Não use tailscale funnel, que publica na internet aberta.
Com nginx ou Caddy, encerre o TLS e coloque autenticação na frente do md-redline você mesmo. Ele não fará isso por você.
Liste apenas nomes de host que você realmente controla. A defesa contra rebinding de DNS ainda vale para todo o resto, porque um domínio de rebinding de um atacante nunca corresponde a um nome de host que você listou explicitamente.
Sirva-o via HTTPS se puder. A API de área de transferência que o prompt de cópia da transferência precisa só funciona em um contexto seguro, então em HTTP simples esse botão falha exatamente no tablet para o qual você configurou isso.

Um cliente alcançável não pode ampliar seu próprio acesso ao sistema de arquivos: raízes confiáveis crescem apenas quando você escolhe um arquivo ou pasta no diálogo nativo, então o conjunto legível permanece o que você aprovou localmente.

Detalhes de configuração do proxy e como funcionam as verificações de solicitação

Se você precisa da variável ou não depende do seu proxy. tailscale serve e o Caddy preservam o Host original, então você deve listar o nome de host público. O proxy_set_header Host $proxy_host padrão do nginx o reescreve para 127.0.0.1:6373, que já passa, então você só precisa da variável se encaminhar o host original (proxy_set_header Host $host).

Desative o buffer de resposta para /api/watch. Atualizações de arquivos ao vivo chegam via Server-Sent Events. O md-redline envia X-Accel-Buffering: no, que o nginx honra; se o seu proxy ignorar isso, desative o buffer para esse caminho ou as edições não aparecerão até que um buffer seja preenchido.

Por que uma página hostil não pode acionar esses endpoints. Todo endpoint que altera algo é um POST ou um PUT que exige um tipo de conteúdo JSON, que uma página da web não pode enviar para outra origem sem que o navegador peça permissão a este servidor primeiro. É isso que impede uma página que você visita, um link em uma mensagem de chat, ou uma imagem incorporada em um arquivo markdown que você está revisando de acionar silenciosamente um endpoint aqui. O md-redline adicionalmente rejeita solicitações que um navegador rotula como entre sites, mas apenas como uma segunda camada: clientes que não enviam tais metadados, como o CLI e o servidor MCP, são deliberadamente não afetados.

A superfície completa, se você quiser auditá-la: GET/PUT /api/file, GET /api/browse, GET /api/files, GET /api/asset, GET/PUT /api/preferences, GET /api/config, GET /api/version, GET /api/platform, POST /api/pick-file, POST /api/pick-folder, POST /api/reveal, GET /api/watch, POST /api/shutdown, e /api/review-sessions/*. POST /api/grant-access apenas re-verifica um caminho contra raízes que você já aprovou em vez de adicionar novas.

Solução de problemas

O agente diz que não tem ferramentas mdr. Reinicie seu cliente MCP após mdr mcp install; a maioria dos clientes só descobre novos servidores na inicialização. Para clientes que não são Claude, confirme se mdr está no PATH que o cliente realmente usa (veja a configuração do MCP acima).
O navegador abriu, mas a página não carrega. Um servidor obsoleto pode estar segurando a porta. Execute mdr --stop e reabra seu arquivo.
Um banner de revisão está preso na tela. Clique em Encerrar revisão (revisões de agente) ou Cancelar revisão (suas revisões). Uma sessão sobrevive a um reinício do servidor que volta em poucos minutos; comentários sempre sobrevivem, pois vivem no arquivo.
Algo deu errado no meio da sessão. O arquivo é sempre a fonte da verdade. Comentários e perguntas de agentes vivem no próprio markdown como marcadores , então você pode lê-los, editá-los ou excluí-los em qualquer editor, e o agente é sempre instruído a reler o arquivo quando uma sessão termina inesperadamente.

Desenvolvimento

A partir do código-fonte

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

Abra a URL local impressa pelo Vite (geralmente 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

Avaliação do agente

O harness de avaliação testa se agentes de IA leem, abordam e removem corretamente comentários inline.

npm run eval:dry valida fixtures de avaliação
npm run eval executa o harness completo de avaliação
Veja eval/README.md para detalhes

Arquitetura

bin/md-redline             CLI entry point (invoked as `mdr` or `md-redline`)
bin/cli.js                 CLI implementation behind that entry point
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

Licença

MIT