GitHits

O MCP GitHits dá aos agentes de IA acesso a busca de código aberto, documentação de pacotes, exemplos do mundo real, metadados de dependências, changelogs e contexto de vulnerabilidades para melhores decisões de desenvolvimento de software.

GitHub

115

Documentação

GitHits

GitHits CLI

A camada de contexto de código para agentes de codificação de IA.

Website · Documentação · Issues

O GitHits conecta agentes de codificação de IA a evidências de código aberto público em todo o ciclo de vida completo do desenvolvimento de software: descoberta, planejamento, pesquisa, implementação, depuração e manutenção.

A CLI executa um servidor MCP local que sua ferramenta de codificação inicia sob demanda. Os agentes podem então pesquisar pacotes indexados e código-fonte de repositórios, ler arquivos exatos e páginas de documentação, inspecionar a saúde de pacotes, comparar atualizações de dependências e encontrar exemplos citados de código-fonte de projetos reais de código aberto quando o conhecimento do modelo e o contexto do repositório local não são suficientes.

Quer usar o GitHits como parte do seu harness de agente ou fábrica de software? Confira nossa documentação da API pública.

Início Rápido

npx githits@latest init

init faz seu login, detecta ferramentas de codificação compatíveis e configura o GitHits para as ferramentas que você selecionar. Ele usa o MCP stdio local, exceto para o Cursor, cuja configuração direta usa o MCP remoto hospedado.

A configuração automática atualmente suporta Claude Code, Cursor, Windsurf, VS Code / Copilot, Cline, Claude Desktop, Codex CLI, Pi, Gemini CLI, Google Antigravity, OpenCode, Hermes Agent, Zed, Junie, Qwen Code, Kiro, Kilo Code, Factory Droid e Amazon Q CLI.

Após a configuração, abra seu agente de codificação e trabalhe normalmente. Muitos agentes chamam o GitHits quando precisam de contexto com base em código-fonte. Se seu agente começar a adivinhar, solicite diretamente:

Use GitHits Code Navigation to inspect npm:express. Find how middleware
errors are handled, read the relevant source, and explain the fix before
editing code.

O Que o GitHits Adiciona

O GitHits é projetado para o ponto em que um agente precisa de evidências do ecossistema de código aberto mais amplo, não apenas da memória do modelo ou do contexto do repositório local:

Capacidade	Ferramentas MCP	Comandos CLI
Orientação de ferramentas	`quick_start`	—
Exemplos de código	`get_example`	`githits example`
Navegação de inventário	`list`	`githits list`
Pesquisa de código e documentação	`search`, `search_status`, `grep`	`githits search`, `githits search-status`, `githits grep`
Leitura de arquivos de código-fonte ou seções de documentação	`read`	`githits read <target> [path]`
Inspeção de pacotes	`pkg_info`, `pkg_vulns`, `pkg_deps`, `pkg_changelog`, `pkg_upgrade_review`	`githits pkg ...`

Use o GitHits quando seu agente precisar:

descobrir, planejar ou pesquisar como projetos OSS resolvem um problema vago ou erro desconhecido
encontrar artefatos anteriores amplos ou exemplos raros de agulha no palheiro em repositórios
inspecionar código-fonte, testes, símbolos ou documentação de um pacote ou repositório conhecido
verificar como uma dependência realmente se comporta antes de alterar o código
depurar stack traces que apontam para código de terceiros
revisar saúde de pacotes, licenças, vulnerabilidades, dependências e changelogs
comparar atualizações de dependências usando evidências factuais

Exemplos

Encontre artefatos anteriores em código aberto:

npx githits@latest example "HTTP retries with exponential backoff in Python"

Pesquise código, documentação e símbolos indexados de uma dependência:

npx githits@latest search "router middleware" --in npm:express
npx githits@latest search '"body parser" OR multer' --in npm:express --source docs
npx githits@latest search "debounce" --in npm:lodash --source symbol

Leia e faça grep no código-fonte da dependência sem clonar:

npx githits@latest code files npm:express lib
npx githits@latest code read npm:express lib/router/index.js --lines 120-200
npx githits@latest grep 'router\.use' npm:express --path-prefix lib/

Inspecione a saúde do pacote e evidências de atualização:

npx githits@latest pkg info npm:express
npx githits@latest pkg vulns npm:lodash@4.17.20 --severity high
npx githits@latest pkg deps npm:express@4.18.2 --depth 2
npx githits@latest pkg changelog npm:express --from 4.18.2 --to 5.2.1
npx githits@latest pkg upgrade-review npm:zod@4.3.6 --to 4.4.3

Navegue e leia a documentação do pacote:

npx githits@latest docs list npm:express
npx githits@latest docs read <docs-read-target> --lines 20-80

Diffs de Código-Fonte

githits code diff e a ferramenta MCP pública code_diff estão disponíveis por padrão. Compare versões exatas de pacotes ou refs de repositórios públicos, por exemplo:

githits code diff npm:express 5.2.0..5.2.1 --stat
githits code diff npm:express 5.2.0..5.2.1 --patch -- 'lib/**/*.js'

Diffs de pacotes abrangem todo o repositório, a menos que sejam restringidos por um glob de caminho explícito. Diffs brutos não comprovam segurança de atualização. Veja diff de código-fonte para limites, segurança de patch e endereçamento suportado. A disponibilidade do MCP hospedado exige a adoção do pacote @githits/mcp lançado e a implantação.

Resolução de Alvos

resolve_target / githits resolve transforma um nome de pacote, repositório ou site de documentação público vago, com erro de digitação ou ambíguo em alvos canônicos classificados. Está disponível por padrão na CLI, no MCP local e no pacote MCP público. Alvos canônicos ignoram a resolução; identidade incerta exige uma escolha explícita. Veja resolução de alvos para regras de continuação e limites. O MCP hospedado e os plugins o recebem após o pacote lançado ser adotado e implantado.

Ferramentas Experimentais

research / githits research (alias githits ask) responde perguntas fundamentadas com fontes. Está oculta e desabilitada por padrão e disponível através da CLI local e do MCP stdio local após opt-in de configuração do host:

# macOS/Linux: ~/.config/githits/config.toml
# Windows: %APPDATA%\githits\config.toml
[experimental]
tools = true

Reinicie o agente de codificação após alterar a configuração. Veja Ferramentas experimentais para configuração e uso.

Fontes Suportadas

O GitHits funciona com alvos de pacotes e repositórios, como:

especificações de pacotes: npm:react, npm:react@18.2.0, pypi:requests, crates:serde
repositórios GitHub: https://github.com/expressjs/express, github:expressjs/express@main

A inspeção de pacotes suporta npm, PyPI, Hex, Crates, NuGet, Maven, Packagist, RubyGems, Go, Swift, vcpkg e Zig. Dados de avisos não estão disponíveis para vcpkg e Zig; o suporte a gráficos de dependências varia por registro.

Filtragem de Licenças

A pesquisa de exemplos de código suporta filtragem de licenças:

strict é o padrão e filtra repositórios com licenças copyleft ou não declaradas
custom usa sua lista de bloqueio de conta configurada em githits.com
yolo desabilita a filtragem de licenças

npx githits@latest example "async file reading" --lang python --license strict

Autenticação

A configuração local normal é tratada por:

npx githits@latest init

Para login manual:

npx githits@latest login

O OAuth do navegador é recomendado para desenvolvimento local. As credenciais são armazenadas no chaveiro do sistema por padrão e atualizadas automaticamente. Flags úteis:

init --no-browser ou login --no-browser imprime a URL de login em vez de abrir um navegador
init --port <port> ou login --port <port> corrige a porta de callback do loopback
login --force re-autentica mesmo se você já estiver logado

O callback OAuth sempre escuta na máquina onde o GitHits está em execução. Quando o GitHits roda via SSH e o navegador roda localmente, encaminhe a porta selecionada da máquina do navegador:

ssh -N -L 8765:127.0.0.1:8765 user@remote-host

Com esse túnel aberto, execute o GitHits na máquina remota usando a mesma porta:

npx githits@latest init --no-browser --port 8765

Abra a URL impressa pelo GitHits no navegador local. Substitua user@remote-host pelo destino SSH que você normalmente usa. As mesmas flags funcionam com githits login após a configuração.

O OAuth do navegador é interativo. Para CI e outros ambientes não supervisionados, forneça GITHITS_API_TOKEN através do gerenciador de segredos do ambiente.

Prompts do Chaveiro e Armazenamento de Arquivos

O GitHits usa o chaveiro do sistema por padrão porque as credenciais OAuth incluem um token de atualização. No macOS, isso significa Acesso às Chaves; no Windows, significa Gerenciador de Credenciais; no Linux, significa o Secret Service ou backend de chaveiro disponível.

Se o macOS mostrar um prompt como "githits quer acessar ... no seu chaveiro", escolha Sempre Permitir quando você confiar na CLI githits instalada. O GitHits não pode personalizar esse prompt do sistema operacional; ele é gerado pelo macOS.

O GitHits também grava um pequeno arquivo de metadados não secretos para que verificações de inicialização recentes não precisem ler o chaveiro. O chaveiro só é lido quando o GitHits precisa do token, por exemplo, durante uma chamada de ferramenta, atualização de token, githits auth status ou uma verificação de login após os metadados estarem desatualizados ou expirados.

Se seu agente continuar mostrando prompts do chaveiro mesmo após Sempre Permitir, alterne o armazenamento OAuth para o modo de arquivo:

# macOS/Linux: ~/.config/githits/config.toml, or $XDG_CONFIG_HOME/githits/config.toml
# Windows: %APPDATA%\githits\config.toml
[auth]
storage = "file"

O diretório de configuração pode estar vazio até você criar config.toml ou o GitHits gravar metadados de autenticação. Instalações macOS mais antigas podem ter usado ~/Library/Application Support/githits; o GitHits ainda lê esse local para migração, mas a nova configuração de autenticação e o armazenamento de arquivos usam ~/.config/githits.

Você também pode optar por um processo:

GITHITS_AUTH_STORAGE=file githits login --force

O modo de arquivo armazena credenciais OAuth como arquivos JSON no diretório de configuração do GitHits. Os arquivos são gravados com permissões privadas onde a plataforma suporta, mas não são criptografados. Qualquer processo que possa ler arquivos como seu usuário do sistema operacional pode ser capaz de ler os tokens.

Use o modo de arquivo apenas em máquinas onde você confia no acesso da conta de usuário local. Para CI e automação, prefira GITHITS_API_TOKEN em vez de OAuth do navegador.

Inspecione o estado de autenticação e runtime com:

npx githits@latest auth status
npx githits@latest doctor

Veja a documentação de autenticação para comportamento do chaveiro, modo de armazenamento de arquivos, configuração de CI e solução de problemas.

Configuração Manual do MCP

Se sua ferramenta de codificação não for configurada automaticamente por init, adicione o GitHits à sua configuração MCP manualmente:

{
  "mcpServers": {
    "githits": {
      "command": "npx",
      "args": ["-y", "githits@latest", "mcp", "start"]
    }
  }
}

Sua ferramenta executa este comando via stdio. Nenhum daemon em segundo plano ou instalação global é necessário.

Para remover a configuração gravada por init:

npx githits@latest uninstall

Isso remove a configuração MCP do GitHits e as orientações gravadas por init, enquanto preserva as credenciais armazenadas. Execute npx githits@latest logout separadamente para remover credenciais. O formulário de compatibilidade npx githits@latest init uninstall aceita as mesmas opções --yes, --project e --keep-guidance.

Configuração do Projeto

Para configuração MCP local do projeto, execute:

npx githits@latest init --project

A configuração do projeto está disponível apenas para ferramentas com suporte MCP local de projeto verificado. A configuração do projeto não contém segredos, mas pode ser commitada como outra configuração de ferramentas, então revise os arquivos gerados antes de adicioná-los ao controle de versão.

A configuração não interativa segura para agentes usa descoberta em etapas e instalação explícita:

npx githits@latest init --detect-agents --json
npx githits@latest init --install-agents cursor,codex-cli

Empacotamento de Plugins e Extensões

O repositório e o pacote publicado fornecem os assets de plugins e extensões usados por hosts compatíveis. Instalações baseadas em Git também mantêm os symlinks de arquivos de contexto (CLAUDE.md e GEMINI.md) para o AGENTS.md canônico:

.plugin/plugin.json
.claude-plugin/plugin.json
.claude-plugin/marketplace.json
.codex-plugin/plugin.json
.cursor-plugin/plugin.json
.mcp.json
gemini-extension.json
plugin.json (Google Antigravity)
mcp_config.json (Google Antigravity)
AGENTS.md
CLAUDE.md
GEMINI.md
skills/

A árvore de skills raiz é compartilhada por todos os hosts suportados. Cada instalação de plugin e extensão usa o MCP remoto hospedado, incluindo Claude, Codex, Cursor, Gemini CLI, Google Antigravity e VS Code/GitHub Copilot OpenPlugin. A configuração direta githits init é um caminho separado: ela instala configurações stdio locais para ferramentas suportadas, exceto Cursor, que permanece apenas remoto. A raiz do repositório é um plugin nativo do Antigravity através de plugin.json, mcp_config.json e da árvore compartilhada skills/. Os manifests gerados são atualizados com bun run plugins:generate e validados com bun run plugins:check.

O init guiado instala as quatro skills canônicas (githits-code, githits-mcp, githits-onboarding e githits-package) apenas para agentes selecionados. Agentes com suporte a skills compartilhadas usam ~/.agents/skills/ no escopo do usuário ou .agents/skills/ no escopo do projeto; agentes apenas nativos usam seu diretório de skills nativo verificado. Agentes compatíveis que leem uma raiz compartilhada podem descobrir essas skills. Uma execução guiada posterior repara skills ausentes, e a migração remove apenas o githits-mcp/SKILL.md histórico do Cline ou Junie após o conjunto compartilhado completo ser verificado.

Para instalações do marketplace do Claude Code:

claude plugin marketplace add githits-com/githits-cli
claude plugin install githits@githits-plugins

Para instalações de extensão do Gemini CLI:

gemini extensions install https://github.com/githits-com/githits-cli

Referência de Comandos

githits init             Connect GitHits to your coding agents
githits uninstall        Remove GitHits MCP configuration and guidance
githits init uninstall   Compatibility alias for `githits uninstall`
githits login            Sign in to your GitHits account
githits logout           Remove stored credentials
githits mcp              Show setup instructions or start the local MCP server
githits mcp start        Always start the local MCP server over stdio
githits example          Find real-world implementations from open source
githits doctor           Diagnose configuration and auth state
githits resolve          Resolve a fuzzy name to canonical targets
githits settings         View and update preferences, privacy, and terms
githits search           Explore repository code, dependencies, docs, and symbols
githits search-status    Check the status of a previous indexed search
githits code             List, read, grep, or diff source
githits pkg              Inspect package metadata, vulnerabilities, deps, and changelogs
githits docs             Browse and read package documentation
githits auth             Manage authentication
githits auth status      Show authentication status

Referência completa da CLI: https://docs.githits.com/cli/commands

Variáveis de Ambiente

A maioria dos usuários não precisa de variáveis de ambiente. Estas são as substituições comuns para CI, armazenamento de autenticação e diagnósticos locais:

Variável	Finalidade	Padrão
`GITHITS_API_TOKEN`	Token de API para autenticação	não definido
`GITHITS_AUTH_STORAGE`	Substituir o modo de armazenamento OAuth: `keychain` ou `file`	`keychain`
`GITHITS_DISABLE_UPDATE_CHECK`	Desativar avisos de atualização da versão mais recente do npm	não definido
`GITHITS_TELEMETRY`	Emitir diagnósticos de tempo locais para stderr	não definido

Referência completa: https://docs.githits.com/cli/environment-variables

Estrutura do Código-Fonte

Este repositório contém a CLI do GitHits e o pacote MCP reutilizável:

src/ - Comandos da CLI, autenticação local, fluxos de configuração e inicialização local do MCP stdio
packages/mcp/ - Pacote público @githits/mcp para APIs de servidor MCP neutras em transporte, registro de ferramentas, instruções e auxiliares de teste de fumaça
packages/core-internal/ - Implementação de workspace compartilhada usada pela CLI e pelo pacote MCP
docs/ - Notas de implementação e diretrizes para contribuidores
scripts/ - Validação de pacotes, testes de fumaça e utilitários de desenvolvimento

Consulte CHANGELOG.md para alterações publicadas, trabalho pendente e o impacto atual na versão do pacote.

Desenvolvimento

Requisitos:

Node.js ^20.18.1 || >=22.13.0
Bun
Python 3.11 ou posterior para os testes do avaliador de atualização de dependências (python no Windows, python3 em outros lugares)

Comandos comuns:

bun install
bun run dev --help
bun test
bun run typecheck
bun run build

Ao alterar ferramentas MCP, comandos da CLI, formatadores compartilhados, envelopes de autenticação/erro ou comportamento de paridade MCP/CLI, execute também os conjuntos de testes de fumaça relevantes:

bun run smoke:mcp
bun run smoke:cli

O CI também verifica o produto compilado sem credenciais ou chamadas de backend ao vivo. Execute as mesmas verificações localmente após bun run build:

bun run smoke:cli:built
bun run smoke:mcp:built

O harness permanece no Bun, enquanto os subprocessos do produto executam dist/cli.js com node de PATH. O CI provisiona esse runtime a partir de .node-version.

Ao alterar instruções MCP, descrições de ferramentas ou comportamento voltado ao agente, use as avaliações de agente direcionadas descritas em eval/agentic/README.md:

bun run agent:e2e

Licença

Apache-2.0