CodeAlmanac - um wiki da base de código para agentes de codificação com IA

• Um wiki vivo que registra decisões, fluxos, invariantes e armadilhas (gotchas) que não cabem só no código, fornecendo contexto para agentes de IA
  • Registra por que o sistema tem a forma atual, o que quebrou no passado e como os fluxos de trabalho atravessam arquivos/serviços
• O wiki é armazenado como arquivos Markdown dentro do repositório e, após indexação local, pode ser revisado no Git como código
• Agentes e pessoas usam os mesmos comandos locais de leitura: search, show, topics, health, validate
  • Suporta busca por caminho de arquivo com search --mentions src/checkout/, e é possível consultar outro wiki com --wiki <name>
• As tarefas de ciclo de vida para atualizar continuamente o wiki são executadas por três agentes explícitos: build / ingest / garden
  • Usa o Yoke SDK, publicado separadamente
  • ingest: integra ao wiki arquivos, diretórios, diffs do Git, intervalos de commits, PRs/issues do GitHub, URLs e transcrições de agentes locais
  • garden: organiza páginas antigas, links fracos, tópicos, páginas duplicadas etc.
• Para não precisar lembrar comandos de manutenção, oferece 3 tipos de tarefas em segundo plano locais do macOS launchd
  • Sync (a cada 5 horas): varre conversas recentes do Codex/Claude e as coloca na fila como tarefas de ingest para o wiki relevante
  • Garden (a cada 24 horas): revisa conhecimento antigo/duplicado/com conexões fracas em todos os wikis registrados
  • Update (a cada 24 horas): atualiza automaticamente a CLI apenas em momentos seguros e pula se houver tarefas de ciclo de vida em andamento
• Execução totalmente local, sem serviço hospedado nem sincronização em nuvem; os logs ficam em ~/.codealmanac/logs/
• O histórico de execução fica salvo em registros locais de jobs, então pode ser consultado mesmo após fechar o terminal
  • jobs, jobs show, jobs logs, jobs attach, jobs cancel
  • Integração com scripts via --json
• O provider usa almanac-yoke como ponto único de acesso; o Codex usa app-server e o Claude usa Python Agent SDK
  • Reutiliza sessões OAuth existentes do Codex/Claude Code
• O visualizador local iniciado com serve é somente leitura e renderiza navegação por páginas/busca/tópicos/backlinks/referências de arquivo
• Os agentes de ciclo de vida operam com amplas permissões não interativas no sistema de arquivos
  • A pasta almanac/ não é um sandbox do sistema operacional, mas sim uma política de instruções/commits, portanto deve ser executada apenas em repositórios confiáveis
• A telemetria é opcional. Não envia código/caminhos/prompts/transcrições/credenciais, desativa GeoIP e também pode ser bloqueada com DO_NOT_TRACK=1
• Licença Apache-2.0