Around the time that my 3rd year at University was wrapping up, when I had looming coursework deadlines and a deep sense of foreboding for the upcoming exams, I came to the realisation that my organisation methods were inadequate. I was juggling courseworks I had to finish with the revision I had yet to start, whilst adding the final touches to my 3rd year project.

…That, or I just decided to procrastinate and have fun making something useful instead of revising for those exams. You decide.

Either way, I started envisioning a tool that would help me better organise my work. It could store todo lists in plain-text, allowing me to easily access them from the command-line. It could maintain separate todo list files, one for each separate area of my studies I wanted to organise. It could automatically find which todo list to use, based on the current directory…

And so I created Todor.

Yes, Todor. It’s a clever attempt to mimick the names of other trendy tools that intentionally drop some vowels in their names. In this case, it was supposed to be based on “Todo-er”. It also helped that I’m a huge fan of Game of Thrones.


Todor was designed with the UNIX philosophy in mind: do one thing, and do it well. It has a handful of useful features and very little else; you should be aiming to get things done, not waste time learning how to use a todo manager.

Todor command-line interface
Todor’s command-line interface is simple to use

Plain-text lists

Todor generates and stores tasks in two plain-text files inside a .todor directory: tasks for the main list of tasks yet to be completed, and done for tasks that have been done.

Because these lists are plain-text it means you can open the lists with your favourite text editor if you want to, and manage your tasks that way. This also means that it’s simple to version control your tasks, or perform diffs on them.

Multiple projects

Inspired by version control systems such as Git or Mercurial, any Todor commands that you run operate on the current project directory structure that you’re in. Todor recurses up the directory tree until it finds a .todor folder, and then uses that as the current project.

This means that you can create a Todor task list in the root folder of your projects, and then any todor commands will run on that list as long as you’re in that folder or in any of the folders nested within.

Generating IDs for tasks

To make referencing individual tasks in the Todor command-line tool easier, each task has a unique ID associated with it, generated by taking the SHA-1 hash of the task text.

These hashes can get quite long and unwieldy however, so Todor intelligently outputs only the number of characters for the IDs that needed to make all IDs in a list unique. In most cases this tends to be between 1-3 characters — much easier to deal with than full hashes!

Simple command-line interface

Adding, editing, listing, searching and completing of tasks can all be done via with the simple todor tool.

For some of the commands, such as when adding tasks, Todor can open the default text editor to make bulk operations easier.

Adding tasks in bulk with Vim
Tasks can be added in bulk with the system $EDITOR

Combining with other UNIX tools

Todor can be easily combined with other UNIX tools to achieve more advanced functionality.

For example, you can count tasks in Todor by piping the output of todor ls into wc:

$ todor ls | wc -l
$ todor ls --done | wc -l

If the Todor lists are stored along with the rest of your project files in a version-controlled repository, it is easy to see who added or completed a task using the standard “blame” functionality.

For example, to use Git to deduce who completed a recent task, you could use git blame on the .todor/done file in your project root:

$ git blame .todor/done
^6e89c29 (Jamie Davies 2014-05-05 00:49:26 +0100 1) Watch Game of Thrones
^6e89c29 (Jamie Davies 2014-05-05 00:49:26 +0100 2) Fix those bugs
^6e89c29 (Jamie Davies 2014-05-05 00:49:26 +0100 3) Feed the dog
93d5b4c3 (Jamie Davies 2014-05-05 00:50:35 +0100 4) Buy lots of beer

Whilst creating Todor might have started as a way to convince myself that the time I was wasting not revising for my exams was still being spent productively, it ultimately turned out to be a useful tool that I used throughout the rest of my time at University.

Maybe the next time I get some immovable deadlines I’ll get around to submitting it to PyPI and updating it to use Python 3.

Todor can be downloaded from GitHub, where you’ll also find more detailed documentation on the available commands.