🚧 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.8.0.

Installation

Requirements:

• Go (current project targets Go 1.24+)
• Mage (optional, recommended)

Build with Mage:

go install github.com/magefile/mage@latest
mage build

Or build directly:

go build -o timesamurai ./cmd/timesamurai

CLI Overview

timesamurai now uses Cobra and supports global flags:

timesamurai --version
timesamurai --config /path/to/config.json

Top-level command groups:

• timesamurai timer ...
• timesamurai work ...
• timesamurai tui

timer Commands

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

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:

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:

./install-fish-integration.fish

Then add timesamurai_prompt to your fish_prompt or fish_right_prompt.