todo.txt: one line is one task, and every rule exists to keep plain sort working
‼️ A complete primer on the whys and hows of todo.txt.
At a glance
- What is it?
- A specification repository with no code in it: two READMEs, a licence and two images. The format has five rules for incomplete and completed tasks, and every one of them is chosen so that an ordinary text editor sorting alphabetically produces a sensible list, which is why priority sits in uppercase parentheses at the front, why dates are prepended, and why completion is a lowercase x.
- Who is it for?
- todo.txt suits someone who wants their task list to remain a file they own, readable and editable with anything from a terminal editor to a phone, and who is willing to learn five formatting rules instead of adopting a client's conventions.
- Can I use it commercially?
- Yes, with conditions. GPL-3.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
- Is it still maintained?
- Yes. The repository last received commits 140 days ago.
- What is it written in?
- GitHub does not report a main language for this repository.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- todotxt/todo.txt3,449 ★ · +40
| Repository | 2026-09-27 | 2026-11-15 |
|---|---|---|
| todotxt/todo.txt | 3.4k | 3.4k |
40 Stars in the last 49 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
A specification repository with no code in it
It helps to know what kind of repository this is before reading the rules. There is no source code, no build, no package to install and no published release. The root holds a licence file, an English README, a Korean translation of it, and two SVG images, one of them the Korean version. The repository description calls it a complete primer on the whys and hows of the format, which is accurate: this is the specification that client developers implement, not a client. That has a practical consequence for anyone arriving with a question about an app, because the answers here are about the file, and the repository also points to a chat channel for the wider community.
One line is one task, and no tool is required to read it
The first and most important rule is a single sentence: one line in the file represents one task. Everything else in the document is elaboration on that, plus the reason it works. Two goals are stated for the format. The file must be readable without any tool other than a plain text viewer, and a user must be able to manipulate it in a text editor in sensible, expected ways, with the example given being that an editor able to sort lines alphabetically should be able to sort your task list in a meaningful way. The pitch for plain text is made in the same register: it is portable, searchable and lightweight, it keeps working when someone else's server is down or a mail file is corrupt, and it has no export step, no database, no tags, no flags, no stars and no imposed prioritising rules.
Three axes: what is most important, which project, and where you are
The notation exists to make a list sliceable three ways. Priority is the first axis, described as something you assign optionally so the task bubbles to the top of the list, whether you are sorting by project, by context or overall. The second axis is project, on the argument that the only way to move a large project forward is to take a small subtask attached to it: cleaning out the garage is not a good item, but calling a charity to schedule a pickup is, inside the project for cleaning the garage. The third is context, following the suggestion from the author of Getting Things Done to split task lists by the place and situation in which you will work. Messages go in an email context, calls in a phone context, household jobs in a home context, so a few free minutes in the car become a filter you can act on immediately.
Priority is an uppercase letter in parentheses, and it always comes first
The first rule for incomplete tasks is about position. If a priority exists it always appears first, and the priority itself is an uppercase character from A to Z in parentheses followed by a space. That is the whole rule, and the document is careful about the near misses:
(A) Call Momis a prioritised task, while all three of these are not. A priority in the middle of the line, after some text, is not a priority at all:
Really gotta call Mom (A) @phone @someday
(b) Get back to the boss
(B)->Submit TPS reportA lowercase letter in parentheses is a different thing, and an uppercase letter followed by an arrow with no space is a third. Both are excluded by the same rule, which is why the format spec is worth reading closely rather than approximating.
A creation date goes directly after the priority, never at the end
The second rule places the optional creation date. It may appear directly after the priority and a space, and if there is no priority the creation date is simply the first thing on the line. The format is the four-digit year, dash, month, dash, day:
2011-03-02 Document +TodoTxt task format
(A) 2011-03-02 Call MomThe negative example is the one that trips people up, because the same digits in the wrong position mean nothing:
(A) Call Mom 2011-03-02has no creation date at all. That is not pedantry: the position is what lets a sort by date work, since a date at the end of a line sorts alphabetically with the rest of the text.
Projects and contexts may go anywhere after that
The third rule is the permissive one. Contexts and projects may appear anywhere in the line after the priority and any prepended date, with a context introduced by a space and an at sign and a project by a space and a plus sign. Either may contain any non-whitespace characters, and a task may carry none, one, or several of each. The example given packs four of them onto one line:
(A) Call Mom +Family +PeaceLoveAndHappiness @iphone @phoneand the surrounding examples show the permissive edge, a task with no contexts in it and a task with no projects in it, both of which are valid. That freedom is the reason the format calls itself completely unstructured: the fields you attach to a task are limited only by your imagination, and only the three rules above constrain them.
Completion is a lowercase x, and the dates sort themselves
Two rules cover finished work, and both are about sorting. A completed task starts with a lowercase x followed by a space, and the rule is case sensitive:
x 2011-03-03 Call Momis complete, while a word beginning with x, an uppercase x, and an x appearing after a priority are all not. Lowercase is chosen deliberately so completed tasks fall to the bottom under a standard sort and so the character reads as a filled checkbox. The completion date goes directly after that x, and if a creation date was prepended it follows the completion date, which is what lets you compute how many days a task took. One consequence is called out for client developers: many clients discard priority when a task completes, so to keep it you store it as a key and value pair such as a priority key with the letter A as its value.
Extra metadata is a key, one colon, and a value
The last section of the specification is the extension point. Tool developers may define additional formatting rules for extra metadata, and they are asked to use a key and value form, with a due date given as the example of a key holding an ISO date. The constraints on it are short: both the key and the value must consist of non-whitespace characters, neither may contain a colon, and exactly one colon separates the two. That is the same mechanism used to carry a priority across completion, so a client that discards priorities on purpose has a documented way to preserve the information, and a client that reads unknown keys has a documented way to skip them.
Editorial conclusion
todo.txt suits someone who wants their task list to remain a file they own, readable and editable with anything from a terminal editor to a phone, and who is willing to learn five formatting rules instead of adopting a client's conventions. It does not suit a team that needs shared assignment, reminders or a query language, because the format has no concept of any of those, and it does not suit anyone who wants tooling that comes with the specification, since this repository is documentation only. Three things to check before adopting it: whether your existing client preserves the metadata you already use, because clients are free to define extra key and value pairs and to discard priority when a task is completed; whether your sort tools behave the way the format assumes, since the ordering rules are built on plain alphabetical sorting; and whether losing the original priority on completion is acceptable to you, or whether you need to carry it in a key and value field to survive.
Frequently asked questions
what is todo txt
todo.txt is a plain text task format in which a single line represents a single task. Tasks can carry a priority, a creation date, project names introduced with a plus sign and context tags introduced with an at sign, and a completed task is marked with a lowercase x followed by its completion date. The format is designed so an ordinary text editor can sort and edit the file meaningfully.
how to use todo txt
Write one task per line. Put an uppercase priority in parentheses first if you want one, then an optional creation date in the form year dash month dash day, then your text with any projects and contexts anywhere after that. To finish a task, add a lowercase x and a space at the very start of the line, followed by the date you completed it, and any creation date after that.
What are the three rules for an incomplete task in todo.txt?
First, a priority always appears first and must be an uppercase letter in parentheses followed by a space. Second, a creation date may follow the priority and a space, or come first when there is no priority, in the format YYYY-MM-DD. Third, projects and contexts may appear anywhere after those, introduced by a space and a plus sign or a space and an at sign, and a task may have none, one or several.
How does todo.txt mark a task as complete?
With a lowercase x followed by a space at the start of the line, then the completion date. If the task had a creation date, that follows the completion date. The x must be lowercase and at the very start, so a word beginning with x, an uppercase x, or an x after a priority does not count as complete.
What is the key:value format in todo.txt?
It is the convention for extra metadata that tool developers add, such as a due key holding a date. The key and the value must both be non-whitespace and must not contain colons, and exactly one colon separates them. It is also the documented way to preserve a priority across completion, since many clients drop the priority when a task is marked done.
Why is todo.txt formatted the way it is?
Two goals: the file must be readable with nothing but a plain text viewer, and it must be editable and sortable with ordinary tools in ways that make sense. That is why priority and dates are prepended so a sort works, and why completion uses a lowercase x, which sorts to the bottom alphabetically and also looks like a filled checkbox.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/todotxt-todo-txt)Star history chart for your README
[](https://hysenlabs.com/projects/todotxt-todo-txt)Was this useful?