The arbtt package

[ Tags: desktop, gpl, program ] [ Propose Tags ]

arbtt is a background daemon that stores which windows are open, which one has the focus and how long since your last action (and possbly more sources later), and stores this. It is also a program that will, based on expressive rules you specify, derive what you were doing, and what for.

WARNING: The log file might contain very sensitive private data. Make sure you understand the consequences of a full-time logger and be careful with this data.

[Skip to Readme]


Versions 0.1, 0.1.1, 0.1.2, 0.1.3, 0.1.4, 0.1.5, 0.2.0, 0.3.0, 0.4, 0.4.1, 0.4.2, 0.4.3, 0.4.4, 0.4.5,, 0.5, 0.6, 0.6.1, 0.6.2, 0.6.4,, 0.7, 0.8, 0.8.1,,,,, 0.9,,,,,,,,,,,,,
Dependencies base (==4.*), binary, bytestring, containers, directory, filepath, mtl, parsec (==2.*), pcre-light, setlocale, tabular, time, unix, X11 (>1.4.4) [details]
License GPL
Copyright Joachim Breitner 2009
Author Joachim Breitner <>
Maintainer Joachim Breitner <>
Category Desktop
Home page
Source repository head: darcs get
Uploaded Thu Oct 8 17:48:27 UTC 2009 by JoachimBreitner
Distributions Debian:, LTSHaskell:, NixOS:, Tumbleweed:
Executables arbtt-dump, arbtt-stats, arbtt-capture
Downloads 9603 total (69 in the last 30 days)
Rating 0.0 (0 ratings) [clear rating]
  • λ
  • λ
  • λ
Status Docs not available [build log]
All reported builds failed as of 2016-12-31 [all 8 reports]
Hackage Matrix CI


Maintainer's Corner

For package maintainers and hackage trustees

Readme for arbtt-0.4

[back to package description]
arbtt, the Automatic Rule-Based Time Tracker

© 2009 Joachim Breitner <>

The Automatic Rule-Based Time Tracker is a desktop daemon that runs in the
background and, every minute, records what windows are open on your
desktop, what their titles are, which one is active. The accompanied
statistics program lets you derive information from this log file, i.e.
what how much of your time have you been spending with e-Mail, or what
projects are your largest time wasters. The mapping from the raw window
titles to sensible „tags“ is done by a configuration file with an powerful


You can build and install this program as any other Cabalized program:
 $ runhaskell Setup.hs configure
 $ runhaskell Setup.hs build
 $ runhaskell Setup.hs install

You also need to make sure that arbtt-capture is started with your X
session. If you use GNOME or KDE, you can copy the file
"arbtt-capture.desktop" to ~/.config/autostart/. You might need to put the
full path to arbtt-capture in the Exec line there, if you did not do a
system wide installation.

If you want to record samples at a different rate than one per minute, you
will have to pass the "--sample-rate" parameter to arbtt-capture. 


Once arbtt-capture is running, it will start recording, without further
configuration. The configuration is only needed to do an analysis of the
recorded data. Thus, if you improve your categorization later, it will
apply even to previous data samples!

The configuration file needs to be placed in ~/.arbtt/categorize.cfg. An
example file is included, which should be more enlighting than this rather
formal description.

Whitespace is non-significant and Haskell-style comments are allowed.

Here is grammar of the file:

Rules := [ "aliases" AliasSpec ] Rule ( ("," Rule)* | (";" Rule)* )

Rule := "{" Rules "}" | Cond "==>" Rule | "if" Cond "then" Rule "else" Rule
      | "tag" Tag

Cond := "(" Cond ")" | "!" Cond | Cond "&&" Cond | Cond "||" Cond 
      | "$" SVar "==" String | "$" SVar "/=" String
      | "$" SVar "=~" "/" Regex "/" |
      | "$" NVar NOp Number
      | "$" TVar NOp TSpec
      | "$" BVar
      | "current window" Cond
      | "any window" Cond

NOp := "<=" | "<" | "==" | ">" | ">="

SVar := "title" | "program"
NVar := "idle"
BVar := "active"
TVar := "time" | "sampleage"

The variables $title, $program, $active refer to the "window in scope". At
first, no window is in scope. Only when evaluating the condition passed to
"current window" or "any window", this changes.

For "current window", the currently active window is in scopre. If there is
no such window, the condition is false.

For "any window", the condition is applied to each window, and if any
window matches the condition, the result is true. If it matches more than
one window, of which match the variables $1,.. (see below) will be taken.

Tags are not enclosed in quotation marks, and contain only letters, dashes
or underscores (e.g. work).

They may be prepended with a category,
separated by a colon (e.g. Project:arbtt). This category can later be used
for pie chart like statistics. For each category, no more than one tags can
be matched per sample. If multiple tags with the same category are
generated by the rules, only the first one will be taken.

A tag can also interpolate variables, including in the category part.
Available variables are:
 $1, $2,..  Matches from the last successfully applied regular expression
            in the enclosing condition
	    The title or the name of the currently active program. If no
	    program happens to be active, this tag will be ignored.

The variable $time refers to the time-of-day of the sample (i.e. the time
since 0:00 that day), while $sampleage refers to the timespan from when the
sample was created until now, the time of evaluating the statistics. They
can be compared with expressions of the type "hh:mm", for example:
 $time >=  8:00 && $time < 12:00 ==> tag time-of-day:morning,


Run the statistics program arbtt-stats with the parameter --help to get an
overview of the options.

By default, any sample with the tag "inactive" are excluded from the
statistics, and tags with a percentage lower than one will not be shown.

The tags that affect the selection (-x, -o, --also-inactive) of samples can
be mixed with the report options (-m) and the reports (-i, -t, -c), but
will apply to all reports.

The flag --filter (-f) allows you to sepecify an arbitrary complex
condition using the same syntax for conditions that you can use in the
categorize.cfg file.

Some useful examples:

  # Only consider the time when I was programming in Haskell 
  arbtt-stats -o Editing-Haskell

  # Tell me what evolution folders I spend my time in when I actually do
  # work with e-Mail
  arbtt-stats -o Program:evolution -c Evo-Folder

  # Generate statistics about the last hour
  arbtt-stats -f '$sampleage < 1:00'

Data Dump

If you need to inspect the recorded sample, for example to think about
interesting things to match, use arbtt-dump.


You are very welcome to help the developement of arbtt. You can find the
latest source at the darcs repository at

Some of my plans or ideas include:

 * A graphical viewer that allows you to expore the tags in an appealing,
   interactive way. Possibly based on the Charts haskell library.
 * A better representation of the data in the log, to keep the size and 
   parsing speed down. 
 * Looking forward and backwards in time when writing rules. (Information
   is already passed to the categorizing function, but not exposed to the
 * $total_idle time, which is the maximum idle time until it is reset. This
   would allow the user to catch the idle times more exactly.
 * Rules based on day of time, to create tags for worktime, weekend, late
   at night.
 * Statistics based on time, to visualize trends.
 * Possibly more data sources?

Any help cleaning, documenting or testing the current code is appreciated
as well.