ai-drift

Detect code quality degradation during AI-assisted development sessions.

When you use AI coding assistants extensively, your codebase can accumulate technical debt: unused imports, duplicate code patterns, functions that grew too large, excessive error handling, and more. This tool helps you track and fix that drift.

The Problem

As @tom_doerr put it: "LLM coding assistants try to solve problems by adding 20 new lines of code; works great for a while, but after 50+ edits your codebase becomes a superfund site."

ai-drift helps you catch this before it becomes unmanageable.

Installation

npm install -g ai-drift

Or run directly with npx:

npx ai-drift check

Quick Start

1. Create a baseline before your AI coding session:

ai-drift init

2. Do your AI-assisted development work...

3. Check for drift:

ai-drift check

4. Auto-fix simple issues:

ai-drift clean

Commands

init

Create a baseline snapshot of your current codebase state.

ai-drift init [options]

Options:
  -p, --path <path>        Path to analyze (default: ".")
  --include <patterns>     File patterns to include (default: "**/*.{js,ts,jsx,tsx,py,go,rs}")
  --exclude <patterns>     File patterns to exclude (default: "**/node_modules/**,...")

check

Compare current state to baseline and detect drift.

ai-drift check [options]

Options:
  -p, --path <path>        Path to analyze (default: ".")
  --json                   Output as JSON
  --threshold <number>     Minimum severity to report, 1-5 (default: 2)

status

Quick drift status summary.

ai-drift status

report

Generate a detailed drift report.

ai-drift report [options]

Options:
  -p, --path <path>        Path to analyze (default: ".")
  -o, --output <file>      Output file (default: stdout)
  --format <format>        Output format: text, json, markdown (default: "markdown")

clean

Auto-fix simple drift issues.

ai-drift clean [options]

Options:
  -p, --path <path>        Path to analyze (default: ".")
  --dry-run                Show what would be fixed without making changes
  --aggressive             Enable aggressive fixes (may change code behavior)

What It Detects

Issue Type	Description	Severity
Line Growth	Files that grew significantly	3-4
Complexity Increase	Cyclomatic complexity growth	3-4
Deep Nesting	Excessive nesting levels	3-4
Excessive Try-Catch	Overuse of error handling	2
TODO Accumulation	New TODO/FIXME comments	1
Function Proliferation	Too many new functions	2
Import Growth	Many new imports (may be unused)	2
Long Lines	Lines over 120 characters	1
Magic Numbers	Hardcoded numeric values	2

Drift Score

The drift score (0-100) combines:

• Issue severity and count
• Complexity increase ratio
• Percentage of files affected
• Net line growth

Score	Status
0-19	Healthy - no action needed
20-49	Some drift - consider review
50-100	Significant drift - cleanup recommended

Supported Languages

• JavaScript / TypeScript (.js, .ts, .jsx, .tsx)
• Python (.py)
• Go (.go)
• Rust (.rs) - basic support

Best Practices

1. Run ai-drift init at the start of each AI-heavy coding session
2. Check drift periodically during long sessions
3. Run ai-drift clean --dry-run before committing
4. Create a new baseline after major refactors

CI Integration

Add to your CI pipeline to catch drift before merge:

# .github/workflows/drift.yml
name: AI Drift Check
on: [pull_request]
jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g ai-drift
      - run: ai-drift init
      - run: ai-drift check --threshold 3

Example Output

ai-drift check

  Detected 5 drift issue(s)

  src/api/handlers.ts
    ○ File grew by 87 lines
    ● Complexity increased by 15

  src/utils/parser.ts
    ● Added 4 new try-catch blocks
    ○ 3 new lines over 120 characters

  ──────────────────────────────────────────────────
  Drift Score: 34/100
  Files affected: 2
  Lines changed: +112 / -3

License

MIT