docs-keeper

Documentation that can’t drift from the code.

Docs are written once and left behind. The code moves on; the docs don’t. By the time someone reads one, it may already be wrong — and no one can tell which line went stale.

docs-keeper makes docs a maintained system.

Why docs-keeper

• 🔁 Both-way sync — Change the code or the docs; docs-keeper pulls the other side back into step. Neither silently drifts.
• 🛡️ Commit-time gate — Drift can't sneak in. The commit blocks (or warns) the moment docs fall behind, and names exactly what to fix.
• 🗂️ Hierarchical index — An LLM finds the right doc in seconds — a map at every level it walks top-down. No grep, no whole-repo dump.
• 🔌 No MCP, no server — The index is plain index.md in your repo. Nothing to host or keep alive — unlike servers like mcp-server-markdown.
• 📒 Sources-of-truth registry — Your host prompt's canonical references stay current on their own.
• 🎯 Deterministic — Same tree, same index, every time. Computed by the engine — no LLM guesswork.
• ♻️ Incremental — Only what changed gets reindexed. Never a full rebuild.
• 🌐 Platform-agnostic — Stack-, domain-, and host-neutral core. Claude Code today; adapters stay thin.

Install

docs-keeper installs per repository, not per user — so the whole team (and CI) picks it up from one committed config. Run these in the repo you want to steward:

claude plugin marketplace add kostiantyn-matsebora/docs-keeper
claude plugin install docs-keeper@docs-keeper --scope project

--scope project writes the enablement into the repo’s .claude/settings.json — commit that file and every collaborator gets docs-keeper automatically. A plain /plugin install inside a session enables it for you only; use project scope so it travels with the repo.

The repo is public — marketplace add works for anyone; no access request needed.

Installing registers the agent, the /docs-keeper:* commands, and the commit/session hooks. It doesn’t touch your repo yet.

Set up (once)

Run once in the repo you want to steward:

/docs-keeper:setup            # whole repo
/docs-keeper:setup docs/      # or scope to specific doc roots

setup reaches a green baseline: it creates .docs-keeper/config.json, finds or creates your host prompt (CLAUDE.md), builds the index.md indexes, seeds the “Sources of truth” section, and verifies there’s no drift. It’s idempotent — re-running on a green repo changes nothing.

Everyday use

After setup, maintenance is automatic at commit time:

1. Edit docs (or code + docs) and run git commit.
2. In strict mode the drift gate blocks the commit and prints the exact fix queue.
3. The agent runs the queued maintenance (incremental — only what changed).
4. Re-stage and re-commit — the gate is clean and the commit lands.

Set warn mode if you’d rather be advised without blocking. The agent never commits for you — you own the commit.

Commands

Configuration

Settings live in .docs-keeper/config.json — a small, committed, per-repo file:

{
  "enforcement": "warn",
  "paths": ["**/*.md"]
}

• enforcement — warn advises without blocking; block fails the commit (exit 2) on drift.
• paths — globs docs-keeper watches and indexes (default: every Markdown file). Narrow it (["docs/**/*.md"]) or add more (["docs/**/*.md", "adr/**/*.md"]).

Edit it directly, or use the command:

/docs-keeper:config                                 # show current settings
/docs-keeper:config enforcement block               # switch enforcement
/docs-keeper:config paths docs/**/*.md adr/**/*.md  # replace the watch globs

Per-machine runtime state (session / capture files) lives under .docs-keeper/sessions/ and stays gitignored — only config.json is committed.

Use it in CI (no plugin needed)

The engine ships a host-neutral drift gate (stdlib-only Python 3.11+) — no Claude Code, no plugin. Check docs-keeper out alongside your repo and point the gate at your repo root:

# .github/workflows/docs-drift.yml — in YOUR repo
- uses: actions/checkout@v4                        # your repo, into the workspace
- name: Fetch the docs-keeper engine
  run: git clone --depth 1 https://github.com/kostiantyn-matsebora/docs-keeper /tmp/docs-keeper
- name: Drift gate
  run: python3 /tmp/docs-keeper/core/engine/cli.py --drift-only --repo-root . --enforce block

--repo-root is the repo to check (. = your checkout); --enforce warn|block mirrors your .docs-keeper/config.json. Exit 0 (clean) or 2 (drift; message on stderr).

Alternatives & comparison

docs-keeper occupies a niche no single tool covers: agent-native, in-repo, structural documentation stewardship. Adjacent tools each cover one slice; none unify INDEX + REVISE + REGISTER + DRIFT GATE + CAPTURE + SWEEP.

Where docs-keeper wins:

• Commit-time drift gating wired into coding-agent hooks.
• Hierarchical index.md generation with ancestor walk-up.
• Agent-native decision capture during coding sessions.
• Platform-neutral core + thin adapters.

Where established tools still lead: hosting, versioning, ecosystem breadth, and non-Markdown/API docs.

Troubleshooting

• The commit gate didn’t fire. It only runs when Claude Code runs git commit (a PreToolUse hook), and only when staged files match your paths globs. A code-only change with the default ["**/*.md"] won’t trip it.
• setup left drift. Re-run /docs-keeper:setup — it converges to green and is idempotent.
• Plugin shows “failed to load”. Re-install: /plugin install docs-keeper@docs-keeper. Hooks load from the plugin’s standard hooks/hooks.json.
• Want a stricter repo. /docs-keeper:config enforcement block makes commits fail on drift.

Questions or issues? See the repository.