mdtodo

mdtodo is a command-line todo manager that keeps everything in one plain markdown file. mdtodo is a command-line todo manager that keeps everything in one plain markdown file. Headings are projects and checkbox items are tasks. You can edit the file in any editor, or use the mdtodo commands. Either way, it stays readable markdown. use the mdtodo commands. Either way, it stays readable markdown.

- [ ] Call the bank due:2026-10-20

## Website
- [ ] Write landing copy @active due:2026-10-18
- [ ] Pick a color palette @next
  - [ ] Shortlist 3 palettes
- [x] Buy domain

• [ ] means open, and [x] means completed.
• @active marks a task you're working on now. @next adds a task to the pool of tasks you plan to pick up next.
• due:YYYY-MM-DD sets a deadline. Open tasks are flagged as overdue, or as due soon (today through the next 3 days).
• Tasks above the first heading go into the Inbox project. Prose, notes, and code blocks are ignored.

Listings show each task with its reference. A subtask is labelled with its parent's name, as <parent>: <task>, so you can tell which task it belongs to:

$ mdtodo list --project Website
## Website
bbdb3a  Write landing copy  (due 2026-10-18, overdue)
b1b77f  Pick a color palette
  aa0d81  Pick a color palette: Shortlist 3 palettes

The full syntax is in specs/001-markdown-todo-manager/contracts/file-format.md.

Install

With uv installed:

uv tool install mdtodo   # puts `mdtodo` on your PATH (~/.local/bin)
mdtodo --version

If you don't have a suitable Python, uv downloads one for you.

uv tool install mdtodo==X.Y.Z   # install a specific version
uv tool upgrade mdtodo          # move to the latest release
uv tool uninstall mdtodo        # remove the command

Uninstalling removes only the command. Your todo file (~/tracker.md, or whatever --file or MDTODO_FILE points at) is left untouched.

Switching from an editable install: if you installed with uv tool install --editable ., run uv tool uninstall mdtodo first, or replace it in one step with uv tool install --force mdtodo.

Which file is used

The first match wins:

1. --file PATH, which can go before or after the command;
2. the MDTODO_FILE environment variable;
3. ~/tracker.md.

If you used an earlier version that read ~/TODO.md, rename that file to ~/tracker.md, or point --file or MDTODO_FILE at it. 2. the MDTODO_FILE environment variable; 3. ~/tracker.md.

If you used an earlier version that read ~/TODO.md, rename that file to ~/tracker.md, or point --file or MDTODO_FILE at it.

mdtodo init creates a starter file. Nothing else ever creates the file. mdtodo init creates a starter file. Nothing else ever creates the file.

Commands

REF is the 6-character reference shown in every listing. It stays the same when markers change. If you edit a task's text, its reference changes, and the old one is refused rather than applied to the wrong task. Each command changes only the task's own line. If the file changed while the command was running, nothing is written.

Details, including output formats and exit codes, are in contracts/cli.md.

Development

uv sync
uv tool install --editable .       # installs this working tree as the `mdtodo` command
scripts/check.sh                   # format, lint, mypy --strict, tests (coverage ≥ 80%)
uv run pytest -m perf --no-cov     # timing checks (SC-002), kept out of the default run

The design documents are in specs/001-markdown-todo-manager/, and the project principles are in .specify/memory/constitution.md.

Releasing

Releases go to PyPI with scripts/release.sh. See docs/releasing.md.