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.
pip install debtpilot
Full install (file watcher + live notifications):
pip install "debtpilot[full]"
-
Scan your project debtpilot scan .
-
See the report debtpilot report
-
Block bad commits automatically debtpilot hook --install
-
Start live background watching debtpilot start --dir .
| Command | What happens |
|---|---|
debtpilot scan . |
Scores every file 0-100 for technical debt |
debtpilot report |
Shows top debt files in a ranked table |
debtpilot file <path> |
Deep breakdown of one file |
debtpilot ai <path> |
AI explains exactly what to fix (needs Gemini key) |
debtpilot predict |
Predicts which file will cause your next bug |
debtpilot dashboard |
Generates an HTML dashboard — open in browser |
debtpilot report-pdf |
Generates a print-ready PDF report |
debtpilot alerts |
Shows active danger alerts |
debtpilot todos |
Lists stale TODOs by age |
debtpilot hook --install |
Blocks commits above the debt threshold |
debtpilot start |
Starts live file watcher + WebSocket server |
debtpilot status |
Full health check of your DebtPilot setup |
debtpilot digest --send |
Sends weekly email summary to your team |
| Grade | Score | Meaning |
|---|---|---|
| A | 0-25 | Healthy |
| B | 26-45 | Watch |
| C | 46-65 | Concerning |
| D | 66-80 | Dangerous |
| F | 81-100 | Critical — fix before next deploy |
Score = weighted combination of: git churn (30%) + complexity (25%) + lint issues (20%) + stale TODOs (15%) + staleness (10%).
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.
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
debtpilot autostart --install --dir .
DebtPilot will start silently in the background every time Windows starts. No manual debtpilot start needed.
- Python 3.10 or higher
- git in PATH
- pylint / mypy / eslint — optional, for richer lint scores
MIT