krz/orgstar

A native macOS editor for org-mode files. editor org-mode swift

guide/07-agenda.html

pages
orgstar/guide/07-agenda.html history · blame · raw

464 lines · 53272 bytes

  1<!DOCTYPE html>
  2<html lang="en">
  3<head>
  4<meta charset="utf-8">
  5<meta name="viewport" content="width=device-width, initial-scale=1">
  6<title>The agenda &middot; Orgstar</title>
  7<meta name="description" content="The agenda window, the TODO list, tag and property matches, saved views, filters, reminders and the board.">
  8<link rel="icon" href="../favicon.svg" type="image/svg+xml">
  9<link rel="stylesheet" href="../theme.css">
 10<link rel="stylesheet" href="../syntax.css">
 11<link rel="stylesheet" href="../style.css">
 12</head>
 13<body>
 14<header class="site">
 15<a class="site-title" href="../index.html">Orgstar</a>
 16<nav>
 17<a href="../install.html">Install</a>
 18<a href="../quickstart.html">Quick start</a>
 19<a href="index.html">Manual</a>
 20</nav>
 21</header>
 22<main>
 23<h1>The agenda</h1>
 24<p class="lede">The agenda collects dated entries and TODO items from your agenda files into one list you can act on.</p>
 25<nav class="toc" aria-label="On this page">
 26<h2>On this page</h2>
 27<ul>
 28<li><a href="#opening-the-agenda">Opening the agenda</a></li>
 29<li><a href="#agenda-files">Agenda files</a></li>
 30<li><a href="#the-day-and-week-view">The day and week view</a>
 31<ul>
 32<li><a href="#moving-through-days">Moving through days</a></li>
 33<li><a href="#what-appears-on-each-day">What appears on each day</a></li>
 34<li><a href="#sorting">Sorting</a></li>
 35<li><a href="#log-mode">Log mode</a></li>
 36</ul></li>
 37<li><a href="#diary-sexps">Diary sexps</a></li>
 38<li><a href="#habits">Habits</a></li>
 39<li><a href="#the-todo-list">The TODO list</a></li>
 40<li><a href="#tag-and-property-matches">Tag and property matches</a>
 41<ul>
 42<li><a href="#tags">Tags</a></li>
 43<li><a href="#properties">Properties</a></li>
 44<li><a href="#keywords">keywords</a></li>
 45</ul></li>
 46<li><a href="#text-search">Text search</a></li>
 47<li><a href="#views">Views</a></li>
 48<li><a href="#filters">Filters</a></li>
 49<li><a href="#the-prefix-and-line-layout">The prefix and line layout</a></li>
 50<li><a href="#acting-on-entries">Acting on entries</a>
 51<ul>
 52<li><a href="#bulk-actions">Bulk actions</a></li>
 53</ul></li>
 54<li><a href="#reminders">Reminders</a></li>
 55<li><a href="#the-board">The board</a>
 56<ul>
 57<li><a href="#table">Table</a></li>
 58<li><a href="#kanban">Kanban</a></li>
 59</ul></li>
 60<li><a href="#the-agenda-on-ios">The agenda on iOS</a></li>
 61</ul>
 62</nav>
 63<h2 id="opening-the-agenda">Opening the agenda</h2>
 64<p>On the Mac the agenda is its own window. Open it with Window ▸ Agenda, or with the key for your preset:</p>
 65<table>
 66<thead>
 67<tr><th>Preset</th><th>Key</th></tr>
 68</thead>
 69<tbody>
 70<tr><td>Mac</td><td><code class="verbatim">⇧⌘A</code></td></tr>
 71<tr><td>Emacs</td><td><code class="verbatim">C-c a</code> or <code class="verbatim">⇧⌘A</code></td></tr>
 72<tr><td>Doom</td><td><code class="verbatim">SPC o a</code> (normal state), <code class="verbatim">C-c a</code> or <code class="verbatim">⇧⌘A</code></td></tr>
 73</tbody>
 74</table>
 75<p>With <code class="verbatim">org-use-speed-commands</code> on, <code class="verbatim">v</code> at the start of a heading line opens it too (see <a href="03-keys.html">Keys</a>).</p>
 76<p>The key opens the window directly. There is no <code class="verbatim">org-agenda</code> dispatcher; you choose what the window shows from the view menu at the left of its toolbar (see <a href="#views">Views</a>).</p>
 77<p>Opening a timestamp with <code class="verbatim">org-open-at-point</code> (<code class="verbatim">C-c C-o</code> in the Emacs preset) opens the agenda on that timestamp's day, or on every day of a date range.</p>
 78<p>On iOS the agenda is the first tab. See <a href="#the-agenda-on-ios">The agenda on iOS</a>.</p>
 79<h2 id="agenda-files">Agenda files</h2>
 80<p>Orgstar has no <code class="verbatim">org-agenda-files</code> list. The agenda reads every <code class="verbatim">.org</code> file at the top level of each folder you have added (see <a href="01-files-and-folders.html">Files and folders</a>). Files whose names start with a dot are left out, as <code class="verbatim">org-agenda-file-regexp</code> leaves them out.</p>
 81<p>To include files in subfolders as well, turn on Settings ▸ Agenda ▸ Include files in subfolders, or set this in <code class="verbatim">config.toml</code>:</p>
 82<pre><code class="language-toml highlight"><span class="source toml"><span class="punctuation definition table toml">[</span><span class="entity name section toml">orgstar</span><span class="punctuation definition table toml">]</span>
 83<span class="variable other key toml">agenda-include-subfolders</span> <span class="keyword operator assignment toml">=</span> <span class="constant language toml">true</span></span></code></pre>
 84<p>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 <code class="verbatim">#+SETUPFILE</code> is read again on every refresh, because its setup file may have changed.</p>
 85<p>Within a file, the agenda skips:</p>
 86<ul>
 87<li>trees tagged <code class="verbatim">ARCHIVE</code>, and every entry in a file whose <code class="verbatim">#+FILETAGS</code> include <code class="verbatim">ARCHIVE</code>;</li>
 88<li>commented trees (a heading whose title starts with <code class="verbatim">COMMENT</code>);</li>
 89<li>everything below a skipped heading.</li>
 90</ul>
 91<p>An entry's category is the nearest <code class="verbatim">CATEGORY</code> property on it or an ancestor, else the file's <code class="verbatim">#+CATEGORY</code>, else the file name without <code class="verbatim">.org</code>.</p>
 92<p>If no agenda file exists, the window says so.</p>
 93<h2 id="the-day-and-week-view">The day and week view</h2>
 94<p>The default view is <code class="verbatim">org-agenda-list</code>: a run of days, each with a header such as <code class="verbatim">Monday      5 October 2026 W41</code> (the ISO week number appears on Mondays).</p>
 95<table>
 96<thead>
 97<tr><th>Setting</th><th>Default</th><th><code class="verbatim">config.toml</code></th><th>Range in Settings</th></tr>
 98</thead>
 99<tbody>
100<tr><td>Days shown</td><td>10</td><td><code class="verbatim">org-agenda-span = 10</code></td><td>1 to 366</td></tr>
101<tr><td>First day, relative to today</td><td>3 days before</td><td><code class="verbatim">org-agenda-start-day = "-3d"</code></td><td>0 to 14 days before</td></tr>
102</tbody>
103</table>
104<p>Both mirror the Emacs variables of the same name. The defaults are Doom's values, not plain Emacs's (a week starting today). <code class="verbatim">org-agenda-start-day</code> takes only day offsets such as <code class="verbatim">"-3d"</code> or <code class="verbatim">"+0d"</code>. There are no day, week or month view keys (<code class="verbatim">d</code>, <code class="verbatim">w</code>, <code class="verbatim">m</code> in Emacs) and no <code class="verbatim">org-agenda-start-on-weekday</code>: the span is a number of days and always begins at the configured offset.</p>
105<h3 id="moving-through-days">Moving through days</h3>
106<table>
107<thead>
108<tr><th>Key</th><th>Toolbar</th><th>Does</th><th>Org command</th></tr>
109</thead>
110<tbody>
111<tr><td><code class="verbatim">f</code></td><td>Later (›)</td><td>Moves forward by a whole span</td><td><code class="verbatim">org-agenda-later</code></td></tr>
112<tr><td><code class="verbatim">b</code></td><td>Earlier (‹)</td><td>Moves back by a whole span</td><td><code class="verbatim">org-agenda-earlier</code></td></tr>
113<tr><td><code class="verbatim">.</code></td><td>Today</td><td>Returns to the span around today</td><td><code class="verbatim">org-agenda-goto-today</code></td></tr>
114<tr><td><code class="verbatim">g</code>, <code class="verbatim">r</code></td><td></td><td>Refreshes, and reloads <code class="verbatim">views.toml</code></td><td><code class="verbatim">org-agenda-redo</code></td></tr>
115</tbody>
116</table>
117<p>The agenda also refreshes on its own when files change, when you edit an open buffer, and once a minute so the time grid and the current day stay correct.</p>
118<h3 id="what-appears-on-each-day">What appears on each day</h3>
119<p>The entries follow <code class="verbatim">org-agenda-get-day-entries</code> with Org's default entry types, in the formats Org prints.</p>
120<table>
121<thead>
122<tr><th>Entry</th><th>Where it appears</th><th>Leader</th></tr>
123</thead>
124<tbody>
125<tr><td><code class="verbatim">DEADLINE</code> on that day</td><td>On its day</td><td><code class="verbatim">Deadline:</code></td></tr>
126<tr><td><code class="verbatim">DEADLINE</code> in the future</td><td>On today, from the warning period before it</td><td><code class="verbatim">In   3 d.:</code></td></tr>
127<tr><td><code class="verbatim">DEADLINE</code> in the past, not done</td><td>On today</td><td><code class="verbatim">2 d. ago:</code></td></tr>
128<tr><td><code class="verbatim">SCHEDULED</code> on that day</td><td>On its day</td><td><code class="verbatim">Scheduled:</code></td></tr>
129<tr><td><code class="verbatim">SCHEDULED</code> in the past, not done</td><td>On today</td><td><code class="verbatim">Sched. 3x:</code></td></tr>
130<tr><td>Active timestamp <code class="verbatim">&lt;2026-10-05 Mon&gt;</code></td><td>On its day; also in property drawers</td><td>none</td></tr>
131<tr><td>Repeating timestamp <code class="verbatim">&lt;… +1w&gt;</code></td><td>On each occurrence within the span</td><td>none</td></tr>
132<tr><td>Date range <code class="verbatim">&lt;…&gt;--&lt;…&gt;</code></td><td>On every day of the range</td><td><code class="verbatim">(2/5):</code> (day 2 of 5)</td></tr>
133<tr><td>Diary sexp <code class="verbatim">%%(…)</code> line or <code class="verbatim">&lt;%%(…)&gt;</code></td><td>On each day the sexp applies; see <a href="#diary-sexps">Diary sexps</a></td><td>none</td></tr>
134<tr><td>Habit (<code class="verbatim">STYLE: habit</code>)</td><td>On today only, while not done; see <a href="#habits">Habits</a></td><td>none, with a consistency graph</td></tr>
135</tbody>
136</table>
137<p>Details:</p>
138<ul>
139<li>Deadline warnings use <code class="verbatim">org-deadline-warning-days</code>, fixed at 14 days. A <code class="verbatim">-Nd</code> cookie in the timestamp (<code class="verbatim">&lt;2026-10-20 Tue -3d&gt;</code>) changes the warning for that deadline; <code class="verbatim">w</code>, <code class="verbatim">m</code> and <code class="verbatim">y</code> units work too.</li>
140<li>A <code class="verbatim">-Nd</code> cookie on a <code class="verbatim">SCHEDULED</code> timestamp delays it: the entry first shows N days after the scheduled date.</li>
141<li>Repeaters on <code class="verbatim">SCHEDULED</code> and <code class="verbatim">DEADLINE</code> timestamps (<code class="verbatim">+1w</code>, <code class="verbatim">++1w</code>, <code class="verbatim">.+1d</code>) make the entry show on the next occurrence on future days, as in Org.</li>
142<li>A done entry shows only on the day of its deadline or scheduled date, not as overdue.</li>
143<li>Inactive timestamps (<code class="verbatim">[…]</code>) never appear, except in log mode.</li>
144<li>Ranges in comment lines and inside source blocks are ignored, as in Org.</li>
145</ul>
146<p>Entries with a time of day sort into the day by time. On today, and on any day when the span is one day, a time grid is added when at least one entry has a time: lines at 8:00, 10:00, 12:00, 14:00, 16:00, 18:00 and 20:00, and on today a "now" line at the current time. The grid times are not configurable.</p>
147<p>A time can come from the timestamp (<code class="verbatim">&lt;2026-10-05 Mon 14:00-15:30&gt;</code>) or from the heading text (<code class="verbatim">Call Ada 9:30am</code>), as <code class="verbatim">org-agenda-search-headline-for-time</code> allows. Times past 24:00, such as <code class="verbatim">25:30</code>, show as <code class="verbatim">+1:30</code>.</p>
148<h3 id="sorting">Sorting</h3>
149<p>Days are sorted as <code class="verbatim">org-agenda-sorting-strategy</code> sorts them by default for the agenda: <code class="verbatim">(habit-down time-up urgency-down category-keep)</code>. 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. The TODO list and match views sort by urgency, then file order. The sorting is not configurable.</p>
150<h3 id="log-mode">Log mode</h3>
151<p>Press <code class="verbatim">l</code> to turn log mode (<code class="verbatim">org-agenda-log-mode</code>) on or off. Each day then also shows:</p>
152<ul>
153<li><code class="verbatim">Closed:</code> entries whose <code class="verbatim">CLOSED:</code> timestamp is on that day;</li>
154<li><code class="verbatim">Clocked: (1:30)</code> for each <code class="verbatim">CLOCK:</code> line that starts on that day, with the clock's range and duration.</li>
155</ul>
156<p>A note under a clock line (a list item directly below it) is added to the line after a <code class="verbatim">-</code>. These are the default <code class="verbatim">org-agenda-log-mode-items</code>, <code class="verbatim">(closed clock)</code>; state changes are not shown and there is no setting for that.</p>
157<h2 id="diary-sexps">Diary sexps</h2>
158<p>The agenda evaluates diary sexps as <code class="verbatim">org-diary-sexp-entry</code> does. They can appear as a line starting with <code class="verbatim">%%(</code> under a heading, as an active timestamp <code class="verbatim">&lt;%%(…)&gt;</code>, or as a <code class="verbatim">SCHEDULED</code> or <code class="verbatim">DEADLINE</code> value.</p>
159<pre><code class="language-org highlight"><span class="text org"><span class="markup heading org"><span class="punctuation definition heading org">*</span> Birthdays
160</span>%%(diary-anniversary 10 7 1990) Ada is %d years old
161%%(org-anniversary 1985 3 14) Bob turns %d
162
163<span class="markup heading org"><span class="punctuation definition heading org">*</span> Teaching
164</span><span class="markup heading org"><span class="punctuation definition heading org">**</span> Algebra lecture
165</span>&lt;%%(org-class 2026 9 7 2026 12 18 1 41)&gt;</span></code></pre>
166<p>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.</p>
167<table>
168<thead>
169<tr><th>Function</th><th>Applies</th><th>Date order</th></tr>
170</thead>
171<tbody>
172<tr><td><code class="verbatim">diary-date</code> <em>month day year</em></td><td>On matching dates; <code class="verbatim">t</code> or a list matches any or several</td><td>month day year</td></tr>
173<tr><td><code class="verbatim">diary-block</code> <em>m1 d1 y1 m2 d2 y2</em></td><td>Every day from the first date to the second</td><td>month day year</td></tr>
174<tr><td><code class="verbatim">diary-float</code> <em>month dayname n</em> [/day/]</td><td>The nth <em>dayname</em> (0 is Sunday) of the month; negative n counts from the end</td><td>month</td></tr>
175<tr><td><code class="verbatim">diary-anniversary</code> <em>month day</em> [/year/]</td><td>Each year on the date; <code class="verbatim">%d</code> is the count, <code class="verbatim">%s</code> its ordinal suffix</td><td>month day year</td></tr>
176<tr><td><code class="verbatim">diary-cyclic</code> <em>n month day year</em></td><td>Every n days from the date</td><td>month day year</td></tr>
177<tr><td><code class="verbatim">diary-remind</code> <em>sexp days</em></td><td>On the days before another sexp applies: <code class="verbatim">Reminder: Only 3 days until …</code></td><td>n/a</td></tr>
178<tr><td><code class="verbatim">org-anniversary</code> <em>year month day</em></td><td>As <code class="verbatim">diary-anniversary</code></td><td>year month day</td></tr>
179<tr><td><code class="verbatim">org-cyclic</code> <em>n year month day</em></td><td>As <code class="verbatim">diary-cyclic</code></td><td>year month day</td></tr>
180<tr><td><code class="verbatim">org-block</code> <em>y1 m1 d1 y2 m2 d2</em></td><td>As <code class="verbatim">diary-block</code></td><td>year month day</td></tr>
181<tr><td><code class="verbatim">org-date</code> <em>year month day</em></td><td>As <code class="verbatim">diary-date</code></td><td>year month day</td></tr>
182<tr><td><code class="verbatim">org-class</code> <em>y1 m1 d1 y2 m2 d2 dayname</em> [/skip-weeks…/]</td><td>On <em>dayname</em> between the dates, except the ISO weeks listed</td><td>year month day</td></tr>
183</tbody>
184</table>
185<p>The <code class="verbatim">diary-</code> functions read dates in <code class="verbatim">calendar-date-style</code> <code class="verbatim">american</code> (month, day, year); the <code class="verbatim">org-</code> functions use ISO order. <code class="verbatim">org-class</code> skip lists take ISO week numbers only; holiday names and <code class="verbatim">holidays</code> need the Emacs calendar's holiday lists and make the sexp fail.</p>
186<p>For your own expressions, the variables <code class="verbatim">date</code> (as <code class="verbatim">(month day year)</code>) and <code class="verbatim">entry</code> are bound, and these calendar functions are available: <code class="verbatim">calendar-extract-month</code>, <code class="verbatim">calendar-extract-day</code>, <code class="verbatim">calendar-extract-year</code>, <code class="verbatim">calendar-absolute-from-gregorian</code>, <code class="verbatim">calendar-gregorian-from-absolute</code>, <code class="verbatim">calendar-day-of-week</code>, <code class="verbatim">calendar-leap-year-p</code>, <code class="verbatim">calendar-last-day-of-month</code>, <code class="verbatim">calendar-date-equal</code>, <code class="verbatim">calendar-day-number</code>, <code class="verbatim">calendar-nth-named-absday</code>, <code class="verbatim">calendar-nth-named-day</code>, <code class="verbatim">calendar-iso-from-absolute</code>, <code class="verbatim">diary-ordinal-suffix</code> and <code class="verbatim">diary-make-date</code>. The evaluator also has the common special forms (<code class="verbatim">if</code>, <code class="verbatim">when</code>, <code class="verbatim">cond</code>, <code class="verbatim">and</code>, <code class="verbatim">or</code>, <code class="verbatim">let</code>, <code class="verbatim">progn</code> and others) and arithmetic. It is a small subset of Emacs Lisp, not Emacs.</p>
187<p>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.</p>
188<h2 id="habits">Habits</h2>
189<p>An entry with the property <code class="verbatim">STYLE: habit</code> and a <code class="verbatim">SCHEDULED</code> timestamp with a repeater is a habit, as in <code class="verbatim">org-habit</code>:</p>
190<pre><code class="language-org highlight"><span class="text org"><span class="markup heading org"><span class="punctuation definition heading org">*</span> <span class="keyword other todo org">TODO</span> Run
191</span>SCHEDULED: <span class="constant other timestamp org">&lt;2026-10-05 Mon .+2d/4d&gt;</span>
192:PROPERTIES:
193:STYLE:    habit
194:END:
195<span class="punctuation definition list org">- </span>State &quot;DONE&quot;       from &quot;TODO&quot;       <span class="constant other timestamp org">[2026-10-03 Sat 07:10]</span>
196<span class="punctuation definition list org">- </span>State &quot;DONE&quot;       from &quot;TODO&quot;       <span class="constant other timestamp org">[2026-10-01 Thu 07:05]</span></span></code></pre>
197<p>The repeater can be <code class="verbatim">+</code>, <code class="verbatim">++</code> or <code class="verbatim">.+</code>, with an optional <code class="verbatim">/Nd</code> maximum interval. Days the habit was done are read from <code class="verbatim">- State "DONE" … [date]</code> lines (for any done keyword) and <code class="verbatim">CLOSING NOTE [date]</code> lines in the entry.</p>
198<p>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 (<code class="verbatim">org-habit-preceding-days</code> and <code class="verbatim">org-habit-following-days</code>), with <code class="verbatim">*</code> on days it was done and <code class="verbatim">!</code> on today. Cell colors follow org-habit's faces:</p>
199<table>
200<thead>
201<tr><th>Color</th><th>Meaning</th><th>Theme key</th></tr>
202</thead>
203<tbody>
204<tr><td>Blue</td><td>Not yet due</td><td><code class="verbatim">habit-clear</code></td></tr>
205<tr><td>Green</td><td>Due, within the allowed interval</td><td><code class="verbatim">habit-ready</code></td></tr>
206<tr><td>Yellow</td><td>Last day of the interval</td><td><code class="verbatim">habit-alert</code></td></tr>
207<tr><td>Red</td><td>Overdue</td><td><code class="verbatim">habit-overdue</code></td></tr>
208</tbody>
209</table>
210<p>Future days use lighter shades. Hover a cell to see its date. Habits sort after other entries.</p>
211<h2 id="the-todo-list">The TODO list</h2>
212<p>The built-in view TODO List is <code class="verbatim">org-todo-list</code>: every heading with a TODO keyword that is not a done keyword, sorted by urgency (priority first). The time-based skipping options (<code class="verbatim">org-agenda-todo-ignore-scheduled</code> and its relatives) are not supported; every open TODO appears, as with Org's defaults.</p>
213<p>A saved view can list specific keywords instead, done ones included, with <code class="verbatim">keywords = "WAIT|HOLD"</code> (see <a href="#views">Views</a>). This mirrors <code class="verbatim">C-u M-x org-todo-list</code> with a keyword argument.</p>
214<h2 id="tag-and-property-matches">Tag and property matches</h2>
215<p>Choose Match… from the view menu to list entries matching a match string, as <code class="verbatim">org-tags-view</code> (<code class="verbatim">m</code>) does, or TODO Match… to list only entries with an open TODO keyword (<code class="verbatim">M</code>). Type the match in the toolbar field and press Return.</p>
216<p>The syntax is <code class="verbatim">org-make-tags-matcher</code>'s:</p>
217<pre><code class="language-text">+work-boss|LEVEL&gt;2+TODO="WAIT"/!NEXT</code></pre>
218<h3 id="tags">Tags</h3>
219<table>
220<thead>
221<tr><th>Form</th><th>Matches</th></tr>
222</thead>
223<tbody>
224<tr><td><code class="verbatim">work</code>, <code class="verbatim">+work</code></td><td>Entries with the tag</td></tr>
225<tr><td><code class="verbatim">-boss</code></td><td>Entries without the tag</td></tr>
226<tr><td><code class="verbatim">+work-boss</code></td><td>Both conditions (and)</td></tr>
227<tr><td><code class="verbatim">a&amp;b</code></td><td><code class="verbatim">&amp;</code> between terms is the same as <code class="verbatim">+</code></td></tr>
228<tr><td><code class="verbatim">{^proj}</code></td><td>Any tag matching the regular expression</td></tr>
229</tbody>
230</table>
231<p><code class="verbatim">work|home</code> matches either side: the vertical bar separates alternatives, and within an alternative, terms are joined by <code class="verbatim">+</code>, <code class="verbatim">-</code> or <code class="verbatim">&amp;</code>. Tags include inherited tags and <code class="verbatim">#+FILETAGS</code>. Tag names compare exactly; regular expressions in braces are Emacs regexps, matched without case.</p>
232<h3 id="properties">Properties</h3>
233<p>A term can compare a property: <code class="verbatim">NAME op value</code>.</p>
234<table>
235<thead>
236<tr><th>Operator</th><th>Meaning</th></tr>
237</thead>
238<tbody>
239<tr><td><code class="verbatim">=</code>, <code class="verbatim">==</code></td><td>Equal</td></tr>
240<tr><td><code class="verbatim">&lt;&gt;</code>, <code class="verbatim">!=</code>, <code class="verbatim">/=</code></td><td>Not equal</td></tr>
241<tr><td><code class="verbatim">&lt;</code>, <code class="verbatim">&lt;=</code></td><td>Less, less or equal</td></tr>
242<tr><td><code class="verbatim">&gt;</code>, <code class="verbatim">&gt;=</code></td><td>Greater, greater or equal</td></tr>
243</tbody>
244</table>
245<p>The value decides how the comparison works:</p>
246<table>
247<thead>
248<tr><th>Value</th><th>Compared as</th></tr>
249</thead>
250<tbody>
251<tr><td><code class="verbatim">3</code>, <code class="verbatim">-1.5</code></td><td>Numbers; a missing or non-numeric property is 0</td></tr>
252<tr><td><code class="verbatim">"WAIT"</code></td><td>Strings</td></tr>
253<tr><td><code class="verbatim">{regexp}</code></td><td>Regular expression match; with <code class="verbatim">&lt;&gt;</code>, <code class="verbatim">!=</code> or <code class="verbatim">/=</code> it must not match</td></tr>
254<tr><td><code class="verbatim">"&lt;2026-10-01&gt;"</code></td><td>Dates. Also <code class="verbatim">"&lt;now&gt;"</code>, <code class="verbatim">"&lt;today&gt;"</code>, <code class="verbatim">"&lt;tomorrow&gt;"</code>, <code class="verbatim">"&lt;yesterday&gt;"</code>, and offsets such as <code class="verbatim">"&lt;-1w&gt;"</code> or <code class="verbatim">"&lt;+3d&gt;"</code> (units <code class="verbatim">h</code> <code class="verbatim">d</code> <code class="verbatim">w</code> <code class="verbatim">m</code> <code class="verbatim">y</code>). Brackets may be <code class="verbatim">[…]</code>.</td></tr>
255</tbody>
256</table>
257<p>Follow the operator with <code class="verbatim">*</code> (<code class="verbatim">Effort&gt;*1</code>) to require that the property exists; without it, a missing property compares as an empty string or 0.</p>
258<p>Names are case-insensitive. Prefix a character in a name with <code class="verbatim">\</code> to use it literally (<code class="verbatim">MY\-PROP</code>"x"=). Besides the entry's own property drawer, these special properties work:</p>
259<table>
260<thead>
261<tr><th>Name</th><th>Value</th></tr>
262</thead>
263<tbody>
264<tr><td><code class="verbatim">LEVEL</code></td><td>The heading's level</td></tr>
265<tr><td><code class="verbatim">TODO</code></td><td>The TODO keyword</td></tr>
266<tr><td><code class="verbatim">ITEM</code></td><td>The heading title</td></tr>
267<tr><td><code class="verbatim">PRIORITY</code></td><td>The priority letter, or the default priority</td></tr>
268<tr><td><code class="verbatim">CATEGORY</code></td><td>The entry's category</td></tr>
269<tr><td><code class="verbatim">FILE</code></td><td>The file's path</td></tr>
270<tr><td><code class="verbatim">TAGS</code></td><td>The heading's own tags, as <code class="verbatim">:a:b:</code></td></tr>
271<tr><td><code class="verbatim">ALLTAGS</code></td><td>All tags including inherited ones</td></tr>
272<tr><td><code class="verbatim">SCHEDULED</code>, <code class="verbatim">DEADLINE</code>, <code class="verbatim">CLOSED</code></td><td>The planning timestamp</td></tr>
273<tr><td><code class="verbatim">TIMESTAMP</code>, <code class="verbatim">TIMESTAMP_IA</code></td><td>The entry's first active or inactive timestamp</td></tr>
274</tbody>
275</table>
276<p>Properties are not inherited in matches (<code class="verbatim">org-use-property-inheritance</code> is nil). With a date value, <code class="verbatim">&lt;&gt;</code> and its synonyms match dates that are equal, as Orgstar's comparison mirrors <code class="verbatim">org-time&lt;&gt;</code> in Org 9.8.7; use <code class="verbatim">&lt;</code> and <code class="verbatim">&gt;</code> for date ranges.</p>
277<h3 id="keywords"><span class="todo TODO">TODO</span> keywords</h3>
278<p>After the last <code class="verbatim">/</code> (one not followed by a quote), the match restricts TODO keywords:</p>
279<table>
280<thead>
281<tr><th>Form</th><th>Matches</th></tr>
282</thead>
283<tbody>
284<tr><td><code class="verbatim">/NEXT</code></td><td>Entries whose keyword is <code class="verbatim">NEXT</code></td></tr>
285<tr><td><code class="verbatim">/-WAIT</code></td><td>Any keyword but <code class="verbatim">WAIT</code>, and entries with none</td></tr>
286<tr><td><code class="verbatim">/{^W}</code></td><td>Keywords matching the regexp</td></tr>
287<tr><td><code class="verbatim">/!</code></td><td>Only entries with an open (not done) TODO keyword</td></tr>
288<tr><td><code class="verbatim">/!-WAIT-HOLD</code></td><td>Open TODO entries except those two</td></tr>
289</tbody>
290</table>
291<p><code class="verbatim">/TODO|NEXT</code> matches either keyword, and <code class="verbatim">/!NEXT|WAIT</code> either one while open. <code class="verbatim">/!</code> has the same effect as choosing TODO Match….</p>
292<h2 id="text-search">Text search</h2>
293<p>The agenda has no <code class="verbatim">org-search-view</code> (<code class="verbatim">s</code>). To search the text of your files, use Search Notes (<code class="verbatim">⇧⌘F</code>).</p>
294<h2 id="views">Views</h2>
295<p>The view menu lists the built-in views, Agenda and TODO List, then the views in <code class="verbatim">views.toml</code>, then Match… and TODO Match…. Saved views mirror <code class="verbatim">org-agenda-custom-commands</code>, with fewer options.</p>
296<p><code class="verbatim">views.toml</code> lives in the configuration folder beside <code class="verbatim">config.toml</code> (<code class="verbatim">~/.config/orgstar/</code> by default; see <a href="13-configuration.html">Configuration</a>). Each view is a <code class="verbatim">[[view]]</code> table:</p>
297<pre><code class="language-toml highlight"><span class="source toml"><span class="punctuation definition table array toml">[[</span><span class="entity name section toml">view</span><span class="punctuation definition table array toml">]]</span>
298<span class="variable other key toml">name</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>Fortnight<span class="punctuation definition string end toml">&quot;</span></span>
299<span class="variable other key toml">type</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>agenda<span class="punctuation definition string end toml">&quot;</span></span>
300<span class="variable other key toml">span</span> <span class="keyword operator assignment toml">=</span> <span class="constant numeric toml">14</span>
301<span class="variable other key toml">start</span> <span class="keyword operator assignment toml">=</span> <span class="constant numeric toml">0</span>
302
303<span class="punctuation definition table array toml">[[</span><span class="entity name section toml">view</span><span class="punctuation definition table array toml">]]</span>
304<span class="variable other key toml">name</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>Waiting<span class="punctuation definition string end toml">&quot;</span></span>
305<span class="variable other key toml">type</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>todo<span class="punctuation definition string end toml">&quot;</span></span>
306<span class="variable other key toml">keywords</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>WAIT|HOLD<span class="punctuation definition string end toml">&quot;</span></span>
307
308<span class="punctuation definition table array toml">[[</span><span class="entity name section toml">view</span><span class="punctuation definition table array toml">]]</span>
309<span class="variable other key toml">name</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>Work<span class="punctuation definition string end toml">&quot;</span></span>
310<span class="variable other key toml">type</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>match<span class="punctuation definition string end toml">&quot;</span></span>
311<span class="variable other key toml">match</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>+work-boss<span class="punctuation definition string end toml">&quot;</span></span>
312
313<span class="punctuation definition table array toml">[[</span><span class="entity name section toml">view</span><span class="punctuation definition table array toml">]]</span>
314<span class="variable other key toml">name</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>Next at work<span class="punctuation definition string end toml">&quot;</span></span>
315<span class="variable other key toml">type</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>todo-match<span class="punctuation definition string end toml">&quot;</span></span>
316<span class="variable other key toml">match</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span>+work/NEXT<span class="punctuation definition string end toml">&quot;</span></span></span></code></pre>
317<table>
318<thead>
319<tr><th>Key</th><th>Applies to</th><th>Meaning</th></tr>
320</thead>
321<tbody>
322<tr><td><code class="verbatim">name</code></td><td>all, required</td><td>The name in the view menu</td></tr>
323<tr><td><code class="verbatim">type</code></td><td>all</td><td><code class="verbatim">agenda</code> (the default), <code class="verbatim">todo</code>, <code class="verbatim">match</code> or <code class="verbatim">todo-match</code></td></tr>
324<tr><td><code class="verbatim">span</code></td><td><code class="verbatim">agenda</code></td><td>Days shown; the setting when omitted</td></tr>
325<tr><td><code class="verbatim">start</code></td><td><code class="verbatim">agenda</code></td><td>First day as an integer number of days from today (<code class="verbatim">-3</code>, <code class="verbatim">0</code>); the setting when omitted</td></tr>
326<tr><td><code class="verbatim">keywords</code></td><td><code class="verbatim">todo</code></td><td>Keywords separated by the vertical bar; all open TODOs when omitted</td></tr>
327<tr><td><code class="verbatim">match</code></td><td><code class="verbatim">match</code>, <code class="verbatim">todo-match</code>, required</td><td>A match string as in <a href="#tag-and-property-matches">Tag and property matches</a>; <code class="verbatim">todo-match</code> keeps only open TODO entries</td></tr>
328</tbody>
329</table>
330<p>Note that <code class="verbatim">start</code> is a plain integer here, while <code class="verbatim">org-agenda-start-day</code> in <code class="verbatim">config.toml</code> is a string such as <code class="verbatim">"-3d"</code>.</p>
331<p>Not supported: block agendas (several views in one), per-view settings such as <code class="verbatim">org-agenda-skip-function</code> or a different prefix format, <code class="verbatim">stuck</code> projects, and search views. The views load when the window opens and again on <code class="verbatim">g</code> or <code class="verbatim">r</code>. A problem in the file, such as a missing <code class="verbatim">name</code> or an unknown <code class="verbatim">type</code>, shows in the status line at the bottom of the window, and the remaining views still load.</p>
332<h2 id="filters">Filters</h2>
333<p>Filters hide lines without changing the view, as <code class="verbatim">org-agenda-filter</code> does. Time grid lines always stay. The active filter shows in the status line at the bottom of the window as <code class="verbatim">Filter: …</code>.</p>
334<table>
335<thead>
336<tr><th>Key</th><th>Does</th><th>Org command</th></tr>
337</thead>
338<tbody>
339<tr><td><code class="verbatim">\</code></td><td>Asks for a tag filter</td><td><code class="verbatim">org-agenda-filter-by-tag</code></td></tr>
340<tr><td><code class="verbatim">&lt;</code></td><td>Keeps only the selected line's category; again removes it</td><td><code class="verbatim">org-agenda-filter-by-category</code></td></tr>
341<tr><td><code class="verbatim">=</code></td><td>Asks for a regexp filter</td><td><code class="verbatim">org-agenda-filter-by-regexp</code></td></tr>
342</tbody>
343</table>
344<p>The vertical bar key, <code class="verbatim">|</code>, removes every filter (<code class="verbatim">org-agenda-filter-remove-all</code>).</p>
345<p>The combined filter <code class="verbatim">/</code> reads terms such as:</p>
346<pre><code class="language-text">+work-phone&lt;2:00/report/</code></pre>
347<ul>
348<li><code class="verbatim">+word</code> keeps and <code class="verbatim">-word</code> drops lines. A word without a sign keeps.</li>
349<li>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 <code class="verbatim">-</code>: <code class="verbatim">"my-cat"</code>.</li>
350<li><code class="verbatim">&lt;0:30</code>, <code class="verbatim">&gt;1:00</code> and <code class="verbatim">=1:00</code> compare the entry's <code class="verbatim">Effort</code> property. Entries without an effort count as longer than any effort, as with <code class="verbatim">org-agenda-sort-noeffort-is-high</code> t. Durations can be <code class="verbatim">H:MM</code>, minutes, or units such as <code class="verbatim">1h 30min</code> or <code class="verbatim">2d</code>.</li>
351<li><code class="verbatim">/regexp/</code> keeps lines whose text matches; <code class="verbatim">-/regexp/</code> drops them. Matching ignores case.</li>
352<li>Starting the input with <code class="verbatim">+</code> followed by another sign (<code class="verbatim">++urgent</code>) adds to the current filter instead of replacing it.</li>
353</ul>
354<p>With two or more <code class="verbatim">+</code> categories, a line may have any of them. Tag terms all have to hold.</p>
355<p>The <code class="verbatim">/</code> 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 <code class="verbatim">-</code> in quotes. Pressing <code class="verbatim">Return</code> on it unchanged keeps the same filter.</p>
356<p>The <code class="verbatim">\</code> prompt reads every word as a tag, whether or not a line has it; there, <code class="verbatim">{regexp}</code> matches any tag that matches the regexp. The <code class="verbatim">=</code> prompt takes one regexp, with a leading <code class="verbatim">-</code> to drop matches. The <code class="verbatim">_</code> prompt takes one comparison such as <code class="verbatim">&lt;0:30</code>.</p>
357<h2 id="the-prefix-and-line-layout">The prefix and line layout</h2>
358<p>Each line shows the category, the time, the leader (<code class="verbatim">Deadline:</code>, <code class="verbatim">In   3 d.:</code>, <code class="verbatim">(2/5):</code>), the heading with its TODO keyword colored, the habit graph if any, and the tags.</p>
359<p>To change what comes before the heading, set <code class="verbatim">org-agenda-prefix-format</code> in <code class="verbatim">config.toml</code>:</p>
360<pre><code class="language-toml highlight"><span class="source toml"><span class="punctuation definition table toml">[</span><span class="entity name section toml">org-agenda-prefix-format</span><span class="punctuation definition table toml">]</span>
361<span class="variable other key toml">agenda</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span> %i %-12:c%?-12t% s<span class="punctuation definition string end toml">&quot;</span></span>
362<span class="variable other key toml">todo</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span> %i %-12:c<span class="punctuation definition string end toml">&quot;</span></span>
363<span class="variable other key toml">tags</span> <span class="keyword operator assignment toml">=</span> <span class="string quoted double toml"><span class="punctuation definition string begin toml">&quot;</span> %i %-12:c<span class="punctuation definition string end toml">&quot;</span></span></span></code></pre>
364<p>These are the defaults. <code class="verbatim">agenda</code> applies to the day view, <code class="verbatim">todo</code> to the TODO list, and <code class="verbatim">tags</code> 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.</p>
365<table>
366<thead>
367<tr><th>Field</th><th>Shows</th></tr>
368</thead>
369<tbody>
370<tr><td><code class="verbatim">%c</code></td><td>The category</td></tr>
371<tr><td><code class="verbatim">%t</code></td><td>The time of day, or the time range</td></tr>
372<tr><td><code class="verbatim">%s</code></td><td>The leader: <code class="verbatim">Scheduled:</code>, <code class="verbatim">Deadline:</code>, <code class="verbatim">In 3 d.:</code> and so on</td></tr>
373<tr><td><code class="verbatim">%e</code></td><td>The <code class="verbatim">Effort</code> property</td></tr>
374<tr><td><code class="verbatim">%l</code></td><td>One space per heading level</td></tr>
375<tr><td><code class="verbatim">%b</code></td><td>The outline path above the heading, each title followed by <code class="verbatim">-&gt;</code></td></tr>
376<tr><td><code class="verbatim">%T</code></td><td>The item's last tag, counting inherited tags</td></tr>
377<tr><td><code class="verbatim">%i</code></td><td>The category icon; always empty in Orgstar</td></tr>
378</tbody>
379</table>
380<p>Each field takes Org's modifiers: <code class="verbatim">%-12c</code> pads to 12 columns on the right (<code class="verbatim">%12c</code> on the left); <code class="verbatim">%-12.6c</code> limits a category to 5 characters; <code class="verbatim">%?t</code> leaves the field out entirely when empty; a punctuation character after the width (<code class="verbatim">%-12:c</code>) is added after a non-empty value. When the format contains <code class="verbatim">%t</code>, times move out of the heading text into the prefix, as <code class="verbatim">org-agenda-remove-times-when-in-prefix</code> does. <code class="verbatim">%(…)</code> Lisp forms are accepted but always empty.</p>
381<p>Colors come from the theme keys <code class="verbatim">agenda-background</code>, <code class="verbatim">agenda-date</code>, <code class="verbatim">agenda-today</code>, <code class="verbatim">agenda-time</code>, <code class="verbatim">agenda-category</code>, <code class="verbatim">agenda-deadline</code>, <code class="verbatim">agenda-upcoming</code>, <code class="verbatim">agenda-scheduled</code> and <code class="verbatim">agenda-scheduled-past</code> (see <a href="13-configuration.html">Configuration</a>).</p>
382<h2 id="acting-on-entries">Acting on entries</h2>
383<p>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 <code class="verbatim">keymap.toml</code>.</p>
384<table>
385<thead>
386<tr><th>Key</th><th>Does</th><th>Org command</th></tr>
387</thead>
388<tbody>
389<tr><td><code class="verbatim">RET</code> or double click</td><td>Shows the entry in the main window</td><td><code class="verbatim">org-agenda-switch-to</code></td></tr>
390<tr><td><code class="verbatim">t</code> or <code class="verbatim">C-c C-t</code></td><td>Changes the TODO state, as in the editor</td><td><code class="verbatim">org-agenda-todo</code></td></tr>
391<tr><td><code class="verbatim">+</code>, <code class="verbatim">-</code></td><td>Raises or lowers the priority</td><td><code class="verbatim">org-agenda-priority-up=/</code>-down=</td></tr>
392<tr><td><code class="verbatim">:</code> or <code class="verbatim">C-c C-q</code></td><td>Sets tags</td><td><code class="verbatim">org-agenda-set-tags</code></td></tr>
393<tr><td><code class="verbatim">C-c C-s</code></td><td>Schedules</td><td><code class="verbatim">org-agenda-schedule</code></td></tr>
394<tr><td><code class="verbatim">C-c C-d</code></td><td>Sets a deadline</td><td><code class="verbatim">org-agenda-deadline</code></td></tr>
395<tr><td><code class="verbatim">S-&lt;right&gt;</code>, <code class="verbatim">S-&lt;left&gt;</code> (<code class="verbatim">⇧→</code>, <code class="verbatim">⇧←</code>)</td><td>Moves the date the line is listed for by a day</td><td><code class="verbatim">org-agenda-date-later=/</code>-earlier=</td></tr>
396<tr><td><code class="verbatim">I</code></td><td>Clocks in</td><td><code class="verbatim">org-agenda-clock-in</code></td></tr>
397<tr><td><code class="verbatim">O</code></td><td>Clocks out</td><td><code class="verbatim">org-agenda-clock-out</code></td></tr>
398<tr><td><code class="verbatim">X</code></td><td>Cancels the clock</td><td><code class="verbatim">org-agenda-clock-cancel</code></td></tr>
399<tr><td><code class="verbatim">C-c C-w</code></td><td>Refiles</td><td><code class="verbatim">org-agenda-refile</code></td></tr>
400<tr><td><code class="verbatim">$</code>, <code class="verbatim">C-c $</code>, <code class="verbatim">C-c C-x C-s</code></td><td>Archives</td><td><code class="verbatim">org-agenda-archive</code></td></tr>
401</tbody>
402</table>
403<p><code class="verbatim">t</code> follows <code class="verbatim">org-todo</code>: with fast-selection keys in your TODO keywords it asks for the state, otherwise it cycles (see <a href="05-todos-and-tags.html">TODOs and tags</a>). Questions an action needs, such as a date for <code class="verbatim">C-c C-s</code> or a note on a state change, appear in the agenda window. Dates take the same input as in the editor (see <a href="06-dates-and-clocking.html">Dates, scheduling and clocking</a>). <code class="verbatim">S-&lt;right&gt;</code> and <code class="verbatim">S-&lt;left&gt;</code> work only on deadline, scheduled and timestamp lines; they change the timestamp the line comes from.</p>
404<p><code class="verbatim">C-c C-w</code> brings the main window forward and asks for the target there, where the target list is searchable.</p>
405<p>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.</p>
406<h3 id="bulk-actions">Bulk actions</h3>
407<table>
408<thead>
409<tr><th>Key</th><th>Does</th><th>Org command</th></tr>
410</thead>
411<tbody>
412<tr><td><code class="verbatim">m</code></td><td>Marks the selected entry (shown with <code class="verbatim">›</code>)</td><td><code class="verbatim">org-agenda-bulk-mark</code></td></tr>
413<tr><td><code class="verbatim">u</code></td><td>Unmarks it</td><td><code class="verbatim">org-agenda-bulk-unmark</code></td></tr>
414<tr><td><code class="verbatim">U</code></td><td>Unmarks everything</td><td><code class="verbatim">org-agenda-bulk-unmark-all</code></td></tr>
415<tr><td><code class="verbatim">B</code></td><td>Asks for an action on every marked entry</td><td><code class="verbatim">org-agenda-bulk-action</code></td></tr>
416</tbody>
417</table>
418<p><code class="verbatim">B</code> offers <code class="verbatim">$</code> archive, <code class="verbatim">r</code> refile, <code class="verbatim">t</code> set a TODO state (typed; empty for none), <code class="verbatim">+</code> add a tag, <code class="verbatim">-</code> remove a tag, <code class="verbatim">s</code> schedule and <code class="verbatim">d</code> 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.</p>
419<h2 id="reminders">Reminders</h2>
420<p>Orgstar can post a notification before each timed entry, as <code class="verbatim">org-agenda-to-appt</code> hands entries to <code class="verbatim">appt</code>. 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.</p>
421<table>
422<thead>
423<tr><th>Setting</th><th>Default</th><th><code class="verbatim">config.toml</code></th></tr>
424</thead>
425<tbody>
426<tr><td>Notify before timed entries</td><td>on</td><td><code class="verbatim">reminders = true</code> under <code class="verbatim">[orgstar]</code></td></tr>
427<tr><td>Minutes of warning</td><td>12</td><td><code class="verbatim">appt-message-warning-time = 12</code></td></tr>
428</tbody>
429</table>
430<p>Both are in Settings ▸ Agenda. An entry's <code class="verbatim">APPT_WARNTIME</code> 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.</p>
431<p>The notification's title is the heading; its body is the time, the leader if any, and the category, such as <code class="verbatim">14:00 · Scheduled: · work</code>. Clicking it shows the entry in the main window.</p>
432<p>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.</p>
433<h2 id="the-board">The board</h2>
434<p>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 (<code class="verbatim">⇧⌘B</code>). It reads the same files as the agenda, including the subfolder setting.</p>
435<p>The toolbar has:</p>
436<ul>
437<li>a Table / Kanban switch;</li>
438<li>a match field, with the syntax of <a href="#tag-and-property-matches">Tag and property matches</a>. When empty, the board shows every entry with a TODO keyword;</li>
439<li>in table mode, a field of property names to show as extra columns, separated by commas (default <code class="verbatim">EFFORT</code>).</li>
440</ul>
441<p>These three choices are remembered by the app; they are not in <code class="verbatim">config.toml</code>.</p>
442<h3 id="table">Table</h3>
443<p>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 <code class="verbatim">NAME value</code>) and Open. Double-click a row to open the entry.</p>
444<h3 id="kanban">Kanban</h3>
445<p>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.</p>
446<p>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.</p>
447<p>The board is not available on iOS.</p>
448<h2 id="the-agenda-on-ios">The agenda on iOS</h2>
449<p>The Agenda tab shows the same views from the same files, using the settings in the synced <code class="verbatim">config.toml</code> and the views in <code class="verbatim">views.toml</code> (see <a href="14-ios.html">iOS</a>). Differences from the Mac:</p>
450<ul>
451<li>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 <code class="verbatim">/!</code> in the match or a <code class="verbatim">todo-match</code> view. Today, Earlier and Later are in the same menu.</li>
452<li>Pull down to refresh.</li>
453<li>The Filter button opens a sheet: type a filter as for <code class="verbatim">/</code>, or tap a tag or category to cycle between Keep, Leave out and no filter.</li>
454<li>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 <code class="verbatim">config.toml</code>, the file's own <code class="verbatim">#+TODO</code> lines, and those of its setup files, with unsaved edits in an open buffer included.</li>
455<li>Touch and hold an entry for TODO State…, Schedule…, Deadline…, Tags…, Priority…, Clock In, Refile… and Archive….</li>
456<li>There are no keyboard commands, time grid lines, habit graphs, log mode, bulk marks or custom prefix formats.</li>
457<li>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.</li>
458</ul>
459</main>
460<footer class="site">
461Orgstar is 0BSD-licensed. Source: <a href="https://gitbay.org/krz/orgstar">gitbay.org/krz/orgstar</a>.
462</footer>
463</body>
464</html>