✅ Creating TODO Items

Add TODO after the headline stars to create a task:

* TODO Write documentation
** TODO Complete first draft
** TODO Review and edit

✅ Cycling TODO States

Press C-c C-t on a headline to cycle through TODO states:

(no keyword) → TODO → DONE → (no keyword)

Or use the command scimax.org.cycleTodo.

With speed commands enabled, press t at the beginning of a headline.

✅ TODO Keywords

The default TODO keywords are:

Additional states available:

Logging Completion

When you mark a task as DONE, a CLOSED timestamp is automatically added:

* DONE Write introduction
CLOSED: [2026-01-13 Mon 15:30]

Changing a heading to any state that is not done (another TODO keyword, or no keyword) removes the CLOSED timestamp. Other planning keywords on the same line (SCHEDULED, DEADLINE) are kept. As in org-mode this happens in either direction (S- or S-), whatever the previous state was.

✅ Setting Priorities

Add a priority cookie after the TODO keyword:

* TODO [#A] Urgent and important task
* TODO [#B] Important but not urgent
* TODO [#C] Nice to have

✅ Priority Levels

✅ Priority Commands

You can also set priority through the command palette: scimax.org.setPriority

✅ Statistics Cookies [/]

✅ Checkbox States

✅ Toggling Checkboxes

Press C-c C-c with cursor on a checkbox line to toggle it.

Or use scimax.org.toggleCheckbox.

* Packing List [1/2]
- [-] Clothes [2/3]
  - [X] Shirts
  - [X] Pants
  - [ ] Socks
- [X] Toiletries [3/3]
  - [X] Toothbrush
  - [X] Soap
  - [X] Towel

✅ Inserting Checkboxes

Type - [ ] followed by space to manually create a checkbox item.

✅ NEXT

Indicates the very next action to take:

* NEXT Call client about project requirements

Use NEXT for tasks you're actively working on or will work on immediately.

✅ WAITING

Task is blocked waiting for someone or something:

* WAITING Review from manager
:PROPERTIES:
:WAITING_ON: John Smith
:END:

✅ HOLD

Task is paused but not cancelled:

* HOLD Website redesign
Paused until Q2 budget approval.

✅ CANCELLED

Task won't be done (but kept for records):

* CANCELLED Old feature request
No longer relevant after product pivot.

✅ Workflow Example

A typical task progression:

TODO → NEXT → WAITING → NEXT → DONE
         ↓
       HOLD → NEXT → DONE
         ↓
     CANCELLED

✅ Defining Custom States

Add #+TODO: at the top of your org file (before any headings):

#+TODO: DRAFT REVIEW | PUBLISHED REJECTED

The | separates active (incomplete) states from done (complete) states. When you cycle TODO states, they will follow this sequence:

(none) → DRAFT → REVIEW → PUBLISHED → (none)

✅ Multiple TODO Lines

You can define multiple workflow sequences:

#+TODO: TODO IN-PROGRESS | DONE
#+TODO: BUG INVESTIGATING FIXING | FIXED WONTFIX

All states from all #+TODO: lines are recognized.

✅ Without Pipe Separator

If you omit the |, the last state is treated as done:

#+TODO: IDEA DRAFT REVIEW PUBLISHED

This makes PUBLISHED the done state.

✅ Syntax Variants

These keywords are all equivalent:

✅ Example Workflows

#+TODO: DRAFT REVIEW APPROVED | MERGED REJECTED

* DRAFT Implement new feature
* REVIEW Fix login bug
* APPROVED Update documentation

#+TODO: IDEA OUTLINE WRITING EDITING | PUBLISHED ARCHIVED

* WRITING Blog post about org-mode
* EDITING Tutorial on source blocks

#+TODO: BACKLOG SPRINT IN-PROGRESS TESTING | DONE CANCELLED

* IN-PROGRESS User authentication
* TESTING Payment integration

✅ LOGBOOK Drawer

State changes are recorded in the LOGBOOK drawer:

* DONE Complete documentation
CLOSED: [2026-01-13 Mon 16:00]
:LOGBOOK:
- State "DONE"       from "TODO"       [2026-01-13 Mon 16:00]
- State "TODO"       from "WAITING"    [2026-01-12 Sun 10:00]
- State "WAITING"    from "TODO"       [2026-01-10 Fri 14:30]
:END:

✅ Timestamps on State Changes

When enabled, each state change adds:

• A timestamp showing when the change occurred

• The previous state

This creates a complete history of task progress.

✅ Enabling Progress Logging

Progress logging is off by default. Enable it with:

{
  "scimax.org.logRepeat": "time"  // or "note" for note prompts
}

#+STARTUP: logrepeat       ;; Enable with timestamp
#+STARTUP: lognoterepeat   ;; Enable with note prompt
#+STARTUP: nologrepeat     ;; Disable

* TODO Weekly review
:PROPERTIES:
:LOGGING: logrepeat
:END:
DEADLINE: <2026-01-30 Fri +1w>

✅ Priority Order

Settings are resolved in this priority order (highest to lowest):

1. Heading :LOGGING: property

2. File #+STARTUP: keywords

3. Global scimax.org.logRepeat setting

✅ Log Output Example

When you mark a repeating task as done with logging enabled:

* TODO Weekly review
DEADLINE: <2026-02-06 Fri +1w>
:PROPERTIES:
:LAST_REPEAT: [2026-01-23 Fri 07:31]
:END:
- State "DONE"       from "TODO"       [2026-01-23 Fri 07:31]

The log shows:

• LAST_REPEAT property with when the task was last completed

• State change entry showing the transition from TODO to DONE

✅ Logging to Drawer

By default, log entries appear in the body text. To log into a drawer:

{
  "scimax.org.logIntoDrawer": true       // Use :LOGBOOK: drawer
  // or
  "scimax.org.logIntoDrawer": "MYLOG"    // Use custom drawer name
}

Or use file-level #+STARTUP: logdrawer to enable.

With drawer logging, the output becomes:

* TODO Weekly review
DEADLINE: <2026-02-06 Fri +1w>
:PROPERTIES:
:LAST_REPEAT: [2026-01-23 Fri 07:31]
:END:
:LOGBOOK:
- State "DONE"       from "TODO"       [2026-01-23 Fri 07:31]
:END:

✅ Note Prompts

When logRepeat is set to "note", you'll be prompted to enter a note when completing a repeating task. The note is included in the log entry:

- State "DONE"       from "TODO"       [2026-01-23 Fri 07:31] \\
  Completed early because of deadline change.

If you cancel or leave the note empty, the entry is logged without a note.

✅ Configuration Summary

✅ Adding Tags

Tags appear at the end of the headline, enclosed in colons:

* TODO Review quarterly report                               :work:urgent:
* TODO Buy groceries                                         :personal:errands:

✅ Tag Commands

Setting tags opens a multi-select list of every tag already in use: the tags in the current file and its #+TAGS: / #+FILETAGS: lines, plus every heading tag in the database, each with how many headings carry it. Check or uncheck tags and press Enter. The heading's current tags start out checked.

You don't have to tick the box: as you type, the best matching tag is highlighted (the tag typed in full, else the first tag starting with the text, else the first one containing it), and Enter adds it along with any checked tags. Use the arrow keys to highlight a different one first. The "new tag" entry is highlighted only when no existing tag contains what you typed, so proj Enter adds :project:; to make :proj: as well, arrow down to its "new tag" entry before pressing Enter. With nothing typed, Enter applies exactly the checked tags, so unchecking all of them removes the heading's tags.

To add a tag nobody has used yet, type it. It shows up at the top as a "new tag". If it looks like an existing tag (a plural, a typo, or a different capitalization), the entry warns you, for example:

groupmeetings   new tag
  ⚠ similar to existing: :groupmeeting:

That makes it easy to reuse :groupmeeting: instead of starting a second spelling of it.

✅ Inherited Tags

Child headlines inherit their parent's tags:

* Work Projects                                              :work:
** TODO Project A                                            :client1:
This task has both :work: and :client1: tags.
** TODO Project B                                            :internal:
This task has both :work: and :internal: tags.

✅ Common Tag Conventions

Filtering by Tags

Use agenda views or search to filter tasks by tag:

• scimax.db.searchByTag - List every heading tag in the database with its count (like Emacs org-tags-view), then pick one to see the headings that carry it, including headings that inherit it from a parent

• scimax.agenda.filterByTag - Filter agenda by tag

✅ SCHEDULED

When you plan to start or work on a task:

* TODO Write report
SCHEDULED: <2026-01-15 Wed>

✅ DEADLINE

When a task must be completed by:

* TODO Submit proposal
DEADLINE: <2026-01-20 Mon>

✅ Both Together

* TODO Complete project
SCHEDULED: <2026-01-15 Wed> DEADLINE: <2026-01-25 Sat>

✅ Adding Dates

Or use commands:

• scimax.org.schedule

• scimax.org.deadline

See Timestamps for more on date formats.

✅ Clocking In/Out

✅ Clock Entries

Clock entries are stored in the LOGBOOK drawer:

* TODO Working on documentation
:LOGBOOK:
CLOCK: [2026-01-13 Mon 09:00]--[2026-01-13 Mon 10:30] =>  1:30
CLOCK: [2026-01-12 Sun 14:00]--[2026-01-12 Sun 16:00] =>  2:00
:END:

✅ Total Time

The total clocked time appears in the properties or can be calculated for reports.

✅ Setting Effort

Add an EFFORT property:

* TODO Review document
:PROPERTIES:
:EFFORT: 1:30
:END:

Effort Format

Any of these formats work, in the property and in the Set effort prompt (speed key e, or Set Effort... in the project view):

• 0:30 - 30 minutes (H:MM)

• 2:30 - 2 hours 30 minutes

• 3h or 1.5h - hours

• 45m - minutes

• 2d - 2 days; a day counts as 8 hours

The Set effort list offers common values (0:15 to 8:00, 2d, 5d); choose Custom... to type another one.

✅ Viewing All TODOs

Use scimax.agenda.todoList or scimax.db.showTodos to see all tasks.

✅ Deadline View

Use scimax.agenda.deadlines to see upcoming and overdue deadlines.

✅ Filtering Options

• By priority (A, B, C)

• By tag

• By date range

• By TODO state

See Agenda for complete agenda documentation.

✅ Task Granularity

Make tasks actionable:

* TODO "Write documentation"           ; Too vague
* TODO Write introduction section      ; Better - specific and actionable

✅ Use NEXT for Clarity

Always have at least one NEXT task to know what to work on:

* Project: New Feature
** DONE Design architecture
** NEXT Implement core module           ; ← Clear next step
** TODO Write tests
** TODO Deploy to staging

✅ Regular Review

Periodically review tasks to:

• Move stale TODO items to HOLD or CANCELLED

• Update WAITING items

• Identify next actions

✅ Tags vs Hierarchy

Use hierarchy for project structure, tags for cross-cutting concerns:

* Work                                                       :work:
** Project A
*** TODO Task requiring phone                                :@phone:
*** TODO Task requiring computer                             :@computer:
** Project B
*** TODO Another phone task                                  :@phone:

Now you can filter by @phone to see all phone tasks across projects.

✅ Keybindings

✅ Speed Commands (at heading start)

✅ Commands