driftless

Driftless tells you when Markdown docs may be stale.

You point a doc at the code it describes. Driftless saves the reviewed source hash in .driftless.lock. Later, when that source changes, driftless check points back to the exact doc section that needs review.

It does not decide whether prose is correct. It creates a fast review tripwire so docs are checked while code is still being changed.

Install

Install the latest GitHub Release:

curl -fsSL https://raw.githubusercontent.com/akshay5995/driftless/main/install.sh | sh

For pinned versions or a custom install directory, see the installer options. Prebuilt archives and checksums are available on GitHub Releases.

Basic Loop

Print the setup prompt for an agent:

driftless init

You can also point an agent at docs/setup-prompt.txt. The prompt checks whether Driftless is installed, installs the latest GitHub Release when needed, and verifies the CLI before configuring the repository.

After adding useful refs and reviewing the docs:

driftless update

While working:

driftless check
driftless check --json

Run driftless update only after the docs and source have been reviewed. Do not use it just to silence failures.

Add Refs

Inline refs:

Login is handled by `src/auth.py#AuthService.login`.

Markdown links stay clickable:

See [login](../src/auth.py#AuthService.login).

Fenced code refs work when prose is attached to a snippet:

```python ref=src/auth.py#AuthService.login
def login(self, user, password): ...
```

Supported source files: Go, Java, Kotlin, Python, Ruby, Rust, TypeScript, TSX, JavaScript, and JSX.

What Fails

A clean check:

driftless: ok

If a referenced symbol changes:

error    README.md:42 src/lib.rs#login signature changed (... -> ...); update docs, then `driftless update`
driftless: 1 error(s)

For agents, JSON output includes the stale doc section and current source:

[
  {
    "status": "body_drift",
    "ref": "src/lib.rs#login",
    "doc": { "file": "README.md", "line": 42 },
    "symbol_source": "pub fn login(...) { ... }"
  }
]

Editor

Driftless includes an LSP server over stdio:

driftless lsp

The editor path uses the same checker as the CLI and can report diagnostics while source buffers are still unsaved.

Documentation

• Agent setup prompt — self-contained instructions that install Driftless when needed and add it to a repository.
• Architecture — how Markdown refs are extracted, resolved, hashed, and checked.
• Development — local verification, dogfooding, and the release process.
• Benchmarking — performance scenarios, baselines, and measurement guidance.
• Contributing — how to propose and validate changes.