Gem Version Build Status

This is a Ruby client library for Gina Trapani's todo.txt. It allows for easy management of task lists and tasks in the todo.txt format.

Find the project on GitHub:

Find the full API docs on


Installation is very simple. The project is packaged as a Ruby gem and can be installed by running:

gem install todo-txt



A Todo::List object encapsulates your todo.txt file. You initialise it by passing the path to your todo.txt to the constructor:

require 'todo-txt'

list = "path/to/todo.txt"

Todo::List subclasses Array so it has all of the standard methods that are available on an array. It is, basically, an array of Todo::Task items.


You can filter your todo list by priority, project, context or a combination of all three with ease.

require 'todo-txt'

list = "path/to/todo.txt"

list.by_priority "A"
# => Contains a Todo::List object with only priority A tasks.

list.by_context "@code"
# => Returns a new Todo::List with only tasks that have a @code context.

list.by_project "+manhattan"
# => Returns a new Todo::List with only tasks that are part of the
#    +manhattan project (see what I did there?)

# And you can combine these, like so


A Todo::Task object can be created from a standard task string if you don't want to use the Todo::List approach (though using Todo::List is recommended).

require 'todo-txt'

task = "(A) This task is top priority! +project @context"

# => "A"

# => ["@context"]

# => ["+project"]

# => "This task is top priority!"

# => "(A) This task is top priority! +project @context"


The Todo::Task object includes the Comparable mixin. It compares with other tasks and sorts by priority in descending order.

task1 = "(A) Priority A."
task2 = "(B) Priority B."

task1 > task2
# => true

task1 == task2
# => false

task2 > task1
# => false

Tasks without a priority will always be less than a task with a priority.


The todo-txt gem requires Ruby 2.0 or higher.