md-preview: pré-visualização de Markdown no Claude Code em um painel lateral

O md-preview é uma pré-visualização de Markdown no Claude Code, um mod da comunidade criado por Hamza Zafar (hamzafer), parte da coleção claude-code-mods dele. Quando o Claude escreve ou edita um arquivo .md, .mdx ou .markdown, um toast avisa README.md changed · /md to preview, e o /md abre um painel ao lado do chat que mostra o arquivo renderizado do jeito que o GitHub o mostra.

O painel tem botões para Prev, Next, Before, Render, Text, Browser e Close, cada um com uma tecla de atalho (p, n, b, r, t, o, q). As teclas n e p percorrem os arquivos Markdown alterados nesta sessão. b mostra o arquivo como ele era antes da primeira edição do turno ao lado do texto atual, e os blocos alterados pela última edição ganham uma barra verde. /md compare <a> <b> coloca dois arquivos lado a lado, e o ou /md open abre a mesma página no seu próprio navegador.

A forma como a página é desenhada depende da sua configuração. Num terminal com imagens (Ghostty, iTerm2, WezTerm ou kitty, fora do tmux) e com o Chrome ou um Chromium instalado, a página é desenhada em PNG e exibida no painel. Caso contrário, o painel mostra uma visualização em texto com títulos, listas, tabelas e blocos de código estilizados com as cores do terminal. O manifesto não indica uma versão mínima do Claude Code.

A gravação inicia o Claude Code com o mod carregado no pequeno projeto de demonstração e executa /md README.md. O comando responde com as dicas de teclas (n/p: next/previous · b: before | after · o: browser · r: render again · t: page/text · q: close), e um painel com borda se abre acima do prompt. A primeira linha tem os botões, a segunda mostra README.md 1/1, e abaixo dela o README do projeto aparece na visualização em texto: o título demo-app e a linha "A tiny demo app. Run it with npm start." com o trecho de código colorido. O terminal da demonstração não consegue exibir imagens, então ele mostra a visualização em texto em vez da página renderizada.

Use qualquer um dos métodos do bloco de instalação; eles instalam direto do marketplace do próprio autor. Depois de instalar, execute /reload-plugins ou inicie uma nova sessão e então use /md.

O mod é um único módulo de function hooks, hooks/register.tsx, mais um pequeno parser de Markdown (hooks/md.ts) e um gerador de páginas HTML (hooks/page.ts). Um hook tool.call lê o arquivo antes de uma chamada Write, Edit ou MultiEdit num caminho de Markdown, deixa a chamada rodar e devolve o resultado sem alterações. Este é o renderizador do GitHub, de hooks/register.tsx:

const repo = await repoOf($, dir)
if (!repo) return null // not in a GitHub repo: the Markdown stays on this machine
const r = await $.process
  .run(['gh', 'api', '-X', 'POST', '/markdown', '--input', '-'], { stdin: JSON.stringify({ text: md, mode: 'markdown', context: repo }), timeoutMs: GH_TIMEOUT_MS })
  .catch(() => null)

repoOf pergunta ao git remote -v por um remote do GitHub. Se o gh falhar, a renderização pelo GitHub fica pausada por um minuto e o renderizador embutido é usado. O HTML é gravado em $TMPDIR/md-preview/ e desenhado com o Chrome headless por meio de um script sh curto, um desenho por vez, com os desenhos em cache por conteúdo. Os arquivos que o Claude editou são desenhados em segundo plano quando o turno termina, então o /md normalmente abre numa página que já está desenhada.

Não há opções no /config. Tudo é feito com o comando e as teclas do painel: /md abre o arquivo mais recente, /md <path> abre qualquer arquivo Markdown, /md compare <a> <b> compara dois e /md open abre o navegador. Se outro comando já usar o nome /md, o mod registra /mdview no lugar. Para mudar limites como a lista de caminhos do Chrome (CHROMES), o número de arquivos guardados (MAX_FILES) ou o tamanho do cache (CACHE_SIZE), edite as constantes no início do register.tsx.

Lemos todos os arquivos que o plugin pode executar antes de rodá-lo: plugin.json, hooks/hooks.json, hooks/register.tsx, hooks/md.ts, hooks/page.ts, as declarações de tipos e os testes. Não há package.json, script de instalação, binário nem código empacotado, e não encontramos caracteres ocultos ou de largura zero.

• Rede: nenhuma requisição direta. Com um remote do GitHub e um gh autenticado, o texto Markdown é enviado para a API /markdown do GitHub via gh api (register.tsx:592-594), sem nenhum consentimento adicional. Arquivos acima de cerca de 390 KB são renderizados localmente. A página renderizada é carregada pelo Chrome headless com uma Content-Security-Policy que permite imagens de qualquer host (page.ts:97), então imagens remotas num arquivo Markdown são baixadas quando a página é desenhada. Scripts no Markdown não podem rodar.
• Processos: git ls-files e git remote -v (register.tsx:386, 607), gh api (593), sh -c com um script fixo que inicia o Chrome headless e encerra apenas o Chrome que ele iniciou (49-67, 675), e open ou xdg-open para o botão do navegador (788).
• Gravação de arquivos: apenas $TMPDIR/md-preview/ (HTML da página, partes em PNG e um perfil descartável do Chrome). Nada em ~/.claude, configurações, arquivos de shell, LaunchAgents ou git hooks.
• Leitura de arquivos: os arquivos Markdown que o Claude edita, os arquivos que você indica e, antes do primeiro comando de shell de um turno, até 200 arquivos Markdown do repositório obtidos de git ls-files.
• Ambiente: HOME, TMPDIR, TMUX, TERM_PROGRAM e TERM. Eles não são enviados a lugar nenhum.
• Daemons, telemetria, injeção de prompt: nenhum. Ele não adiciona texto aos prompts nem aos resultados das ferramentas.
• Bloqueio (gating): o hook tool.call é um observador. Ele espera a chamada e devolve o resultado sem alterações. O validate o aponta como um hook de bloqueio sem .catch; a primeira chamada de shell de um turno espera o snapshot do Markdown, que apenas lê arquivos.
• Requisitos externos: Chrome, Chromium, Edge ou Brave para a visualização renderizada, um terminal com suporte a imagens e, opcionalmente, o gh. Todos são opcionais; a visualização em texto é a alternativa.
• Licença: MIT, com um arquivo LICENSE na raiz do repositório.

O claude plugin validate não relatou erros nem avisos, e os 26 testes do autor passaram no Claude Code 2.1.291.

Verificado com o Claude Code 2.1.291 no macOS (validate, testes e a gravação). Se o painel não estiver como você espera:

• /md é desconhecido: confira se o /plugin mostra o md-preview carregado, ou tente /mdview.
• Você vê texto em vez de uma página: o seu terminal não consegue mostrar imagens, você está dentro do tmux ou nenhum Chrome foi encontrado. Pressione r depois de corrigir, ou t para alternar a visualização.
• "Chrome could not draw the page": pressione r para tentar de novo. O mod não tenta de novo sozinho.
• A mudança num arquivo não gera um toast: só caminhos de Markdown são acompanhados, e gravações feitas pelo shell só são percebidas num repositório git.
• O painel diz built-in em vez de GitHub: o arquivo não está num repositório do GitHub, o gh não está autenticado ou o arquivo tem mais de cerca de 390 KB.