README_pt-BR.md

 ▄▀▀▀ █▀▀▄ ▄▀▀▄ █▀▀█ █▀▀▀ █▀▀▄ ▄▀▀▄ ▄▀▀▄ ▀█▀
 █ ▀▄ █▄▄▀ █▄▄█ █▄▄█ █▀▀  █▄▄▀ █  █ █  █  █
 ▀▀▀▀ ▀ ▀▀ ▀  ▀ █    ▀▀▀▀ ▀ ▀▀ ▀▀▀▀ ▀▀▀▀  ▀

O que é GrapeRoot?

GrapeRoot é um motor de contexto open-source que fica entre você e seu assistente de codificação com IA. Ele constrói um grafo semântico do seu projeto — arquivos, símbolos, importações, cadeias de chamada — e carrega exatamente o código certo em cada prompt antes que sua IA o veja.

O resultado: sua IA gasta tokens raciocínando, não explorando.

Você executa: dgc /caminho/do/projeto
              ↓
1. Projeto escaneado → grafo semântico construído (arquivos, símbolos, importações)
2. Você faz uma pergunta
3. O grafo identifica os arquivos relevantes → os inclui no contexto
4. A IA recebe sua pergunta + o código certo já carregado
5. Menos turnos, menos tokens, respostas melhores

A economia de tokens se acumula ao longo de uma sessão. O grafo lembra quais arquivos foram lidos, editados e consultados — cada turno fica mais barato.

Resultados

Avaliado em múltiplas bases de código reais (mais de 7.700 arquivos) e mais de 50 prompts de engenharia:

Redução de custo por tipo de tarefa

As economias se acumulam ao longo de uma sessão — um token evitado no turno 3 também evita a refaturação do cache em cada turno subsequente. A qualidade permanece igual ou melhora em cada tipo de tarefa acima.

Metodologia completa e resultados do benchmark: graperoot.dev/benchmarks

Ferramentas de IA Suportadas

Linguagens Suportadas

TypeScript · JavaScript · Python · Go · Swift · Rust · Java · Kotlin · Scala · C# · Ruby · PHP

Instalação

macOS / Linux:

curl -sSL https://raw.githubusercontent.com/kunal12203/Codex-CLI-Compact/main/install.sh | bash
source ~/.zshrc   # ou ~/.bashrc / ~/.profile

Windows (PowerShell):

irm https://raw.githubusercontent.com/kunal12203/Codex-CLI-Compact/main/install.ps1 | iex

Windows (Scoop):

scoop bucket add dual-graph https://github.com/kunal12203/scoop-dual-graph
scoop install dual-graph

Pré-requisitos: Python 3.10+, Node.js 18+ e uma das ferramentas de IA suportadas. O instalador detecta ferramentas ausentes e oferece instalá-las automaticamente.

Uso

Importante: Sempre use dgc (não claude diretamente) para garantir que o servidor MCP esteja em execução.

Claude Code

dgc                                      # escaneia o diretório atual, inicia o Claude
dgc /path/to/project                     # escaneia um projeto específico
dgc /path/to/project "fix the login bug" # inicia com um prompt

OpenAI Codex CLI

dg                              # escaneia o diretório atual
dg /path/to/project             # escaneia um projeto específico
dg /path/to/project "add tests" # inicia com um prompt

Seletor Interativo (novo na v3.9.99)

graperoot          # exibe confirmação de diretório + seletor de ferramenta por teclas de seta
graperoot .        # igual ao anterior, usa o diretório atual
graperoot --version   # exibe a versão atual
graperoot --update    # força atualização automática

Todas as Ferramentas via graperoot

graperoot . --cursor          # Cursor
graperoot . --gemini          # Gemini CLI
graperoot . --opencode        # OpenCode
graperoot . --copilot         # GitHub Copilot
graperoot . --openclaw        # OpenClaw
graperoot . --kilocode        # Kilocode
graperoot . --mimocode        # MiMo Code
graperoot /path --gemini "add tests"   # projeto específico + prompt

Windows

dgc .                          # de dentro do diretório do projeto
dgc "D:\projects\my-app"       # qualquer unidade, qualquer caminho
dg "C:\work\backend"           # Codex CLI
dgc --gemini "D:\projects\app" # Gemini CLI no Windows

Como Funciona

1. Escaneamento do grafo — na primeira execução, o GrapeRoot extrai arquivos, funções, classes e relacionamentos de importação em um grafo local armazenado em .dual-graph/.
2. Recuperação de contexto — cada vez que você faz uma pergunta, o grafo classifica os arquivos mais relevantes e os inclui no prompt antes que sua IA os veja.
3. Memória de sessão — arquivos que você leu, editou ou consultou recebem peso maior nos turnos futuros. O contexto se acumula.
4. Ferramentas MCP — sua IA ainda pode explorar mais fundo por meio de ferramentas com consciência de grafo (graph_read, graph_retrieve, graph_neighbors) quando precisar investigar algo.

Todo o processamento é local. Nenhum código sai da sua máquina.

Dados e Arquivos

Todos os dados ficam em <projeto>/.dual-graph/ (adicionado automaticamente ao .gitignore):

Instalação global em ~/.dual-graph/:

Configuração

Todas opcionais, via variáveis de ambiente:

Atualização Automática

O launcher verifica atualizações a cada execução e se atualiza silenciosamente. Para forçar uma atualização:

graperoot --update

Para desativar a atualização automática:

graperoot --no-auto-update

Para reativar:

graperoot --auto-update

Versão atual: 3.10.16

Telemetria

O GrapeRoot coleta relatórios de falhas anônimos para ajudar a corrigir bugs. O que é enviado: tipo de erro, qual etapa falhou, versão do OS/Python, versão do GrapeRoot. Nunca é enviado: seu código, caminhos de arquivos, nomes de projetos ou dados pessoais.

graperoot --no-telemetry    # disable
graperoot --telemetry       # re-enable

GrapeRoot Pro

O GrapeRoot Pro adiciona funcionalidades avançadas para usuários experientes:

• Modo de tarefa exaustivo — análise profunda de múltiplos arquivos para refatorações complexas
• Detecção de exportações mortas — encontre exportações não utilizadas em todo o projeto
• Localizador de ciclos de dependência — detecta cadeias de importação circulares
• Busca entre projetos — busca semântica em múltiplos repositórios
• Escudo de desfazer — hooks pré-uso de ferramentas que protegem operações destrutivas

Solução de Problemas

"MCP Server Connection Failed"

Sempre use dgc em vez de claude diretamente. O dgc inicia o servidor MCP automaticamente.

# Solução:
claude mcp remove dual-graph
dgc   # registra tudo novamente

Guia completo de solução de problemas

Consulte TROUBLESHOOTING.md ou graperoot.dev/docs.

Contribuição

Os scripts de lançamento (bin/) são open source sob Apache 2.0. PRs são bem-vindos — correções de bugs, suporte a novos assistentes de IA, melhorias de instalação, documentação.

Observação: O motor de grafo (graperoot pip package) é proprietário. Os launchers e ferramentas neste repositório são totalmente open source.

Comunidade

Tem alguma dúvida, encontrou um bug ou quer compartilhar feedback?

Entre no Discord →

Histórico de Estrelas

Licença

Scripts de lançamento e ferramentas neste repositório: Apache License 2.0

O motor de grafo graperoot (PyPI): proprietário. Consulte graperoot.dev/graperoot-pro.