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

TODO Items

Most task managers keep tasks in one place and notes in another. Org takes the opposite approach: a task is simply a headline that carries a keyword, and it lives in the same outline as the notes, meeting minutes and code snippets it came from. When you write “ask the vendor about the license” in the middle of a project log, you can turn that line into a task on the spot, and the surrounding text stays attached to it as context.

The obvious cost of this design is that tasks end up scattered across many headlines and many files. Org pays that cost back with commands that collect them again: sparse trees inside one buffer, and the agenda across all your files (see Agenda Views). This chapter covers the task side of that bargain: how a headline becomes a task, how tasks move through states, how Org records that movement, and how you split work into smaller pieces and measure progress on them.

The essential idea: a keyword at the start of a headline

A TODO item (or task) is a headline whose title begins with a TODO keyword. Out of the box Org knows 2 keywords: TODO, which means that something still needs to be done, and DONE, which means that it is finished.

* Infrastructure
** TODO Renew the TLS certificate
** DONE Rotate the database password
** Notes from the security review

Only the second and third headlines are tasks. The fourth is an ordinary headline, and it remains one until you give it a keyword. Nothing else about a task is special: it can have body text, children, tags, properties and timestamps like any other entry (see Document Structure).

Changing the state

You rarely type keywords by hand. The central command is C-c C-t (org-todo), which rotates the current headline through its states. With the default keywords the rotation has three steps:

stateDiagram-v2
    direction LR
    none: no keyword
    none --> TODO: C-c C-t
    TODO --> DONE: C-c C-t
    DONE --> none: C-c C-t

Figure 8.1: With the default setup, C-c C-t cycles a headline from plain text to TODO, to DONE, and back to plain text.

Several other commands change states as well:

KeyCommandEffect
C-c C-torg-todoRotate to the next state, or open the fast selection menu when keywords have selection keys.
S-RIGHT, S-LEFTMove to the next or previous state, like cycling in either direction.
S-M-RETorg-insert-todo-headingInsert a new task below the current entry, with the same keyword (or the first keyword when the current one is done or missing).
C-c / torg-show-todo-treeFold the buffer and show only tasks that are not done, together with their parents.
t in the agendaChange the state of the task on the current agenda line.

The C-c / t command builds a sparse tree: a view of the buffer where everything is folded except the matching headlines and the headlines above them. It answers the question “what is still open in this file?” without losing the structure of the file. With a prefix (C-u C-c / t, or C-c / T) it asks for a keyword, and you can name several at once, separated by |, for example WAIT|NEXT.

For a list of open tasks across all your files, press t in the agenda dispatcher (M-x org-agenda t, the command org-todo-list). That list belongs to the agenda, which has its own chapter.

Designing your own keywords

A shopping list needs only 2 states, but real work often passes through intermediate stages: a task waits for someone else, a bug is reproduced but not yet fixed, a draft is out for review. Org lets you define as many keywords as you need in the variable org-todo-keywords.

Keywords as workflow states

The most common use is a sequence: an ordered list of states that a task moves through. A vertical bar divides the list into two groups. Keywords before the bar are not-done states (the task still needs action); keywords after it are done states (no further action is needed).

(setq org-todo-keywords
      '((sequence "TODO" "NEXT" "WAIT" "|" "DONE" "CANCELED")))

With this setting, C-c C-t moves a headline through TODO, NEXT, WAIT, DONE and CANCELED, and then back to no keyword. If you leave out the bar, Org treats the last keyword as the only done state.

The distinction between done and not-done matters more than the order. The agenda hides done tasks from the TODO list, the CLOSED timestamp is written only when a task enters a done state, and statistics cookies (described later) count done children. CANCELED sits after the bar for this reason: a canceled task needs no action, so Org should treat it as finished even though it was never completed.

To jump straight to a specific state, give C-c C-t a numeric prefix: with the setting above, C-3 C-c C-t sets WAIT, the third keyword. Changes to org-todo-keywords take effect only when Org mode restarts in a buffer, so run M-x org-mode (or reopen the file) after you edit your configuration.

Keywords as types

Org also supports a second interpretation, in which the keywords before the bar name kinds of tasks rather than stages. The classic example is assigning work to people:

(setq org-todo-keywords '((type "Ana" "Ben" "Chen" "|" "DONE")))

The type symbol changes how C-c C-t behaves. Pressed several times in a row, it still steps through all the names so that you can pick the right person. Pressed later, on a headline that already carries a name, it jumps straight to DONE. In a batch test, two presses on a plain headline gave Ben, and a third press in a separate command gave DONE:

* Ben Review the budget
* DONE Review the budget

The manual itself recommends tags over type keywords for this purpose, since a headline can carry many tags but only one keyword. Treat this feature as a way to read older files rather than as a design to copy (see Tags, Properties and Column View).

Several sequences side by side

Different kinds of work deserve different workflows. A bug goes through REPORT, BUG and KNOWNCAUSE before it is FIXED, while an errand only needs TODO and DONE. You can define several sequences at once:

(setq org-todo-keywords
      '((sequence "TODO" "|" "DONE")
        (sequence "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED")
        (sequence "|" "CANCELED")))

Each keyword should appear in only one sequence, because Org uses the current keyword to decide which sequence a headline belongs to. Plain C-c C-t then stays inside that sequence. To switch to another sequence, use C-u C-u C-c C-t (or C-S-RIGHT and C-S-LEFT). S-RIGHT and S-LEFT ignore the boundaries and walk through every keyword of every sequence.

The following trace comes from a batch run with fast selection turned off (org-use-fast-todo-selection set to nil), starting from * TODO Crash on startup. Each line shows the prefix passed to org-todo and the resulting headline:

nil    -> * DONE Crash on startup
nil    -> * Crash on startup
nil    -> * TODO Crash on startup
(16)   -> * REPORT Crash on startup
nil    -> * BUG Crash on startup
nil    -> * KNOWNCAUSE Crash on startup
nil    -> * FIXED Crash on startup
nil    -> * Crash on startup
(16)   -> * CANCELED Crash on startup

The (16) entries are the double prefix, C-u C-u, which moves to the first keyword of the next sequence.

Fast access with selection keys

Cycling becomes tedious once you have more than 3 or 4 keywords. Instead, append a selection character in parentheses to each keyword:

(setq org-todo-keywords
      '((sequence "TODO(t)" "NEXT(n)" "WAIT(w)" "|" "DONE(d)" "CANCELED(c)")))

When at least one keyword has a key, C-c C-t no longer cycles. It opens a small menu, and a single key sets the state directly: C-c C-t w marks the task as waiting, and C-c C-t SPC removes the keyword. This behavior is controlled by org-use-fast-todo-selection, whose default value auto means “use the menu whenever keys are defined”. The characters @, ! and ^ cannot serve as selection keys because they have other meanings inside the parentheses, as the logging section below explains.

Per-file keywords

The variable sets keywords for every file. A single file can override it with in-buffer settings, which are lines that start with #+ (see Getting Started):

#+TODO: TODO(t) | DONE(d)
#+TODO: REPORT(r) BUG(b) KNOWNCAUSE(k) | FIXED(f)
#+TODO: | CANCELED(c)

Each #+TODO: line defines one sequence. #+SEQ_TODO: is a synonym, and #+TYP_TODO: defines a type set. Org reads these lines when it starts in a buffer, so after editing one, press C-c C-c with point on the line to restart Org in that buffer.

Per-file keywords are useful when a file has a purpose of its own: a bug tracker, a reading list (TOREAD, READING, READ) or a hiring pipeline. Keep the keywords for personal tasks in org-todo-keywords, and let specialized files declare their own.

Faces

Org draws not-done keywords with the face org-todo and done keywords with org-done. With many keywords, color helps you scan a list. The variable org-todo-keyword-faces maps keywords to faces; a string value is read as a color name:

(setq org-todo-keyword-faces
      '(("WAIT" . "orange")
        ("CANCELED" . (:foreground "gray" :weight bold))))

Whether a color string sets the foreground or the background depends on org-faces-easy-properties.

Triggering tag changes from state changes

Sometimes a state should also be visible as a tag, for example so that an agenda filter can find all waiting tasks. The variable org-todo-state-tags-triggers adds or removes tags when a task enters a state. Each entry names a state (a keyword string, "" for no keyword, or the symbols todo and done for any not-done or done state) and a list of (TAG . FLAG) pairs, where a non-nil flag adds the tag and nil removes it.

(setq org-todo-keywords '((sequence "TODO" "WAIT" "|" "DONE"))
      org-todo-state-tags-triggers
      '(("WAIT" ("waiting" . t))
        ("TODO" ("waiting"))
        (done ("waiting"))))

Changing a task to WAIT and then to DONE produced these headlines in a batch run:

* WAIT Get the signed contract back                                 :waiting:
* DONE Get the signed contract back

Be careful with the symbol todo. WAIT is itself a not-done state, so a rule (todo ("waiting")) would fire on the same change and remove the tag that the WAIT rule had just added. The function org-todo-trigger-tag-changes applies the rules for the exact keyword first and the rules for todo or done after them, so the later rule wins.

Dependencies between tasks

An outline already expresses that some tasks are parts of others. Org can turn that structure into a rule: a parent cannot be finished while its children are still open. Set org-enforce-todo-dependencies to t to enable the rule.

A second rule handles sequences of steps. If a headline has the property ORDERED set to t, each child task is blocked until all the siblings above it are done. Properties live in a PROPERTIES drawer under the headline (see Tags, Properties and Column View).

* TODO Publish the paper
** DONE Write the draft
** TODO Get approval from co-authors

* Migrate the database
:PROPERTIES:
:ORDERED:  t
:END:
** TODO Take a backup
** TODO Run the migration script

With dependencies enabled, trying to mark the first or the last headline as DONE leaves the file unchanged and prints a message instead. These are the two messages from a batch run:

TODO state change from TODO to DONE blocked (by "TODO Get approval from co-authors")
TODO state change from TODO to DONE blocked (by "** TODO Take a backup")

A blocked task also reports t for the special property BLOCKED, which you can use in searches and column view.

Several tools adjust or bypass the rules:

  • C-c C-x o (org-toggle-ordered-property) adds or removes the ORDERED property. Org uses a property rather than a tag here because the setting should apply to one entry only, while tags are inherited. If you want to see the setting at a glance anyway, org-track-ordered-property-with-tag mirrors it as a tag.
  • A NOBLOCKING property with value t exempts an entry from blocking.
  • C-u C-u C-u C-c C-t changes the state regardless of any blocking.
  • org-enforce-todo-checkbox-dependencies extends the rule to checkboxes: an entry with unchecked boxes cannot become done.
  • In the agenda, org-agenda-dim-blocked-tasks (on by default) shows blocked tasks in a dimmed face.

Dependencies only follow the outline. Org itself has no syntax for “task A in one file waits for task B in another”; the manual points to the org-depend.el module in the separate org-contrib repository for that.

Recording progress

A task list tells you what is open. A log tells you what happened: when a task was finished, how long it sat in WAIT, why it was canceled. Org can write that log into the file as you change states, so that the history stays next to the task.

Recording when a task was closed

The simplest log is a single timestamp that marks completion. Set org-log-done to time:

(setq org-log-done 'time)

Now, whenever a task moves from a not-done state to a done state, Org adds a CLOSED line right below the headline. Here is a task after one press of C-c C-t in a batch run:

* DONE Write the release notes
CLOSED: [2026-11-19 Thu 04:44]

The brackets mark an inactive timestamp, a date that records a fact without placing the entry on the agenda calendar (see Dates and Times). If you cycle the task back to TODO, Org removes the line again. If you remove the keyword altogether, the line is also removed, unless org-closed-keep-when-no-todo is non-nil.

Set org-log-done to note instead, and Org also asks for a short note when you close a task. The per-file equivalents are #+STARTUP: logdone and #+STARTUP: lognotedone.

Logging every state change

A CLOSED line records the end of a task, not its path. To log intermediate changes, add markers to the keywords in org-todo-keywords, inside the same parentheses as the selection key:

  • ! records a timestamp when the task enters this state.
  • @ records a timestamp and asks for a note.
  • A slash followed by ! or @ (for example w@/!) adds a rule for leaving the state: Org logs the departure, but only if the target state does not already log its own arrival.
(setq org-todo-keywords
      '((sequence "TODO(t)" "WAIT(w@/!)" "|" "DONE(d!)" "CANCELED(c@)"))
      org-log-into-drawer t)

This setup asks for a note when a task starts waiting or gets canceled, because those moments deserve an explanation. It records a bare timestamp when a task is done. Thanks to /!, it also stamps the moment a task leaves WAIT for TODO, even though TODO itself logs nothing.

stateDiagram-v2
    direction LR
    TODO --> WAIT: on entry, timestamp and note (@)
    WAIT --> TODO: on leaving WAIT, timestamp (/!)
    TODO --> DONE: on entry, timestamp (!)
    WAIT --> DONE: on entry, timestamp (!)
    TODO --> CANCELED: on entry, timestamp and note (@)
    WAIT --> CANCELED: on entry, timestamp and note (@)

Figure 8.2: Each keyword declares what Org records when a task enters it, and WAIT also declares a record for leaving it, which applies only when the target state records nothing itself.

Starting from * TODO Renew the TLS certificate, a batch run moved the task to WAIT (with a note), back to TODO, and then to DONE. The result:

* DONE Renew the TLS certificate
:LOGBOOK:
- State "DONE"       from "TODO"       [2026-11-19 Thu 04:24]
- State "TODO"       from "WAIT"       [2026-11-19 Thu 04:24]
- State "WAIT"       from "TODO"       [2026-11-19 Thu 04:24] \\
  Waiting for the CA to validate the domain.
:END:

Notice 3 details. The newest record comes first, as set by org-log-states-order-reversed (default t). The records sit inside a LOGBOOK drawer, because org-log-into-drawer is t; a drawer is a named block between :NAME: and :END: that Org folds away by default (see Document Structure). Without that setting the records would appear as a plain list directly under the headline, where they clutter the entry. Finally, the note appears after a \\ line break on its own indented line.

When Org asks for a note, it opens a small buffer. Type the note and press C-c C-c to store it. If you only want the timestamp this time, press C-c C-c on the empty buffer. You can also force a note on any state change with C-u C-c C-t, even when the keyword does not request one.

The same marker syntax works in per-file settings:

#+TODO: TODO(t) WAIT(w@/!) | DONE(d!) CANCELED(c@)

If you use both org-log-done and per-keyword logging, Org may write 2 timestamps for 1 change, but it never asks for 2 notes: the state-change note takes precedence over the closing note.

Logging rules for one subtree

Logging needs vary between projects. A client project may need a full audit trail, while a personal errand list needs none. The LOGGING property sets the rules for an entry and its subtree. Any non-empty value first resets every logging option to nil; the words in the value then turn individual options back on. A value can contain keyword markers such as NEXT(!) and logging words from #+STARTUP, such as lognotedone or logrepeat. The value nil disables logging completely. The related property LOG_INTO_DRAWER overrides org-log-into-drawer for the subtree.

#+STARTUP: logdone
#+TODO: TODO NEXT | DONE

* Project Atlas
:PROPERTIES:
:LOGGING:  NEXT(!) DONE(!)
:LOG_INTO_DRAWER: t
:END:
** TODO Draft the schema
* TODO Buy coffee beans

In a batch run, “Draft the schema” went to NEXT and then to DONE, and “Buy coffee beans” went straight to DONE. The file afterwards (the 2 header lines, which did not change, are left out):

* Project Atlas
:PROPERTIES:
:LOGGING:  NEXT(!) DONE(!)
:LOG_INTO_DRAWER: t
:END:
** DONE Draft the schema
:LOGBOOK:
- State "DONE"       from "NEXT"       [2026-11-19 Thu 04:30]
- State "NEXT"       from "TODO"       [2026-11-19 Thu 04:30]
:END:
* DONE Buy coffee beans
CLOSED: [2026-11-19 Thu 04:30]

The task inside Project Atlas has no CLOSED line. The LOGGING property reset logdone for that subtree, and the value does not turn it back on, so the only record of completion is the DONE(!) state line. The task outside the project still follows the file-wide #+STARTUP: logdone.

Which mechanism to choose

The 3 logging mechanisms overlap, so it helps to assign each one a job:

NeedMechanism
Know when each task was finishedorg-log-done set to time (CLOSED line).
Know why a task stalled or was dropped@ on the waiting and canceled keywords.
A full history of a task’s states! on every keyword, together with org-log-into-drawer.
Different rules for one projectA LOGGING property on the project headline.

The LOGBOOK drawer is also where clocking writes its CLOCK lines, so time tracking and state history end up side by side (see Clocking, Effort and Timers).

Priorities

Once you have more open tasks than you can do today, you need a way to say which ones matter most. Org’s answer is the priority cookie: a marker such as [#A] placed right after the keyword.

* TODO [#A] Patch the production outage
* TODO [#C] Tidy the wiki sidebar
* TODO Answer the conference invitation

By default there are 3 priorities, A (highest), B and C (lowest), and a headline without a cookie counts as B, the value of org-priority-default. Priorities do not change the behavior of the task itself; they matter when the agenda sorts entries. Any headline can carry a priority, not only tasks.

The keys:

  • C-c , (org-priority) asks for a priority character; SPC removes the cookie.
  • S-UP (org-priority-up) and S-DOWN (org-priority-down) step through the priorities.
  • , in the agenda sets the priority of the task on the current line.

Stepping starts from the default priority when a headline has no cookie (governed by org-priority-start-cycle-with-default) and removes the cookie again after the last value. A batch run pressed S-UP twice and then S-DOWN three times on a fresh task:

* TODO [#B] Fix the login bug
* TODO [#A] Fix the login bug
* TODO Fix the login bug

The first 2 lines show the state after each S-UP; the last line shows the state after the 3 S-DOWN presses, which went from A to B, to C, and then removed the cookie. Note that S-UP and S-DOWN also change dates when point is on a timestamp.

Changing the range

If 3 levels are too few, widen the range with org-priority-highest, org-priority-lowest and org-priority-default. The values are characters (uppercase letters A to Z) or integers from 0 to 64. A file can set all three at once with the order highest, lowest, default:

#+PRIORITIES: A E C

Numeric priorities look like [#1] and need numeric settings:

#+PRIORITIES: 1 10 5
* TODO [#1] Patch the production outage

Keep the highest value smaller (earlier in the alphabet, or a lower number) than the lowest. In Org 9.8, org-lint also checks priority cookies against these settings, and the speed keys 1, 2 and 3 (single-key commands at the start of a headline, see Getting Started) insert the highest, default and lowest priority instead of fixed letters.

Breaking tasks into subtasks

Large tasks are hard to start and hard to track. The natural Org solution is to add child headlines under the task, each a smaller task of its own. To see progress at a glance, put a statistics cookie in the parent headline: [/] shows a fraction and [%] shows a percentage. Org fills in the cookie and updates it whenever the state of a direct child changes.

* Prepare the 2.0 release [/]
** TODO Freeze the API [%]
*** DONE Review public functions
*** TODO Write deprecation notices
** TODO Update the changelog
** DONE Tag the release candidate

After C-u C-c # (org-update-statistics-cookies with a prefix, which updates every cookie in the file), the batch output was:

* Prepare the 2.0 release [1/3]
** TODO Freeze the API [50%]
*** DONE Review public functions
*** TODO Write deprecation notices
** TODO Update the changelog
** DONE Tag the release candidate

Marking “Write deprecation notices” as DONE then changed the cookie of its parent to [100%]. The top cookie stayed at [1/3], because “Freeze the API” itself was still TODO: each cookie counts only its direct children. The parent did not change state either; whether to close it is your decision.

If you add or delete children by editing text, the cookies can fall out of date. C-c # updates the cookie of the current entry, and C-u C-c # updates the whole file. C-c C-c on a cookie also updates it.

Counting deeper levels

The variable org-hierarchical-todo-statistics controls the scope: its default t restricts the count to direct children, and nil counts every task in the subtree. To change the scope of one cookie only, put the word recursive in the COOKIE_DATA property:

* Parent [1/3]
:PROPERTIES:
:COOKIE_DATA: todo recursive
:END:
** TODO Child
*** DONE Grandchild
*** TODO Grandchild 2

The cookie counts all 3 tasks below the parent, and 1 of them is done. The word todo in the same property tells the cookie to count child tasks rather than checkboxes, which matters when an entry has both.

Closing the parent automatically

Some people prefer the parent to follow its children: done when all subtasks are done, open again when one is reopened. Org does not do this by itself, but whenever a child changes state and the parent has a cookie, it runs org-after-todo-statistics-hook with the number of done and not-done children. A small function on that hook does the job:

(defun my/org-summary-todo (n-done n-not-done)
  "Mark the parent DONE when all children are done, TODO otherwise."
  (let (org-log-done org-todo-log-states)
    (org-todo (if (= n-not-done 0) "DONE" "TODO"))))

(add-hook 'org-after-todo-statistics-hook #'my/org-summary-todo)

The let form turns logging off while the function runs, so that the automatic change does not prompt for notes. With the hook installed, finishing the last child in this file:

* TODO Onboard the new teammate [/]
** DONE Create accounts
** TODO Pair on the first ticket

gave this result in a batch run:

* DONE Onboard the new teammate [2/2]
** DONE Create accounts
** DONE Pair on the first ticket

The hook fires only for headlines that carry a statistics cookie, so you choose per parent whether it should follow its children.

Checkboxes

Not every step deserves a headline. Child tasks appear in the global TODO list, can be scheduled and carry their own logs; for a checklist of small steps, that is too much. A checkbox is a lighter alternative: a plain list item that starts with [ ] (see Document Structure for plain lists). Checkboxes do not appear in the agenda’s TODO list, which keeps short steps out of your daily overview.

A checkbox has 3 states: [ ] (not checked), [-] (partly checked) and [X] (checked). A parent checkbox follows its children automatically, and a statistics cookie in the headline or in a list item counts the checkboxes directly below it.

* TODO Set up the new laptop [/]
- [ ] Install the operating system
- [ ] Restore dotfiles [/]
  - [ ] Emacs configuration
  - [ ] Shell configuration
- [ ] Enroll in the VPN

Toggling “Emacs configuration” with C-c C-c gave this state:

* TODO Set up the new laptop [0/3]
- [ ] Install the operating system
- [-] Restore dotfiles [1/2]
  - [X] Emacs configuration
  - [ ] Shell configuration
- [ ] Enroll in the VPN

Toggling “Shell configuration” and “Install the operating system” as well gave:

* TODO Set up the new laptop [2/3]
- [X] Install the operating system
- [X] Restore dotfiles [2/2]
  - [X] Emacs configuration
  - [X] Shell configuration
- [ ] Enroll in the VPN

The parent item “Restore dotfiles” moved from [ ] to [-] to [X] without being touched, and both cookies kept up.

flowchart LR
    A["toggle a child checkbox"] -->|"none, some or all checked"| B["parent item: [ ] [-] [X]"]
    B -->|"checked count"| C["item cookie [n/m]"]
    B -->|"checked count of direct items"| D["headline cookie [n/m]"]
    E["change a child TODO state"] -->|"done count"| D
    D -->|"n-done, n-not-done"| F["org-after-todo-statistics-hook"]

Figure 8.3: A change at the bottom of the tree propagates upward one level at a time: checkboxes update their parent item and the nearest cookie, and TODO children update the cookie of their parent headline, which can in turn run a hook.

The checkbox commands:

KeyCommandEffect
C-c C-corg-toggle-checkboxToggle the checkbox at point. With C-u, add or remove the checkbox itself; with C-u C-u, set it to [-].
C-c C-x C-borg-toggle-checkboxThe same, but also works on a region (all boxes follow the first) and, on a headline, on the boxes between it and the next headline.
M-S-RETorg-insert-todo-headingIn a list item, insert a new item with a checkbox.
C-c C-x C-rorg-toggle-radio-buttonTreat the box at point as a radio button: checking it unchecks its siblings.
C-c #org-update-statistics-cookiesRecount after manual edits.

To convert an existing list, put point on its first item and press C-u C-c C-c: when that item has no checkbox, Org gives one to each item in the list.

A few variations are worth knowing:

  • An ORDERED property on the headline forces checkboxes to be checked in order; checking one out of order raises an error.
  • A cookie counts only direct children by default. Set org-checkbox-hierarchical-statistics to nil to count every checkbox below it.
  • To make a whole list behave like radio buttons, put #+ATTR_ORG: :radio t before it, or enable org-list-checkbox-radio-mode.
  • When a headline has both child tasks and checkboxes, set COOKIE_DATA to checkbox or todo to say which one its cookie counts.

Headlines or checkboxes?

Use child headlines whenUse checkboxes when
A step needs its own date, priority, tags or notes.A step is a single action with no metadata.
A step should appear in the agenda.Steps should stay out of the agenda.
A step may need its own subtasks or log.The list is a checklist, such as a packing list or a release checklist.

You can mix both: a task headline for each deliverable, and a checklist inside each one.

Habits

A habit is a recurring task that you want to perform regularly, such as exercising or reviewing your inbox. Org treats habits as a special case of repeating tasks and draws a consistency graph for them in the agenda, so that you can see at a glance whether you are keeping up.

Habits live in an optional module that you load first:

(with-eval-after-load 'org
  (add-to-list 'org-modules 'org-habit))

A habit needs 4 things:

  1. A not-done keyword.
  2. The property STYLE set to habit.
  3. A SCHEDULED date with a repeater, usually of the .+ kind, which counts the next date from the day you complete the task. The repeater may have a second interval after a slash: .+2d/4d means “at most every 2 days, at least every 4 days”.
  4. Logging of the done state, so that Org has a history to draw. Without it the habit still works, but the graph has no data.

Scheduling and repeaters are covered in Dates and Times. Here is a habit with a few weeks of history in its LOGBOOK:

* TODO Water the plants
SCHEDULED: <2026-11-19 Thu .+2d/4d>
:PROPERTIES:
:STYLE:    habit
:LAST_REPEAT: [2026-11-18 Wed 08:10]
:END:
:LOGBOOK:
- State "DONE"       from "TODO"       [2026-11-18 Wed 08:10]
- State "DONE"       from "TODO"       [2026-11-14 Sat 09:02]
- State "DONE"       from "TODO"       [2026-11-12 Thu 07:45]
- State "DONE"       from "TODO"       [2026-11-08 Sun 10:30]
- State "DONE"       from "TODO"       [2026-11-06 Fri 08:15]
- State "DONE"       from "TODO"       [2026-11-01 Sun 09:00]
:END:

The day agenda for 19 November 2026, generated in batch with org-habit loaded and this file (habits.org, which also contains an ordinary scheduled task) as the only agenda file, looked like this:

Day-agenda (W47):
Thursday   19 November 2026
  habits:     Scheduled:  TODO Review the weekly metrics
  habits:     TODO Water the plants        *    * *   * *   *!

The graph starts at the column given by org-habit-graph-column (default 40) and overwrites any text there, so keep habit titles short. Each character is one day: an asterisk marks a day on which you completed the habit, and ! marks today. In a live Emacs, each day is also colored: blue when the task was not yet due, green when it could have been done, yellow when it would become overdue the next day, and red when it was overdue.

Related settings: org-habit-preceding-days (default 21) and org-habit-following-days (default 7) set the span of the graph, and org-habit-show-habits-only-for-today (default t) keeps habits off future days of the agenda. In the agenda, K hides or shows all habits, and C-u K toggles the “only today” option.

Summary

  • A headline becomes a task when it starts with a TODO keyword; C-c C-t changes the state.
  • org-todo-keywords (or #+TODO: lines) define sequences of states, split into not-done and done by |; selection keys in parentheses turn on fast selection.
  • org-enforce-todo-dependencies and the ORDERED property block tasks until their children or earlier siblings are done.
  • org-log-done, the ! and @ markers, org-log-into-drawer and the LOGGING property record when and why a task changed state.
  • Priority cookies such as [#A] rank tasks for agenda sorting.
  • Statistics cookies [/] and [%] measure progress over child tasks or checkboxes, and org-after-todo-statistics-hook can act on that progress.
  • Habits are repeating tasks with a STYLE of habit and a consistency graph in the agenda.

Further reading