todoage

How old is your tech debt? todoage scans your codebase for TODO / FIXME / HACK / XXX / BUG comments, then uses git blame to show how old each one is and who wrote it — and flags anything that's been rotting longer than your threshold.

Zero dependencies (pure standard library). Zero config. Read-only — it never writes to your repo.

pipx run todoage

AGE   TAG    LOCATION              AUTHOR          TEXT
418d  FIXME  app/auth/session.py:71  Alice Dev       refresh tokens before they expire
402d  TODO   app/billing/charge.py:12  Alice Dev     validate the amount before charging
311d  HACK   app/api/proxy.py:88    Bob Maintainer  works around the upstream 1.4 bug
9d    TODO   app/ui/cart.py:140     Carol           wire up the empty-cart state

summary:  4 markers · 3 older than 90d

The red rows are your stalest debt — the stuff that quietly became permanent.

Why it exists

tickgit (324★) promised exactly this — blame + age tracking for your TODOs — and then went quiet in 2020 having never shipped it. VS Code's todo-tree solves IDE visibility, but there's no small CLI that does the age + author part for a CI report or a Markdown summary.

So that's all todoage is: the missing CLI. It answers one question — which of these TODOs has been here so long it's basically a lie? — and answers it in a way you can drop into a CI gate.

How it works

It walks your tree (skipping .git, node_modules, .venv, dist, build artifacts and obvious binaries), matches comment markers in real comment contexts (#, //, /* */, <!-- -->, --, ;, leading *), and asks git blame for the author and author-date of each matching line. Age is whole days from the commit that introduced the line.

Markers are case-sensitive UPPER, so todomvc and fixme_helper don't trigger false positives — only an actual # TODO does.

Not in a git repo? It still lists every marker; age and author just show as ?.

Install

pipx run todoage           # no install, run on demand
pip install todoage        # or install the `todoage` command

There's an identical Node build too: npx todoage / npm i -g todoage (see todoage). Both ports are tested against the same vectors, so they produce byte-for-byte identical output.

Usage

todoage [path] [options]

Exit codes: 0 nothing stale · 1 stale found (with --fail-on-stale) · 2 usage error.

Examples

# fail CI if any TODO is older than a quarter
pipx run todoage --max-age 90d --fail-on-stale

# just the FIXMEs Alice left behind
todoage --tags FIXME --author alice

# feed a dashboard / Markdown summary
todoage --json | jq '.items[] | select(.stale)'

# scan one subtree, tighter threshold
todoage app/ --max-age 30d

Design notes

• One pure core, two runtimes. scan_line, age_days, and is_stale are pure functions with no I/O, clock, or git — driven by a shared input→output vectors table that the Python and Node suites both run. That's what proves the two ports agree.
• Age math never touches a datetime. It's integer milliseconds → whole days, so the result is deterministic and identical across languages.
• Read-only. It blames, it prints, it exits. No state, no cache, no config file, nothing written to your tree.

License

MIT