topydo: three interfaces over the todo.txt file format

The todo.txt file stays a plain text file

topydo works on the todo.txt format, the plain text convention where one task is a line of text with an optional completion marker, a priority, key value pairs and free text. The project is explicit that the format itself is limited, and that it extends the format with tags rather than replacing it. The file remains readable by other todo.txt tools, with the caveat stated in the documentation that those tools may not interpret the tags correctly.

That design choice is the whole character of the program. A task manager that stores tasks in a database has room for structured fields; a tool that edits a text file has to encode everything a user might want to filter on into a line of plain text. topydo takes the second road and makes the encoding work: it parses tags out of the line, keeps them there, and gives them meaning. The cost is that two applications reading the same file can disagree about what a particular tag means, and the benefit is that the file is still a file, still greppable, still the same file your other tools open.

Three interfaces sit on the same task file

The application has three user interfaces, and the distinction between them matters for how you would adopt it. The command line interface is the original one, inspired by the todo.txt CLI by Gina Trapani, and it is where the sorting, grouping and output control live. Prompt mode is described as a convenience mode for the CLI, launched with topydo prompt. Column mode is a text based user interface with customizable columns and vim-like bindings, launched with topydo columns.

The two optional interfaces are the interesting part because they come with their own dependencies, and the packaging reflects that. The column mode extra pulls in urwid and watchdog, and the prompt extra pulls in prompt_toolkit and watchdog, so a plain installation stays small. The console entry point is a single script, topydo=topydo.ui.UILoader:main, which means the same binary can dispatch to whichever interface you asked for.

pip3 install topydo
pip3 install topydo[columns]
pip3 install topydo[prompt]

The first line installs the base application, and the other two are the optional extras for the two richer interfaces. Installing everything at once is possible, but separating them keeps a minimal install to a single runtime dependency, which is arrow.

Tags carry dates, dependencies and recurrence

The extensions topydo supports natively are a short list, and each one answers a question the bare format cannot. Due dates and start dates come first, and they are what let a task appear only when it is relevant. Dependencies between todo items are supported, so one task can block another. Recurring items are supported, which is the hardest of the three to do in a flat text file, since a recurring task must be written back after completion without a separate rule store.

Everything else in the file is yours to define, and that is where the practical limits appear. A project context, a waiting-on note, a location or a priority scheme are all expressible in a tag, but topydo will not interpret them for you unless the configuration teaches it to. The documentation on the TiddlyWiki is where the feature set and the usage details live.

Two smaller conveniences are worth naming because they are the kind of thing that makes people stick with a tool: creation dates can be added automatically when an item is entered, and relative dates can be used, so you can say something like next Friday at the point of entry rather than computing the date yourself. There are also aliases for frequently used commands, and text based todo identifiers that are described as more stable and convenient than line based ones, which matters as soon as you reorder or delete lines.

Sorting, grouping and output formats decide what a run looks like

A todo.txt file is a flat list, so a tool that only prints it verbatim adds nothing. topydo offers fine-grained control over sorting and grouping items, plus customizable output, which is what turns a pile of lines into a working list. Grouping by project, by due date or by priority are the obvious moves, and the sorting controls are stated to be fine grained rather than a fixed set of presets.

The same pipeline also emits formats other than the text list. iCalendar, JSON and Graphviz Dot are named as additional output formats, which is the feature that turns the program into a component in a larger pipeline rather than only an application. The iCalendar output in particular is the one that changes daily behaviour, because it lets the same task list feed a calendar without a second copy of the data. The setup file also exposes an ical extra, pulling in the icalendar package, and an icalendar dependency sits in the test extra as well.

The Graphviz Dot output is a smaller feature with a clear use: a dependency graph is a graph, and the dependency support in the tag system can be rendered as one.

Configuration files decide the behaviour of both interfaces

The repository root carries two configuration files, topydo.conf and topydo_columns.conf, and their existence tells you where the flexibility lives. The column interface is described as having customizable columns, which cannot be configured without a file, so topydo_columns.conf is where the column layout is defined. topydo.conf is the general configuration for the rest of the program, and it is where things like sort order and output options are set.

That arrangement has an upside and a downside for a team. The upside is that the behaviour of the tool is in files you can commit, review and distribute, so everyone on a team can run the same list the same way. The downside is that a configuration file is another place for state to live, and a file with a rich configuration surface has a rich surface for mistakes. A custom sort key that references a tag nobody uses, for instance, produces an order that looks arbitrary until you read the configuration.

The project is also packaged in the conventional Python way, with pyproject.toml declaring a setuptools build, setup.py holding the metadata, and the version read from a file in the package rather than hardcoded, so releases pick up a single source of truth. Tooling configuration is present too, with black set to a line length of 79 and isort configured to the black profile.

The column interface borrows vim keys and watches the file

Column mode is the part of topydo that is not a thin wrapper over a text file. A text based user interface with customizable columns and vim-like bindings means the list is a table on screen, navigable with the keyboard, with each column showing one attribute of the task. The column extra also pulls in watchdog, a file monitoring library, and the documentation does not spell out how the view uses it, so it is fair to assume the interface is meant to react to the file changing underneath it rather than showing stale content.

That is the argument for a text based interface over a web or native application in the first place. The todo.txt file is the database, and every other tool that edits it works fine. A TUI that watches the file gives you a sortable, filterable view without taking ownership of the data, which is the difference between adopting topydo as a viewer and adopting it as the system of record.

The cost is the same in every case: the file format is the schema, and the schema is a set of conventions that only topydo interprets. Another tool that writes the same file will not know what a due tag means, and topydo itself only understands the tags it supports natively. Custom tags are readable and greppable, but they are not first class.

A GPL licence, an old release history and a busy commit line

The licence is GPL-3.0, and the setup metadata classifies the project as GPLv3 or later under an OSI approved licence. For a console tool that people install with pip, the practical question is whether you intend to redistribute it, and if you bundle it into a product or a managed environment, the copyleft terms of the GPL have to be looked at properly rather than assumed. The project also states that it is fully todo.txt compliant, so the file format itself carries no licensing constraint and remains readable by any other todo.txt tool.

The release history is unusual in shape. The tags are 0.13 in 2017, 0.14 in 2020 and 0.16 in 2026, so the version number has barely moved in six years while the commits have kept coming: the last push was on 2026-09-16. A project whose releases are this far apart relative to its commit activity is one where most users will be running a version that is old in date but not necessarily old in code, and where the repository is the real source of truth. The CHANGES.md file at the root is the place to look for what changed between versions.

The version is not hardcoded in the packaging metadata. The setup script reads it out of a version file inside the package with a regular expression, and raises an error if the version string cannot be found, which means a release built from an incomplete checkout fails loudly rather than shipping as version zero.

Editorial conclusion

Adopt topydo when your task list already lives in a todo.txt file and you want dependencies, recurring items and a keyboard driven view without moving to a proprietary format, and skip it when you need a shared team task system or a format that can hold structured data without inventing tag conventions. Before you commit, read the tags your existing file already uses, because the native support covers due dates, start dates, dependencies and recurrence and nothing else, and check topydo.conf and topydo_columns.conf, since the behaviour of both interfaces is configuration driven.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. Releases
5. topydo/topydo on GitHub