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
|
> **🚧 PRE-ALPHA SOFTWARE:** This project is in a pre-alpha state and is intended for my own personal use only. Use at your own risk.
# timesamurai
`timesamurai` is a terminal time-tracking tool that combines:
- a stopwatch timer,
- worktime-style work log tracking,
- weekly reporting,
- and a Bubble Tea TUI.
Current version: `v0.6.0`.
## Installation
Requirements:
- Go (current project targets Go 1.24+)
- [Mage](https://magefile.org/) (optional, recommended)
Build with Mage:
```bash
go install github.com/magefile/mage@latest
mage build
```
Or build directly:
```bash
go build -o timesamurai ./cmd/timesamurai
```
## CLI Overview
`timesamurai` now uses Cobra and supports global flags:
```bash
timesamurai --version
timesamurai --config /path/to/config.json
```
Top-level command groups:
- `timesamurai timer ...`
- `timesamurai work ...`
- `timesamurai tui`
### `timer` Commands
```bash
timesamurai timer start
timesamurai timer stop
timesamurai timer continue
timesamurai timer reset
timesamurai timer status [--raw|--raw-minutes]
timesamurai timer prompt
timesamurai timer track <description>
timesamurai timer live [-f|--font <font>]
```
### `work` Commands
```bash
timesamurai work login [-c|--category <cat>] [--at <time>] [-d|--descr <text>] [--start-timer]
timesamurai work logout [-c|--category <cat>] [--at <time>] [-d|--descr <text>] [--stop-timer]
timesamurai work add <duration> [-c|--category <cat>] [--at <time>] [-d|--descr <text>]
timesamurai work sub <duration> [-c|--category <cat>] [--at <time>] [-d|--descr <text>]
timesamurai work day-off [--at <time>] [-d|--descr <text>]
timesamurai work use-buffer <duration> [--at <time>] [-d|--descr <text>]
timesamurai work status
timesamurai work report [--verbose] [--no-color]
timesamurai work edit
timesamurai work import <file>
```
## TUI
Launch the TUI:
```bash
timesamurai tui
timesamurai tui --disco
```
The TUI includes:
- tab-based navigation (`Entries`, `Report`, `Timer`),
- TaskSamurai-inspired table styling and status bars,
- vi-style global keys (`Tab`, `gt`, `gT`, `1/2/3`, `?`/`H`, `q`, `ZQ`),
- theme controls (`c` randomize theme, `C` reset, `x` toggle disco mode),
- entries timeline table flows (navigate columns with `h/l` and press `Enter` to edit selected field, including date/time/value/description; `D` opens day-off datepicker),
- report browsing,
- timer screen with work login/logout toggle (`l`).
## TUI Screenshots
Screenshots section (`v0.5.1` baseline):
- Entries screen: _to be captured_
- Report screen: _to be captured_
- Timer screen: _to be captured_
## Fish Shell Integration
Install fish prompt helper:
```bash
./install-fish-integration.fish
```
Then add `timesamurai_prompt` to your `fish_prompt` or `fish_right_prompt`.
|
