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 with a header such as Monday 5 October 2026 W41 (the ISO week number appears on Mondays).

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". There are no day, week or month view keys (d, w, m in Emacs) and no org-agenda-start-on-weekday: the span is a number of days and always begins at the configured offset.

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 line 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), with * on days it was done and ! on today. Cell colors follow org-habit's faces:

Future days use lighter shades. 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.

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

The agenda has no org-search-view (s). To search the text of your files, use Search Notes (⇧⌘F).

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

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, stuck projects, and search views. 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. Time grid lines always stay. The active filter shows in the status line at the bottom of the window as Filter: ….

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.

Each line shows the category, the time, the leader (Deadline:, In 3 d.:, (2/5):), the heading with its TODO keyword colored, the habit graph if any, and the tags.

To change what comes before the heading, set org-agenda-prefix-format in config.toml:

[org-agenda-prefix-format]
agenda = " %i %-12:c%?-12t% s"
todo = " %i %-12:c"
tags = " %i %-12:c"

These are the defaults. agenda applies to the day view, todo to the TODO list, and tags to match views. When a format differs from its default, the agenda shows the prefix as Emacs prints it, in a monospaced font, instead of its own columns.

Each field takes Org's modifiers: %-12c pads to 12 columns on the right (%12c on the left); %-12.6c limits a category to 5 characters; %?t leaves the field out entirely when empty; a punctuation character after the width (%-12:c) is added after a non-empty value. When the format contains %t, times move out of the heading text into the prefix, as org-agenda-remove-times-when-in-prefix does. %(…) Lisp forms are accepted but always empty.

Colors come from the theme keys agenda-background, agenda-date, agenda-today, agenda-time, agenda-category, agenda-deadline, agenda-upcoming, agenda-scheduled and agenda-scheduled-past (see Configuration).

Select a line with the arrow keys or the mouse. These keys work in the agenda window in every keymap preset; they are fixed and are not read from keymap.toml.

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.

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, the leader 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 lists the built-in views, your saved views, and Tags and Properties…, which asks for a match string. There is no TODO-only match from the menu; use /! in the match or a todo-match view. Today, Earlier and Later are in the same menu.
• 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. Swipe left on an open TODO to mark it done with the first done keyword of its sequence, as the file defines its keywords: 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.
• Touch and hold an entry for TODO State…, Schedule…, Deadline…, Tags…, Priority…, Clock In, Refile… and Archive….
• There are no keyboard commands, time grid lines, habit graphs, log mode, bulk marks or custom prefix formats.
• 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.