tododebt

How much acknowledged debt is sitting in the codebase? tododebt inventories the markers — TODO, FIXME, HACK by default — across a set of source files and reports every occurrence with its file, 1-based line number, and line text, plus counts in total, by marker, and by file.

A marker counts only as a standalone token (the marker followed by a non-letter), so TODOS and METHOD never false-positive, while TODO:, FIXME(user), and // TODO all count. Only the first marker on a line is reported. Matching is case-sensitive.

The MCP tool takes file contents as input (no disk access); the CLI reads the files you name. Pure local computation: no network, no configuration.

CLI

npx @reneturcios/tododebt scan src/*.ts
npx @reneturcios/tododebt scan README.md src/index.ts --markers TODO,XXX
npx @reneturcios/tododebt --version

Exit codes: 0 on success (a non-empty inventory is a result, not an error), 1 on a runtime error (including an unreadable file), 2 on a usage error.

Related MCP server: promptpack

MCP server

npx -y @reneturcios/tododebt mcp

MCP client config:

{
  "mcpServers": {
    "tododebt": {
      "command": "npx",
      "args": ["-y", "@reneturcios/tododebt", "mcp"]
    }
  }
}

Tools

• scan_todos — Inventory debt markers across supplied source files.

  • files (array, required) — the files to scan, as {path, content} pairs

  • markers (array of strings, optional) — markers to look for; default TODO, FIXME, HACK

Docker

docker run -i ghcr.io/cloudcorprecords/tododebt
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/tododebt scan /w/src/index.ts

Development

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

License

MIT — Copyright (c) 2026 Rene Turcios