org-super-agenda
Stability: stable (org-extensions-stability)
Modelled on the Emacs package org-super-agenda: splits each day of the agenda, and each TODO, tags, search and org-ql list, into groups.
extensions = {
super_agenda = {
groups = {
{ name = "Today", time_grid = true, date = "today" },
{ name = "Important", priority = "A" },
{ name = "Due soon", deadline = "future", order = 2 },
{ name = "Work", tag = { "work", "office" }, order = 1 },
{ discard = { tag = "someday" } },
{ auto_category = true, order = 9 },
},
},
}
An item goes to the first group it matches. A group's selectors are ORed and take their items in turn, as in Emacs: the group lists what its first selector takes, then what the next takes (keep_order = true keeps the agenda's order instead). The selectors of an Emacs plist run in its order; those of a Lua table by name, automatic selectors last. Empty groups are not shown; items no group takes are shown under "Other items" (unmatched_name, order unmatched_order = 99). Groups are shown by order (default 0, lowest first; groups with the same non-zero order by name; an order that isn't a number counts as 0). A block (or custom command, or org-ql view) can set super_groups to use other groups, or false for none.
On a group header, <Tab> folds and unfolds the group (it stays folded when the agenda is redone; elsewhere <Tab> keeps its agenda meaning), and gj / gk move to the next / previous header. Set them with header_keys = { toggle = "<Tab>", next = "gj", prev = "gk" }, or false for none.
Keys may be written time_grid or, as in Emacs, ["time-grid"]; a group may also be an Emacs plist such as { ":name", "Today", ":time-grid", true }.
Selectors:
time_grid | items on the time grid (with a time) |
date true|false|"today" | items with a date (in the agenda) |
deadline, scheduled | true, false, "past", "today", "future", { "before"|"on"|"after", "2026-10-01" } |
todo | keywords, true (any) or false (none) |
tag, category | any of them (tags ignore case, as Emacs' cl-equalp, accented letters too) |
priority | letters; priority_gt priority_ge priority_lt priority_le (or ["priority>"] etc.) compare with one |
effort_lt, effort_gt | (["effort<"], ["effort>"]) at most / at least a duration |
habit, log | habits; log items (true, "closed", "clock", "state") |
regexp, heading_regexp, file_path | Emacs regexps (file_path = true: any file item) |
property | "NAME", { "NAME", "value" } or { "NAME", function(value) } |
children | true, false, "todo" or keywords |
pred | function(item) or a list of them |
anything | every item |
["and"], ["not"] | a table of selectors that all / none match |
discard | drop the items matching a table of selectors |
take | { N, selectors }: the first N (last when negative) matching items |
Auto groups make one group per value, named and sorted as in Emacs. In a group with other selectors, those take their items first (into a group named name), and the automatic selector groups the rest: auto_category, auto_tags, auto_todo, auto_priority, auto_property = "NAME", auto_group (the agenda-group property), auto_parent, auto_outline_path, auto_dir_name, auto_planning, auto_ts ("reverse" for newest first), auto_map = function(item) and ancestor_with_todo = "KW" (or { "KW", limit = N, nearest = true }).
Other keys of a group: name ("none" hides the header), order, face (a highlight group, or attributes such as { fg = "#e06c75", bold = true }, drawn over the agenda's highlights; with append = true under them), transformer (function(line, item) returning the new line text; the agenda's highlights move with the text it keeps) and order_multi ({ N, group, group, ... }).
Options: unmatched_name, unmatched_order, header_separator (default "\n", a blank line; one character is repeated across the window), header_prefix (" "), final_group_separator, date_format ("%e %B %Y"), group_property_name, properties_inherit, keep_order and header_keys. Headers use the OrgSuperAgendaHeader highlight group, the item count of a folded group OrgSuperAgendaFolded.
Differences from Emacs org-super-agenda: folding is built in (Emacs uses origami); an automatic selector can be combined with other selectors, which Emacs does not support; face is a highlight group or attribute table; transformer is a Lua function, and the agenda's highlights are kept only for text it keeps unchanged; :pred and :auto-map receive the agenda item (a Lua table), not the item's text.