Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Agenda Views

Org lets you keep tasks where they belong: a bug fix next to the notes about the bug, a meeting under the project it concerns, a birthday in a personal file. The price of this freedom is that the things you must act on are scattered across many headlines and many files. The agenda is the part of Org that gathers them again. It reads a set of files, selects entries by date, TODO state, tags, properties or text, and presents the result in a single buffer from which you can also edit the original entries.

This chapter starts with the files the agenda reads and the dispatcher that starts every view. It then walks through the built-in views, explains how each line is formatted and sorted, lists the commands you use inside the agenda buffer, and ends with custom views, export and batch use. The chapters on TODO Items, Tags, Properties and Column View and Dates and Times describe the data that the agenda displays; this chapter is about collecting and presenting it.

All output in this chapter was produced by Org 9.8.13 in Emacs batch mode, with the system clock set to Wednesday, 11 March 2026, 08:05. Lines such as Sched. 2x: or 1 d. ago: are relative to that moment, so they will look different if you run the same files on another day.

The sample files

This chapter uses 2 small agenda files. The first collects work projects. Each project is a level-1 headline with the tag project, and its children are the tasks:

* Website redesign                                                  :project:
** NEXT Draft the new navigation                                       :web:
SCHEDULED: <2026-03-11 Wed>
:PROPERTIES:
:Effort:   1:00
:END:
** TODO Review the color palette with design
DEADLINE: <2026-03-13 Fri>
** TODO Remove unused pages
** WAITING Final copy from marketing
* Quarterly report                                                  :project:
** TODO Collect sales figures
DEADLINE: <2026-03-10 Tue>
** TODO [#A] Write the summary
SCHEDULED: <2026-03-09 Mon>
* Conference talk                                                   :project:
** DONE Submit the abstract
CLOSED: [2026-03-10 Tue 16:10]
* Meetings
** Team standup
<2026-03-09 Mon 09:30-09:45 +1w>
** 1:1 with Maria
<2026-03-12 Thu 14:00>

The second file holds personal tasks, an appointment and a diary-style expression for an anniversary:

#+CATEGORY: home

* TODO Renew passport                                                :errand:
DEADLINE: <2026-03-20 Fri>
* TODO Call the plumber                                                :call:
SCHEDULED: <2026-03-10 Tue>
* NEXT Buy groceries                                                 :errand:
* Anniversaries
%%(org-anniversary 1990 3 12) Alex turns %d
* Dentist appointment
<2026-03-11 Wed 15:00-16:00>

The files are saved as work.org and home.org. The configuration below defines the TODO keywords for both files and registers them as agenda files:

(setq org-todo-keywords
      '((sequence "TODO(t)" "NEXT(n)" "WAITING(w)" "|" "DONE(d)" "CANCELED(c)")))
(setq org-agenda-files '("~/org/work.org" "~/org/home.org"))

From files to a view

Every agenda view is built in the same way. Org takes a list of files, scans them for entries that satisfy the view’s criteria, formats each entry as one line, sorts the lines, and inserts them into a read-only buffer named *Org Agenda*. Each line remembers where its entry lives, so commands in the agenda buffer can change the original file. Figure 13.1 shows this pipeline.

flowchart TD
  F["org-agenda-files"] -->|"files, or a restriction"| D["Dispatcher: C-c a"]
  D -->|"view type and match"| S["Select entries"]
  S -->|"skip functions, limits"| P["Format prefix, sort"]
  P -->|"one line per entry"| B["*Org Agenda* buffer"]
  B -->|"t, C-c C-s, :, ..."| O["Original Org entries"]
  O -->|"r or g rebuilds"| S

Figure 13.1: The agenda reads entries from your files, formats them as lines, and sends edits back to the files they came from.

The design has an important consequence: the agenda never stores data of its own. If you change a TODO state in the agenda, the change is written to the Org file; if you edit the Org file, the next rebuild of the agenda reflects it. There is only one copy of each piece of information.

Agenda files

The variable org-agenda-files lists the files the agenda reads. An element can be a file or a directory; a directory contributes every file with the .org extension that it contains. If the value is a single file name instead of a list, Org reads the list of agenda files from that file, one name per line.

You can edit the variable directly, but Org also provides commands that maintain it from inside an Org buffer:

KeyCommandEffect
C-c [org-agenda-file-to-frontAdd the current file to the front of the list, or move it there. With a prefix argument, add or move it to the end.
C-c ]org-remove-fileRemove the current file from the list.
C-' or C-,org-cycle-agenda-filesVisit the agenda files one after another.

The order of the list also matters a little: when the sorting rules described later consider 2 entries equal, the agenda keeps the order of their categories, which follows org-agenda-files.

Sometimes you want a view of only one file or one subtree, for example during a project meeting. The command C-c C-x < (org-agenda-set-restriction-lock) restricts all following agenda commands to the subtree at point, or to the whole file if you call it with C-u or before the first headline. The restriction stays in force until you remove it with C-c C-x > (org-agenda-remove-restriction-lock). For a single command, the dispatcher offers a lighter alternative, described next.

The dispatcher

All agenda views start from the agenda dispatcher, the command org-agenda. It shows a menu and waits for one more key that selects the view. The manual recommends binding it globally; C-c a is the conventional choice:

(global-set-key (kbd "C-c a") #'org-agenda)

The default entries of the dispatcher are:

KeyView
aThe weekly or daily agenda: a calendar of dated entries.
t / TThe global TODO list; T first asks for a TODO keyword.
m / MHeadlines matching a tags and properties expression; M keeps only TODO entries.
s / SA search view that selects entries by words or regular expressions; S keeps only TODO entries.
/A multi-occur search for a regular expression across the agenda files.
# / !The list of stuck projects; ! customizes how stuck projects are recognized.
<Restrict the next command to the current buffer, or to the narrowed part of it.
< <Restrict the next command to the active region, or to the current subtree.
>Remove a restriction.
eWrite the export files of custom commands (see “Exporting agenda views” below).
CCustomize org-agenda-custom-commands.
*Toggle sticky agenda buffers.

The restriction keys are prefixes: after < you still press the key of the view, so C-c a < t produces a TODO list of the current file only.

Custom commands, described later in this chapter, appear in the same menu. Org looks up the key among the custom commands before it checks the built-in keys, so a custom command bound to e or t hides the built-in command with that key. Choose letters that the dispatcher does not use.

By default Org keeps a single agenda buffer and rebuilds it every time you choose a view. If you switch between several expensive views, sticky agendas keep one buffer per view instead. You turn them on with * in the dispatcher, with org-toggle-sticky-agenda, or permanently with org-agenda-sticky. A sticky view is not refreshed automatically when you return to it; press r or g to rebuild it.

The weekly and daily agenda

The view under a (org-agenda-list) behaves like a page of a paper diary. For each day of the displayed span, it lists the entries that are relevant on that day:

  • entries with a plain active timestamp on that day, such as appointments;
  • entries scheduled on that day, and on today’s page, entries scheduled earlier that are still open;
  • deadlines on that day, and on today’s page, deadlines that are close or already past;
  • diary-style sexp entries that match the day;
  • with log mode turned on, entries closed or clocked on that day.

This is the week of the sample files:

Week-agenda (W11):
Monday      9 March 2026 W11
  work:        9:30-9:45  Team standup
  work:       Scheduled:  TODO [#A] Write the summary                :project::
Tuesday    10 March 2026
  home:       Scheduled:  TODO Call the plumber                          :call:
  work:       Deadline:   TODO Collect sales figures                 :project::
Wednesday  11 March 2026
               8:00...... ----------------
               8:05...... now - - - - - - - - - - - - - - - - - - - - - - - - -
              10:00...... ----------------
              12:00...... ----------------
              14:00...... ----------------
  home:       15:00-16:00 Dentist appointment
              16:00...... ----------------
              18:00...... ----------------
              20:00...... ----------------
  work:       Sched. 2x:  TODO [#A] Write the summary                :project::
  home:       Sched. 1x:  TODO Call the plumber                          :call:
  work:       Scheduled:  NEXT Draft the new navigation          :project::web:
  work:        1 d. ago:  TODO Collect sales figures                 :project::
  work:       In   2 d.:  TODO Review the color palette with design  :project::
  home:       In   9 d.:  TODO Renew passport                          :errand:
Thursday   12 March 2026
  work:       14:00...... 1:1 with Maria
  home:       Alex turns 36
Friday     13 March 2026
  work:       Deadline:   TODO Review the color palette with design  :project::
Saturday   14 March 2026
Sunday     15 March 2026

Several details in this output deserve explanation, because together they describe how Org thinks about time.

  • Today is special. Overdue and upcoming items appear only on today’s page. Sched. 2x: means that the summary was scheduled 2 days ago and is still open; 1 d. ago: marks a deadline that passed yesterday; In 2 d.: warns about a deadline 2 days ahead. The warning period defaults to org-deadline-warning-days, which is 14 days, so the passport deadline 9 days away already appears.
  • Items stay until they are done. A scheduled task that you do not finish keeps appearing on today’s page, every day, until you close it. This is why the summary appears on Monday (where it was scheduled) and again on Wednesday, with a growing counter.
  • The time grid frames the day. Today’s page shows timed entries between grid lines at 8:00, 10:00 and so on, plus a now marker at the current time. Entries without a time follow below the grid.
  • Repeaters produce one occurrence per period. The standup has the repeater +1w, so it appears on Monday of every week, without any copy in the file.
  • Diary expressions are evaluated. The %%(org-anniversary 1990 3 12) line produces Alex turns 36 on 12 March, with %d replaced by the number of years.

For more detail on deadlines, scheduling, warning periods and repeaters, see Dates and Times.

Choosing the span and the start day

The variable org-agenda-span sets the default length of the view. It accepts a number of days or one of the symbols day, week, month and year; the default is week. Weekly views start on the day given by org-agenda-start-on-weekday, which is 1 (Monday) by default; set it to nil to start on the current day. The variable org-agenda-start-day moves the start, either to a fixed date such as "2026-03-12" or relative to today, such as "+10d". In weekly and two-week views, org-agenda-start-on-weekday takes precedence over it.

A single-day view of 11 March shows only the part of the week that concerns today:

Day-agenda (W11):
Wednesday  11 March 2026
               8:00...... ----------------
               8:05...... now - - - - - - - - - - - - - - - - - - - - - - - - -
              10:00...... ----------------
              12:00...... ----------------
              14:00...... ----------------
  home:       15:00-16:00 Dentist appointment
              16:00...... ----------------
              18:00...... ----------------
              20:00...... ----------------
  work:       Sched. 2x:  TODO [#A] Write the summary                :project::
  home:       Sched. 1x:  TODO Call the plumber                          :call:
  work:       Scheduled:  NEXT Draft the new navigation          :project::web:
  work:        1 d. ago:  TODO Collect sales figures                 :project::
  work:       In   2 d.:  TODO Review the color palette with design  :project::
  home:       In   9 d.:  TODO Renew passport                          :errand:

The same single-day view for Thursday, 12 March (produced with org-agenda-start-day set to "2026-03-12") contains no overdue items at all, because they belong to today:

Day-agenda (W11):
Thursday   12 March 2026
               8:00...... ----------------
              10:00...... ----------------
              12:00...... ----------------
  work:       14:00...... 1:1 with Maria
              14:00...... ----------------
              16:00...... ----------------
              18:00...... ----------------
              20:00...... ----------------
  home:       Alex turns 36

The time grid

The grid is controlled by 2 variables. org-agenda-use-time-grid turns it on or off, and org-agenda-time-grid describes when it appears and which times it marks. Its default conditions are daily, today and require-timed: the grid appears in a single-day view (as in the Thursday example above) and on today’s page in a longer view, but only when the day has at least one timed entry. The default grid lines are at 8:00, 10:00, 12:00, 14:00, 16:00, 18:00 and 20:00. The now line uses the string in org-agenda-current-time-string. In the agenda buffer, G toggles the grid for the current view.

Org finds the time of an entry in its timestamp (<2026-03-11 Wed 15:00-16:00>), in its scheduled or deadline timestamp, or in the headline text itself, where something like 12:45 or 8:30-1pm is recognized. The last behavior is controlled by org-agenda-search-headline-for-time.

Done items, the diary and log mode

A few variables decide whether finished work remains visible. org-agenda-skip-scheduled-if-done and org-agenda-skip-deadline-if-done hide DONE entries on the day they were scheduled or due; both are nil by default, so a finished task stays on its original date as a record. Warnings about past or upcoming dates disappear in any case once the task is done.

If you also keep an Emacs diary file, set org-agenda-include-diary to t and its entries appear in the agenda. For anniversaries and holidays, the alternative used in the sample file is often simpler: write a diary-style expression such as %%(org-anniversary 1990 3 12) directly in an Org file. The expression must start at the beginning of the line.

Log mode adds what you have already done. Press l in the agenda (or set org-agenda-start-with-log-mode) and the agenda also lists entries closed on each day and entries with clocked time, according to org-agenda-log-mode-items. With log mode on, the Tuesday of the sample week gains a line for the abstract that was closed at 16:10:

Tuesday    10 March 2026
  work:       16:10...... Closed:     DONE Submit the abstract       :project::
  home:       Scheduled:  TODO Call the plumber                          :call:
  work:       Deadline:   TODO Collect sales figures                 :project::

C-u l also shows state changes, and C-u C-u l shows only the logged entries. Recording state changes is the subject of TODO Items; recording clocked time is the subject of Clocking, Effort and Timers.

The global TODO list

The weekly agenda answers “what is due when?”. The global TODO list (t, org-todo-list) answers “what is still open?”. It lists every entry whose TODO keyword is not a DONE state, regardless of dates:

Global list of TODO items of type: ALL
Press ‘N r’ (e.g. ‘0 r’) to search again: (0)[ALL] (1)CANCELED (2)DONE
                      (3)WAITING (4)NEXT (5)TODO
  work:       TODO [#A] Write the summary                            :project::
  work:       NEXT Draft the new navigation                      :project::web:
  work:       TODO Review the color palette with design              :project::
  work:       TODO Remove unused pages                               :project::
  work:       WAITING Final copy from marketing                      :project::
  work:       TODO Collect sales figures                             :project::
  home:       TODO Renew passport                                      :errand:
  home:       TODO Call the plumber                                      :call:
  home:       NEXT Buy groceries                                       :errand:

The header explains how to narrow the list to one keyword: 4 r rebuilds it with only NEXT entries. T (or C-u t) asks for the keyword first, and accepts several keywords separated by |.

A long-lived TODO list quickly becomes too long to read. 2 groups of variables keep it focused:

  • org-agenda-todo-ignore-scheduled, org-agenda-todo-ignore-deadlines, org-agenda-todo-ignore-timestamp and org-agenda-todo-ignore-with-date remove entries that already have a date. The reasoning is that a dated task is visible in the weekly agenda, so it need not appear here as well.
  • org-agenda-todo-list-sublevels, which is t by default, decides whether TODO entries below another TODO entry are listed. Set it to nil to see only the top-level task of each hierarchy.

Match views: tags, properties and TODO states

A match view (m, org-tags-view) selects headlines with a match string, a small query language over tags, properties and TODO keywords. The full grammar is described in Tags, Properties and Column View; a few examples are enough to show what the agenda does with it.

The string errand|call selects headlines tagged errand or call:

Headlines with TAGS match: errand|call
Press ‘C-u r’ to search again
  home:       TODO Renew passport                                      :errand:
  home:       TODO Call the plumber                                      :call:
  home:       NEXT Buy groceries                                       :errand:

The part after a slash restricts the TODO keyword. project/NEXT|WAITING selects entries tagged project whose keyword is NEXT or WAITING:

Headlines with TAGS match: project/NEXT|WAITING
Press ‘C-u r’ to search again
  work:       NEXT Draft the new navigation                      :project::web:
  work:       WAITING Final copy from marketing                      :project::

None of these tasks carries the tag project itself; they inherit it from their parent headline. The agenda shows this in the tag column: inherited tags come first, and a double colon separates them from the entry’s own tags, so :project::web: means “inherited project, local web”. If you prefer to hide inherited tags, set org-agenda-show-inherited-tags to nil; T in the agenda still shows all tags of the entry at point.

M (or org-tags-view with a prefix argument) works like m but only considers headlines with a TODO keyword that is not done.

Search view

The search view (s, org-search-view) finds entries by their text, including the body below the headline. It is the right tool for notes that have no keyword or tag to select them by.

Without a leading +, the whole string is searched as a phrase, so computer equipment matches the 2 words even when they are separated by a line break. With a leading +, the string becomes a Boolean query: words prefixed with + must occur, words prefixed with - must not, and regular expressions are written in braces. For example, +invoice -paid {20[0-9][0-9]} finds entries that mention an invoice and a year but do not mention paid.

Inside a search view, 4 keys refine the query without retyping it:

KeyAdds
[a word that must occur
]a word that must not occur
{a regular expression that must match
}a regular expression that must not match

The search view reads the agenda files and also the files in org-agenda-text-search-extra-files. This makes it useful for reference notes that you never want in your daily agenda: list them there instead of in org-agenda-files. A stored search for the word color (defined later as the custom command n) returns the one entry that mentions it:

Entries mentioning color
  work:       TODO Review the color palette with design              :project::

Stuck projects

Task-management methods such as GTD (Getting Things Done) ask you to make sure that every project has a defined next step. A stuck project is one without such a step: it will never appear in your lists of things to do, so it silently stops moving. The view under # (org-agenda-list-stuck-projects) finds these projects.

Org cannot know what a “project” or a “next step” means in your files, so you describe it in org-stuck-projects. The value has 4 elements:

  1. a match string that identifies projects;
  2. a list of TODO keywords that count as a next step;
  3. a list of tags that count as a next step;
  4. a regular expression that, if found anywhere in the project, marks it as not stuck.

A project is reported as stuck when its subtree contains none of these markers. The default value assumes that projects are level-2 headlines, which rarely matches anyone’s files, so you almost always have to set the variable yourself. A first attempt for the sample files could look like this:

(setq org-stuck-projects
      '("+project/-DONE" ("NEXT" "TODO") nil ""))

The result shows a common mistake:

List of stuck projects:
  work:       WAITING Final copy from marketing                      :project::
  work:       Conference talk                                         :project:

Conference talk is correct: its only task is done. The WAITING task, however, is not a project. It appears because the match string +project also matches headlines that inherit the tag, and the WAITING entry has no NEXT or TODO below it. There are 2 ways to fix the definition. You can limit the match to level-1 headlines:

(setq org-stuck-projects
      '("+project+LEVEL=1/-DONE" ("NEXT" "TODO") nil ""))

Or you can stop the project tag from being inherited at all, which also cleans up the tag column of every view:

(setq org-tags-exclude-from-inheritance '("project"))

With either change, only Conference talk remains. The Putting It Together chapter uses a stricter definition, where only NEXT counts as a next step.

How lines are formatted and sorted

Categories

Each agenda line starts with a category, a short label for the area an entry belongs to. By default it is the file name without the extension, which is why the sample shows work:. A #+CATEGORY: keyword sets it for a whole file (as in home.org), and a CATEGORY property sets it for one subtree. Keep categories short: the default format reserves 12 columns for them. The variable org-agenda-category-icon-alist can add an icon per category.

The prefix

The text before the headline is the prefix, and its format is set by org-agenda-prefix-format. The variable holds one format string per kind of view:

View typeDefault format
agenda" %i %-12:c%?-12t% s"
todo" %i %-12:c"
tags" %i %-12:c"
search" %i %-12:c"

The most useful codes are:

CodeMeaning
%cthe category
%ithe category icon
%tthe time of day, if any
%sscheduling or deadline information, such as Sched. 2x:
%ethe effort estimate
%Tthe last local tag
%lthe level, as spaces
%bbreadcrumbs: the titles of the parent headlines

Between % and the letter you can give a width, as in printf. A colon after the width (%-12:c) appends a colon to non-empty values, and %?-12t produces the 12 columns only when the time is present. Figure 13.2 labels the parts of one line from the weekly agenda.

Figure 13.2: Every agenda line is a formatted prefix followed by a cleaned-up headline, so changing the prefix format changes what each line tells you.

Changing the prefix is a cheap way to make a view more informative. The custom command p, defined later in this chapter, uses " %-6e %b": the effort estimate followed by the path of parent headlines.

Global list of TODO items of type: ALL
Press ‘N r’ (e.g. ‘0 r’) to search again: (0)[ALL] (1)CANCELED (2)DONE
                      (3)WAITING (4)NEXT (5)TODO
         Quarterly report->TODO [#A] Write the summary               :project::
  1:00   Website redesign->NEXT Draft the new navigation         :project::web:
         Website redesign->TODO Review the color palette with design :project::
         Website redesign->TODO Remove unused pages                  :project::
         Website redesign->WAITING Final copy from marketing         :project::
         Quarterly report->TODO Collect sales figures                :project::
         TODO Renew passport                                           :errand:
         TODO Call the plumber                                           :call:
         NEXT Buy groceries                                            :errand:

Tags are aligned according to org-agenda-tags-column, which by default aligns them to the right edge of the window. org-agenda-remove-tags removes them from the lines completely.

Sorting

Lines are sorted before they are inserted, and the rules depend on the view. The variable org-agenda-sorting-strategy holds a list of criteria per view type. Its default is:

((agenda habit-down time-up urgency-down category-keep)
 (todo   urgency-down category-keep)
 (tags   urgency-down category-keep)
 (search category-keep))

Read the agenda entry from left to right: habits come last, timed entries are sorted by time, then entries are sorted by urgency, and entries of equal urgency keep the order of their categories.

Urgency starts from the priority. With the default priority range, C, B and A are worth 0, 1000 and 2000, and an entry without a cookie counts as the default priority B. The functions that collect agenda entries (in org-agenda.el) then adjust the value. A scheduled entry gets 99 points plus the number of days since its scheduled date; a deadline on today’s page gets the number of days it is overdue, which is negative for deadlines still ahead. For today’s page of the sample week this gives:

EntryCalculationUrgency
Write the summary2000 + 99 + 2 days late2101
Call the plumber1000 + 99 + 1 day late1100
Draft the new navigation1000 + 99 + 01099
Collect sales figures1000 + 1 day overdue1001
Review the color palette1000 - 2 days ahead998
Renew passport1000 - 9 days ahead991

This is exactly the order of the untimed lines on Wednesday, even though it mixes the categories work and home. The practical result is that late scheduled work rises above deadlines that are not yet due, and an A priority outweighs any realistic delay. The CSV output at the end of this chapter shows only the priority part (2000 and 1000), not the adjusted urgency.

Other sorting criteria include priority-down, effort-up, alpha-up, tag-up and todo-state-up; the docstring of the variable lists them all.

Working in the agenda buffer

The agenda buffer is read-only, but it is not passive. Almost every command that you use on a headline in an Org buffer has a counterpart in the agenda that acts on the entry behind the current line. This is called remote editing.

Moving and visiting

KeyCommandEffect
n / porg-agenda-next-line / org-agenda-previous-lineMove between lines.
SPCorg-agenda-show-and-scroll-upShow the entry in another window, keep point in the agenda.
TABorg-agenda-gotoGo to the entry in another window.
RETorg-agenda-switch-toGo to the entry and delete other windows.
Forg-agenda-follow-modeToggle Follow mode, which shows each entry as you move.
Lorg-agenda-recenterShow the entry and recenter that window.
C-c C-oorg-agenda-open-linkFollow a link in the entry.
C-c C-x borg-agenda-tree-to-indirect-bufferShow the entry’s subtree in an indirect buffer.

Changing what is displayed

KeyCommandEffect
d / worg-agenda-day-view / org-agenda-week-viewSwitch to a day or week span.
v m / v yorg-agenda-month-view / org-agenda-year-viewSwitch to a month or year span.
f / borg-agenda-later / org-agenda-earlierMove forward or backward by one span.
.org-agenda-goto-todayReturn to today.
jorg-agenda-goto-dateJump to a date.
r / gorg-agenda-redoRebuild the view from the files.
lorg-agenda-log-modeToggle log mode.
v aorg-agenda-archives-modeInclude archived trees; v A also includes archive files.
Rorg-agenda-clockreport-modeShow a clock table for the displayed span.
Eorg-agenda-entry-text-modeShow the first lines of each entry’s body.
Gorg-agenda-toggle-time-gridToggle the time grid.
Dorg-agenda-toggle-diaryToggle diary entries.
AAppend another view to the current one.
sorg-save-all-org-buffersSave all Org buffers.

Month and year views are slow to build, so v m and v y do not become the default for later refreshes, while d and w do.

Editing entries remotely

KeyCommandEffect on the original entry
torg-agenda-todoChange the TODO state.
,org-agenda-prioritySet the priority; + and - raise or lower it.
:org-agenda-set-tagsSet tags.
eorg-agenda-set-effortSet the effort estimate.
zorg-agenda-add-noteAdd a note, filed where state-change notes go.
C-c C-sorg-agenda-scheduleSchedule; with a prefix argument, remove the schedule.
C-c C-dorg-agenda-deadlineSet a deadline; with a prefix argument, remove it.
S-RIGHT / S-LEFTorg-agenda-do-date-later / org-agenda-do-date-earlierMove the date by one day.
>org-agenda-date-promptChange the date through the date prompt.
I / O / Xorg-agenda-clock-in / org-agenda-clock-out / org-agenda-clock-cancelStart, stop or cancel the clock.
C-c C-worg-agenda-refileRefile the entry.
$org-agenda-archiveArchive the subtree.
C-korg-agenda-killDelete the entry and its subtree.
korg-agenda-captureCapture, using the date at point as the default date.
C-_org-agenda-undoUndo the last remote edit, in the agenda and in the file.

Some of these commands change the file without redrawing the line. After moving a date with S-RIGHT, for example, the line stays where it is until you press r or g. This is deliberate: rebuilding the whole view after each small edit would be slow and would move point.

A typical morning pass over today’s page therefore looks like this: move with n, press t to mark finished tasks, S-RIGHT to postpone what will not happen today, C-c C-w to move stray items to their project, and finally g to see the cleaned-up day.

Acting on many entries at once

When the same change applies to several lines, mark them first and then act on all of them. m marks the line at point, u unmarks it, * marks every visible line, U removes all marks, and % marks lines matching a regular expression. B (org-agenda-bulk-action) then asks for an action:

Key after BAction
tChange the TODO state of all marked entries.
+ / -Add or remove a tag.
s / dSchedule, or set a deadline. At the schedule prompt, ++2w shifts every existing date by 2 weeks.
rRefile all marked entries to one target.
$ / AArchive, or move to the archive sibling.
SScatter the entries randomly over the next N days.
fApply a function to every marked entry.

Filters and limits

A view defines which entries are collected. Filters then hide some of the collected lines without rebuilding the view, which makes them fast enough to use interactively:

KeyCommandFilters by
/org-agenda-filterA combined expression, such as +work-call+<0:30
\org-agenda-filter-by-tagA tag
<org-agenda-filter-by-categoryThe category of the line at point
=org-agenda-filter-by-regexpA regular expression
_org-agenda-filter-by-effortThe effort estimate
^org-agenda-filter-by-top-headlineThe top-level headline of the line at point
|org-agenda-filter-remove-allRemove all filters

A single C-u before a filter command inverts it, and C-u C-u adds the new condition to those already active. The combined filter / accepts categories, tags, effort comparisons and regular expressions in one string; elements prefixed with - exclude lines.

Limits work at an earlier stage: they restrict which entries are collected at all. The variables org-agenda-max-entries, org-agenda-max-todos, org-agenda-max-tags and org-agenda-max-effort cap the number of entries, TODO entries, tagged entries and the total effort in minutes. They are most useful as local settings of a custom command; a list of “the next 5 tasks” is one example. The key ~ (org-agenda-limit-interactively) applies a temporary limit to the current view.

Leaving the agenda

q (org-agenda-quit) removes the agenda buffer. x (org-agenda-exit) also kills the buffers that Org opened only to build the agenda, while buffers you opened yourself stay. Where the agenda window appears in the first place is decided by org-agenda-window-setup, and org-agenda-restore-windows-after-quit decides whether the previous window layout comes back when you leave.

Custom agenda views

Built-in views take a query every time. Once you notice that you type the same match string every day, or that you always look at 2 views one after the other, it is time for a custom agenda command. Custom commands are defined in org-agenda-custom-commands and appear in the dispatcher next to the built-in ones. They serve 2 purposes: storing searches under a key, and combining several views into one buffer.

Figure 13.3 shows the parts of one entry in the variable.

Figure 13.3: A custom command pairs a dispatcher key with one or more blocks, and each layer of the entry can carry its own variable settings.

The simplest entry has a key, a description, a view type, a match string and an optional list of settings. The following configuration defines 5 commands that are used in this chapter:

(setq org-agenda-custom-commands
      '(("c" "Errands and calls" tags-todo "errand|call"
         ((org-agenda-prefix-format "  [ ] ")
          (org-agenda-remove-tags t)))
        ("u" "Unplanned project tasks" tags-todo "project"
         ((org-agenda-skip-function
           '(org-agenda-skip-entry-if 'scheduled 'deadline))
          (org-agenda-overriding-header "Project tasks without a date")))
        ("p" "Tasks with breadcrumbs" todo ""
         ((org-agenda-prefix-format "  %-6e %b")))
        ("n" "Notes about colors" search "color"
         ((org-agenda-overriding-header "Entries mentioning color")))
        ("X" "Week as text" agenda ""
         ((org-agenda-use-time-grid nil))
         ("~/agenda/week.txt"))))

The available view types are:

TypeEquivalent built-in view
agendathe weekly or daily agenda (a)
agenda*the same, limited to entries with a time of day (appointments)
todothe TODO list for given keywords (T)
alltodothe global TODO list (t)
tagsa match view (m)
tags-todoa match view of TODO entries (M)
searcha search view (s)
stuckthe stuck projects list (#)
todo-tree, tags-tree, occur-treea sparse tree in the current buffer instead of an agenda buffer

The settings list binds variables while the view is built, so any agenda option can be changed for one command. The command c turns the errand list into a checklist that fits on a piece of paper:

Headlines with TAGS match: errand|call
Press ‘C-u r’ to search again
  [ ] TODO Renew passport
  [ ] TODO Call the plumber
  [ ] NEXT Buy groceries

If you define many commands, group them under prefix keys. An entry of the form ("h" . "Home searches") describes the prefix, and commands with keys such as "ha" and "hb" are then reached with C-c a h a and C-c a h b.

Block agendas

A block agenda puts the results of several views into one buffer, one block after another. Instead of a single type and match, the entry contains a list of blocks, each of the form (type match settings):

(add-to-list 'org-agenda-custom-commands
             '("d" "Daily overview"
               ((agenda "" ((org-agenda-span 'day)))
                (todo "NEXT"
                      ((org-agenda-overriding-header "Next actions")))
                (todo "WAITING"
                      ((org-agenda-overriding-header "Waiting for others"))))
               ((org-agenda-block-separator ?-))))

This command answers the 3 questions of a working day in one screen: what is fixed today, what can I do next, and what am I waiting for.

Day-agenda (W11):
Wednesday  11 March 2026
               8:00...... ----------------
               8:05...... now - - - - - - - - - - - - - - - - - - - - - - - - -
              10:00...... ----------------
              12:00...... ----------------
              14:00...... ----------------
  home:       15:00-16:00 Dentist appointment
              16:00...... ----------------
              18:00...... ----------------
              20:00...... ----------------
  work:       Sched. 2x:  TODO [#A] Write the summary                :project::
  home:       Sched. 1x:  TODO Call the plumber                          :call:
  work:       Scheduled:  NEXT Draft the new navigation          :project::web:
  work:        1 d. ago:  TODO Collect sales figures                 :project::
  work:       In   2 d.:  TODO Review the color palette with design  :project::
  home:       In   9 d.:  TODO Renew passport                          :errand:

-------------------------------------------------------------------------------
Next actions
  work:       NEXT Draft the new navigation                      :project::web:
  home:       NEXT Buy groceries                                       :errand:

-------------------------------------------------------------------------------
Waiting for others
  work:       WAITING Final copy from marketing                      :project::

Notice the 2 places where settings appear. Settings inside a block apply only to that block: the span of 1 day affects only the agenda block. Settings after the list of blocks apply to every block: here org-agenda-block-separator replaces the default separator line (drawn with ─, or with = where that character cannot be displayed) with dashes. The variable org-agenda-overriding-header replaces the default header of a block with your own text, which matters more in a block agenda than anywhere else, because the default headers (“Global list of TODO items of type: NEXT”) do not say why a block is there.

Some options are read only when the agenda buffer is first set up, not when each block is built. org-agenda-start-with-log-mode is one of them: in Org 9.8.13 it takes effect when placed in the shared settings of a block agenda, and has no effect inside a single block. When an option seems to be ignored in a block, try the shared settings.

Skip functions

Match strings select entries by tags, properties and keywords. Sometimes the condition you need is different, for example “project tasks that have no date yet”. A skip function handles such cases: Org calls it at each candidate entry, and if it returns a buffer position, the entry is skipped and the search continues from that position; if it returns nil, the entry is kept.

You set a skip function with org-agenda-skip-function in the settings of a command. Org provides 2 ready-made helpers. org-agenda-skip-entry-if skips the current entry when a condition holds; org-agenda-skip-subtree-if skips the whole subtree. The conditions include scheduled, notscheduled, deadline, notdeadline, timestamp, nottimestamp, regexp, notregexp, todo and nottodo. The command u from the configuration above combines a match string with a skip function:

("u" "Unplanned project tasks" tags-todo "project"
 ((org-agenda-skip-function
   '(org-agenda-skip-entry-if 'scheduled 'deadline))
  (org-agenda-overriding-header "Project tasks without a date")))

It returns the project tasks that are neither scheduled nor have a deadline, which are the tasks most likely to be forgotten:

Project tasks without a date
  work:       TODO Remove unused pages                               :project::
  work:       WAITING Final copy from marketing                      :project::

When no helper fits, write a function. It runs with point at the beginning of the candidate entry and must return nil to keep it, or a position to continue from. This function keeps only entries whose Effort property is set:

(defun my-agenda-skip-without-effort ()
  "Skip entries that have no Effort property."
  (unless (org-entry-get nil "Effort")
    (or (outline-next-heading) (point-max))))

Use it in a command like any other skip function. Over the sample files, a TODO list with this skip function keeps only the one task that has an estimate:

("f" "Estimated tasks" alltodo ""
 ((org-agenda-skip-function #'my-agenda-skip-without-effort)))
Global list of TODO items of type: ALL
Press ‘N r’ (e.g. ‘0 r’) to search again: (0)[ALL] (1)CANCELED (2)DONE
                      (3)WAITING (4)NEXT (5)TODO
  work:       NEXT Draft the new navigation                      :project::web:

The variable org-agenda-skip-function-global applies a skip function to every view, which is occasionally useful for excluding a whole class of entries everywhere.

Commands that depend on context

org-agenda-custom-commands-contexts makes a command available only in certain situations, for example only when the current buffer is in a particular major mode. Each entry names a command key and one or more conditions:

(setq org-agenda-custom-commands-contexts
      '(("c" (in-mode . "message-mode"))))

With this setting, c appears in the dispatcher only when you start it from a message-mode buffer. The docstring of the variable lists the other conditions, such as in-file, in-buffer and their negations not-in-mode, not-in-file and not-in-buffer.

Exporting agenda views

An agenda view can be written to a file, which is useful for printing a week on paper, for sharing a status list, or for feeding another program.

Writing the current view

C-x C-w (org-agenda-write) writes the current agenda buffer to a file. The extension of the file name selects the format:

ExtensionResult
.htmlHTML, which requires the htmlize package
.psPostScript
.pdfPDF, converted from PostScript by the external program ps2pdf
.icsiCalendar, for the entries shown in the view
.organ Org file containing the subtrees of the listed entries
any otherplain text

Settings in org-agenda-exporter-settings are applied while the file is written.

Views with permanent output files

If you export the same views regularly, attach file names to the custom commands. The file list is the last element of an entry, after the settings, as in the command X above. Running a command interactively does not create its files; instead, e in the dispatcher (org-store-agenda-views) writes the files of every command that has them. This is what the command X produces:

Week-agenda (W11):
Monday      9 March 2026 W11
  work:        9:30-9:45  Team standup
  work:       Scheduled:  TODO [#A] Write the summary                :project::
Tuesday    10 March 2026
  home:       Scheduled:  TODO Call the plumber                          :call:
  work:       Deadline:   TODO Collect sales figures                 :project::
Wednesday  11 March 2026
  home:       15:00-16:00 Dentist appointment
  work:       Sched. 2x:  TODO [#A] Write the summary                :project::
  home:       Sched. 1x:  TODO Call the plumber                          :call:
  work:       Scheduled:  NEXT Draft the new navigation          :project::web:
  work:        1 d. ago:  TODO Collect sales figures                 :project::
  work:       In   2 d.:  TODO Review the color palette with design  :project::
  home:       In   9 d.:  TODO Renew passport                          :errand:
Thursday   12 March 2026
  work:       14:00...... 1:1 with Maria
  home:       Alex turns 36
Friday     13 March 2026
  work:       Deadline:   TODO Review the color palette with design  :project::
Saturday   14 March 2026
Sunday     15 March 2026

The setting org-agenda-use-time-grid is nil in this command because grid lines are noise on paper.

The agenda from the command line

Because Emacs can run without a display, agenda views can be produced by scripts and scheduled jobs. Org offers 3 entry points for batch use:

  • org-batch-store-agenda-views writes the files of all custom commands that have them, like e in the dispatcher.
  • org-batch-agenda prints a view to standard output. Its first argument is a one-letter command key, or a longer match string for a match view.
  • org-batch-agenda-csv prints the same view as comma-separated values for further processing.

All 3 accept pairs of variable names and values that are bound while the view is built. The examples in this chapter were produced with commands of this shape:

emacs -Q --batch -l setup.el \
  --eval '(org-batch-agenda "a" org-agenda-span (quote day))'

where setup.el contained the configuration shown at the beginning of the chapter. The CSV variant of the same day, with the time grid turned off, looks like this:

home,Dentist appointment,timestamp,,,2026-03-11,15:00-16:00,,,1000,2026-03-11
work,Write the summary,past-scheduled,TODO,project,2026-03-09,,Sched. 2x:,A,2000,2026-03-11
home,Call the plumber,past-scheduled,TODO,call,2026-03-10,,Sched. 1x:,,1000,2026-03-11
work,Draft the new navigation,scheduled,NEXT,project:web,2026-03-11,,Scheduled:,,1000,2026-03-11
work,Collect sales figures,deadline,TODO,project,2026-03-10,,1 d. ago:,,1000,2026-03-11
work,Review the color palette with design,upcoming-deadline,TODO,project,2026-03-11,,In   2 d.:,,1000,2026-03-11
home,Renew passport,upcoming-deadline,TODO,errand,2026-03-11,,In   9 d.:,,1000,2026-03-11

The fields are, in order: category, headline, type of entry, TODO keyword, tags, date, time, extra planning text, priority letter, numeric priority, and the agenda day on which the line appears. The type field is the most informative: it distinguishes timestamp, scheduled, past-scheduled, deadline, upcoming-deadline, closed and other cases that the text view shows only through the prefix.

Column view in the agenda

Column view, described in Tags, Properties and Column View, shows the properties of entries as a table. C-c C-x C-c (org-agenda-columns) turns it on in the agenda as well, which is useful for comparing effort estimates with clocked time across all the tasks of a day or a search.

Because agenda entries come from different files, Org must decide which column format to use. It takes the first of these that is set: org-overriding-columns-format (meant to be set in the settings of a custom command), org-columns-default-format-for-agenda, the format of the first entry in the view, and finally org-columns-default-format.

Keep 2 cautions in mind. Summary values in agenda column view add up the lines that are displayed, and an entry may appear twice (as scheduled and as a deadline, or as a parent and its child), so sums can count some values twice. And the special property CLOCKSUM always shows the total time clocked on an entry, not the time within the displayed span; use CLOCKSUM_T for today’s time, or clock report mode (R) for the span.

Keeping the agenda fast

The agenda reads every agenda file each time it is built, so its speed depends on the size of those files. If building a view becomes slow, try these settings before anything else:

(setq org-agenda-inhibit-startup t)          ; do not apply startup visibility
(setq org-agenda-dim-blocked-tasks nil)      ; skip the blocking check
(setq org-agenda-use-tag-inheritance nil)    ; no inherited tags in views
(setq org-agenda-ignore-properties '(stats)) ; do not update statistics cookies

Each of these settings has a cost. With org-agenda-use-tag-inheritance set to nil, for example, the weekly agenda, the TODO list and the search view no longer know about inherited tags, so a tag filter for project misses the tasks inside a project. (Match views are not affected; they follow org-use-tag-inheritance.) Apply them selectively, in the settings of the custom commands that need speed, rather than globally. Keeping the agenda files small helps as well: archive finished subtrees regularly, as described in Capture, Refile, Archive and Attachments.

Summary

  • The agenda collects entries from org-agenda-files and shows them as lines that point back to the original headlines.
  • The dispatcher (C-c a) offers a calendar view (a), a TODO list (t), match views (m, M), a text search (s) and stuck projects (#).
  • Overdue and upcoming items appear on today’s page only, and stay there until they are done.
  • Remote editing keys such as t, C-c C-s and C-c C-w change the files directly; r or g rebuild the view.
  • Custom commands store searches, combine views into block agendas, adjust options per view, and attach output files for printing and scripts.

Further reading