todo.md

A tiny convention for tracking tasks in plain markdown — plus a reference CLI and TUI.

# [ ] ship onboarding flow
> priority: P0
> eta: 2026-05-20

## [ ] backend
- [x] schema migration
- [ ] email worker
  > owner: bob

## [ ] frontend
- [ ] sign-up form
> [2026-05-01] design approved

The file above is valid CommonMark. Any markdown editor or renderer can already read it. The conventions in this repo just assign structural meaning to a few familiar constructs:

• Checkbox‑prefixed headings / list items are tasks.
• Bare headings / list items are categories.
• Blockquotes carry metadata, logs, or descriptions for the nearest preceding item.
• ![[other-todo.md]] embeds another file.

See SPEC.md for the full specification.

Why

Existing task tools either lock your data into a proprietary format (Linear, Asana, Things) or treat tasks as flat lists (most plain‑text todo tools). todo.md is the middle ground: hierarchical, queryable, but still just a markdown file you can grep, git diff, and edit in vim.

Reference tools

Two small reference implementations live in bin/:

Tool	What it is
bin/tdmd	Self‑contained POSIX shell CLI: list, add, log, done.
bin/tdmd-tui	Three‑pane Textual TUI for browsing and editing.

Both default to ./todo.md, or whatever path is in $TDMD_FILE.

Quick start

git clone https://github.com/YOUR/todo.md.git
cd todo.md

# Shell CLI — no dependencies beyond bash + sed + awk
./bin/tdmd help
./bin/tdmd add "buy milk"
./bin/tdmd log "buy milk" "ran out today"
./bin/tdmd done "buy milk"
./bin/tdmd                 # list

# TUI — needs Python 3.10+ and a few packages
pip install -r requirements.txt
./bin/tdmd-tui             # opens ./todo.md
TDMD_FILE=~/work/todo.md ./bin/tdmd-tui

Drop bin/tdmd and bin/tdmd-tui anywhere on $PATH if you want them globally.

Format at a glance

# [ ] task          top-level task
## [ ] subtask      nested task
- [ ] inline        list-style task
# category          heading with no checkbox = grouping node
> priority: P0      metadata for the nearest item
> eta: 2026-05-20
> owner: alice
> [2026-05-01] log  log entry (ISO date in brackets)
> free description  any other blockquote = description
![[other.md]]       embed another todo file

Full spec: SPEC.md. Worked example: examples/example.md.

License

MIT — see LICENSE.