todo-scan

Scan your codebase for TODO, FIXME, HACK, and other comment tags. Zero dependencies. CI/CD ready.

Install

# Run instantly with npx (no install)
npx todo-scan

# Or install globally
npm i -g todo-scan

Usage

# Scan current directory
todo-scan

# Scan a specific directory
todo-scan ./src

# Output as JSON (for CI pipelines)
todo-scan --json

# Fail CI if any TODOs are found
todo-scan --strict

# Only look for specific tags
todo-scan --tags TODO,FIXME,BUG

# Ignore additional directories
todo-scan --ignore vendor,tmp,generated

# Sort by tag type instead of file
todo-scan --sort tag

Terminal Output

todo-scan v1.0.0

src/index.js
  L42   TODO     Refactor this to use async iteration
  L87   FIXME    Race condition when concurrent writes happen
  L155  HACK     Workaround for Node 18 bug, remove after v20

src/cli.js
  L12   TODO(alex)  Add --exclude flag for file extensions
  L98   NOTE        This could be optimized with a worker pool

Summary: 5 items found (3 TODO, 1 FIXME, 1 HACK, 0 XXX, 0 BUG, 1 NOTE)

JSON Output

todo-scan --json

{
  "version": "1.0.0",
  "scannedAt": "2026-03-10T12:00:00.000Z",
  "directory": "/path/to/project",
  "items": [
    {
      "file": "src/index.js",
      "line": 42,
      "tag": "TODO",
      "author": null,
      "message": "Refactor this to use async iteration"
    },
    {
      "file": "src/cli.js",
      "line": 12,
      "tag": "TODO",
      "author": "alex",
      "message": "Add --exclude flag for file extensions"
    }
  ],
  "summary": {
    "total": 2,
    "TODO": 2,
    "FIXME": 0,
    "HACK": 0,
    "XXX": 0,
    "BUG": 0,
    "NOTE": 0
  }
}

CLI Flags

| Flag | Short | Description | |------|-------|-------------| | --help | -h | Show usage information | | --version | -v | Show version number | | --json | | Output as JSON (for CI pipelines) | | --strict | | Exit with code 1 if any tagged comments found | | --no-color | | Disable ANSI color output | | --tags <tags> | | Comma-separated tags to scan (default: TODO,FIXME,HACK,XXX,BUG,NOTE) | | --ignore <patterns> | | Comma-separated patterns to ignore (default: node_modules,.git,dist,build,coverage,.next) | | --sort <field> | | Sort by: file, tag, or line (default: file) |

The first positional argument is the directory to scan (defaults to .).

Supported Comment Styles

todo-scan recognizes tagged comments across many languages:

| Style | Languages | |-------|-----------| | // TODO: ... | JavaScript, TypeScript, Go, Rust, C, C++, Java, Swift | | # TODO: ... | Python, Ruby, Shell, YAML, Dockerfile | | /* TODO: ... */ | CSS, C, C++, Java | | -- TODO: ... | SQL, Lua, Haskell | | ; TODO: ... | Lisp, Assembly, INI files | | % TODO: ... | LaTeX, Erlang, MATLAB | | <!-- TODO: ... --> | HTML, XML, Markdown |

Author Tags

Supports optional author attribution in parentheses:

// TODO(alice): Implement caching layer
// FIXME(bob): This breaks on Windows
# HACK(carol): Temporary workaround for API rate limit

CI/CD Integration

GitHub Actions

name: Check TODOs
on: [push, pull_request]

jobs:
  todo-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Scan for TODOs
        run: npx todo-scan --strict

As a JSON report

      - name: Generate TODO report
        run: npx todo-scan --json > todo-report.json
      - uses: actions/upload-artifact@v4
        with:
          name: todo-report
          path: todo-report.json

Pre-commit hook

#!/bin/sh
# .git/hooks/pre-commit
npx todo-scan --strict --tags FIXME,BUG

Programmatic API

const { scan } = require('todo-scan');

const result = await scan({
  directory: './src',
  tags: ['TODO', 'FIXME'],
  ignore: ['node_modules', 'dist'],
  sort: 'tag',
});

console.log(result.items);   // Array of found items
console.log(result.summary); // { total: N, TODO: N, FIXME: N, ... }

Requirements

• Node.js 18 or higher
• Zero external dependencies

License

MIT