Tracking Tasks with todo.txt: One Line, One Task

Quick answer

todo.txt is an open plain-text format for tasks, and its first and most important rule is simple: each line in the file is one task. Everything else is optional: a priority, a date, +project and @context tags, and key:value metadata.

A complete line looks like this:

(A) 2011-03-02 Call Mom +Family @phone due:2011-03-05

The appeal is ownership, plain and simple. As one write-up on why to use todo.txt puts it, "You own your to-do list," so you decide how to edit, back up, and sync it. The cost is a plain interface: the same author admits "It's not pretty, but it's very functional."

If you already keep checkbox lists inside notes, see task lists in Markdown. todo.txt is different: it is a single standalone file with its own grammar, built to be sorted and filtered line by line.

Step-by-step

1. Write one task per line

Open a plain todo.txt file and type a task. No bullet. No checkbox.

Post signs around the neighborhood +GarageSale
@GroceryStore pies

A line break ends the task. That's the whole format at its smallest.

2. Add a priority

A priority is an uppercase letter from A to Z in parentheses, followed by a space. It must be the first thing on the line.

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

Not valid: a lowercase letter such as (b), or a trailing form such as Call Mom (A).

3. Add a creation date

A creation date is optional. When you use one, write it as YYYY-MM-DD right after the priority, or at the start of the line if there is no priority.

(A) 2011-03-02 Call Mom

(A) Call Mom 2011-03-02 is not valid, because the date has to come before the description. The year-first order is also why YYYY-MM-DD sorts correctly in any tool that sorts text.

4. Tag projects and contexts

A project starts with + and a context starts with @. Each must be preceded by a single space and can contain any non-whitespace characters. A task can carry zero or more of each, anywhere after the priority and date.

(A) Call Mom +Family +PeaceLoveAndHappiness @iphone @phone

Projects answer "what is this part of?" Contexts answer "where or with what can I do this?"

5. Add key:value metadata

Tools can add their own fields as key:value, for example due:2010-01-02. Key and value must both be non-whitespace and contain no colons, with exactly one colon between them.

Renew passport due:2026-12-01

6. Complete a task

To finish a task, start the line with a lowercase x and a space. The completion date follows, then the creation date if the task had one.

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

The spec notes that the lowercase x sorts completed items to the bottom. These are not complete: xylophone lesson, X 2012-01-01 Make resolutions, and (A) x Find ticket prices.

7. Put it together

Here's a small file that uses every piece. Active tasks sit on top, and the completed one has the x prefix:

(A) 2026-10-09 Book dentist +Health @phone due:2026-10-16
(B) 2026-10-08 Draft release notes +Launch @laptop
Water the plants @home
x 2026-10-08 2026-10-07 Pay electricity bill +Home

Each line stands alone, so you can read, reorder, or delete a task without touching the rest. Priority, project, context, and due date are all just text on the line, which is why any editor can work with the file.

Common problems and fixes

A priority or date is ignored. Check position. The priority must be first on the line, and the creation date must sit right after it.

A finished task is not recognized as done. The marker is a lowercase x followed by a space, at the very start. An uppercase X, or an x after a priority, does not count.

The priority disappears when you complete a task. The spec says some clients clear the priority on completion. Keep it by adding pri:A to the line.

Two tools disagree on a detail. Derived specs exist. One, todotxt-spec, restricts itself to 7-bit US-ASCII and notes that it lacks some post-2016 changes from the main project. Check which version your tools follow before you lean on an edge case.

You have to run your own setup. This is the trade-off the format asks for: the command line and unusual syntax put some people off, and plain text means you pick the tools and handle sync. Back up the file like any other notes, since nothing else is keeping a copy.

Doing this with Carets

A todo.txt file is plain text, which is exactly what Carets is built for. It is a native notes and code editor for iPhone, iPad, and Mac, so the same file opens the same way on every device you use. Because Carets keeps your files as plain text, nothing about your task list is locked into an app.

Two things help. Carets organizes work into files, projects, and tags, so a todo.txt can sit next to the project it belongs to. And it handles plain text and Markdown in one editor, so your task file and your notes live side by side. To sync plain-text files across devices, follow the setup in that guide.

Get Carets on the App Store for iPhone, iPad, and Mac and start your first todo.txt.

Frequently Asked Questions

Does the priority have to be at the start of the line?

Yes. The spec requires the uppercase letter in parentheses, followed by a space, to come first. Something like Call Mom (A) is not a valid priority.

Can I use lowercase priorities such as (b)?

No. A priority is an uppercase character from A to Z, so (b) is not recognized.

How do I mark a task as done?

Start the line with a lowercase x and a space, then the completion date, then the creation date if there is one. The lowercase x also sorts finished tasks to the bottom.

What is the key:value syntax for?

It carries extra metadata such as due:2010-01-02. The key and value must be non-whitespace and contain no colons, with exactly one colon between them.