TimeDebt

Makes invisible tech debt visible: every TODO, FIXME, and HACK shows how old it is and who wrote it, so stale comments actually get fixed.

A TODO written yesterday and a TODO written two years ago look identical in the editor. TimeDebt uses git blame to attach an age and an owner to every tracked comment, colors them by age tier, and gives you tools to hunt down the oldest ones first.

Features

Inline age decorations

Every tracked comment gets a subtle suffix rendered right in the editor:

// TODO: add retry logic for failed payments   -> 214d old, alice

Colored by age tier: fresh, aging, or stale
Falls back to file modification time when git or blame data is unavailable, and shows " -> unknown age" only when neither is available
Updates automatically as you open and edit files (debounced)
Toggle with TimeDebt: Toggle Inline Age Decorations or the timeDebt.inlineDecorations setting

Age tiers

Items are classified into three tiers with distinct, theme-friendly colors used in both the tree and the inline decorations:

Fresh -> younger than timeDebt.agingThresholdDays (default 7)
Aging -> between the two thresholds
Stale -> older than timeDebt.stalenessThresholdDays (default 30)

Hover details

Hover any tracked comment to see the keyword, full text, author, absolute date, age in days, and the short commit hash that introduced it.

Tech Debt tree view

Group by file, keyword, author, age tier, or a flat list sorted oldest-first
Per-group counts and stale counts in each group description
Filter to stale items only, or by a single keyword
Click any item to jump straight to the line

Top oldest

TimeDebt: Show Top Oldest Items opens a quick pick of the 10 oldest items in the workspace; picking one jumps to it.

Debt report

TimeDebt: Copy Debt Report builds a markdown table (keyword | age | author | file:line | text) sorted oldest-first and copies it to the clipboard, ready to paste into an issue or standup notes.

Status bar

The status bar shows N debt (M stale) and turns to the warning color whenever stale items exist. The tooltip breaks the count down per keyword, and clicking it focuses the Tech Debt view.

Performance

Workspace scans use VS Code's file search with your timeDebt.excludePatterns merged with files.exclude
One git blame call per file (porcelain output, parsed once for all lines)
Saving a file rescans just that file

Commands

All commands live under the TimeDebt category in the command palette:

Scan Workspace -> full rescan with a result toast
Refresh Panel -> quiet rescan
Show Top Oldest Items -> quick pick of the 10 oldest items
Copy Debt Report -> markdown table to the clipboard
Group By... -> file, keyword, author, age tier, or flat list
Filter by Keyword / Show Stale Items Only / Show All Items / Clear Filters
Toggle Inline Age Decorations
Enable or Disable
Jump to Item -> used internally when clicking tree items

Configuration

{
  "timeDebt.enabled": true,
  "timeDebt.keywords": ["TODO", "FIXME", "HACK", "XXX", "BUG", "NOCOMMIT"],
  "timeDebt.agingThresholdDays": 7,
  "timeDebt.stalenessThresholdDays": 30,
  "timeDebt.excludePatterns": ["**/node_modules/**", "**/dist/**", "**/.git/**"],
  "timeDebt.useGitBlame": true,
  "timeDebt.inlineDecorations": true
}

How it works

TimeDebt scans your workspace for comments containing tracked keywords
For each file with matches it runs a single git blame --porcelain call and maps every matched line to its author, date, and commit
When git is unavailable or the file is untracked, the file's modification time is used instead
Items are tiered as fresh, aging, or stale and shown in the tree, inline in the editor, on hover, and in the status bar

Getting started

Open the walkthrough via Help -> Welcome -> Get Started with TimeDebt, or just open the TimeDebt icon in the activity bar and run TimeDebt: Scan Workspace.

Requirements

VS Code 1.85.0 or higher
Git is optional; without it, ages fall back to file modification times

Tips

Run Show Top Oldest Items weekly and tackle one item per week
Group by author to route stale items to the person who wrote them
Paste the debt report into sprint planning to make the backlog visible

Author

Kanaihya Kumar - kanaihyakmr@gmail.com

License

MIT