docs/manual/guide/07-agenda.org

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.

Orgstar has no org-agenda-files list. 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

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 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 defaults are Doom's values, not plain Emacs's (a week starting today). org-agenda-start-day takes only day offsets such as "-3d" or "+0d".

org-agenda-show-all-dates = true

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, with the event's location.
• 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.

The agenda can show events from the system Calendar app (EventKit) among your entries. They are read-only: Orgstar never changes your calendars. 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.

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.

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. org-class skip lists take ISO week numbers only; holiday names and holidays need the Emacs calendar's holiday lists and make the sexp fail.

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

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]

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. 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 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). The time-based skipping options (org-agenda-todo-ignore-scheduled and its relatives) are not supported; every open TODO appears, as with Org's defaults.

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.

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

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

The view menu lists the built-in views, Agenda and TODO List, 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".

Not supported: block agendas (several views in one), per-view settings such as org-agenda-skip-function or a different prefix format, and stuck projects. 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 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.

The rows look the same whatever org-agenda-prefix-format says. Orgstar reads the [org-agenda-prefix-format] table in config.toml (see Configuration), but the only effect is on times written in heading text: when the agenda format contains %t, 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.

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…, Clock In, Mark or Unmark, and Archive. A calendar event's menu has Show in Calendar.

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.

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

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). Weeks start on Monday, 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.
• 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. 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, Refile… and Archive….
• 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 or bulk marks.
• 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.