Dates, scheduling and clocking

Put dates on entries, plan work with scheduled dates and deadlines, and record the time you spend.

Timestamps

A timestamp is a date, optionally with a time, in angle brackets (active) or square brackets (inactive):

<2026-10-07 Wed>
<2026-10-07 Wed 14:30>
<2026-10-07 Wed 10:00-11:30>
<2026-10-07 Wed>--<2026-10-09 Fri>
[2026-10-07 Wed 09:12]

• Active timestamps put the entry on the agenda for that day. Inactive ones are records only.
• 10:00-11:30 is a time range within one day. <…>--<…> is a range of days; both ends must be of the same kind.
• orgstar writes day names in English. When reading, it accepts a day name in any language, as Org does.

Repeaters and warning periods

After the date and time, a timestamp can carry a repeater and a warning or delay:

<2026-10-07 Wed +1w>
<2026-10-07 Wed 08:00 ++1d>
<2026-10-07 Wed .+2w>
<2026-10-31 Sat -3d>
<2026-10-31 Sat +1m -5d>
<2026-10-07 Wed .+2d/4d>

Units are h (hours), d, w, m and y. What happens when a repeating task is done is described under "Repeating tasks".

Diary sexps

The agenda also reads <%%(…)> timestamps and %%(…) lines with Emacs diary expressions such as diary-float, diary-anniversary, diary-block and diary-cyclic, and their org- counterparts. See The agenda for the functions that are supported. orgstar does not insert or edit these.

Inserting timestamps

Both ask for a date in the echo area (see "The date prompt"). With the caret on an existing timestamp, they replace it with the date you give, keep its repeater, and start from its date and time. In a range of days, the caret picks the end: with the caret between the two dashes of -- or after them, the second timestamp is replaced and the prompt starts from its date; before that, the first. Run the command again right after inserting a timestamp to add a second one and make a range, <…>--<…>; the second date starts from the timestamp at the caret.

Org's prefix arguments are not available: to include the current time, type it, or use a relative time such as +0h (see below).

The date prompt

Every command that asks for a date shows the same prompt (org-read-date): a text field, the date the text reads as, and a month calendar.

• Type a date in any of the forms below. The line above the field shows the result, such as <2026-10-09 Fri 15:00>, as you type; for an inactive timestamp it is in square brackets, [2026-10-09 Fri 15:00].
• Click a day in the calendar to answer with that day. A time you typed is kept.
• S-<left> and S-<right> in the field move the answer one day; S-<up> and S-<down> move it one week.
• RET accepts. An empty answer takes the default: the date of the timestamp being changed, or today.
• Esc cancels.

orgstar reads the answer as Org 9.8 does, with org-read-date-prefer-future t: a date given without a year, or without a month, is taken to be the next such date from today.

Forms without a sign, such as fri, 15 or 10:00, fill in what is missing from the default date: the date of the timestamp being changed, or today. Forms with a single sign count from today; ++ counts from the default date. Two-digit years are read relative to the current year. Words the prompt does not recognize are ignored, so tomorrow gives the default date.

Changing dates

These keys act on the timestamp when the caret is in one. Elsewhere the same keys do other things, such as changing the TODO keyword or priority on a heading line (TODOs and tags). In the Doom preset they work in normal and insert state, and C-S-h, C-S-j, C-S-k and C-S-l do the same as S-<left>, S-<down>, S-<up> and S-<right>.

S-<up> and S-<down> change the part of the timestamp under the caret:

• the year, month or day (on the day name, the day);
• the hour, or the minute in steps of 5 (org-time-stamp-rounding-minutes), first rounding to a multiple of 5;
• in a time range, the end time; changing the start time moves the end time with it;
• the number or unit of a repeater or warning (the unit cycles d, w, m, y);
• on the opening or closing bracket, the timestamp switches between active and inactive.

S-<left> and S-<right> move the whole timestamp by a day, wherever the caret is in it. The day name is rewritten after every change. In a range of days, each end changes on its own.

C-c C-c on a timestamp rewrites its day name to match its date. C-c C-y shows the length of the range at the caret, or of the first range on the line, such as 2 days 3 hours; on a clock line it recomputes the clock's duration.

SCHEDULED and DEADLINE

A planning line goes directly under the heading:

* TODO Submit the tax return
DEADLINE: <2026-10-31 Sat -7d> SCHEDULED: <2026-10-20 Tue>

• SCHEDULED is the day you plan to start. The agenda shows the entry from that day until it is done.
• DEADLINE is the day it is due. The agenda warns about it 14 days ahead (org-deadline-warning-days in config.toml), or as the timestamp's own -Nd says.

Schedule and Set Deadline ask for a date, starting from the entry's current one and its time. They replace an existing date, keep its repeater and warning, and remove a CLOSED stamp from the entry. Remove Schedule and Remove Deadline have no default keys; run them from the Org menu or the command palette (Keys).

With org-log-reschedule or org-log-redeadline set to time or note in config.toml, or the matching #+STARTUP words, orgstar logs each change of an existing date and each removal:

* TODO Submit the tax return
SCHEDULED: <2026-10-22 Thu>
- Rescheduled from "[2026-10-20 Tue]" on [2026-10-19 Mon 08:40]

Where these notes go, and the #+STARTUP words, are covered in TODOs and tags.

Repeating tasks

When an entry with a repeater in an active timestamp changes from an active TODO keyword to a done one (org-auto-repeat-maybe), orgstar does not leave it done:

1. The keyword returns to the first keyword of its sequence. In a #+TYP_TODO sequence it returns to the keyword it had. A REPEAT_TO_STATE property, inherited from ancestors, names another keyword to use.
2. CLOSED is removed.
3. With org-log-repeat on (the default, time), the LAST_REPEAT property is set to the current time and a state note is logged, such as - State "DONE" from "TODO" [2026-10-07 Wed 18:02].
4. A SCHEDULED date without a repeater is removed.
5. Every active timestamp with a repeater in the entry moves forward:
   • +N moves it by N once, which may leave it in the past.
   • ++N moves it by N until it is after today (for hours, after now).
   • .+N sets it to today and then moves it by N. With hours, .+Nh, the new time is N hours after the current time, to the minute, and a time range loses its end time.
6. -- delays in those timestamps are removed.

* TODO Water the plants
SCHEDULED: <2026-10-07 Wed .+3d>

Marking this done on 7 October gives:

* TODO Water the plants
SCHEDULED: <2026-10-10 Sat .+3d>
:PROPERTIES:
:LAST_REPEAT: [2026-10-07 Wed 18:02]
:END:
- State "DONE"       from "TODO"       [2026-10-07 Wed 18:02]

A repeater of 0 (+0d) does not repeat. An hourly repeater needs a time in the timestamp; without one, orgstar reports "Cannot repeat in N hour(s) because no hour has been set". Inactive timestamps never repeat.

To turn the repeat note off for a file, use #+STARTUP: nologrepeat; lognoterepeat asks for a note instead.

Effort

Effort estimates live in the Effort property.

Set Effort asks for a value, such as 0:30 or 2:00, starting with the current one. If the entry, an ancestor, or a #+PROPERTY: Effort_ALL line defines Effort_ALL, its values are offered as choices; you can also type another value.

#+PROPERTY: Effort_ALL 0:15 0:30 1:00 2:00 4:00

Effort appears in column view and in clock tables with :properties ("Effort"). orgstar does not compare the running clock with the effort estimate.

Timers

orgstar has Org's relative timer, which counts up from when it starts, and its countdown timer (org-timer). One timer runs at a time, for every file; it shows in the mode line as <0:01:23> (above the text on iOS) and stops when orgstar quits.

M-RET in a timer list inserts a timer item, so notes taken in a meeting can be stamped as they're written:

- 0:00:05 :: Introductions
- 0:04:40 :: Budget

When a countdown ends, orgstar shows Heading: time out, and a notification when it isn't in front. Starting a relative timer during a countdown, or a countdown during a relative timer, is refused until the other is stopped. org-timer-format ("%s ") sets what Insert Timer Value writes, and org-timer-default-timer the countdown Set Countdown Timer… offers; see Configuration.

Clocking

Clocking records the time you work on an entry as CLOCK: lines in its LOGBOOK drawer.

The Emacs keys are Org's own, and work in the Doom preset too, as every C-c key does. Commands without a key in your preset are in the command palette and in Org ▸ Clock, which lists every clock command with its keys, followed by the recent entries. In the agenda, I, O and X clock in, out and cancel for the entry at the line (The agenda). Capture templates can clock in too (Capture).

orgstar has no C-u forms of these commands. Clock In to Recent Entry… and Go to Recent Clocked Entry… stand for C-u C-c C-x C-i and C-u C-c C-x C-j.

Clocking in and out

Clock In starts a clock on the heading at the caret and inserts a line at the top of its LOGBOOK drawer, creating the drawer after the planning line and property drawer if needed (see "The clock drawer" below for other drawers):

* TODO Write the report
:LOGBOOK:
CLOCK: [2026-10-07 Wed 09:00]
CLOCK: [2026-10-06 Tue 14:00]--[2026-10-06 Tue 15:30] =>  1:30
:END:

• Only one clock runs at a time. Clocking in while another clock runs clocks that one out first, and remembers it as the interrupted task (i in the selection below).
• Clocking in on the entry whose clock is running changes nothing and says Clock continues in "Write the report".
• CLOCK: lines outside a drawer move into the new drawer the first time you clock in on that entry.
• With org-clock-in-switch-to-state set to a keyword in config.toml, Clock In gives the entry that keyword first (unless it has it), logging and checking dependencies as C-c C-t does. A file without the keyword can't be clocked in, as in Org: "State `NEXT' not valid in this file".
• Clock Out completes the line with the end time and the duration in hours and minutes. Clocks of zero minutes are kept, unless org-clock-out-remove-zero-time-clocks is true; then the line goes and the message ends with "LINE REMOVED".
• With org-clock-rounding-minutes set to N, the clock starts at the multiple of N minutes nearest now that isn't later, and stops at the nearest multiple; with 5, clocking in at 14:47 starts at 14:45.
• Marking the clocked entry done clocks out (org-clock-out-when-done, on by default as in Org; set it to "nil" to keep the clock running, or to keywords that clock out). orgstar watches the entry's heading line, so typing a done keyword yourself clocks out too.
• When the entry has an Effort, a notification says "Task `…' should be finished by now. (1:00)" once the time clocked on it and its subtree passes it, counting earlier clocks as org-clock-mode-line-total auto does (since LAST_REPEAT for a repeating task) or as its CLOCK_MODELINE_TOTAL says.
• Cancel Clock removes the running clock's line, and the drawer if it is left empty.
• Go to Clocked Entry opens the file and moves the caret to the running clock's line. With no clock running, it goes to the most recently clocked entry and says "No running clock, this is the most recently clocked task".

With no clock running, Clock In first asks about open clocks; see Open clocks below. So do the agenda's I and a capture template's clock-in.

orgstar remembers the running clock and the clock history across restarts, in clock.json in ~/Library/Application Support/Orgstar. If the open CLOCK: line is deleted from the file, Clock Out reports "Clock start time is gone" and forgets the clock.

orgstar follows the open CLOCK: lines in the files, so a clock started or stopped in Emacs, or on another device, is the one it shows:

• At launch, and as your folders load, it looks for open clock lines in the agenda files; when a file changes on disk, in that file.
• With no clock running, the most recently started open clock it hasn't seen before becomes the running clock, and the status line says so. Older open clocks stay dangling; Clock In asks about them, as described in Open clocks below.
• When the running clock's line is closed (Emacs clocked out) or removed, the clock stops here too, with the message "The clock in … was stopped elsewhere".

Clocking out in orgstar closes the line as Org does, so Emacs sees a finished clock when it reverts the file. orgstar does not read Emacs's org-clock-persist file, so Emacs learns of a clock started here only from the line, when it next resolves clocks.

These parts of Org's clocking are not implemented:

• org-clock-in-switch-to-state and org-clock-out-switch-to-state as functions, and org-clock-sound: the notification uses the system's sound.

The clock drawer

Where clock lines go follows org-clock-into-drawer in config.toml, or an entry's CLOCK_INTO_DRAWER property, which its subtree inherits:

An existing drawer of that name always takes the new line.

The running clock

While a clock runs, orgstar shows it in three places, refreshed every 30 seconds:

• the mode line under the editor: ⏱ 0:42 Write the report;
• the window's toolbar;
• the macOS menu bar, with the elapsed time.

The time shown is the time since you clocked in, not the entry's total. Each of them opens a menu with Clock Out, Cancel Clock and Go to Clocked Entry. The toolbar's menu also has Clock In to Recent Entry…, Go to Recent Clocked Entry… and the recent entries. The menu bar item also has Clock In to Recent Entry…, Clock Report and a Recent Entries section. Choosing a recent entry clocks in to it.

Recent entries

orgstar keeps a clock history, as org-clock-history. Every clock-in, including one from the agenda or a capture template, puts the entry first in the history and removes its other entries there. The history holds org-clock-history-length entries (5 by default); the oldest go first.

Entries are found again after edits by their ID property, else by the heading's position among the file's headings together with its title, else by the title alone. An entry that can't be found is dropped from the history the next time an entry is added, and left out of the selection.

Clock In to Recent Entry… and Go to Recent Clocked Entry… ask for an entry in the echo area, as org-clock-select-task does. Each line shows its key, the entry's category padded to 12 characters, and the heading with its TODO keyword and priority, under these sections:

Type a key to choose. q, x or Esc leave the question. With an empty history the commands say "No recent clock"; a key that isn't listed says "Invalid task choice X".

Clock In to Last Entry clocks in to the first entry of the history, the same as 1. With no clock running it says "Clocking back: Write the report (in work.org)"; with an empty history, "No last clock".

Mark as Default Clock Task makes the heading at the caret the d entry and says "Default clock task: Write the report"; Org sets it without a message. As in Org, the default task lasts until you quit orgstar.

Open clocks

An open clock is a CLOCK: line with a start and no end. Org calls one that isn't the running clock dangling, for example after orgstar or Emacs quit while it ran, or a line synced from another machine.

When you clock in with no clock running, orgstar first looks for open clocks in the org files of your folders and in the open buffers (org-clock-auto-clock-resolution set to when-no-clock-is-running), and asks about each one:

Dangling clock started 95 mins ago [jkKtTgGSscCiq]?

Clocking in from the agenda (I) or from a capture template with clock-in asks too, as org-clock-in does in Org. A capture template resolves open clocks as of when the capture began, which is when its clock starts. On the Mac, the questions for an agenda or capture clock-in are asked in the main window's echo area.

Resolve Open Clocks… asks the same about every open clock, the running one included, and says "No open clocks" when there are none.

Unlike Org, orgstar doesn't show the clock's line while it asks; j opens it afterwards, except while clocking in.

The answer is a key, as in org-clock-resolve. The idle time is the time since the clock started, for an open clock, or since you stopped using the Mac, for an idle one (see Idle time below).

• k, K, g and G ask for minutes with the default in the question, as Keep how many minutes (default 95):; Return with an empty field takes the default.
• t and T ask Date+time: with Org's date syntax, as 14:00 or -1h.
• If the clock ran less than 45 seconds before the idle time began, s removes the line and starts a new clock now, and S removes it. For an open clock all its time is idle time, so s and S remove its line.
• Any other key asks again.

While clocking in, an answer never restarts the clock it resolves: where a key would start a new clock or keep one running, the line ends instead, and the clock you asked for starts. Resolving an open clock that isn't running with k and all the minutes, outside a clock-in, makes it the running clock.

When K, T or S ends a clock outside a clock-in, the next clock-in, from the agenda or a capture template too, asks:

You stopped another clock 12 mins ago; start this one from then? (y or n)

y starts the new clock when the old one ended.

Idle time

On the Mac, set org-clock-idle-time to a number of minutes, or turn on Settings ▸ Agenda ▸ "Ask what to do with idle time while clocked in", to be asked about time away from the Mac. The default, 0, never asks, as nil does in Emacs.

While a clock runs, orgstar checks every minute how long the Mac has had no keyboard or mouse input, in any app. Past the limit, it requests your attention, which bounces its Dock icon while another app is active, and asks in the echo area:

Clocked in & idle for 17.3 mins [jkKtTgGSscCiq]?

The keys are those in the table above, with the idle time starting when input stopped. The iOS app has no idle detection.

Editing clock lines

You can edit clock lines by hand. S-<up>, S-<down>, S-<left> and S-<right> change their timestamps as anywhere else, and then write the duration after => again, as H:MM. After typing changes yourself, press C-c C-c (or C-c C-y) on the line: orgstar fixes both day names and writes the duration again (org-clock-update-time-maybe).

C-c . on a clock line's range replaces one of its timestamps, as in any range of days (see "Inserting timestamps").

A line of the form CLOCK: => 1:15, with only a duration, counts towards clock tables.

Clock summaries

The inspector

View ▸ Show or Hide Columns and Clock opens the inspector beside the editor. Its Clock tab lists the clocked time per heading in the open file for Today, This Week (weeks start on Monday) or All, with a total. Clicking a heading moves to it. Only finished clocks count.

The clock report window

Clock Report (SPC m c R and SPC z t in Doom, the command palette, or the clock menus) opens a window that totals time across files. Choose files on the left; files with clock lines are selected when the window opens. Turn on From to limit the report to a range of dates. The report is an Org table of time per date and heading, with a total after each ISO week:

#+title: Time Report

| Date         | Code                                          | Hours |
|--------------+-----------------------------------------------+-------|
| 2026-10-05   | Write the report                              |  2:15 |
| 2026-10-06   | Write the report                              |  1:30 |
|--------------+-----------------------------------------------+-------|
| 2026-W41     | WEEK TOTAL                                    |  3:45 |

Copy puts it on the clipboard; Save writes it to a file.

Clock tables

A clock table is a dynamic block that orgstar fills with a summary of clocked time (org-clocktable-write-default).

C-c C-c on the #+BEGIN: line also updates the block; in the Mac preset, ⌃⌘X does.

Insert or Update Clock Table updates the clock table at the caret. Elsewhere it inserts a new one, with :scope subtree inside an entry or :scope file before the first heading, and fills it:

#+BEGIN: clocktable :scope file :maxlevel 2 :block thisweek
#+CAPTION: Clock summary at [2026-10-07 Wed 17:00], for week 2026-W41.
| Headline         | Time   |      |
|------------------+--------+------|
| *Total time*     | *5:15* |      |
|------------------+--------+------|
| Project Alpha    | 5:15   |      |
| \_  Design       |        | 3:00 |
| \_  Write code   |        | 2:15 |
#+END:

Times are written as H:MM, with a day count such as 2d before them for a day or more. A heading's time includes its subtree's. Only finished clock lines and CLOCK: => H:MM lines count; a running clock does not. A COMMENT prefix is left out of headlines.

Parameters

:scope tree covers the top-level tree around the block; tree2 the tree from its level-2 ancestor, and so on. :block takes precedence over :tstart and :tend. Clocks that cross the start or end of the range count only the part inside it.

:block values:

week, month and year are the same as thisweek, thismonth and thisyear, and a +N suffix moves forward.

A #+TBLFM line already under the table is kept when the table is updated, unless :formula gives one.

Other files

:scope agenda sums the agenda files (see The agenda), and agenda-with-archives adds each one's archive files: the one its #+ARCHIVE: or org-archive-location names, and those its ARCHIVE properties name, where they exist. file-with-archives is this file with its archives, summed as one file. A list names files, relative to this file's folder; a folder in the list gives its .org files, which Org doesn't do. Over several files the table gets a File column and a row with each file's total before its headings:

| File     | Headline         | Time   |      |
|----------+------------------+--------+------|
|          | ALL *Total time* | *3:30* |      |
|----------+------------------+--------+------|
| work.org | *File time*      | *1:30* |      |
|          | Project Alpha    | 1:30   |      |
|          | \_  Design       |        | 0:30 |

Other files are read from disk, so unsaved edits in another open file don't count; this file's buffer does. With :link t, headlines link to file:PATH::*Heading.

Steps

:step writes a table for each day, week (from :wstart), half month, month (from :mstart), quarter or year of the range, each after a line such as Daily report: [2026-10-05 Mon] or Weekly report starting on: [2026-10-05 Mon], without captions. It needs :block, or both :tstart and :tend.

:match takes a match such as "work", "-home" or "TODO=\"DONE\"". Headings that don't match add none of their own time, but the headings above a matching one are still listed with its time.

Not supported: :formatter, which is ignored along with other unknown parameters, and scopes given as functions. Labels are in English only.

Habits

A habit is a repeating task whose history the agenda shows as a consistency graph (org-habit). Define one with the STYLE property and a SCHEDULED date with a repeater:

* TODO Go for a run
SCHEDULED: <2026-10-07 Wed .+2d/4d>
:PROPERTIES:
:STYLE:    habit
:END:
:LOGBOOK:
- State "DONE"       from "TODO"       [2026-10-05 Mon 07:30]
- State "DONE"       from "TODO"       [2026-10-03 Sat 07:10]
:END:

• The repeater sets the interval you aim for. Use .+ for most habits, so the next date counts from when you last did it.
• The optional /4d sets the longest acceptable interval. It must be longer than the repeater.
• The repeater's unit must be d, w, m or y. A month counts as 30.4 days and a year as 365.25.
• The history comes from the entry's state notes for done keywords and its CLOSING NOTE lines, up to 28 of them. Those are written when the task repeats, as long as org-log-repeat is on (the default), or when org-log-done is note.

How habits appear in the agenda, with the graph covering 21 days back and 7 ahead, is described in The agenda.

Reminders

orgstar can post a macOS notification before entries that have a time of day, as Emacs's appt does with org-agenda-to-appt.

• It covers the agenda's files and the next 7 days: scheduled items, deadlines, plain active timestamps and date ranges with a time, that are not done.
• Each reminder comes the lead time before the entry's time: 12 minutes by default (appt-message-warning-time). An APPT_WARNTIME property on the entry, in minutes, overrides it.
• If the warning time has already passed when orgstar sets a reminder but the entry has not started, the notification comes at once.
• At most 64 reminders are pending at a time, the earliest first.
• The notification shows the entry's text, its time, and its category. Clicking it opens the entry. Notifications also show while orgstar is the active app.

orgstar updates the reminders a couple of seconds after you stop editing, when files change, and every hour. The agenda window shows how far ahead reminders are set. Reminders already set still arrive after you quit orgstar; changes to your files are taken into account the next time it runs.

Turn reminders on or off, and set the lead time from 0 to 120 minutes, in Settings ▸ Agenda; in config.toml the keys are reminders under [orgstar] (default true) and appt-message-warning-time. The first time, macOS asks whether orgstar may post notifications; if you decline, the agenda says so, and you can change it in System Settings ▸ Notifications. The iOS app's reminders are described in iOS.