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

Complexity is measured exactly for Python (AST) and estimated for other code languages (JS/TS, Java, Go, Ruby, Rust, PHP, C/C++, C#, Kotlin, Swift…). A language DebtPilot can't analyse is marked unmeasured and its weight is redistributed — a file is never scored as "zero complexity = healthy" just because we couldn't read it.

---

Configuration & CI policy (debtpilot.toml)

Scaffold a per-repo policy and commit it:

debtpilot init-config

ignore = ["**/generated/**", "**/vendor/**"]   # top-level keys come first

[weights]                 # renormalised automatically
churn = 0.30
complexity = 0.25
lint = 0.20
todo = 0.15
staleness = 0.10

[thresholds]
alert = 65                # daemon alert level
fail  = 80                # `debtpilot cicd run` fails a file at/above this

[grades]                  # score <= value -> grade
A = 25
B = 45
C = 65
D = 80

[[waiver]]                # approved, time-boxed exceptions
path    = "legacy/importer.py"
reason  = "scheduled rewrite in Q3"
expires = "2026-12-31"    # after this, the gate fails again automatically

CI gate — fail on absolute debt, or ratchet so debt can't grow:

debtpilot cicd run --write-baseline          # record current scores
debtpilot cicd run --ratchet                 # fail if a file rose above baseline
debtpilot cicd run --fail-threshold 70       # or fail any file >= 70
debtpilot cicd run --sarif debt.sarif        # SARIF 2.1.0 for code scanning

Waived files stay in the report (marked, and suppressed in SARIF) but never fail the gate.

---

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)

0-BYOK — no API keys. The AI advisor runs on OnePort's managed models, metered against your account. Get a token at https://www.oneport.co.in/console, then:

onp account login <op_live_...> debtpilot ai src/payments.py

DebtPilot sends only the file context through the OnePort backend (metered to your account) and gets back exact fix suggestions with code examples and effort estimates. Static debt scoring works fully offline with no account.

---

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