Timewarrior lets you record and track the time you spend on projects right from your terminal window.

What You Need

To complete this tutorial on macOS, you’ll need Homebrew installed, which you can do by following the Install Homebrew tutorial.

Installing TimeWarrior

Installing it is as easy as using your package manager. If you’re on a Mac, you can install Timewarrior with brew:

brew install timewarrior

On Ubuntu, use apt:

sudo apt install timewarrior

Once installed, run the timew command once to set up the default configuration and database file:

timew

The program asks you to confirm the location of the configuration:

Create new config in /Users/ssst/.config/timewarrior?
Create new database in /Users/ssst/.local/share/timewarrior? (yes/no)

Press y to confirm.

Then you can start tracking time.

Keeping Time

Use the start subcommand to start tracking time.

For example, to track the time you spent writing a blog post, you’d use the following command:

timew start "blog post"

This starts a new timer and tags the entry with the name of the task you’re working on.

Timewarrior shows some output on the screen as a result of the command:

Note: '"blog post"' is a new tag.
Tracking "blog post"
  Started 2024-05-14T13:02:43
  Current                  43
  Total               0:00:00

Once you’ve completed the task, or you need to switch gears to some other project, you use the timew stop command, which stops the timer and shows some results:

timew stop

Recorded "blog post"
  Started 2024-05-14T13:02:43
  Ended                 03:44
  Total               0:01:01

To get a summary, use the timew summary command:

timew summary

Wk  Date       Day Tags         Start      End    Time   Total
W20 2024-05-14 Tue blog post 13:02:43 13:03:44 0:01:01 0:01:01

                                                       0:01:01

The summary shows the week number, the date and day, the tag used for the entry so you can identify what you did, the start time, end time, and total time spent.

If you forget to record something, you can add an entry by specifying the start and end dates:

timew track from 2024-05-13T17:00 to 2024-05-13T18:00 Blog post

The timew summary command only shows the current day. Use timew summary :week to see the whole week’s time report:

timew summary :week

Wk  Date       Day Tags         Start      End    Time   Total
W20 2024-05-13 Mon blog post 17:00:00 18:00:00 1:00:00 1:00:00
W20 2024-05-14 Tue blog post 13:02:43 13:03:44 0:01:01 0:01:01

                                                       1:01:01

The documentation is detailed and covers more advanced usage.

Conclusion

If you spend a lot of time in the terminal, Timewarrior can help you track where you spend your time each day due to its approachable interface and low friction.