Timers and reminders

org.nvim has two kinds of timers, and it can remind you of appointments:

• A relative timer counts up from zero (or from any offset). Insert its value into the text to timestamp notes relative to the start of a meeting, a talk or a recording: - 0:04:40 :: roadmap discussion.
• A countdown timer counts down from N minutes and notifies you at the end: a pomodoro, a time box for a task (it can use the task's Effort).
• Appointment reminders watch the timed entries of your agenda files and notify you a few minutes before each one starts.

Only one timer (relative or countdown) runs at a time. Both are different from clocking, which records time spent on tasks in the file: see 08-clocking.org.

• The file starts folded (#+STARTUP: overview). Put the cursor on a heading and press <Tab> to open it, <S-Tab> to cycle the whole file.
• Lines starting with Try: are exercises, Expect: says what you should see afterwards. Lines starting with # are comments about the example next to them.
• Nothing breaks if you make a mess: u undoes, and git checkout examples/20-timers-reminders.org restores the file.
• <prefix> means <leader>o. g? lists every key of the buffer.
• A count is a number typed before a key: 4<C-c><C-x>0 means press 4, then <C-c><C-x>0. Counts stand in for Emacs's C-u (4) and C-u C-u (16).

Start Neovim from the repository root with the bundled init file, so the agenda (and the reminders) see these files and your own notes are untouched:

nvim -u examples/minimal_init.lua examples/20-timers-reminders.org

examples/minimal_init.lua sets agenda_files to examples/*.org (plus a scratch directory under stdpath("state") for captures) and adds a few capture templates and custom agenda commands. It does not turn the reminders on: you start them with a command below.

Timer values change every second, so the Expect: lines below show the shape of the result (0:00:07 means "whatever the timer shows").

require("org").statusline() returns the running clock and timer as a string: ⏲ 0:12:34 for the timer, with (paused) appended while it is paused, and an empty string when nothing runs. Put it in your statusline to see the timer tick. For this session only:

:set laststatus=2
:let &statusline = "%f %= %{v:lua.require'org'.statusline()} "

With lualine, in your config:

require("lualine").setup({
  sections = {
    lualine_x = { function() return require("org").statusline() end },
  },
})

Try: run the two : commands above (type them on the command line).

Expect: the right side of the statusline is empty for now. It shows the timer once you start one in the next section.

<C-c><C-x>0 (:Org timer_start) starts a timer at 0:00:00 and says Timer start time set to 15:19:42, current value is 0:00:00. <C-c><C-x>. (:Org timer_insert) inserts the current value after the cursor, followed by a space (the timer.format option, "%s "); if no timer runs yet, it starts one first.

<C-c><C-x>, pauses the timer (Timer paused at 0:01:07) and continues it (Timer continues at 0:01:07): paused time doesn't count. <C-c><C-x>_ stops it (Timer stopped); another stop says No running timer.

Scratch area (the empty lines are where you insert):

Try: put the cursor on the empty line under "Line 1" and press <C-c><C-x>..

Expect: the message Timer start time set to HH:MM:SS, current value is 0:00:00, the line now reads 0:00:00 (plus a trailing space), and the statusline shows ⏲ 0:00:01, ⏲ 0:00:02, …

Try: wait a few seconds, then on the empty line under "Line 2" press <C-c><C-x>. again.

Expect: a larger value there, e.g. 0:00:09: the timer kept running.

Try: press <C-c><C-x>,, wait five seconds, press <C-c><C-x>, again.

Expect: Timer paused at 0:00:14, the statusline shows ⏲ 0:00:14 (paused) and doesn't move; then Timer continues at 0:00:14 and it counts on from there.

Try: press <C-c><C-x>_, then <C-c><C-x>_ once more.

Expect: Timer stopped, the statusline part disappears; then No running timer.

<C-c><C-x>- (:Org timer_item) inserts a description item whose term is the timer value, - 0:02:15 ::, and leaves you in Insert mode to type the note. It starts the timer if none runs (a count restarts it).

• On a line of plain text, it turns the line into the first item: Introductions becomes - 0:00:00 :: Introductions.
• On an item of a timer list, the new item goes below the current one (and below its continuation lines), with the same bullet; in a numbered list the number goes up (1. → 2.).
• In a list that is not a timer list (- apples), it refuses with This is not a timer list.

In a timer list, <M-CR> does the same as <C-c><C-x>- (like Emacs): it inserts the next item with the current timer value.

<C-c><C-x>; (:Org timer_countdown) starts a countdown. How long:

1. :Org timer_countdown 25 → 25 minutes. The argument is minutes, or H:MM:SS / M:SS: :Org timer_countdown 0:00:30 is 30 seconds, :Org timer_countdown 1:30 is 1 minute 30.
2. a count, 25<C-c><C-x>; → 25 minutes (Emacs's C-u for "the default timer" has no count form here: a count is always minutes);
3. otherwise the Effort of the entry at the cursor (0:25 → 25 minutes);
4. otherwise a prompt How much time left? (minutes or h:mm:ss), pre-filled with timer.default_timer when you set it (e.g. "25").

While it runs, the statusline shows the time left (⏲ 0:24:59), :Org timer_remaining says 24 minute(s) 12 seconds left before next time out, <C-c><C-x>, pauses and continues it, <C-c><C-x>_ cancels it, and <C-c><C-x>. inserts the remaining time. At zero you get a notification <title>: time out, where the title is the headline of the entry the cursor was in when you started (the file name before the first headline), with the clock.sound and clock.notification_handler options of clocking.

Starting a countdown while the relative timer runs is refused (Relative timer is running. Stop first), and the other way round (Countdown timer is running. Cancel first). Starting a second countdown asks Replace current timer?.

Timer events are User autocommands, handy for your own integrations:

vim.api.nvim_create_autocmd("User", {
  pattern = "OrgTimerDone",
  callback = function(ev)
    vim.notify("Take a break! (" .. (ev.data.title or "timer") .. ")")
  end,
})

Options (in require("org").setup({ ... })):

timer = {
  format = "%s ",        -- how timer_insert writes the value
  default_timer = "25",  -- suggested length of a countdown ("0" = none)
},
clock = {
  sound = true,          -- countdown end: terminal bell, or a sound file
  notification_handler = nil, -- function(msg) or a program name
},

Reminders watch the entries of your agenda files that have a time today or tomorrow:

• a SCHEDULED or DEADLINE date with a time (SCHEDULED: <... 16:00>),
• or a plain active timestamp with a time or time range in the entry (<... 16:10-16:25>).

Entries without a time, DONE entries and inactive timestamps are ignored.

At each of notifications.reminder_time minutes before the start (by default 12, 9, 6, 3 and 0) you get one notification, a warning in Neovim:

TODO Call the bank
Scheduled at 16:00 (in 12 min) — timers

The first line is the TODO keyword and title, the second says what kind of time it is (Scheduled, Deadline or Appointment for a plain timestamp), the time, how far off (now at 0) and the category. With system_notification (on by default) a desktop notification is shown too (osascript on macOS, notify-send on Linux).

The check runs once a minute (check_interval, in seconds). If Neovim was not running at a reminder time, the next check sends only the nearest one that was missed (at 15:57 for a 16:00 entry you get "in 3 min", once). Changes are picked up right away, even unsaved ones.

• :h org-timers and :h org-notifications: every timer command and the reminders.
• :h org-api: require("org").statusline().
• :h org-config: the timer and notifications options, clock.sound and clock.notification_handler.
• :h org-differences: the countdown count vs. Emacs's C-u.
• The other example files: 07-dates.org (timestamps with times and the date prompt), 08-clocking.org (clocking time on tasks) and 09-agenda.org (the agenda that the reminders read).