Simple time tracking application using the CLI. In the spirit of todo.txt.
Tcl VimL
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


time_track.tcl Command Line Time Tracking

In the spirit of TODO.TXT, this little Tcl script will handle tracking how much time you spend on tasks throughout the day. All records are stored in a plain text file so you’re not dependent on anyone else’s format.


This program is released under the BSD license.



If you already have MacPorts installed on your OS X system, you can install the latest version of Time-Track-CLI via the command: sudo port install time-track-cli.

See for additional information on MacPorts.


Installation on *NIX systems should be pretty straightforward. The only dependencies are Tcl 8.5 or greater and the tcllib support library (specifically, the cmdline packet). If you’re running Ubuntu, you can install both of these using apt-get:

apt-get install tcl8.5 tcllib

On Windows, I recommend downloading the excellent ActiveTcl distribution from the folks at ActiveState

Data Storage

All data is currently stored in a single txt file in $HOME/.time_track/time_track.txt.


The script itself is still somewhat rudimentary, and help is sparse. So here are some usage tips to get you started.

First, the script itself is called time_track.tcl. All commands follow the format:

time_track.tcl <command> [options]

Most commands accept a -help that will list all of the available options, defaults, etc.

Basic Example

Assuming you only need basic time tracking, you can use the program as follows:

$ ./time_track.tcl start hacking on a project
$ ./time_track.tcl start hacking on another project
$ ./time_track.tcl stop
$ ./time_track.tcl summary
Charges to <NONE>
   hacking on a project -  1 hour
   start hacking on another project -  1 hour
Subtotal for <NONE> 2 hours
For the day 2 hours

Using Task Codes

Let’s say you work for multiple clients, and you spend a portion of each day working on tasks for each of your clients. You can track time for each client as follows:

$ ./time_track.tcl start -code client_a hacking on project 1
$ ./time_track.tcl start -code client_a hacking on project 2
$ ./time_track.tcl start -code client_b fixing some bugs
$ ./time_track.tcl start -code client_a more hacking on project 1
$ ./time_track.tcl stop
$ ./time_track.tcl summary
Charges to client_a
  hacking on project 2 -  18 minutes
  hacking on project 2 -  30 minutes
  more hacking on project 1 -  30 minutes
Subtotal for client_a 1 hour, 18 minutes
Charges to client_b
  fixing some bugs -  30 minutes
Subtotal for client_b 30 minutes
For the day 1 hour, 48 minutes



Lists all available commands along with a brief description.




The start command starts a new task. A new line is appended to the data file containing the starting time, along with a brief message describing the task. If a current task is running it will be stopped.


Option Description
-time Explicitly set the starting time for the task. Defaults to now.
-code Set an associated code for the task. This is useful for grouping multiple tasks together into a single account and is used in summarization. This parameter also accepts an alias for a code. See the list-aliases command for more details on aliases.


The stop command stops the current task. The current time is used as the ending time for the task.


Option Description
-time Explicitly set the stop time for the task. Defaults to now.


Summarizes all of the tasks for today and outputs a simple report detailing how long you spent on each task. Subtotals are provided for each task code as well as a total for the day.


Option Description
-date The date to summarize. Defaults to today.


Lists all of the active task codes along with the date they were last used and the last description.




Lists all of the aliases for task codes.

One or more aliases may defined for each task code you use to track your work. Aliases are just another way of referring to the task code. If a task code corresponds to a length project or account number for timekeeping purposes, then you may define multiple aliases that are easier to remember. These aliases may be used anywhere you would otherwise use a task code.

Aliases are defined in the $HOME/.time_track/aliases.txt file. One alias may be defined per line, with each line having the following format:

<alias> = <code>

For example:

customer_a = account.number.for.customer.a
customer_b = account.number.for.customer.b




Prints the currently active task along with the amount of time spent.




Cancels the currently active task, optionally resuming work on the previous task.


Options Description
-resume Resume work on the previous active task.


Prints the version number.



Hook Scripts

Time-Track-CLI supports the use of hook scripts to extend functionality. Hook scripts are small shell scripts executed at various stages within Time-Track-CLI. For example, the post-stop hook is executed whenever a task is stopped.

Currently the following hooks are supported:

  • post-stop – Executed whenever a task is stopped.

Example hooks scripts are included in the source distribution. All examples end with the extension *.sample. The post-stop.sample script includes an example of how to post your tasks to Twitter.

To use the hook scripts, simple copy one of the *.sample scripts to $(HOME)/.time_track, removing the *.sample extension. Then set the executable bits on the script.

Reporting Bugs and Requesting Features

Please report all bugs and feature requests via the Github issue tracker at