Timewarrior builds with CMake, ships on five package managers, and tests across multiple Linux distributions

Two ways to track time, one binary

Timewarrior describes itself in one sentence that contains the whole product decision: simple stopwatch features as well as sophisticated calendar based backfill, along with flexible reporting.

Those are two different habits. A stopwatch starts when you start working and stops when you stop. Backfill means typing in what you did yesterday afternoon, which is what most people actually do at the end of a week. A tool that only supports the first habit loses data the moment you forget, and a tool that only supports the second asks for discipline nobody has.

The interval model is what unifies them. Work is recorded as intervals with a tag, and both the live tracking and the typed retrospective entry produce the same shape. Reporting then operates over those intervals, which is why the README calls the reporting flexible rather than describing specific report formats.

The command is timew, and the documentation lives at timewarrior.net/docs rather than in the repository. That is the main gap for anyone evaluating from source: the README covers installation and community, and defers usage to the website.

Building needs C++17, CMake 3.8 and Python for the tests

The build prerequisites are listed precisely enough to check against your machine before starting.

You need Git, CMake 3.8 or newer, Make, a C++ compiler with full C++17 support which is currently GCC 8 or Clang 5 or newer, Python 3 to run the test suite, and Asciidoctor for building the documentation. That last item is the one people discover late: documentation is generated from source in the repository, so a headless build server without Asciidoctor will fail on a target you did not expect.

Sources come either from a clone with submodules, or from a release tarball:

git clone --recurse-submodules https://github.com/GothenburgBitFactory/timewarrior
cd timewarrior

The --recurse-submodules flag is not optional advice. The repository has a .gitmodules entry at the root, so a plain clone leaves you with an incomplete tree and a confusing build error rather than a clear message.

Then the four build commands, with the test target in brackets because it is optional:

cmake -DCMAKE_BUILD_TYPE=release -S . -B _build
cmake --build _build -j
[cmake --build _build --target timew_test]
sudo cmake --install _build

The install prefix can be changed with -DCMAKE_INSTALL_PREFIX, and the README notes that cmake --install may not need sudo depending on where you install, which is the usual advice but worth repeating because it is where a build script breaks.

Package managers are the primary install path, not the fallback

The README leads with binary packages and treats building from source as the second option. That ordering is meaningful for a tool meant to be on every machine.

Badges name the distributions with maintained packages: Arch Linux as timew, Debian, Fedora, Ubuntu, and Homebrew on macOS. There is also a packaging status badge pointing at Repology, which aggregates the versions across distributions and is the fastest way to answer whether your platform is current.

A new release has to reach every listed repository, and users on a slow distribution will run an old version for months. That has a direct consequence for you: if you rely on a newly added flag, check the version your package manager offers rather than assuming the newest release is available.

The homepage at timewarrior.net carries downloads and news, and the README calls the project portable, well supported and active. The last push was on 2026-10-06 and the most recent release is v1.10.0 from 2026-08-02, so development continues after the tag.

A compose file that exists to test distributions, not to run the app

The most surprising file in the repository root is docker-compose.yml, because it does not define a Timewarrior service. It defines services whose names are distributions.

There is test-alpine-edge, test-alpine-latest, test-archlinux, test-centos-stream9, test-debian-stable, test-debian-testing, test-fedora-41, test-fedora-42, test-opensuse-leap and test-opensuse-tumbleweed among them. Each builds from its own Dockerfile under test/docker/, so a Linux distribution shipped in the last few years gets its own build context rather than being approximated by a generic base image.

Every service uses host networking, applies a runtime security label, and allocates a TTY. That combination is what a terminal program needs: it does not listen on a port, it reads from a terminal, and it writes files, so there is nothing to publish and nothing to bridge.

What this buys is glibc and toolchain coverage. A C++ program links against the system C library, and a build that passes on Fedora and fails on Alpine is a real class of bug that only shows up in a container matrix. The cost is CI time and a compose file that will confuse anyone looking for a way to containerise their own time tracking, which this one is not.

Repository layout, community channels, and the Taskwarrior connection

The rest of the root tells you what kind of project this is. src/ holds the C++, test/ the test suite including those distribution Dockerfiles, doc/ the documentation sources, and completion/ the shell completions, which tells you the tool is expected to be used with tab completion rather than by memorising subcommands.

There is a DCO file, meaning contributions require a Developer Certificate of Origin sign-off rather than a CLA. There is an AUTHORS file, a ChangeLog, an INSTALL file, and cmake.h.in and commit.h.in templates for generating headers from the build, which is how a version string ends up in the binary without editing a source file by hand.

There is also a pre-commit-config.yaml, so formatting is checked before a commit rather than in review.

The community arrangement is unusual for a small tool and worth knowing about. Timewarrior shares a Discord server with Taskwarrior, and the Reddit badge points at the taskwarrior subreddit rather than a timewarrior one. The README says the best place to ask questions is the Discord channel or the GitHub discussions forum, and points at timewarrior.net/support for other options. If you already use Taskwarrior, the overlap means the same community answers both.

Licensing is MIT, with the details in the LICENSE file, which makes Timewarrior safe to redistribute and to bundle in a commercial environment without copyleft obligations.

Editorial conclusion

Timewarrior suits someone who tracks time from a terminal and wants their data in plain files rather than in a web application, and it is the wrong tool for a team that needs multi user accounts, invoicing or a shared backend. Before building, check the compiler floor of GCC 8 or Clang 5 with CMake 3.8 or newer, since that is what the README requires, and prefer the distribution packages where they exist: the project lists Arch, Debian, Fedora, Ubuntu and Homebrew as maintained builds.

Frequently asked questions

Official sources

1. GothenburgBitFactory/timewarrior on GitHub
2. License: MIT
3. Project website
4. README
5. Releases