Skip to main content

An interactive terminal based todo.txt file editor

Project description

todd is an interactive console TODO-list manager with VI key bindings.

It provides a minimalistic interface with a view on your todo list, following in the spirit of spirit of ranger and mutt.

The file format conforms to todo.txt. This means you have full control over your data and can choose to store it locally or in the cloud (like Dropbox). You can use different applications to access your tasks on your desktop or mobile devices.

Thanks to the creator and contributors of todotxt-machine for providing the basis for this project.


  • View your tasks in a column formatted list with relative due dates

  • Switch context (only view tasks that you can work on)

  • Sort by due date or priority

  • Search/filter

  • Edit in plain text with tab completion or adjust priority and due

  • Due dates can be set with

    • weekday name (mo, tu, …)

    • offset (2d in two days, 3m in three moths, 1y in a year)

    • a fixed date (YYYY-MM-DD)


Supports Python 3.6 on Linux or macOS.

Using pip

pip3 install todd

(Or pip install todd if Python 3 is the default for your system.)


Download or clone this repo and run the script.

git clone
cd todd
pip3 install -r requirements.txt

Command Line Options


  todd [--config FILE] [TODOFILE] [DONEFILE]
  todd (-h | --help)
  todd --version
  todd --show-default-bindings

  -c FILE --config=FILE               Path to your todd configuraton file [default: ~/.toddrc]
  -h --help                           Show this screen.
  --version                           Show version.
  --show-default-bindings             Show default keybindings in config parser format

Config File

You can tell todd to use the same todo.txt file whenever it starts up by adding a file entry to the ~/.toddrc file. If you want to archive done tasks, you can specify a done.txt file using an archive entry. You can also set you preferred colorscheme or even define new themes.

Here is a short example:

file = ~/todo.txt
archive = ~/done.txt
enable-word-wrap = True
colorscheme = myawesometheme

Color Schemes

Here is a config file with a complete colorscheme definition:

file = ~/todo.txt
colorscheme = myawesometheme


You can add colorschemes by adding sections with names that start with colorscheme-. Then under the [settings] section you can say which colorscheme you want to use.

The format for a color definitions is:


Foreground and background colors are follow the 256 color formats defined by urwid. You can see all the colors defined here.

Key Bindings

See active key bindings with h or ? in todd.

You can customize any key binding by adding a setting to the [keys] section of your config file ~/.toddrc.

For a list of the default key bindings run:

todd --show-default-bindings

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

todd-0.0.7.tar.gz (20.7 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page