DebtBomb is a cross-language technical-debt enforcement tool that scans source code comments for time-limited “debt bombs” and fails CI when they expire.

It lets teams ship temporary hacks safely by attaching an expiry date to them. When the date passes, the build fails — forcing the debt to be cleaned up instead of silently rotting forever.

Every codebase has comments like:

TODO: remove later
FIXME: temporary workaround

They almost never get removed.

DebtBomb gives those comments a deadline.

Temporary code is allowed — but it must be time-bounded, owned, and visible.

Install as a dev dependency to use DebtBomb without installing Go:

npm install -D debtbomb

You can then run it via npx:

npx debtbomb check

go install github.com/jobin-404/debtbomb/cmd/debtbomb@latest

If the debtbomb command is not found, add Go’s bin directory to your PATH:

macOS / Linux

echo 'export PATH="$HOME/go/bin:$PATH"' >> ~/.zshrc  # or ~/.bashrc
source ~/.zshrc

Windows Add %USERPROFILE%\go\bin to your PATH environment variable.

git clone https://github.com/jobin-404/debtbomb.git
cd debtbomb
go build -o debtbomb cmd/debtbomb/main.go

For a complete reference of all commands and flags, see CLI Reference.

debtbomb check

Fails with exit code 1 if any debt bomb is expired.

Warn before things explode:

debtbomb check --warn-in-days 7

This surfaces expiring debt in CI without blocking releases yet.

debtbomb list
debtbomb list --expired
debtbomb list --json

Generate a high-level summary of technical debt:

debtbomb report
debtbomb report --json

This shows debt breakdown by:

• Owner
• Folder/Module
• Reason
• Urgency (Expired, < 30 days, < 90 days)

DebtBomb looks for comments containing @debtbomb. It works with any language because it only reads comments.

Supported comment styles:

• //
• #
• --
• /* */

// @debtbomb(expire=2026-02-10, owner=pricing, ticket=JIRA-123)

// @debtbomb
//   expire: 2026-02-10
//   owner: pricing
//   ticket: JIRA-123
//   reason: Temporary surge override

Create a .debtbombignore file to exclude paths:

migrations/
legacy/
src/generated/*.go

DebtBomb skips files that are not human-written source.

Directories

• node_modules, vendor, .venv, __pycache__
• dist, build, out, target, bin, pkg, obj
• .git, .svn, .hg
• .idea, .vscode, .terraform

Files

• Images, videos, archives, executables
• PDFs and office documents
• Minified files (.min.js, .min.css)
• Lock files
• Any file larger than 1MB

This keeps it fast even on large repos.

MIT