Your repo has 600 debt markers. Todo Drip shows you exactly one today.
Todo Drip is a deliberately small, read-only CLI for making a large debt list feel approachable. It scans a Git worktree's tracked files, then deterministically reveals one TODO, FIXME, or HACK marker for the calendar date. Tomorrow brings back the curiosity; today asks for only one decision. It leans on the low friction of "just one," curiosity about tomorrow, and the temptation to avoid organizing the whole list—never shame, fear, or fake urgency.
todo-drip pickreveals at most one marker line. With markers available, it reveals exactly one.todo-drip countreports only the marker count and scan totals; it does not reveal marker text or file names.- Files come from
git ls-files -z --cached. Untracked and ignored files are never opened. - Source files are read only. Todo Drip never edits, stages, or commits them.
- Matches are exact uppercase text tokens with ASCII identifier boundaries:
TODO,FIXME, andHACK. - A marker is a text match, not a parsed comment. Matches in strings, documentation, or generated tracked files are still markers unless excluded.
- Files over 1 MiB, NUL-containing files, non-UTF-8 files, symlinks, missing files, and unsafe paths are skipped and counted by reason.
- No markers is a successful result, not an error.
Runtime requirements: Python 3.10+, Git, and no third-party Python runtime dependencies.
python -m pip install .
todo-drip --helpFor an isolated command-line install, pipx install . also works when pipx is already available. This repository does not claim that a PyPI release exists.
Run inside the repository you want to inspect:
todo-drip count .
todo-drip pick .Or run from a parent directory and pass the repository directory:
todo-drip pick my-repo --date 2026-08-30 --seed team-demo
todo-drip count my-repo --exclude 'vendor/**' --exclude '*.md'
todo-drip pick my-repo --jsonPATH must be relative, contain no .., stay within the current directory after resolution, and name the Git worktree root. Absolute paths and repository subdirectories are rejected. All emitted file paths are repository-relative with / separators.
--exclude is repeatable. Patterns use case-sensitive shell-style matching against /-normalized Git paths. A pattern without / matches any path component; vendor/** excludes that tree. Excludes are applied before files are inspected.
By default, the date is the machine's local calendar date. --date YYYY-MM-DD makes demos and tests replayable. The ordered candidate identities, date, and optional seed are framed into SHA-256; Python's randomized hash() is not used. Selection happens before output redaction, so --json and --raw do not change which marker is chosen. A different date or seed can still land on the same marker because the candidate set is finite.
Marker text is filtered by default for the current home-directory prefix, common home-path forms, email addresses, common token prefixes, and secret-like assignments such as api_key=..., token=..., and password=....
This is a heuristic, not a secrecy guarantee. It can miss credentials or hide innocent text. Manually inspect all output before pasting it into an issue, chat, log, or public post. --raw is an explicit opt-in that bypasses content redaction:
todo-drip pick . --raw
todo-drip pick . --raw --jsonHuman-readable output still escapes terminal control characters. JSON uses normal JSON string escaping.
Todo Drip is an anti-task-manager: it deliberately removes the backlog and the
choice. t-rush offers an interactive
picker, editor flow, timer, streaks, and history;
todos is a mature multi-language scanner
that prints a full inventory in several formats. Those are useful when you want
to manage or inspect the whole queue. Todo Drip instead keeps only a
tracked-file count and one deterministic daily reveal—no list, picker, timer,
streak, ranking, issue sync, or state file.
That narrow boundary is the product, not a missing roadmap. Todo Drip does not claim to be the first source-marker scanner.
The demo creates a temporary Git repository, tracks two files, leaves one file ignored and another untracked, then removes the entire temporary directory. It does not add files to your current repository.
python scripts/demo.pyReal output from the checked-in demo on 2026-08-30:
Todo Drip disposable demo (the temporary Git repo is removed afterward).
$ todo-drip count demo-repo
3 markers
Scanned 2 of 2 tracked files; excluded 0; skipped 0.
$ todo-drip pick demo-repo --date 2026-08-30 --seed readme
[FIXME] src/payments.py:3:13
pass # FIXME replace retry magic number
Scanned 2 of 2 tracked files; excluded 0; skipped 0.
Temporary repository removed; ignored and untracked markers were never scanned.
pick --json emits one success document on stdout with selected set to a marker object or null. count --json emits count and summary only. Errors, including malformed arguments, exit with code 2 and emit one error document on stderr when --json is present.
{
"command": "pick",
"count": 3,
"date": "2026-08-30",
"seed": "readme",
"selected": {
"column": 13,
"kind": "FIXME",
"line": 3,
"path": "src/payments.py",
"redaction_applied": true,
"text": " pass # FIXME replace retry magic number"
},
"summary": {
"excluded_files": 0,
"scanned_files": 2,
"skipped_by_reason": {
"binary": 0,
"oversize": 0,
"symlink": 0,
"unavailable": 0,
"unsafe": 0
},
"skipped_files": 0,
"tracked_files": 2
}
}python -m unittest discover -s tests -v
python scripts/demo.pyThe CI workflow runs the same source tests across supported Python lines. The tag workflow is configured to test/build source distributions, build one-file PyInstaller executables for Linux, macOS, and Windows, and attach a .sha256 file for every asset. Those hosted workflows and standalone binaries are not locally verified merely by being checked in.
See SECURITY.md for reporting guidance and CHANGELOG.md for project history. Todo Drip is licensed under the MIT License.