Domscribe

Domscribe

Agentes de codificação de IA editam seus arquivos de origem às cegas — eles não conseguem ver seu frontend em execução, e seu frontend não consegue dizer a eles onde procurar.

O Domscribe faz a ponte nas duas direções: clique em um elemento do DOM para dizer ao seu agente o que mudar, ou deixe seu agente consultar qualquer localização de origem para ver exatamente como ela aparece ao vivo no navegador. IDs estáveis em tempo de build, contexto de runtime profundo (props, estado, DOM), agnóstico de framework, qualquer agente compatível com MCP. Zero impacto em produção.

Começando

npx domscribe init

O assistente de configuração orienta você em duas etapas:

1. Conecte seu agente de codificação — selecione seu agente (Claude Code, Copilot, Gemini, Kiro ou outros) e o assistente instala o plugin automaticamente.
2. Adicione ao seu aplicativo — selecione seu framework e bundler, o assistente instala o pacote correto e mostra o trecho de configuração para adicionar.

É isso. Inicie seu servidor de desenvolvimento e você está pronto para começar.

Prefere configurar manualmente ou precisa de controle mais fino? Veja as instruções de configuração manual abaixo.

Recursos

Código → UI: Deixe o agente ver o navegador

Seu agente chama domscribe.query.bySource com um caminho de arquivo e número de linha e recebe o snapshot do DOM ao vivo, props atuais, estado do componente e atributos renderizados — diretamente do navegador em execução. Nenhuma interação humana necessária.

[!TIP] Agentes não consultam espontaneamente o estado do runtime — solicite explicitamente: "Corrija a cor do botão — use o domscribe para verificar quais classes CSS ele tem antes de mudar qualquer coisa." Seu servidor de desenvolvimento deve estar em execução com a página de destino aberta no navegador.

UI → Código: Aponte e diga

Clique em qualquer elemento na sobreposição do navegador, descreva a mudança em inglês simples e envie. O Domscribe captura a localização da origem do elemento, o contexto do runtime e sua instrução como uma anotação. O agente a reivindica, navega até o arquivo e linha exatos e implementa a mudança. A sobreposição mostra a resposta do agente em tempo real via WebSocket.

Mais

• 🎯 IDs estáveis em tempo de build — atributos data-ds determinísticos injetados via AST, estáveis em HMR e fast refresh
• 🧩 Agnóstico de framework — React 18-19, Vue 3, Next.js 15-16, Nuxt 3+, com uma interface de adaptador extensível
• 📦 Qualquer bundler — Vite 5-7, Webpack 5, Turbopack
• 🔍 Captura de runtime profunda — props ao vivo, estado e snapshots de DOM via caminhada de fiber do React e inspeção de VNode do Vue
• 🛡️ Zero impacto em produção — toda instrumentação removida em builds de produção, aplicado no CI
• 🔒 Redação de PII — e-mails, tokens e padrões sensíveis automaticamente removidos antes de sair do navegador
• 📁 Anotações vivem no seu repositório — armazenadas como arquivos JSON em .domscribe/annotations/, expostas via APIs REST que o MCP encapsula para acesso do agente
• 📡 Feedback em tempo real — relay WebSocket envia respostas do agente para a sobreposição do navegador conforme acontecem

Configuração Manual

[!NOTE] npx domscribe init lida com ambas as etapas abaixo automaticamente. Use a configuração manual apenas se precisar de controle mais fino.

O Domscribe tem dois lados: lado do aplicativo (plugins de bundler + framework) e lado do agente (MCP para seu agente de codificação). Ambos são necessários para o fluxo de trabalho completo.

Lado do Aplicativo — Adicione ao Seu Bundler

// next.config.ts
import type { NextConfig } from 'next';
import { withDomscribe } from '@domscribe/next';

const nextConfig: NextConfig = {};

export default withDomscribe()(nextConfig);

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@domscribe/nuxt'],
});

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { domscribe } from '@domscribe/react/vite';

export default defineConfig({
  plugins: [react(), domscribe()],
});

// webpack.config.js
const { DomscribeWebpackPlugin } = require('@domscribe/react/webpack');

const isDevelopment = process.env.NODE_ENV !== 'production';

module.exports = {
  module: {
    rules: [
      {
        test: /\.[jt]sx?$/,
        exclude: /node_modules/,
        enforce: 'pre',
        use: [
          {
            loader: '@domscribe/transform/webpack-loader',
            options: { enabled: isDevelopment },
          },
        ],
      },
    ],
  },
  plugins: [
    new DomscribeWebpackPlugin({
      enabled: isDevelopment,
      overlay: true,
    }),
  ],
};

// vite.config.ts
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import { domscribe } from '@domscribe/vue/vite';

export default defineConfig({
  plugins: [vue(), domscribe()],
});

// webpack.config.js
const { DomscribeWebpackPlugin } = require('@domscribe/vue/webpack');

const isDevelopment = process.env.NODE_ENV !== 'production';

module.exports = {
  module: {
    rules: [
      {
        test: /\.[jt]sx?$/,
        exclude: /node_modules/,
        enforce: 'pre',
        use: [
          {
            loader: '@domscribe/transform/webpack-loader',
            options: { enabled: isDevelopment },
          },
        ],
      },
    ],
  },
  plugins: [
    new DomscribeWebpackPlugin({
      enabled: isDevelopment,
      overlay: true,
    }),
  ],
};

// vite.config.ts
import { defineConfig } from 'vite';
import { domscribe } from '@domscribe/transform/plugins/vite';

export default defineConfig({
  plugins: [domscribe()],
});

// webpack.config.js
const {
  DomscribeWebpackPlugin,
} = require('@domscribe/transform/plugins/webpack');

const isDevelopment = process.env.NODE_ENV !== 'production';

module.exports = {
  module: {
    rules: [
      {
        test: /\.[jt]sx?$/,
        exclude: /node_modules/,
        enforce: 'pre',
        use: [
          {
            loader: '@domscribe/transform/webpack-loader',
            options: { enabled: isDevelopment },
          },
        ],
      },
    ],
  },
  plugins: [
    new DomscribeWebpackPlugin({
      enabled: isDevelopment,
      overlay: true,
    }),
  ],
};

Exemplos funcionais: Veja packages/domscribe-test-fixtures/fixtures/ para configurações completas de aplicativos em todas as combinações de framework e bundler suportadas.

Para opções de configuração do plugin, veja o README do @domscribe/transform.

Monorepos

Se seu aplicativo frontend estiver em um subdiretório (ex.: apps/web), passe --app-root durante a inicialização:

npx domscribe init --app-root apps/web

Ou execute npx domscribe init e siga os prompts — o assistente pergunta se você está em um monorepo.

Isso cria um domscribe.config.json na raiz do seu repositório que informa a todas as ferramentas do Domscribe onde seu aplicativo está. Comandos CLI (serve, stop, status) e conexões MCP do agente resolvem automaticamente a raiz do aplicativo a partir desta configuração — sem necessidade de flags extras.

Lado do Agente — Conecte Seu Agente de Codificação

O Domscribe expõe 12 ferramentas e 4 prompts via MCP. Os plugins de agente incluem a configuração MCP e um arquivo de skill que ensina o agente a usar as ferramentas de forma eficaz.

Claude Code

claude plugin marketplace add patchorbit/domscribe
claude plugin install domscribe@domscribe

GitHub Copilot

copilot plugin install patchorbit/domscribe

Gemini CLI

gemini extensions install https://github.com/patchorbit/domscribe

Amazon Kiro

Abra o painel Powers → Adicionar power do GitHub → insira https://github.com/patchorbit/domscribe/tree/main/domscribe-power.

Cursor

Qualquer agente (Skills e MCP)

Instale as skills do Domscribe:

npx skills add patchorbit/domscribe

Em seguida, adicione esta configuração MCP ao seu agente:

{
  "mcpServers": {
    "domscribe": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@domscribe/mcp"]
    }
  }
}

Como Funciona

1. Injeção. O plugin do bundler analisa cada arquivo de origem, injeta IDs data-ds estáveis em HMR via xxhash64 e registra cada mapeamento em .domscribe/manifest.jsonl.

2. Captura. Adaptadores de framework (caminhada de fiber do React, inspeção de VNode do Vue) extraem props ao vivo, estado e metadados do componente. A interface de sobreposição permite clicar em qualquer elemento e ver seu contexto completo.

3. Relay. Um daemon Fastify em localhost conecta o navegador e seu agente via REST, WebSocket e MCP stdio. Um bloqueio de arquivo evita instâncias duplicadas em reinicializações do servidor de desenvolvimento.

4. Agente. Seu agente de codificação se conecta via MCP para consultar por origem (ver como qualquer linha aparece ao vivo) ou processar anotações (reivindicar, implementar e responder a solicitações de mudança na UI).

Comparação

Nenhum concorrente individual combina IDs estáveis em tempo de build, captura de runtime profunda, consulta bidirecional origem↔DOM e uma superfície de ferramentas MCP de forma agnóstica de framework.

Ferramentas MCP

The agent-facing surface — tools, prompts, wire schemas, and error envelope — is listed below as a human-readable index.

Consulte o @domscribe/mcp README para obter esquemas detalhados de ferramentas, formatos de resposta e definições de prompt.

Pacotes

Contribuindo

pnpm install
nx run-many -t build test lint typecheck

As convenções estão em .claude/rules/. PRs são bem-vindos.

Licença

MIT