# VIT turns Taskwarrior into a full screen terminal interface with Vim style keys

> vit-project/vit is an MIT licensed Python program that renders Taskwarrior as a full screen terminal interface, with fully customisable key bindings, per-column colourisation, themes, tab completion and a built-in editor for column formatters, all built on the urwid widget toolkit and the tasklib client. The project is maintained by the Taskwarrior team and keeps its documentation in a set of markdown files beside the code rather than in a single manual.

**vit-project/vit** — VIT is a lightweight, fast, curses-based front end to Taskwarrior

- Repository: https://github.com/vit-project/vit
- Stars: 586 · Forks: 58
- Language: Python
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/vit-project-vit

## A full screen interface over a task list

VIT is described as a lightweight, fast, curses-based front end to Taskwarrior, and in the repository it is a Visual Interactive Taskwarrior full-screen terminal interface. The distinction from using task directly is the interaction model. Taskwarrior's own command line is a filter and a report, so you ask a question and get a list, and any change is another invocation. VIT keeps a persistent view of the list, gives it a keyboard-driven cursor, and lets you act on the selected item. The feature list reads like a list of the things a terminal interface tends to get wrong. There is an uncluttered display, no mouse at all, per-column colorization, advanced tab completion, and multiple customizable themes. The key bindings are fully customizable, with a default Vim-like set, which is the detail that decides whether the program feels like a tool you already know or one you have to learn.

## Themes and column formatters are the extension points

Two features do most of the work in practice. The first is the theme system, since the same task list looks different depending on whether you care about urgency, project or due date, and VIT lets you define more than one and switch between them. The second is the ability to override or customize column formatters, which is the interesting one. A column formatter decides how a field is rendered in a cell, and once that is overridable, the same task can be shown as a relative due date in one column and an absolute one in another, or a project shown with a different indent. That connects to the last feature on the list, intelligent sub-project indenting, which is a display concern that only becomes a real problem once you have nested projects. The documentation acknowledges that the interface borrows from a different tool, and it points to a separate COLOR.md because VIT handles task coloring differently than Taskwarrior, which is the kind of detail that catches out anyone coming from the underlying tool.

## The dependency list explains the design

The runtime requirements are three lines, and they tell you what the program is built on:

```text
tasklib>=2.4.3
urwid>=2.1.2
backports.zoneinfo;python_version<"3.9"
```

tasklib is the Python client for Taskwarrior, so VIT is a client in exactly the sense that it does not own your data, it reads and writes the same database through a supported interface. urwid is the widget toolkit that provides the curses-based interface, which is why the program can offer a full screen layout, themes and tab completion without a line of terminal escape handling written by hand. The third line is a compatibility shim, the zoneinfo backport pulled in only on interpreters older than 3.9, which is the kind of detail that shows the project still supports the Python versions it claims to. The README lists the requirements as Taskwarrior, Python 3.7 or newer, and pip, and the packaging metadata agrees with the 3.7 floor.

## Getting started is three commands and a config file

The installation instructions live in INSTALL.md, and the quick start is deliberately minimal. Run vit --help from the command line for basic usage instructions, run vit from the command line to start VIT with the default config, report and filters, and while VIT is running, type :help followed by enter to review the basic command and navigation actions. The recommendations then make the process concrete. VIT will suggest installing a default user config file if none exists, and that file is fully commented with all the configuration options, which is where most of the value of the program sits for a new user. For further tweaks the README points to CUSTOMIZE.md, and it advises using an xterm terminal for full color support. Troubleshooting is in FAQ.md, upgrading follows UPGRADE.md, and DEVELOPMENT.md covers the architecture for anyone who wants to contribute.

## The package is a handful of modules and a rewrite of the readme

The packaging is small enough to read in one sitting. The console entry point is declared as vit=vit.command_line:main, and the distributed packages are listed explicitly:

```python
    packages=['vit', 'vit.config', 'vit.formatter', 'vit.keybinding', 'vit.theme'],
```

Those five names are the architecture in miniature. There is a config module, a formatter module, a keybinding module and a theme module, plus the top level package, which matches the feature list almost one to one. The build backend is setuptools with a wheel, declared in pyproject.toml:

```toml
[build-system]
requires = [
    "setuptools>=42",
    "wheel"
]
build-backend = "setuptools.build_meta"
```

setup.py does something a little unusual as well. It reads README.md, rewrites the relative markdown links so they point at the 2.x branch on GitHub, since the README is published to PyPI where the relative links would otherwise break, and it reads the version out of vit/version.py with a regular expression rather than keeping the number in two places. The rest of the repository is the documentation set listed earlier, plus a test/ directory, a run-tests.sh script and a TEST-CASE.md.

## Where VIT is the wrong tool

Two cases. The first is a team that wants a mouse. VIT is explicitly a no mouse interface, and the recommendations even suggest a specific terminal for full color support, which tells you how much the rendering depends on the terminal rather than on a graphics stack. If your workflow is clicking through a task list, a graphical client is the better fit and VIT will fight you. The second case is a team that wants a different task model. VIT is a front end to Taskwarrior, so every capability it has is a capability Taskwarrior has, and anything Taskwarrior does not model is not something VIT can show. There is also a subtler cost. A full screen curses interface is fast to use once you know the keys and slow to learn, and the Vim-like defaults help only if you already think in Vim. The two problems compound, since the customisable bindings exist to solve a problem you may not have.

## Maintained by the Taskwarrior team, and still moving

The project is MIT licensed, with the LICENSE file at the repository root, and the packaging metadata records the same licence in the classifiers along with a Production/Stable development status and a Console environment. The release history shows steady but slow movement: v2.3.2 on 2023-10-17, v2.3.3 on 2025-02-22 and v2.3.4 on 2026-03-17, with the last push on 2026-09-15 and the default branch set to 2.x. The README also keeps the older line available, pointing readers who want VIT 1.3 to a separate tree, and the repository carries an AUTHORS.md and a CHANGES.md for the record. The final line of the README explains the stewardship. The project is in tribute to a collaborator, Steve Rader, who passed away in May 2013, and the Taskwarrior team preserved, maintained and continued vit, which is the honest reason a small terminal front end has survived well over a decade.

## Conclusion

Adopt VIT if you live in Taskwarrior and want to work through your task list in a full screen interface instead of a sequence of one-shot commands, since the key bindings, themes and column formatters are all adjustable without leaving the program. Do not adopt it if you want a mouse, or if you are looking for a task manager with a different data model, because VIT is a front end to Taskwarrior rather than a tracker of its own. Before you install, read INSTALL.md and the tasklib and urwid requirements, and check the UPGRADE.md notes, since the 1.3 line lives in a separate tree and the current work happens on the 2.x branch.

## FAQ

### What is VIT and what does it need to run?

VIT is a lightweight, fast, curses-based full screen terminal interface for Taskwarrior, written in Python. The README lists Taskwarrior, Python 3.7 or newer and pip as the requirements, and the runtime dependencies are tasklib, urwid and, on interpreters older than 3.9, the backport of zoneinfo.

### How do I install and start VIT?

The installation instructions are in INSTALL.md. Once it is installed, run vit --help for the command line usage, run vit to start with the default config, report and filters, and type :help inside the running program to see the command and navigation actions. VIT also suggests creating a default user config file, and that file is fully commented with all the configuration options.

### Which key bindings and themes does VIT support?

The key bindings are fully customizable and default to a Vim-like set, and there are multiple customizable themes. The README also lists per-column colorization, advanced tab completion, the ability to override or customize column formatters, and intelligent sub-project indenting. For further tweaks it points to CUSTOMIZE.md, and to COLOR.md because VIT handles task coloring differently than Taskwarrior.

### What is the module structure of the VIT package?

The distribution lists the packages vit, vit.config, vit.formatter, vit.keybinding and vit.theme, and the console entry point is vit=vit.command_line:main. setup.py also rewrites the relative markdown links in README.md to point at the 2.x branch on GitHub, and reads the version from vit/version.py so the number is not duplicated.

### Which release of VIT is current?

The default branch is 2.x, and the most recent release listed is v2.3.4 from 2026-03-17, after v2.3.3 and v2.3.2. The older 1.3 line is kept in a separate tree, and UPGRADE.md in the repository covers moving between versions.

## Sources

- [Issues](https://github.com/vit-project/vit/issues)
- [License: MIT](https://github.com/vit-project/vit/blob/2.x/LICENSE)
- [README](https://github.com/vit-project/vit/blob/2.x/README.md)
- [Releases](https://github.com/vit-project/vit/releases)
- [vit-project/vit on GitHub](https://github.com/vit-project/vit)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/vit-project-vit