My todo list lives in the repository

tdx - your todos, in markdown, done fast.

I don’t want every small project to come with a second project called “maintaining the task management system”.

Sometimes I just want a list next to the code. Clone the repository, open the list, carry on. If the tasks belong in the README, even better. The introduction and the unfinished business can share a file.

That is what tdx is for. It is a small terminal app that works directly on Markdown checkboxes. The Markdown file is the task list. There is no service somewhere else holding the real version.

Point it at the file you already have

Take an ordinary README:

# Tiny weather app

A weekend project. Bring your own umbrella.

## Next up

- [ ] Add a rain alert #feature
- [ ] Write the setup guide #docs
- [x] Make it run locally

## Run it

Use `npm run dev` to start the app.

Now run:

tdx README.md

That is the whole setup. No workspace to create, no project to import, no invitation to send yourself.

Edit tasks inside a real README. tdx 0.13.1 opens the sample README, ticks a task in the terminal UI, and leaves a normal Git diff. The surrounding prose stays in the file.

You get the comfortable parts of a todo app: keyboard navigation, toggling, editing, filtering, searching. Underneath, the result is still - [x] in your Markdown.

It also works without the interactive interface:

tdx README.md list
tdx README.md add "Check the rain alert on a real phone #testing"

One binary, no service

The 0.13.1 Apple Silicon release is a single executable of 9,661,858 bytes, about 9.66 MB. Other platforms differ a little. There is no application server or task database to run next to it.

The smallness I care about more is how little it asks of a project. Keep a todo.md beside the source, or put a checklist under a README heading. Commit it when that makes sense. Your normal Git workflow carries the tasks between machines and collaborators along with the code.

That does not turn a Markdown file into a live shared board. Git still has merges, and people still have to talk to each other. For most of my projects that is exactly the arrangement I want: the work travels with the repository, in a format I can read without tdx. If I stop using the app tomorrow, there is nothing to export. The list is already sitting there.

Other tools edit the same file

Because the file is ordinary Markdown, other tools are welcome to edit it too. That is a feature, and it is the reason saving deserves some care.

Say you tick a task in tdx while another editor adds a note to the same file. If tdx blindly wrote back its old copy, the note would be gone. Atomic writes alone don’t help with that. You can write the wrong contents very reliably.

01 / FOLLOW THE FILE

Two editors. One file. Your move.

You ticked a task in the app. Meanwhile, your other editor is perfectly capable of having opinions.

IN THE APP your pending edit

[x] Ship the thing

Opened disk version 1

ON DISK tasks.md

[ ] Ship the thing

Version 1

RECOVERY SNAPSHOTNo write yet. No snapshot in this example.

Try adding a note in the other editor, then save. Or save first to see the uncomplicated version.

A simplified model of conflict detection, review, and recovery. “Keep both edits” represents your deliberate resolution after inspection; it does not claim that tdx automatically merges arbitrary changes.

So tdx detects external changes, shows a conflict view, and keeps recoverable snapshots. The 0.13 line also has a :versions view for looking through the file’s history and restoring an older version. Those features exist so the simple idea can be trusted. They are not a reason to sign up for anything.

I wrote about building tdx last year. What keeps it useful to me hasn’t changed much: open the repository, find the next thing to do, tick it off without leaving the place where the work is.