> ## Documentation Index
> Fetch the complete content index at: https://smallsharpsoftwaretools.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Track Time With Timewarrior


[Timewarrior](https://timewarrior.net)  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]({{< ref "homebrew" >}}) tutorial.

## Installing Timewarrior

Install Timewarrior using your package manager. If you're on a Mac, you can install Timewarrior with `brew`:

```command
brew install timewarrior
```

On Ubuntu, use `apt`:

```command
sudo apt install timewarrior
```

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

```command
timew
```

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

```output
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:

```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:

```output
Tracking "blog post"
  Started 2026-08-20T17:01:46
  Current                  46
  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:

```command
timew stop
```

```output
Recorded "blog post"
  Started 2026-08-20T17:01:46
  Ended                 02:12
  Total               0:00:26
```

To get a summary, use the `timew summary` command:

```command
timew summary
```

```output
Wk  Date       Day Tags         Start      End    Time   Total
W34 2026-08-20 Thu blog post 17:01:46 17:02:12 0:00:26 0:00:26

                                                       0:00:26
```

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:

```command
timew track from 2026-08-20T08:00 to 2026-08-20T08:30 "blog post"
```

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

```command
timew summary :week
```

```output
Wk  Date       Day Tags         Start      End    Time   Total
W34 2026-08-20 Thu blog post  8:00:00  8:30:00 0:30:00
                   blog post 17:01:46 17:02:12 0:00:26 0:30:26

                                                       0:30:26

```

The [documentation](https://timewarrior.net/docs/) 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.