CodeAlmanac

A living, Git-reviewed Markdown wiki that gives AI coding agents the decisions, flows, invariants and gotchas code alone cannot express.

Stars
★ 950
Last updated
4mo ago
License
Apache-2.0
Primary language
TypeScript

At a glance

How it runs
CLI
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
macOSPython 3.12+uvCodex CLI or Claude Code CLI (authenticated)Shell / CLINetwork accessLocal filesystem
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)

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.

  1. 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.
  2. A new engineer or agent needs the rationale behind a module and uses codealmanac search and codealmanac show instead of grepping the codebase.
  3. A developer who lives in Codex or Claude Code lets scheduled transcript sync archive durable lessons into the matching registered repo wiki automatically.
  4. A wiki has grown noisy and needs codealmanac garden to remove duplicates, fix weak links, and prune unsupported claims.
  5. A team wants wiki edits to pass the same code review as source changes by committing the almanac/ directory to Git.
  6. 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 setup

Install with recommended defaults using Codex as the runner:

codealmanac setup --yes

Switch to Claude as the runner:

codealmanac setup --yes --runner claude

Migrating 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 doctor

Use 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 serve

Ingest 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 codex

Follow 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 false

Disable telemetry:

codealmanac config set telemetry.enabled false

What are this agent's strengths and limitations?

Pros
  • 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.
Limitations
  • 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?

FollowAgents source review · FARS-2.1
Major gaps
51/ 100 5-point scale 2.6 / 5
Trust 13/29
Reliability 8/14
Adaptability 10/18
Convention 10/18
Effectiveness 7/13
Verifiability 3/8
Why each dimension lost points
Trust13 / 29 · 2.2/5

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.

Reliability8 / 14 · 2.9/5

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.

Adaptability10 / 18 · 2.8/5

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.

Convention10 / 18 · 2.8/5

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).

Effectiveness7 / 13 · 2.7/5

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.

Verifiability3 / 8 · 1.9/5

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').

Risks and how to mitigate them
  • 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.
Evidence confidence: Low Reviewed Nov 17, 2026 Reviewed revision 0f153501f40a
See the full review method →
Maintain this project? Add the FARS badge to your README

The badge shows the current review score and verdict and links back to this page. It refreshes about once an hour after a re-review.

FARS

[![FARS review](https://followagents.com/badge/codealmanac.svg)](https://followagents.com/en/agents/codealmanac)
<a href="https://followagents.com/en/agents/codealmanac"><img src="https://followagents.com/badge/codealmanac.svg" alt="FARS review"></a>

Recent releases

Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.

  1. v0.4.4 CodeAlmanac 0.4.4
    Release notes excerpt
    Full Changelog: https://github.com/AlmanacCode/codealmanac/compare/v0.4.3...v0.4.4
    View on GitHub ↗
  2. 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 ↗
  3. 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?
The CLI itself is free and open source under Apache-2.0. Write-capable commands call your already-authenticated Codex or Claude, so cost follows that provider's subscription or usage billing; read commands and the local viewer need no model credentials.
Does my code or wiki leave my machine?
The documented contract is local-only: the wiki is Markdown in your repo and runtime state sits under ~/.codealmanac/ with launchd scheduling. Optional anonymous telemetry sends controlled command and lifecycle outcomes plus sanitized crashes, and can be disabled at setup or later.
How much filesystem access do the agents get?
README states lifecycle agents run with broad, non-interactive permissions, and the almanac/ boundary is an instruction and commit policy rather than an OS sandbox. Run write commands only in repos where you accept that trust model, and review Git diffs when auto-commit is off.
Can I run it on Linux or Windows?
Not in the current release. Documented support is macOS with Python 3.12+, and automation is implemented as local launchd jobs.
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?
Yes. The source code is on GitHub (AlmanacCode/codealmanac) under the Apache-2.0 licence.
Is CodeAlmanac safe to use?
FollowAgents' FARS review (Nov 17, 2026) scored CodeAlmanac 13/29 on trust and safety. None of the eight safety controls the review checks for was missing outright.
Is CodeAlmanac still maintained?
Development has slowed: the latest commit on GitHub is from 2026-07-17, within the last six months but not the last 30 days. The latest release is v0.4.4 (2026-07-11).
Who makes CodeAlmanac?
CodeAlmanac is published on GitHub by the account AlmanacCode. FollowAgents has not verified which person or company is behind that account.
What is CodeAlmanac's official website?
The project's GitHub repository lists https://codealmanac.com as its website. That link is set by the repository owner; the source code itself is on GitHub (AlmanacCode/codealmanac).
Was this page helpful?
View on GitHub ↗ Install ↓

Host ecosystems

Compare agents like this one

The same FARS review applied across the shortlist this agent qualifies for.

Related concepts