blob: 94359f8bfcfbadca3ed25013f39418a624dc6aeb (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
|
# Task Samurai
<img src="logo.png" alt="tasksamurai logo" width="250" />
Task Samurai is a fast terminal interface for [Taskwarrior](https://taskwarrior.org/) written in Go using the [Bubble Tea](https://github.com/charmbracelet/bubbletea) framework. It shows your tasks in a table and lets you manage them without leaving your keyboard.
## Why does this exist?
- I wanted to tinker with agentic coding (actually, it has been mainly vibe coded using OpenAI Codex and Claude Code CLI)
- 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.
## How it works
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.
## Hotkeys
Press `H` to view all available hotkeys.
Example: press `+`, type `Buy milk` and hit Enter to add a new task called "Buy milk".
## Screenshot
## Installation
There are two ways to install the `tasksamurai` command:
```bash
go install codeberg.org/snonux/tasksamurai/cmd/tasksamurai@latest
```
Alternatively, clone this repository and run:
```bash
mage install
```
The second method requires [mage](https://magefile.org/) to be installed.
### Usage
```bash
# 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
```
### Flags
- `--browser-cmd <command>`: command used to open URLs (default: firefox on Linux, open on macOS)
- `--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
## Debugging
If Task Samurai appears to hang or freeze, you can capture runtime diagnostics using signal handlers to help diagnose the issue.
### Signal Handlers (Unix/Linux/macOS only)
Task Samurai supports two debugging signals:
#### SIGUSR1 - Quick Goroutine Dump
Captures all goroutine stacks to a timestamped text file for quick inspection:
```bash
# Find the Task Samurai process ID
ps aux | grep tasksamurai
# Send signal to dump goroutines
kill -SIGUSR1 <pid>
```
This creates a file like `tasksamurai-goroutines-20260204-143022.txt` showing what each goroutine is doing.
#### SIGUSR2 - Full Profile Dump
Captures comprehensive profiling data for deeper analysis:
```bash
# Send signal to dump full profiles
kill -SIGUSR2 <pid>
```
This creates multiple files:
- `tasksamurai-TIMESTAMP-goroutines.txt` - Goroutine stacks (text)
- `tasksamurai-TIMESTAMP-heap.pprof` - Memory allocations
- `tasksamurai-TIMESTAMP-cpu.pprof` - CPU profile (5 second sample)
- `tasksamurai-TIMESTAMP-block.pprof` - Lock contention events
### Analyzing Profiles
Use Go's pprof tool to analyze the binary profile files:
```bash
# Interactive analysis
go tool pprof tasksamurai-TIMESTAMP-heap.pprof
# Generate visualization (requires graphviz)
go tool pprof -web tasksamurai-TIMESTAMP-cpu.pprof
# Top functions by CPU usage
go tool pprof -top tasksamurai-TIMESTAMP-cpu.pprof
```
### Specifying Output Location
By default, debug files are written to the current working directory. Use the `--debug-dir` flag to specify a different location:
```bash
tasksamurai --debug-dir=/tmp/tasksamurai-debug
```
### Example Debugging Workflow
When Task Samurai hangs:
1. **Keep the hung process running** - Don't kill it yet!
2. Find the process ID: `pgrep tasksamurai` or `ps aux | grep tasksamurai`
3. Dump goroutines: `kill -SIGUSR1 <pid>`
4. Open the generated file to see what goroutines are blocked
5. If needed, dump full profiles: `kill -SIGUSR2 <pid>`
6. Analyze with pprof to identify the bottleneck
Common issues revealed by goroutine dumps:
- External `task` command hanging (stuck in syscall)
- Waiting for terminal input (blocked on I/O)
- External editor not responding
**Note:** Signal handlers are not available on Windows. Consider using `GODEBUG` environment variables or running under a debugger instead.
|
