Aikito

O que Aikito faz?

Propósito

Use o Aikito como a fonte canônica e gerenciada pelo Git para recursos duráveis de Agentes e sincronize esses recursos nos agentes e projetos de codificação suportados.

Modelo Mental

Mantenha o código-fonte da CLI e o workspace do usuário separados:

~/aikito-src   checkout do código-fonte da CLI
~/aikito       workspace canônico do usuário

O workspace contém as fontes da verdade:

~/aikito/
├── agents.toml
├── skills.toml
├── subagents.toml
├── mcps/
├── global/AGENTS.md
├── skills/
├── memory/
└── projects/<nome>/

Os diretórios de configuração dos agentes e os diretórios .agents/ dos projetos são pontos de entrada em tempo de execução, não fontes independentes. Modifique primeiro os arquivos canônicos do workspace, depois sincronize-os com a CLI.

Use AIKITO_DIR quando o workspace não for ~/aikito. Use o comando aikito instalado, em vez de assumir que a CLI reside dentro do workspace.

Inicialização (Bootstrap)

Quando a CLI não estiver instalada, use o repositório oficial e mantenha seu checkout separado do workspace futuro:

git clone https://github.com/lsaint/aikito.git "$HOME/aikito-src"
export PATH="$HOME/aikito-src/bin:$PATH"

Antes de clonar, verifique se o destino não contém dados de usuário não relacionados. Não sobrescreva um checkout existente sem a orientação do usuário.

Inicialize e inspecione um workspace:

aikito init workspace ~/aikito
aikito status

aikito init workspace recusa a árvore de código-fonte da CLI, outro checkout do repositório e um diretório não vazio não reconhecido. Não tente burlar essas proteções. Após a inicialização, inspecione os arquivos gerados antes de sincronizar qualquer coisa.

Protocolo de Segurança

• Comece com descoberta somente leitura: inspecione os arquivos canônicos relevantes, execute aikito status e use comandos de status específicos do recurso.
• Execute aikito adopt sem --apply primeiro. Mostre ao usuário o plano de adoção, conflitos e tratamento de credenciais antes de aplicá-lo.
• Use --dry-run para comandos de sincronização que o suportam.
• Trate destinos não gerenciados e instruções conflitantes como decisões para o usuário. Não os sobrescreva silenciosamente.
• Mantenha chaves de API, tokens, senhas e materiais OAuth fora do workspace do Aikito e do Git. Armazene referências de variáveis de ambiente na configuração canônica do MCP.
• Alerte antes de qualquer operação explícita de força ou poda e delimite-a ao alvo revisado.
• Não trate um repositório Git local como seguro para publicar. Reveja a memória e a configuração em busca de dados privados antes de adicionar um remoto ou fazer push.
• Preserve alterações não relacionadas do usuário tanto no workspace quanto na configuração do Agente de destino.

Roteamento de Recursos

Instruções e Habilidades Globais

Fontes canônicas:

~/aikito/global/AGENTS.md
~/aikito/skills.toml
~/aikito/skills/<nome-da-habilidade>/

Após revisar as alterações:

aikito sync global --dry-run
aikito sync global
aikito status
aikito show skills
aikito show skill <alvo>
aikito edit skill <alvo>

Não edite entradas de instruções ou habilidades geradas nativamente pelo Agente como fontes independentes.

Ao adicionar, renomear ou remover uma habilidade global, trate a alteração como uma migração entre runtimes, não como uma edição apenas no diretório:

• Atualize skills.toml, a lista de permissão de exportação pública e referências ao nome antigo da habilidade.
• Verifique se cada agente suportado que carrega habilidades globais tem o caminho skills_path correto em agents.toml e no modelo aikito init. Não assuma que a CLI de um agente e seu IDE usam o mesmo diretório de habilidades global.
• Execute os testes relevantes, depois execute aikito sync global e aikito status.
• Inspecione cada destino de agente gerenciado e confirme que a nova habilidade está visível e que qualquer link obsoleto para o nome antigo foi removido.
• Mantenha uma habilidade global fora dos arquivos agent.toml do projeto, a menos que o projeto a substitua ou copie intencionalmente.

Projetos

Um workspace é a fonte central da verdade e normalmente existe uma vez. Um registro de projeto representa um diretório de código e seus recursos de Agente específicos do projeto. Quando uma instrução solicitada, seleção de habilidade ou memória é específica do projeto e o diretório de código atual não está registrado, pergunte se o usuário deseja registrá-lo. Não registre um projeto para um recurso global.

Após confirmação, inicialize o projeto a partir de seu diretório de código:

aikito init project

O nome do diretório e o caminho atual são os padrões. Use argumentos explícitos quando necessário:

aikito init project <nome> <caminho>

Este comando cria o esqueleto do projeto canônico e sincroniza seu runtime .agents/. Trate recursos de runtime não gerenciados existentes ou um nome de projeto vinculado a outro caminho como conflitos para o usuário; não os ignore.

A configuração do projeto pertence a:

~/aikito/projects/<nome>/agent.toml
~/aikito/projects/<nome>/AGENTS.md
~/aikito/projects/<nome>/memory/

Sincronize e verifique com:

aikito show projects
aikito show project <nome>
aikito sync project <nome> --dry-run
aikito sync project <nome>
aikito status
aikito diff
aikito show memory

As instruções e a memória do projeto permanecem vinculadas às fontes canônicas. As habilidades do projeto seguem o sync_mode: link mantém links simbólicos; copy gera cópias gerenciadas para rastreamento Git do projeto. Use aikito status para detectar divergências em habilidades copiadas e aikito diff para compará-las com a habilidade canônica. A sincronização se recusa a substituir cópias divergentes; mescle as alterações que devem persistir ou use aikito sync project <nome> --force somente após revisão.

Os diretórios de destino .agents/skills/ e .agents/memory/ são gerenciados exclusivamente pelo Aikito. Entradas desconhecidas são conflitos e nunca são excluídas pela sincronização do projeto. Não armazene arquivos não relacionados lá.

Servidores MCP

Fonte canônica:

~/aikito/mcps/*.toml

Visualize, aplique e verifique:

aikito sync mcp --dry-run
aikito sync mcp
aikito show mcp

Use aikito show mcp --live apenas quando verificações ao vivo no agente forem úteis. Use aikito auth mcp <agente> <servidor> para fluxos de autenticação suportados. Nunca imprima, persista ou confirme credenciais capturadas.

Subagentes

Fontes canônicas:

~/aikito/subagents.toml
~/aikito/subagents/

Visualize, aplique e verifique:

aikito sync subagents --dry-run
aikito sync subagents
aikito show subagents
aikito show subagent <alvo>
aikito edit subagent <alvo>

Revise arquivos gerenciados órfãos antes de usar --prune. Nunca force um destino não gerenciado apenas para deixar o status verde.

Memória

A memória global pertence a ~/aikito/memory/. A memória específica do projeto pertence a ~/aikito/projects/<nome>/memory/.

aikito show memory [alvo]
aikito edit memory <alvo>

Use a habilidade separada durable-memory para decidir quando o conhecimento é durável o suficiente para persistir, qual escopo o possui e como versioná-lo.

Adoção (Adoption)

Visualize a configuração existente do Agente antes de importá-la:

aikito adopt

Somente após o usuário revisar o plano e resolver os conflitos de instrução:

aikito adopt --apply

A aplicação cria backups com carimbo de data/hora em ~/.aikito/backups/adopt_<timestamp>. A adoção importa recursos para o workspace; a configuração nativa do Agente muda apenas durante a sincronização implícita.

Verificação e Comportamento Atual

Após cada escrita, execute o comando de status relevante mais restrito e inspecione os destinos relatados. Use aikito <comando> --help como autoridade para opções suportadas pela versão instalada. Ao trabalhar a partir de um checkout do código-fonte, consulte o README raiz e a documentação vinculada relevante para a arquitetura atual e modelo de segurança.