org-super-agenda

Introduction

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.

Contents

• Screenshots
• Installation
• Usage
  • Examples
  • Group selectors
  • Tips
• FAQ
• Changelog

Screenshots

Here’s what a normal agenda looks like:

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

There are also a few more screenshots.

Installation

MELPA

Just install the org-super-agenda package!

Manual installation

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

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

Then put org-super-agenda.el in your load-path, and eval (require 'org-super-agenda).

Usage

1. Enable org-super-agenda-mode.
2. Set the variable org-super-agenda-groups as desired (see example below).

   Note: In order for groups to be automatically, persistently applied to all agenda buffers, the variable org-super-agenda-groups must be set in the global scope (e.g. with setq in your init file, or using the customization interface). Alternatively, it can be let-bound in lisp code that calls org-agenda commands, but in that case, the setting will not persist across agenda commands (so after refreshing an agenda buffer by pressing g, there will be no groups).

3. Run an Org agenda command.
4. Start the day with confidence, knowing that nothing important has been lost in the jumble of ahem overdue items.

Examples

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

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

(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-super-agenda-groups to nil around a call to an agenda command, or you can disable it globally by disabling the mode.

Group selectors

Each group selector creates a group in the agenda containing the items it matches and consumes those items; any items it doesn’t match are passed to the next group selector. The selector :discard is an exception: it consumes any items it matches without creating an agenda group and passes through the rest to the next selector.

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.

Note: The order of items may not be preserved after grouping due to the implementation’s using hash tables. Future versions may address this shortcoming.

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.

:face

A face to apply to items in the group. If face is a plist containing :append t, it will be appended. See function add-face-text-property.

:transformer

Used to transform item strings before display. Either a function called with one argument, the item string, or a sexp, in which case the item string is bound to it.

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-dir-name

This automatically groups items by the directory name of their source buffer.

: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).

:auto-map

This automatically groups items by the value returned when applying each item to the given function as a string from the agenda buffer (example). The function should return a string to be used as the grouping key and as the header for its group.

:auto-outline-path

This automatically groups items by their outline path hierarchy, like Plans/Take over the universe/Take over the moon.

:auto-parent

This automatically groups items by their parent heading. This is surprisingly handy, especially if you group tasks hierarchically by project and use agenda restrictions to limit the agenda to a subtree.

:auto-planning

This automatically groups items by their earliest of scheduled date or deadline, formatted according to variable org-super-agenda-date-format.

:auto-priority

This automatically groups items by their priority.

:auto-property

This automatically groups items by the value of the given property (example).

:auto-tags

This automatically groups items by all of their tags (i.e. items with exactly the same tags, in any order, will be grouped together).

:auto-todo

This automatically groups items by their to-do keyword.

:auto-ts

This automatically groups items by the date of their latest timestamp anywhere in the entry, formatted according to variable org-super-agenda-date-format. With argument reverse, groups are sorted newest-first.

:discard

Discard items that 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.

• 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. For example, (: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.

: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.

:take

Take the first N items in GROUP. If N is negative, take the last N items. For example, (:take (-3 group)) will take the last 3 items from the group. The remainder of items are discarded. Note: The order of entries from GROUP is not guaranteed to be preserved, so :take may not always show expected entries.

Normal selectors

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

:ancestor-with-todo

Group items whose ancestor (up to :limit hops, or with :nearestp, their nearest) has the given to-do keyword. (For example, (:ancestor-with-todo ("PROJECT" :nearestp t)) to group by the nearest ancestor project heading.)

:category

Group items that match any of the given categories. Argument may be a string or list of strings.

: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.

:file-path

Group items whose buffers’ filename paths match any of the given regular expressions.

:habit

Group habit items (items which have a STYLE: habit Org property).

:heading-regexp

Group items whose headings match any of the given regular expressions.

:log

Group Agenda Log Mode items. Argument may be close or closed to select items closed today; clock or clocked to select items clocked today; changed or state to select items whose to-do state was changed today; t to select any logged item, or nil to select any non-logged item. (See also variable org-agenda-log-mode-items.) 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.

:pred

Group items if any of the given predicate functions return non-nil when called with each item as a string from the agenda buffer (example).

: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.

:property

Group items with a property, optionally matching a value. Argument may be a property name string, or a list of property name string and either value string or predicate with which to test the value.

: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.

Tips

• An info page is included, with the contents of this readme file.
• Group headers use the keymap org-super-agenda-header-map, allowing you to bind keys in that map which will take effect when point is on a header.
  • For example, origami works with org-super-agenda buffers without any extra configuration. Just activate origami-mode in the agenda buffer and use the command origami-toggle-node to fold groups. You can bind, e.g. TAB to that command in the header map, and then you can easily collapse groups as if they were an outline. You might even fold some automatically (example).

FAQ

Why are some items not displayed even though I used group selectors for them?

This is a common misunderstanding of how this package works. As written in the introduction, it does not collect items. It only groups items that are collected by Org Agenda or org-ql. So if your Agenda command or org-ql query does not collect certain items, they will not be displayed, regardless of what org-super-agenda groups you configure.

org-ql provides an easier way to write queries to generate agenda-like views that can be grouped with org-super-agenda.

Why did a group disappear when I moved it to the end of the list?

As explained in the usage instructions and shown in the example, items are collected into groups in the order the groups are listed, and empty groups are not shown. To display a group out of the order in which groups are listed, use :order.

Changelog

1.4-pre

Additions

• Selector :ancestor-with-todo, which groups items by their ancestor having a certain to-do keyword (up to a :limit number of hops, or with :nearestp, the nearest one). (Useful, for example, to group items by their parent or ancestor project.)
• Option org-super-agenda-show-message allows disabling of the message shown when the mode is enabled. (Thanks to Liam Hupfer.)

Changes

• Selector :auto-outline-path puts top-level headings in a group named “Top-level headings”. (#258. Thanks to Gulshan Singh for suggesting.)

Fixes

• Selector :time-grid incorrectly recognized some items. (#264. Thanks to Florian Lindner for reporting, and to Ihor Radchenko for suggesting.)

1.3

Additions

• Selector :property, which groups items with a property, optionally also matching a value or predicate. (Thanks to Per Weijnitz.)
• Special selector :take, which limits the number of items displayed in a group. (Thanks to Pete Kazmier.)
• Option org-super-agenda-hide-empty-groups, which hides empty groups. (Thanks to Christian Schwarzgruber.)
• Option org-super-agenda-keep-order, which re-sorts items after grouping to preserve their original sort order. (Thanks to Alexander-Miller.)
• Selector :auto-ts may be given the argument reverse to sort the groups newest-first.
• Option org-super-agenda-final-group-separator, which is a separator inserted after the final agenda group. (Thanks to Tyler Funnell.)

Fixes

• Widen buffers when collecting parent headers. (#231. Thanks to Abdul-Lateef Haji-Ali for reporting.)
• Showing names of empty sections. (#236. Thanks to Patrick Duncan and Christian Schwarzgruber.)

1.2

Added

• Selector :auto-planning, which groups items by their earliest of scheduled date or deadline, formatted according to variable org-super-agenda-date-format.
• Selector :auto-ts, which groups items by the date of their latest timestamp anywhere in the entry, formatted according to variable org-super-agenda-date-format.
• Selector :auto-tags, which groups items by all of their tags.
• Option org-super-agenda-date-format, used to format date headers in the :auto-date selector.
• To-do keyword faces are applied to keywords in group headers.
• Option org-super-agenda-header-separator may also be a character, which is automatically repeated to the window width. (Thanks to YUE Daian.)
• Option org-super-agenda-header-properties. It sets org-agenda-structural-header by default, which enables navigating to headers with the default M-{ / M-} bindings in agenda buffers. (Thanks to Abdul-Lateef Haji-Ali.)
• Option org-super-agenda-header-prefix, a string prepended to group headers. (#108. Thanks to Christian Schwarzgruber.)

Changed

• Group headers face is now appended to face list instead of overriding it.
• Minimum Emacs version requirement is now 26.1 (required by ts library).

Fixed

• :children todo group selection (#75). (Thanks to Ben Leggett and Elric Milon.)
• :children group headings.
• Don’t show blank lines for disabled headers (i.e. with :name none and org-super-agenda-header-separator set to an empty string). (Fixes #105. Thanks to Florian Schrödl.)

Updated

• Tests updated for Org 9.2.4.

Internal

• org-habit is now loaded when org-super-agenda is loaded. This avoids issues, real and potential, and should not cause any problems.
• Variable org-super-agenda-allow-unsafe-groups may be used to disable groups which call arbitrary functions (e.g. when called from other packages that may read code from untrusted origins).

1.1.1

Fixed

• Selector :auto-dir-name did not handle items without markers

1.1

Additions

• Keyword :face, used to apply faces to items in groups.
• Keyword :transformer, used to transform items in groups.
• Option org-super-agenda-header-separator, which can, e.g. be set to an empty string for a more compact view. (Thanks to Sébastien Delafond.)
• Face org-super-agenda-header, which can be used to customize group headers. (Thanks to Christian Schwarzgruber.)
• Selector :auto-map, which groups items by the value returned when applying items to a function.
• Selector :file-path, which groups items by regular expressions matched against their buffers’ filename paths.
• Selector :pred, which matches if any of the given predicate functions return non-nil when called with the item string from the agenda buffer.
• Selector :auto-dir-name, which groups items by the directory name of their source buffer.
• Selector :auto-parent, which groups items by their parent heading.
• Selector :auto-todo, which groups items by their to-do keyword.
• Selector :auto-priority, which groups items by their priority.
• Option org-super-agenda-unmatched-name, used to change the name of the unmatched group. (Thanks to Marcin Swieczkowski.)

Internal

• Refactor auto-groups with macro.

1.0.3

Fixed

• Require seq library. (Fixes #54. Thanks to Rick Hanson.)

1.0.2

Fixed

• Byte-compiler warnings.

1.0.1

Fixes

• Initialize org-super-agenda-header-map to a copy of org-agenda-mode-map. (Fixes #50. Thanks to Yiufung Cheong.)

1.0.0

First tagged version.

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.

Tests

It’s easy to run the tests:

1. Install Cask.
2. From the repo root directory, run cask install, which installs Emacs and package dependencies into the .cask directory.
3. Run make test.

Credits

• Thanks to Balaji Sivaraman for contributing the :category selector.
• Thanks to Michael Welle for contributing the customizable auto-group Org property name.

License

GPLv3+