Mastering Taskwarrior-TUI
Taskwarrior-TUI is a beautiful and intuitive terminal-based user interface for Taskwarrior that brings visual structure and speed to your task management. Created by kdheepak, it combines the flexibility of Taskwarrior with a clean and customizable TUI interface.
🖼️ Taskwarrior-TUI in Action
🌟 Key Features
- Intuitive Navigation: Easily browse and filter your tasks with vim-like keybindings
- Rich Task Preview: See all task details, annotations, and dependencies in the preview pane
- Context Awareness: Automatically respects your Taskwarrior contexts and filters
- Customizable Views: Switch between different reports and customize the display
- Real-time Updates: Changes are immediately reflected in both the TUI and Taskwarrior's database
- Keyboard-driven Workflow: Accomplish everything without leaving the keyboard
- Color Themes: Supports custom color schemes to match your terminal setup
🚀 Quick Start
To install Taskwarrior-TUI:
brew install taskwarrior-tui # macOS
# OR
cargo install taskwarrior-tui # with Rust
Then simply run:
taskwarrior-tui
The app automatically detects and uses your existing taskrc and task data. You don’t need to do any additional configuration to get started.
🧭 Interface Overview
Taskwarrior-TUI opens up to a split-pane layout with:
- A task list on the left
- A preview pane on the right
- A filter bar at the bottom
This layout helps you focus while also giving context about the selected task and applied filters.
⌨️ Keybindings
Taskwarrior-TUI supports a rich set of keybindings to manage your tasks efficiently. Here are the most useful ones:
Default Keybindings
Global Navigation
| Key | Action |
|---|---|
Esc | Exit current action |
q | Quit |
? | Help menu |
[ | Previous view |
] | Next view |
Task Report Navigation
| Key | Action |
|---|---|
j | Move down in task report |
k | Move up in task report |
J | Move page down in task report |
K | Move page up in task report |
g | Go to top |
G | Go to bottom |
z | Toggle task info view |
Ctrl+e | Scroll task details view down one line |
Ctrl+y | Scroll task details view up one line |
Task Management
| Key | Action |
|---|---|
/ | Filter task report |
a | Add new task |
d | Mark task as done |
e | Open selected task in editor |
y | Duplicate tasks |
l | Log new task |
m | Modify selected task |
s | Toggle start and stop |
t | Toggle quick tag (default: next) |
u | Undo |
v | Toggle mark on selected |
V | Toggle marks on all tasks in current filter report |
x | Delete task |
A | Annotate current task |
: | Jump to task id |
c | Open context switcher menu |
1-9 | Run user defined shortcuts |
! | Custom shell command |
Filter/Command Prompt
| Key | Action |
|---|---|
Ctrl+f / Right | Move forward one character |
Ctrl+b / Left | Move backward one character |
Ctrl+h / Backspace | Delete one character back |
Ctrl+d / Delete | Delete one character forward |
Ctrl+a / Home | Go to the beginning of line |
Ctrl+e / End | Go to the end of line |
Ctrl+k | Delete to the end of line |
Ctrl+u | Delete to the beginning of line |
Ctrl+w | Delete previous word |
Alt+d | Delete next word |
Alt+b | Move to previous word |
Alt+f | Move to next word |
Alt+t | Transpose words |
Up | Go backward in history matching from beginning of line to cursor |
Down | Go forward in history matching from beginning of line to cursor |
Tab / Ctrl+n | Open tab completion and cycle to next element |
Backtab / Ctrl+p | Cycle to previous element |
Context Switcher
| Key | Action |
|---|---|
j | Move forward a context |
k | Move back a context |
Enter | Select highlighted context |
Calendar
| Key | Action |
|---|---|
j | Move forward a year in calendar |
k | Move back a year in calendar |
J | Move forward a decade in calendar |
K | Move back a decade in calendar |
You can customize keybindings in the configuration file if desired.
See full list at Keybindings Reference.
📦 Features
- Dynamic search and filtering
- Real-time preview of task details
- Multiple panes for better organization
- Custom filters and themes
- Fully keyboard-driven
- Built-in command line access
⚙️ Configuration
Taskwarrior-TUI uses the existing Taskwarrior configuration (~/.taskrc) and data files. It also supports its own TOML-based config for keybindings, filters, and UI settings.
Example config file location:
~/.config/taskwarrior-tui/taskwarrior-tui.toml
Check the full config guide in the GitHub repository.
💡 Tips
- Use
:to directly run Taskwarrior commands if something isn’t supported via TUI. - Save custom filters and map them to function keys for quick access.
- Adjust preview pane width by resizing your terminal.
📚 Resources
Taskwarrior-TUI is the perfect companion for CLI productivity enthusiasts. Whether you’re managing a simple to-do list or juggling multiple projects, it empowers you to do more with clarity and speed—all from your terminal.
Stay sharp, stay terminal. ⚡