mdtodo

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.

- [ ] 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  OVERDUE  ACTIVE  Write landing copy  (2 days overdue, 2026-10-18)
b1b77f  NEXT  Pick a color palette
  aa0d81  Pick a color palette: Shortlist 3 palettes

Each task line starts with its ref, then a marker for how urgent it is: OVERDUE, DUE SOON, ACTIVE, or NEXT. Deadlines read relative to today ("due tomorrow", "2 days overdue") next to the date. The summary lists Overdue, Due soon, Active, then Next, and shows each task only once, in its most urgent section.

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.

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

Colour

On a terminal, urgent tasks are coloured: overdue in bold red, due soon in bold magenta, active in bold green, and next in green. Titles are bold, and everything else is normal text. Only bold and the terminal's standard named colours are used, so your theme picks the exact shades and the output stays readable on light and dark backgrounds. Colour only repeats what the text already says, so nothing is lost without it.

--color auto|always|never (before or after the command) chooses when to use it. With auto, the default, colour is off when output is piped or redirected, when NO_COLOR is set, or when TERM=dumb. FORCE_COLOR is not read; use --color always to force colour, for example mdtodo --color always | less -R.

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.