Need help with todotxt-machine?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

211 Stars 36 Forks GNU General Public License v3.0 291 Commits 28 Opened issues


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

Services available


Need anything else?

Contributors list


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
  • Archive completed todos
  • 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 uses 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
git clone
cd todotxt-machine

Command Line Options


Usage: todotxt-machine todotxt-machine TODOFILE [DONEFILE] todotxt-machine [--config FILE] todotxt-machine (-h | --help) todotxt-machine --version todotxt-machine --show-default-bindings

Options: -c FILE --config=FILE Path to your todotxt-machine configuraton file [default: ~/.todotxt-machinerc] -h --help Show this screen. --version Show version. --show-default-bindings Show default keybindings in config parser format Add this to your config file and edit to customize

Config File

You can tell todotxt-machine to use the same todo.txt file whenever it starts up by adding a

entry to the
file. If you want to archive completed tasks, you can specify a done.txt file using an
entry. You can also set you preferred colorscheme or even define new themes. Here is a short example:
file = ~/todo.txt
archive = ~/done.txt
auto-save = True
show-toolbar = False
show-filter-panel = False
enable-borders = False
enable-word-wrap = True
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

[colorscheme-myawesometheme] plain=h250 selected=,h238 header=h250,h235 header_todo_count=h39,h235 header_todo_pending_count=h228,h235 header_todo_done_count=h156,h235 header_file=h48,h235 dialog_background=,h248 dialog_color=,h240 dialog_shadow=,h238 footer=h39,h235 search_match=h222,h235 completed=h59 context=h39 project=h214 creation_date=h135 due_date=h161 priority_a=h167 priority_b=h173 priority_c=h185 priority_d=h77 priority_e=h80 priority_f=h62

You can add colorschemes by adding sections with names that start with

. Then under the
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

, ...,
or with the shortcuts for the color cube
, ...,
or gray scale entries
(black from color cube) ,
, ...
(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

You can customize any key binding by adding a setting to the

section of your config file

For a list of the default key bindings run:

todotxt-machine --show-default-bindings

You can easily append this to your config file by running:

todotxt-machine --show-default-bindings >> ~/.todotxt-machinerc

When you edit a key binding the in app help will reflect it. Hit

to view the help.

Known Issues


  • On Mac OS hitting
    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

    variable to

    export TERM=screen-256color

Planned Features

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


See the log here

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.