codealmanac
A codebase wiki for AI coding agents. Captures what the code can't say: decisions, flows, invariants, gotchas.
CodeAlmanac is an AI agent that maintains a living wiki for your codebase, documenting architectural decisions, workflows, invariants, and contextual knowledge that source code alone cannot capture. The agent automatically scans coding conversations from Codex or Claude Code, extracts valuable knowledge, and organizes it into markdown pages stored in your repository's almanac/ directory. It runs three automated jobs locally—sync, garden, and update—to keep wiki content current, remove stale information, and improve page connections, giving both AI coding agents and human developers access to critical context through search, topics, and visual navigation.
Key Features
Use Cases
- 01Preserving architectural decisions and design rationale for onboarding new developers
- 02Documenting cross-file workflows and system invariants that span multiple services
- 03Capturing gotchas, breaking changes, and lessons learned from past incidents
- 04Providing AI coding agents with contextual knowledge to improve code suggestions
- 05Automatically maintaining documentation without manual wiki updates
- 06Creating searchable knowledge base from GitHub PRs, issues, and commit history
Related Agents
View morehermes-agent
The agent that grows with you
agency-agents
A complete AI agency at your fingertips - From frontend wizards to Reddit community ninjas, from whimsy injectors to reality checkers. Each agent is a specialized expert with personality, processes, and proven deliverables.
openinterpreter
A coding agent for open models like Kimi K3
cline
Autonomous coding agent as an SDK, IDE extension, or CLI assistant.
codealmanac — FAQ
What is CodeAlmanac and how does it work?+
CodeAlmanac is an AI agent that maintains a markdown wiki in your repository, capturing architectural decisions, workflows, and context from your coding conversations and codebase. It runs locally on macOS, scanning Codex or Claude Code transcripts and organizing knowledge into the almanac/ directory.
How do I install CodeAlmanac?+
Install via uv with 'uv tool install codealmanac@latest', then run 'codealmanac setup' to configure. The setup installs agent instructions and optional background jobs for automatic syncing, gardening, and updates.
Which AI coding tools does CodeAlmanac work with?+
CodeAlmanac currently supports macOS with Codex or Claude Code. During setup, you choose your runner (--runner codex or --runner claude) and which agent instruction files to install (--target).
Do I need API keys or credentials?+
Yes, you need existing Codex or Claude Code OAuth sessions. Run 'codex login' or 'claude auth login' before using lifecycle commands. Read commands do not require credentials.
Is CodeAlmanac free and open source?+
Yes, CodeAlmanac is licensed under Apache-2.0. It runs entirely locally with no hosted service or cloud sync, though it optionally collects anonymous usage telemetry that can be disabled.
What are the system requirements?+
CodeAlmanac requires macOS and Python 3.12 or later. It uses local launchd jobs for automation and stores all data under ~/.codealmanac/ and your repository's almanac/ directory.
How do I install codealmanac?+
Open the source repository on GitHub and follow its README. codealmanac is a agent — MCP Agents Market links you directly to the official repo.
Is codealmanac free?+
codealmanac is an open-source project hosted on GitHub. Check the repository for its license and any usage requirements.