
Controle de versão baseado em grafo semântico para código escrito por IA. Rastreia entidades e relações em vez de diffs de arquivos, permitindo análise de raio de impacto, revisão de shadow merge e contexto de agente com MCP para software gerado por IA confiável.
<p align="center"> <img src="https://assets.kitploit.com/production/public/readmes/12665/55686ad4696e166589300e948ce2ed89f45622266654371a433a31c612829ec8.png" alt="Kin, um repositório de código para agentes de IA e as pessoas que constroem com eles" width="100%" /> </p> <h3 align="center">Uma nova base para o código.</h3> <p align="center"> <a href="https://github.com/firelock-ai/kin/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="Apache-2.0" /></a> <a href="https://github.com/kinlab-ai/kin/releases/latest"><img src="https://img.shields.io/badge/release-latest-6E56CF.svg" alt="Latest release" /></a> </p> **Kin é um repositório de código nativo em grafo para agentes de IA e as pessoas que constroem com eles.** Ele armazena o código-fonte, as relações de código registradas e o histórico versionado como estado do repositório. O grafo é o modelo do repositório, não um índice de busca mantido ao lado de outro repositório. Funções, tipos e as relações entre eles são dados que você faz commit, branch e merge. O código-fonte exato é preservado byte a byte, e as projeções de sistema de arquivos permitem que ferramentas compatíveis continuem funcionando com arquivos comuns. **Beta público.** Experimente o Kin em um projeto real que você conhece bem. Espere arestas ásperas. [Início rápido](#quickstart) · [Documentação](https://github.com/firelock-ai/kin/blob/main/docs/quickstart.md) · [Demonstração no navegador](https://kinlab.ai/demo) <p align="center"> <img src="https://raw.githubusercontent.com/firelock-ai/kin/main/docs/assets/kin-impact-human-bytes.gif" alt="kin impact human_bytes --file crates/kin-cli/src/commands/cache.rs --kind function --depth 1, mostrando seus chamadores diretos no próprio código-fonte do Kin ao lado de uma busca git grep pelo mesmo nome" width="100%" /> </p> Uma estrela ajuda outras pessoas a encontrar o Kin, e as [Discussões](https://github.com/kinlab-ai/kin/discussions) são o lugar para trazer uma dúvida sobre ele. ## Veja o que se conecta Antes de alterar uma função compartilhada, o que mais você deveria inspecionar? O Kin permite consultar seus chamadores registrados e explorar código relacionado. A CLI e o servidor MCP consultam o mesmo grafo, para que você e seu agente possam trabalhar a partir do mesmo registro. <img src="https://assets.kitploit.com/production/public/readmes/12665/43f73477ba09d6aa7a5bb446cadaea9c36981cc1d093faacaa03b9b61346b955.png" alt="Uma consulta kin impact registrada no ripgrep, mostrando entidades relacionadas para uma alteração de assinatura" width="100%" /> *Registrado em um grafo do ripgrep preparado em `e89fff89ac9af12e8d4ce9d5fd07beb408ca730f`. Os artefatos brutos da execução não são públicos. Isto ilustra um fluxo de trabalho, não um benchmark de desempenho.* ## Use a partir do Claude Code, Codex ou Cursor Para o Claude Code: ``` /plugin marketplace add kinlab-ai/kin /plugin install kin@kin ``` Para o [Codex](https://github.com/firelock-ai/kin/blob/main/plugins/kin-codex/README.md#install), adicione o marketplace e instale o plugin, ou deixe que `kin setup --intent agent` grave o servidor MCP em `~/.codex/config.toml` por você. Para o Cursor, adicione o servidor MCP manualmente; consulte [plugins/kin-cursor](https://github.com/firelock-ai/kin/blob/main/plugins/kin-cursor/README.md#install) para o trecho exato. Após a instalação, execute `kin init .` em um clone novo de um projeto que você conhece bem; a skill `kin-setup` orienta você no restante. O Kin não é publicado no crates.io. O crate `kin` lá é um projeto não relacionado. ## Início rápido Comece em um clone novo e completo de um projeto que você conhece bem. O `kin init` lê seu histórico Git sem alterá-lo nem aos seus arquivos rastreados. Ele mantém seu armazenamento fora do seu checkout, em `~/.kin/stores`, e não grava nada no repositório; `kin store path` imprime onde fica o armazenamento de um checkout. Por padrão, ele admite primeiro o commit em checkout, de modo que as perguntas são respondidas assim que essa árvore é lida, e depois importa em segundo plano, com baixa prioridade, todos os commits alcançados pelos seus branches e tags; `kin init --history full` importa todo o histórico de antemão, e `--history none` nunca o importa. A importação do histórico consome tempo, memória e disco que crescem com o histórico, e não com o tamanho do checkout. Antes de começar, o `kin init` verifica a memória e o disco livre e para com os números quando já consegue identificar que a máquina está com recursos insuficientes. **Um clone raso admite apenas seu commit em checkout, e submódulos e Git LFS não são suportados**, e hooks do Git, um checkout esparso ou um merge ou rebase inacabado também interrompem a importação. O `kin init` indica a correção para cada caso, e um clone novo evita a maioria deles. ### 1. Instalação No macOS, Linux e WSL2, um único comando instala o Kin e conecta as ferramentas de codificação com IA que ele encontra. Ele requer Node.js 20 ou mais recente: ```sh npx -y @kinlab/kin setup ``` Em uma máquina sem Node, execute o instalador em vez disso. `get.kinlab.ai` e `get.kinlab.dev` servem o mesmo script: ```sh curl -fsSL https://get.kinlab.dev/install | sh ``` De qualquer forma, recarregue o seu shell como um comando separado, porque a instalação coloca o `kin` em `~/.kin/bin` e adiciona esse diretório ao perfil do seu shell para novas sessões: ```sh exec "$SHELL" -l ``` No Windows x64 nativo, instale a partir do PowerShell com `irm https://get.kinlab.dev/install.ps1 | iex`. Ele instala a CLI `kin` e não conecta ferramentas de codificação de IA, porque o WSL2 continua sendo o caminho recomendado no Windows. A entrada do Windows em [Limites da versão Beta](#beta-limits) descreve o que funciona lá. Nenhuma build nativa para Windows ARM64 é publicada. Em uma máquina ARM64, execute essa linha a partir do PowerShell x64 para instalar a build x86_64 sob emulação, ou use o WSL2. O instalador adiciona `kin` ao PATH do seu usuário, então abra uma nova janela do PowerShell no lugar de `exec "$SHELL" -l` antes do próximo passo. Para outros instaladores ou solução de problemas, consulte o [quickstart completo](https://github.com/firelock-ai/kin/blob/main/docs/quickstart.md#1-install). ### 2. Inicialize o repositório No novo prompt, clone um repositório com o Kin: ```sh kin clone https://github.com/pallets/itsdangerous ``` Ou inicialize um que você já tenha, substituindo o caminho abaixo: ```sh cd /path/to/your/repository && kin init . && kin overview && kin status ``` Ambos terminam com o próximo comando a executar, uma pergunta `kin refs` sobre uma função nesse repositório. Também ligam o Codex CLI e o Grok CLI a ele quando você permitiu isso na configuração, porque esses clientes mantêm uma entrada que nomeia um repositório. O Windows PowerShell 5.1 não tem `&&`, então no Windows nativo execute os mesmos comandos um de cada vez e pare se algum falhar: ```powershell cd C:\path\to\your\repository kin init . kin overview kin status ``` `kin overview` mostra as entidades que o Kin importou. `kin status` mostra o que foi admitido e o estado da árvore de trabalho em relação a isso. `kin graph status` relata o grafo de consultas ativo do daemon e a cobertura. Alterações não commitadas e não rastreadas não fazem parte do histórico Git importado; `kin init` relata o que foi deixado de fora. ### 3. Faça uma pergunta que você possa verificar Procure algo que você já sabe que está no código: ```sh kin locate "<something you already know is in this repository>" ``` Substitua `ExactEntityName` abaixo por um símbolo do resultado: ```sh kin refs ExactEntityName kin trace ExactEntityName kin impact ExactEntityName ``` `refs` retorna referências registradas, `trace` traz contexto próximo e `impact` explora efeitos potenciais através do grafo. Verifique os resultados em relação à fonte. ### 4. Suas ferramentas de codificação com IA e busca semântica O `kin setup` já perguntou antes de conectar as ferramentas de codificação com IA que encontrou, e as conectou se você disse sim. Não há etapa separada de vinculação. Depois de instalar outra ferramenta, execute `kin setup` novamente, e `kin setup status` mostra o que está conectado. No Windows, conecte as ferramentas de IA dentro do WSL2. `kin runtime status --json` verifica a instalação compartilhada da CLI e do daemon, incluindo sua identidade exata de origem. Comandos normais recusam pares incompatíveis; builds de desenvolvimento usam estado isolado. Consulte [instalação do runtime](https://github.com/firelock-ai/kin/blob/main/docs/runtime-installation.md). A recuperação por grafo e lexical funciona sem um modelo. Embeddings e reranking são opcionais, e seus provedores de modelo têm como padrão `none`. Builds padrão da CLI e do daemon incluem suporte externo a modelos HTTP. Modelos integrados exigem um build com inferência local opcional habilitada. Para construir um índice de embeddings usando um endpoint compatível com OpenAI que você opera: ```sh KIN_MODEL_EMBEDDINGS_PROVIDER=external \ KIN_MODEL_EMBEDDINGS_BASE_URL=http://localhost:1234/v1 \ KIN_MODEL_EMBEDDINGS_MODEL=your-served-embedding-model kin embed ``` Os endpoints de modelo recebem o texto da entidade selecionada necessário para a sua etapa. As [configurações de modelo](https://github.com/firelock-ai/kin/blob/main/docs/env-vars.md) descrevem provedores, identidades de modelo e nomes de variáveis de ambiente de credenciais. O Kin suporta Claude Code, Codex, Cursor, Gemini e outros clientes MCP. Use `kin setup --intent editor` para o VS Code. O Kin também inclui `kin agent run` para endpoints de modelo compatíveis com OpenAI locais ou hospedados. [Configuração do cliente](https://github.com/firelock-ai/kin/blob/main/docs/readme-reference.md#works-with-your-agent) · [Ferramentas MCP](https://github.com/firelock-ai/kin/blob/main/docs/mcp-tools.md) · [Agente integrado](https://github.com/firelock-ai/kin/blob/main/docs/cli-reference.md#kin-agent) Importações locais, armazenamento e consultas ao grafo são executados na sua máquina. A instalação do Kin requer acesso à rede; o caminho padrão de recuperação do grafo não requer download de modelo. Quando um provedor de embeddings é selecionado, as consultas reportam a sua cobertura vetorial e quaisquer lacunas. ## Revisar uma alteração Após executar `kin init` no branch Git que deseja revisar, compare SHAs de commit explícitos com `main`: ```sh kin review shadow "$(git rev-parse main)..$(git rev-parse HEAD)" ``` O relatório retorna `PASS`, `NEEDS ATTENTION` ou `WOULD BLOCK`, com impacto derivado do grafo e evidências de suporte. **É consultivo:** não bloqueia um merge nem altera o estado do grafo. A autoria é declarada, não verificada de forma independente. ## Use o Kin com ou sem Git O Kin tem seus próprios commits, branches, merges, diffs e histórico, inclusive em repositórios sem Git por baixo. Repositórios Git existentes podem ser importados, e fluxos de trabalho suportados podem exportar um novo repositório Git. [Passo a passo do controle de versão nativo](https://github.com/firelock-ai/kin/blob/main/docs/readme-reference.md#version-control-without-git) · [Interoperabilidade com Git e limites de exportação](https://github.com/firelock-ai/kin/blob/main/docs/readme-reference.md#how-kin-relates-to-git) ## Limites da versão beta **A cobertura é incompleta.** As linguagens suportadas são analisadas em entidades e relacionamentos; os demais arquivos permanecem disponíveis como conteúdo e histórico. Um resultado vazio não prova que não há chamadores ou dependências. Continue usando seu compilador, testes e revisão. Consulte [suporte a linguagens](https://github.com/firelock-ai/kin/blob/main/docs/language-support.md). **A compatibilidade varia.** Os arquivos de release não incluem a projeção de sistema de arquivos `kin-vfs` obsoleta, portanto não há projeção transparente com que contar. Verifique as [notas de plataforma](https://github.com/firelock-ai/kin/blob/main/docs/readme-reference.md#platform-and-maturity) para saber o que cada plataforma suporta. **Faça backup do estado exclusivo do Kin.** Commits, branches, revisões e specs que você registra com o Kin ficam no armazenamento Kin do repositório, não no Git. Excluir o armazenamento e reimportar do Git não os recupera, então execute `kin backup create` primeiro. `kin store prune` exclui armazenamentos apenas quando você passa `--yes`, pelo mesmo motivo. Leia as [notas de importação, recuperação e atualização](https://github.com/firelock-ai/kin/blob/main/docs/readme-reference.md#what-is-real-today-and-what-is-beta). **Windows.** O suporte nativo ao Windows x86_64 é inicial. A admissão de repositório funciona: `kin init` importa um repositório Git e publica a autoridade do grafo, e consultas de grafo, lexicais e com suporte de daemon respondem nativamente. A prova de instalação ponta a ponta também executa a configuração do agente no Windows nativo e obtém respostas com suporte de grafo do servidor MCP instalado. A projeção transparente de sistema de arquivos não é distribuída no Windows, e os fluxos de trabalho de revisão ainda não foram testados nele, então o WSL2 continua sendo o caminho recomendado para a experiência completa do Kin. ## Por que construí o Kin Eu continuava vendo agentes de programação juntarem partes de uma base de código que já havíamos trabalhado. Depois eu fazia uma versão desse trabalho para revisar suas mudanças. Comecei a me perguntar por que mais dessa compreensão estrutural não fazia parte do próprio repositório. É isso que estou construindo com o Kin. Troy ## Saiba mais e contribua [Referência da CLI](https://github.com/firelock-ai/kin/blob/main/docs/cli-reference.md) · [Arquitetura e limites detalhados](https://github.com/firelock-ai/kin/blob/main/docs/readme-reference.md) · [Contribuindo](https://github.com/firelock-ai/kin/blob/main/CONTRIBUTING.md) · [Issues](https://github.com/kinlab-ai/kin/issues/new/choose) · [Segurança](https://github.com/firelock-ai/kin/blob/main/SECURITY.md) O Kin e sua stack local, incluindo o [kin-db](https://github.com/kinlab-ai/kin-db), são [Apache-2.0](https://github.com/firelock-ai/kin/blob/main/LICENSE). O [KinLab](https://kinlab.ai) é o produto hospedado proprietário separado. A integração de repositórios públicos ainda está em desenvolvimento.