Documentation

01Installation

Homebrew (recommended)

$ brew install greatnessinabox/tap/drift

Shell script

$ curl -fsSL https://raw.githubusercontent.com/greatnessinabox/drift/main/install.sh | sh

On macOS, if you download drift manually from GitHub Releases, you may need to allow it inSystem Settings → Privacy & Securityor run xattr -d com.apple.quarantine $(which drift). The Homebrew and shell script installers handle this automatically.

Go install

$ go install github.com/greatnessinabox/drift/cmd/drift@latest

Build from source

$ git clone https://github.com/greatnessinabox/drift.git
$ cd drift
$ go build ./cmd/drift/

Verify it works

$ drift --version
drift v1.0.0

02Quick Start

# Run the live dashboard in any supported project
$ cd your-project
$ drift

# Generate a report
$ drift report

# Check health (for CI)
$ drift check --fail-under 70

# Interactive fix with GitHub Copilot CLI
$ drift fix

drift auto-detects the language by checking for manifest files (go.mod, package.json, Cargo.toml, pyproject.toml, pom.xml, Gemfile, composer.json, *.csproj). Supports Go, TypeScript/JavaScript, Python, Rust, Java, Ruby, PHP, and C#.

03Configuration

Create a .drift.yaml in your project root. All fields are optional — drift works with zero config.

# Language (empty = auto-detect)
language: ""

# Directories to exclude
exclude:
  - vendor
  - node_modules
  - .git
  - __pycache__
  - target

# Metric weights (must sum to 1.0)
weights:
  complexity: 0.30
  deps: 0.20
  boundaries: 0.20
  dead_code: 0.15
  coverage: 0.15

# Architecture boundary rules
boundaries:
  - deny: "pkg/api -> internal/db"
  - deny: "cmd -> internal/tui"

# AI diagnostics (optional)
ai:
  provider: anthropic  # or "openai"
  model: ""            # uses sensible defaults

# Thresholds
thresholds:
  max_complexity: 15
  max_stale_days: 90
  min_score: 70

04CLI Reference

05Health Metrics

The overall health score is a weighted average of five dimensions. Weights are configurable in .drift.yaml.

06AI Diagnostics

Press d in the dashboard to trigger an AI diagnosis. The AI analyzes your worst-scoring metrics and provides specific, actionable recommendations with code snippets.

Supported providers

# .drift.yaml
ai:
  provider: anthropic  # or "openai"
  model: ""            # uses sensible defaults

07GitHub Copilot Integration

Interactive fixing

$ drift fix

  Analyzing codebase... (Score: 78/100)

  Found 3 issue(s) to fix:
  1. [HIGH] model.Update() in app.go:126 (complexity: 25)

  Asking GitHub Copilot for suggestions...
  Apply this suggestion? [y/N/s(kip rest)]

Custom agent

$ copilot --agent drift-dev "analyze internal/tui/app.go"
$ copilot --agent drift-dev "suggest refactoring for Update()"
$ copilot --agent drift-dev "help me add C# analyzer support"

Requires brew install copilot-cli. drift also works with any AI coding assistant — see the multi-agent guide.

08CI/CD

Basic GitHub Action

# .github/workflows/drift.yml
name: Code Health
on: [pull_request]

jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
      - run: go install github.com/greatnessinabox/drift/cmd/drift@latest
      - run: drift check --fail-under 70

Advanced: JSON snapshot

$ SCORE=$(drift snapshot | jq '.score.total')
$ LANG=$(drift snapshot | jq -r '.language')
$ echo "Language: $LANG, Score: $SCORE"

09Keyboard Shortcuts

10Compatibility

drift is a single static binary with zero runtime dependencies. No Node.js, no Python runtime, no Docker. Just download and run.

11FAQ & Troubleshooting