Skip to content
a POSIX-compliant utility for comfortable time management
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


a simple POSIX-compliant utility for comfortable time management


timemaster lets you record how much time you spend on different activities. Before we cover its features in more detail, let's mention a few keywords we'll be using:

  • By stage, we mean a time period. You may for example want to begin new stages monthly.
  • We will refer to the different actions you will be recording simply as activities.
  • Saving directory is the directory where timemaster stores all its data.

Less important facts will be written in italic. Note that in the code examples, timemaster is referred to as simply tm. It is recommended that you add timemaster to your $PATH as tm, or another short convenient label of your choice.


Now, let's cover all the commands.


tm -h and tm --help print a short rundown on timemaster's commands. Whenever you are not sure about the usage, you can use this.


tm set [saving directory] lets you set the saving directory. You don't need to use this command if you don't want to reset it to another one, because you will be asked which directory to use if you don't set it before the first start or begin.


tm begin [stage name] sets the current stage name


Timemaster stores all the settings in ~/tm.set. Each stage has its data stored in a different file inside the saving directory.

start and stop

tm start [activity] and tm stop [activity] start and stop an activity. If you don't want to waste your time on writing a 5 letter long word, you can use tm s [activity](lowercase s) for start and tm S [activity](capital S) for stop.


tm recap [stage name], perhaps the most important command, prints how much time in total you spent on all activities during the selected stage (along with their wages, if any are set).

If you don't specify the stage name, the current stage will be recapitulated.


tm status prints the current settings (in case you forget) and currently running activities.

autostop and multi

If your goal is to continuously switch between activities, you may want to run the tm autostop + command, which will make timemaster stop all running activities when starting a new one (cutting down the need to stop them manually).

If you want to be able to have multiple activities running at once, run the tm multi + command.

tm autostop - and tm multi - unset these settings.

Both these commands have a shorter version: tm a+, tm a-, tm m+ and tm m-

These options are disabled on default, which ensures that you don't leave any activity running when starting a new one.


Timemaster also lets you set 'wages' for your activities. The syntax for that is tm wage [activity name] [h/m/s] [wage value(integer)] [unit], where h means hour, m minute, and s second.

For example, if you want to reward yourself with a cookie for every hour of workout, you may run: tm wage workout h 1 cookies Or if you work from home and your salary is $2000 a second, you may run: tm wage work s 2000 USD

As stated above, these settings than take effect when recapitulating a stage (your deserved wage will be printed along with the time you spent on the activity).

Wages are not stage specific (they are stored in the ~/tm.set config file), so you don't have to reset them every time you begin a new stage.



IMPORTANT NOTE: You should only use letters from the English alphabet for activity, stage, and unit names. Other characters are not permitted.

You can’t perform that action at this time.