23 releases (stable)

2.3.1 Jun 6, 2022
2.3.0 Apr 24, 2021
2.2.0 Mar 20, 2021
2.1.0 Dec 8, 2020
0.2.0 Dec 31, 2019

#1986 in Command line utilities


2.5K SLoC

rtw crate rtw documentation GitHub license

Branch Status
master Build Status

RTW - Rust Time Watcher

Command-line interface (CLI) time tracker.

CLI usage is stable, underlying API is not stable.

Note: This software is built specifically as a productivity tool for myself, not as a consumer resource. I cannot commit a large amount of time to maintaining this software but I'll do my best to provide support if something fails =).

This project is heavily inspired from Timewarrior.

For a stable feature-rich CLI time tracker, please use Timewarrior: https://timewarrior.net/.

Why another time tracker tool?

  1. learn Rust
  2. I once lost a month worth of data with another time tracker tool (database corruption)...never again!


Supported OS: Linux, MacOS, Windows

CI runs on ubuntu-latest, macos-latest, windows-latest.

Note: Windows support is only experimental. Some features may not be supported on Windows.


cargo install rtw

Build From Source

rtw compiles with Rust 1.42.0 (stable) or newer.

Clone and build from source:

git clone https://github.com/PicoJr/rtw.git
cd rtw
cargo build --release

From binaries (Linux only)

Download the corresponding archive from the Release page.

Shell Completion (Bash, Zsh, Fish, Powershell, Elvish)

Please see shell completion.

Starship prompt integration

# starship.toml
command = """ rtw status --format "{ongoing} {human_duration}" """
when = "test -f ~/.rtw.json"
shell = ["bash", "--noprofile", "--norc"]

~/.rtw.json is the file where rtw stores ongoing activities


Please see the CHANGELOG for a release history.

Basic Usage

Start tracking an activity


rtw start "learn rust"

Example output:

Tracking learn rust
Started  2019-12-25T19:43:00

Display current activity


Example output:

Tracking learn rust
Total    01:15:00

Stop current activity

rtw stop

Example output:

Recorded learn rust
Started 2019-12-25T19:43:00
Ended   2019-12-25T21:00:00
Total   01:17:000

Display the day's activity summary

rtw summary

Example output:

read the doc 2019-12-25T11:49:30 2019-12-25T11:53:36 00:04:246
eat cookies  2019-12-25T12:08:49 2019-12-25T12:12:14 00:03:204

Display a timeline for the day

rtw day

Example output (YMMV):



For further details see Full Usage.


RTW doesn't create the config file for you, but it looks for one in the following locations (in this order):

  1. $XDG_CONFIG_HOME/rtw/rtw_config.json
  2. $HOME/.config/rtw/rtw_config.json
  3. $XDG_CONFIG_HOME/.config/rtw_config.json
  4. $HOME/.config/rtw_config.json

see example folder for a default config file.


RTW relies on json files for persistence.

Default location is the home (~) directory.

~/.rtw.json  # stores current activity
~/.rtwh.json # stores finished activities

there is currently no file locking mechanism: running several rtw commands at the same time may lead to undefined behavior.

Similar Tools


~138K SLoC