todo.txt: The Plain-Text Task Format and How to Use It

What todo.txt Is and Who It Is For

todo.txt is a format specification for task management in a plain text file. The repository contains a README that defines the format rules, a LICENSE, and a description SVG image. It is not an application, a CLI tool, or a library. The repository documents how to structure a todo.txt file so that multiple tools can read and write it consistently.

The README states the first rule: a single line in your todo.txt text file represents a single task. This one-line-per-task constraint is the foundation of the entire format. It means any tool that can read lines of text, from grep to a spreadsheet, can work with a todo.txt file without parsing a binary format or connecting to a server.

The format is for people who want a durable, portable task list that does not depend on any particular application remaining available, and for developers who want to build task management tools on a documented, interoperable base.

The Three Axes: Priority, Project, and Context

The README describes three dimensions for organizing tasks. Priority is an uppercase letter from A to Z, enclosed in parentheses, that appears first on the line. A task with (A) sorts above one with (B), and both sort above an unprioritized task when a standard alphabetical sort is applied.

A project is marked with a plus sign directly before a word with no surrounding spaces, for example +GarageSale. A context is marked with an at-sign, for example @phone. Both can appear anywhere in the task line after the priority and any creation date. A single task can carry multiple projects and multiple contexts.

The practical value of this design is that standard text tools can filter the list. A grep for @phone shows only tasks that can be done by phone. A grep for +GarageSale shows only tasks belonging to that project. No application is required; the notation itself enables the filtering.

todo.txt Syntax in Detail

There are three format rules for incomplete tasks. First, if a priority is present, it always appears first. Second, a creation date may follow the priority, and if no priority is present, the creation date appears first. Third, contexts and projects can appear anywhere after the priority or creation date.

The README gives these examples:

(A) Thank Mom for the meatballs @phone
(B) Schedule Goodwill pickup +GarageSale @phone
Post signs around the neighborhood +GarageSale

A task with both a priority and a creation date looks like:

(A) 2011-03-02 Call Mom

Priority must use an uppercase letter. The README explicitly shows that (b) or (B)-> do not count as priorities under the spec.

Marking Tasks Complete

A completed task starts with a lowercase x followed by a space. Uppercase X does not count. A task starting with xylophone is not complete. This rule is deliberate: lowercase x sorts to the bottom of an alphabetical list, which places completed tasks below all incomplete tasks in a standard sort.

The date of completion follows the x and the space. If the task also has a creation date, the completion date comes first:

x 2011-03-02 2011-03-01 Review Tim's pull request +TodoTxtTouch @github

This ordering means a standard date sort on the completion column places recently completed tasks at the top or bottom consistently. With both dates present, you can calculate how long a task took to complete. The README notes that many clients discard priority on completion. To preserve priority through completion, the spec suggests using the key:value format, for example pri:A.

Extending todo.txt with key:value Pairs

The core format leaves room for tool-specific extensions through a key:value notation. Any non-whitespace string without a colon can serve as a key, and the value follows directly after the colon. A common convention is due:2010-01-02 for a due date.

The specification says both the key and value must consist of non-whitespace characters with no spaces, and only one colon separates them. The README does not define which keys are canonical or required. Individual clients define the key:value pairs they support. This means a due: date set in one client may not be read by another client unless that client also implements the same key. The spec provides the syntax but not a registry of standard keys.

Limitations: Recurrence, Subtasks, and Tooling Fragmentation

The format has no built-in concept of recurring tasks. A task that repeats weekly can only be represented by creating a new task each time, either manually or by a client that implements a recurrence extension. The specification documents no such extension.

Hierarchical subtasks are not part of the format either. The one-line-per-task rule means every task is a flat item. Projects mark that a task belongs to a group, but they do not create a parent-child relationship between tasks. A project tag is a string label, not a container.

The key:value extension system means clients are fragmented. A due: tag created by one application may be invisible to another. There is no canonical registry of valid keys, so interoperability between clients for extended metadata is not guaranteed by the format alone. Teams that need structured metadata, dependency graphs, or shared databases will reach the format's ceiling.

todo.txt vs Taskwarrior: Format Philosophy Compared

Taskwarrior is a CLI task manager that stores data in a proprietary binary format with a local database. It supports dependencies, recurring tasks, complex filters, and reports out of the box. The trade-off is that Taskwarrior data cannot be read by a plain text editor, and it requires Taskwarrior to be installed to access or modify tasks.

todo.txt takes the opposite position: the file is always human-readable, portable to any system with a text editor, and usable offline without installing any tool. The README states this goal explicitly: the file contents should be human-readable without requiring any tools other than a plain text viewer or editor. You give up structured queries and dependency tracking; you gain a format that works anywhere text works.

The repository specification itself is available under GPL-3.0. The last push was on 2026-06-28.

Editorial conclusion

The todo.txt format suits individuals who want a task list that works in any environment without installing software. A plain text editor, a standard sort tool, and grep are sufficient. Teams that need due date tracking, recurring tasks, dependencies, or multi-user synchronization will hit the format's ceiling quickly because those features require either key:value extensions with tool-specific support or a more structured system. The specification itself is a short document; read it directly at the repository before choosing a client, because client implementations vary in which extensions they support.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. todotxt/todo.txt on GitHub