TODO / FIXME tracker with blame author, age and owner groups

What it does

Takes stock of "do it later" comments left in the code.

• Searches tracked files for TODO, FIXME, HACK and XXX (tags are configurable)
• Matches only after a comment marker (#, //, /*, <!--, -- and others), so words inside strings are ignored
• Uses git blame --porcelain for the line's author, email, date, age in days and commit; uncommitted lines are marked
• Reads owners written in the comment, such as TODO(alice): or FIXME[bob]
• Groups by owner, age (under 30 days, 30-90, 90-365, over 1 year), tag or file
• Filters by age, owner or folder; outputs Markdown, CSV or JSON
• Optional issue draft per item (location, author, text, done-when checklist)

How to use

python scripts/todo_scan.py --group age
python scripts/todo_scan.py --format csv --out todos.csv
python scripts/todo_scan.py --older-than 365 --issues --out old-todos.md

Ask the agent something like "list TODOs older than a year and draft issues for them". Works with Claude, Codex, Hermes Agent and Cursor.

Requirements

• Python 3 (standard library only)
• Git

Caveats

• Read-only. The agent files issues or removes comments only when you ask.
• The blame author is whoever last changed the line; formatting-only commits can change it.
• Binary files, lockfiles, minified files, files over 1 MB and untracked files are skipped.
• CSV and JSON output include author emails; take care when sharing outside the team.