GitHub - AlmanacCode/codealmanac: A codebase wiki for AI coding agents. Captures what the code can't say: decisions, flows, invariants, gotchas.
Pangram verdict · v3.3
We believe that this document is a mix of AI-generated, and human-written content
AI likelihood · overall
MixedArticle text · 1,562 words · 6 segments analyzed
A living wiki for your codebase, maintained by AI coding agents. CodeAlmanac gives AI agents the context code alone cannot hold: why a system is shaped the way it is, what broke before, which invariants matter, and how workflows cross files and services. The wiki is plain markdown in your repo, indexed locally, and reviewed in Git like any other code change. Supported today: macOS with Codex or Claude Code. Requires Python 3.12+. Quickstart uv tool install codealmanac@latest codealmanac setup See Setup for configuration options. Once CodeAlmanac is set up: cd your-repo codealmanac init # Makes your wiki, if you don't have one codealmanac search "getting started" # Shows matching wiki pages. codealmanac show getting-started # Opens one page in the terminal codealmanac serve # Shows the wiki in local web viewer. Setup Install global agent instructions for the local tools you use: # Interactive setup codealmanac setup
# Quick install with recommended defaults; uses Codex as the AI runner codealmanac setup --yes
# Quick install using Claude as the AI runner codealmanac setup --yes --runner claude Setup installs agent instructions for your chosen tools and three local macOS launchd jobs. The jobs and all wiki work run locally.
Job Default schedule What it does
Sync Every 5 hours Scans recent Codex and Claude conversations and queues useful knowledge for the relevant registered wiki.
Garden Every 24 hours Reviews every registered wiki for stale, duplicated, or poorly connected knowledge.
Update Every 24 hours Checks for and installs CodeAlmanac CLI updates when it is safe to do so.
These schedules run locally in the background. Use codealmanac automation status to see what is installed. The final setup step asks about anonymous telemetry and recommends Yes so we can see which commands work and where the CLI breaks. It sends controlled command and lifecycle outcomes plus sanitized unhandled crashes under a random install UUID.
It never sends code, paths, arguments, queries, prompts, transcripts, repository/run IDs, locals, or credentials; GeoIP is disabled. Choose No in setup, pass setup --no-telemetry, set telemetry.enabled to false, or use DO_NOT_TRACK=1 at any time. Without a future login, the UUID profile has no name or email. If you don't have Codex or prefer Claude, use --runner claude. --target only chooses which global agent instruction files to install; it does not choose the AI runner: codealmanac setup --yes --target codex codealmanac setup --yes --target claude Customize automatic work during setup: # Change how often recent agent conversations are scanned codealmanac setup --yes --sync-every 5h
# Do not install automatic transcript sync codealmanac setup --yes --sync-off
# Do not install automatic wiki cleanup codealmanac setup --yes --garden-off
# Do not install automatic CodeAlmanac updates codealmanac setup --yes --no-auto-update To uninstall CodeAlmanac-owned local artifacts: codealmanac uninstall --yes Daily Read Surface Agents and humans use the same local read commands: codealmanac search "checkout timeout" codealmanac search --mentions src/checkout/ codealmanac show checkout-flow codealmanac topics codealmanac health codealmanac validate Use --wiki <name> to read another registered local wiki. By default, commands target the exact current directory when it is a registered repository root. Updating The Wiki Lifecycle commands run one of three explicit agents—build, ingest, or garden— through the public Yoke SDK. The existing packaged prompt files remain the complete task instructions and direct agents to edit the wiki under almanac/. 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. Run lifecycle commands only in repositories where you accept that trust model, and review the resulting Git diff when automatic commits are disabled.
codealmanac ingest README.md --using codex codealmanac ingest github:pr:123 --using claude codealmanac garden --using codex ingest folds selected local material into the wiki. Inputs can include files, directories, Git diffs, commit ranges, GitHub PRs or issues, URLs, and local agent transcripts. garden improves the existing wiki graph: stale pages, links, topics, weak leads, duplicate pages, and unsupported claims. No-op is valid. If the material adds no durable wiki knowledge, the harness should leave the wiki unchanged. init, ingest, and garden create queued runs and start a local worker. To follow them visually, run codealmanac serve and select Jobs in the sidebar. To stay in the terminal, use codealmanac jobs attach <run-id>. Sync And Automation CodeAlmanac can keep registered wikis current without requiring you to remember maintenance commands. Sync scans local Codex and Claude transcript stores for conversations active since the previous completed sync. Conversations associated with registered repositories are queued as ordinary ingest jobs. Sync may decide that a conversation contains no durable knowledge and leave the wiki unchanged. Garden periodically queues a maintenance job for each registered wiki. It improves stale pages, weak links, topics, duplicated knowledge, and graph structure. Update keeps the locally installed CodeAlmanac CLI current. Scheduled updates are skipped when an update would be unsafe, such as while lifecycle work is active. Automation is implemented with local macOS launchd jobs, not a hosted service or cloud sync. Logs are stored under ~/.codealmanac/logs/. # See installed schedules codealmanac automation status
# Change a schedule codealmanac config set automation.sync.every 5h codealmanac config set automation.garden.every 24h codealmanac config set automation.update.every 24h
# Disable or re-enable a schedule codealmanac config set automation.sync.enabled false codealmanac config set automation.sync.enabled true config set updates the user TOML and immediately makes launchd match. If you edit the TOML directly, run codealmanac config apply afterward.
Automation creates individual background runs. Inspect those runs separately with codealmanac jobs. Jobs Lifecycle runs are recorded under ~/.codealmanac/. Use these commands to inspect and control them: # List recent jobs with their IDs, kinds, statuses, and elapsed times codealmanac jobs
# Show one job's status, summary, page changes, timestamps, and error details codealmanac jobs show <run-id>
# Print the events recorded so far, including progress, tool activity, and errors codealmanac jobs logs <run-id>
# Follow new events live until the job finishes, fails, or is marked cancelled codealmanac jobs attach <run-id>
# Prevent a queued job from starting, or stop a running job and its agent codealmanac jobs cancel <run-id> show is a summary of the job; logs is a snapshot of its event history; attach keeps watching and prints events as they arrive. All of these commands read the same durable local job record, so they still work after the terminal that started the job has closed.
Add --json when consuming their output from a script. Providers CodeAlmanac uses almanac-yoke as its single provider boundary. Codex runs through app-server; Claude uses Yoke's default Claude surface (currently the Python Agent SDK). Existing Codex or Claude Code OAuth sessions are reused, and API credentials can be supplied through Yoke when embedding the SDK. Build, ingest, and garden are packaged as a Yoke agent collection under src/codealmanac/agents/. Each agent uses Yoke's native folder contract: agent.yaml describes tools and permissions, while instructions.md contains the durable agent instructions. A lifecycle run passes only its typed runtime context as the task prompt. Optional Yoke skills/, subagents/, and workflows/ folders can be added to an agent when the product needs them; native Claude or Codex execution still decides how and when to use them. codex login claude auth login codealmanac doctor Read commands do not need provider credentials. Write-capable lifecycle commands need the selected harness to be available and authenticated. What Gets Created By Init With the default root: your-repo/ |-- almanac/ | |-- README.md | |-- topics.yaml | |-- architecture/ | | |-- README.md | | `-- indexer.md | |-- decisions/ | | `-- local-first.md | `-- guides/ | `-- setup.md |-- src/ `-- ...
Markdown pages live directly under almanac/ in meaningful folders. topics.yaml organizes pages across folders. README.md files act as landing pages for their folder routes. For auto-detection, a repository counts as a CodeAlmanac wiki when almanac/topics.yaml and almanac/README.md exist. Runtime State Derived local state lives under ~/.codealmanac/: ~/.codealmanac/codealmanac.db ~/.codealmanac/repos/<repo-id>/index.db
The local database records repositories, runs, run events, worker locks, and sync state. Per-repository runtime files contain derived indexes. They do not belong in the committed almanac/ tree.
Configuration User config lives at: ~/.codealmanac/config.toml
The supported defaults are: auto_commit = true
[harness] default = "codex" model = "gpt-5.5"
[automation.sync] enabled = true every = "5h"
[automation.garden] enabled = true every = "24h"
[automation.update] enabled = true every = "24h" CLI flags still win over config. Use codealmanac config set <key> <value> for normal changes. It applies automation changes to launchd immediately. Direct file edits are supported but must be followed by: codealmanac config apply auto_commit means lifecycle prompts may tell the selected agent to use normal Git commands for wiki source changes. CodeAlmanac does not stage files, split diffs, or commit internally. codealmanac setup --no-auto-commit codealmanac config set auto_commit false codealmanac config set auto_commit true Local Viewer codealmanac serve The viewer is read-only. It renders pages, search, topics, backlinks, and file-reference navigation from local wiki data. serve opens it in your default browser once the server is ready; use codealmanac serve --no-open for headless or scripted use. By default the viewer can switch across available registered local wikis. Use codealmanac serve --wiki <name> to narrow it to one wiki. Migrating From The npm CLI The legacy codealmanac npm package is retired. PyPI is the only supported distribution. If you used the npm CLI, your machine may still carry the old global install plus the hooks and agent instructions it set up.