Release Date
March 22nd, 2014
Last Updated
December 27th, 2020
Download zip   Download tar.gz

Melpa Status Melpa Stable Status

A simple Emacs extension for working with Beeminder.

beeminder.el is designed to integrate with org-mode, and adds support for submitting data directly to Beeminder when tasks are closed (see usage for some examples).

Thanks to Sacha Chua for providing the inspiration and initial code for this extension:


It is recommended to install this package directly from MELPA or via el-get.

Alternatively you can install manually. All Emacs installs are a little different, but the basic outline is this:


(setq beeminder-username   "username"
      beeminder-auth-token "token")
(global-set-key "\C-cba" #'beeminder-add-data)
(global-set-key "\C-cbg" #'beeminder-goals)
(global-set-key "\C-cbi" #'beeminder-my-goals-org)
(global-set-key "\C-cbr" #'beeminder-refresh-goal)
(global-set-key "\C-cbt" #'beeminder-submit-clocked-time)
(global-set-key "\C-cbw" #'beeminder-whoami)

The same setup for use-package looks like this:

(use-package beeminder
   :after (org)
   (("C-c b a" . beeminder-add-data)
    ("C-c b g" . beeminder-goals)
    ("C-c b i" . beeminder-my-goals-org)
    ("C-c b r" . beeminder-refresh-goal)
    ("C-c b t" . beeminder-submit-clocked-time)
    ("C-c b w" . beeminder-whoami)))

The recommended settings above will add the following keyboard shortcuts:

C-c b a (beeminder-add-data) - Add data to a Beeminder goal. Prompts for the goal identifier, a numeric value and an optional comment.

C-c b g (beeminder-goals) - Fetches all of your goals from Beeminder and displays them in a separate buffer. See “The goals buffer” for more information on how to use this.

C-c b i (beeminder-my-goals-org) - Fetches all of your goals from Beeminder and inserts them in the current buffer as a list of org-mode headlines.

C-c b r (beeminder-refresh-goal) - Update the current org-mode headline with information from Beeminder.

C-c b t (beeminder-submit-clocked-time) - Submits clocked time for the current goal (and any of its sub-tasks).

C-c b w (beeminder-whoami) - Fetches your username from Beeminder.


Interactive functions


Directly add data to a beeminder goal.


Fetches all goals for the current user (set via beeminder-username) and displays them in an interactive buffer.


Fetches all goals for the current user (set via beeminder-username) and inserts them as a list of org-mode headings.


Fetches goal data for the current headline and updates its properties and deadlines.

If the beeminder-skip-deadlines property is set to any value (such as “true”), the org deadline will not be updated.


Submit all clocked time for the current goal (and any of its sub-tasks). Only time clocked since the updated-at property is counted. Submits the number of minutes clocked as the value. If the goal property beeminder-unit is set to “hours”, it will submit the number of hours worked instead.


Fetches the username associated with the current token (set via beeminder-auth-token). Not really useful, but good for checking if your authorization token is set and valid.

The goals buffer

beeminder.el can browse your Beeminder goals directly from Emacs. Once your authentication token has been configured, call M-x beeminder-goals to open the goals buffer. It looks like this:

Viewing goals with

To refresh the list of goals, press g.

To close the buffer, press q.

To view information about a single goal, press [enter] when highlighting the goal to view.

The single goal buffer looks like this:

Viewing a single goal with

Like the goals view, pressing g will refresh the buffer.

Pressing q will close the buffer.

Data can be added to the current goal by pressing a. This will prompt for a value and optional comment.

To view all datapoints for the current goal, move the cursor to “View all data” and press the [enter] key.

Integrating with org-mode

beeminder.el listens for changes to the state of org-mode todo items, and can automatically add data to Beeminder once a task is complete. In order to do this, the task (or its ancestors) must have a beeminder property set to the name of the goal to add to.

By default, closing a task will submit a value of “1” to the appropriate goal. This behaviour can be customized using the beeminder-value property:

Setting beeminder-value to anything else will submit that value. If no beeminder-value property is set, a value of “1” will be used.

Here’s an example:

* Beeminder.el Tasks
   :beeminder: beeminder-el
** TODO Write documentation

When “Write documentation” is changed to “DONE”, a value of “1” will be submitted to the “beeminder-el” goal with “Write documentation” as the comment.

A headline’s properties will be updated with data from once it is closed. For org-mode habit headlines (i.e. headlines with their style property set to habit), all properties except beeminder-value are updated. This can be changed via the beeminder-excluded-habit-sync-properties variable.

;; Synchronize ALL properties of the habit when closed, including the value.
(setq beeminder-excluded-habit-sync-properties '())

;; Prevent target value from being synced.
(setq beeminder-excluded-habit-sync-properties '("beeminder-target"))