Work-timers

Table of Contents

• What is this and why
• Usage
  • Workflow
  • Concepts
  • Notable customizable variables
  • Commands and keybinds
  • Integration with org-agenda
• Comparison to org-pomodoro
  • Differences
  • Similarities
  • Why I use work-timer instead of using org-pomodoro
• Mimicking X package
  • Org-pomodoro
  • Org-pomodoro-third-time
• Tips and tricks
  • Saving current timer across Emacs sessions with savehist
• Inspirations and related packages

What is this and why

Work-timer has in mind users who seek to regulate the duration and frequency in which they work and take breaks from their work. Those who have have large amounts of self-directed work time, for instance students and industrious employees, will appreciate this package the most. Work-timer is meant to be an automatic and therefore zero-effort way to apportion how long you should be taking a break given how long you worked (or: how long you should work given how long you want to take a break).

In addition to setting the duration of timers in a way desirable to the user, work-timer supports setting durations of timers but going beyond them, modifying the parameters of the current timer, pausing timers, and dynamically prompting for additions or subtractions to timer durations based on deviations in the duration and elapsed time of the durations of previous timers. (i.e. surplus time). (See Concepts for an explanation of relevant concepts.)

Usage

Workflow

Users are meant to start a working timer either with work-timer-start or work-timer-dwim. If during the timer the user wishes to modify the parameters of the timer, they can call work-timer-modify. When they wish, they can call work-timer-cycle-finish or work-timer-dwim to end the current timer and start a break timer. Then once they wish, they can once again call work-timer-cycle-finish or work-timer-dwim to end that timer and begin a new working timer.

The durations of all timers are automatically determined according to work-timer-work-duration-function and work-timer-break-duration-function.

Concepts

Running or elapsed time: Every timer has a running time, that is, the time since the timer began. (Using work-timer-modify, the running time of a timer can be modified.) This is effectively a stopwatch.

“Durations”

Throughout this README, timers are said to have durations which is determined once the timer is started. (Using work-timer-modify, the duration of a timer can be modified.) A sound (work-timer-sound) will play once the running time of the timer meets that duration. However, timers will continue to run beyond their duration indefinitely. This allows users the flexibility to go over or under the duration initially set by the timer (and take into account this overrun duration in work-timer-work-duration-function and work-timer-break-duration-function if they are configured to do so). In total, “durations” should be thought of more as targets rather than end-points.

Overrun time

The “overrun” time of a timer is the amount of time a user has spent passed the duration of the timer. It is the difference between the running time and duration. Overrun time can be usefully incorporated into work-timer-work-duration-function or work-timer-break-duration-function.

Working and break timers

Work-timer has “working” timers and “break” timers.[fn:1] These are essentially timers labeled as such to help determine the parameters of following timers. For instance, a user may want their break timer durations to be determined separately from their work timer durations.

Timer history

The parameters of every timer (e.g. type, duration, running time, and pauses) are stored in work-timer-history. In this way, work-timer-work-duration-function or work-timer-break-duration-function can leverage details of previous timer(s) to determine the duration for the next timer. The history is cleared when work-timer-end is called.

Surplus or “carry over” time

Surplus time is the amount of time added to a timer based on the amount of overrun time of previous timer(s) of the same type.

For example, if I worked for a period, then took a break 4 minutes shorter than my duration, the next break timer I have will ask if I want to add 4 minutes to the timer (or another user-inputted time). Likewise, if I took a break for 6 minutes longer than I should’ve, the next break timer will ask if I want to subtract 6 minutes (or another user-inputted time) from my break. Effectively, considering surplus time allows the user to “make up” for going over time in breaks or “given themselves a reward” for going above and beyond in work.

Currently, every built-in option for work-timer-break-duration-function considers surplus time when creating a new timer if work-timer-break-surplus-prompt-p is non-nil. (The current implementation of built-in break-duration functions will prompt the user for a surplus time before it is added.)

[fn:1] Work-timer is written such that users can neatly hack the internals of work-timer to add any number of other types of timers.

Notable customizable variables

All customizable variables can be seen and edited via M-x customize-group RET work-timer. However, below are a few variables most users would like to be aware of.

• work-timer-debug: Whether to print useful debugging messages.
• work-timer-time-format: Format of the time representation in the modeline.
• work-timer-sound: Sound file played when a timer’s running time meets its duration.
• work-timer-notifications-p: Whether to send notifications.
• work-timer-work-duration-function: Function used to calculate the duration of a new working timer.
• work-timer-break-duration-function: Function used to calculate the duration of a new break timer.
• work-timer-default-*: Variables relevant to the default/basic style of timers.
• work-timer-pomodoro-*: Variables relevant to the Pomodoro style of timers.
• work-timer-fractional-*: Variables relevant to the “fractional” style of timers. (See Org-pomodoro-third-time for a description of the fractional style of timer.)
• work-timer-break-surplus-prompt-p: Whether to prompt for a surplus time (see Concepts for a description of surplus time) when creating a new timer.[fn:2]

[fn:2] The prompt is only shown for break/work timer functions that use the work-timer--surplus-prompt function.

Commands and keybinds

Work-timer provides the work-timer-prefix-map keymap. Bind this keymap to any keybind you wish, e.g.:

(define-key global-map (kbd "C-c w") work-timer-prefix-map)

Below are the commands bound in work-timer-prefix-map and their keybinds in that keymap.

Command	Keybind	Description
work-timer-start	s	Start a “working” timer
work-timer-cycle-finish	f	Start a timer meant to proceed[fn:3] the current timer
work-timer-end	e	End current timer and clear history
work-timer-dwim	w	Either start a timer or cycle to a new timer
work-timer-pause-or-continue	p	Pause or continue the running time of the current timer
work-timer-modify	m	Modify the parameters of the current timer
work-timer-report	r	Print out statistics about work-timer-history

Additionally, work-timer provides the work-timer-transient-menu transient menu. Users can alternatively bind this transient map instead of work-timer-prefix-map.

[fn:3] That is, start a working timer if the current one is a break timer and start a break timer if the current one is a working timer.

Integration with org-agenda

Additionally, work-timer-with-org-clock-mode is a global minor mode that allows work-timer-dwim to work in org-agenda buffers. Calling work-timer-dwim clocks in the todo at point (in org-agenda buffers) while starting a work timer and clocks out the current todo (only in org-agenda buffers) while starting a break timer. (There is additional functionality written such that other behaviors between org-agenda and work-timer work as expected. See work-timer-org-clock-in, work-timer-org-clock-out, and work-timer-org-agenda-dwim.)

Comparison to org-pomodoro

Differences

• Work-timer supports arbitrarily complex ways to set the duration of timers. For instance, built-in is support determining timer duration based on the history of ran timers and how much time the previous was overran by.
• Work-timer allows for convenient user configuration/hacking by means of work-timer-work-duration-function and work-timer-break-duration-function.
  • work-timer also has more built-in support for useful ways to determine break and work durations beyond Pomodoro-style timers, e.g., work-timer-fractional-*.
• Work-timer supports pausing (and continuing) of timers.
• Work-timer offers work-timer-modify to modify the parameters of timers (e.g. running time, duration).
• Work-timer generally has cleaner code logic and more points of entry for users, making it more extensible, in my opinion. For example, work-timer-history and the several variables that hold information for the current timer are accessible for whatever the user needs, whether it be defining their own work-timer-work-duration-function or adding to work-timer-modify.
• Work-timer supports arbitrary timer types (for more flexibility than just work-break cycles).

Similarities

• Overrun in timers.
• Mode line indicator.
• Pomodoro-style timers.
• org-agenda integration

Why I use work-timer instead of using org-pomodoro

Overall, org-pomodoro comes closest to the behavior I seek. However, I found org-pomodoro lacking in flexibility. Flexibility in which sense? In two senses:

1. In-practice. There are many cases when I hoped org-pomodoro could support me doing one thing while it could not. To name just a few: a. Pausing. Sometimes I want to pause a timer because, say, I want to go to the bathroom without chipping away at the current work or break timer. b. Flexibility in timer durations. Sometimes I might be feeling particularly sluggish or particularly productive, and org-pomodoro did not have the flexibility for me to painlessly work or take a break for as long as I have in mind while also maintaining its purpose: off-loading the mental work of keeping such information top-of-mind to Emacs.
2. User-side hacking. org-pomodoro seemed implemented in such a way as to preclude as possibilities the functions are so outlined. Or, at least make it difficult.

As such, I made work-timer to try to ameliorate these pains.

Mimicking X package

Org-pomodoro

Setting work-timer-work-duration-function to work-timer-work-duration-pomodoro and work-timer-break-duration-function to work-timer-break-duration-pomodoro will mimic a pomodoro-style workflow. Working timers will be 25 minutes long (configurable by work-timer-pomodoro-work-duration; the pomodoro technique Kis usually don in multiples of 25 minutes, the second most common working duration being 50 minutes with 10 minute breaks) and break timers will be 5 minutes long (work-timer-pomodoro-break-duration-short) with 20 minute long breaks every 4 working timers (work-timer-pomodoro-break-duration-long).

Org-pomodoro-third-time

Setting work-timer-work-duration-function to work-timer-work-duration-fractional and work-timer-break-duration-function work-timer-break-duration-fractional will create a workflow similar to org-third-time’s workflow. Work timers will be 25 minutes long (work-timer-fractional-work-duration ) and break timers will be 0.2 times (work-timer-fractional-break-duration-fraction) the elapsed working timer (read Concepts for the difference between “durations” and “elapsed times”).

Tips and tricks

Saving current timer across Emacs sessions with savehist

Sometimes you have a running timer and Emacs crashes. Or perhaps you’d like to save the work-timer-history for one reason or another. work-timer simply saves the current work timer information in variables, so you can save these variables across Emacs sessions via savehist. work-timer is configured such that starting a new timer (via work-timer-start or work-timer-start-or-finish) will use the already set variable values, effectively resuming the timer.

;; Save timer variables to resume timer across Emacs sessions
(dolist (var '(work-timer-start-time
               work-timer-duration
               work-timer-type
               work-timer-pauses
               work-timer-history))
  (add-to-list 'savehist-additional-variables var))

If you do not want to save the timer history, feel free to remove work-timer-history. (It might be useful to know that work-timer-end wipes work-timer-history.)

Inspirations and related packages

• Org-pomodoro-third-time: Adapt org-pomodoro to implement the Third Time system
• Org-timer: built-in org-mode package.
• Tmr: Protesilaos Stavrou’s timer package.
• org-pomodoro: pomodoro technique for org-mode