Clocking, effort and clock tables

Org mode can record how long you spend on each task. You clock in on a headline when you start working on it and clock out when you stop. Each session becomes a CLOCK: line in the entry's :LOGBOOK: drawer. From those lines org.nvim sums up time per subtree, shows the running clock in your statusline, compares it with an effort estimate and builds clock tables (reports) for any period.

This file is a hands-on workbook. Every top-level heading covers one part of clocking, from the basics to clock tables with many parameters. Nothing breaks if you make a mess:

• u undoes; git checkout examples/08-clocking.org restores the file.
• The file starts folded (#+STARTUP: overview). <Tab> on a heading opens it, <S-Tab> cycles the whole buffer.
• <prefix> means the key prefix, <leader>o by default (so with <leader> = space, <prefix>xi is <Space>oxi).
• g? lists every keymap of the buffer.
• Coming from Emacs? The C-c C-x ... keys work too; they are given next to the Vim-style keys below (:h org-emacs-keys).
• Lines starting with Try: are exercises, and Expect: tells you what you should see afterwards.
• Lines starting with =# = are Org comments: notes for you that are not exported.

Start Neovim with the bundled init file from the repository root, so the clock history and the running clock are kept in a scratch directory and never touch your own setup:

nvim -u examples/minimal_init.lua examples/08-clocking.org

examples/minimal_init.lua sets agenda_files to examples/*.org (so the clocks of this file also show up in the agenda's log mode and in :scope agenda clock tables), a scratch org_directory for captures, some capture templates, custom agenda commands and clock.persist_file in that scratch directory.

The dates in this file are chosen relative to Mon 2026-09-28: the sample data covers August and September 2026 up to Sun 2026-09-27, so the clock tables with a fixed period show exactly the numbers printed here.

The three basic commands:

• <prefix>xi (C-c C-x C-i) clocks in on the headline the cursor is in (anywhere in its body works too). A line CLOCK: [2026-09-28 Mon 15:04] is added to the entry's :LOGBOOK: drawer, created when missing. A clock that is already running elsewhere is clocked out first: only one clock runs at a time.
• <prefix>xo (C-c C-x C-o) clocks out. The open line is closed and the duration is written after =>: CLOCK: [2026-09-28 Mon 15:04]--[2026-09-28 Mon 15:31] => 0:27. <prefix>xo is a global key: it also works from other buffers, and so do <prefix>xq and <prefix>xj.
• <prefix>xq (C-c C-x C-q) cancels the clock: the open CLOCK: line is deleted as if you never clocked in (and an emptied drawer too).

Clocking in on the entry that is already clocked does nothing except say "Clock continues in …". Marking the clocked entry DONE clocks it out (clock.out_when_done).

Clock lines live in a drawer so they don't clutter the entry. Which drawer is used is decided, in this order, by:

1. the CLOCK_INTO_DRAWER property (inherited from parents, or set for the whole file with #+PROPERTY: CLOCK_INTO_DRAWER ...):

   nil

   no drawer, the CLOCK: lines go right under the headline;

   t

   the log drawer (LOGBOOK);

   a number N

   loose lines until there are N of them, then all of them are moved into the drawer;

   any other word

   a drawer with that name, e.g. CLOCKING;

2. the option clock.into_drawer (default true);
3. the log drawer (log_into_drawer, else LOGBOOK).

New lines are added at the top (log_states_order_reversed = true), so the most recent session comes first.

A CLOCK line has a fixed format: an inactive start timestamp, --, the end timestamp, " => " and the duration as H:MM, right-aligned to 5 chars.

CLOCK: [2026-09-23 Wed 09:30]--[2026-09-23 Wed 11:00] =>  1:30
CLOCK: [2026-09-24 Thu 23:30]--[2026-09-25 Fri 00:30] =>  1:00

The first is a normal session, the second crosses midnight (clock tables split it correctly between days). A running clock has only the start: CLOCK: [2026-09-28 Mon 15:04].

• <prefix>xj (C-c C-x C-j) jumps to the entry that is being clocked, from any buffer. Without a running clock it goes to the most recently clocked entry and says so ("No running clock, this is the most recently clocked task").
• :Org clock_in_last (C-c C-x C-x) clocks in the last clocked task again, wherever you are: handy after a break.
• org.nvim remembers the recently clocked tasks (clock.history_length, 5 by default). A count before <prefix>xi (any count from 1 to 15, e.g. 4<prefix>xi which is Emacs' C-u C-c C-x C-i) opens a menu of them:

  d

  the default task (see below),

  i

  the task that was interrupted by the current clock,

  c

  the task being clocked now,

  1 .. 9, A .. Z

  recent tasks, newest first.

• 16<prefix>xi (C-u C-u) clocks in on the entry and also marks it as the default task, offered as d in the menu. :Org clock_mark_default_task marks it without clocking in.
• 64<prefix>xi (C-u C-u C-u) starts the new clock at the time the last one stopped, so there is no gap between the two.
• A count before <prefix>xj also asks which task of the history to jump to.

With clock.persist = true (the default is false; minimal_init.lua keeps the history file in the scratch directory) the running clock and the history survive a restart of Neovim.

CLOCK lines are plain text: you can fix a forgotten clock-out or a wrong start time by editing them. Afterwards the => duration must match the timestamps again:

• <C-c><C-c> (C-c C-c) on a CLOCK line recomputes its duration. So does C-c C-y (org-evaluate-time-range) on it.
• <C-a> / <C-x> (S-Up / S-Down in Emacs, also <S-Up> / <S-Down> here) on the year, month, day, hour or minute of a CLOCK timestamp change that part and update the duration at once.
• <C-S-Up> / <C-S-Down> move both timestamps by the part under the cursor, keeping the duration: "this happened an hour earlier".
• <M-K> / <M-J> (Alt-Shift-k / Alt-Shift-j; the Emacs key is S-M-Up / S-M-Down) on a CLOCK timestamp change it and move the touching timestamp of the previous (on a clock-in) or next (on a clock-out) task of the clock history by the same amount, so two back-to-back sessions stay back to back.

The examples below are dated July 2026 so they don't change the numbers of the September clock tables further down.

An effort estimate is how long you think a task will take. It is the Effort property (effort_property), written as a duration: 0:30, 1:15, 2:00, 1d 2:00, 90 (minutes), 1h 30min, 2.5h (:h org-durations).

• <prefix>xe (C-c C-x e) asks for the effort of the entry at the cursor. When Effort_ALL is set (here: in the file header, #+PROPERTY: Effort_ALL 0:15 0:30 1:00 2:00 3:00 4:00 6:00) you pick from those values in a selection list.
• <prefix>xE (C-c C-x E) sets the effort to the next value of Effort_ALL (the first one when there is none yet).
• <prefix>xm (C-c C-x C-e) changes the effort of the task that is being clocked, wherever you are; without a running clock, of the entry at the cursor. Type 1:00 to set it, +0:15 to add a quarter of an hour, -10 to take ten minutes off.
• Column view (<prefix>C) shows Effort next to the clocked time; see 06-properties-columns.org. The #+COLUMNS: line of this file already has %Effort{:} and %CLOCKSUM.

While a clock runs, require("org").statusline() returns a string such as

⏱ [0:12/1:00] (Write the blog post)

that is: the icon (clock.statusline_icon), the time clocked on the task (0:12), its effort when it has one (/1:00) and the heading. It returns "" when no clock (and no timer, see 20-timers-reminders.org) runs.

Put it in the built-in statusline:

vim.o.statusline = "%f %m%=%{v:lua.require'org'.statusline()} %l:%c "

or in lualine:

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

What the first number counts is chosen by clock.mode_line_total or the CLOCK_MODELINE_TOTAL property of the entry (inherited):

current

only the running session,

today

everything clocked on the task today,

repeat

since the LAST_REPEAT property (the last time a repeating task was marked done),

all

all the time ever clocked on the task and its children,

auto (default)

repeat for tasks that have been repeated, else all.

Other options: clock.string_limit (cut the text), clock.heading_function (a Lua function returning the text), clock.task_overrun_text (put before the text once the effort is exceeded).

<prefix>xd (C-c C-x C-d) shows, at the end of every headline line, the time clocked in its subtree, and in the message area the total of the file. The range is clock.display_default_range (thisyear). With a count:

4<prefix>xd

only today's time ("Total file time for today: …"),

16<prefix>xd

asks for a range (today, yesterday, thisweek, lastweek, thismonth, lastmonth, thisyear, lastyear, untilnow),

64<prefix>xd

only prints the total, without the sums.

Editing the buffer, <C-c><C-c> or <prefix>xd again hides the sums.

Try: press <S-Tab> until you see all headlines (CONTENTS), then <prefix>xd.

Expect: a row of dots and the sum at the end of every headline with time: 15:15 for "Project Alpha", 11:00 for "Build the prototype", 5:30 for "Project Beta", 2:50 for "Home" (sums of 2026, the default range), and the message Total file time: 1d 11:16 (35 hours and 16 minutes), plus anything you clocked while doing the exercises. Press <prefix>xd again to hide it.

Try: 16<prefix>xd and answer lastmonth.

Expect: (on Mon 2026-09-28, "last month" is August) only August's clocks count: "Project Alpha" and "Write the spec" show 2:30, "Project Beta" and "Research competitors …" 1:30, and the message says Total file time (custom): 4:00 (4 hours and 0 minutes).

A CLOCK line without an end time that is not the running clock is a dangling clock: Neovim crashed, you quit without clocking out, the file was edited elsewhere. org.nvim finds such lines:

• when you clock in (clock.auto_clock_resolution, default "when-no-clock-is-running"; true = always, false = never),
• with <prefix>xz (C-c C-x C-z); 4<prefix>xz looks only at dangling clocks, not at the running one.

For each one it asks what to do with the time since the clock started:

Idle detection: with clock.idle_time = 10 (minutes) you get the same prompt about the running clock after ten idle minutes. The system idle time is used on macOS (ioreg) and on X11 (xprintidle); elsewhere it is Neovim's own input, so time in other programs counts as idle. clock.auto_clockout_timer = 600 (seconds) simply clocks out after that much idle time, and :Org clock_toggle_auto_clockout turns this on and off for the session.

require("org").setup({
  clock = {
    idle_time = 10,                 -- ask after 10 idle minutes
    auto_clock_resolution = true,   -- also check when a clock is running
    persist = true,                 -- keep the clock over restarts
  },
})

A clock table is a dynamic block (see 18-dynamic-blocks.org): the lines between #+BEGIN: clocktable ... and #+END: are generated from the clock lines, and regenerated whenever you ask.

• <C-c><C-c> (or <prefix>xu, C-c C-x C-u) on the #+BEGIN: line updates that one block; <prefix>xU updates every block in the file.
• <prefix>xr (Emacs: C-c C-x x then clocktable) inserts a new clock table for the entry at the cursor (:scope subtree), or for the whole file when the cursor is before the first headline. On an existing clock table it updates it. 4<prefix>xr updates the first clock table in the buffer.
• <S-Left> / <S-Right> on the #+BEGIN: line move its :block one period back / forward and update the table: 2026-09 becomes 2026-08, 2026-W39 becomes 2026-W38, today becomes today-1.

The tables below were generated by org.nvim itself. The ones with a fixed period (2026-09, 2026-W38, :tstart / :tend before Sep 28) always show these numbers; the ones marked "live" depend on today's date and on what you clocked in the exercises above.

The data they read is in the last trees of the file, after "Sample data": open them to see the LOGBOOKs.

The clock tables above read the three top-level trees that follow: "Project Alpha", "Project Beta" and "Home" (open them to see the LOGBOOKs; <prefix>xd shows their sums). All sessions are in August and September 2026, the last one on Sun 2026-09-27. Totals, to check the tables against:

:h org-clock

clocking and effort, the keys and options.

:h org-clock-resolve

resolving dangling clocks, idle time.

:h org-durations

duration syntax, duration_format.

:h org-dblocks

every clocktable parameter.

:h org-api

require("org").statusline().

:h org-config

the clock options.

07-dates.org

timestamps and how to edit them.

20-timers-reminders.org

timers, countdowns (a pomodoro) and reminders.

09-agenda.org

log mode (l) and the clock report (R) in the agenda.