org-super-agenda

This package lets you “supercharge” your Org daily/weekly agenda. The idea is to group items into sections, rather than having them all in one big list.

Now you can sort-of do this already with custom agenda commands, but when you do that, you lose the daily/weekly aspect of the agenda: items are no longer shown based on deadline/scheduled timestamps, but are shown no-matter-what.

So this package filters the results from org-agenda-finalize-entries, which runs just before items are inserted into agenda views. It runs them through a set of filters that separate them into groups. Then the groups are inserted into the agenda buffer, and any remaining items are inserted at the end. Empty groups are not displayed.

The end result is your standard daily/weekly agenda, but arranged into groups defined by you. You might put items with certain tags in one group, habits in another group, items with certain todo keywords in another, and items with certain priorities in another. The possibilities are only limited by the grouping functions.

The primary use of this package is for the daily/weekly agenda, made by the org-agenda-list command, but it also works for other agenda views, like org-tags-view, org-todo-list, org-search-view, etc.

Here’s what a normal agenda looks like:

Here’s what the “super” agenda looks like:

There are also a few more screenshots.

Usage

After installing, run the command org-super-agenda-mode, then set the variable org-super-agenda-groups as desired. The variable should be a list of groups. Then run an agenda command, and the entries will be grouped!

Here’s the code for the example above. You can test it quickly by evaluating this form:

(let ((org-super-agenda-groups
       '(;; Each group has an implicit boolean OR operator between its selectors.
         (:name "Today"  ; Optionally specify section name
                :time-grid t  ; Items that appear on the time grid
                :todo "TODAY")  ; Items that have this TODO keyword
         (:name "Important"
                ;; Single arguments given alone
                :tag "bills"
                :priority "A")
         ;; Set order of multiple groups at once
         (:order-multi (2 (:name "Shopping in town"
                                 ;; Boolean AND group matches items that match all subgroups
                                 :and (:tag "shopping" :tag "@town"))
                          (:name "Food-related"
                                 ;; Multiple args given in list with implicit OR
                                 :tag ("food" "dinner"))
                          (:name "Personal"
                                 :habit t
                                 :tag "personal")
                          (:name "Space-related (non-moon-or-planet-related)"
                                 ;; Regexps match case-insensitively on the entire entry
                                 :and (:regexp ("space" "NASA")
                                               ;; Boolean NOT also has implicit OR between selectors
                                               :not (:regexp "moon" :tag "planet")))))
         ;; Groups supply their own section names when none are given
         (:todo "WAITING" :order 8)  ; Set order of this section
         (:todo ("SOMEDAY" "TO-READ" "CHECK" "TO-WATCH" "WATCHING")
                ;; Show this group at the end of the agenda (since it has the
                ;; highest number). If you specified this group last, items
                ;; with these todo keywords that e.g. have priority A would be
                ;; displayed in that group instead, because items are grouped
                ;; out in the order the groups are listed.
                :order 9)
         (:priority<= "B"
                      ;; Show this section after "Today" and "Important", because
                      ;; their order is unspecified, defaulting to 0. Sections
                      ;; are displayed lowest-number-first.
                      :order 1)
         ;; After the last group, the agenda will display items that didn't
         ;; match any of these groups, with the default order position of 99
         )))
  (org-agenda nil "a"))

The groups apply to all agenda commands (at least, every one that calls org-agenda-finalize-entries). You can set different groups for custom commands by setting org-super-agenda-groups in the custom command’s settings list (see the description for org-agenda-custom-commands). You can disable grouping by binding org-agenda-super-groups to nil around a call to an agenda command, or you can disable it globally by disabling the mode.

Examples

At first you might feel bewildered by all the options. Never fear, examples are here!

Group selectors

Each group selector takes an argument which can be a single atom or a list, e.g. :tag takes a string or list of strings. Some selectors are predicates, like :deadline or :habit; for consistency, they also take an argument, but it is ignored.

A group selector creates a section in the agenda containing the items it matches, and any items it doesn’t match are passed to the next group selector.

:discard is a special exception to this: it simply discards any items it matches, and passes through the rest to the next group selector.

Note that the :not group selector creates a group with items it does not match; it can be combined with :discard to discard items that don’t match, e.g. (:discard (:not (:priority "A"))) as the first selector would mean that only priority A items would appear in the agenda, while (:discard (:priority "C")) would mean that any priority C items would not appear in the agenda.

Keywords:

• :name Optionally, set group name header. May be a string; or the symbol none, in which case no header will be inserted. If :name is not set at all, the group will be named automatically.

Special selectors:

Every selector requires an argument, even if it’s just t, e.g. :anything, :auto-category, :auto-group, and :discard.

• :and Group ITEMS that match all selectors in GROUP.
• :anything Select every item, no matter what. This is probably most useful with :discard, because it doesn’t actually test anything, so it’s faster than, e.g. :regexp ".", which has to get the entry text for every item.
• :auto-category This automatically groups items by their category (usually the filename it’s in, without the .org suffix).
• :auto-group This selects items that have the agenda-group Org property set. By setting this property for a subtree, every item in it will be sorted into an agenda group by that name and placed into the agenda where the :auto-group selector is (example).
• :discard Discard items that don’t match selectors. Any groups processed after this one will not see discarded items. You might use this at the beginning or end of a list of groups, either to narrow down the list of items (used in combination with :not), or to exclude items you’re not interested in.
• :not Group ITEMS that match no selectors in GROUP.
• :order A number setting the order sections will be displayed in the agenda, lowest number first. Defaults to 0.
• :order-multi Set the order of multiple groups at once, like (:order-multi (2 (groupA) (groupB) ...)) to set the order of these groups to 2.

Normal selectors:

These selectors take one argument alone, or multiple arguments in a list.

• :children Select any item that has child entries. Argument may be t to match if it has any children, nil to match if it has no children, todo to match if it has children with any to-do keywords, or a string to match if it has children with certain to-do keywords. You might use this to select items that are project top-level headings. Be aware that this may be very slow in non-daily/weekly agenda views because of its recursive nature.
• :date Group items that have a date associated. Argument can be t to match items with any date, nil to match items without a date, or today to match items with today’s date. The ts-date text-property is matched against.
• :deadline Group items that have a deadline. Argument can be t (to match items with any deadline), nil (to match items that have no deadline), past (to match items with a deadline in the past), today (to match items whose deadline is today), or future (to match items with a deadline in the future). Argument may also be given like before DATE or after DATE where DATE is a date string that org-time-string-to-absolute can process.
• :effort< Group items that are less than (or equal to) the given effort. Argument is a time-duration string, like 5 or 0:05 for 5 minutes.
• :effort> Group items that are higher than (or equal to) the given effort. Argument is a time-duration string, like 5 or 0:05 for 5 minutes.
• :habit Group habit items. Habit items have a “STYLE: habit” Org property.
• :heading-regexp Group items whose headings match any of the given regular expressions.
• :log Group items from log mode. Note that these items may also be matched by the :time-grid selector, so if you want these displayed in their own group, you may need to select them in a group before a group containing the :time-grid selector.
• :priority Group items that match any of the given priorities. Argument may be a string or list of strings, which should be the priority letter, e.g. A.
• :priority> Group items that are higher than the given priority, e.g. C.
• :priority>= Group items that are higher than or equal to the given priority, e.g. B.
• :priority< Group items that are lower than the given priority, e.g. A.
• :priority<= Group items that are lower than or equal to the given priority, e.g. B.
• :regexp Group items that match any of the given regular expressions.
• :scheduled Group items that are scheduled. Argument can be t (to match items scheduled for any date), nil (to match items that are not schedule), past (to match items scheduled for the past), today (to match items scheduled for today), or future (to match items scheduled for the future). Argument may also be given like before DATE or after DATE where DATE is a date string that org-time-string-to-absolute can process.
• :tag Group items that match any of the given tags. Argument may be a string or list of strings.
• :time-grid Group items that appear on the time grid.
• :todo Group items that match any of the given TODO keywords. Argument may be a string or list of strings, or t to match any keyword, or nil to match only non-todo items.

Installation

Install org-super-agenda from MELPA. Then:

1. Add to your init file: (use-package org-super-agenda :config (org-super-agenda-mode)).
2. Set the org-super-agenda-groups variable. Use the example code above as a guideline.
3. Start the day with confidence, knowing that nothing important has been lost in the jumble of ahem overdue items.

Manual installation

If you want to install manually, you must also install these packages:

• Emacs >= 25.1
• dash >= 2.13
• ht >=2.2
• org-mode >= 9.0
• s >= 1.10

Development

Contributions and feedback are welcome.

If you find this useful, I’d appreciate if you would share a screenshot or two of your agenda views using it (minus any private data, of course). I’d like to get ideas for how to better organize my agenda. :)

Bugs

• The org-search-view agenda command does not seem to set the todo-state text property for items it finds, so the :todo selector doesn’t work with it. We should be able to work around this by getting the todo state for each item manually, but we have to make sure that we only do that when necessary, otherwise it might be slow. And I wouldn’t be surprised if there are other selectors that don’t work with this or other commands, but org-agenda-list should work fine, and org-tags-view and org-todo-list seem to work.

License

GPLv3+