The purpose of the weekly/daily agenda is to act like a page of a paper agenda, showing all the tasks for the current week or day.

M-x org-agenda a (org-agenda-list)

Compile an agenda for the current week from a list of Org files. The agenda shows the entries for each day. With a numeric prefix

argument³³—like C-u 2 1 M-x org-agenda a—you may set the number of days to be displayed.

The default number of days displayed in the agenda is set by the variable org-agenda-span. This variable can be set to any number of days you want to see by default in the agenda, or to a span name, such a day, week, month or year. For weekly agendas, the default is to start on the previous Monday (see org-agenda-start-on-weekday). You can also set the start date using a date shift: (setq org-agenda-start-day "+10d") starts the agenda ten days from today in the future. org-agenda-start-on-weekday takes precedence over org-agenda-start-day in weekly and bi-weekly agendas.

Remote editing from the agenda buffer means, for example, that you can change the dates of deadlines and appointments from the agenda buffer. The commands available in the Agenda buffer are listed in Commands in the Agenda Buffer.

(setq org-agenda-include-diary t)

* Holidays
  :PROPERTIES:
  :CATEGORY: Holiday
  :END:
%%(org-calendar-holiday)   ; special function for holiday names

* Birthdays
  :PROPERTIES:
  :CATEGORY: Ann
  :END:
%%(org-anniversary 1956  5 14) Arthur Dent is %d years old
%%(org-anniversary 1869 10  2) Mahatma Gandhi would be %d years old

* Anniversaries
  :PROPERTIES:
  :CATEGORY: Anniv
  :END:
%%(org-bbdb-anniversaries)

1973-06-22
06-22
1955-08-02 wedding
2008-04-14 %s released version 6.01 of Org mode, %d years ago

* Anniversaries
  :PROPERTIES:
  :CATEGORY: Anniv
  :END:
%%(org-bbdb-anniversaries-future 3)

The global TODO list contains all unfinished TODO items formatted and collected into a single place.

M-x org-agenda t (org-todo-list)

Show the global TODO list. This collects the TODO items from all agenda files (see Agenda Views) into a single buffer. By default, this lists items with a state that is not a DONE state. The buffer is in Agenda mode, so there are commands to examine and manipulate the TODO entries directly from that buffer (see Commands in the Agenda Buffer).

M-x org-agenda T (org-todo-list)

Like the above, but allows selection of a specific TODO keyword. You can also do this by specifying a prefix argument to t. You are prompted for a keyword, and you may also specify several keywords by separating them with | as the boolean OR operator. With a numeric prefix, the Nth keyword in org-todo-keywords is selected.

The r key in the agenda buffer regenerates it, and you can give a prefix argument to this command to change the selected TODO keyword, for example 3 r. If you often need a search for a specific keyword, define a custom command for it (see The Agenda Dispatcher).

Matching specific TODO keywords can also be done as part of a tags search (see Tag Searches).

Remote editing of TODO items means that you can change the state of a TODO entry with a single key press. The commands available in the TODO list are described in Commands in the Agenda Buffer.

Normally the global TODO list simply shows all headlines with TODO keywords. This list can become very long. There are two ways to keep it more compact:

Some people view a TODO item that has been scheduled for execution or have a deadline (see Timestamps) as no longer open. Configure the variables org-agenda-todo-ignore-scheduled to exclude some or all scheduled items from the global TODO list, org-agenda-todo-ignore-deadlines to exclude some or all items with a deadline set, org-agenda-todo-ignore-timestamp to exclude some or all items with an active timestamp other than a DEADLINE or a SCHEDULED timestamp and/or org-agenda-todo-ignore-with-date to exclude items with at least one active timestamp.

TODO items may have sublevels to break up the task into subtasks. In such cases it may be enough to list only the highest level TODO headline and omit the sublevels from the global list. Configure the variable org-agenda-todo-list-sublevels to get this behavior.

If headlines in the agenda files are marked with tags (see Tags), or have properties (see Properties and Columns), you can select headlines based on this metadata and collect them into an agenda buffer. The match syntax described here also applies when creating sparse trees with C-c / m.

M-x org-agenda m (org-tags-view)

Produce a list of all headlines that match a given set of tags. The command prompts for a selection criterion, which is a boolean logic expression with tags, like +work+urgent-withboss or work|home (see Tags). If you often need a specific search, define a custom command for it (see The Agenda Dispatcher).

M-x org-agenda M (org-tags-view)

Like m, but only select headlines that are also TODO items. To exclude scheduled/deadline items, see the variable org-agenda-tags-todo-honor-ignore-options. Matching specific TODO keywords together with a tags match is also possible, see Tag Searches.

The commands available in the tags list are described in Commands in the Agenda Buffer.

A search string can use Boolean operators & for AND and | for OR. & binds more strongly than |. Parentheses are currently not implemented. Each element in the search is either a tag, a regular expression matching tags, or an expression like PROPERTY OPERATOR VALUE with a comparison operator, accessing a property value. Each element may be preceded by - to select against it, and + is syntactic sugar for positive selection. The AND operator & is optional when + or - is present. Here are some examples, using only tags.

+work-boss

Select headlines tagged work, but discard those also tagged boss.

work|laptop

Selects lines tagged work or laptop.

work|laptop+night

Like before, but require the laptop lines to be tagged also night.

Instead of a tag, you may also specify a regular expression enclosed in curly braces (see Regular Expressions). For example, work+{^boss.*} matches headlines that contain the tag :work: and any tag starting with boss.

Group tags (see Tag Hierarchy) are expanded as regular expressions. E.g., if work is a group tag for the group :work:lab:conf:, then searching for work also searches for {\(?:work\|lab\|conf\)} and searching for -work searches for all headlines but those with one of the tags in the group (i.e., -{\(?:work\|lab\|conf\)}).

You may also test for properties (see Properties and Columns) at the same time as matching tags. The properties may be real properties, or special properties that represent other metadata (see Special Properties). For example, the property TODO represents the TODO keyword of the entry. Or, the property LEVEL represents the level of an entry. So searching +LEVEL=3+boss-TODO​"DONE"= lists all level three headlines that have the tag boss and are not marked with the TODO keyword DONE. In buffers with org-odd-levels-only set, LEVEL does not count the number of stars, but LEVEL=2 corresponds to 3 stars etc.

Here are more examples:

work+TODO​"WAITING"=

Select work-tagged TODO lines with the specific TODO keyword WAITING.

work+TODO​"WAITING"|home+TODO​="WAITING"=

Waiting tasks both at work and at home.

When matching properties, a number of different operators can be used to test the value of a property. Here is a complex example:

+work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<*2
         +With={Sarah\|Denny}+SCHEDULED>="<2008-10-11>"

The type of comparison depends on how the comparison value is written:

• If the comparison value is a plain number, a numerical comparison is done, and the allowed operators are <, =, >, <=, >=, and <>. As a synonym for the equality operator =, there is also ==; != and /= are synonyms of the inequality operator <>.
• If the comparison value is enclosed in double-quotes, a string comparison is done, and the same operators are allowed.
• If the comparison value is enclosed in double-quotes and angular brackets (like DEADLINE<​"<2008-12-24 Wed 18:30>"=), both values are assumed to be date/time specifications in the standard Org way, and the comparison is done accordingly. Valid values also include "<now>" for now (including time), "<today>", and "<tomorrow>" for these days at 0:00 hours, i.e., without a time specification. You can also use strings like "<+5d>" or "<-2m>" with units d, w, m, and y for day, week, month, and year, respectively.
• If the comparison value is enclosed in curly braces, a regexp match is performed, with = meaning that the regexp matches the property value, and <> meaning that it does not match.
• All operators may be optionally followed by an asterisk *, like in <*, !=*, etc. Such starred operators work like their regular, unstarred counterparts except that they match only headlines where the tested property is actually present. This is most useful for search terms that logically exclude results, like the inequality operator.

So the search string in the example finds entries tagged work but not boss, which also have a priority value A, a Coffee property with the value unlimited, an EFFORT property that is numerically smaller than 2, a With property that is matched by the regular expression Sarah\|Denny, and that are scheduled on or after October 11, 2008.

Note that the test on the EFFORT property uses operator <*, so that the search result will include only entries that actually have an EFFORT property defined and with numerical value smaller than 2. With the regular < operator, the search would handle entries without an EFFORT property as having a zero effort and would include them in the result as well.

You can use all characters valid in property names when matching properties. However, you have to quote some characters in property names with backslashes when using them in search strings, namely all characters different from alphanumerics and underscores(note: If you quote alphanumeric characters or underscores with a backslash, that backslash is ignored.). For example, to search for all entries having a property boss-prio, boss:prio, or boss\prio, respectively, with value C, use search strings

boss\-prio="C"
boss\:prio="C"
boss\\prio="C"

You can configure Org mode to use property inheritance during a search, but beware that this can slow down searches considerably. See Property Inheritance, for details.

For backward compatibility, and also for typing speed, there is also a different way to test TODO states in a search. For this, terminate the tags/property part of the search string (which may include several terms connected with |) with a / and then specify a Boolean expression just for TODO keywords. The syntax is then similar to that for tags, but should be applied with care: for example, a positive selection on several TODO keywords cannot meaningfully be combined with boolean AND. However, negative selection combined with AND can be meaningful. To make sure that only lines are checked that actually have any TODO keyword (resulting in a speed-up), use M-x org-agenda M, or equivalently start the TODO part after the slash with !. Using M-x org-agenda M or /! does not match TODO keywords in a DONE state. Examples:

work/WAITING

Same as work+TODO​"WAITING"=.

work/!-WAITING-NEXT

Select work-tagged TODO lines that are neither WAITING nor NEXT.

work/!+WAITING|+NEXT

Select work-tagged TODO lines that are either WAITING or NEXT.

This agenda view is a general text search facility for Org mode entries. It is particularly useful to find notes.

M-x org-agenda s (org-search-view)

This is a special search that lets you select entries by matching a substring or specific words using a boolean logic.

For example, the search string computer equipment matches entries that contain computer equipment as a substring, even if the two words are separated by more space or a line break.

Search view can also search for specific keywords in the entry, using Boolean logic. The search string +computer +wifi -ethernet -{8\.11[bg]} matches note entries that contain the keywords computer and wifi, but not the keyword ethernet, and which are also not matched by the regular expression 8\.11[bg], meaning to exclude both 8.11b and 8.11g. The first + is necessary to turn on boolean search, other + characters are optional. For more details, see the docstring of the command org-search-view.

You can incrementally and conveniently adjust a boolean search from the agenda search view with the following keys

Note that in addition to the agenda files, this command also searches the files listed in org-agenda-text-search-extra-files.

If you are following a system like David Allen's GTD to organize your work, one of the "duties" you have is a regular review to make sure that all projects move along. A stuck project is a project that has no defined next actions, so it never shows up in the TODO lists Org mode produces. During the review, you need to identify such projects and define next actions for them.

M-x org-agenda # (org-agenda-list-stuck-projects)

List projects that are stuck.

M-x org-agenda !

Customize the variable org-stuck-projects to define what a stuck project is and how to find it.

You almost certainly need to configure this view before it works for you. The built-in default assumes that all your projects are level-2 headlines, and that a project is not stuck if it has at least one entry marked with a TODO keyword TODO or NEXT or NEXTACTION.

Let's assume that you, in your own way of using Org mode, identify projects with a tag :PROJECT:, and that you use a TODO keyword MAYBE to indicate a project that should not be considered yet. Let's further assume that the TODO keyword DONE marks finished projects, and that NEXT and TODO indicate next actions. The tag :@shop: indicates shopping and is a next action even without the NEXT tag. Finally, if the project contains the special word IGNORE anywhere, it should not be listed either. In this case you would start by identifying eligible projects with a tags/TODO match (see Tag Searches) +PROJECT/-MAYBE-DONE, and then check for TODO, NEXT, @shop, and IGNORE in the subtree to identify projects that are not stuck. The correct customization for this is:

(setq org-stuck-projects
      '("+PROJECT/-MAYBE-DONE" ("NEXT" "TODO") ("@shop")
        "\\<IGNORE\\>"))

Note that if a project is identified as non-stuck, the subtree of this entry is searched for stuck projects.

The category is a broad label assigned to each agenda item. By default, the category is simply derived from the file name, but you can also specify it with a special line in the buffer, like this:

#+CATEGORY: Thesis

If you would like to have a special category for a single entry or a (sub)tree, give the entry a CATEGORY property with the special category you want to apply as the value.

The display in the agenda buffer looks best if the category is not longer than 10 characters. You can set up icons for category by customizing the org-agenda-category-icon-alist variable.

Org mode checks each agenda item for a time-of-day specification. The time can be part of the timestamp that triggered inclusion into the agenda, for example

<2005-05-10 Tue 19:00>

Time ranges can be specified with two timestamps:

<2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15>

In the headline of the entry itself, a time(range)—like 12:45 or a 8:30-1pm—may also appear as plain text(note: You can, however, disable this by setting org-agenda-search-headline-for-time variable to a nil value.).

If the agenda integrates the Emacs diary (see Weekly/daily agenda), time specifications in diary entries are recognized as well.

For agenda display, Org mode extracts the time and displays it in a standard 24-hour format as part of the prefix. The example times in the previous paragraphs would end up in the agenda like this:

 8:30-13:00 Arthur Dent lies in front of the bulldozer
12:45...... Ford Prefect arrives and takes Arthur to the pub
19:00...... The Vogon reads his poem
20:30-22:15 Marvin escorts the Hitchhikers to the bridge

If the agenda is in single-day mode, or for the display of today, the timed entries are embedded in a time grid, like

 8:00...... ------------------
 8:30-13:00 Arthur Dent lies in front of the bulldozer
10:00...... ------------------
12:00...... ------------------
12:45...... Ford Prefect arrives and takes Arthur to the pub
14:00...... ------------------
16:00...... ------------------
18:00...... ------------------
19:00...... The Vogon reads his poem
20:00...... ------------------
20:30-22:15 Marvin escorts the Hitchhikers to the bridge

The time grid can be turned on and off with the variable org-agenda-use-time-grid, and can be configured with org-agenda-time-grid.

Before being inserted into a view, the items are sorted. How this is done depends on the type of view.

For the daily/weekly agenda, the items for each day are sorted. The default order is to first collect all items containing an explicit time-of-day specification. These entries are shown at the beginning of the list, as a schedule for the day. After that, items remain grouped in categories, in the sequence given by org-agenda-files. Within each category, items are sorted by urgency, which is derived from the priority (see Priorities), plus additional increments for overdue scheduled or deadline items. The lowest priority is scored as 0, the next as 1000, and continues in steps of 1000 until reaching the highest priority, e.g., C, B, A are scored as 0, 1000, and 2000, respectively.

• For the TODO list, items remain in the order of categories, but within each category, sorting takes place according to urgency. The urgency used for sorting derives from the priority cookie, with additions depending on how close an item is to its due or scheduled date.
• For tags matches, items are not sorted at all, but just appear in the sequence in which they are found in the agenda files.

Sorting can be customized using the variable org-agenda-sorting-strategy, and may also include criteria based on the estimated effort of an entry (see Effort Estimates).

Agenda built-in or custom commands are statically defined. Agenda filters and limits allow flexibly narrowing down the list of agenda entries.

Filters only change the visibility of items, are very fast and are

mostly used interactively³⁴. You can switch quickly between different filters without having to recreate the agenda. Limits on the other hand take effect before the agenda buffer is populated, so they are mostly useful when defined as local variables within custom agenda commands.

(setq org-global-properties
      '(("Effort_ALL". "0 0:10 0:30 1:00 2:00 3:00 4:00")))

+work-John+<0:10-/plot/

(defun my-auto-exclude-fn (tag)
  (when (cond ((string= tag "net")
               (/= 0 (call-process "/sbin/ping" nil nil nil
                                   "-c1" "-q" "-t1" "mail.gnu.org")))
              ((member tag '("errand" "call"))
               (let ((hr (nth 2 (decode-time))))
                 (or (< hr 8) (> hr 21)))))
    (concat "-" tag)))

(setq org-agenda-auto-exclude-function #'my-auto-exclude-fn)

(setq org-agenda-custom-commands
      '(("n" todo "NEXT"
         ((org-agenda-max-entries 5)))))

n (org-agenda-next-line)

Next line (same as DOWN and C-n).

p (org-agenda-previous-line)

Previous line (same as UP and C-p).

SPC or mouse-3 (org-agenda-show-and-scroll-up)

Display the original location of the item in another window. With a prefix argument, make sure that drawers stay folded.

L (org-agenda-recenter)

Display original location and recenter that window.

TAB or mouse-2 (org-agenda-goto)

Go to the original location of the item in another window.

RET (org-agenda-switch-to)

Go to the original location of the item and delete other windows.

F (org-agenda-follow-mode)

Toggle Follow mode. In Follow mode, as you move point through the agenda buffer, the other window always shows the corresponding location in the Org file. The initial setting for this mode in new agenda buffers can be set with the variable org-agenda-start-with-follow-mode.

C-c C-x b (org-agenda-tree-to-indirect-buffer)

Display the entire subtree of the current item in an indirect buffer. With a numeric prefix argument N, go up to level N and then take that tree. If N is negative, go up that many levels. With a C-u prefix, do not remove the previously used indirect buffer.

C-c C-o (org-agenda-open-link)

Follow a link in the entry. This offers a selection of any links in the text belonging to the referenced Org node. If there is only one link, follow it without a selection prompt.

A

Interactively select another agenda view and append it to the current view.

o

Delete other windows.

v d or short d (org-agenda-day-view)

Switch to day view. When switching to day view, this setting becomes the default for subsequent agenda refreshes. A numeric prefix argument may be used to jump directly to a specific day of the year. For example, 32 d jumps to February 1st. When setting day view, a year may be encoded in the prefix argument as well. For example, 200712 d jumps to January 12, 2007. If such a year specification has only one or two digits, it is expanded into one of the 30 next years or the last 69 years.

v w or short w (org-agenda-week-view)

Switch to week view. When switching week view, this setting becomes the default for subsequent agenda refreshes. A numeric prefix argument may be used to jump directly to a specific day of the ISO week. For example 9 w to ISO week number 9. When setting week view, a year may be encoded in the prefix argument as well. For example, 200712 w jumps to week 12 in 2007. If such a year specification has only one or two digits, it is expanded into one of the 30 next years or the last 69 years.

v m (org-agenda-month-view)

Switch to month view. Because month views are slow to create, they do not become the default for subsequent agenda refreshes. A numeric prefix argument may be used to jump directly to a specific day of the month. When setting month view, a year may be encoded in the prefix argument as well. For example, 200712 m jumps to December 2007. If such a year specification has only one or two digits, it is expanded into one of the 30 next years or the last 69 years.

v y (org-agenda-year-view)

Switch to year view. Because year views are slow to create, they do not become the default for subsequent agenda refreshes. A numeric prefix argument may be used to jump directly to a specific day of the year.

v SPC (org-agenda-reset-view)

Reset the current view to org-agenda-span.

f (org-agenda-later)

Go forward in time to display the span following the current one. For example, if the display covers a week, switch to the following week. With a prefix argument, repeat that many times.

b (org-agenda-earlier)

Go backward in time to display earlier dates.

. (org-agenda-goto-today)

Go to today.

j (org-agenda-goto-date)

Prompt for a date and go there.

J (org-agenda-clock-goto)

Go to the currently clocked-in task in the agenda buffer.

D (org-agenda-toggle-diary)

Toggle the inclusion of diary entries. See Weekly/daily agenda.

v l or v L or short l (org-agenda-log-mode)

Toggle Logbook mode. In Logbook mode, entries that were marked as done while logging was on (see the variable org-log-done) are shown in the agenda, as are entries that have been clocked on that day. You can configure the entry types that should be included in log mode using the variable org-agenda-log-mode-items. When called with a C-u prefix argument, show all possible logbook entries, including state changes. When called with two prefix arguments C-u C-u, show only logging information, nothing else. v L is equivalent to C-u v l.

v [ or short [ (org-agenda-manipulate-query-add)

Include inactive timestamps into the current view. Only for weekly/daily agenda.

v a (org-agenda-archives-mode)

Toggle Archives mode. In Archives mode, trees that are archived (see Internal archiving) are also scanned when producing the agenda. To exit archives mode, press v a again. The initial setting for this mode in new agenda buffers can set with the variable org-agenda-start-with-archives-mode, which can be set with the same values as org-agenda-archives-mode.

v A

Toggle Archives mode. Include all archive files as well.

v R or short R (org-agenda-clockreport-mode)

Toggle Clockreport mode. In Clockreport mode, the daily/weekly agenda always shows a table with the clocked times for the time span and file scope covered by the current agenda view. The initial setting for this mode in new agenda buffers can be set with the variable org-agenda-start-with-clockreport-mode. By using a prefix argument when toggling this mode (i.e., C-u R), the clock table does not show contributions from entries that are hidden by agenda filtering(note: Only tags filtering is respected here, effort filtering is ignored.). See also the variables org-clock-report-include-clocking-task and org-agenda-clock-report-header.

v c

Show overlapping clock entries, clocking gaps, and other clocking problems in the current agenda range. You can then visit clocking lines and fix them manually. See the variable org-agenda-clock-consistency-checks for information on how to customize the definition of what constituted a clocking problem. To return to normal agenda display, press l to exit Logbook mode.

v E or short E (org-agenda-entry-text-mode)

Toggle entry text mode. In entry text mode, a number of lines from the Org heading referenced by an agenda line are displayed below the line. The maximum number of lines is given by the variable org-agenda-entry-text-maxlines. Calling this command with a numeric prefix argument temporarily modifies that number to the prefix value.

G (org-agenda-toggle-time-grid)

Toggle the time grid on and off. See also the variables org-agenda-use-time-grid and org-agenda-time-grid.

r (org-agenda-redo), g

Recreate the agenda buffer, for example to reflect the changes after modification of the timestamps of items with S-LEFT and S-RIGHT. When the buffer is the global TODO list, a prefix argument is interpreted to create a selective list for a specific TODO keyword.

C-x C-s or short s (org-save-all-org-buffers)

Save all Org buffers in the current Emacs session, and also the locations of IDs.

C-c C-x C-c (org-agenda-columns)

Invoke column view (see Column View) in the agenda buffer. The column view format is taken from the entry at point, or, if there is no entry at point, from the first entry in the agenda view. So whatever the format for that entry would be in the original buffer (taken from a property, from a COLUMNS keyword, or from the default variable org-columns-default-format) is used in the agenda.

C-c C-x > (org-agenda-remove-restriction-lock)

Remove the restriction lock on the agenda, if it is currently restricted to a file or subtree (see Agenda Files).

M-UP (org-agenda-drag-line-backward)

Drag the line at point backward one line. With a numeric prefix argument, drag backward by that many lines.

Moving agenda lines does not persist after an agenda refresh and does not modify the contributing Org files.

M-DOWN (org-agenda-drag-line-forward)

Drag the line at point forward one line. With a numeric prefix argument, drag forward by that many lines.

0--9

Digit argument.

C-_ (org-agenda-undo)

Undo a change due to a remote editing command. The change is undone both in the agenda buffer and in the remote buffer.

t (org-agenda-todo)

Change the TODO state of the item, both in the agenda and in the original Org file. A prefix argument is passed through to the org-todo command, so for example a C-u prefix are will trigger taking a note to document the state change.

C-S-RIGHT (org-agenda-todo-nextset)

Switch to the next set of TODO keywords.

C-S-LEFT, org-agenda-todo-previousset

Switch to the previous set of TODO keywords.

C-k (org-agenda-kill)

Delete the current agenda item along with the entire subtree belonging to it in the original Org file. If the text to be deleted remotely is longer than one line, the kill needs to be confirmed by the user. See variable org-agenda-confirm-kill.

C-c C-w (org-agenda-refile)

Refile the entry at point.

C-c C-x C-a or short a (org-agenda-archive-default-with-confirmation)

Archive the subtree corresponding to the entry at point using the default archiving command set in org-archive-default-command. When using the a key, confirmation is required.

C-c C-x a (org-agenda-toggle-archive-tag)

Toggle the archive tag (see Internal archiving) for the current headline.

C-c C-x A (org-agenda-archive-to-archive-sibling)

Move the subtree corresponding to the current entry to its archive sibling.

C-c C-x C-s or short $ (org-agenda-archive)

Archive the subtree corresponding to the current headline. This means the entry is moved to the configured archive location, most likely a different file.

T (org-agenda-show-tags)

Show all tags associated with the current item. This is useful if you have turned off org-agenda-show-inherited-tags, but still want to see all tags of a headline occasionally.

: (org-agenda-set-tags)

Set tags for the current headline. If there is an active region in the agenda, change a tag for all headings in the region.

\, (org-agenda-priority)

Set the priority for the current item. Org mode prompts for the priority character. If you reply with SPC, the priority cookie is removed from the entry.

+ or S-UP (org-agenda-priority-up)

Increase the priority of the current item. The priority is changed in the original buffer, but the agenda is not resorted. Use the r key for this.

- or S-DOWN (org-agenda-priority-down)

Decrease the priority of the current item.

C-c C-x e or short e (org-agenda-set-effort)

Set the effort property for the current item.

C-c C-z or short z (org-agenda-add-note)

Add a note to the entry. This note is recorded, and then filed to the same location where state change notes are put. Depending on org-log-into-drawer, this may be inside a drawer.

C-c C-a (org-attach)

Dispatcher for all command related to attachments.

C-c C-s (org-agenda-schedule)

Schedule this item. With a prefix argument, remove the scheduling timestamp

C-c C-d (org-agenda-deadline)

Set a deadline for this item. With a prefix argument, remove the deadline.

S-RIGHT (org-agenda-do-date-later)

Change the timestamp associated with the current line by one day into the future. If the date is in the past, the first call to this command moves it to today. With a numeric prefix argument, change it by that many days. For example, 3 6 5 S-RIGHT changes it by a year. With a C-u prefix, change the time by one hour. If you immediately repeat the command, it will continue to change hours even without the prefix argument. With a double C-u C-u prefix, do the same for changing minutes. The stamp is changed in the original Org file, but the change is not directly reflected in the agenda buffer. Use r or g to update the buffer.

S-LEFT (org-agenda-do-date-earlier)

Change the timestamp associated with the current line by one day into the past.

> (org-agenda-date-prompt)

Change the timestamp associated with the current line. The key > has been chosen, because it is the same as S-. on my keyboard.

I (org-agenda-clock-in)

Start the clock on the current item. If a clock is running already, it is stopped first.

O (org-agenda-clock-out)

Stop the previously started clock.

X (org-agenda-clock-cancel)

Cancel the currently running clock.

J (org-agenda-clock-goto)

Jump to the running clock in another window.

k (org-agenda-capture)

Like org-capture, but use the date at point as the default date for the capture template. See org-capture-use-agenda-date to make this the default behavior of org-capture.

m (org-agenda-bulk-mark)

Mark the entry at point for bulk action. If there is an active region in the agenda, mark the entries in the region. With numeric prefix argument, mark that many successive entries.

* (org-agenda-bulk-mark-all)

Mark all visible agenda entries for bulk action.

u (org-agenda-bulk-unmark)

Unmark entry for bulk action.

U (org-agenda-bulk-unmark-all)

Unmark all marked entries for bulk action.

M-m (org-agenda-bulk-toggle)

Toggle mark of the entry at point for bulk action.

M-* (org-agenda-bulk-toggle-all)

Toggle mark of every entry for bulk action.

% (org-agenda-bulk-mark-regexp)

Mark entries matching a regular expression for bulk action.

B (org-agenda-bulk-action)

Bulk action: act on all marked entries in the agenda. This prompts for another key to select the action to be applied. The prefix argument to B is passed through to the s and d commands, to bulk-remove these special timestamps. By default, marks are removed after the bulk. If you want them to persist, set org-agenda-bulk-persistent-marks to t or hit p at the prompt.

p

Toggle persistent marks.

$

Archive all selected entries.

A

Archive entries by moving them to their respective archive siblings.

t

Change TODO state. This prompts for a single TODO keyword and changes the state of all selected entries, bypassing blocking and suppressing logging notes—but not timestamps.

+

Add a tag to all selected entries.

-

Remove a tag from all selected entries.

s

Schedule all items to a new date. To shift existing schedule dates by a fixed number of days, use something starting with double plus at the prompt, for example ++8d or ++2w.

d

Set deadline to a specific date.

r

Prompt for a single refile target and move all entries. The entries are no longer in the agenda; refresh (g) to bring them back.

S

Reschedule randomly into the coming N days. N is prompted for. With a prefix argument (C-u B S), scatter only across weekdays.

f

Apply a function(note: You can also create persistent custom functions through org-agenda-bulk-custom-functions.) to marked entries. For example, the function below sets the CATEGORY property of the entries to web.

(defun set-category ()
  (interactive "P")
  (let ((marker (or (org-get-at-bol 'org-hd-marker)
                    (org-agenda-error))))
    (org-with-point-at marker
      (org-back-to-heading t)
      (org-set-property "CATEGORY" "web"))))

c (org-agenda-goto-calendar)

Open the Emacs calendar and go to the date at point in the agenda.

c (org-calendar-goto-agenda)

When in the calendar, compute and show the Org agenda for the date at point.

i (org-agenda-diary-entry)

Insert a new entry into the diary, using the date at point and (for block entries) the date at the mark. This adds to the Emacs diary file(note: This file is parsed for the agenda when org-agenda-include-diary is set.), in a way similar to the i command in the calendar. The diary file pops up in another window, where you can add the entry.

If you configure org-agenda-diary-file to point to an Org file, Org creates entries in that file instead. Most entries are stored in a date-based outline tree that will later make it easy to archive appointments from previous months/years. The tree is built under an entry with a DATE_TREE property, or else with years as top-level entries. Emacs prompts you for the entry text—if you specify it, the entry is created in org-agenda-diary-file without further interaction. If you directly press RET at the prompt without typing text, the target file is shown in another window for you to finish the entry there. See also the k r command.

M (org-agenda-phases-of-moon)

Show the phases of the moon for the three months around current date.

S (org-agenda-sunrise-sunset)

Show sunrise and sunset times. The geographical location must be set with calendar variables, see the documentation for the Emacs calendar.

C (org-agenda-convert-date)

Convert the date at point into many other cultural and historic calendars.

H (org-agenda-holidays)

Show holidays for three months around point date.

q (org-agenda-quit)

Quit agenda, remove the agenda buffer.

x (org-agenda-exit)

Exit agenda, remove the agenda buffer and all buffers loaded by Emacs for the compilation of the agenda. Buffers created by the user to visit Org files are not removed.

The first application of custom searches is the definition of keyboard shortcuts for frequently used searches, either creating an agenda buffer, or a sparse tree (the latter covering of course only the current buffer).

Custom commands are configured in the variable org-agenda-custom-commands. You can customize this variable, for example by pressing C from the agenda dispatcher (see The Agenda Dispatcher). You can also directly set it with Emacs Lisp in the Emacs init file. The following example contains all valid agenda views:

(setq org-agenda-custom-commands
      '(("x" agenda)
        ("y" agenda*)
        ("w" todo "WAITING")
        ("W" todo-tree "WAITING")
        ("u" tags "+boss-urgent")
        ("v" tags-todo "+boss-urgent")
        ("U" tags-tree "+boss-urgent")
        ("f" occur-tree "\\<FIXME\\>")
        ("h" . "HOME+Name tags searches") ;description for "h" prefix
        ("hl" tags "+home+Lisa")
        ("hp" tags "+home+Peter")
        ("hk" tags "+home+Kim")))

The initial string in each entry defines the keys you have to press after the dispatcher command in order to access the command. Usually this is just a single character, but if you have many similar commands, you can also define two-letter combinations where the first character is the same in several combinations and serves as a prefix key(note: You can provide a description for a prefix key by inserting a cons cell with the prefix and the description.). The second parameter is the search type, followed by the string or regular expression to be used for the matching. The example above will therefore define:

x

as a global search for agenda entries planned³⁵ this week/day.

y

as the same search, but only for entries with an hour specification like [h]h:mm—think of them as appointments.

w

as a global search for TODO entries with WAITING as the TODO keyword.

W

as the same search, but only in the current buffer and displaying the results as a sparse tree.

u

as a global tags search for headlines tagged boss but not urgent.

v

The same search, but limiting it to headlines that are also TODO items.

U

as the same search, but only in the current buffer and displaying the result as a sparse tree.

f

to create a sparse tree (again, current buffer only) with all entries containing the word FIXME.

h

as a prefix command for a HOME tags search where you have to press an additional key (l, p or k) to select a name (Lisa, Peter, or Kim) as additional tag to match.

Note that *-tree agenda views need to be called from an Org buffer as they operate on the current buffer only.

Another possibility is the construction of agenda views that comprise the results of several commands, each of which creates a block in the agenda buffer. The available commands include agenda for the daily or weekly agenda (as created with a), alltodo for the global TODO list (as constructed with t), stuck for the list of stuck projects (as obtained with #) and the matching commands discussed above: todo, tags, and tags-todo.

Here are two examples:

(setq org-agenda-custom-commands
      '(("h" "Agenda and Home-related tasks"
         ((agenda "")
          (tags-todo "home")
          (tags "garden")))
        ("o" "Agenda and Office-related tasks"
         ((agenda "")
          (tags-todo "work")
          (tags "office")))))

This defines h to create a multi-block view for stuff you need to attend to at home. The resulting agenda buffer contains your agenda for the current week, all TODO items that carry the tag home, and also all lines tagged with garden. Finally, the command o provides a similar view for office tasks.

Org mode contains a number of variables regulating agenda construction and display. The global variables define the behavior for all agenda commands, including the custom commands. However, if you want to change some settings just for a single custom view, you can do so. Setting options requires inserting a list of variable names and values at the right spot in org-agenda-custom-commands. For example:

(setq org-agenda-custom-commands
      '(("w" todo "WAITING"
         ((org-agenda-sorting-strategy '(priority-down))
          (org-agenda-prefix-format "  Mixed: ")))
        ("U" tags-tree "+boss-urgent"
         ((org-fold-show-context-detail 'minimal)))
        ("N" search ""
         ((org-agenda-files '("~org/notes.org"))
          (org-agenda-text-search-extra-files nil)))))

Now the w command sorts the collected entries only by priority, and the prefix format is modified to just say Mixed: instead of giving the category of the entry. The sparse tags tree of U now turns out ultra-compact, because neither the headline hierarchy above the match, nor the headline following the match are shown. The command N does a text search limited to only a single file.

For command sets creating a block agenda, org-agenda-custom-commands has two separate spots for setting options. You can add options that should be valid for just a single command in the set, and options that should be valid for all commands in the set. The former are just added to the command entry; the latter must come after the list of command entries. Going back to the block agenda example (see Block agenda), let's change the sorting strategy for the h commands to priority-down, but let's sort the results for garden tags query in the opposite order, priority-up. This would look like this:

(setq org-agenda-custom-commands
      '(("h" "Agenda and Home-related tasks"
         ((agenda)
          (tags-todo "home")
          (tags "garden"
                ((org-agenda-sorting-strategy '(priority-up)))))
         ((org-agenda-sorting-strategy '(priority-down))))
        ("o" "Agenda and Office-related tasks"
         ((agenda)
          (tags-todo "work")
          (tags "office")))))

As you see, the values and parentheses setting is a little complex. When in doubt, use the customize interface to set this variable—it fully supports its structure. Just one caveat: when setting options in this interface, the values are just Lisp expressions. So if the value is a string, you need to add the double-quotes around the value yourself.

To control whether an agenda command should be accessible from a specific context, you can customize org-agenda-custom-commands-contexts. Let's say for example that you have an agenda command o displaying a view that you only need when reading emails. Then you would configure this option like this:

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

You can also tell that the command key o should refer to another command key r. In that case, add this command key like this:

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

See the docstring of the variable for more information.