Back to catalog
Timewarrior
MITTimewarrior is a private CLI time tracker that records hours in local plain text with Taskwarrior hooks, replacing centralized cloud timesheet apps.
Overview
Cloud time trackers require running browser tabs, clicking web widgets, and sending activity logs to external servers. Timewarrior tracks work entirely inside the terminal as local plain text, operating without background daemons, accounts, or network dependencies.
Where Timewarrior fits
Standard time tracking tools like Toggl Track or Clockify center around web dashboards, desktop widgets, and cloud synchronization. For developers and DevOps engineers immersed in shells, tmux sessions, and text editors, that model introduces constant context switching. Timewarrior replaces graphical timers with command-line verbs, allowing engineers to start, tag, adjust, and stop tracking intervals where they run builds and manage servers. Tracking becomes an extension of the shell prompt rather than an administrative chore separated from daily technical tasks.
Where Timewarrior diverges from commercial platforms is its strict local-first architecture. It provides no multi-user aggregation, manager approval workflows, or native invoicing engines. Teams do not use Timewarrior as a centralized timesheet repository; instead, individual engineers use it to capture accurate hours and stream JSON data into team billing pipelines or internal reporting scripts. Migrating from cloud tools means giving up graphical widgets and automated cross-device syncing in exchange for instant execution, zero subscription costs, and complete data sovereignty.
What it does well
- Taskwarrior hook integration: Official hook scripts connect directly to Taskwarrior, automatically starting and stopping intervals when engineers begin or complete tasks.
- Precise interval arithmetic: Commands such as
split,join,lengthen,shorten, andmoverepair mistakes and adjust overlapping sessions without manual timestamp calculations. - Configurable exclusion rules: Built-in holiday tables and defined working hours automatically split active intervals around lunch breaks and weekends to preserve accurate records.
- Plain-text flat files: Tracking records live in monthly text files under
~/.timewarrior/data/, simplifying Git versioning and inspection with standard Unix tools. - Extensible JSON pipeline: The extension architecture passes interval data as JSON through standard input, allowing custom scripts to generate specialized timesheets or status bar outputs.
