todo-hunter

Scan a codebase for TODO / FIXME / HACK / XXX comments and see them plotted on an ASCII radar — grouped by how old each one is, according to git blame. Fresh TODOs sit near the center; ancient ones drift to the edge.

No dependencies. Just Node + git.

Install

npm install -g todo-hunter

Or run it without installing:

npx todo-hunter

Usage

todo-hunter                # scan the current directory
todo-hunter ./src          # scan a specific directory
todo-hunter --json         # machine-readable output

Example output

todo-hunter — scanning /Users/Luketonium/ChemLab
                    |                    
              .............              
          .....     |     .....          
        ...    ...........    ...        
      ..   .....    |    .....   ..      
    ..    ..    .........    ..    ..    
    .   ..   ....   |   ....   ..   .    
   .   ..   ..      |      ...  ..   .   
  ..  ..  ..     .......     ..  ..  ..  
  .   .   .     ..  |  ..     .   .   .  
--.---.---.-----.---+*--.-----.---.---.--
  .   .   .     ..  |  ..     .   .   .  
  ..  ..  ..     .......     ..  ..  ..  
   .   ..  ...      |      ...  ..   .   
    .   ..   ....   |   ....   ..   .    
    ..    ..    .........    ..    ..    
      ..   .....    |    .....   ..      
        ...    ...........    ...        
          .....     |     .....          
              .............              
                    |   

Legend:
  *  Fresh (<7d)
  o  Aging (7-30d)
  +  Stale (30-90d)
  #  Ancient (>90d)
  ?  Unknown age

Found 4 markers across the scanned files.

* Fresh (<7d): 1
o Aging (7-30d): 1
+ Stale (30-90d): 1
# Ancient (>90d): 1

Oldest markers:
  FIXME src/legacy/parser.js:112 (214d) — replace regex hack with a real parser
  TODO src/api/routes.js:48 (61d) — add pagination
  HACK src/utils/format.js:9 (18d) — remove once date-fns upgrade lands
  TODO src/index.js:3 (2d) — write integration tests

How it works

1. Walks the directory tree (skipping node_modules, .git, dist, build, etc.) and reads common source file extensions.
2. Finds lines where TODO, FIXME, HACK, or XXX appears after a comment token (//, #, /*, *, <!--, --) — so it won't flag the word showing up in a string or regex.
3. For each hit, runs git blame -L <line>,<line> --porcelain to find the commit's timestamp, and buckets the marker by age:
   • Fresh — under 7 days old
   • Aging — 7–30 days
   • Stale — 30–90 days
   • Ancient — over 90 days
   • Unknown — file isn't tracked by git, or git isn't available
4. Renders the buckets as concentric rings on an ASCII radar, with each marker plotted as a colored blip at a random angle within its ring.

The radar is meant to give a quick "vibe check" — not precise coordinates. For exact locations, read the summary list below it, or use --json.

Options

| Flag | Description | |-----------------|-------------------------------------------| | -d, --dir | Directory to scan (default: .) | | --json | Print raw JSON instead of the radar | | -h, --help | Show help |

Respects NO_COLOR to disable ANSI colors.

Limitations

• Requires the repo to be a git repository for age data; otherwise markers show as "Unknown age".
• It's a line-based scanner, not a real comment parser — a docstring that discusses TODOs (like this README) will also get matched if it's inside actual comment syntax in a source file.
• Radar blip positions are randomized within their ring for visual spread, not meaningful spatial coordinates.

License

MIT