Stable

driftryanwaits/drift

Your code changed. Your docs didn't.

GitHubDemo ↗

Problem
JSDoc, examples, and markdown fall out of sync with your actual API.
Detect
drift scan finds 17 drift types across 4 categories.
Surfaces
One engine, three truths: TypeScript packages, OpenAPI specs, Clarity contracts.
Output
{ok, data, meta} JSON to stdout, with file and line.
Agents
Ships as a Claude Code skill and an MCP server — /drift inside any TypeScript project.
The Problem

Your Code Changed. Your Docs Didn't.

JSDoc says one param, function takes three. @example blocks reference APIs you removed last sprint. Markdown docs import exports that no longer exist. Nobody knows until a user files an issue.

src/index.ts
/** @param x - the first number */

export function calculate(x, y, opts) {

  // JSDoc: 1 param. Code: 3 params.

}



/** @example

 * transform(input, { mode: "fast" })

 * // 'mode' option was removed in v2

 */

export function transform(input) {}
Detect It

drift scan

23 commands, one engine, three truth surfaces — TypeScript packages, OpenAPI specs, Clarity contracts. 17 drift types across 4 categories: structural (JSDoc vs code), semantic (deprecation, broken links), example (code errors), and prose (stale markdown references, deprecated-API mentions).

Terminal
drift scan



# Extracting API spec...

# Checking coverage...

# Cross-referencing JSDoc vs code...

# Validating examples...

# Scanning prose for stale refs...
The Output

Structured, Not Prose

All commands output {ok, data, meta} JSON to stdout. Every drift issue includes filePath and line — agents read the diagnosis, then edit code directly. Detection is the tool's job. Mutation is the agent's job.

Terminal
DRIFT SCAN



Coverage:   ████████░░░░░░░░░░░░  42%



structural  7 issues  (param mismatch, type drift)

semantic    3 issues  (broken @link, deprecation)

example     4 issues  (typecheck failures)

prose       3 issues  (stale markdown refs, deprecated mentions)



17 drift issues found — each with filePath + line for agent fixes
Agent Usage

Built for /drift

Ships as a Claude Code skill and an MCP server. Install the skill, then /drift inside any TypeScript project — or add the MCP server for tool-level access. Every primitive is individually addressable — scan is a convenience, not a gate.

Terminal
/drift              # status check, auto-init

/drift fix          # lint → fix JSDoc signatures

/drift enrich       # coverage → add missing JSDoc

/drift review       # PR documentation impact

/drift release      # pre-release audit

/drift docs/        # scan external docs for stale refs



# MCP server — drift_scan, drift_diff, drift_breaking...

claude mcp add drift -- drift mcp



# Machine-readable command discovery

drift --tools
Get Started

Adopt It

Entry auto-detects from package.json. Three steps to a CI gate that actually catches doc regressions.

  1. 1

    Run a scan

    Full package audit — coverage, lint, prose drift, health.

    Terminal
    drift scan
  2. 2

    Set a baseline

    Pick a coverage floor you can actually hold today.

    Terminal
    drift ci --all --min 80
  3. 3

    Gate pull requests

    Add the GitHub Action so regressions fail CI, not code review.

    .github/workflows/ci.yml
    - uses: ryanwaits/drift/action@v1

      with:

        min-coverage: 80