DebtPilot

Track technical debt before it blows up in production.

Every IDE catches syntax errors. DebtPilot does something no IDE can — it knows that payments/stripe.js has been edited 30 times by 4 different developers, has a TODO from 8 months ago, and a complexity score of 24. That combination is your next production incident.

Install

pip install debtpilot

Full install (file watcher + live notifications):

pip install "debtpilot[full]"

Quickstart — 4 commands, done

1. Scan your project debtpilot scan .

2. See the report debtpilot report

3. Block bad commits automatically debtpilot hook --install

4. Start live background watching debtpilot start --dir .

What it does

Debt Score (0-100)

Score = weighted combination of: git churn (30%) + complexity (25%) + lint issues (20%) + stale TODOs (15%) + staleness (10%).

Where your data lives

Scan results are stored per project, in a .debtpilot/ folder at your project root (found the same way git finds its root). Two different projects scanned on the same machine never share data. The folder self-ignores via its own .gitignore, so you'll never accidentally commit your scan database.

Your global settings (Gemini API key, email digest config) live separately in ~/.debtpilot/config.json — those are per-user, not per-project.

AI Fix Suggestions (optional)

Get a free Gemini API key at aistudio.google.com then:

debtpilot config --gemini-key YOUR_KEY debtpilot ai src/payments.py

DebtPilot sends the file context to Gemini and gets back exact fix suggestions with code examples and effort estimates.

Weekly Email Digest

debtpilot config --gmail you@gmail.com --gmail-password YOUR_APP_PASS --recipients team@company.com debtpilot digest --send

Use a Gmail App Password from: myaccount.google.com/apppasswords

Auto-start on Windows login

debtpilot autostart --install --dir .

DebtPilot will start silently in the background every time Windows starts. No manual debtpilot start needed.

Requirements

• Python 3.10 or higher
• git in PATH
• pylint / mypy / eslint — optional, for richer lint scores

License

MIT