CodeAlmanac
A living, Git-reviewed Markdown wiki that gives AI coding agents the decisions, flows, invariants and gotchas code alone cannot express.
- Source repo
- AlmanacCode/codealmanac
- Stars
- ★ 950
- Last updated
- 4mo ago
- License
- Apache-2.0
- Primary language
- TypeScript
- FA score
- 51/100 · Major gaps
At a glance
- How it runs
- Works with
- Portable with changesCodex · Claude Code
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A team has source code but thin design docs and wants to convert PRs, commit ranges, and docs into a reviewable Markdown wiki via
codealmanac ingest. - Not a fit if
- Teams that need Linux or Windows support
- Users uncomfortable with trusted agents running broad non-interactive filesystem permissions
- Organizations needing hosted cloud sync or a shared team backend
- Website
- codealmanac.com ↗ set on GitHub
- Maintenance
- Commits in the last 6 monthslast commit 2026-07-17latest release v0.4.4 (2026-07-11)
- Source review
- 51/100 · Major gaps
What does this agent do, and when should you use it?
CodeAlmanac is a local-first CLI that creates and maintains a Markdown wiki inside your repository (default root almanac/) so coding agents such as Codex and Claude Code get context the source code does not hold. It drives three explicit lifecycle agents — build, ingest, and garden — packaged as a Yoke agent collection and executed through almanac-yoke, which dispatches to Codex (app-server) or Claude (Python Agent SDK) while reusing existing OAuth sessions. Runtime state, including job records, per-repo indexes, worker locks, and sync state, lives under ~/.codealmanac/, while the wiki itself is plain Markdown committed and reviewed like code. A read surface of search, show, topics, health, and validate commands plus a read-only local web viewer (codealmanac serve) works without model credentials. The current release is macOS-only, requires Python 3.12+, and uses local launchd jobs for sync, garden, and self-update.
All write paths go through the Yoke agent collection in src/codealmanac/agents/, where each agent follows the folder contract of agent.yaml plus instructions.md. codealmanac init runs the build agent to scaffold almanac/README.md, almanac/topics.yaml, and folder landing pages. codealmanac ingest accepts files, directories, Git diffs, commit ranges, GitHub PRs or issues, URLs, and local agent transcripts, folding durable knowledge into the wiki and treating a no-op as a valid outcome. codealmanac garden reviews the wiki graph for stale pages, weak links, topics, duplicates, and unsupported claims. Every lifecycle invocation creates a queued run plus a local worker, persisted under ~/.codealmanac/ and inspectable with codealmanac jobs, jobs show, jobs logs, jobs attach, and jobs cancel. Read commands query the derived index at ~/.codealmanac/repos/<repo-id>/index.db and need no provider login. Optional launchd automation scans Codex and Claude transcripts every 5 hours for sync, gardens each registered wiki every 24 hours, and checks for CLI updates daily. codealmanac serve renders pages, search, topics, backlinks, and file references in a read-only local browser UI.
- A team has source code but thin design docs and wants to convert PRs, commit ranges, and docs into a reviewable Markdown wiki via
codealmanac ingest. - A new engineer or agent needs the rationale behind a module and uses
codealmanac searchandcodealmanac showinstead of grepping the codebase. - A developer who lives in Codex or Claude Code lets scheduled transcript sync archive durable lessons into the matching registered repo wiki automatically.
- A wiki has grown noisy and needs
codealmanac gardento remove duplicates, fix weak links, and prune unsupported claims. - A team wants wiki edits to pass the same code review as source changes by committing the almanac/ directory to Git.
- Someone wants to browse and cross-navigate wiki pages in a browser without deploying a service, using
codealmanac serve.
Key setup facts
Pulled from the install and usage notes below. The project README has the current values.
- Install / run
uv tool install codealmanac@latest
- Runtime
- Python 3.12+
- Install notes cover
- macOS
How do you install or deploy this agent?
Requires macOS, Python 3.12+, uv, and an authenticated Codex or Claude Code CLI.
uv tool install codealmanac@latest
codealmanac setupInstall with recommended defaults using Codex as the runner:
codealmanac setup --yesSwitch to Claude as the runner:
codealmanac setup --yes --runner claudeMigrating from the retired npm package requires removing the old global install and its hooks first:
npm uninstall -g codealmanac
uv tool install codealmanac@latest
codealmanac setup --yes
codealmanac doctorUse codealmanac doctor afterward to verify the runner is available.
How do you use this agent?
Initialize and read a wiki in a repository:
cd your-repo
codealmanac init
codealmanac search "getting started"
codealmanac show getting-started
codealmanac serveIngest material and garden the wiki (requires an authenticated harness):
codealmanac ingest README.md --using codex
codealmanac ingest github:pr:123 --using claude
codealmanac garden --using codexFollow lifecycle runs:
codealmanac jobs
codealmanac jobs show <run-id>
codealmanac jobs logs <run-id>
codealmanac jobs attach <run-id>Inspect and adjust automation:
codealmanac automation status
codealmanac config set automation.sync.every 5h
codealmanac config set automation.sync.enabled falseDisable telemetry:
codealmanac config set telemetry.enabled falseWhat are this agent's strengths and limitations?
- The wiki is plain Markdown plus topics.yaml inside the repo, so it is committed and reviewed like code and not locked into a private format or hosted service.
- Work is organized around three explicit lifecycle agents (build, ingest, garden) with durable job records that can be followed via jobs logs and jobs attach.
- Read commands and the local viewer need no model credentials; only write-capable lifecycle commands require Codex or Claude.
- almanac-yoke provides a single provider boundary so Codex and Claude can be swapped in one CLI while reusing existing OAuth sessions.
- Optional anonymous telemetry is off-switchable and documented as never sending code, paths, prompts, transcripts, or command arguments.
- macOS-only today, requires Python 3.12+, and relies on launchd for scheduled automation.
- Lifecycle agents run with broad, non-interactive filesystem permissions; the almanac/ boundary is an instruction and commit policy, not an OS sandbox.
- Depends on a working, authenticated local Codex or Claude Code CLI, and broken installs (ENOENT) require manual reinstall.
- Migration from the retired npm distribution requires manually removing the old global package, hooks, and stray binaries.
- Documented defaults such as the model (gpt-5.5) track upstream tools, so behavior varies with the installed runner version.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| CodeAlmanac This agent | 51 · Major gaps | CLIFree + model costs | ★ 950 | 4mo ago | TypeScript | Codex · Claude Code |
| Yardlet | 80 · Good | Desktop appFree | ★ 46 | today | Swift | Codex · Claude Code |
| wsp | 59 · Major gaps | Desktop appFree + model costs | ★ 15 | 8d ago | TypeScript | Codex · Claude Code |
| Crew44 | 48 · Major gaps | Desktop appFree + model costs | ★ 358 | 5mo ago | Go | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Trust: the README states lifecycle agents run with 'broad, non-interactive filesystem permissions' and that the almanac/ boundary is an instruction/commit policy, not an OS sandbox, so least_privilege scores 1; setup/uninstall support --yes plus interactive confirmation and non-zero exit without --yes in non-interactive mode (per the uninstall plan), giving user_confirmation 2; telemetry is recommended-on by default but can be disabled via --no-telemetry, DO_NOT_TRACK, or config, and the README claims no code/path/prompt upload, so data_flow_transparency is 2 with a deduction for default-on; sensitive_data_handling is 1 because sync scans local Codex/Claude transcripts and the handling boundary for sensitive conversation content is thin; dependency_security is 1 because the dependency list includes posthog telemetry and almanac-yoke with no lockfile or vulnerability-audit evidence in the packet; external_effects is 1 because launchd jobs, auto-update, and auto-commit are default-on with large blast radius; rollback is 2 due to uninstall --yes, --no-auto-commit, jobs cancel, and Git-reversible wiki edits; source_attribution is 1 because only badges and a pyproject author field exist and publisher identity is unverified.
Reliability: AGENTS.md/CLAUDE.md still reference .almanac/, npm, TypeScript, and old paths that contradict the README's almanac/, PyPI, Python rewrite, so self_consistency is 1; dependency_availability is 2 given bounded version ranges and CI using uv sync --locked; failure_messages is 2 given Troubleshooting and doctor output.
Adaptability: audience_and_scenarios is 2 (AI coding agents and developers, macOS with Codex/Claude); capability_boundaries is 2 (Current Contract states local-only, no hosted, no MCP); trigger_precision is 2 (SKILL.md descriptions are specific); environment_fit is 1 because only macOS and two harnesses are supported.
Convention: information_architecture is 2 (clear README structure, tree, command tables); install_notes is 2 (install, setup, migration steps); naming_stability is 1 due to historical drift between almanac/codealmanac and .almanac/almanac; examples_and_faq is 2 (Quickstart, Troubleshooting, migration); known_limitations is 2 (macOS-only, local-only, no hosted); license is 3 (full Apache-2.0 text matching pyproject); versioning_changelog is 1 (version in pyproject but no CHANGELOG); maintenance_responsibility is 1 (author field and Discord/LinkedIn only, no explicit maintainer commitment).
Effectiveness: output_usability is 2 (CLI, jobs, viewer, JSON output); marginal_value is 2 (decisions/invariants beyond ordinary docs); cost_benefit is 1 because it requires local agents, scheduled jobs, and telemetry, raising cost.
Verifiability: claim_traceability is 1 (README claims are product descriptions without traceable test or benchmark evidence); cross_source_corroboration is 1 (docs/bugs and plans offer partial corroboration but are historical/planning documents); fact_inference_separation is 1 (docs mix facts with assertions such as 'more authoritative').
- Lifecycle agents run with broad non-interactive filesystem permissions; almanac/ is not an OS sandbox, so use only in repos where that trust model is acceptable.
- Setup installs launchd jobs (sync, garden, auto-update) and defaults auto_commit=true, which can auto-commit and auto-upgrade; disable or review explicitly.
- Telemetry is recommended-on by default; it can be disabled and claims no code/path/prompt upload, but confirm the configuration.
- AGENTS.md/CLAUDE.md still reference .almanac/, npm, and TypeScript, contradicting the README's Python/PyPI rewrite and potentially misleading agents.
- Publisher identity is unverified; dependencies include telemetry and third-party SDKs with no lockfile or vulnerability-audit evidence in the packet.
- Only macOS with Codex/Claude is supported; other environments are unsupported.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v0.4.4 CodeAlmanac 0.4.4
Release notes excerpt
Full Changelog: https://github.com/AlmanacCode/codealmanac/compare/v0.4.3...v0.4.4View on GitHub ↗ -
v0.4.3 CodeAlmanac 0.4.3
Release notes excerpt
Build, ingest, and garden are now packaged as a first-class Yoke agent collection. Stable instructions live in Yoke agent folders; lifecycle workflows send only typed runtime context. Removes the old prompt-rendering service, requires Yoke 0.1.5, preserves the previous instruction words exactly, and refreshes the canonical provider/agent architecture documentation.View on GitHub ↗ -
v0.4.2 CodeAlmanac 0.4.2
Release notes excerpt
Requires Yoke 0.1.4 so Codex internal message/reasoning lifecycle wrappers stay out of human-readable CLI and viewer activity. Real assistant text, tools, native subagents, statuses, and failures remain visible.View on GitHub ↗
FAQ
Does CodeAlmanac cost anything to use?
Does my code or wiki leave my machine?
How much filesystem access do the agents get?
Can I run it on Linux or Windows?
What happens if automation misfires?
codealmanac automation status shows installed schedules, codealmanac config set automation.<job>.enabled false disables one, and codealmanac uninstall --yes removes CodeAlmanac-owned local artifacts. Logs live under ~/.codealmanac/logs/.Is CodeAlmanac open source?
Is CodeAlmanac safe to use?
Is CodeAlmanac still maintained?
Who makes CodeAlmanac?
What is CodeAlmanac's official website?
Thanks — we use this to improve the page.