Description

Consult-org-clock is an Emacs package providing a consult-based interface to org clock. This allows the user to quickly clock into previous tasks. The main command of this package is consult-org-clock which can be seen as a “do what I mean” replacement of the built-in org-clock-in command (when the latter is called with a prefix argument). Apart from using the consult interface (and thus providing live previews), this package offers the following additional features:

• Clock out when selecting a heading that is currently clocked in, which removes the need for the org-clock-out command.
• Optionally add the Org heading at point to the list of candidates as the first (or second) element (see consult-org-clock-add-heading-clocked-out and consult-org-clock-add-heading-clocked-in).
• Optionally display the candidates with their file as a prefix (see consult-org-clock-show-name).
• A new command consult-org-clock-goto, replacing org-clock-goto with a consult-based version.

By using this completing-read interface, org mode is also streamlined, using the default completion mechanism of Emacs instead of its custom one.

Demonstration

demo.mp4

This demo uses the default configuration with consult and vertico.

In it, I start in a source code file and invoke consult-org-clock to clock into the respective task (which I have worked on before). I then clock out again, using the same command and switch to an org file. Then I move the cursor onto the Org heading “Write README”, which then appears at the top of consult-org-clock, allowing me to clock into that task. After switching to the README file, I decide to work on another project. Using consult-org-clock, I navigate the history and select the project I want to continue working on. This stops the clock for the running task (“Write README”) and starts it for the project in question. Finally, I switch to the corresponding project file and am ready to continue my work.

This demo hopefully highlights a possible usage of this package. Use consult-org-clock to clock into any tasks have been worked on recently. When starting to work on a completely new task, use other commands (e.g. consult-org-agenda) to navigate to the respective heading, from where consult-org-clock with the default candidate can be invoked to clock in.

Dependencies and Installation

This package requires at least version 27.1 (probably older versions work fine too) of GNU Emacs and depends on the following packages:

• org-mode (built-in)
• cl-lib (built-in)
• seq (built-in)
• consult

It is recommended to also install and configure vertico.

Default Configuration

Install the package via straight. The configuration may look as follows (using use-packge which is built-in since Emacs 29):

(use-package consult-org-clock
  :straight (:type git :host github :repo "overideal/consult-org-clock")
  :config
  (defun consult-org-clock-agenda-predicate (entry)
	"Return non-nil if ENTRY belongs to no file or to an org agenda file."
	(let ((file (buffer-file-name (marker-buffer entry))))
	  (or (not file) (org-agenda-file-p file))))
  (setq consult-org-clock-predicate-secondary #'consult-org-clock-agenda-predicate)
  :bind
  ("C-c C-x TAB" . consult-org-clock)
  ("C-c C-x C-j" . consult-org-clock-goto))

The main commands provided by this package are consult-org-clock and consult-org-clock-goto. This configuration binds those commands to the default bindings of org-clock-in and org-clock-goto (which however by default are only active in Org mode), essentially replacing those built-in functions. Feel free to choose different bindings or change some of the variables.

Customization

Many customization options are provided, run M-x customize-group consult-org-clock to see them. For example, with the following customization (put it inside the :config block of use-package or modified into the :custom block)

(setq consult-org-clock-add-heading-predicate #'org-at-heading-p)

the org heading will only be added if the cursor (point) is exactly on an Org heading. In contrast, if this variable is nil, a heading will also be added if the cursor is in the body of the heading (the text below it).

Comparison to other Packages

Here we compare this package with related ones:

• The org-mru-clock package served as inspiration for this package, given that it provides a completing-read based interface to org-clock-in. One drawback of this is that no preview is provided.
• The consult Wiki provides a small function implementing a consult-based interface to org-clock-in. Of course, this package (being an actual package) offers more features and customization options.

This package is different from the above in the following points:

• consult-org-clock only offers the previously clocked-in entries as candidates to choose from. The idea is to either clock into an already recently clocked-in task or use other commands to navigate to a new heading and then clock in with the cursor on the heading.
• consult-org-clock will clock out if the user selects a heading that is currently clocked into.
• consult-org-clock adds the current org heading to the top or second entry of the list, depending on whether a task is currently clocked in and on the user’s configuration.