Time Tracking with Watson and Tmux


March 23, 2022

Reading time
10 min read

Time Tracking with the Watson CLI

Watson is a command-line tool to track your time across various projects. I don't do client work, but my schedule isn't always 8 AM to 5 PM. I want to keep my time around 8 hours a day, but I don't want to think about it too much. Also, I've been trying to move many of my tools to the terminal, so watson seemed like a great fit.

NOTE: I only touch the surface on the commands and flags available for watson. Feel free to check their documentation for more features.

Install Watson

There are several ways to install watson. If you are on macOS, then brew is a good option to install. The following command should update and install the program.

brew update && brew install watson

If you're on another system, then you could try using pip or pip3 to install watson. One of the following should work depending on which is available.

pip install td-watson
pip3 install td-watson

Starting a Project

Once you have watson installed, the next step is to start your first project with watson start name-of-your-project.

watson start my-project
~/github/my-project main
watson start my-project
Starting project my-project at 12:51

If you want to check if you have a project running or not you can verify using the watson status command. If you use git, then this command may sound familiar to you.

watson status
~/github/my-project main
watson status
Project my-project started just now (2022.03.23 18:58:08-0500)

Stopping a Project

When it's time to take a break or you are done working for the day, then you can stop your project with the watson stop command.

watson stop
~/github/my-project main
watson stop
Stopping project my-project, started 4 hours ago
and stopped just now. (id: 5dab13)

As before, you can run the watson status command to verify that you no longer are tracking a project.

watson status
~/github/my-project main
watson status
No project started.

Editing a Project

I've used other tools to track my time before watson and a common thing I'd find myself doing is to tweak the starting or ending time of a task. Sometimes I forget to start or stop my project, so having a way to modify these times is handy… watson edit to the rescue!

watson edit
~/github/my-project main
watson edit

Running the watson edit command will open the metadata for the currently running task or for the one that ended last. Then you edit the date/time and save your changes.

watson edit
 1 {
  1"project": "my-project",
  2"start": "2022-03-23 08:13:26",
  3"stop": "2022-03-23 11:55:30",
  4"tags": [],
NORMALeditor-2d7vqtp9.json{} json16%1:1

Logging Project Hours

You can view the log of how much you've worked with the watson log command. This is helpful because watson status only shows the most recent segment of work and does not list all frames for the day. The following is an example of the output from the command.

In the example, I'm using the flags -wGc

  • -c - Shows the current running frame in the results
  • -w - Shows results for this week
  • -G - Don't show the results using a pager
watson log
~/github/my-project main
watson log -wGc
Tue 22 March 2022 (4h 05m 31s)
42d276b 07:58 to 12:02 4h 04m 44s my-project
current 12:51 to 12:52 47s my-project

Tue 21 March 2022 (8h 14m 12s)
0518b42 07:58 to 12:20 4h 22m 07s my-project
5c57c2e 13:00 to 13:29 29m 13s my-project
a6be624 13:30 to 16:53 3h 22m 52s my-project

Generating a Project Report

The watson log command does a great job showing all the frame results for a given time period, but sometimes I want an overall number for a period. Running watson report will display a report of the time spent on each project.

In the example, I'm using the flags -dcG

  • -c - Shows the current running frame in the results
  • -d - Shows results for today
  • -G - Don't show the results using a pager
watson project
~/github/my-project main
watson report -dcG
Tue 22 March 2022 -> Tue 22 March 2022

my-project - 8h 16m 53s

Total: 8h 16m 53s

Pulling Today's Hours into Tmux Status Bar

I don't typically run all the above commands on a day-to-day basis. My typical flow is to run 2 or 3 commands (watson start, watson stop, watson edit). Instead of manually running watson status, watson log, or watson project I wrote a custom bash script that displays my daily hour summary in my tmux statusbar (see the following image).

Use watson report with grep and sed

The first step towards making the bash script was to figure out how to get just the amount of time I've worked today. To do this, I leveraged the watson report command and piped the results through grep and sed.

watson report | grep
~/github/my-project main
watson report -dcG | grep "Total: " | sed "s/Total: //"
6h 22m 42s

Wire up tmux to Execute a bash script for status-right

The following snippet in my tmux.config updates the interval that the status will be refresh, defines how wide the right status will be, and executes a custom bash script to be executed that will be the contents of my right status.

set -g status-interval 30
set -g status-right-length 140
set -g status-right "#( ~/.tmux/status-right.sh )"

Bash Script that Displays Hours Worked

The following is a simplified version of the script that I'm running, but hopefully, it gives a good indication of what is going on. The main pieces involve…

  1. Running watson status to switch the icon used (to indicate if I have a project started or not)
  2. Running watson report and piping that through grep and sed to get the hours worked
  3. Print the results to the terminal using colors and special characters
function mrwatson() {
    local status=""
    if [[ "$(watson status)" == "No project started." ]]; then
    local total=$(watson report -dcG | grep 'Total:' | sed 's/Total: //')
    local slot=$(printf "%s %s" $status "${total}")
    printf "#[fg=%s]#[fg=%s]#[bg=%s] %s #[bg=%s]" $1 $2 $1 "${slot}" $1

mrwatson $green $dark_gray

NOTE: If you want to see my full script you can reference my dotfiles.

Web Mentions

Tweet about this post and have it show up here!