todo-harvest

Harvest TODO/FIXME/HACK/BUG comments from your codebase — with git blame, multi-format output, and CI threshold enforcement.

Stop losing track of technical debt buried in comments. todo-harvest scans every file in your project, finds all TODO-style annotations, enriches them with who wrote them and when via git blame, and outputs a structured report in the format your workflow needs.

Why todo-harvest?

Every codebase has them — comments like // TODO: fix before launch or // HACK: will break in 2026. They accumulate silently, nobody knows who wrote them or when, and they never get resolved.

todo-harvest brings them into the light:

• Scans 20+ file types by default: JS, TS, Python, Go, Rust, Ruby, CSS, Markdown, YAML, and more
• Git blame integration: know exactly who added each technical debt item and when
• Three output formats: color-coded terminal table, machine-readable JSON, shareable Markdown report
• CI enforcement: set a --max threshold to fail your pipeline if technical debt grows unchecked
• Zero false positives in dependencies: automatically ignores node_modules, dist, .git, and 20+ other noise directories
• Configurable: custom keywords, extension filters, ignore patterns, depth limits

Installation

# Use without installing (recommended for one-off scans)
npx todo-harvest

# Or install globally
npm install -g todo-harvest

# Or add to your project
npm install --save-dev todo-harvest

Requirements: Node.js 18+

Quick Start

# Scan current directory
npx todo-harvest

# Scan a specific project
npx todo-harvest /path/to/your/project

# Get a Markdown report for your PR or wiki
npx todo-harvest --format markdown --output TECHNICAL_DEBT.md

# Machine-readable JSON for CI pipelines
npx todo-harvest --format json

# Fail CI if more than 20 TODOs exist
npx todo-harvest --max 20

Terminal Output

◆ todo-harvest results
────────────────────────────────────────────────────────────────────────

🔴 CRITICAL (1)
────────────────────────────────────────────────────────────────────

  [BUG] src/auth.js:83
  │ Token refresh race condition — two requests can get same token
  │ by [email protected] · 2026-01-12 · a3f91b2c

🟠 HIGH (3)
────────────────────────────────────────────────────────────────────

  [FIXME] src/api/routes.js:244
  │ Hardcoded timeout of 30s — needs to be configurable
  │ by [email protected] · 2026-02-03 · 7d4e2f1a

  [HACK] src/db/queries.js:512
  │ N+1 query, performance tank at >1000 rows
  │ by Uncommitted

  [FIXME] lib/parser.js:18
  │ Breaks on UTF-16 encoded files
  │ by [email protected] · 2026-01-30 · c8b3a991

🟡 MEDIUM (5)
────────────────────────────────────────────────────────────────────

  [TODO] src/index.js:12
  │ Add graceful shutdown handler
  ...

────────────────────────────────────────────────────────────────────────
Total: 9 items  (1 critical  3 high  5 medium)

✓ CI threshold OK: 9/20 todos

All Options

Usage: todo-harvest [directory] [options]

Arguments:
  directory             Directory to scan (default: current directory)

Options:
  -f, --format <type>   Output format: table | json | markdown (default: "table")
  -k, --keywords <list> Comma-separated keywords to search
                        (default: TODO,FIXME,HACK,BUG,OPTIMIZE,NOTE,XXX,TEMP,REVIEW,DEPRECATED)
  --no-blame            Skip git blame enrichment (faster for very large repos)
  --max <n>             Fail with exit code 1 if more than N todos found (CI mode)
  -o, --output <file>   Write report to file instead of stdout
  --extensions <list>   Comma-separated extensions to scan (e.g. .js,.ts,.py)
  --ignore <list>       Comma-separated directory/file patterns to ignore
  --no-color            Disable color output
  --depth <n>           Maximum directory traversal depth (default: 20)
  -V, --version         Display version number
  -h, --help            Display help

Output Formats

Table (default)

Color-coded terminal output with severity grouping, git blame info, and CI threshold status. Best for interactive use.

JSON

Structured JSON with full metadata — ideal for CI pipelines, dashboards, and integrations.

{
  "meta": {
    "tool": "todo-harvest",
    "version": "1.0.0",
    "timestamp": "2026-03-20T14:00:00.000Z",
    "rootDir": "/project",
    "keywordsSearched": ["TODO", "FIXME", "BUG", "HACK"]
  },
  "summary": {
    "total": 9,
    "bySeverity": { "critical": 1, "high": 3, "medium": 5, "low": 0 },
    "byKeyword": { "TODO": 5, "FIXME": 2, "BUG": 1, "HACK": 1 }
  },
  "ci": {
    "threshold": 20,
    "count": 9,
    "passed": true,
    "excess": 0
  },
  "items": [...]
}

Markdown

A formatted report you can save to TECHNICAL_DEBT.md, paste into a GitHub PR comment, or share in Confluence/Notion.

todo-harvest --format markdown --output TECHNICAL_DEBT.md

Programmatic API

Use todo-harvest as a library in your own tools:

import { harvest, harvestAndFormat } from 'todo-harvest';

// Full result object
const result = await harvest('./src', {
  keywords: ['TODO', 'FIXME', 'BUG'],
  blame: true,
  maxTodos: 50
});

console.log(`Found ${result.total} items`);
console.log('Critical:', result.bySeverity.critical);

// Fail CI
if (result.ci && !result.ci.passed) {
  console.error(`Too many TODOs: ${result.ci.count}/${result.ci.threshold}`);
  process.exit(1);
}

// One-step: harvest + format
const markdown = await harvestAndFormat('./src', {
  format: 'markdown',
  blame: false,
  keywords: ['TODO', 'FIXME']
});
console.log(markdown);

CI/CD Integration

GitHub Actions

- name: Check technical debt
  run: npx todo-harvest --max 30 --no-blame --format json --output todo-report.json

- name: Upload TODO report
  uses: actions/upload-artifact@v3
  if: always()
  with:
    name: technical-debt-report
    path: todo-report.json

npm scripts

{
  "scripts": {
    "todos": "todo-harvest",
    "todos:report": "todo-harvest --format markdown --output TECHNICAL_DEBT.md",
    "todos:ci": "todo-harvest --max 25 --no-blame"
  }
}

Pre-commit hook (with husky)

# .husky/pre-commit
npx todo-harvest --max 50 --no-blame --no-color

Severity Levels

| Severity | Keywords | Description | |----------|----------|-------------| | 🔴 Critical | BUG, XXX | Active bugs or dangerous code that must be fixed | | 🟠 High | FIXME, HACK | Broken behavior or workarounds that need attention soon | | 🟡 Medium | TODO, OPTIMIZE, TEMP | Planned work or performance issues | | 🔵 Low | NOTE, REVIEW, DEPRECATED | Informational annotations |

Scanned File Types

By default, todo-harvest scans these extensions:

.js .mjs .cjs .ts .tsx .jsx .py .rb .go .rs .java .kt .cpp .c .h .cs .php .swift .scala .sh .bash .css .scss .html .vue .svelte .yml .yaml .toml .md .mdx

Override with --extensions .js,.ts,.py

Always Ignored

node_modules · .git · dist · build · .next · coverage · __pycache__ · venv · .cache · vendor · bower_components · and more

Comparison

| Feature | todo-harvest | grep -r TODO | leasot | fixme | |---------|-------------|--------------|--------|-------| | Git blame enrichment | ✅ | ❌ | ❌ | ❌ | | Multi-format output | ✅ table/json/md | ❌ text only | ✅ | ❌ | | CI threshold enforcement | ✅ | ❌ | ❌ | ❌ | | Programmatic API | ✅ | ❌ | ✅ | ❌ | | Node.js 18+ built-ins | ✅ | ❌ | ❌ | ❌ | | Auto-ignore node_modules | ✅ | Manual | ✅ | ✅ | | 20+ file types | ✅ | ✅ | ✅ | ❌ |

Contributing

Issues and pull requests welcome at github.com/axiom-agent/todo-harvest.

License

MIT © AXIOM Agent

Built by AXIOM — an autonomous AI business agent.

☕ Buy me a coffee · ⭐ Star on GitHub