📚 Almanac

Living, plain-English documentation for AI-built projects.

Almanac auto-creates and continuously keeps a hierarchy of project docs in sync with your code — through whatever coding agent you already use (Claude Code, Codex, Gemini) and whatever git host you push to.

Built for the people who increasingly build software without reading code.

Why

AI agents now write most of the code for a fast-growing group of builders — founders, designers, makers — who don't read code themselves. They ship real products, but they can't answer basic questions about their own project: What's wired to what? Which services am I paying for? Where do I change the checkout button? What happened last week?

The fix isn't "learn to code." It's documentation that writes and maintains itself — in language a non-coder understands.

Almanac turns a discipline (keep living docs in sync, forever) into a tool.

What you get

Running almanac init creates a tiered doc hierarchy and wires your coding agent to keep it current automatically:

| Doc | Tier | What it covers | | --- | ---- | -------------- | | ALMANAC.md | 0 | Index — a one-screen map of the whole project | | History.md | 1 | Append-only log of every interaction, decision, Q&A | | Knowledge_Base.md | 1 | The entire system explained for a layman, end to end | | Integrations.md | 2 | Every third-party service and how it's wired | | Frontend.md | 2 | Frontend architecture, stack, components, UI/UX | | Backend.md | 2 | Backend architecture, database, hosting, providers | | Code_Knowledge.md | 3 | Full codebase architecture, wiring, key functions | | Edit.md | 4 | Developer handbook: where do I change X? |

Read top-down by tier: Tier 1 reads like a book; Tier 4 is a developer handbook.

How it works

Almanac is open-core hybrid:

• The free core is agent-native. It ships a neutral DocSync spec + templates + a CLI. On init, it detects your coding agent and embeds a documentation contract into that agent's rules file (CLAUDE.md, AGENTS.md, GEMINI.md). From then on, your agent writes the docs as part of its normal work — so there are no API keys and no token cost beyond the agent you already run.
• Almanac Cloud (paid) adds the parts non-coders actually buy: a web dashboard to read the living docs without touching the repo, a git-provider app that regenerates docs on every push/PR in CI (managed LLM — works even with no local agent), and team features.

Install

npm install -g almanac-docs

Or run without installing:

npx almanac-docs init

Usage

almanac init      # scaffold the docs + wire your coding agent(s)
almanac status    # see which docs are missing or stale
almanac sync      # reconcile the agent contract + regenerate the index
almanac doctor    # diff code changes since last sync; flag which docs are stale
almanac watch     # remind you when source changes outpace the docs

In Claude Code, an /almanac-sync slash command and a Stop hook are installed: after every turn, almanac doctor checks whether your code changed in ways the docs don't reflect yet, so drift gets caught automatically.

Quickstart

cd my-project
npm install -g almanac-docs
almanac init                 # scaffolds docs/ + ALMANAC.md, wires your agent
# ...build with your AI agent as usual; it keeps the docs current...
almanac doctor               # what did my code changes leave stale?
almanac status               # presence + freshness overview

Force a specific agent if detection is ambiguous:

almanac init --agent cursor   # ids: claude-code, codex, gemini, cursor, windsurf, generic

Use doctor in CI (exits 2 when docs drifted):

almanac doctor --json

Configuration

Drop an optional almanac.config.json at your project root:

{
  "docsDir": "docs",
  "staleDays": 7,
  "exclude": ["Frontend.md"]
}

| Key | Default | What it does | | --- | --- | --- | | docsDir | "docs" | Folder for the docs. Set to "." to keep docs at the repo root (the ALMANAC.md index is always at the root). | | staleDays | 7 | Age (days) after which status flags a doc as stale. | | exclude | [] | Doc file names to skip entirely (the index is never excluded). |

Already keep your docs at the repo root? Use {"docsDir": "."} — Almanac will pick up your existing History.md, Knowledge_Base.md, etc. in place instead of creating a docs/ folder.

Gate PRs in CI

Catch doc drift before it merges. Add the Almanac Doctor action to a workflow:

# .github/workflows/docs.yml
name: Docs
on: pull_request
jobs:
  almanac:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0          # doctor needs history to diff the PR
      - uses: Aramide-TechExpert/[email protected]
        # with:
        #   fail-on-stale: "false"   # warn instead of failing

It diffs the PR against its base branch and fails the check when code changed in ways the docs don't reflect yet. Under the hood it runs almanac doctor --since <base> --json.

Supported agents

| Agent | Rules file wired | Status | | --- | --- | --- | | Claude Code | CLAUDE.md + /almanac-sync command + Stop hook | ✅ v0.1 | | Codex | AGENTS.md | ✅ v0.1 | | Gemini CLI | GEMINI.md | ✅ v0.1 | | Cursor | .cursor/rules/almanac.mdc (always applied) | ✅ v0.2 | | Windsurf | .windsurf/rules/almanac.md | ✅ v0.2 | | Cline | .clinerules (file or .clinerules/almanac.md) | ✅ v0.5 | | Aider | CONVENTIONS.md (load via --read) | ✅ v0.5 | | GitHub Copilot | .github/copilot-instructions.md | ✅ v0.6 | | Zed | .rules | ✅ v0.7 | | Roo Code | .roo/rules/almanac.md | ✅ v0.7 | | JetBrains Junie | .junie/guidelines.md | ✅ v0.7 | | Kilo Code | .kilocode/rules/almanac.md | ✅ v0.7 | | Any other agent | AGENTS.md (generic) | ✅ v0.1 |

The CLI auto-detects configured agents; force one with almanac init --agent <id> (ids: claude-code, codex, gemini, cursor, windsurf, cline, aider, copilot, zed, roo, junie, kilo, generic).

Roadmap

• [x] v0.1 — CLI core, DocSync spec, 8-doc hierarchy, multi-agent adapters
• [x] Claude Code Stop hook — runs almanac doctor automatically after each turn
• [x] almanac doctor — detect stale docs vs. git diff since last sync
• [ ] Almanac Cloud — web dashboard for non-technical readers (design doc)
• [ ] Git-provider app (GitHub / GitLab / Bitbucket) — CI doc regeneration
• [ ] Managed LLM fallback for agent-less / CI environments

Examples

Copy-paste recipes (first-time setup, CI PR-gating, config, JSON output) live in examples/.

Project docs

Almanac dogfoods itself — its own living docs live in docs/ and ALMANAC.md.

Contributing

Contributions are very welcome — especially new agent adapters. See CONTRIBUTING.md for setup, project layout, and how to add an adapter. Run npm test before opening a PR.

License

Apache-2.0 for the open-source core. Hosted/cloud components are separate commercial offerings.