docs/manual/guide/07-agenda.org
546 lines · 44540 bytes
1#+TITLE: The agenda
2#+DESCRIPTION: The agenda window, its rows, calendar events, the TODO list, tag and property matches, saved views, filters, reminders and the board.
3#+LEDE: The agenda collects dated entries and TODO items from your agenda files into one list you can act on.
4
5* Opening the agenda
6
7On the Mac the agenda is its own window. Open it with Window ▸ Agenda, or with the key for your preset:
8
9| Preset | Key |
10|--------+--------------------------------------|
11| Mac | =⇧⌘A= |
12| Emacs | =C-c a= or =⇧⌘A= |
13| Doom | =SPC o a= (normal state), =C-c a= or =⇧⌘A= |
14
15With =org-use-speed-commands= on, =v= at the start of a heading line opens it too (see [[file:03-keys.org][Keys]]).
16
17The 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][Views]]).
18
19Opening 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.
20
21On iOS the agenda is the first tab. See [[*The agenda on iOS][The agenda on iOS]].
22
23* Agenda files
24
25Orgstar has no =org-agenda-files= list. The agenda reads every =.org= file at the top level of each folder you have added (see [[file:01-files-and-folders.org][Files and folders]]). Files whose names start with a dot are left out, as =org-agenda-file-regexp= leaves them out.
26
27To include files in subfolders as well, turn on Settings ▸ Agenda ▸ Include files in subfolders, or set this in =config.toml=:
28
29#+BEGIN_SRC toml
30[orgstar]
31agenda-include-subfolders = true
32#+END_SRC
33
34When 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.
35
36Within a file, the agenda skips:
37
38- trees tagged =ARCHIVE=, and every entry in a file whose =#+FILETAGS= include =ARCHIVE=;
39- commented trees (a heading whose title starts with =COMMENT=);
40- everything below a skipped heading.
41
42An entry's category is the nearest =CATEGORY= property on it or an ancestor, else the file's =#+CATEGORY=, else the file name without =.org=.
43
44If no agenda file exists, the window says so.
45
46* The day, week and month view
47
48The 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.
49
50| Setting | Default | =config.toml= | Range in Settings |
51|------------------------------+---------+-----------------------------------+-------------------|
52| Days shown | 10 | =org-agenda-span = 10= | 1 to 366 |
53| First day, relative to today | 3 days before | =org-agenda-start-day = "-3d"= | 0 to 14 days before |
54
55Both 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"=.
56
57** Day, week and month
58
59The 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 Monday; there is no =org-agenda-start-on-weekday= setting.
60
61To return to the configured span, choose Agenda from the view menu.
62
63The 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=.
64
65** Moving through days
66
67| Key | Toolbar | Does | Org command |
68|----------+----------------------+-------------------------------------------------------------------------------+-------------------------|
69| =f= | Later (›) | Moves forward by the days shown; in the month view, to the next month | =org-agenda-later= |
70| =b= | Earlier (‹) | Moves back by the days shown; in the month view, to the month before | =org-agenda-earlier= |
71| =.= | Today | Returns to the days around today, keeping a day, week or month view | =org-agenda-goto-today= |
72| =j= | Go to Date (calendar) | Picks a date in a calendar and shows the days from it, or its day, week or month | =org-agenda-goto-date= |
73| =g=, =r= | | Refreshes, and reloads =views.toml= | =org-agenda-redo= |
74
75The 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.
76
77** What appears on each day
78
79The 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:
80
81| Entry | Where it appears | Left column |
82|-----------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------|
83| =DEADLINE= on that day | On its day | =Due today= on today, =Due= on other days |
84| =DEADLINE= in the future | On today, from the warning period before it | =Due in 3d= |
85| =DEADLINE= in the past, not done | On today, in the Overdue group | =2d late= |
86| =SCHEDULED= on that day | On its day | =Scheduled= |
87| =SCHEDULED= in the past, not done | On today, in the Overdue group | =3d ago= |
88| Active timestamp =<2026-10-05 Mon>= | On its day; also in property drawers | =All day= |
89| Repeating timestamp =<… +1w>= | On each occurrence within the span | =All day= |
90| Date range =<…>--<…>= | On every day of the range | =Day 2/5= (day 2 of 5) |
91| Diary sexp =%%(…)= line or =<%%(…)>= | On each day the sexp applies; see [[*Diary sexps][Diary sexps]] | =All day= |
92| Habit (=STYLE: habit=) | On today only, while not done; see [[*Habits][Habits]] | =Habit=, with a consistency graph |
93
94An entry with a time of day shows the time instead of the status: =08:00=, or =13:50–14:30= with an end time.
95
96Details:
97
98- Deadline warnings use =org-deadline-warning-days=, fixed at 14 days. A =-Nd= cookie in the timestamp (=<2026-10-20 Tue -3d>=) changes the warning for that deadline; =w=, =m= and =y= units work too.
99- A =-Nd= cookie on a =SCHEDULED= timestamp delays it: the entry first shows N days after the scheduled date.
100- Repeaters on =SCHEDULED= and =DEADLINE= timestamps (=+1w=, =++1w=, =.+1d=) make the entry show on the next occurrence on future days, as in Org.
101- 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.
102- Inactive timestamps (=[…]=) never appear, except in log mode.
103- Ranges in comment lines and inside source blocks are ignored, as in Org.
104
105A 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=.
106
107** Today, overdue entries and empty days
108
109Days 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=:
110
111#+BEGIN_SRC toml
112org-agenda-show-all-dates = true
113#+END_SRC
114
115Today'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.
116
117On today, a line marked with the current time sits between the timed entries: before the first entry that starts later, or after the last one when all have started. It shows only when today has timed entries, as Org's =now= line does. Org's time grid (the lines at 8:00, 10:00 and so on) isn't shown.
118
119** Sorting
120
121Days are sorted as =org-agenda-sorting-strategy= sorts them by default for the agenda: =(habit-down time-up urgency-down category-keep)=. Habits go last; timed entries come first, earliest first; the rest 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][Calendar events]]. The TODO list and match views sort by urgency, then file order. The sorting is not configurable.
122
123** Log mode
124
125Press =l= to turn log mode (=org-agenda-log-mode=) on or off. Each day then also shows:
126
127- =Closed= entries whose =CLOSED:= timestamp is on that day;
128- =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.
129
130A note under a clock line (a list item directly below it) is added to the title after a =-=. These are the default =org-agenda-log-mode-items=, =(closed clock)=; state changes are not shown and there is no setting for that.
131
132* Rows
133
134Each row shows, from left to right:
135
136- 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.
137- The category, with a colored dot, above the title. For a calendar event this is the calendar's name, with the event's location.
138- 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.
139- 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.
140- The habit's consistency graph, for habits.
141- The TODO keyword as a colored badge, and the priority as a colored letter in a circle.
142
143The status sets the color of the left column:
144
145| Status | When | Theme key |
146|----------+-------------------------------------------------------------------------+-------------------|
147| Overdue | Not done, with a deadline or scheduled date before today | =agenda-overdue= |
148| Due soon | Not done, a deadline listed on today: due today or within its warning | =agenda-due-soon= |
149| Done | A done keyword | =done= |
150| Normal | Everything else | =agenda-time= |
151
152Ages 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.
153
154The 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 [[file:13-configuration.org][Configuration]] for the keyword lists and the theme keys.
155
156* Calendar events
157
158The 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:
159
160- On the Mac, turn on Settings ▸ Agenda ▸ Show events from Calendar, and check the calendars to show.
161- On iOS, turn on Settings ▸ Calendar ▸ Show Calendar Events, and tap the calendars to show.
162- Or set the keys in =config.toml=:
163
164#+BEGIN_SRC toml
165[orgstar]
166calendar-events = true
167calendar-event-calendars = "Work, Family"
168#+END_SRC
169
170=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.
171
172The 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.
173
174Events appear only in the day, week and month view:
175
176- All-day events come first on their day, as calendars show them.
177- Timed events go among the timed entries by start time, after entries with the same start and before untimed entries and habits.
178- 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.
179- The dot and the icon take the calendar's color, or =agenda-event= when the calendar has none.
180- Filters don't hide events.
181
182On 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.
183
184* Done keywords the agenda doesn't know
185
186A 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 ~|~:
187
188#+BEGIN_SRC toml
189org-todo-keywords = "TODO(t) PROJ(p) LOOP(r) STRT(s) WAIT(w) HOLD(h) IDEA(i) | DONE(d) KILL(k) SKIPPED"
190#+END_SRC
191
192Done 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.
193
194* Diary sexps
195
196The 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.
197
198#+BEGIN_SRC org
199,* Birthdays
200%%(diary-anniversary 10 7 1990) Ada is %d years old
201%%(org-anniversary 1985 3 14) Bob turns %d
202
203,* Teaching
204,** Algebra lecture
205<%%(org-class 2026 9 7 2026 12 18 1 41)>
206#+END_SRC
207
208Lines 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.
209
210| Function | Applies | Date order |
211|--------------------------------------------+--------------------------------------------------------------------+-------------------|
212| =diary-date= /month day year/ | On matching dates; =t= or a list matches any or several | month day year |
213| =diary-block= /m1 d1 y1 m2 d2 y2/ | Every day from the first date to the second | month day year |
214| =diary-float= /month dayname n/ [/day/] | The nth /dayname/ (0 is Sunday) of the month; negative n counts from the end | month |
215| =diary-anniversary= /month day/ [/year/] | Each year on the date; =%d= is the count, =%s= its ordinal suffix | month day year |
216| =diary-cyclic= /n month day year/ | Every n days from the date | month day year |
217| =diary-remind= /sexp days/ | On the days before another sexp applies: =Reminder: Only 3 days until …= | n/a |
218| =org-anniversary= /year month day/ | As =diary-anniversary= | year month day |
219| =org-cyclic= /n year month day/ | As =diary-cyclic= | year month day |
220| =org-block= /y1 m1 d1 y2 m2 d2/ | As =diary-block= | year month day |
221| =org-date= /year month day/ | As =diary-date= | year month day |
222| =org-class= /y1 m1 d1 y2 m2 d2 dayname/ [/skip-weeks…/] | On /dayname/ between the dates, except the ISO weeks listed | year month day |
223
224The =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.
225
226For 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.
227
228A 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.
229
230* Habits
231
232An entry with the property =STYLE: habit= and a =SCHEDULED= timestamp with a repeater is a habit, as in =org-habit=:
233
234#+BEGIN_SRC org
235,* TODO Run
236SCHEDULED: <2026-10-05 Mon .+2d/4d>
237:PROPERTIES:
238:STYLE: habit
239:END:
240- State "DONE" from "TODO" [2026-10-03 Sat 07:10]
241- State "DONE" from "TODO" [2026-10-01 Thu 07:05]
242#+END_SRC
243
244The 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.
245
246A 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:
247
248| Color | Meaning | Theme key |
249|--------+--------------------------------------------+-----------------|
250| Blue | Not yet due | =habit-clear= |
251| Green | Due, within the allowed interval | =habit-ready= |
252| Yellow | Last day of the interval | =habit-alert= |
253| Red | Overdue | =habit-overdue= |
254
255Future days use lighter shades. On the Mac, hover a cell to see its date. Habits sort after other entries.
256
257* The TODO list
258
259The 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.
260
261A saved view can list specific keywords instead, done ones included, with =keywords = "WAIT|HOLD"= (see [[*Views][Views]]). This mirrors =C-u M-x org-todo-list= with a keyword argument.
262
263The TODO list and the match views use the same rows as the day view (see [[*Rows][Rows]]), without the left column.
264
265* Tag and property matches
266
267Choose 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.
268
269The syntax is =org-make-tags-matcher='s:
270
271#+BEGIN_SRC text
272+work-boss|LEVEL>2+TODO="WAIT"/!NEXT
273#+END_SRC
274
275** Tags
276
277| Form | Matches |
278|----------------+-----------------------------------------------------------|
279| =work=, =+work= | Entries with the tag |
280| =-boss= | Entries without the tag |
281| =+work-boss= | Both conditions (and) |
282| =a&b= | =&= between terms is the same as =+= |
283| ={^proj}= | Any tag matching the regular expression |
284
285=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.
286
287** Properties
288
289A term can compare a property: =NAME op value=.
290
291| Operator | Meaning |
292|-----------------------+-----------------------|
293| ===, ==== | Equal |
294| =<>=, =!==, =/== | Not equal |
295| =<=, =<== | Less, less or equal |
296| =>=, =>== | Greater, greater or equal |
297
298The value decides how the comparison works:
299
300| Value | Compared as |
301|--------------------+-----------------------------------------------------------------------------|
302| =3=, =-1.5= | Numbers; a missing or non-numeric property is 0 |
303| ="WAIT"= | Strings |
304| ={regexp}= | Regular expression match; with =<>=, =!== or =/== it must not match |
305| ="<2026-10-01>"= | Dates. Also ="<now>"=, ="<today>"=, ="<tomorrow>"=, ="<yesterday>"=, and offsets such as ="<-1w>"= or ="<+3d>"= (units =h= =d= =w= =m= =y=). Brackets may be =[…]=. |
306
307Follow the operator with =*= (=Effort>*1=) to require that the property exists; without it, a missing property compares as an empty string or 0.
308
309Names 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:
310
311| Name | Value |
312|----------------+----------------------------------------------------------|
313| =LEVEL= | The heading's level |
314| =TODO= | The TODO keyword |
315| =ITEM= | The heading title |
316| =PRIORITY= | The priority letter, or the default priority |
317| =CATEGORY= | The entry's category |
318| =FILE= | The file's path |
319| =TAGS= | The heading's own tags, as =:a:b:= |
320| =ALLTAGS= | All tags including inherited ones |
321| =SCHEDULED=, =DEADLINE=, =CLOSED= | The planning timestamp |
322| =TIMESTAMP=, =TIMESTAMP_IA= | The entry's first active or inactive timestamp |
323
324Properties are not inherited in matches (=org-use-property-inheritance= is nil). 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.
325
326** TODO keywords
327
328After the last =/= (one not followed by a quote), the match restricts TODO keywords:
329
330| Form | Matches |
331|--------------------+----------------------------------------------------------|
332| =/NEXT= | Entries whose keyword is =NEXT= |
333| =/-WAIT= | Any keyword but =WAIT=, and entries with none |
334| =/{^W}= | Keywords matching the regexp |
335| =/!= | Only entries with an open (not done) TODO keyword |
336| =/!-WAIT-HOLD= | Open TODO entries except those two |
337
338=/TODO|NEXT= matches either keyword, and =/!NEXT|WAIT= either one while open. =/!= has the same effect as choosing TODO Match….
339
340* Text search
341
342The agenda has no =org-search-view= (=s=). To search the text of your files, use Search Notes (=⇧⌘F=).
343
344* Views
345
346The 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.
347
348=views.toml= lives in the configuration folder beside =config.toml= (=~/.config/orgstar/= by default; see [[file:13-configuration.org][Configuration]]). Each view is a =[[view]]= table:
349
350#+BEGIN_SRC toml
351[[view]]
352name = "Fortnight"
353type = "agenda"
354span = 14
355start = 0
356
357[[view]]
358name = "Waiting"
359type = "todo"
360keywords = "WAIT|HOLD"
361
362[[view]]
363name = "Work"
364type = "match"
365match = "+work-boss"
366
367[[view]]
368name = "Next at work"
369type = "todo-match"
370match = "+work/NEXT"
371#+END_SRC
372
373| Key | Applies to | Meaning |
374|------------+--------------------+----------------------------------------------------------------------------|
375| =name= | all, required | The name in the view menu |
376| =type= | all | =agenda= (the default), =todo=, =match= or =todo-match= |
377| =span= | =agenda= | Days shown; the setting when omitted |
378| =start= | =agenda= | First day as an integer number of days from today (=-3=, =0=); the setting when omitted |
379| =keywords= | =todo= | Keywords separated by the vertical bar; all open TODOs when omitted |
380| =match= | =match=, =todo-match=, required | A match string as in [[*Tag and property matches][Tag and property matches]]; =todo-match= keeps only open TODO entries |
381
382Note that =start= is a plain integer here, while =org-agenda-start-day= in =config.toml= is a string such as ="-3d"=.
383
384Not 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.
385
386* Filters
387
388Filters 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: …=.
389
390The Filter button in the toolbar asks for a combined filter, as =/= does; its menu has each of the filters below and Remove Filters.
391
392| Key | Does | Org command |
393|------+---------------------------------------------------------------+-----------------------------------|
394| =/= | Asks for a combined filter, starting from the current one | =org-agenda-filter= |
395| =\= | Asks for a tag filter | =org-agenda-filter-by-tag= |
396| =<= | Keeps only the selected line's category; again removes it | =org-agenda-filter-by-category= |
397| === | Asks for a regexp filter | =org-agenda-filter-by-regexp= |
398| =_= | Asks for an effort filter | =org-agenda-filter-by-effort= |
399
400The vertical bar key, =|=, removes every filter (=org-agenda-filter-remove-all=).
401
402The combined filter =/= reads terms such as:
403
404#+BEGIN_SRC text
405+work-phone<2:00/report/
406#+END_SRC
407
408- =+word= keeps and =-word= drops lines. A word without a sign keeps.
409- 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"=.
410- =<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=.
411- =/regexp/= keeps lines whose text matches; =-/regexp/= drops them. Matching ignores case.
412- Starting the input with =+= followed by another sign (=++urgent=) adds to the current filter instead of replacing it.
413
414With two or more =+= categories, a line may have any of them. Tag terms all have to hold.
415
416The =/= 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.
417
418The =\= 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=.
419
420* Prefix format and colors
421
422The rows look the same whatever =org-agenda-prefix-format= says. Orgstar reads the =[org-agenda-prefix-format]= table in =config.toml= (see [[file:13-configuration.org][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.
423
424The agenda's colors come from these theme keys (see [[file:13-configuration.org][Configuration]]):
425
426| Key | Colors |
427|---------------------+---------------------------------------------------------------------------|
428| =agenda-background= | the Mac window's background, and the iOS widgets' background |
429| =agenda-date= | headers of days after today (Mac) |
430| =agenda-today= | today's header, the now line, and on iOS the widgets' date |
431| =agenda-time= | the left column of rows with the normal status |
432| =agenda-overdue= | the left column of overdue rows, and the Overdue group's header |
433| =agenda-due-soon= | the left column of deadlines due today or coming up |
434| =agenda-event= | calendar events whose calendar has no color |
435| =agenda-category= | category names (Mac) |
436| =todo=, =todo-next=, =todo-waiting=, =done=, =todo-cancelled= | TODO keyword badges, by class |
437| =priority-a=, =priority-b=, =priority-c=, =priority= | priority letters |
438| =tags= | tag capsules (Mac) |
439
440=[theme.todo]= colors keywords by name and =[theme.category]= colors categories by name. =agenda-deadline=, =agenda-upcoming=, =agenda-scheduled= and =agenda-scheduled-past= are accepted in a theme but not used.
441
442* Acting on entries
443
444Select 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=.
445
446| Key | Does | Org command |
447|-------------------------+--------------------------------------------------------------+------------------------------|
448| =n=, =p= | Moves to the next or previous line | =org-agenda-next-line=/=-previous-line= |
449| =RET=, =TAB= or double click | Shows the entry in the main window; opens a calendar event in Calendar | =org-agenda-switch-to=, =org-agenda-goto= |
450| =SPC= | Shows the entry in the main window, keeping the agenda in front | =org-agenda-show-and-scroll-up= |
451| =t= or =C-c C-t= | Changes the TODO state, as in the editor | =org-agenda-todo= |
452| =+=, =-= | Raises or lowers the priority | =org-agenda-priority-up=/=-down= |
453| =,= | Sets the priority | =org-agenda-priority= |
454| =:= or =C-c C-q= | Sets tags | =org-agenda-set-tags= |
455| =C-c C-s= | Schedules | =org-agenda-schedule= |
456| =C-c C-d= | Sets a deadline | =org-agenda-deadline= |
457| =S-<right>=, =S-<left>= (=⇧→=, =⇧←=) | Moves the date the line is listed for by a day | =org-agenda-date-later=/=-earlier= |
458| =I= | Clocks in | =org-agenda-clock-in= |
459| =O= | Clocks out | =org-agenda-clock-out= |
460| =X= | Cancels the clock | =org-agenda-clock-cancel= |
461| =C-c C-w= | Refiles | =org-agenda-refile= |
462| =$=, =C-c $=, =C-c C-x C-s= | Archives | =org-agenda-archive= |
463| =k= | Captures an entry scheduled on the selected line's day | =org-agenda-capture= |
464| =s= | Saves every file | =org-save-all-org-buffers= |
465
466Without 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 [[file:08-capture.org][Capture]].
467
468Right-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.
469
470=t= follows =org-todo=: with fast-selection keys in your TODO keywords it asks for the state, otherwise it cycles (see [[file:05-todos-and-tags.org][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 [[file:06-dates-and-clocking.org][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.
471
472=C-c C-w= brings the main window forward and asks for the target there, where the target list is searchable.
473
474=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 [[file:06-dates-and-clocking.org][Dates, scheduling and clocking]].
475
476Each 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.
477
478** Bulk actions
479
480| Key | Does | Org command |
481|-----+------------------------------------------+--------------------------------|
482| =m= | Marks the selected entry (shown with a bar at its left) | =org-agenda-bulk-mark= |
483| =u= | Unmarks it | =org-agenda-bulk-unmark= |
484| =U= | Unmarks everything | =org-agenda-bulk-unmark-all= |
485| =B= | Asks for an action on every marked entry | =org-agenda-bulk-action= |
486
487=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.
488
489* Reminders
490
491Orgstar 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.
492
493| Setting | Default | =config.toml= |
494|-------------------------------+---------+------------------------------------|
495| Notify before timed entries | on | =reminders = true= under =[orgstar]= |
496| Minutes of warning | 12 | =appt-message-warning-time = 12= |
497
498Both 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.
499
500The 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.
501
502On 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.
503
504* The board
505
506The 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.
507
508The toolbar has:
509
510- a Table / Kanban switch;
511- a match field, with the syntax of [[*Tag and property matches][Tag and property matches]]. When empty, the board shows every entry with a TODO keyword;
512- in table mode, a field of property names to show as extra columns, separated by commas (default =EFFORT=).
513
514These three choices are remembered by the app; they are not in =config.toml=.
515
516** Table
517
518Columns: 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.
519
520** Kanban
521
522Each 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.
523
524With 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.
525
526The board is not available on iOS.
527
528* The agenda on iOS
529
530The 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 [[file:14-ios.org][iOS]]). Differences from the Mac:
531
532- The Views menu, at the top left, 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.
533- 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.
534- The title names the days shown: =Thu 8 Oct=, =Week of 5 Oct=, =October 2026=, or =5 Oct – 14 Oct=.
535- 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.
536- Pull down to refresh.
537- 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.
538- 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.
539- 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.
540- 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.
541- Touch and hold an entry for TODO State…, Reschedule (Tomorrow, Next Week, Pick Date…), Schedule…, Deadline…, Tags…, Priority…, Clock In, Refile… and Archive….
542- Marking an entry done and rescheduling one give haptic feedback.
543- There are no keyboard commands, log mode or bulk marks.
544- 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.
545
546The Today and Up Next widgets show the agenda on the Home Screen and the Lock Screen; see [[file:14-ios.org][iPhone and iPad]].