# 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](https://github.com/AlmanacCode/Yoke), 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:

```bash
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:

```bash
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:

| Job | Default | What it does |
|---|---|---|
| Sync | every 5h | Scans local Codex and Claude transcript stores for conversations since the last sync, queues durable knowledge for the matching wiki |
| Garden | every 24h | Reviews every registered wiki for stale, duplicated or poorly connected pages |
| Update | every 24h | Updates the CLI when it's safe to do so |

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 [[toolbox/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>