CodeAlmanac convierte las conversaciones en un wiki vivo del código

CodeAlmanac es un CLI de código abierto que convierte las conversaciones de desarrolladores en un wiki vivo para una base de código. El proyecto, publicado en Hacker News como un Show HN, almacena ese conocimiento como Markdown plano dentro del repositorio, lo indexa localmente y envía los cambios a través de la revisión habitual de Git.

La propuesta es sencilla: el código fuente rara vez captura por qué un sistema tiene cierta apariencia, qué falló antes o qué invariantes importan entre archivos y servicios. CodeAlmanac está diseñado para preservar ese contexto escaneando conversaciones locales de Codex o Claude Code e incorporando el conocimiento útil de nuevo en un directorio almanac/.

Actualmente es compatible con macOS y requiere Python 3.12+. La instalación comienza con uv tool install codealmanac@latest, seguida de codealmanac setup. A partir de ahí, los usuarios pueden inicializar un wiki, buscar páginas, abrir entradas en la terminal o lanzar un visor web local de solo lectura con codealmanac serve.

La configuración instala instrucciones del agente para el runner elegido y crea tres trabajos locales launchd de macOS:

Recomendado

uhubctl permite cortar la alimentación USB puerto por puerto

• Sync cada 5 horas para escanear conversaciones recientes y poner en cola conocimientos útiles
• Garden cada 24 horas para limpiar páginas obsoletas, duplicadas o débilmente conectadas
• Update cada 24 horas para instalar de forma segura actualizaciones del CLI

Todo se ejecuta localmente, incluidos los registros bajo ~/.codealmanac/logs/. El proyecto afirma que la telemetría es anónima y excluye código, rutas, prompts, transcripciones, IDs de repositorio, datos locales y credenciales; puede desactivarse durante la configuración, mediante la configuración o con DO_NOT_TRACK=1.

Almacenamiento local, runners y modelo de confianza

CodeAlmanac utiliza almanac/ como la única raíz de wiki compatible en el repositorio. Una configuración por defecto crea archivos como README.md, topics.yaml y carpetas para notas de arquitectura, decisiones y guías. El estado derivado vive por separado bajo ~/.codealmanac/, incluyendo codealmanac.db e índices por repositorio.

Las operaciones de escritura las manejan tres agentes explícitos del ciclo de vida: build, ingest y garden. El proyecto indica que se ejecutan a través del SDK público Yoke. Codex usa app-server, mientras que Claude usa la surface por defecto de Yoke para Claude, actualmente el Python Agent SDK.

El límite de confianza es deliberadamente laxo. Son agentes de codificación locales con permisos amplios y no interactivos sobre el sistema de archivos, y el límite almanac/ se hace cumplir mediante instrucciones y la política de commits en lugar de un sandbox del sistema operativo. El proyecto aconseja ejecutar los comandos del ciclo de vida solo en repositorios donde ese modelo sea aceptable y revisar el diff de Git resultante cuando los commits automáticos estén deshabilitados.

La anterior CLI de npm ha sido retirada; PyPI es ahora la única distribución compatible. Para equipos que quieran una capa de memoria versionada y buscable junto al propio código, la apuesta central de CodeAlmanac es simple: la documentación que falta ya está en el historial de chats.