todo-harvest

Find the oldest, most-forgotten TODOs and put their authors on blast (constructively).

TL;DR: /todo-harvest → markdown table of every TODO/FIXME/HACK with git blame author + age in days, sorted oldest-first.

Why this exists

TODO comments are how engineers say "future me will deal with this." Future me never does. Worse, future-me-the-new-hire doesn't even know who wrote them or whether they still apply. todo-harvest runs git blame for each match so you can triage: 800-day-old TODOs from a dev who left the company three years ago are deletable; 12-day-old ones from this sprint are real work.

Install (Claude Code)

git clone https://github.com/mturac/pluginpool-todo-harvest ~/.claude/plugins/todo-harvest

Restart Claude Code; the slash command /todo-harvest appears.

Quick start

/todo-harvest

Or directly:

python3 scripts/harvest.py --format md
python3 scripts/harvest.py --min-age 180 --format md     # only stuff older than 6 months
python3 scripts/harvest.py --markers TODO,FIXME --format json

Flags

Flag	Default	Description
--repo	cwd	Repo path
--markers	TODO,FIXME,HACK,XXX,NOTE	Comma-separated marker words
--min-age	0	Only show markers ≥ N days old
--format	json	json or md

Example output (markdown)

| age (d) | marker | file:line | author | note |
|---|---|---|---|---|
| 1247 | HACK | src/legacy/login.py:42 | Alice (left in 2022) | special-case the demo-account UA |
| 412 | FIXME | src/db.py:81 | Bob | this `n+1` lookup needs a join |
| 88 | TODO | src/auth.py:17 | Cara | wire to the new OAuth2 path |

How it works

1. Uses git ls-files so untracked + .gitignored files are skipped.
2. Detects worktrees correctly (.git can be a file pointer, not a directory).
3. Skips binary files (null byte in first 1 KB).
4. Matches markers as whole words: TODO, TODO:, # TODO ….
5. Runs git blame --porcelain -L N,N -- <file> per match for the original author + author-time.

Limitations

• One git blame call per match means it's slow on huge repos — use --min-age or --markers to narrow.
• "Age" is the age of the current line. Renames and reformats reset the clock.
• Unicode-safe (decodes with errors="replace").

Examples

Step-by-step walkthroughs with real input fixtures and the helper's actual output live in examples/. Three or four scenarios per plugin — from the happy path to the edge cases the test suite guards.

Part of the pluginpool family

Ten focused Claude Code plugins for everyday productivity: commit-narrator · pr-storyteller · test-gap · deps-doctor · env-lint · secret-guard · standup-gen · todo-harvest · flaky-detector · changelog-forge

License

MIT — see LICENSE. Contributions welcome.