CodeAlmanac

CodeAlmanac maintains a wiki about your codebase, written and kept current by coding agents, aimed at the context that code itself cannot carry: why a system is shaped the way it is, what broke before, which invariants matter, and how a workflow crosses files and services. The wiki is plain markdown under almanac/ in the repository, indexed locally, and reviewed in Git like any other change. It's the llm-wiki-pattern pointed at a codebase — see llm-wiki-as-agent-memory for why several unrelated projects landed on the same substrate.

How it works

Three lifecycle agents do all the writing — build, ingest, and garden — driven through the project's own Yoke SDK, with packaged prompt files as the complete task instructions.

ingest folds material into the wiki. Inputs can be files, directories, git diffs, commit ranges, GitHub PRs or issues, URLs, and local agent transcripts:

codealmanac ingest README.md --using codex
codealmanac ingest github:pr:123 --using claude

garden works on the graph rather than adding to it: stale pages, broken links, topics, weak leads, duplicate pages, unsupported claims.

The read surface is shared by agents and humans, and is deliberately plain:

codealmanac search "checkout timeout"
codealmanac search --mentions src/checkout/
codealmanac show checkout-flow
codealmanac topics
codealmanac health
codealmanac serve            # local web viewer, with a Jobs panel

The automation is the point

codealmanac setup installs three macOS launchd jobs:

Sync is the interesting one, and it's the piece most similar systems lack: the knowledge source is your existing agent conversations, harvested passively, rather than something you remember to write down. The design explicitly allows nothing to happen — "No-op is valid. If the material adds no durable wiki knowledge, the harness should leave the wiki unchanged" — which is the right default for an unattended writer and not what you'd get from a naive implementation.

Trust model

The README is unusually direct about this, and it's the main thing to weigh before running it:

Lifecycle agents are trusted local coding agents. They run with the same broad, non-interactive filesystem permissions CodeAlmanac historically provided, so the almanac/ boundary is an instruction and commit policy, not an OS sandbox.

So an unattended agent with full filesystem access runs on your machine every five hours. Their advice is to use it only in repositories where you accept that, and to review the git diff when automatic commits are off. Anyone already thinking about sandboxing-ai-agents or bubblewrap-dev-env will want to wrap this rather than take the default.

Telemetry is opt-in-by-recommendation during setup; the documented payload is command and lifecycle outcomes plus sanitized crashes under a random install UUID, with GeoIP disabled and no code, paths, arguments, queries, prompts or transcripts. DO_NOT_TRACK=1 works.

Constraints

macOS only, and requires either Codex or Claude Code as the runner. Python 3.12+, installed with uv tool install codealmanac@latest. The launchd dependency is what pins it to macOS — the underlying design has nothing Apple-specific about it, so a Linux systemd-timer port is the obvious missing piece.

Assessment

The two ideas worth stealing regardless of whether you adopt the tool: harvesting durable knowledge from agent transcripts you're already producing, and scheduling a recurring gardening pass as a first-class job rather than a thing you do when the wiki gets bad. This vault does the second manually as its /lint workflow.

On watchlist — 529★, YC S26, macOS-only, and the automatic-agent-with-filesystem-access model needs to survive contact with users before it's a default-yes.

Apache-2.0, 529★, 45 forks. Repo: https://github.com/AlmanacCode/codealmanac