debtpilot 0.1.0

Track technical debt before it blows up in production

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

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

---

Debt Score (0-100)

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%).

---

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 [e-mail] --gmail-password YOUR_APP_PASS --recipients [e-mail] 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