Org agenda

The agenda gathers what's scheduled, due and still to do in your Org files into one week, so you can see what's next without opening each file.

Opening the agenda

SPC o a a (or M-x org-agenda-list) opens the agenda on this week, with the cursor on today.

• Overdue, at the top, lists undone tasks scheduled or due before today. Sched. 3x means it was scheduled 3 days ago; 2 d. ago means its deadline was 2 days ago.
• Each day lists what falls on it: scheduled tasks, deadlines and appointments. A repeating task shows on every day it falls on.
• Later lists undone tasks dated after this week, each with its date.
• To do, at the bottom, lists TODOs with no date.

Done tasks are left out. A file you have open is read from its buffer, so changes you haven't saved yet show too.

Reading a line

Each task is one line, and its parts line up down the agenda:

    14:00   Sched.    TODO  [#A] Review the pull request    :work:  imp

From the left: a ▸ if it's marked (see Acting on several tasks), its time, what the date is, its TODO keyword, its priority and title, its tags, and its category (see Org). A habit has its graph after its title (see Habits). A long title is cut short with … so the rest stays in place. In a window under 60 columns wide, tags are left out.

In the window client, the agenda's title and the day headers are drawn larger, at the sizes org-heading-heights gives Org's headings.

Moving around

Changing tasks from the agenda

Change a task right from its line, without opening its file.

H and L move the date that line shows: its scheduled date, its deadline, or an appointment, keeping its time and repeater.

The change is made in the task's file. If the file isn't open, it's opened out of sight and saved. If it's open with changes you haven't saved, the change joins them and nothing is saved. The agenda redraws to show it; a task that's now done leaves the agenda. u can't undo refiling or archiving into another file.

Filtering

Narrow the agenda to what you're working on. Filters add up, show at the right of the title as Filter: +work -home, and stay while you move, refresh and change the view.

A task with no effort is left out by se, except with <>. A section the filters leave empty is left out; the days always show. Opening another view starts without filters.

Acting on several tasks

Mark tasks, then act on all of them at once. A marked task has a ▸ at the left of its line, and its title is highlighted.

Marks stay while you move and refresh; opening another view clears them.

Then press x and pick what to do to every marked task:

It asks once, acts on each task, then clears the marks. S moves a task's scheduled date and deadline, or its first appointment when it has neither. u undoes the whole action when it changed a single file, but not a refile or an archive.

Clocking from the agenda

Keep track of time on a task from its line, as SPC m c does in its file (see Clocking).

Days, weeks, months

Press gD to change how much the agenda shows:

f and b then move by that much: a month at a time in a month's view. The agenda is back to a week the next time you open it.

Log mode

Press gD l to see what you did on each day, alongside what's planned. Each line is at its time:

Done tasks show too. Press gD l again to turn it off; it's off again the next time you open the agenda.

The clock report

Press gD R or cr to add a table below the agenda of the time you clocked in the days it shows. It gives each file's time, and each heading's under it, two levels deep. A heading's time includes the time of the headings under it.

Clock report
────────────
File      Heading    Time
─────────────────────────
work.org  File time  1:55
          Project    1:55
            Draft    1:25
─────────────────────────
Total                1:55

A clock counts on the day it started. It's off again the next time you open the agenda.

Times and appointments

A time in a task's date, such as <2026-10-25 Sun 14:00> or <2026-10-25 Sun 9:30-10:00>, puts it at that time of day. Timed tasks come first in their day, by time; the rest follow by priority.

Any other active date in a heading or its text is an appointment, shown on its day:

* Dentist <2026-10-24 Sat 10:00>
* Conference
<2026-11-02 Mon>--<2026-11-04 Wed>

A date range shows on each of its days, as (2/3) on the second.

Habits

A habit is a task you mean to do regularly. Give it a repeating scheduled date and a STYLE property of habit:

* TODO Exercise
SCHEDULED: <2026-10-21 Wed .+2d>
:PROPERTIES:
:STYLE:    habit
:END:

A habit shows on today only, once it's due, never under Overdue or Later. After its title is a graph of the last three weeks and the week to come, a cell a day:

    Sched.   TODO  Exercise          *      * * !

A * is a day you did it, ! is today. The colors say how you were doing on each day, as in Org: blue before it was due, green while it could be done, yellow on its last day, red once it was overdue. Days to come, and past days you didn't do it, are drawn lighter.

A repeater can give the longest you may wait after a slash: .+2d/4d is due two days after you last did it, and overdue after four. The days you did it come from the state changes logged when you marked it done, and its LAST_REPEAT property (see Org).

Diary dates

A date can be one of Emacs's diary forms, for things that come round in a pattern a repeater can't give. The agenda reads five of them, written in a timestamp:

* Ana is %d <%%(diary-anniversary 10 22 1990)>
* Thanksgiving <%%(diary-float 11 4 4)>
* Book club <%%(diary-float t 3 3) 19:00>
* Trip <%%(diary-block 10 19 2026 10 23 2026)>
* Bins out <%%(diary-cyclic 14 10 10 2026)>
* Payday <%%(diary-date t 25 t)>

A time after the form, as 19:00, puts it at that time. Dates are month, day, year, as in Emacs; set calendar-date-style to 'european for day, month, year, or 'iso for year, month, day. The agenda doesn't run Lisp, so any other form is skipped, and the agenda's last line says how many were. H and L can't move a diary date.

The time grid

Today, and any other day with something timed, has a time grid: a dim line every two hours from 08:00 to 20:00, among the timed tasks. On today, a now line marks the time the agenda was drawn; gr moves it on.

(set-option! 'org-agenda-use-time-grid #f)          ; no grid
(set-option! 'org-agenda-time-grid '(900 1200 1700)) ; other times

Deadlines coming up

Deadlines in the next 14 days also show on today, as In 3 d.. A deadline can give its own warning period in its timestamp:

DEADLINE: <2026-10-30 Fri -3d>

That one shows on today only from three days before.

Tags

A task's tags are its own, those of the headings it's under, and the file's #+FILETAGS::

#+FILETAGS: :home:
* Garden :outside:
** TODO Plant the bulbs :autumn:

Plant the bulbs shows as :autumn:outside:home:.

Lists of TODOs

SPC o a t (or M-x org-todo-list) lists every undone TODO in your agenda files, dated or not, by priority and then in the order they're written. The same keys work on it as in the agenda, so you can change a task from the list.

Matching tags and properties

SPC o a m (or M-x org-tags-view) asks for a match and lists every heading it fits, done ones too:

Compare properties with =, <>, <, >, <= or >=, against a number, a "string" or a {regexp}. A heading without the property matches only <>.

Searching

SPC o a s (or M-x org-search-view) asks for words and lists every entry whose heading or text holds them all, ignoring case:

The dispatcher

SPC o A (or M-x org-agenda, or :OrgAgenda) shows a menu of views, as Org's agenda dispatcher does:

A limited view says so in its title, and keeps the limit when you press gr.

Your own views

Add a view to the dispatcher in init.scm with define-agenda-command!: a key, a name, and the parts it shows, one after another.

(define-agenda-command! "w" "Work day"
  '((agenda (span 1))
    (tags-todo "+work" (header "Work to do"))
    (search "meeting")))

Each part can have a (header "Name"). With more than one part, each is shown under its name. f and b move the agenda part by its span.

Choosing the files

Set the files to read in init.scm. Relative names are looked up in org-directory. With none set, the agenda reads every .org file in org-directory.

(set-option! 'org-agenda-files '("inbox.org" "work.org"))

Options