The agenda

The agenda collects dated entries and TODO items from your agenda files into one list you can act on.

Opening the agenda

On the Mac the agenda is its own window. Open it with Window ▸ Agenda, or with the key for your preset:

With org-use-speed-commands on, v at the start of a heading line opens it too (see Keys).

The key opens the window directly. There is no org-agenda dispatcher; you choose what the window shows from the view menu at the left of its toolbar (see Views).

Opening a timestamp with org-open-at-point (C-c C-o in the Emacs preset) opens the agenda on that timestamp's day, or on every day of a date range.

On iOS the agenda is the first tab. See The agenda on iOS.

Agenda files

By default the agenda reads every .org file at the top level of each folder you have added (see Files and folders). Files whose names start with a dot are left out, as org-agenda-file-regexp leaves them out.

To include files in subfolders as well, turn on Settings ▸ Agenda ▸ Include files in subfolders, or set this in config.toml:

[orgstar]
agenda-include-subfolders = true

To read a list of files instead, as org-agenda-files does, set org-agenda-files in config.toml, entries separated by \n:

org-agenda-files = "~/notes/\n~/work/plan.org\n~/.agenda_files"

Each entry is one of:

• a folder: its .org files whose names don't start with a dot, in name order, without subfolders;
• an .org file;
• another file: a list of entries, one per line, as Emacs reads the file named when org-agenda-files is a string. Files named in it are agenda files whatever their extension.

Relative paths count from the first folder in the sidebar, standing in for org-directory. Entries that don't exist are left out. The agenda follows the order of the list. With a list, Include files in subfolders has no effect. The agenda refreshes on its own only for changes inside your folders; on iOS, files outside them can't be read.

When a file is open in the editor, the agenda reads the buffer, so unsaved edits show. Other files are read from disk and cached until their modification date or size changes. A file that uses #+SETUPFILE is read again on every refresh, because its setup file may have changed.

Within a file, the agenda skips:

• trees tagged ARCHIVE, and every entry in a file whose #+FILETAGS include ARCHIVE;
• commented trees (a heading whose title starts with COMMENT);
• everything below a skipped heading.

An entry's category is the nearest CATEGORY property on it or an ancestor, else the file's #+CATEGORY, else the file name without .org.

If no agenda file exists, the window says so.

The day, week and month view

The default view is org-agenda-list: a run of days, each under a header with its date, such as Monday 5 October (with the year when it isn't the current year). Today, tomorrow and yesterday are named before the date: Today · Thursday 8 October. Today's header is in the agenda-today color and days before today are grey. Each header stays at the top of the window while you scroll through its day.

Both mirror the Emacs variables of the same name. The span's default is Doom's (plain Emacs shows a week); the agenda starts today, as in plain Emacs. Doom starts it 3 days back, with "-3d". org-agenda-start-day takes only day offsets such as "-3d" or "+0d".

Day, week and month

The Day, Week and Month control in the toolbar, or v d, v w and v m, shows one day, one week or one calendar month, as org-agenda-day-view, org-agenda-week-view and org-agenda-month-view do. d and w also show a day and a week. The view is the one around the selected line's day, else around today when today is shown, else around the first day shown. Weeks start on org-agenda-start-on-weekday in config.toml: Monday ("1") by default, "0" for Sunday, or "nil" to start on the day the view starts from. As in Org, a configured span of 7 or 14 days starts on that weekday too.

To return to the configured span, choose Agenda from the view menu.

The window's title names the days shown: Thursday 8 October 2026 for a day, Week of 5 Oct 2026, October 2026, or the first and last day for the configured span, 5 Oct – 14 Oct 2026.

Moving through days

The agenda also refreshes on its own when files change and when you edit an open buffer. The now line (see below) moves each minute, and at midnight the agenda refreshes so that Today, the overdue entries and the statuses move to the new day.

What appears on each day

The entries follow org-agenda-get-day-entries with Org's default entry types. The left column of each row shows the time, or for an untimed entry a short status:

An entry with a time of day shows the time instead of the status: 08:00, or 13:50–14:30 with an end time.

Details:

• Deadline warnings start org-deadline-warning-days days ahead, 14 by default, set in config.toml. A -Nd cookie in the timestamp (<2026-10-20 Tue -3d>) changes the warning for that deadline; w, m and y units work too.
• A -Nd cookie on a SCHEDULED timestamp delays it: the entry first shows N days after the scheduled date.
• Repeaters on SCHEDULED and DEADLINE timestamps (+1w, ++1w, .+1d) make the entry show on the next occurrence on future days, as in Org.
• A done entry shows only on the day of its deadline or scheduled date, not as overdue. With org-agenda-skip-scheduled-if-done or org-agenda-skip-deadline-if-done set to true in config.toml, a done entry's scheduled date or deadline doesn't show on that day either. Both are false by default, as in Org.
• Inactive timestamps ([…]) never appear, except in log mode.
• Ranges in comment lines and inside source blocks are ignored, as in Org.

A time can come from the timestamp (<2026-10-05 Mon 14:00-15:30>) or from the heading text (Call Ada 9:30am), as org-agenda-search-headline-for-time allows. Times past 24:00, such as 25:30, show as the time on the next day, 01:30.

Today, overdue entries and empty days

Days without entries are left out. Today always shows, with Nothing scheduled when it has no entries. To show every day of the span, as Org does by default, turn on Settings ▸ Agenda ▸ Show days without entries (on iOS, Settings ▸ Agenda), or set this in config.toml:

org-agenda-show-all-dates = true

Today's past deadlines and entries scheduled on earlier days, habits excepted, go in a group headed Overdue with their count, above today's other entries. The oldest date comes first; entries with the same date keep Org's order. Click or tap the header to collapse or expand the group; it stays as you left it.

Days with a time grid show dotted lines at the grid's times among the timed entries, as org-agenda-time-grid does: by default at 8:00, 10:00 and every two hours to 20:00, on today and in one-day views, when the day has a timed entry. An entry at a grid line's time comes before the line. On today, a line marked with the current time sits among them: before the first entry that starts later, or after the last one when all have started. The grid's days and times are set in [org-agenda-time-grid] in config.toml, org-agenda-use-time-grid turns the grid off, and org-agenda-show-current-time-in-grid the now line (see Configuration). With the grid off there is no now line, as in Org.

Sorting

Lines are sorted by org-agenda-sorting-strategy, set per kind of view in the [org-agenda-sorting-strategy] table of config.toml (see Configuration) or for one view in views.toml. The defaults are time-up habit-down urgency-down category-keep for days, urgency-down category-keep for the TODO list and matches, and category-keep for text search. With those, timed entries come first, earliest first, timed habits among them; then untimed entries, habits last, by urgency, which combines priority with how overdue an entry is; ties keep file order. Calendar events go among them as described in Calendar events.

Each key compares two lines, and the next key is tried when they tie:

In the TODO list and matches, the date keys use the first one in the strategy: with scheduled-up every line sorts by its SCHEDULED date, as in Org. Org's user-defined-up and user-defined-down are not supported.

Log mode

Press l to turn log mode (org-agenda-log-mode) on or off; on iOS, use Log Mode in the span menu. Each day then also shows:

• Closed entries whose CLOSED: timestamp is on that day;
• Clocked entries for each CLOCK: line that starts on that day, with the clock's start and end times in the left column and the time clocked, such as 1:30, after the title;
• with state in org-agenda-log-mode-items, State: entries for each state change logged that day (a - State "DONE" from "TODO" [2026-10-05 Mon 16:20] line), with the new state in parentheses and the note's first line after the title.

A note under a clock line (a list item directly below it) is added to the title after a -. org-agenda-log-mode-items in config.toml picks the kinds, separated by spaces; the default is Org's, "closed clock".

Rows

Each row shows, from left to right:

• The time or status described above, with an icon below it on the Mac and before it on iOS: a calendar for scheduled entries, a flag for deadlines, arrows in a circle for habits, a clock or a calendar for timestamps, and a dot or a calendar for calendar events. An overdue entry shows a warning sign instead, and on the Mac a done entry shows a check mark.
• The category, with a colored dot, above the title. For a calendar event this is the calendar's name.
• The title: the heading without its TODO keyword, priority cookie, statistics cookies, timestamps and tags, with links shown as their descriptions. A done entry's title is struck through.
• The value of the first statistics cookie (1/3, 50%) and the tags, inherited tags first, as small capsules. iOS shows at most three tags.
• The habit's consistency graph, for habits.
• The TODO keyword as a colored badge, and the priority as a colored letter in a circle.

The status sets the color of the left column:

Ages and distances are written compactly: days up to 13 (3d), then whole weeks up to 59 days (2w), then months of 30 days up to a year (4mo), then years with any remaining months (1y, 1y 4mo). They round down.

The keyword's color comes from [theme.todo], else from its class: todo-next for keywords of work under way such as NEXT and STRT, todo-waiting for WAIT, HOLD and similar, todo-cancelled for done keywords such as KILL and CANCELLED, and otherwise todo or done. Priorities A, B and C use priority-a, priority-b and priority-c; others use priority. A category's dot takes its color from [theme.category], else a hue worked out from the category's name, the same on every device. See Configuration for the keyword lists and the theme keys.

With org-enforce-todo-dependencies or org-enforce-todo-checkbox-dependencies on, an entry that can't be marked done yet is dimmed in every view (org-agenda-dim-blocked-tasks t). Settings ▸ Agenda ▸ Blocked entries (on iOS, Settings ▸ Agenda) can hide such entries instead (invisible), though one held back only by its own checkboxes stays dimmed, or show them as usual (nil). Marking a blocked entry done from the agenda is refused with the same message as in the editor; see TODOs and tags.

Calendar events

The agenda can show events from the system Calendar app (EventKit) among your entries. orgstar changes your calendars only when you edit an event or add an entry, as below. It is off by default. To turn it on:

• On the Mac, turn on Settings ▸ Agenda ▸ Show events from Calendar, and check the calendars to show.
• On iOS, turn on Settings ▸ Calendar ▸ Show Calendar Events, and tap the calendars to show.
• Or set the keys in config.toml:

[orgstar]
calendar-events = true
calendar-event-calendars = "Work, Family"

calendar-event-calendars names calendars by title or identifier, separated by commas; "" (the default) shows every calendar, including calendars added later. While every calendar is checked in Settings, the key stays empty.

The first time events are turned on, orgstar asks for access to your calendars. The system asks for full access, because Calendar has no read-only level of access. If you declined, allow it in System Settings ▸ Privacy & Security ▸ Calendars on the Mac, or in the Settings app on iOS.

Events appear only in the day, week and month view:

• All-day events come first on their day, as calendars show them.
• Timed events go among the timed entries by start time, after entries with the same start and before untimed entries and habits.
• An event over several days shows its start time on its first day, Until 02:00 on its last day, and All day on the days between.
• The dot and the icon take the calendar's color, or agenda-event when the calendar has none.
• Filters don't hide events.

On the Mac, double-click an event, or select it and press RET, to open it in Calendar; its context menu has Show in Calendar. Entry commands such as t don't apply to events.

Editing events and adding entries

Edit Event…

in an event's context menu on the Mac, or by tapping the event on iOS (touch and hold for Edit Event… and Show in Calendar). The sheet changes the title, All day, the start and end, the location and the calendar. For a repeating event, the change applies to that occurrence only.

Add to Calendar…

in an entry's context menu on the Mac and iOS. The sheet starts with the entry's title and its time on the day it shows: an entry at 10:00-11:30 becomes an event from 10:00 to 11:30, one at 10:00 an hour-long event, and one without a time an all-day event. The calendar starts as Calendar's default calendar for new events; only calendars that can be changed are offered. The entry itself doesn't change.

Both use the access granted for showing events. Read-only calendars, such as subscriptions and holidays, can't be chosen.

Reminders from the Reminders app

The agenda can also show reminders from the Reminders app (EventKit), read-only. It is off by default. To turn it on:

• On the Mac, turn on Settings ▸ Agenda ▸ Show reminders from Reminders, and check the lists to show.
• On iOS, turn on Settings ▸ Reminders ▸ Show Reminders, and tap the lists to show.
• Or set the keys in config.toml:

[orgstar]
agenda-reminders = true
agenda-reminder-lists = "Errands, Work"

agenda-reminder-lists names lists by title or identifier, separated by commas; "" (the default) shows every list. The first time reminders are turned on, orgstar asks for full access to your reminders; if you declined, allow it in System Settings ▸ Privacy & Security ▸ Reminders on the Mac, or in the Settings app on iOS.

Only incomplete reminders with a due date show, in the day, week and month view:

• A reminder with a due time shows at that time among the timed entries, as a timed event does. One with only a due date shows Reminder with the all-day events.
• A reminder due before today shows in today's Overdue group as 2d late, among the overdue entries by date.
• The row's category is the list's name, and the dot takes the list's color.

Completing or editing a reminder is done in Reminders. On the Mac, double-click a reminder, or press RET, to open it in Reminders; its context menu has Show in Reminders. On iOS, tap it.

Done keywords the agenda doesn't know

A keyword that isn't in org-todo-keywords or the file's #+TODO lines is not a keyword to orgstar, as to Org: it is part of the title. A heading such as SKIPPED Call the bank with a SCHEDULED date last week is therefore an open entry, and shows as overdue. To make such a word a done state, add it after the |:

org-todo-keywords = "TODO(t) PROJ(p) LOOP(r) STRT(s) WAIT(w) HOLD(h) IDEA(i) | DONE(d) KILL(k) SKIPPED"

Done entries leave the Overdue group. With org-agenda-skip-scheduled-if-done and org-agenda-skip-deadline-if-done on, they leave their own day too.

Diary sexps

The agenda evaluates diary sexps as org-diary-sexp-entry does. They can appear as a line starting with %%( under a heading, as an active timestamp <%%(…)>, or as a SCHEDULED or DEADLINE value.

* Birthdays
%%(diary-anniversary 10 7 1990) Ada is %d years old
%%(org-anniversary 1985 3 14) Bob turns %d

* Teaching
** Algebra lecture
<%%(org-class 2026 9 7 2026 12 18 1 41)>

Lines before the first heading are ignored. A sexp that uses a function orgstar doesn't have, or signals an error, doesn't apply on any day, as Emacs reports a bad sexp and moves on.

The diary- functions read dates in calendar-date-style american (month, day, year); the org- functions use ISO order.

The holidays are those of Emacs's default calendar-holidays that follow fixed rules: holiday-general-holidays (New Year's Day, Martin Luther King Day, Groundhog Day, Valentine's Day, President's Day, St. Patrick's Day, April Fools' Day, Mother's Day, Memorial Day, Flag Day, Father's Day, Independence Day, Labor Day, Columbus Day, Halloween, Veteran's Day, Thanksgiving) and holiday-christian-holidays (Ash Wednesday, Good Friday, Easter Sunday, Christmas). The Hebrew, Islamic, Bahá'í, Chinese and solar holidays, and holidays you add to calendar-holidays in Emacs, are not included.

For your own expressions, the variables date (as (month day year)) and entry are bound, and these calendar functions are available: calendar-extract-month, calendar-extract-day, calendar-extract-year, calendar-absolute-from-gregorian, calendar-gregorian-from-absolute, calendar-day-of-week, calendar-leap-year-p, calendar-last-day-of-month, calendar-date-equal, calendar-day-number, calendar-nth-named-absday, calendar-nth-named-day, calendar-iso-from-absolute, calendar-check-holidays, diary-ordinal-suffix and diary-make-date. The evaluator also has the common special forms (if, when, cond, and, or, let, progn and others) and arithmetic. It is a small subset of Emacs Lisp, not Emacs.

A sexp line that returns a string shows that string; one that returns a list of strings shows one line per string; otherwise the line's text after the sexp shows.

Habits

An entry with the property STYLE: habit and a SCHEDULED timestamp with a repeater is a habit, as in org-habit:

* TODO Run
SCHEDULED: <2026-10-05 Mon .+2d/4d>
:PROPERTIES:
:STYLE:    habit
:END:
- State "DONE"       from "TODO"       [2026-10-03 Sat 07:10]
- State "DONE"       from "TODO"       [2026-10-01 Thu 07:05]

To make every entry of a file a habit, put #+PROPERTY: STYLE habit at the top of the file and set org-use-property-inheritance = "STYLE" in config.toml. As in Org, the #+PROPERTY line counts only when STYLE inherits; set the same variable in Emacs, (setq org-use-property-inheritance '("STYLE")), for Emacs to agree.

The repeater can be +, ++ or .+, with an optional /Nd maximum interval. Days the habit was done are read from - State "DONE" … [date] lines (for any done keyword) and CLOSING NOTE [date] lines in the entry.

A habit appears only on today's agenda and not once it is done for the day. To show habits on the later days they are scheduled for too, turn off Settings ▸ Agenda ▸ Habits only today, or set org-habit-show-habits-only-for-today = false in config.toml. Its row carries the consistency graph: one cell per day for the 21 days before today and the 7 after (org-habit-preceding-days and org-habit-following-days). On the Mac the graph is at the right of the row, with * on days the habit was done and ! on today; on iOS it is a strip under the title, with a dot on days it was done and today outlined. Cell colors follow org-habit's faces:

Future days use lighter shades. On the Mac, hover a cell to see its date. Habits sort after other entries.

The TODO list

The built-in view TODO List is org-todo-list: every heading with a TODO keyword that is not a done keyword, sorted by urgency (priority first). By default every open TODO appears, as in Org. org-agenda-todo-ignore-scheduled, org-agenda-todo-ignore-deadlines, org-agenda-todo-ignore-timestamp and org-agenda-todo-ignore-with-date in config.toml leave out entries for their timestamps, so that the TODO list shows only what isn't already on the calendar; see Configuration. As in Org, the searches look through the entry's text in order, so with both set, a SCHEDULED that doesn't leave the entry out hides a DEADLINE before it on the same line. With org-agenda-tags-todo-honor-ignore-options, TODO-only matches leave the same entries out.

A saved view can list specific keywords instead, done ones included, with keywords = "WAIT|HOLD" (see Views). This mirrors C-u M-x org-todo-list with a keyword argument.

The TODO list and the match views use the same rows as the day view (see Rows), without the left column.

Tag and property matches

Choose Match… from the view menu to list entries matching a match string, as org-tags-view (m) does, or TODO Match… to list only entries with an open TODO keyword (M). Type the match in the toolbar field and press Return.

The syntax is org-make-tags-matcher's:

+work-boss|LEVEL>2+TODO="WAIT"/!NEXT

Tags

work|home matches either side: the vertical bar separates alternatives, and within an alternative, terms are joined by +, - or &. Tags include inherited tags and #+FILETAGS. Tag names compare exactly; regular expressions in braces are Emacs regexps, matched without case.

Properties

A term can compare a property: NAME op value.

The value decides how the comparison works:

Follow the operator with * (Effort>*1) to require that the property exists; without it, a missing property compares as an empty string or 0.

Names are case-insensitive. Prefix a character in a name with \ to use it literally (MY\-PROP"x"=). Besides the entry's own property drawer, these special properties work:

Properties inherit in matches as org-use-property-inheritance says: by default they don't, so TEAM"ops"= matches only the entry with the property; with org-use-property-inheritance = "TEAM" it matches the entries under it too, and #+PROPERTY lines count. With a date value, <> and its synonyms match dates that are equal, as orgstar's comparison mirrors org-time<> in Org 9.8.7; use < and > for date ranges.

TODO keywords

After the last / (one not followed by a quote), the match restricts TODO keywords:

/TODO|NEXT matches either keyword, and /!NEXT|WAIT either one while open. /! has the same effect as choosing TODO Match….

Stuck projects

The built-in view Stuck Projects is org-agenda-list-stuck-projects (#): the projects that have no next action. [org-stuck-projects] in config.toml says what a project is and what makes one active, as org-stuck-projects does:

The project's own heading counts: a project whose heading has a todo keyword is not stuck. Keywords, tags and the regexp are case-sensitive. A project that isn't stuck can still contain stuck subprojects, which are listed. When todo, tags and regexp are all empty, every project is listed; Org signals an error instead. Lines sort as tag matches do.

Text search

Choose Search… from the view menu to list entries containing some text, as org-search-view (s) does, or TODO Search… to list only entries with an open TODO keyword (S, or C-u s). Type the search string in the toolbar field and press Return. An entry is its heading and the text up to the next heading; text before the first heading of a file is not searched. Entries show in file order, with the rows of the TODO list.

By default the string is a phrase: pay rent finds those words in that order, case-insensitively, and each space matches any run of spaces, tabs and line breaks, so a phrase can span lines. A string that starts with +, - or { is a list of snippets separated by spaces instead, all of which must hold:

Phrases and snippets match parts of words: +rent finds parent. These may come first in the string, in this order:

*!:+rent -paid lists open TODO headlines with the word rent and without paid.

Two settings in config.toml change the defaults: org-agenda-search-view-always-boolean reads every string as snippets, and org-agenda-search-view-force-full-words makes snippets match whole words (see Configuration).

The search covers the agenda files only, not org-agenda-text-search-extra-files or archive files. Entries in archived or commented trees are left out, as in the other views. To search every file in the folders, use Search Notes (⇧⌘F).

Views

The view menu lists the built-in views, Agenda, TODO List and Stuck Projects, then the views in views.toml, then Match…, TODO Match…, Search… and TODO Search…. Saved views mirror org-agenda-custom-commands, with fewer options.

views.toml lives in the configuration folder beside config.toml (~/.config/orgstar/ by default; see Configuration). Each view is a [[view]] table:

[[view]]
name = "Fortnight"
type = "agenda"
span = 14
start = 0

[[view]]
name = "Waiting"
type = "todo"
keywords = "WAIT|HOLD"

[[view]]
name = "Work"
type = "match"
match = "+work-boss"

[[view]]
name = "Next at work"
type = "todo-match"
match = "+work/NEXT"

[[view]]
name = "Invoices"
type = "search"
match = "+invoice -paid"

Note that start is a plain integer here, while org-agenda-start-day in config.toml is a string such as "-3d".

Skipping entries

skip-entry-if takes the arguments of org-agenda-skip-entry-if as Lisp writes them, the quotes optional:

[[view]]
name = "Unplanned"
type = "todo"
skip-entry-if = "'scheduled 'deadline"

An entry is left out when any condition holds: scheduled, notscheduled, deadline and notdeadline look at the planning line; timestamp and nottimestamp at active timestamps in the entry; regexp "RE" and notregexp "RE" at its text, with an Emacs regular expression; todo and nottodo at its keyword, given as a list ('("WAIT" "HOLD"), "*" for any) or a class (todo, done or any). skip-subtree-if takes the same conditions, looks at the whole subtree, and leaves out the subtree when one holds. As in Org, the day and TODO views match the regexps case-sensitively, and tag matches and search ignore case. Org's todo-unblocked and nottodo-unblocked, and skip functions of your own, are not supported.

Block agendas

A view with [[view.block]] tables after it shows several views one after the other, as an org-agenda-custom-commands entry with a list of blocks does. Each block takes the keys of a view except name; the view's sorting-strategy, prefix-format and skip settings, and for agenda blocks its span and start, apply to blocks that don't set their own:

[[view]]
name = "Daily"
span = 1

[[view.block]]
type = "agenda"
header = "Today"

[[view.block]]
type = "todo"
keywords = "NEXT"
skip-entry-if = "'scheduled 'deadline"

[[view.block]]
type = "stuck"

Each block has its title over it: its header, or one for its kind such as Day agenda or TODO items: NEXT. Agenda blocks start from their own start (or the setting), so the arrows that move through days don't apply to them.

The views load when the window opens and again on g or r. A problem in the file, such as a missing name or an unknown type, shows in the status line at the bottom of the window, and the remaining views still load.

Filters

Filters hide lines without changing the view, as org-agenda-filter does. Calendar events always stay. The active filter shows in the status line at the bottom of the window as Filter: ….

The Filter button in the toolbar asks for a combined filter, as / does; its menu has each of the filters below and Remove Filters.

The vertical bar key, |, removes every filter (org-agenda-filter-remove-all).

The combined filter / reads terms such as:

+work-phone<2:00/report/

• +word keeps and -word drops lines. A word without a sign keeps.
• A word is a tag if a line in the view has that tag, else a category if a line has that category; otherwise it is ignored and the status line says so. Quote a category that contains -: "my-cat".
• <0:30, >1:00 and =1:00 compare the entry's Effort property. Entries without an effort count as longer than any effort, as with org-agenda-sort-noeffort-is-high t. Durations can be H:MM, minutes, or units such as 1h 30min or 2d.
• /regexp/ keeps lines whose text matches; -/regexp/ drops them. Matching ignores case.
• Starting the input with + followed by another sign (++urgent) adds to the current filter instead of replacing it.

With two or more + categories, a line may have any of them. Tag terms all have to hold.

The / prompt starts with the whole current filter written in this form, every term with its sign: categories, then tags, efforts and regexps, with categories that contain - in quotes. Pressing Return on it unchanged keeps the same filter.

The \ prompt reads every word as a tag, whether or not a line has it; there, {regexp} matches any tag that matches the regexp. The = prompt takes one regexp, with a leading - to drop matches. The _ prompt takes one comparison such as <0:30.

Prefix format and colors

orgstar reads org-agenda-prefix-format from the [org-agenda-prefix-format] table in config.toml (see Configuration) or a view's prefix-format. Rows already show the category, the time and the scheduled or deadline leader in their own places, so %c, %t, %s and %i add nothing there. What the format adds besides them shows after the category: %e the effort, %b the outline path (Project->Phase->), %T the last tag, and any literal text. %l (the level as spaces) and %(…) Lisp forms show nothing. Widths, ? and punctuation work as in Org.

Times written in heading text depend on %t: when the agenda format contains it, as the default " %i %-12:c%?-12t% s" does, a time such as 9:30am in Call Ada 9:30am moves out of the title into the left column, as org-agenda-remove-times-when-in-prefix does. Without %t, the title keeps it.

The agenda's colors come from these theme keys (see Configuration):

[theme.todo] colors keywords by name and [theme.category] colors categories by name.

Acting on entries

Select a line with the mouse, or move the selection with n and p, C-n and C-p, or ↓ and ↑. These keys work in the agenda window in every keymap preset; they are fixed and are not read from keymap.toml.

Without a selected line, k captures onto today when today is shown, else onto the first day shown. The + at the right of each day's header captures onto that day; see Capture.

Right-click a line for Open, Cycle TODO State, Set Priority…, Set Tags…, Schedule…, Set Deadline…, Add to Calendar…, Clock In, Mark or Unmark, and Archive. A calendar event's menu has Show in Calendar and Edit Event…; a reminder's has Show in Reminders.

t follows org-todo: with fast-selection keys in your TODO keywords it asks for the state, otherwise it cycles (see TODOs and tags). Questions an action needs, such as a date for C-c C-s or a note on a state change, appear in the agenda window. Dates take the same input as in the editor (see Dates, scheduling and clocking). S-<right> and S-<left> work only on deadline, scheduled and timestamp lines; they change the timestamp the line comes from.

C-c C-w brings the main window forward and asks for the target there, where the target list is searchable.

I clocks in as Clock In does, so with no clock running it first asks about open clocks, in the main window's echo area. See Dates, scheduling and clocking.

Each action finds the entry again by its heading line before it changes anything, so an action on a line whose entry has since moved or changed reports that rather than editing the wrong text. Edits go through the open buffer when the file is open, and through the file otherwise.

Bulk actions

B offers $ archive, r refile, t set a TODO state (typed; empty for none), + add a tag, - remove a tag, s schedule and d set a deadline. Type the letter and press OK. Entries that changed since they were marked are skipped and counted in the status line. An action that needs a further answer per entry, such as a state-change note, is not run in bulk; the status line tells you to run it on the entry.

On iOS, tap Select in the bar at the bottom, or Select in an entry's menu, then tap entries to mark them. The bar then shows how many are selected, Actions and Done. Actions offers the same actions: TODO State…, Add Tag…, Remove Tag…, Schedule…, Deadline…, Refile… and Archive…, which asks first. After an action, or Done, the selection ends.

Reminders

orgstar can post a notification before each timed entry, as org-agenda-to-appt hands entries to appt. Reminders cover the next 7 days and include deadline, scheduled, plain timestamp and range lines that have a time of day and are not done. Overdue items and upcoming-deadline warnings don't get reminders.

Both are in Settings ▸ Agenda. An entry's APPT_WARNTIME property, in minutes, overrides the warning time for that entry. If the warning time has already passed but the entry hasn't started, the reminder fires at once.

The notification's title is the heading; its body is the time, Org's leader text (Scheduled:, Deadline:) if any, and the category, such as 14:00 · Scheduled: · work. Clicking it shows the entry in the main window.

On the Mac, reminders are updated two seconds after edits stop, when files change, and every hour. At most 64 are set, the earliest first. The agenda's status line says how far ahead they are set, or that notifications are off for orgstar in System Settings. Turning reminders off removes the pending ones.

The board

The board shows the entries of your agenda files as a table or as kanban columns. It has no Org equivalent; the table is close to Org's column view across files. Open it with Window ▸ Board (⇧⌘B). It reads the same files as the agenda, including the subfolder setting.

The toolbar has:

• a Table / Kanban switch;
• a match field, with the syntax of Tag and property matches. When empty, the board shows every entry with a TODO keyword;
• in table mode, a field of property names to show as extra columns, separated by commas (default EFFORT).

These three choices are remembered by the app; they are not in config.toml.

Table

Columns: TODO, priority, title, tags, scheduled, deadline, your property columns, and the file. Click a column header to sort (the property columns don't sort). The TODO column sorts by the keyword's order in your sequences. The context menu on a row offers Set TODO (a keyword or None), Set Property… (asked in the main window as NAME value) and Open. Double-click a row to open the entry.

Kanban

Each TODO keyword your files use gets a column, in sequence order, done keywords included. A card shows the priority and title, the category and tags, and the deadline (in red) or the scheduled date. Drag a card to another column to set that keyword; this is the same edit as changing the state in the editor, so logging and state-change notes apply (a note is asked for in the main window). Double-click a card to open its entry. With VoiceOver, each card has a Move to … action for each other column.

With a match that includes entries without a TODO keyword, those entries appear in the table but not on the kanban board, which has no column for them.

On iOS

Choose Board from the Views menu in the Agenda tab. The board opens over the agenda with a List / Kanban switch at the top, a match field under it (press Search to apply it), and Done to close it. The list shows the entries sorted by keyword, then title; tap one to open it. In Kanban, columns scroll sideways; touch and hold a card, then drag it to another column to set that keyword. A card's or row's menu has Move To (a keyword, or None), Set Property… (NAME value) and Open. The Kanban or List choice and the match are remembered, separately from the Mac's.

The board is not available on iOS.

Desktop widgets

On the Mac, orgstar's widgets go on the desktop and in Notification Center: right-click the desktop, choose Edit Widgets…, and pick orgstar in the gallery. They appear there once orgstar has run.

Click a row in Today, the Up Next widget or a habit to show that entry in orgstar; click elsewhere to open the agenda. The widgets read the next seven days of the agenda and the habits, which the app writes to ~/Library/Application Support/Orgstar/Widgets when files, edits or settings change and every hour while it runs; see iOS for what they show and leave out.

The agenda on iOS

The Agenda tab shows the same views from the same files, using the settings in the synced config.toml and the views in views.toml (see iOS). Differences from the Mac:

• The Views menu, at the top left, lists the built-in views, your saved views, Tags and Properties…, which asks for a match string, and Search…, which asks for a search string. There is no TODO-only match or search from the menu; use /! in the match, ! at the start of the search string, or a todo-match or todo-search view.
• A bar floats at the bottom of the screen with Earlier, Filter, Today, Go to Date, the span and Later. The span menu switches between Day, Week, Month and the configured span (10 Days by default); Day, Week and Month are around today when today is shown, else around the first day shown. Weeks start on org-agenda-start-on-weekday, as on the Mac. In the TODO list and match views the bar has Filter and Agenda, which returns to the day view. Messages show above the bar; tap one to dismiss it.
• The title names the days shown: Thu 8 Oct, Week of 5 Oct, October 2026, or 5 Oct – 14 Oct.
• A block view lists its blocks one after the other, each under its title; an agenda block's days follow its title.
• Day headers read Today · Thu 8 Oct, Tomorrow · Fri 9 Oct or Mon 12 Oct, with a + that captures onto that day. Days before today are grey.
• Pull down to refresh.
• The Filter button opens a sheet: type a filter as for /, or tap a tag or category to cycle between Keep, Leave out and no filter.
• Tap an entry to open it. Tap a calendar event to open Calendar on the event's day; iOS can't open Calendar at one event.
• Swipe left on an open TODO entry for Done, which sets the first done keyword of its sequence, and Next State, which moves to the next keyword; and on any entry with a heading, for Delete, which asks first, as Delete… in the menu does. The sequence is the one the file defines: the default keywords from config.toml, the file's own #+TODO lines, and those of its setup files, with unsaved edits in an open buffer included.
• Swipe right on a scheduled entry, a deadline, a habit or a TODO entry, when it isn't done, for Tomorrow, Next Week and Pick Date. Tomorrow is the day after today and Next Week is next Monday. On a deadline row these move the deadline; on other rows they set the scheduled date. A timed row keeps its times.
• Touch and hold an entry for TODO State…, Reschedule (Tomorrow, Next Week, Pick Date…), Schedule…, Deadline…, Tags…, Priority…, Clock In, Add to Calendar…, Refile…, Archive… and Delete…, which removes the heading and everything under it.
• Marking an entry done and rescheduling one give haptic feedback.
• Log Mode, in the span menu, turns log mode on and off. The widgets never show log mode's entries.
• There are no keyboard commands; bulk actions use Select instead of marks (see Bulk actions).
• Reminders are set while the app is open. iOS allows at most 64 pending notifications and the app can't add more while it isn't running, so the agenda's footer says how far ahead they go and asks you to open orgstar to set later ones.

The Today and Up Next widgets show the agenda on the Home Screen and the Lock Screen; see iPhone and iPad.