- Release Date
- March 22nd, 2014
- Last Updated
- December 27th, 2020
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: https://gist.github.com/sachac/9700455
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:
- Download the source code and put it somewhere Emacs can find it
- Add that directory to your
load-pathif it’s not yet there:
(add-to-list 'load-path "/path/to/dir")
(require 'beeminder)somewhere in your
- Set your API authorization token and Beeminder username configuration
variables. You can find your token by logging into Beeminder and then
visiting the following URI: https://www.beeminder.com/api/v1/auth_token.json
To set it in Emacs, add the following code (or use
(setq beeminder-username "username" beeminder-auth-token "token")
- Set up your keyboard shortcuts. Here are some recommendations:
(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) :bind (("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.
Directly add data to a beeminder goal.
Fetches all goals for the current user (set via
displays them in an interactive buffer.
Fetches all goals for the current user (set via
inserts them as a list of org-mode headings.
Fetches goal data for the current headline and updates its properties and deadlines.
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:
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:
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
prompt– Will prompt for a value to be submitted.
time-today– Will send the time worked on the task today. Setting
beeminder-unitto “minutes” will submit minutes worked, “hours” will submit hours. Defaults to “hours” for backward compatibility.
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 :PROPERTIES: :beeminder: beeminder-el :END: ** 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 beeminder.com once it is
closed. For org-mode habit headlines (i.e. headlines with their
habit), all properties except
beeminder-value are updated. This
can be changed via the
;; 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"))