CodeAlmanac - Karpathy-style codebase wiki from AI conversations
Show HN: CodeAlmanac – Karpathy-style codebase wiki from your conversations
CodeAlmanac transforms your codebase into a living wiki maintained by AI coding agents like Codex and Claude. It captures critical context that code alone cannot express, including architectural decisions, system invariants, and historical gotchas. By automatically scanning local conversations and generating plain Markdown pages within your repository, it ensures both humans and AI agents stay aligned with the project's true intent. Running entirely locally on macOS, it offers a secure, Git-reviewed knowledge base that evolves alongside your development workflow.
Captures what the code can't say: decisions, flows, invariants, gotchas.
- 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.
- 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?
- pwillia7
Any data on better outputs and/or token saving?