ANDYCYCA NOTES: Jump to “Syntax” if you want the summary of it all.

1 What?

todo.txt is a… system of sorts for managing tasks and projects. The basic idea is to track your projects and tasks in a regular text file using a very simple, human-readable, machine parseable syntax.

2 Why?

Because it’s designed to be:

3 Who?

The original implementation was described/programmed by Gina Trapani, developer, blogger and founder of Lifehacker.

4 How?

Here’s the quick and dirty, starting from the rationale. Jump to “Syntax” to learn the actual implementation.

4.1 Main rationale

One line in your todo.txt file is one task.

4.2 Slicing

You should be able to “slice” your list of tasks by three axes: Priority, Project and Context.

4.2.1 Priority

Simply put, a triage of sorts that supersedes other criteria.

Ideally, more urgent tasks should appear “at the top” of the list.

Why? Because you should be able to quickly look at urgent tasks.

4.2.2 Project

A “Project” is anything that requires several steps or tasks to be done.

Ideally, tasks pertaining to a single project should be able to be grouped together.

Why? Because you should be able to look at a specific project and see easily what has been done and what is yet to be completed.

4.2.3 Context

A “Context” is the place/situation where you’ll work on the task.

Ideally, tasks pertaining to a particular space/time situation should be able to be grouped together.

Why? Because it helps fight procrastination. If you’re, say, fiddling around in your emails, you should be able to quickly look at tasks that need an email.

4.3 Syntax

There’s several rules to it, but a “full” completed task looks like this (in this order)

Sample Task
x (A) 2020-01-02 2020-01-01 Write *Beat Hazard 2* @writemonkey +e2 due:2020-01-31

In order, there’s

  • (Optional) An “x” marking whether the task is completed or not.
  • (Optional) Completion date
  • (Optional) Task creation date
  • The task description, which includes:
    • A @context,
    • A +project, and
    • Other user-defined key:value pairs (more on that later)

5 That’s it?

In essence, yes. Your todo.txt list is mostly unstructured by itself, but the above criteria are good enough let you search and sort your file in lots of ways. For example, if I sort my own list lexicographically ascending (as Notepad++ does) the list shows me, in this order:

  1. Tasks with Priority,
  2. Tasks with a creation date, from earliest to latest, in alphabetical order
  3. Tasks without a creation date,
  4. Completed tasks, ordered by completion date

This, in and of itself, is a very sensible way of ordering tasks for most general purposes. But the beauty of this system is that the syntax allows for filtering (“slicing”) in a meaningful way. For instance, filtering for +my-awesome-project lets me see that I’ve already completed set up website, that I still need to @call my agent and that think of a name has been sitting there for over a month.

6 What do you think, Andy?

I personally luuuuuuuv this system, but—like many other things I like—comes with the caveat that there’s some assembly required.

6.1 What I love

  • It’s simple
  • It’s fast
  • It’s lightweight on disk space and resources1
  • It’s not tied to a specific operating system, philosophy, company or propietary format
  • Requires little to no front up investment of time and money (you most likely already have a text editor in whatever device you’re using)
  • It’s easy to understand and—hopefully—easy to implement
  • It’s flexible enough to grow in very interesting—and sometimes unexpected—ways
  • Can be hacked

6.2 What I don’t like that much, or why I don’t recommend it to everyone

  • It’s relatively old, which means some software/apps aren’t very active
  • Requires hacking (or 3rd party tools) for generating statistics of any kind
  • Requires hacking (or 3rd party tools) for a clean and friendly user interface
  • Requires hacking (or 3rd party tools) for cross-device integration
  • Requires hacking (or 3rd party tools) for cross-person or cross-team integration
  • (I think you get the idea, right?)

The simplicity of this system is also why it might not be a good fit for many users. Out of the box, it’s very barebones and might pale in comparison with other systems/apps. There’s little to no visualization (other than sorting/filtering the text file itself). As I’m slowly entering my middle age, I find the use of colors to be more and more important in my personal organization, so I can easily discern between, say, different projects.

Fortunately, there’s no shortage of tools and programs for pretty much all major systems that help the end user in keeping, updating and managing their lists. I won’t put an exhaustive list here, but you can find a partial list in the sources below.

7 See also

8 Further reading

Appendix: key:value pairs

As mentioned in the “official” format document, todo.txt could theoretically be expanded in many ways. A very common one is the use of key:value pairs. For instance, one could mark a task’s due date by appending something like due:2038-01-19

The beauty of this system is that allows for an easy way of extending the three main slices by an arbitrary amount, as long as it can be represented with non-whitespace characters. This means that lots of nuances can be attached to the main system without extra «equipment».

I’ve seen a few useful pairs, some of which I’d like to share:

  • due:YYYY-MM-DD as it says on the tin, it’s the expected completion date of a particular task. This is probably the most requested feature of the original spec and there’s good (though mostly philosophical) reasons to not incorporate them «officially» (Trapani 2017; Descy 2015)
  • t:YYYY-MM-DD or threshold:YYYY-MM-DD used to describe the first date when a task should appear
  • url and link for referencing an internet resource
  • r, rec for indicating a recurrent task (depends on the actual implementation, but generally helps the software automatically create a new task with a due date in the future)
  • issue for specific use with Github

Utlimately, one should be the final judge in deciding whether these are used or not. Personally, I like to keep my file as free from dates as possible (with the exception of creation/completion, of course).

Also, the limitation of «non-whitespace characters» could perhaps be salvaged with the use of some kind of tag, like single- or double quotes, square or curly brackets, but these take from the intended simplicity of the system.


Descy, Michael. 2015. “Due Dates and Todo.txt.” Edited by Plaintext Productivity. 2015.

Trapani, Gina. 2017. “List of "Special Tag / Additional Definitions".” Edited by September 17, 2017.

  1. Honestly, if a simple .txt file starts becoming too large to be manageable, your problem might lie somewhere else. Even so, there’s many ways to prune this file. Keep reading.

Log in or register to write something here or to contact authors.