Tododebt

io.github.CloudCorpRecordsPublished by GitHub account CloudCorpRecordsv0.1.0Updated Nov 6, 2026

TODO, FIXME, and HACK inventory with git blame age and file owner.

VerifiedSTDIODesktop onlyDeveloper Tools

Overview

AI-generated overview

Scans supplied source files for TODO, FIXME, HACK and XXX markers and reports each occurrence with file, line and text, plus counts.

What you can do
  • Inventory debt markers across source files passed in as path and content pairs
  • Report each finding with file, 1-based line number, marker and line text
  • Summarize counts in total, by marker and by file
  • Return a verdict of NONE when the tree is clean and DEBT otherwise
  • Optionally restrict the scan to a custom list of markers
When to use it
Useful when you want an assistant to audit a codebase for acknowledged technical debt, count outstanding TODOs before a cleanup or release, or point to where markers cluster by file.
Requirements
Runs as a local process via npx or the Docker image; no network, configuration, accounts or API keys. The MCP tool takes file contents as input rather than reading disk itself, so the client must supply the files.
Before you install
Read-only scanning with no writes, credentials or third-party data transfer. Matching is case-sensitive, only the first marker per line is reported, and markers must be standalone tokens, so results are an inventory rather than a complete audit.

Installation

In SourceWeft

  1. Open Tododebt in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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

bash
npx @reneturcios/tododebt scan src/*.tsnpx @reneturcios/tododebt scan README.md src/index.ts --markers TODO,XXXnpx @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.

MCP server

bash
npx -y @reneturcios/tododebt mcp

MCP client config:

json
{  "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

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

Development

bash
npm installnpm 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

Source: README.md at commit 9db7f97

Tools

1

scan_todo_debt

Scan a repo for TODO, FIXME, HACK, and XXX markers in source files: each finding carries file, line, marker, and text; counts are grouped by marker and by file; when git history is available, blame dates the oldest markers. Verdict NONE when the tree is clean, DEBT otherwise.

Parameterspathrequired

Version history

1
  1. v0.1.0LatestOct 30, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts