Hello good people of HN,
This is Rohan from Almanac (YC S26). Today I want to share CodeAlmanac. It is a self-updating wiki for your coding agent. It lives in your repo as Markdown files and updates from your conversations with your agent. It’s open-source, local, and free.
How it works
-
Install the CLI and pick your agent (it uses your CC or Codex sub)
-
It scans your codebase and generates an initial wiki.
-
A background job reads your agent conversations every few hours and updates the wiki
-
Your agent queries the wiki through a local SQLite index, using commands like codealmanac search and codealmanac show.
Principles it’s based on
Conversations as a primary source: There’s a lot you discuss with your agent, and there’s a lot said in those conversations that isn’t directly seen in the code. Why the code is shaped the way it is, what ideas you’ve explicitly rejected, and repeatable procedures that the agent did. We document what’s relevant for future agent runs from there.
Maintenance, maintenance, maintenance: An organised wiki is a queryable wiki. Since the first wiki, WikiWikiWeb, people have talked about the need for wiki gardening (see: https://wiki.c2.com/?WikiGardener=). In CodeAlmanac, an agent gardens your wiki every few hours.
Docs as code: The wiki lives in your repository as a folder, following the docs as code philosophy See: https://www.writethedocs.org/guide/docs-as-code/
Frequent updates: An outdated wiki is worse than no wiki (see: https://www.trevorlasn.com/blog/outdated-docs-are-tech-debt ). Almanac updates the wiki every 5 hours, and the time between updates is configurable.
What goes in the wiki
We have borrowed heavily from the Diataxis framework(https://diataxis.fr/). Here’s some of the things the wiki covers: How-to guides (AKA Skills): These cover repeatable procedures and explain things step by step to the agent (eg., How to deploy the CLI, see: https://git.new/2uKhYr7 . They function much the same way as skills, but are connected to the rest of the knowledge base. I talk more about why we think skills are the wrong abstraction here.
Decisions: In every conversation with your agent, you make many important decisions. Almanac saves these inside the decisions folder. For example, our pipeline doesn’t commit code directly and instead lets the underlying model do it. This was automatically documented here: https://git.new/6M6Cprw
Architecture: Every time you start a new run, your agent needs to read and piece together the codebase. This burns tokens unnecessarily, especially on large codebases. We maintain docs on the entire architecture so it can read only what’s relevant: https://git.new/FJQdHVh.
Would love to hear your feedback and any feature requests!
Check it out here: https://github.com/AlmanacCode/codealmanac/ (We only support macOS right now, but are working to support Linux/Windows)
Comments URL: [https://news.ycombinator.com/item?id=48849361](https://news.ycombinator.com/item?id=48849361)
Points: 1