#i3 Tracker

An automated time tracker based on i3 and TimeWarrior.

#Dependencies

• i3-msg
• timew
• pkill

#Installation

To install, download the script and put it in your path.

#Running

tracker works by starting a timew task whenever you switch focus to a specific i3 workspace, and stops the tracker when you switch away from that workspace. It provides some fuzz by waiting 30 seconds before starting or stopping a timer, so you can jump away from a workspace (either on purpose or on accident) and back without stopping and starting the timer.

Be on the workspace where you're doing your work and run

tracker start <tag>

where <tag> is the tag tracker will use for the TimeWarrior tasks. Then go about your business.

Tracker should work with multiple workspaces -- that is, if you start trackers for each of your workspaces, it should do what you'd expect and allow you to track multiple activities. This hasn't been well tested, though, so you may encounter bugs.

If 60 seconds is too granular (or isn't granular enough, you hedgehog you), the variable LAG at the top of the scrip controls the reaction delay; the units are seconds (300 seconds for 5 minutes, etc).

Run tracker without arguments to get a more detailed list of run options. The most interesting ones are probably -d and -n, which turn on debugging and do-nothing modes, respectively. Use one or the other, not both.

#Reconciliation

There is a sketchy function called reconcile that can help clean up the history. If you generate invoices from TimeWarrior, having a bunch of noise in the records can be distracting. reconcile can help clean this up, and here's how it works:

1. It first deletes all records with less than a minute duration.
2. It then joins all records separated by less than 5 minutes -- that is, if the time stopped while you grabbed a cup of joe and you started working again 4 minutes later, those two records will be joined and the gap eliminated.
3. It then deletes all remaining records that are less than 5 minutes long.

It tells you exactly what it's doing as it does it, and then prints out the amount of time deleted, the amount of time added, how much that delta is in seconds, and how many operations it performed. That last bit is important, because if it looks like it really screwed up and ate your data, you can use timew undo to restore it. For example, if reconcile reports that it did 12 operations, you can run:

for x in `seq 1 12`; do timew undo; done

and get your data back. If you're a sissy, you can also run reconcile with a -n argument (before the tag) and it'll run in NOP mode -- it'll print what it would do, but won't actually do it.

For my workflow, reconcile ends up keeping things mostly fair; the end result neither adds nor removes much time to the overall report, and it can greatly reduce the number of records in the report.

Note that this can be used to simulate tracker being smarter about workspaces, and allow you to have multiple workspaces for the same task. You'd run tracker on multiple workspaces with the same tag, which would result in multiple back-to-back records as you switch between the workspaces. If you spent all of your time on only those workspaces, switching between them, you might end up with dozens of records for the day; reconcile would then collapse those into one contiguous record.

#Related

If you're a consultant using this, you may also find this invoice generator interesting. It produces nicely formatted PDF invoices from TimeWarrior data.