Kith

Início rápido · Demonstração · Integrações · CLI e API · Contribuir

Coordenação local para agentes de programação que cooperam entre si.

Reivindique trabalho, isole alterações com worktrees do Git, compartilhe recursos locais e verifique a integração — sem um serviço hospedado.

Um agente altera uma interface enquanto outro constrói sobre ela. Dois agentes editam o mesmo arquivo. Worktrees separadas ainda competem por uma porta de servidor de desenvolvimento ou por uma instalação de pacote.

O Kith oferece aos agentes cooperantes um estado local compartilhado: quem é dono de uma tarefa, quais arquivos estão reivindicados e quais comandos precisam esperar. Os agentes usam seu servidor MCP; os comandos de CLI dão suporte à inspeção e manutenção local. A coordenação fica em SQLite na sua máquina; o próprio Kith não precisa de serviço hospedado nem de chave de API de modelo.

O que o Kith faz

Necessidade	O Kith oferece
Evitar sobreposição de tarefas	Reivindicações com escopo e respostas de conflito
Dar aos agentes arquivos de trabalho separados	Worktrees do Git com uma etapa de integração explícita
Verificar o trabalho antes da integração	O comando de verificação do seu projeto
Compartilhar ferramentas locais	Reservas de porta e mutexes de comandos supervisionados
Ver o que está acontecendo	Estado de sessão/tarefa via kith status e MCP

O Kith se encaixa em fluxos de trabalho em que você já inicia vários agentes de programação e quer que eles se coordenem. Ele não escolhe modelos, não escreve prompts nem inicia uma frota por você. As worktrees separam arquivos; o Kith acrescenta propriedade compartilhada e coordenação de recursos.

O contrato de confiabilidade define propriedade, verificação, recuperação e limites de aplicação. As reivindicações coordenam clientes cooperantes; os hooks não isolam o acesso ao sistema de arquivos. A correspondência de escopo segue uma gramática documentada. Relatórios de mudança de contrato e dicas de reutilização de nomes exatos são apenas informativos.

Início rápido

Requer Git 2.38+ e Node.js 22.13+ na linha 22.x ou Node.js 24+. Os fluxos completos têm como alvo macOS e Linux. A versão 0.1.1 também valida reivindicações MCP nativas, worktrees, portas, integração e recuperação no Windows; comandos de mutex supervisionados e hooks de shell exigem macOS/Linux ou WSL. Consulte as evidências de suporte.

Instale a versão de lançamento e configure seu projeto:

npm install --global kith-coord@0.1.1
cd /path/to/your/project
kith init --dry-run
kith init

Para instalação a partir do código-fonte e a demonstração descartável, use o pnpm 10.20.0 fixado:

git clone https://github.com/connorhriley/kith.git
cd kith
corepack enable
pnpm install --frozen-lockfile
pnpm build

Veja funcionando

pnpm demo

A demonstração inicia dois clientes MCP reais, dá a cada um uma worktree do Git separada em um repositório temporário, recusa uma reivindicação sobreposta, registra suas edições, executa comandos sob um mutex e verifica/integra ambas as alterações. Ela remove o repositório temporário em seguida. Não são necessárias chamadas a modelos nem credenciais de cliente.

auth: claimed src/auth.mjs in an isolated worktree
billing: overlapping claim on src/auth.mjs refused
billing: claimed src/billing.mjs in an isolated worktree
auth: checked its worktree through the MCP command supervisor
auth: isolated edit reported, verified, and integrated
billing: checked its worktree through the MCP command supervisor
billing: isolated edit reported, verified, and integrated
Two real MCP clients completed work in separate worktrees. Disposable example passed.

A implementação está em examples/two-agents.mjs. Isso demonstra o protocolo de coordenação; a validação com clientes nativos exercita separadamente os clientes de programação instalados.

Conecte seu cliente

Após o início rápido via npm acima, reinicie seu cliente de programação nesse projeto e aprove sua conexão MCP com o Kith. A configuração gerada usa o executável kith instalado; não é necessário um checkout do código-fonte nem pnpm link. Revise e faça commit dos arquivos gerados antes de pedir aos agentes que integrem o trabalho.

A configuração padrão instala a configuração MCP para Claude, Codex e Cursor, além das instruções para agentes, sem adicionar hooks ou shims de gerenciador de pacotes. Revise e faça commit da configuração gerada antes de começar o trabalho; a integração exige um checkout de destino limpo. Reinicie seu cliente com kith em seu PATH. Para selecionar clientes, use --mcp-only --only claude,codex,agents. Hooks existentes são preservados; revise os avisos se eles exigirem uma sessão herdada. Consulte configuração de hooks se precisar deles.

Cliente	Configuração e validação
Claude Code	MCP; hooks de edição opcionais exigem configuração de sessão compartilhada; execuções registradas da CLI nativa
Codex	Configuração MCP do projeto; execuções registradas da CLI nativa com substituições de configuração
Cursor	Fluxo de trabalho da CLI nativa e hooks de edição fail-closed validados; descoberta/confiança na GUI não validada
Outros clientes MCP	Servidor stdio via kith mcp; validação específica do cliente necessária

As verificações nativas são específicas de cada versão. A descoberta na GUI e a confiança persistida no projeto exigem verificações separadas. Consulte configuração de integração, validação registrada e propriedade de sessão antes de misturar hooks, comandos de CLI e clientes MCP.

O pacote npm é kith-coord, com o nome de comando kith. Para um lançador MCP npx fixado, consulte configuração do registro. O pacote npm kith, sem relação, não é este projeto.

Como uma tarefa percorre o Kith

1. Comece via MCP. Chame kith_begin_work com um agentId exclusivo, scopeGlobs explícito e isolateWorktree: true. A conexão mantém a propriedade da sessão; nenhuma exportação de shell é necessária para este fluxo exclusivamente MCP.
2. Reivindique um escopo. Clientes cooperantes recebem um conflito quando uma reivindicação exclusiva se sobrepõe a outra reivindicação.
3. Faça o trabalho. Edite o worktree.worktreePath retornado, relate as edições com kith_record_file_edit e use kith_run_with_mutex para comandos serializados. Envie heartbeat antes da expiração e mantenha a conexão proprietária aberta.
4. Verifique e conclua. Para uma worktree, o Kith faz checkpoint das alterações e integra por meio de uma worktree de staging separada. O destino deve estar limpo. Forneça um comando de verificação para checar mais do que a mesclabilidade do Git.

Uma verificação com falha deixa o destino inalterado e mantém a worktree para reparo. A integração bem-sucedida também mantém a worktree até a limpeza explícita. Escritores externos do Git ainda precisam se coordenar.

Inspecione via kith_get_status ou kith status: caminhos/branches das worktrees, sobreposição de arquivos sujos, ahead/behind, idade de heartbeat/commit e esperas FIFO estão incluídos. Use kith_preview_integrate para caminhos de conflito na árvore de commits antes de concluir. O status normal pode recolher proprietários expirados. Para inspeção de recuperação sem mutação, use:

kith status --offline
kith recover
kith doctor

Hooks opcionais do Claude/Cursor suportam --enforcement block (padrão), warn e off; consulte configuração e desinstalação segura. O protocolo versionado registra os esquemas das ferramentas e a semântica de propriedade.

Para exemplos de MCP, CLI e biblioteca, consulte fluxos de trabalho.

Status do projeto

A suíte exercita contenção de processos, propriedade de sessão, cancelamento de comandos e desconexões, hooks gerados, fluxos de trabalho MCP e integração de worktrees. As verificações de pacote limpo instalam a distribuição compilada em um projeto consumidor separado. Os relatórios de clientes nativos incluem versões exatas e resultados.

O selo de CI leva aos resultados hospedados atuais; testes locais e execuções nativas registradas não estabelecem que toda plataforma ou versão de cliente passa. Descoberta de repositório, verificações de caminho físico, correspondência exata de glob suportado e recusa de conflito do Git têm regressões dedicadas. As verificações de recuperação cobrem upgrades interrompidos, backups de banco de dados/WAL parados e continuação de worktree retida. O contrato de confiabilidade registra os limites desses cenários; a cobertura de clientes nativos está listada acima.

• Contrato de confiabilidade: comportamento, limites e recuperação
• Arquitetura: armazenamento, adaptadores e integração com Git
• Roadmap: prioridades e critérios de conclusão
• Changelog: mudanças de comportamento e notas de migração

Contribuindo

As contribuições mais úteis reproduzem uma falha concreta ou melhoram um fluxo de trabalho real com múltiplos agentes. Inclua um fixture descartável, o comportamento esperado e uma forma de verificar a mudança. Comece pela configuração e pontos de entrada para contribuidores.

Para bugs, use o formulário de relato de bug. Para um fluxo de trabalho proposto, use o formulário de solicitação de recurso. Mantenha tokens, snapshots de código-fonte e estado de .coord fora dos diagnósticos públicos; use as orientações de relato de segurança para relatos sensíveis.

Licenciado sob MIT. A participação segue as expectativas da comunidade.