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 tratá-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 30 segundos:

https://github.com/user-attachments/assets/3a2bf20a-d4a0-403c-b023-e877130fd959

Funciona com Claude Code, Claude Desktop, Codex CLI, Gemini CLI e qualquer outro cliente MCP que suporte servidores stdio. Como Sean Grove argumenta em specs são o novo código, especificações estão se tornando a unidade primária de trabalho no desenvolvimento orientado a agentes. 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

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

Isso dá a você 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

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 desabilitar 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, desabilita 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 por padrão o escopo por projeto, que registra 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_review, mdr_ask e mdr_wait.

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 rascunhar 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 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 um agente rascunhar 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 tratar 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.

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 mdr para revisar prd.md e deixar comentários."

O agente chama mdr_review. As descobertas dele 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 aguarda (via mdr_wait) enquanto você trabalha no feedback: responda em qualquer cartão, edite o documento, exclua comentários com os quais 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/41339401-6096-40de-abbf-e93ef7ffd2c2

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 em questão. Responda diretamente no cartão.
No momento em que todas as perguntas tiverem 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 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, trata o feedback e remove os marcadores de comentário que ele processou.
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 que escrevem especificações, prompts ou documentos de design localmente com agentes de IA baseados em arquivos
Equipes que revisam documentos antes de commitá-los ou enviá-los 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 multiusuário de edição.
Não substitui 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, preview do VS Code)

Recursos

Revisão e comentários

Comentários inline ancorados ao texto renderizado, incluindo comentários sobrepostos
Revisão bidirecional do agente 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 do 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 SO
Localizar no documento (Cmd+F) com navegação entre correspondências
Sumário com rolagem espia
Paleta de comandos (Cmd+K), atalhos de teclado e painel de configurações (Cmd+,)
Painéis redimensionáveis e menus de contexto com botão 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
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 SO 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 com renomeação 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 em que 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 `MDR_BROWSER` mais antigo ainda funciona: é usado sempre que este não estiver definido ou estiver em branco.
`MD_REDLINE_PORT` (ou `PORT`)	`6373`	Porta para o servidor de API. Ele verifica até 10 portas acima a partir daqui se essa estiver ocupada. `MD_REDLINE_PORT` vence quando ambos estão definidos; um em branco cede para `PORT`.
`MD_REDLINE_VITE_PORT`	`5188`	Porta para o cliente de desenvolvimento Vite (apenas desenvolvimento).
`MD_REDLINE_HOME`	seu diretório inicial do 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ção).
`MD_REDLINE_REGISTRY_URL`	registro npm público	URL base do registro usada para a verificação de atualização em segundo plano.
`MD_REDLINE_ALLOWED_HOSTS`	não definido	Nomes de host extras separados por vírgula aceitos pela verificação de cabeçalho Host, para que o servidor vinculado a 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ção em segundo plano é desabilitada.

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 a partir de um tablet. Isso não altera o endereço de bind, então o proxy continua rodando na mesma máquina. Isso muda a fronteira de segurança, de "minha máquina" para "qualquer coisa que alcance o proxy".

O que alcançar o proxy pode ler e escrever em todos os arquivos markdown sob suas raízes confiáveis, navegar por esses 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ê configurar isso:

Prefira tailscale serve, acessí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 hostnames que você realmente controla. A defesa contra rebinding de DNS continua valendo para todo o resto, porque um domínio de rebinding de um atacante nunca corresponde a um hostname que você listou explicitamente.
Sirva via HTTPS se possível. A API de área de transferência que o botão de copiar do prompt de hand-off precisa só funciona em um contexto seguro, então em HTTP puro esse botão falha exatamente no tablet para o qual você configurou isso.

Um cliente acessível não pode ampliar seu próprio acesso ao sistema de arquivos: as 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 requisiçã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 hostname 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 respeita; 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 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 também rejeita requisições que um navegador rotula como cross-site, mas apenas como uma segunda camada: clientes que não enviam esses metadados, como a CLI e o servidor MCP, são deliberadamente afetados.

A superfície completa, se você quiser auditar: 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 desatualizado pode estar segurando a porta. Execute mdr --stop e depois reabra seu arquivo.
Um banner de revisão está preso na tela. Clique em Encerrar revisão (revisões de agentes) ou Cancelar revisão (suas revisões). As sessões não sobrevivem a um reinício do servidor, mas os comentários sobrevivem.
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 de agentes

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

npm run eval:dry valida os 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