Task Samurai is a fast terminal interface for Taskwarrior written in Go using the Bubble Tea framework. It shows your tasks in a table and lets you manage them without leaving your keyboard.
- I wanted to tinker with agentic coding (actually, it has been mainly been generated by LLMs.
- I wanted a faster UI for Taskwarrior than other options like vit which is Python based.
- I wanted something built with Bubble Tea but never had time to deep dive into it.
Task Samurai invokes the task command to read and modify tasks. The tasks are displayed in a Bubble Tea table where each row represents a task. Hotkeys trigger Taskwarrior commands such as starting, completing or annotating tasks. The UI refreshes automatically after each action so the table is always up to date.
Press H to view all available hotkeys.
Example: press +, type Buy milk and hit Enter to add a new task called "Buy milk".
Press R to edit the selected task's recurrence. On a recurring task, press
Ctrl+R to edit the recurrence across the known recurring series.
Press : in either table or ultra mode to open a Taskwarrior command prompt.
The prompt supplies task; type arguments such as add Buy milk, projects,
or +home list. Press ; to open the same prompt pre-filled with the selected
task UUID, ready for commands like modify, annotate, or done. Press Tab
for completion, Enter to run, and Esc to cancel. Press Ctrl+O while in
the prompt to pop the current command line out into $EDITOR; when you save and
quit, the edited text is loaded back into the prompt so you can review it and press
Enter to run. Commands that print output
open a scrollable output panel.
Task Samurai has several toggle keys. Press v to switch between the full
table and a compact view (Pri, Project, Description, Urg). Press Z to toggle
auto-refresh, which reloads the task list every 10 seconds as if you pressed
space; a persistent auto-refresh: on (10s) indicator appears in the status line
(works in compact and ultra mode too, and reloads pause while you are typing).
Press B to toggle the row blink animation after task modifications, and press
x to toggle disco mode, which picks a random theme on every task change.
All of these are also listed on the in-app help screen (H).
There are two ways to install the tasksamurai command:
go install github.com/snonux/tasksamurai/cmd/tasksamurai@latestAlternatively, clone this repository and run:
mage installThe second method requires mage to be installed.
# Start with default pending tasks
tasksamurai
# Start with a Taskwarrior filter
tasksamurai +tag status:pending
tasksamurai project:work due:today
tasksamurai pri:H
tasksamurai -- -excludetag
tasksamurai -- -excludetag +includetag
# Any valid Taskwarrior filter can be passed as arguments--version: print the Task Samurai version and exit--browser-cmd <command>: command used to open URLs (default: firefox on Linux, open on macOS)--youtube-browser-cmd <command>: command used to openyoutube.com/youtu.belinks with theokey (default:chromium, so YouTube videos play in a browser better suited for them than the general--browser-cmddefault). Set it to""to route YouTube links through--browser-cmdlike any other URL.--agent-hotkey <key>: hotkey used to toggle the+agent/-agentfilter (default:3)--debug-log <path>: path to debug log file for Taskwarrior commands--debug-dir <directory>: directory for runtime debug output (goroutine dumps, profiles)--disco: start Task Samurai in disco mode, changing the theme every time a task is modified
If Task Samurai hangs, freezes, or stops responding to hotkeys (e.g. d
does nothing), build with -tags debugsignals and send SIGUSR1/SIGUSR2
to the running process to capture goroutine stacks, a snapshot of the UI's
own state, and full profiling data. See docs/debugging.md
for the full guide, including why hotkeys can silently stop working and how
to read each dump.