Tasks and reminders

The Todo tab reads todo.txt files (todo.txt grammar: x (A) 2016-05-20 2016-04-30 description +project @context #tag key:value).

Todo and Calendar are Features. Switched off, todo.txt and calendar.txt stay plain files, the reminders already scheduled are cancelled, and none is scheduled until it is switched on again.

The list

The open tasks come in sections that follow the sort:

  • By due date (the default): Overdue, Today, Next 7 days, Later and No date.
  • By priority: one section per letter, A first, then No priority.
  • By creation date: one plain list, without headers.

Each header shows how many tasks it holds; tap it (or click it) to fold the section or open it again. A section with nothing in it is not shown. Which sections are folded is remembered on each device, for each library.

There is no standing total of open or done tasks, on purpose: the numbers are in the section headers, and while a filter is on the strip says how many open tasks are shown out of how many. The plain list sorted by creation date has no header, so it shows no count until a filter is on.

Done is the last section: the tasks of done.txt, newest first, folded until you open it. A done task is checked and shows the day it was finished; unchecking it puts it back among the open ones.

Filter narrows both the open tasks and Done: a due range (All dates, Overdue, Today, Next 7 days, No date) and any number of +project, @context and #tag chips, which all have to match. Sort picks the order: due date, priority or creation date. A task’s priority shows as a small badge, except when the list is sorted by priority, where its section already says it. While a filter is on, a strip under the bar lists it as chips you can remove one by one, with how many open tasks are shown out of how many, and Clear to drop them all.

On a phone, help, Filter and Sort are in the app bar; the Filter icon takes the accent color and a dot while a filter is on. On a desktop they are a toolbar over the list — Filter (Filter · 2 with two filters on) and Sort as pills, then Add task and help — or four icons in a pane too narrow for the pills.

Line anatomy

  • x marks completion; (A)…(Z) is priority; dates are completion-then-creation on done lines, creation-only otherwise.
  • +project, @context, #tag tokens carry filing meaning and power the filter chips.
  • key:value tags are annotations. Known: due:YYYY-MM-DD (badge, filter), rem:YYYY-MM-DDTHH:MM (schedules a reminder) and rec: (the task repeats, see Recurring tasks below).
  • [[Note]] is a link to a note (see Links to notes below); inside the brackets a +, @, # or key: is part of the link, not a token.
  • Untouched lines round-trip byte-stable; edits normalize spacing.

A task can point at a note: write a wikilink in its text, the way a note does. (A) Call the plumber [[House/Repairs]] due:2026-11-02 links the note Repairs; a task can hold any number of links. A heading ([[Repairs#Boiler]]), a block ([[Repairs#^b7]]) and an alias ([[Repairs|the plumber's notes]]) are written as in a note, and a Markdown link to a note ([plumber](House/Repairs.md)) is read too — Niman writes wikilinks. The link is resolved like any other, from the library root: a bare name finds the note anywhere, a path finds it by its tail, and case does not matter. See links for the forms.

The Todo list draws each link as a chip with the note’s name, and the link’s words are taken out of the task’s text, so they are not shown twice. A link to a heading reads Repairs › Boiler, one to a block Repairs › ^b7; an alias, when you wrote one, is the chip’s text. A chip you have just typed shows at once, from the words, and settles when the library has answered: it never shows as raw [[…]], and nothing in the row moves when it does. On a phone the chips sit under the task, after the due date and the tokens; on a desktop they follow the task’s text on its line.

Where a task is shown as plain text — a reminder’s notification, the home-screen widget, the Home’s Tasks due tile, the day’s due list in the journal — a link reads the same words as its chip, Repairs or Repairs › Boiler, never [[…]].

  • Tap (or click) a chip to open the note. A heading or a block link opens the note scrolled to it, as a wikilink in a note does. On a desktop or a tablet the note opens in a tab of its own, beside the note you had open rather than in its place; a note already open shows in its tab (#1268). On a desktop, hovering a chip says where it goes (Open House/Repairs.md). The rest of the row still opens the task.
  • Ctrl-click (Cmd-click on a Mac) or middle-click a chip to open the note in a tab behind the one showing, and stay on the list: the note lands on the link’s heading or block when you go to its tab. The same goes for a chip in a note’s task list.
  • Long-press a chip on a phone or a tablet to preview the note in a sheet with an Open action, as a long press on a wikilink does (when Preview a link is on; see links).
  • A link to a name two notes share asks which one, as in a note.
  • A link to a note that does not exist is a dead link: its chip is dashed and dimmed, with a broken-link icon and the name as you wrote it. Tap it to be offered the note, created where a new note goes, as for a dead link in a note; decline and nothing changes.

Typing [[ in a task — in the dialog, or in the field at the top of the list on a desktop — lists the library’s notes under the field, the ones the editor lists for a wikilink; # after a note’s name lists its headings and #^ its blocks. Tap one, or move with ↑ / ↓ and press Enter or Tab, to write the link in its shortest form that finds that note alone; Esc closes the list. The task stays one line.

Renaming or moving a note rewrites the task links that name it, as it does a note’s (see Updating the links to what moved in links).

Other todo.txt tools see the words [[House/Repairs]] in the task’s text, and nothing else: a link is only text on the line, so todo.txt stays the source of truth and syncs line by line like the rest of it.

Tasks for this note

A note shows the tasks that link it. It is in two places, one list, and a count on a wide window, the way Links to this note is:

  • in the side panel on a wide window, the Tasks pane, after Links and before History, following the note in the focused pane;
  • as a sheet on a phone, from the note’s ⋮ menu — Tasks for this note — as the Outline, Tags and Links are (see platforms);
  • the count, on a wide window: a task icon and the number of open tasks at the right of the note’s status row, beside the links count and before the word count. It is always in its place while a library is open and the Todo feature is on (a zero is dimmer), and it follows the tasks as they are ticked and added; a click opens the Tasks pane. With the Todo feature off (Settings → Features) there is no count, no pane and no menu entry. A phone has no count, and the ⋮ menu opens the sheet.

Add task heads the list. The open tasks follow, the soonest due first and the ones with no due date last, in the order of todo.txt; then Done (n), folded, lists the completed ones from done.txt, the latest first. A row is a task as the Todo tab draws it — checkbox, priority, text, due date, +project / @context / #tag and a chip for each other note it links — without the link to this note, which is what the list is about. A heading or block that link names stays, as a small § Boiler chip. The checkbox ticks the task (a ticked one goes to Done, and unticking it there reopens it); a tap on the text opens the task dialog, to change it, give it a date or delete it. The list follows todo.txt: a task edited in the Todo tab, in a text editor or by sync shows at once, and a renamed note keeps its tasks (their links are rewritten).

Add task opens the dialog with [[Note]] already in the description — the shortest form that finds this note alone, as the [[ completion writes it — and the caret at the start, ready for the words of the task. New task in the note’s ⋮ menu does the same from the note itself and, on a desktop, so does Note: New task for this note… in the command palette. With text selected in the editor, the selection (on one line, its white space collapsed) is the description, and the link follows it: select “Order the filter cartridges” and choose New task to get Order the filter cartridges [[Repairs]].

Move to tasks

A checkbox item in a note can become a task. Move to tasks turns the item into a line of todo.txt, links it to the note, and takes it out of the note. It is for the list you wrote as notes and now want in the Todo tab, with a date, a priority or a reminder.

Put the caret on a - [ ] or - [x] line (any list marker, any indent) and choose Move to tasks:

  • in the editor’s right-click menu on a desktop (near its top, below the link and spelling entries), or in the bar a long press opens on a phone, where it is the first entry;
  • in the toolbar’s Tools sheet, on every platform;
  • in the command palette — Move to tasks.

One item opens the task dialog, titled Move to tasks and saved with Move. The description is the item’s text as written — bold, code and links kept — followed by [[Note]], so you can give it a date, a priority or a reminder before it is saved. Cancel changes nothing, in the note or in the files. The task carries today’s creation date, as every task the dialog adds does.

Several items are moved at once, with no dialog: select the lines and choose the same command. Each becomes text [[Note]] with today’s creation date. A ticked item (- [x]) goes to done.txt, completed today: x 2026-10-23 2026-10-23 Fix the hallway light [[Repairs]]. A ticked item that repeats (it carries a rec:) leaves its next copy in todo.txt, as ticking the task does, whether one item is moved or several.

The tasks are written to todo.txt and done.txt first, and the lines leave the note only once both files took them, as one undoable edit of the note, saved like any other. If anything fails in between, the item is in the note and in the task file — never in neither. A snackbar says Moved 3 to tasks with Undo, which puts the lines back where they were (at the nearest place if you have edited the note since) and takes the tasks out of the files.

An item that has sub-items (or a paragraph or a code block of its own under it) is not moved: Move to tasks is greyed on it, with Has sub-items — move them first as its reason, and a selection of several items moves the others and skips it; the snackbar counts what moved. Items inside a quote, and anything inside a code block, are not checkbox items and are left alone. The command is part of the Todo feature: with Todo off in the library, it is gone.

A list of tasks in a note

A fenced block whose language is todo draws a live list of tasks, from todo.txt and done.txt, where you write it. The block holds the question, never the answers: on disk it is a few lines of text, and another Markdown tool shows a code block. (It is todo, not tasks, because Obsidian’s Tasks plugin owns that name with a query language of its own.)

```todo
link: any
project: house
due: <=+7d
```

With the caret outside the block, the list is drawn in the read view and in live mode alike, on a desktop, a tablet and a phone. Its head says what it lists and how many (Tasks · project house · due within 7 days · 2). A row is a task as Tasks for this note draws it: a checkbox that ticks it, a tap that opens the task dialog, a chip for each link; a ticked task goes to done.txt, and the list follows. Add task at its foot opens the dialog written out from the block (below). With the caret inside the block, or after a tap on its head, you see the source again, coloured: the keys the block knows, the values, and a key it does not know in the red of a deletion. Drawing the list never changes the note; the block is rewritten only when you type in it. With the Todo feature off (Settings → Features), or for a note outside a library, the block is just a code block.

The lines

One key: value to a line; blank lines and the spaces round a line do not matter, and keys may be written in any case. Every line must match: a task is listed only if it passes all of them. A key left out asks for nothing, except link, done and sort, which have defaults.

Key Value Meaning
link this (default), [[Note]], any Whose tasks: the ones that link this note; the ones that link another note; every task.
project a name, with or without the + A task with that +project. May be given again: the task must have all of them.
context a name, with or without the @ A task with that @context. May repeat.
tag a name, with or without the # A task with that #tag. May repeat.
due today, overdue, <=+7d, 2026-11-02, 2026-11-01..2026-11-07 Tasks due then. <=+7d is today, the next seven days and everything overdue. A task with no due date matches none of them.
priority A, A-C Tasks with that priority, or one in that range.
done no (default), yes, all The open tasks of todo.txt; the completed ones of done.txt; both, the open ones first.
sort due (default), priority, file The soonest due first, undated last; (A) first; or the file’s own order. As in the Todo tab, ties are broken by priority and creation date.

An empty block is the tasks that link this note, the list Tasks for this note has. link stays this whatever else the block filters by, so a block never widens by itself: to list tasks that do not link the note, say link: any. A block of one line,

```todo
due: overdue
```

lists only the overdue tasks among the ones that link the note; and a dashboard over the whole list, in a note of its own, is

```todo
link: any
due: <=+7d
sort: priority
```

link: [[Repairs]] lists the tasks that link Repairs, resolved as a wikilink in this note is. A link to a heading or a block of the note counts, as in Tasks for this note. A row in a link: this or link: [[Note]] list leaves out the link to that note, as that list does; a link: any list shows every link as a chip.

Add task

Add task opens the task dialog with what the block’s lines would give a new task, so that it shows up in the list. For link: this that is ` [[Note]] — a space, then the shortest link that names this note, the caret before it, as *Tasks for this note* writes it — and then the +project, @context and #tag the block filters by ( [[Note]] +house @phone). For link: [[Repairs]] the link is to *Repairs*; for link: any` there is no link, only the tokens. Dates and priorities are not filled in.

Mistakes

A line the block cannot read — a key it does not know, a value the key does not take, a key with no value, a line with no colon, a key that takes one value given twice — is a row in the block saying so, with the line it is on, and a block with any such row lists no tasks until it is fixed: a half-read filter would show a list that looks right. The rows replace the list; Add task is still there. A mistyped key names the nearest one (Unknown key prio — did you mean priority?), and a wrong value lists what the key takes. A link: [[Note]] that names no note, or a name several notes share, is a row in the same way. In live mode a tap on a row puts the caret on its line.

A block that is fine and finds nothing says No tasks match in one line.

Exporting, and other tools

HTML, PDF and EPUB print the list as it is when you export: the head, then each task after a box — ☐ open, ☑ done — its links shown by their labels, its priority before it and its due date after (Due 2026-11-02). The block’s source is not printed, and a block with errors prints its error lines. Exporting a folder or the library prints the block as the code it is on disk, since a page of a zip is not made where the tasks are.

Another Markdown tool, a sync client or GitHub shows the block as a code block with the lines you wrote, and nothing else; todo.txt is read by the same tools as ever.

Editing and deleting

On a phone, tap a task to edit it; the trash icon in the dialog’s title deletes it. Long-press a row for the same Edit / Delete as a menu, or swipe it to the left and confirm.

On a tablet whose Todo pane has the room — in landscape, where Home and Todo take the width (#1266) — a tapped task opens beside the list instead: the dialog’s fields in a panel that stays while the list does. Tapping another task moves the panel to it; Save writes the line and the panel goes, Cancel leaves it as it was. The task is found by its text when it is saved, so checking off another one meanwhile does not send the edit to the wrong line. Held upright, a tablet opens the dialog.

On a desktop the list is driven by the mouse and the keyboard (#712):

  • a click selects a row, a double click edits its text in place — Enter saves, Esc cancels;
  • ↑ / ↓ move the selection across the tasks and the section headers and scroll it into view; on a task, Space checks it, Enter or F2 edits it in place and Delete deletes it — the selection moves on to the row that takes the task’s place; on a header, Enter or Space folds the section or opens it;
  • a right click opens the row’s menu at the pointer: Edit… (the dialog, for the dates, the reminder and the priority), Set due ▸ (Today, Tomorrow, Next week, Pick a date…, No due date), Priority ▸ (A, B, C, None) and Delete;
  • hovering a row shows a calendar (the due days alone), a trash and a ⋯ that opens the same menu;
  • a field at the top adds a task per Enter, as typed — +project, @context and due: included, with the tokens already in the list completed as you type them (Tab takes the first) and [[ completing a link to a note — and keeps the cursor for the next one;
  • Filter and Sort open under their pills.

Deleting removes the line from todo.txt (or done.txt, for a task in the Done section) outright: there is no trash for tasks. To keep a finished task, check it instead.

The files themselves

todo.txt and done.txt also open in the editor, as text, coloured as a task list: the priority, the dates at the head of a task, +projects, @contexts, #tags and key:value tags (due:, rem:, rec:) each in their own color, and a completed task struck through. A rec: that Niman cannot read — rec:often, rec:0d — keeps its color and gets a wavy underline, and does nothing. They open in the source editor only — the preview and the WYSIWYG editor read Markdown, and would run the lines together — so their switches stay in place, off. The colors are the theme’s, under Task lists (todo.txt) in the theme editor (themes).

Reminders

Add rem:2026-09-20T09:00 to a task and Niman schedules an exact alarm in local wall-clock time. It fires with the screen off, the app in the background, or the process killed (Android). The app warns when a notification or background setting could block delivery — the banner over the task list, and, as soon as a reminder is set, the dialog that set it. The banner appears as soon as the app knows a setting is off, even before any reminder exists; only the system permission dialog waits for the first reminder. Both Open settings actions open Niman’s App info page (Informazioni app), where the notification switch, the battery usage row and the permissions sit together: turn on Allow background usage (Consenti l’utilizzo in background). An app the system will not start in the background never fires an alarm, whatever the notifications say.

Notification text is the task’s prose without key:value tags (and without +/@/# markers unless the library’s reminderShowTokens is true).

An event in calendar.txt carries its reminder the same way — 17-18 jogging @park rem:16:30., a clock time on the line’s own day (journal) — and it feeds the same alarms: one wanted set over both files, so completing or deleting either takes its reminder with it. Tapping an event’s notification opens the journal on that day; tapping a task’s opens the task list.

A repeating event’s reminder fires on every occurrence (recurring events): a clock rem:16:30 is that time on each occurrence’s day, and a full rem: date-time keeps its distance from the event’s first day — written the day before, it reminds the day before every time. The system only holds so many alarms (Android 500 per app, iOS 64), and a rule never ends, so Niman keeps the next two weeks scheduled — every occurrence of each event in those fourteen days — and works that window out again whenever the app runs: at start, on every return to it, when a file changes and, on a desktop, each time a reminder is shown. Skipping an occurrence cancels its alarm alone, and an event with an until: stops reminding after it. Open Niman at least once every two weeks for a repeating event’s reminders to go on: on Android and Apple the alarms already scheduled still fire with the app closed, but the ones after the window are only scheduled when it next runs. The limit is one for all your reminders together (Android 400, iOS 64): when it is reached — a library with a great many repeating events — Niman schedules the soonest alarms of all of them and leaves the later days out. On Android and Apple the days left out are only scheduled the next time Niman runs, so with that many repeating events the alarms can run out before two weeks are over: open Niman more often. On a desktop there is no limit.

Recurring tasks

Add rec: to a task and completing it does not end it: the task goes to done.txt as always, and the next one is added to todo.txt with its due date moved on. The line is the whole of it — there is no hidden setting — so a task repeats the same way on every device, and another todo.txt tool sees one more tag.

Write The next one is due
rec:1d one day after you complete it
rec:2w two weeks after you complete it
rec:1m / rec:1y one month / one year after you complete it
rec:+1w one week after its due date, however late you were (the + is strict)
rec:3b three business days on (Monday to Friday)
rec:1w;mo,we,fr the next of those weekdays after today (mo tu we th fr sa su, in every language)
rec:1m;2tu the second Tuesday of next month; rec:1m;-1fr is the last Friday

d, w, m, y and b are days, weeks, months, years and business days; the number is how many. The two last rows are Niman’s own additions to the common syntax (the one Simpletask, topydo and sleek share): another tool reads them as a tag it does not know, so the task does not repeat there, and nothing else about the line changes.

What completing does. The completed line goes to done.txt with its rec: kept. The next copy is appended to todo.txt:

  • due: moves to the next date, counted from the due date for a strict rec:+… and from the day you completed it otherwise. A task with no due: gets one, counted from the day you completed it;
  • t: (the threshold date other tools write) and rem: move by the same number of days as due:, and a reminder keeps its time of day; so completing a task takes its reminder and schedules the copy’s;
  • the priority, the text, the links to notes and every other tag stay as they were, and a creation date becomes the day you completed it.

This is the same wherever the task is completed: the Todo tab, a note’s tasks, a task list in a note, the Home tile and the home-screen widget.

Month ends. A step of months or years that lands past the end of a shorter month takes its last day: 31 January plus one month is 28 (or 29) February. A task that repeats from its due date and was moved by that clamp stays on the day it landed on — the line holds only its current due date — so a strict rec:+1m from the 31st can drift to the 28th and not come back. Count from the completion when that matters.

Late tasks. A task that is three periods overdue moves one period when you complete it, as it does in every other tool; completing the copy moves it again. Each completion is one line in done.txt, so the history is what you did.

Undo. Unchecking a done task puts that line back in todo.txt as it was; it does not remove the copy, which is a task of its own by then. Delete whichever you do not want.

Two devices. The copy is worked out from the line and the day alone, so two devices that complete the same task on the same day write the same lines, and sync keeps each once. Two that complete it on different days keep both copies, which is a real disagreement left for you to see.

Rows show the rule beside the due date, with a repeat icon: every 2 weeks, every weekday, every month on the 2nd Tuesday. The task dialog’s Repeat row sets it (see The task dialog); a rec: typed in the text is the same thing.

Home-screen widget

Android: the Niman Todos widget shows the tab’s open tasks in the same due-date sections (Overdue, Today, Next 7 days, Later, No date) and toggles a task on a row tap, with the app closed or not. See widgets.

The task dialog

Adding or editing a task opens one dialog: the description, with completion for the +project, @context and #tag already in use and for a [[ link to a note (see Links to notes), the priority, the due date and the reminder. Add task from a day in the journal opens the same dialog with that day already set as the due date (see journal). A long description wraps and the field grows downward, a few lines at most, then scrolls; it is still one line of todo.txt, so Enter saves and a pasted line break becomes a space. On a wide window the dialog is wider.

The Repeat row under the reminder sets how the task repeats — Never, Every day, Every weekday, Every week on the due date’s weekday, Every month and Every year from the due date, or Custom: every N days, weeks, months or years, on which weekdays for weeks, on the same date or on the Nth (or last) weekday of the month, counted from the due date or from completion. It writes the rec: tag in the text, and a rec: typed there shows in the row (a rule Niman cannot read shows as written, in the error color). On a desktop window with the room Custom opens under the row and applies as you change it; on Android it is a sheet, applied with OK. See Recurring tasks.

On a desktop window with the room, the due date and the reminder are picked inside the dialog: the calendar opens under its row, and for a reminder the time is typed beside it (14:30) and set with OK. One opens at a time; tapping the row again folds it. Android — a phone or a tablet alike — keeps the system calendar and clock: a date or a time is picked there, never typed, so the soft keyboard stays down while you choose.

Settings

Per library (.niman/settings.json): reminderShowTokens (default false). Global debug log (last 5 000 lines, exportable, survives reboots) helps diagnose missed reminders.

A reminder whose time has passed gets a todo reminders: overdue line in the log, saying what happened to it:

  • Android, where the system holds the alarm: STILL PENDING, never fired (the system is still holding it past its time) or no longer pending, fired, plus the two settings that can defer an alarm, exact alarms and battery optimization.
  • Linux and Windows, where the alarm is a timer inside Niman: timer fired … late, timer STILL ARMED past its time (the machine slept through it) or NOT FIRED (Niman was not running at its time). A desktop reminder needs Niman running, in the tray if the window is closed; one that came due while it was closed is shown on the next run, as long as it is still within the hour it stays wanted. A reminder is shown once: editing the task’s text after it showed does not show it again, while a second task due at the same minute is a reminder of its own and is shown.

Edit this page on GitHub