Skip to content
Tutorials Center
My learning

Topics

Lesson 35 of 38 ยท Projects and Practice

Project: A Daily Planner from Org-style TODO Headings

Plan your day the Emacs way: write TODO headings with priorities and dates, learn how the Org agenda collects them, and build a small planner that mirrors it.

One of the best reasons to learn Emacs is a planning system that is just a text file. Org mode turns headings that start with TODO and carry dates into a daily and weekly agenda, a prioritized list of what to do today. In this project you set up a real planner in Emacs, then write a small JavaScript program that parses the same headings and builds an agenda, so you understand exactly what the agenda command is doing.

The Emacs configuration and key sequences are real. The program is a stand-in (Emacs's agenda is far richer); we describe it as a model of the core idea. Org mode itself is covered in its own chapter of this course.

The file

Create ~/org/tasks.org with content like this:

ORG
* TODO [#A] Send invoice to client
  DEADLINE: <2025-03-14 Fri>
* TODO [#B] Write chapter 3
  SCHEDULED: <2025-03-12 Wed>
* TODO [#C] Water the plants
  SCHEDULED: <2025-03-12 Wed +3d>
* DONE Book dentist
  CLOSED: [2025-03-10 Mon 09:15]
* TODO Read about Tree-sitter

Pieces to know:

  • TODO and DONE are keywords; cycle them on a heading with C-c C-t or S-<right>.
  • [#A] is a priority (A highest, C lowest); S-<up> and S-<down> change it.
  • SCHEDULED: is the day you plan to start; DEADLINE: is the day it is due. Insert either with C-c C-s or C-c C-d, then pick a date in the calendar popup.
  • +3d is a repeater: after you mark the task DONE, Org moves the date three days ahead and sets the state back to TODO. Other units: h, w, m, y. ++ and .+ choose how the next date is computed (from the old date, after today, or from completion).

Wiring the agenda

ELISP
(setq org-directory "~/org/")
(setq org-agenda-files (list (expand-file-name "tasks.org" org-directory)))
(setq org-todo-keywords '((sequence "TODO(t)" "WAIT(w)" "|" "DONE(d)" "CANCELED(c)")))
(setq org-log-done 'time)                 ; add CLOSED: timestamp when done
(global-set-key (kbd "C-c a") #'org-agenda)
(global-set-key (kbd "C-c c") #'org-capture)

(setq org-capture-templates
      '(("t" "Todo" entry (file+headline "~/org/tasks.org" "Inbox")
         "* TODO %?\n  %U\n")))

Press C-c a and then a for the weekly agenda, t for the global TODO list, n for both together. In the agenda: n and p move, RET visits the heading, t changes its state, r refreshes, d, w, m switch to day, week, month views, . jumps to today, and q quits. Capture ideas from anywhere with C-c c t and finish with C-c C-c.

The idea behind the agenda

An agenda for a day is built from a few rules:

  1. Collect every heading with a date (scheduled, deadline) from the agenda files.
  2. Show items scheduled for the day or earlier (overdue scheduled items stay visible until done).
  3. Show deadlines that fall within the warning window (14 days by default, org-deadline-warning-days).
  4. Sort by priority, then by date.
  5. Expand repeaters into future occurrences.

The stand-in below follows exactly that logic for a handful of headings.

JS Stand-in: build a day's agenda

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Repeaters: marking a task done

When you finish a repeating task, Org shifts its date by the repeater and resets the state. A stand-in shows the three flavours (+ simple, ++ catch up past today, .+ count from the completion day):

JS Stand-in: repeaters

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Choose + for fixed duties (rent), ++ for rhythmic events that should not pile up (a weekly meeting you skipped) and .+ for habits measured from the last time (water the plants three days after you actually did).

Extend it

  • Add org-agenda-custom-commands for a "work only" view filtered by tag.
  • Use C-c C-x C-i / C-c C-x C-o to clock in and out and get time reports.
  • Archive finished subtrees with C-c C-x C-a.
  • Sync the file between devices with Git or a file-sync tool; it is plain text.

The agenda only sees files in org-agenda-files. If an item is missing, check that its file is listed, that it has a date, and that the keyword is one of org-todo-keywords.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which Org keywords place a task on the agenda by date?

    Scheduled and deadline timestamps put a heading on the agenda; TODO is the state.
  2. 2. What does the repeater +3d on a scheduled task do when you mark it DONE?

    Repeating tasks reappear: the date moves forward and the state returns to TODO.
  3. 3. Which key opens the Org agenda dispatcher in the configuration above?

    We bound C-c a to org-agenda and C-c c to org-capture.
  4. 4. Which repeater style counts from the day you finished the task?

    .+ shifts relative to the completion date; + and ++ shift relative to the old scheduled date.

Summary

  • A planner is a plain-text Org file with TODO headings, priorities and SCHEDULED/DEADLINE dates.
  • C-c a opens the agenda; C-c c captures new tasks; C-c C-t cycles state.
  • The agenda collects dated items, shows overdue scheduled ones and approaching deadlines, then sorts by priority.
  • Repeaters (+, ++, .+) re-schedule recurring tasks.
  • Keep the files in org-agenda-files and under version control.

Next: Project: Write Your Own Minor Mode