Track TODO age in codebases with a zero-deps CLI

The first time you stumble across a TODO comment buried in legacy code, your heart sinks. Not because the task seems difficult, but because the comment lacks context—no author, no date, and no urgency. Over time, these ambiguous notes accumulate like digital cobwebs, silently inflating technical debt until no one dares touch them. But what if every TODO in your repository could reveal its true age and author in seconds?

That’s the promise behind todoage, a lightweight command-line tool that scans your entire codebase for markers like TODO, FIXME, and HACK, then cross-references them with git blame to expose their real timeline. Instead of guessing whether a comment is a week old or a year old, the tool delivers a clear, actionable report—highlighting stale markers that need your attention now.

From guesswork to git blame: solving the TODO mystery

Most developers have written a TODO comment at some point, only to leave it behind as priorities shift. Over time, these markers become invisible infrastructure—part of the codebase’s furniture. While tools like grep can surface them quickly, they offer no insight into when or by whom the comment was added.

Enter git blame. The command is powerful, but running it manually on every TODO line is impractical. todoage automates this process, scanning your entire repository for case-sensitive uppercase tags (TODO, FIXME, HACK, XXX, BUG) within actual comment blocks (//, #, /* */, `, --, ;, leading *). It then runs git blame` on each match and sorts the results by age, making it trivial to identify the oldest and most neglected items.

todoage
AGE TAG LOCATION AUTHOR TEXT
365d TODO src/api/legacy.js:42 Jordan Dev Clean up deprecated endpoint
180d FIXME src/utils/cache.js:15 Lee Dev Handle race condition in cache invalidation
7d HACK src/frontend/error.tsx:92 Maya Dev Workaround for upstream API delay

Markers older than a configurable threshold appear in red, immediately drawing your eye to the debt that matters most.

Why existing tools fall short in CI pipelines

A handful of alternatives exist, but none quite fit the bill for developer workflows that rely on automation and continuous integration (CI). Tools like tickgit once promised blame-based age tracking but stalled in development. Meanwhile, VS Code’s todo-tree plugin excels at surfacing TODO markers inside the editor—useful for individual developers, but not designed for CI gates or team-wide reporting.

todoage bridges this gap. It’s purpose-built for the command line, outputs structured JSON for dashboards or Slack bots, and can fail builds when stale markers cross a defined age limit. This makes it ideal for enforcing coding standards in automated pipelines.

# Fail CI if any TODO is older than 90 days
todoage --max-age 90d --fail-on-stale

With support for flexible time formats (90d, 6m, 1y), the tool adapts to any team’s definition of "stale."

Focused filtering for precise action

Not all TODO markers deserve equal attention. Some are urgent. Some are legacy artifacts. Others are tied to specific authors or modules. todoage includes filtering options to help teams prioritize:

• Filter by tag: todoage --tags FIXME
• Filter by author: todoage --author alice
• Export to JSON for dashboards: todoage --json | jq '.items[] | select(.stale)'

These commands ensure that teams can home in on the markers that matter most—without wading through noise.

Zero dependencies, dual runtime support

At its core, todoage is built to be unobtrusive. It has no external dependencies, no configuration files, and no side effects. It reads your repository, runs git blame, and exits—leaving no trace behind.

The tool ships in two flavors:

• Node.js version: Run directly with npx
• Python version: Installed via pipx

# Node.js
npx todoage

# Python
pipx run todoage

Despite running in different runtimes, both versions share the same core logic, ensuring consistent output across environments. They’re tested against identical inputs to guarantee reliability.

Design choices that ensure consistency and trust

Several architectural decisions make todoage both reliable and maintainable:

• Pure functions at the core: Core logic like scanLine, ageDays, and isStale are stateless, deterministic, and timezone-agnostic.
• No reliance on `Date` objects: Age calculations use integer milliseconds converted to whole days, avoiding floating-point precision issues.
• Read-only and stateless execution: The tool never writes to your repository or caches results—ideal for CI environments.

These principles ensure that the tool behaves predictably, whether used locally or in a build pipeline.

The future of TODO hygiene in codebases

Technical debt thrives in ambiguity. When TODO comments lack context, they become silent blockers—ignored until they break something. Tools like todoage shift the balance by exposing the age and ownership of every marker, turning passive comments into active action items.

As teams adopt automated enforcement of TODO hygiene, the practice of leaving vague markers may decline. Imagine a world where every TODO is either resolved quickly or escalated through CI. That’s not just cleaner code—it’s a healthier engineering culture.

Try todoage in your repository. And if you uncover a TODO that’s been lurking for years, ask yourself: what’s stopping you from fixing it today?