💸 tech-debt

A package manager for technical debt.

Every other package manager helps you add code. This one helps you add what you were going to add anyway.

---

What is this?

You already take on technical debt. You just do it informally — a // TODO here, a "temporary" workaround there, a // HACK: don't ask that has now outlived three managers.

tech-debt makes it official. It gives every shortcut a principal, an interest rate, and a daily-compounding balance, then tracks your total liability in a ledger you can be genuinely ashamed of. It is the only package manager whose dependency graph is your conscience.

Install

npm install -g tech-debt

Usage

Browse the debt catalog

td ls

Package	Principal	APR	Description
todo	$50	12%	a thing for later (later never comes)
fixme	$200	42%	a thing for now that became a thing for later
hack	$500	69%	works. nobody knows why. do not touch.
quick-fix	$1,000	120%	permanent, as all quick fixes are
temporary-workaround	$1,500	250%	load-bearing since 2019
rewrite-later	$5,000	420%	the most expensive promise in software

Take on debt

td install rewrite-later

  + took on rewrite-later (REWRITE)
    // REWRITE: the most expensive promise in software

  principal  $5,000.00   apr 420%   compounding daily
  debt ceiling raised to $5,000.00

  Interest begins accruing immediately. So does the guilt.

Check your balance (and your soul)

td status

  TECHNICAL DEBT STATEMENT

  TODO          12
  FIXME          7
  HACK           3
  REWRITE        1

  Debt ceiling:         $11,350.00
  Principal owed:       $11,350.00
  Interest accrued:     $4,209.55
  Total now owed:       $15,559.55

  Utilization: ████████████████████████ 137%

  Oldest debt:         HACK (412.0 days old, still here)
  Next payment due:    never
  Recommendation:      declare bankruptcy

The balance compounds daily. Leave the repo alone for a year and watch your rewrite-later quietly become a down payment on a house.

Run an audit

td audit

A rigorous, professional audit that — after careful analysis — always recommends doing nothing until next quarter. Then re-auditing. Forever.

Pay it down

td pay rewrite-later

  Scheduling debt repayment for…
  next sprint.

  (No debt was repaid. `td pay` is a no-op, faithfully modeling reality.)

Note

td pay is intentionally a no-op. We considered implementing real repayment, but added it to the backlog. It's scheduled for next sprint.

Declare bankruptcy (the Big Rewrite)

td bankruptcy

  CHAPTER 11: THE REWRITE

  23 debts discharged. The ledger is wiped clean.
  A brave new greenfield stretches before you.

  You will take on your first new debt within 3 days. We both know this.

How it works

State lives in a .techdebt.json ledger in your repo. Interest compounds daily via the same formula your credit card uses, applied to the same outcome:

owed = principal × (1 + apr/365) ^ daysSinceYouSaidYou'dFixItLater

The debt is real. The money is not. The shame is between the two.

The debt lifecycle

  td install todo ──▶ "I'll get to it"
        │
        ▼
  td install fixme ──▶ "okay this one's important"
        │
        ▼
  td install hack ──▶ "ship it, we'll clean up later"
        │
        ▼
  td status ──▶ 😬  (utilization: 340%)
        │
        ▼
  td audit ──▶ "recommend deferring to next quarter"
        │
        ▼
  td bankruptcy ──▶ THE REWRITE ──┐
        ▲                          │
        └──────────────────────────┘  (3 days later)

FAQ

Q: Does it actually scan my code for TODOs? A: No. That would be useful, and usefulness is a kind of debt we're not ready to take on.

Q: Can I pay off my debt? A: There is a pay command. It does nothing. This is the most realistic feature we shipped.

Q: Why does interest compound daily? A: Because so does the dread.

Q: Is the rewrite worth it? A: It never is, and you'll do it anyway. td bankruptcy is right there.

Roadmap

• td refinance — consolidate all TODOs into one enormous FIXME
• Credit score (starts at 850, only ever goes down)
• Slack bot that @-mentions you when interest accrues
• td blame — converts git blame into a payment-due notice
• // TODO: finish this roadmap

License

MIT. The license is free. The debt is not.

_{// FIXME: write a better tagline. (added 2026-06-24, still here)}