AlmanacCode/codealmanac

A codebase wiki for AI coding agents. Captures what the code can't say: decisions, flows, invariants, gotchas.

What it solves

CodeAlmanac addresses the "context gap" in software development where code alone cannot explain the reasoning behind architectural decisions, historical failures, system invariants, or complex cross-service workflows. It provides a way to maintain a "living wiki" that captures this high-level context, which is often lost in commit messages or scattered across documentation.

How it works

The tool creates a wiki consisting of plain Markdown files stored directly in the repository under an almanac/ directory. It uses AI coding agents (via Codex or Claude Code) to automatically maintain this wiki through three primary processes:

  • Ingestion: AI agents scan files, Git diffs, PRs, issues, and agent transcripts to fold new knowledge into the wiki.
  • Gardening: Periodic AI-driven reviews that clean up stale pages, fix broken links, and remove duplicate information.
  • Syncing: Background processes that scan recent AI agent conversations to extract and queue useful knowledge for the wiki.

Users can interact with the wiki via a CLI for searching and viewing pages, or through a local web viewer.

Who it’s for

Developers and teams who want to maintain up-to-date project documentation that is automatically updated by AI agents and reviewed via standard Git workflows.

Highlights

  • Git-native: The wiki is stored as Markdown in the repo, meaning changes are reviewed via pull requests.
  • Automated Maintenance: Uses background launchd jobs on macOS to sync and "garden" the wiki without manual effort.
  • Agent-Integrated: Directly integrates with Codex and Claude Code to turn conversation transcripts into durable documentation.
  • Local-first: All wiki work and indexing happen locally on the user's machine.
  • Web Viewer: Includes a read-only local web interface for browsing the wiki graph.

Related

  • Project
    mex-memory/mex

    A living codebase wiki that allows AI coding agents to maintain and evolve structured project documentation, reducing context window bloat and token costs.

  • Dispatch
    CodeAlmanac: AI-Maintained Codebase Wiki for Coding Agents

    CodeAlmanac is a local-first codebase wiki that uses AI agents to capture architectural decisions, invariants, and workflows in Markdown files stored directly in the repository.

  • Project
    langchain-ai/openwiki

    A CLI tool that uses AI agents to create and maintain a self-updating Markdown wiki for codebases or personal knowledge, featuring grounded claims to ensure factual accuracy.

  • Project
    akitaonrails/ai-memory

    A long-term memory system for AI coding agents that creates a shared, persistent Markdown wiki from session observations to enable seamless context handoffs between different agents.

  • Project
    FSoft-AI4Code/CodeWiki

    CodeWiki is an open‑source Python framework that uses LLMs (OpenAI, Anthropic, Azure, Bedrock, Atlas Cloud, or Claude/Codex subscription) to automatically generate comprehensive, architecture‑aware documentation—including markdown and Mermaid diagrams—for large, multi‑language codebases. It features hierarchical decomposition, recursive multi‑agent processing, configurable token limits, incremental updates, and GitHub‑Pages‑ready output.