CodeAlmanac turns chats into a living code wiki

CodeAlmanac is an open source CLI that turns developer conversations into a living wiki for a codebase. The project, posted to Hacker News as a Show HN, stores that knowledge as plain Markdown inside the repo, indexes it locally, and sends changes through normal Git review.

The pitch is straightforward: source code rarely captures why a system looks the way it does, what broke before, or which invariants matter across files and services. CodeAlmanac is designed to preserve that context by scanning local conversations from Codex or Claude Code and folding useful knowledge back into an almanac/ directory.

It currently supports macOS and requires Python 3.12+. Installation starts with uv tool install codealmanac@latest, followed by codealmanac setup. From there, users can initialize a wiki, search pages, open entries in the terminal, or launch a local read-only web viewer with codealmanac serve.

Setup installs agent instructions for the chosen runner and creates three local macOS launchd jobs:

Recommended reading

Uhubctl lets you cut USB power port by port

• Sync every 5 hours to scan recent conversations and queue useful knowledge
• Garden every 24 hours to clean up stale, duplicated, or weakly connected pages
• Update every 24 hours to safely install CLI updates

Everything runs locally, including logs under ~/.codealmanac/logs/. The project says telemetry is anonymous and excludes code, paths, prompts, transcripts, repository IDs, locals, and credentials; it can be disabled during setup, via config, or with DO_NOT_TRACK=1.

Local storage, runners, and trust model

CodeAlmanac uses almanac/ as the only supported repo wiki root. A default setup creates files such as README.md, topics.yaml, and folders for architecture notes, decisions, and guides. Derived state lives separately under ~/.codealmanac/, including codealmanac.db and per-repository indexes.

Write operations are handled by three explicit lifecycle agents: build, ingest, and garden. The project says they run through the public Yoke SDK. Codex uses app-server, while Claude uses Yoke’s default Claude surface, currently the Python Agent SDK.

The trust boundary is loose by design. These are local coding agents with broad, non-interactive filesystem permissions, and the almanac/ boundary is enforced by instructions and commit policy rather than an OS sandbox. The project advises running lifecycle commands only in repositories where that model is acceptable and reviewing the resulting Git diff when automatic commits are disabled.

The earlier npm CLI has been retired; PyPI is now the only supported distribution. For teams that want a searchable, versioned memory layer sitting next to the code itself, CodeAlmanac’s core bet is simple: the missing documentation is already in the chat history.