livedocs

Notes that know when the code moved on.

livedocs binds Markdown notes (an Obsidian vault, or any folder of .md files inside a repo) to the code they mention, and makes the git commit the place where notes and code are reconciled. It is a thin layer over Fiberplane drift (which fingerprints symbols) that adds what an agent-written vault needs:

• Anchors derived from the note's own backtick mentions — nothing to declare by hand.
• A note hash and member-level hashes in append-only stamps, so "this note was verified against this code" is a recorded fact, and only changes to what the note actually mentions count.
• A git pre-commit gate: a commit that changes code a note mentions is blocked until the note is updated or acked with a reason. Provably benign changes (comment-only edits, pure moves, changes to members the note doesn't mention) are acked mechanically. unknown never blocks.
• A read-time report for agents: CHANGED with was / now pinned to the note lines that mention the symbol — a fact, not a verdict. The agent that made the change decides what the note should say.
• Coverage: which of a note's code claims are anchored, and which names it uses that no longer exist.

The guarantee is a mechanism of the development framework (git), not a capability of any agent: it holds for Claude Code, Codex, a human at a terminal, or anything else that commits.

New project? One command

livedocs new-vault docs/vault --scaffold-modules

creates an Obsidian vault (Home.md, Modules/ Concepts/ Reference/ Sessions/ Templates/, a minimal .obsidian/), one empty note per source module, the livedocs config (sessions, reviews and templates are snapshots), the git gate, the Claude Code adapter, and an AGENTS.md block — then commit. Open the folder in Obsidian as a vault. From there: write notes, commit, reconcile when the gate says so.

Install

brew install fiberplane/tap/drift          # or: curl -fsSL https://drift.fp.dev/install.sh | sh

Then livedocs itself, from PyPI (stdlib only, no Python dependencies):

uv tool install livedocs                   # or: pipx install livedocs

To hack on it: uv tool install --editable /path/to/vault-drift.

Then, in the repository that holds the vault:

livedocs init --vault docs/vault           # git gate (.githooks + core.hooksPath), .livedocs/config.json,
                                           # Claude Code Stop heads-up (settings.local.json), AGENTS.md block

That is the whole setup. Notes are stamped by the commit that adds or edits them: write a note, commit it, and the gate binds its code mentions and records the stamp in the same commit. For an existing vault, git add the notes and commit once (or run livedocs stamp <note> per note to see what each binds). Each clone activates the versioned hook with git config core.hooksPath .githooks (init does it). --repo defaults to the current git repository and --vault to the configured one, so inside the repo the commands need no arguments.

The commit flow

edit code ──► git commit
              │  gate: notes that mention the changed code, not yet reconciled?
              ├─ none / benign ────────────────────────────────► commit passes (benign ones auto-acked;
              │                                                   new or edited notes stamped)
              └─ some ──► "CHANGED: <note> … was: … now: … note lines 13, 30"
                          edit the note and commit again          (the commit stamps it)
                          or, still correct:  livedocs stamp <note> --ack --reason "…"; git add -A; commit

livedocs affected lists the notes your uncommitted changes touch before you get there.

Commands

Snapshot notes

Dated records — reviews, session logs, reports — describe the code as it was. Mark them with livedocs: snapshot in the frontmatter, or list globs in .livedocs/config.json:

{ "vault": "docs/vault", "snapshot_globs": ["Reference/Review *", "Sessions/*"] }

They bind nothing, report snapshot, and never block.

Secret scanners

drift.lock and <vault>/.livedocs/stamps.jsonl hold fingerprints — hashes of your own code's syntax trees. Anyone who can read them can read the code they were computed from; they grant access to nothing. Secret scanners can still misread a hash next to a name like get_access_token as a leaked token. Since 0.1.3, stamps tag every fingerprint (drift:…, ast:…) and store members as pairs so they don't have that shape, and init / new-vault add both files to .gitguardian.yaml's secret.ignored_paths, which ggshield (pre-commit, CI) reads. If you use the GitGuardian dashboard's repository monitoring, add the same two paths as exclusions in its workspace settings, and mark any earlier alert on these files as a false positive. drift.lock itself is drift's format and still holds bare sig = "<hex>" values.

CI

Pre-commit is skipped by --no-verify, merges and rebases. Run the same check in CI:

# .github/workflows/livedocs.yml
name: livedocs
on: [push, pull_request]
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: curl -fsSL https://drift.fp.dev/install.sh | sh && echo "$HOME/.local/bin" >> "$GITHUB_PATH"
      - uses: astral-sh/setup-uv@v5
      - run: uv tool install livedocs
      - run: livedocs verify --repo . --vault docs/vault

Or with the pre-commit framework, add to .pre-commit-config.yaml:

- repo: https://github.com/GusEllerm/vault-drift
  rev: v0.1.0
  hooks: [{ id: livedocs-gate }]

What it can and cannot guarantee

• It guarantees that a committed note has been vouched for against the code it mentions, at that commit. A read-time changed means the working tree has moved since.
• It sees code the note names in backticks. A prose claim with nothing to anchor ("tokens rotate every 15 minutes") is reported unknown, never fresh. livedocs coverage shows how much of each note that is.
• It does not follow the call graph: a note's claim about what a function does can go stale when a callee changes. That is the residual miss class, measured at about 1 in 20 real changes on the reference history.
• Python only, for now (symbol resolution uses ast; drift fingerprints six languages).
• Code is discovered wherever it lives — src/, benchmark/src/, a flat package — excluding tests, environments, build output and docs. To pin it, set "code_roots": ["lib", "services/api"] in .livedocs/config.json.

Background

Design, decisions and the measurements behind every choice live in the vault at live-docs-vault/ (start at Start Here.md). The short version: on a real 141-commit history, the hash flagged 22 of the 23 note-invalidating changes an anchor covered; only ~5% of flags marked a change that made a note wrong — which is why the signal is delivered as a fact at commit time, to the agent that has the context, and never as a verdict.