Skip to main content

An interactive terminal based todo.txt file editor with an interface similar to mutt

Project description

todotxt-machine is an interactive terminal based todo.txt file editor with an interface similar to mutt. It follows the todo.txt format and stores todo items in plain text.

In Action


  • View your todos in a list with helpful syntax highlighting
  • Define your own colorschemes
  • Tab completion of contexts and projects
  • Filter contexts and projects
  • Search for the todos you want with fuzzy matching
  • Sort in ascending or descending order, or keep things unsorted
  • Clickable UI elements


Python 2.7 or Python 3.4 on Linux or Mac OS X.

todotxt-machine 1.1.8 and earlier drew its user interface using only raw terminal escape sequences. While this was very educational it was difficult to extend with new features. Version 2 and up used urwid to draw its interface and is much more easily extendable.


Using pip

pip install todotxt-machine


Download or clone this repo and run the script.

git clone
cd todotxt-machine

Command Line Options


  todotxt-machine TODOFILE
  todotxt-machine [--config FILE]
  todotxt-machine (-h | --help)
  todotxt-machine --version

  -c FILE --config=FILE  Path to your todotxt-machine configuraton file [default: ~/.todotxt-machinerc]
  -h --help              Show this screen.
  --version              Show version.

Config File

You can tell todotxt-machine to use the same todo.txt file whenever it starts up by adding a file entry to the ~/.todotxt-machinerc file. You can also set you preferred colorscheme or even define new themes. Here is a short example:

file = ~/todo.txt
colorscheme = myawesometheme

Color Schemes

todotxt-machine currently supports solarized and base16 colors.

Pictured above are the following themes from left to right:

  • base16-light
  • base16-dark
  • solarized-light
  • solarized-dark

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. Here is an excerpt from that link:

High colors may be specified by their index h0, …, h255 or with the shortcuts for the color cube #000, #006, #008, …, #fff or gray scale entries g0 (black from color cube) , g3, g7, … g100 (white from color cube).

You can see all the colors defined here.

I recommend you leave the foreground out of the following definitions by adding a comma immediately after the =


If you want to use your terminal’s default foreground and background color use blank strings and keep the comma:


Let me know if you make any good colorschemes and I’ll add it to the default collection.

Key Bindings


h, ?         - show / hide this help message
q            - quit and save
t            - show / hide toolbar
w            - toggle word wrap
b            - toggle borders on todo items
S            - save current todo file
R            - reload the todo file (discarding changes)


mouse click  - select any todo, checkbox or button
j, down      - move selection down
k, up        - move selection up
g, page up   - move selection to the top item
G, page down - move selection to the bottom item
left, right  - move selection between todos and filter panel
H, L
tab          - toggle focus between todos, filter panel, and toolbar

Manipulating Todo Items

x            - complete / un-complete selected todo item
n            - add a new todo to the end of the list
o            - add a todo after the selected todo (when not filtering)
O            - add a todo before the selected todo (when not filtering)
enter, A, e  - edit the selected todo
D            - delete the selected todo
J            - swap with item below
K            - swap with item above

While Editing a Todo

tab          - tab complete contexts and projects
return       - save todo item
left, right  - move cursor left and right
ctrl-b       - move cursor backwards (left) by one word
ctrl-f       - move cursor forwards (right) by one word
home, end    - move cursor the beginning or end of the line
ctrl-a, ctrl-e
ctrl-w       - delete one word backwards
ctrl-k       - delete from the cursor to the end of the line
ctrl-y       - paste last deleted text


f            - open the filtering panel
F            - clear any active filters


s            - toggle sort order (Unsorted, Ascending, Descending)
               sort order is saved on quit


/            - start search
enter        - finalize search
C            - clear search

Known Issues


  • On Mac OS hitting ctrl-y suspends the application. Run stty dsusp undef to fix.
  • Mouse interaction doesn’t seem to work properly in the Apple Terminal. I would recommend using iTerm2 or rxvt / xterm in XQuartz.


  • With tmux the background color in todotxt-machine can sometimes be lost at the end of a line. If this is happening to you set your $TERM variable to screen or screen-256color

    export TERM=screen-256color

Planned Features

  • [STRIKEOUT:User defined color themes]
  • [STRIKEOUT:Manual reordering of todo items]
  • [STRIKEOUT:Config file for setting colors and todo.txt file location]
  • Custom keybindings
  • Add vi readline keybindings. urwid doesn’t support readline currently. The emacs style bindings currently available are emulated.
  • Support for archiving todos in done.txt


See the log here

Project details

Download files

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

Files for todotxt-machine, version 2.0.5
Filename, size File type Python version Upload date Hashes
Filename, size todotxt_machine-2.0.5-py2.7.egg (86.5 kB) File type Egg Python version 2.7 Upload date Hashes View
Filename, size todotxt_machine-2.0.5-py3.4.egg (88.9 kB) File type Egg Python version 3.4 Upload date Hashes View
Filename, size todotxt-machine-2.0.5.tar.gz (36.0 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page