CodeAlmanac: a markdown wiki for coding agents, kept honest by Git

The gap CodeAlmanac targets: context that never lands in the repository

Most documentation describes what the code does. It rarely records why a system is shaped the way it is, which invariants hold, what broke before, or how a workflow crosses files and services. The README frames the product around exactly that: a wiki that holds "what the code can't say". The intended reader is not a new hire browsing a docs site. It is an AI coding agent that has the repository in context but no memory of the decisions behind it, plus the humans who review what those agents write. The wiki lives as plain markdown inside the repository, indexed locally, and reviewed in Git like any other change. That last property is the design bet: knowledge is versioned alongside the code it describes, so a stale claim is visible in a diff rather than buried in a chat log. The project is written in TypeScript but distributed through PyPI, which the README's badge links confirm, and it requires Python 3.12 or newer.

Three lifecycle agents, one markdown directory, and a local index

Lifecycle commands run one of three explicit agents: build, ingest, or garden. They execute through the public Yoke SDK, and the packaged prompt files remain the complete task instructions. Those prompts direct the agent to edit the wiki under almanac/. The mechanism is therefore not a parser that extracts structure from source. It is a coding agent, given a prompt and a directory, writing prose. Ingest folds selected material into the wiki: files, directories, Git diffs, commit ranges, GitHub PRs or issues, URLs, and local agent transcripts. Garden reviews the existing graph for stale pages, links, topics, weak leads, duplicate pages, and unsupported claims. The README states that a no-op is valid: if the material adds no durable knowledge, the harness should leave the wiki unchanged. Read commands (search, show, topics, health, validate) are the shared read surface for both agents and humans, and search accepts a --mentions flag that takes a path such as src/checkout/, which is how you find pages touching a given area of the tree. Commands target the exact current directory when it is a registered repository root, and --wiki <name> reads another registered local wiki.

Getting it running: setup flags, launchd jobs, and the read commands

The documented install path is uv tool install codealmanac@latest followed by codealmanac setup. Supported today is macOS with Codex or Claude Code, and Python 3.12+. Setup installs global agent instructions for the tools you use and three local macOS launchd jobs. The Sync job runs every 5 hours by default and scans recent Codex and Claude conversations, queueing useful knowledge for the relevant registered wiki. Garden runs every 24 hours and reviews each registered wiki for stale, duplicated, or poorly connected knowledge. Update runs every 24 hours and installs CLI updates when it is safe to do so. codealmanac automation status reports what is installed. The runner is chosen with --runner claude or left as Codex by default; --target only selects which global agent instruction files to install and does not choose the runner. Schedules are configurable: --sync-every 5h, --sync-off, --garden-off, --no-auto-update. Day to day you work in the terminal with codealmanac search "checkout timeout", codealmanac show checkout-flow, codealmanac topics, codealmanac health, and codealmanac validate. Ingest examples from the README include codealmanac ingest README.md --using codex and codealmanac ingest github:pr:123 --using claude. Init, ingest, and garden create queued runs and start a local worker; codealmanac jobs attach <run-id> follows a run in the terminal, or codealmanac serve opens a local web viewer with a Jobs panel.

The almanac/ boundary is a policy, not a sandbox

This is the limitation that should decide adoption. The README is explicit: lifecycle agents are trusted local coding agents that 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. An agent told to write only under almanac/ can still, in principle, touch anything the process can reach. The README's own guidance is to run lifecycle commands only in repositories where you accept that trust model, and to review the resulting Git diff when automatic commits are disabled. Two consequences follow. First, the value of the Git review workflow is not cosmetic; it is the compensating control for an agent with broad permissions. Second, scheduled Sync and Garden jobs widen the window in which that agent acts without you watching, which is why the opt-out flags matter for anyone evaluating the tool. There is also a platform constraint: macOS only, with Codex or Claude Code as the runner, and Python 3.12+ on the machine. Teams on Linux CI or Windows workstations have no documented path today.

Telemetry, transcripts, and what leaves the machine

The README states that the jobs and all wiki work run locally, and that the index is local. Setup asks about anonymous telemetry and recommends Yes. According to the README, it sends controlled command and lifecycle outcomes plus sanitized unhandled crashes under a random install UUID, and never sends code, paths, arguments, queries, prompts, transcripts, repository or run IDs, locals, or credentials, with GeoIP disabled. It can be declined at setup, disabled with setup --no-telemetry, set to false via the telemetry.enabled config key, or suppressed with DO_NOT_TRACK=1 at any time. The README also notes that without a future login, the UUID profile has no name or email. Separately, Sync reads local Codex and Claude transcript stores. That is local reading, not transmission, but it does mean the tool's input surface includes conversation history that may contain anything you typed into an agent. If your transcripts hold material you would not want summarized into a repository file, --sync-off is the flag to reach for, and ingest should be driven explicitly.

How it differs from generated docs and from plain CLAUDE.md files

The obvious alternative is a hand-maintained AGENTS.md or CLAUDE.md file, or documentation generated from source. A single instruction file is cheap and has no scheduler, no index, and no review loop beyond normal editing; it also has no mechanism to notice when a claim has gone stale. CodeAlmanac's Garden job exists precisely to look for stale pages, duplicates, weak links, and unsupported claims, and Sync turns conversations into ingest jobs so knowledge captured in a debugging session can land in the repository. The cost is machinery: launchd jobs, a local worker, queued runs, and an agent with broad permissions. Source-derived documentation generators sit at the other end. They can describe signatures and call graphs because they read the code, but the README's premise is that the interesting material is what the code cannot express, and that is not recoverable by parsing. The honest comparison is not features but trust and maintenance: a markdown file you edit by hand has no failure mode beyond neglect, while CodeAlmanac trades that for automation that can write the wrong thing confidently.

Upgrades, licensing, and the cost of keeping the wiki alive

The project ships frequently. Three releases landed on 2026-07-11 (v0.4.2, v0.4.3, v0.4.4), and the repository's last push is 2026-07-25. The Update launchd job checks for and installs CLI updates when it is safe to do so, which means the installed binary can move without you initiating it. If you want upgrades to be a deliberate act, pass --no-auto-update during setup and run the update yourself. The wiki itself is plain markdown in your repository, so it survives the tool: if you stop using CodeAlmanac, the files remain readable and reviewable. That is a genuine exit path, and it is worth weighing against the ongoing cost of running Garden so the pages do not rot. Licensing is Apache-2.0, per the repository metadata and the badge in the README. That is a permissive licence with an explicit patent grant and a requirement to preserve notices; it is not a statement about the licence of the AI models or runners you point the lifecycle agents at, and it says nothing about the terms attached to Codex or Claude Code. Check those separately before deploying this in a commercial repository. This is a description of the licence identifier, not legal advice.

Editorial conclusion

Adopt CodeAlmanac if you are on macOS with Python 3.12+ and already run Codex or Claude Code, and if you are willing to treat almanac/ as a commit policy rather than a security boundary. Do not adopt it if you need Linux or Windows, or if you cannot accept lifecycle agents holding broad non-interactive filesystem permissions in the repository. Before wiring in the scheduled jobs, run codealmanac setup --yes --sync-off --garden-off --no-auto-update, then codealmanac init and codealmanac validate by hand, and read the diff the first ingest produces.

Official sources

1. AlmanacCode/codealmanac on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases