Catch stale docs before they reach main.

DocDrift checks the code you changed against your README, docs, and examples, then flags documentation that is now wrong, incomplete, or missing.

What It Does

    Detects changed functions and classes from staged git diffs
    Finds related Markdown and RST docs with semantic search
    Uses AI to check whether the docs still match the code
    Suggests updated documentation and applies fixes interactively
    Flags undocumented new symbols
    Runs locally in the CLI and in GitHub Actions

Install

pip install docdrift

Quick Start

From inside your git repository:

git add . docdrift commit

That will:

    scan your staged code changes
    find related docs
    flag stale or missing documentation
    offer fixes interactively
    let you commit after review

AI Setup

For full documentation checks and autofixes, DocDrift needs an AI backend.

You have 2 options: Option 1: Groq

This is the easiest setup.

Set your API key:

export GROQ_API_KEY="your_key_here"

Then run:

git add . docdrift commit

Option 2: Local / Private AI

If you do not want to use a cloud API, you can use a local OpenAI-compatible endpoint such as:

    LM Studio
    Ollama-compatible OpenAI endpoint

On first run, DocDrift will ask for your endpoint and save it to:

.docdrift/config.json

Common endpoints:

    LM Studio: http://localhost:1234/v1/chat/completions
    Ollama-compatible endpoint: http://localhost:11434/v1/chat/completions
 

What Happens Without AI?

If you do not set GROQ_API_KEY and do not configure a local endpoint, DocDrift cannot run full AI consistency checks or generate fixes.

To get the real stale-doc detection and autofix workflow, you need one of:

    GROQ_API_KEY
    a local AI endpoint

Example

git add . docdrift commit

DocDrift scanning before commit...

Found 1 errors · 0 warnings · 1 undocumented

ERROR validate_token Docs: README.md:42 Docs still say the function returns bool, but the code now raises InvalidTokenError.

Fix this? (y/n): y Generating fix... README.md updated

Commit now? (y/n): y Committed

CLI

Check staged changes without committing:

docdrift check

Run the interactive commit flow:

docdrift commit

Rebuild the documentation index:

docdrift index

Run the pre-commit safety check manually:

docdrift precommit