Graphify-ts

Madar

Dê ao seu agente de codificação o contexto do repositório que ele precisa antes de começar a pesquisar.

O Madar constrói um grafo local do seu repositório TypeScript ou Node.js e transforma a pergunta atual em um pacote de contexto pequeno e ciente da tarefa. Claude Code, Codex, Cursor, Copilot, Gemini, Aider e OpenCode podem começar com arquivos, símbolos, trechos e relacionamentos relevantes, em vez de redescobrir o repositório do zero.

• Comece menor: entregue ao agente pontos de entrada e caminhos de execução prováveis antes da busca ampla.
• Fique local: a geração do grafo não envia seu código-fonte para a nuvem nem exige um serviço em nuvem.
• Fique atualizado: perfis MCP instalados atualizam o grafo conforme o workspace ativo muda.

Experimente em 60 Segundos

Instale o Madar com Node.js 20 ou mais recente e execute-o dentro do seu repositório:

npm install -g @lubab/madar
cd your-repository
madar try "how does authentication work?"

O madar try constrói ou reutiliza o grafo local, imprime um primeiro resultado legível para humanos e recomenda o próximo comando de instalação do agente. Ele não modifica seu código-fonte.

Para um exemplo concreto, o workspace de redefinição de senha incluído no Madar contém este caminho:

account-routes.ts
  -> PasswordResetService.requestPasswordReset()
  -> userRepository.saveResetToken()
  -> enqueueResetEmailJob()
  -> sendPasswordResetEmail()

Esse é o tipo de caminho inicial focado que o Madar dá a um agente antes de ele decidir se é necessária qualquer inspeção adicional de arquivos.

Conecte Seu Agente

Escolha o agente que você usa. Para Claude Code:

madar claude install
madar doctor
madar status

Após instalar um perfil, execute madar doctor e madar status. O agente poderá então pedir contexto ao Madar quando você usar prompts normais, como:

How does authentication work?
Why does this endpoint return 403?
Where is the report generated?
What breaks if I change this service?
Add telemetry to this flow.

O Madar suporta estes instaladores locais ao projeto:

Agente	Comando de instalação
Claude Code	madar claude install
Codex CLI	madar codex install
Cursor	madar cursor install
GitHub Copilot	madar copilot install
Gemini CLI	madar gemini install
Aider	madar aider install
OpenCode	madar opencode install

Os detalhes do instalador estão na referência de CLI e MCP. A configuração passo a passo e os testes rápidos estão nos guias rápidos do agente.

Após atualizar o Madar, execute novamente o comando de instalação do seu agente para atualizar o perfil gerenciado. Perfis mais antigos podem não ter atualização automática nem a janela de inicialização mais longa do Codex.

As instalações do Codex criam um bloco MCP com escopo no workspace, com tempos de inicialização e de ferramenta mais longos. O Madar permanece disponível durante a reconciliação inicial; chamadas com suporte de grafo ficam disponíveis assim que o grafo estiver pronto.

A partir de 0.31.3, uma chamada com suporte de grafo feita enquanto o Madar está starting, pending ou reconciling retorna uma resposta estruturada com possibilidade de nova tentativa. O agente deve tentar novamente a mesma solicitação do Madar após o atraso sugerido, em vez de ignorar o Madar ou executar a geração manualmente. Um dono de atualização morto é recuperado automaticamente; apenas estados de grafo com falha, incompletos ou incompatíveis com a política solicitam reparo.

O Que Muda para o Agente

Sem o Madar, um agente de codificação frequentemente começa com buscas amplas por nomes de arquivos, leituras repetidas e suposições sobre qual rota, serviço ou manipulador é responsável pela tarefa.

Com o Madar, a primeira passada pode incluir:

• arquivos prováveis, símbolos exportados, rotas e manipuladores
• trechos diretos relevantes para a pergunta
• imports, chamadas, papéis de framework e repasses de tempo de execução
• uma hipótese estática de caminho de execução quando o grafo suportar uma, não um trace de execução ao vivo
• sinais de atualização do grafo e de completude da indexação
• orientação explícita para responder, responder com ressalva ou verificar um alvo focado

O Madar não substitui seu agente nem impede que ele leia o código. Ele dá ao agente um ponto de partida menor e fundamentado no repositório.

Como Funciona

Your repository
      |
      v
Local Madar graph
      |
      v
Context for the current question
      |
      v
Claude, Codex, Cursor, or another coding agent

1. O Madar indexa arquivos-fonte, símbolos, imports, chamadas, rotas, manipuladores, metadados de framework e documentação selecionada.
2. Uma pergunta seleciona um pacote de contexto limitado, em vez de despejar o repositório inteiro no prompt.
3. A resposta relata força da evidência, cobertura, atualização e se ainda é necessária verificação focada.
4. Perfis MCP instalados acompanham o workspace ativo e atualizam o contexto com suporte de grafo após mudanças relevantes.

O contrato completo de resposta, incluindo estados de recuperação limitada e de capacidade de resposta, está documentado em formato de resposta MCP.

Use o Madar Sem MCP

A CLI pode gerar e inspecionar contexto sem instalar uma integração de agente:

madar generate .
madar summary
madar pack "how does auth work?" --task explain --format text

Por padrão, o madar generate . combina metadados SPI com semânticas legadas comprovadas para JavaScript/TypeScript e usa fallback legado para outras linguagens suportadas. Modos estritos estão na referência de CLI.

Crie um prompt pronto para o provedor:

madar prompt "how does auth work?" --provider claude

Crie um handoff seguro para compartilhar com outra ferramenta de codificação:

madar handoff "add auth telemetry" --task implement --consumer copilot

Grafos gerados e manifestos de indexação permanecem no local de saída do projeto. Veja o tutorial de introdução para um workspace de exemplo reproduzível e saída esperada.

Onde o Madar se Encaixa

O Madar é mais útil quando:

• seu repositório é médio ou grande
• o projeto é principalmente TypeScript ou Node.js
• os agentes continuam reabrindo os mesmos arquivos ou pesquisando pastas não relacionadas
• você faz perguntas de arquitetura, fluxo de execução, revisão ou impacto
• o uso de tokens, latência ou privacidade do repositório local importam

Ajuda menos quando:

• o repositório é pequeno ou a tarefa é óbvia a partir de um único arquivo
• a pergunta depende de comportamento de execução ao vivo que análise estática não pode observar
• o código depende fortemente de padrões dinâmicos ausentes do grafo
• o grafo está desatualizado ou os arquivos-fonte relevantes não puderam ser indexados

O Madar complementa agentes e indexação de IDE. Ele não é uma base de conhecimento hospedada, rastreador de execução, revisor de PR ou scanner de vulnerabilidades.

Local por Design

• Privacidade: a geração de grafo do Madar roda localmente e não requer chave de API. Seu agente de codificação pode ainda enviar prompts ou contexto de arquivos selecionado ao provedor do modelo, dependendo da configuração do agente.
• Arquivos sensíveis: código-fonte de segurança comum permanece indexável, enquanto chaves privadas, .env*, armazenamentos de credenciais e material de segredo não-fonte conhecido são excluídos. Isso é uma política de caminho, não um scanner de segredos em nível de conteúdo.
• Atualização: perfis MCP instalados usam atualização automática. Usuários de CLI podem regenerar manualmente com madar generate .; fluxos estritos podem exigir --require-fresh-context ou --require-fresh-graph.
• Worktrees: execute o Madar e o agente a partir do mesmo worktree Git vinculado. Cada worktree recebe artefatos de grafo isolados fora do checkout; reconecte o servidor MCP após mudar de worktree.
• Telemetria: a telemetria está desabilitada, a menos que você a ative explicitamente. Os controles e o esquema exato de eventos seguro para fonte estão documentados em telemetria.

Trate cada instalação MCP local, hook ou perfil de agente como parte do seu limite de confiança local. O modelo de ameaça MCP documenta esse limite em detalhes.

Evidências e Limites

O Madar publica os prompts, respostas, traces e relatórios seguros para compartilhamento por trás de suas declarações de benchmark. Dois tipos públicos de experimento respondem a perguntas diferentes e não devem ser comparados como se fossem o mesmo teste.

Evidência controlada v0.30

Seis testes de fluxo de execução TypeScript de junho usaram um checkout de código-fonte com perfis de prova específicos para tarefas. Nesses testes controlados, o Madar foi invocado uma vez por linha e os resultados registrados mostraram:

• 3.5x a 18.5x menos chamadas de ferramenta
• 2.2x a 15.6x menos entrada relatada pelo provedor
• 1.65x a 7.09x menor latência

Esses recibos são medições reais do Madar com assistência de perfil. Eles demonstram o que o fluxo pode alcançar quando a evidência correta da tarefa está disponível. Não são evidência de que uma instalação npm não ajustada reproduzirá o mesmo resultado para perguntas arbitrárias, porque os prompts antigos e a recuperação do checkout continham obrigações específicas de benchmark indisponíveis para usuários comuns de pacotes.

Validação de artefato de produção v0.31

As re-execuções de julho removeram essa assistência e usaram o mesmo artefato de pacote @lubab/madar@0.31.0 isolado e descompactado. Quatro de seis repositórios registraram falha de adoção pelo agente: nenhuma chamada MCP atribuível ao Madar ocorreu. Os outros dois invocaram o Madar, mas falharam nas portas rígidas de prompt ou resposta. O resultado correto é zero comparações de desempenho válidas, não seis perdas de produto. Essas re-execuções expõem o trabalho de adoção e completude de resposta; elas não confirmam nem refutam as medições de eficiência controladas anteriores.

Leia o suite de benchmarks e todos os recibos datados ou o mapa mais curto de declarações e evidências.

Versão Atual

Versão atual: 0.32.1.

O 0.32.1 mantém a atualização automática recuperável quando o Git remove um arquivo durante uma reconstrução monitorada e relata uma configuração saudável de cliente único sem exigir integrações opcionais de agente.

O 0.31.4 mantém recibos vinculados ao contexto visível e endurece a manipulação de hooks para Claude/Codex.

O 0.31.3 recupera donos de atualização mortos, aguarda contenção de atualização ao vivo e retorna um sinal de nova tentativa durante reconciliação temporária, em vez de empurrar agentes para ignorar o Madar.

O 0.31.2 mantém a conexão MCP do Codex responsiva enquanto sua atualização automática inicial do grafo é executada, adiciona uma janela explícita de inicialização do Codex de 180 segundos e mantém respostas com suporte de grafo indisponíveis até que o grafo atualizado esteja pronto.

O 0.31.1 reconstruiu o caminho público de integração e esclareceu o que cada experimento de benchmark prova. O comportamento em tempo de execução não foi alterado desde 0.31.0.

O 0.31.0 tornou os grafos de código direcionados por padrão, separou a força da evidência da prontidão de resposta, adicionou recuperação de contexto limitada, tornou a completude da indexação explícita, preservou a política de geração durante atualização automática, isolou artefatos de worktree vinculado e removeu expectativas de benchmark da recuperação de produção.

Leia as notas completas no changelog 0.32.1.

Documentação

Necessidade	Comece aqui
Primeira execução	Introdução
Configuração do agente	Guias rápidos do agente
Ferramentas CLI e MCP	Referência de CLI e MCP
Pacotes de contexto	Conceitos de pacote de contexto
Atualização e atualização automática	Política de atualização automática
Cobertura de indexação	Completude da indexação
Privacidade e confiança no MCP	Modelo de ameaça
Evidências e benchmarks	Declarações e evidências
Roadmap	Roadmap público
Histórico de versões	Changelog

Contribuindo

As contribuições mais úteis agora são testes em repositórios TypeScript e Node.js reais, relatos de contexto ausente, melhorias de confiabilidade Windows/WSL/MCP, detecção de frameworks e exemplos de configuração mais claros.

Abra issues ou pull requests na branch next. Antes de abrir um PR, execute:

npm test
npm run build
npm run release:verify

Veja o grafo completo de contribuidores em Contribuidores do GitHub.

Contribuidores

Obrigado a todos que estão moldando o Madar. A lista abaixo é regenerada automaticamente a cada push para main.

mohanagy

Gunselheli

qorexdevs

zhengjynicolas

jamemackson

Agradecimento especial a @jamemackson pela #54, a primeira funcionalidade contribuída pela comunidade no Madar.

License

MIT. Use, faça um fork e publique.