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