todo-harvest

May 16, 2026 · View on GitHub

hero

todo-harvest

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

License: MIT Python 3.8+ Claude Code Plugin Tests: 9 passing

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

Writing

LinkedIn

Dev.to

Writing

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.

Writing

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

Writing

Flags

FlagDefaultDescription
--repocwdRepo path
--markersTODO,FIXME,HACK,XXX,NOTEComma-separated marker words
--min-age0Only show markers ≥ N days old
--formatjsonjson or md

Writing

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 |

Writing

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.

Writing

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").

Writing

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.

Writing

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

Writing

License

MIT — see LICENSE. Contributions welcome.