todo-scan

Scan your source code for TODO, FIXME, HACK, BUG, and other comment tags. Groups results by type, shows file and line, and optionally pulls git blame info. Zero dependencies.

Works on Windows, Mac, and Linux — unlike grep -r TODO (Unix-only) or todocheck (needs Go).

Install

npm install -g todo-scan

Or without installing:

npx todo-scan

Usage

todo-scan                          # Scan current directory
todo-scan src/                     # Scan a specific directory
todo-scan --type TODO,FIXME        # Filter to specific tags
todo-scan --blame                  # Show author and age from git blame
todo-scan --format json            # JSON output
todo-scan --format github          # GitHub Actions annotation format
todo-scan --strict --type FIXME    # Fail CI if any FIXMEs

Example Output

todo-scan  /my-project
  12 item(s):  BUG 1  FIXME 3  HACK 2  NOTE 4  TODO 2

  BUG  (1)
    src/auth/session.js:47  Session tokens not invalidated on logout
  
  FIXME  (3)
    src/api/users.js:12   Paginate this query — it'll OOM on large datasets
    src/api/users.js:89   Handle 429 from upstream
    src/db/migrate.js:31  Transaction not rolled back on partial failure
  
  HACK  (2)
    src/utils/retry.js:5  Exponential backoff hardcoded to 3 retries
    config/webpack.js:78  Suppress deprecation warning until webpack 6
  
  TODO  (2)
    README.md:14  Add screenshots
    src/worker.js:22  Move to queue-based processing

With --blame

  FIXME  (1)
    src/api/users.js:12  Paginate this query — it'll OOM on large datasets — Alice, 47d ago

Tags Scanned by Default

TODO · FIXME · HACK · XXX · NOTE · OPTIMIZE · BUG · DEPRECATED · REVIEW

Customize with --type:

todo-scan --type TODO,FIXME,HACK

CI Integration

# Fail the build if any FIXME comments exist
- name: No FIXMEs allowed
  run: npx todo-scan --strict --type FIXME

# Post annotations in GitHub Actions
- name: Scan TODOs
  run: npx todo-scan --format github

Supported Languages

JavaScript, TypeScript, Python, Ruby, PHP, Go, Rust, Java, Kotlin, Swift, C/C++, C#, Shell, YAML, HTML, CSS, SQL, Terraform, Vue, Svelte, and more.

License

MIT

Keywords

todo finder · fixme · code comments · technical debt · find todos · todo list · hack xxx · annotation scanner · zero dependencies · cli

Built to solve, shared to help — Rushabh Shah 🛠️✨

One of 40+ zero-dependency developer CLI tools — no node_modules, ever.