How long has that TODO been waiting?

tododust lists every TODO, FIXME, HACK and XXX in a git repo with its age and who left it, oldest first. One small command line tool. Free and open source.

Download tododust 0.1.0 (zip)
npx https://tododust.pages.dev/download/tododust-0.1.0.tgz

MIT license · no dependencies · needs Node 18.14+ and git · no sign-up

A terminal running tododust --limit 10 in the requests repository: a table of TODO and XXX comments with ages from 6 months to 15 years, their authors and file locations, and a summary line saying 11 markers in 7 of 130 tracked files, oldest 15 years.

tododust 0.1.0 run on a clone of the open-source psf/requests repository. Real output, rendered in a 100-column terminal.

What it does

Finds the markers

Reads every file git tracks and picks out TODO, FIXME, HACK and XXX comments, in any language. Pick your own tags with --tags.

Dates each one

Runs git blame on just those lines, so each marker gets the date and author of the commit that last changed it.

Sorts by neglect

Oldest first, coloured by age, with a summary: how many, the oldest, the median, and how many are over a year old.

Fails a build if you want

tododust --fail-over 1y exits 1 when a marker has waited longer than a year. --json gives you everything else.

Install

You need Node 18.14 or newer and git. Then pick one:

  1. Try it once, nothing installed. In any repository: 
    npx https://tododust.pages.dev/download/tododust-0.1.0.tgz
  2. Install the tododust command. 
    npm install -g https://tododust.pages.dev/download/tododust-0.1.0.tgz
cd your-repo
tododust
  3. No npm. Download the zip, unzip it, and from inside your repository run: 
    node path/to/tododust-0.1.0/bin/tododust.js

Use

# the whole repo, oldest first
tododust
# one folder, only what is older than six months
tododust src/api --older-than 6m
# only yours
tododust --author nell
# in CI: fail when anything has waited more than a year
tododust --fail-over 1y
# everything as JSON, commit hashes included
tododust --json > todos.json

Ages take d, w, m and y. tododust --help lists every option.

FAQ

Does it send my code anywhere?

No. It reads files on your disk and runs git ls-files and git blame. It never opens a network connection and never writes to your repository.

What does the age actually mean?

The date of the commit that last changed that line. Whitespace changes and lines moved within a file keep their age. If someone edited the TODO line itself, the clock starts again from that edit. A marker you have not committed yet shows as "today".

Why not just grep?

grep tells you a TODO exists. It does not tell you the one in billing code has been there for three years, or that half of them came from someone who left. That is the part tododust adds.

Which systems does it run on?

Anywhere Node 18.14+ and git run. I have tested it on Windows 11 and on Ubuntu 24.04. I have not tested it on macOS yet; if it breaks there, I want to know.

Is it slow on a big repo?

It only blames the files that contain a marker, and only those lines, a few files at a time. On a clone of moment.js (823 tracked files, 52 markers) it takes about a second and a half on my machine.

What does it cost?

Nothing. It is MIT licensed. The source is in the zip: about 450 lines of JavaScript, plus its tests.

What does the download count?

The download links count each computer once per hour per file, so the two or three fetches one npx run makes count once. It keeps no IP address and sets no cookie: it stores a salted hash it cannot turn back into one.