💾 My todo list lives in the repository

I do not 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 I like about tdx. It is a small terminal application that works directly with Markdown checkboxes. The Markdown file is the task list. There is no central service holding the authoritative version somewhere else.

Point it at the file you already have

Here is 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 setup. No workspace creation, project import, or ceremonial invitation to yourself.

The app gives you a comfortable view of the tasks: keyboard navigation, toggling, editing, filtering, and searching. Underneath, the result is still - [x] in your Markdown.

You can also use it without opening the interactive interface:

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

A little tool, rather than another service

The 0.13.1 Apple Silicon release is a single 9,661,858-byte executable—about 9.66 MB. Other platforms have slightly different sizes. There is no application server or task database to deploy beside it.

The more important kind of smallness is how little infrastructure 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 usual Git workflow can carry the tasks between machines and collaborators along with the code.

That does not turn a Markdown file into a live collaborative board. Git still has merges, and people still have to coordinate. But for many of my projects, I want exactly that arrangement: the work travels with the repository, in a format I can read without tdx.

If I stop using the application tomorrow, the list does not need to be exported. It is already there.

Being a guest in the file comes with responsibilities

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

Imagine ticking a task in tdx while another editor adds a note. Writing the app’s old copy blindly would erase the note. Atomic writes alone do not solve that: you can write the wrong contents very reliably.

[x] Ship the thing

[ ] Ship the thing

External-change detection, a conflict view, and recoverable snapshots help make this arrangement trustworthy. The 0.13 line also includes a :versions view for inspecting file history and restoring a previous version. Those features support the simple idea; they are not the reason to sign up for a new system.

There is no new system to sign up for.

I wrote earlier about building tdx. What keeps it useful to me is still quite modest: open the repository, find the next thing to do, and tick it off without leaving the place where the work lives.