HN Explorer

Show HN: CodeAlmanac – Karpathy-style codebase wiki from your conversations (github.com)

60 points by divitsheth ↗ HN
Hey HN! This is Divit from Almanac (YC S26). We built CodeAlmanac, a wiki for your coding agents that updates as you talk to them. It is open-source, local, and free.

Here’s a demo: https://www.youtube.com/watch?v=XNQWV3TFBWM

Your CC/Codex conversations contain a LOT of knowledge that is forgotten because it was never documented. People have their own methods of documenting their chats. We used to make Markdown files like MANUAL.md and DESIGN.md, and would prompt Claude to keep them updated. The problem is that these files quickly become outdated and messy, and there’s only so much you can put in a single file.

So we set out to build CodeAlmanac. We wanted something that was 1) maintained automatically, 2) lived inside our repository, and 3) used our existing Codex/Claude Code subscriptions.

CodeAlmanac maintains an almanac/ folder inside your repository. It contains connected Markdown pages that cover things not documented in the codebase, including decisions you have made and why the codebase is shaped this way.

The pages are indexed in SQLite and are queryable through a CLI. We add instructions to AGENTS.md or CLAUDE.md so future sessions automatically search the wiki before they start coding.

Every five hours, CodeAlmanac uses the Codex/CC SDK to spin up an agent that reads your new conversations and updates the relevant pages. We went with a time-based trigger instead of commits because we saw people commit very frequently, which would lead to high token costs.

We originally made CodeAlmanac for individual developers, but the team use case has become much more obvious to us while using it ourselves. We are a team of three, and each of us works with our own coding agents. Before this, I would make some change after a lot of thinking and then later have to call my cofounders and explain why it looked this way. There is almost a sense of relief now knowing that the decisions I made are written down somewhere their agents will actually read.

It’s live today for everyone to try. Please let me know your feedback and I’ll be here to answer any questions. Would also love to hear how you all maintain context across conversations today!

14 comments

[ 2.0 ms ] story [ 31.0 ms ] thread
[deleted]
(comment deleted)
colinb
Not in any way being negative about what you’ve done, but… Mac only. Is this just because of inbuilt knowledge about file system shape or some more important Apple exclusive tool/environmental quirk?
pwillia7
Any data on better outputs and/or token saving?
ajrouvoet
Although I’d like this to work, I have not seen evidence that AIs extract good reusable knowledge from sessions without strong guidance.

I do R&D work in comp sci and usually write software and reports or papers in parallel. I have been using Opus in a controlled human-in-the-loop fashion to (significantly) speed up the work. While I’m at times surprised how high-level input steers output the right way, no high level ideas emerge from the AIs output. Many attempts to abstract from the concrete are wrong.

As a consequence, most writing is poor on content and form. It writes about the wrong things and crosses abstraction levels all the time. It cannot keep implementation details and conceptual leaps apart.

I don’t know what this means for the aim of this project to maintain important info for agents. Perhaps there are enough low-hanging fruits. That said, I’m skeptical that the resulting wiki is good documentation for human contributors.

gupsak31
This looks promising. Is there a version I can use to self improve my production workflows and not just the dev work?
romanoonhn
Looks very interesting! I'll be trying to set that up. One thing I'm wondering is: I have multiple persistent worktrees for my repo so that I start Claude from different locations (ie folders where this worktree is instantiated). Would it be possible for almanach to reconcile it all together? I figure I could set it up into each folder and 'ln -S' the almanach folder from the base repo to each worktree. Would that work?
pseufaux
Are there any plans to sandbox the agents? I suspect it would be fairly trivial on macOS using sandbox-exec. This looks very useful but I hesitate to run yolo mode agents (even with clear instructions) on my machine.
satoyoshidev
Transcripts tend to have secrets pasted into them during debugging, api keys, .env values and so on. Is there anything that keeps the sync agent from writing those into almanac/ pages that get committed?
w4v3z
Nice! Curious about one thing: how do you handle a decision that gets reversed later? If the wiki page just keeps getting updated in place, does it retain any signal that an approach was tried and explicitly abandoned?
tdu01
We built something similar for our team at work. A human has to run it and review/skim for correctness, who quickly gets overwhelmed. The purpose eventually became an AI wiki for AI to use to spawn agents more efficiently (token wise), to pull in only modules it needs and fills in the blanks from the md files. Like a knowledge graph. It has become useful for production support, design, feature dev, domain specific learnings. We also found it makes a huge difference which model you use to encode and which model you use to decode.