davidw-philips/cgraph

CodeGraph (codegraph)

codegraph constrói e mantém um grafo de conhecimento local (SQLite) de auto-sincronização de cada símbolo, aresta de chamada e dependência em uma base de código. Uma vez inicializado, seu agente responde perguntas estruturais diretamente do grafo através da ferramenta MCP codegraph_explore — em uma única chamada, com zero leituras de arquivo — em vez de um loop de grep/leitura.

Quando Usar

• Respondendo "Como X funciona?", "Como X alcança Y?", ou analisando uma área desconhecida do repositório ativo.
• Encontrando chamadores/chamados de uma função, rastreando caminhos de chamada, ou avaliando o raio de impacto de uma mudança.
• Iniciando, gerenciando ou parando daemons em segundo plano do CodeGraph e processos de ambiente.
• Navegando e mantendo índices do grafo em branches Git, rebases e worktrees Git.
• Qualquer pergunta que você normalmente responderia com grep ou lendo vários arquivos para reconstruir a estrutura manualmente.

NÃO use para um repositório que ainda não tenha um índice .codegraph/ (execute codegraph init primeiro) ou para repositórios externos/públicos que você não indexou localmente — prefira a habilidade deepwiki para esses.

Verificação Pré-voo

command -v codegraph || Get-Command codegraph

Se estiver faltando, veja INSTALL.md, ou instale diretamente com:

# macOS / Linux — não requer Node.js, inclui seu próprio runtime
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

# Windows (PowerShell) — não requer Node.js
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex

Isso é o suficiente para a maioria dos ambientes — pule diretamente para Fluxo de Trabalho & Inicialização abaixo. Use os scripts/ incluídos (veja INSTALL.md) apenas se você precisar especificamente do caminho de instalação via npm ou da API de biblioteca Node do CodeGraph.

Fluxo de Trabalho & Inicialização

1. Configuração Única por Máquina

Conecte o CodeGraph a este agente (confirma antes de alterar qualquer coisa):

codegraph install

2. Configuração Inicial por Projeto

Construa o grafo para o projeto ativo (cria .codegraph/codegraph.db; executa o índice inicial completo):

cd seu-projeto
codegraph init

3. Inicialização Diária (Ao Começar a Trabalhar)

Você não precisa iniciar manualmente um daemon ou serviço em segundo plano antes de trabalhar:

• Sessões de Agente (MCP): Seu host de IA (VS Code Copilot, Claude Code, etc.) inicia o servidor MCP automaticamente via codegraph serve --mcp. O servidor se conecta ou cria um daemon em segundo plano sob demanda, completo com um observador do sistema de arquivos do SO.
• Verificar Saúde: Execute codegraph status para verificar a saúde do índice, contagem de símbolos/arestas e itens de sincronização pendentes.
• Sincronização de Atualizações: Se arquivos foram alterados enquanto o agente estava fechado (por exemplo, commits puxados), execute codegraph sync para uma atualização incremental rápida e imediata.

4. Consultando a Estrutura

Seu agente chama a ferramenta MCP codegraph_explore automaticamente uma vez conectada. A mesma funcionalidade está disponível no shell:

codegraph explore "como X alcança Y"
codegraph callers algumaFuncao
codegraph callees algumaFuncao
codegraph impact algumSimbolo

Ciclo de Vida do Ambiente & Daemon

O CodeGraph executa um daemon em segundo plano (modo daemon) por padrão, para que várias sessões de cliente compartilhem um único observador, cache e manipulação do SQLite.

Desligando Daemons

• Parada Interativa: Execute codegraph daemon (ou codegraph daemons). Selecione o daemon do projeto (flutua para o topo) ou escolha parar todos os daemons.
• Parada Programada / Não Interativa: Os daemons registram seu PID em <raiz_do_projeto>/.codegraph/daemon.pid. Encerre esse ID de processo diretamente (ou inspecione ~/.codegraph/daemons/<hash>.json).
• Limpando Locks Obsoletos: Se um processo falhar ou for encerrado abruptamente, limpe locks obsoletos e artefatos de daemon órfãos com:

  codegraph unlock
  

Alternadores de Ambiente (Daemon & Observador)

• Modo Direto (Sem Daemon): Defina CODEGRAPH_NO_DAEMON=1 para forçar cada sessão MCP e CLI a executar como um processo independente e autocontido, em vez de se conectar a um daemon compartilhado.
• Desabilitar Observador de Arquivos: Defina CODEGRAPH_NO_WATCH=1 (ou use a flag --no-watch) para desabilitar o observador de sistema de arquivos ao vivo. Recomendado em sistemas de arquivos lentos (unidades WSL2 /mnt/, montagens de rede) ou configurações com bateria limitada.

Descomissionamento / Desinicialização

• Remover do Projeto: Execute codegraph uninit para deletar o índice .codegraph/ e remover hooks de sincronização Git (--force ignora o prompt).
• Remover da Máquina: Execute codegraph uninstall (ou codegraph uninstall --keep-cli para manter o binário CLI).

Trabalhando com Branches & Worktrees do Git

Alternância de Branch Git (Árvore de Trabalho Única)

• Sincronização Baseada em Sistema de Arquivos: O CodeGraph rastreia caminhos de arquivo e hashes de conteúdo no SQLite, não git status. Alternar branches (git switch <branch> ou git checkout <branch>) modifica arquivos no disco; o observador de arquivos detecta automaticamente as mudanças e sincroniza incrementalmente o índice em cerca de 2 segundos.
• Sincronização Manual: Se o observador foi desabilitado ou estava inativo durante o checkout, execute codegraph sync para uma atualização incremental rápida.
• Rebases / Reconstruções Maiores: Após um rebase massivo ou merge de branch com muitos conflitos, force uma reconstrução limpa do índice com:

  codegraph index --force
  

• Hooks de Sincronização Git (Quando o Observador Está Desligado): Se CODEGRAPH_NO_WATCH=1 estiver definido, o CodeGraph pode instalar hooks post-commit, post-merge e post-checkout que invocam codegraph sync em segundo plano automaticamente após alternâncias de branch.

Worktrees Git & O Perigo do "Índice Emprestado"

• Descoberta do Índice: O CodeGraph descobre .codegraph/ subindo pelos diretórios pai a partir do diretório de trabalho atual.
• O Perigo: Ao usar worktrees Git (por exemplo, git worktree add ../feature-worktree feature), se o worktree não tiver seu próprio diretório .codegraph/, o CodeGraph sobe e se liga ao índice .codegraph/ do checkout principal. Consultas no worktree retornarão símbolos e fonte do branch do checkout principal, perdendo alterações específicas do worktree!
• Detecção de Incompatibilidade: O CodeGraph verifica detectWorktreeIndexMismatch comparando git rev-parse --show-toplevel contra indexRoot via git rev-parse --git-common-dir. Quando um worktree empresta o índice principal, o CodeGraph emite avisos em codegraph status e nas ferramentas de consulta MCP.
• A Regra de Ouro para Worktrees: Sempre execute codegraph init (ou codegraph init -i) dentro de cada diretório de worktree. Cada worktree deve ter seu próprio diretório .codegraph/ dedicado para indexar seu branch independentemente.
• Isolamento de Diretório Personalizado: Defina CODEGRAPH_DIR (por exemplo, export CODEGRAPH_DIR=.codegraph-worktree) se for necessário um nome de pasta de índice personalizado ou isolamento (por exemplo, separar checkouts do Windows e WSL2).

Regras

• Confie nos resultados do grafo — ele se mantém sincronizado via um observador de arquivos (debounce de 2 segundos após um salvamento); não verifique novamente com grep.
• Trate o código-fonte retornado por codegraph_explore como já lido; não reabra o mesmo arquivo com a ferramenta Read.
• Consulte apenas um projeto que tenha um índice .codegraph/. Um caminho sem ele retorna uma orientação clara para usar ferramentas internas — a indexação continua sendo uma decisão deliberada, não automática.
• Em worktrees Git, verifique com codegraph status se o worktree tem seu próprio índice local em vez de emprestar o índice da árvore principal.
• Prefira codegraph_explore (ou codegraph explore da CLI) em vez das ferramentas ocultas mais restritas (codegraph_node, codegraph_search, codegraph_callers, codegraph_callees, codegraph_impact, codegraph_files, codegraph_status) — tudo o que elas retornam já chega embutido no codegraph_explore.

Veja INSTALL.md para opções de instalação, incluindo os scripts de verificação/instalação do Node.js incluídos em scripts/, necessários apenas para o caminho de instalação via npm ou incorporação de biblioteca.