# TaskNotes documentation
> Documentation for the TaskNotes app, Obsidian plugin, and portable task format.
---
# TaskNotes documentation
Source: https://tasknotes.dev/
# TaskNotes documentation
TaskNotes keeps structured task information in portable Markdown records. Use
the dedicated app on the web, Android, or iOS, or work inside Obsidian with the
TaskNotes plugin.
## One portable task model
Both clients understand the same TaskNotes concepts: status, priority, dates,
projects, contexts, recurrence, reminders, relationships, and custom fields.
The interface and available integrations differ, but your task records are not
locked to one screen or application.
- Start with [portable task records](/concepts/task-records/) if you want to
understand what the products share.
- Read the [formal specification](/developers/specification/) when implementing
or integrating with TaskNotes.
- Review the [privacy overview](/privacy/) before choosing a hosted or
computer-connected collection.
---
# TaskNotes app
Source: https://tasknotes.dev/app/
# TaskNotes app
The TaskNotes app is currently in beta. It is a web-first client packaged for
Android and iOS, designed for quick capture, daily review, editing, and
completion while keeping task records portable.
The app is compatible with **TaskNotes v5 collections**, which use the
**mdbase 0.3.0 specification**. The same collection can be used by other
compatible TaskNotes and mdbase tools.
Every TaskNotes session opens an mdbase collection. You can start a new
collection online, or sync a folder of Markdown notes on your computer, such as
an Obsidian vault, with the mdbase Connect desktop app. TaskNotes reads and
writes the collection's online copy, so it works while your computer is off.
The Today workspace in the desktop layout.
## Begin here
1. [Open or install TaskNotes](/app/getting-started/).
2. [Learn how mdbase supports TaskNotes](/app/mdbase/).
3. [Choose where your collection lives](/app/collections/), then follow the
[connection steps](/app/connect-mdbase/).
4. Create a task and open **Today**.
5. Turn on reminders only if the collection and platform support delivery.
## What the app includes
- Today, Upcoming, Projects, lists, boards, and calendars
- Capture, editing, completion, archive, and search
- Projects, contexts, tags, priorities, relationships, and custom fields
- Recurrence, materialized occurrence notes, reminders, and time tracking
- New collections online, or folders on your computer synced with mdbase Connect
- Browser, Android, and iOS packaging from the same application
Plugin-only functionality such as inline Obsidian widgets, the command palette,
external calendar integrations, HTTP APIs, and companion plugins is documented
under the [Obsidian plugin](/obsidian/).
---
# Choose a collection
Source: https://tasknotes.dev/app/collections/
# Choose a collection
TaskNotes opens every collection through mdbase. mdbase keeps a copy of each
collection online, so TaskNotes can reach it from the web, iPhone and Android.
The choice is where the collection starts.
If mdbase is new to you, start with [mdbase and TaskNotes](/app/mdbase/). For
the setup steps, follow [Connect TaskNotes to mdbase](/app/connect-mdbase/).
## A new collection
Create a collection when you sign in to TaskNotes, or with **Add collection →
New collection** in mdbase. It starts online, with no folder on your computer.
You can add it to a computer later with the mdbase Connect desktop app.
## A folder on your computer
The mdbase Connect desktop app can sync an existing folder of Markdown notes,
such as an Obsidian vault, with your mdbase account. The folder stays where it
is, and mdbase keeps a copy online. TaskNotes uses that copy, so your computer
does not need to stay on. Changes reach the folder whenever mdbase Connect is
running on that computer.
For an Obsidian vault, follow
[Use TaskNotes App with your vault](/obsidian/guides/tasknotes-app/).
## Only in this browser
Without an account, TaskNotes on the web opens a collection saved only in that
browser. Use it to try TaskNotes. When you sign in, choose **Bring it in** to
move that work into a collection.
## Change collections later
Use the collection switcher in the sidebar, or **Settings → Collection**.
Opening another collection does not copy or move records from the collection
you were using.
---
# Connect TaskNotes to mdbase
Source: https://tasknotes.dev/app/connect-mdbase/
# Connect TaskNotes to mdbase
TaskNotes keeps your tasks in an mdbase collection: a folder of Markdown
files. You can start a new collection online, or sync a folder that is already
on your computer. Either way, mdbase keeps a copy online, so TaskNotes works on
the web, iPhone and Android even while your computer is off.
Read [What is mdbase?](/app/mdbase/) for more background, or
[Choose a collection](/app/collections/) to compare the options.
## Try it without an account
Open [app.tasknotes.dev](https://app.tasknotes.dev/) in a browser. Without an
account, TaskNotes opens a collection saved only in that browser. When you
connect later, TaskNotes offers to **Bring it in** to the collection you
choose.
## Start a new collection
1. Open [TaskNotes](https://app.tasknotes.dev/) or its iPhone or Android app
and sign in to mdbase. You can create an account there.
2. On the **Open in TaskNotes** page, enter a name under **New collection
name**, or choose a collection you already have.
3. Choose **Open TaskNotes**.
4. The first time TaskNotes opens a collection, it asks to set it up. See
[First-time setup](#first-time-setup).
## Use a folder on your computer
Use this for an existing folder of Markdown task notes, such as an Obsidian
vault. If it is an Obsidian vault, follow
[Use TaskNotes App with your vault](/obsidian/guides/tasknotes-app/) instead:
it has the steps for the TaskNotes plugin as well.
1. Install the [mdbase Connect desktop app](https://mdbase.dev/downloads/) for
macOS, Windows or Linux, and open it.
2. Choose **Sign in with your browser**. In the browser, sign in or create an
account, then choose **Approve computer**.
3. Choose **Add existing folder** and select the folder. Select the top folder
of the collection, not a `tasks` folder inside it. The folder stays where it
is.
4. Open **Collections**, open the folder's **…** menu and choose **Turn on
sync**, then choose **Turn on sync** again. mdbase Connect uploads the files
and keeps them in sync. TaskNotes can use the folder only once sync is on.
5. Open TaskNotes, sign in with the same account, choose the collection and
choose **Open TaskNotes**.
6. The first time, TaskNotes asks to set up the collection. See
[First-time setup](#first-time-setup).
Changes you make in TaskNotes reach the folder whenever mdbase Connect is
running on that computer. Changes you make in the folder reach TaskNotes the
same way.
## First-time setup
The first time TaskNotes opens a collection, it may show **Set up
_collection_ for TaskNotes**. Setup adds or updates the task type and saved
views that TaskNotes needs. It keeps your notes and any changes you made to
those definitions. Choose **Set up** to continue, or **Continue** if nothing
needs to change.
**If the collection is an Obsidian vault**, update the TaskNotes plugin to
version 5 on every device that uses the vault before you set it up. Setup
writes the task type whether or not type definitions are turned on in
Obsidian, and TaskNotes 4 can overwrite it.
## Switch collections
Use the collection switcher in the sidebar, or **Settings → Collection**, and
choose a collection. **Add a collection…** opens mdbase so you can choose
another collection. Switching collections does not copy or move their records.
---
# Connection and availability
Source: https://tasknotes.dev/app/connection/
# Connection and availability
TaskNotes reads and writes the selected mdbase collection directly. It does not
keep a separate offline collection or a queue of changes waiting to sync.
## What each status means
| Status | Meaning |
| --- | --- |
| Connected | TaskNotes can read and change the selected collection |
| Connecting | TaskNotes is checking the collection connection |
| Collection unavailable | TaskNotes cannot reach mdbase |
Open **More** to see the current status and use **Refresh now** to read the
latest collection state.
## What TaskNotes needs
TaskNotes needs a network connection and an available mdbase service. If
either is unavailable, TaskNotes cannot open the collection or save changes.
Reconnect the collection if its authorization has expired.
## Folders on your computer
When a collection is synced with a folder on your computer, TaskNotes uses the
online copy, so the computer can be off. Changes reach the folder the next time
mdbase Connect is running on that computer.
## During a connection problem
Tasks already visible in the current session may remain on screen during a
short interruption, but TaskNotes cannot safely save new changes until mdbase
is reachable. A failed action is not silently queued for later.
If the problem continues, use the collection switcher in the sidebar, or
**Settings → Collection**, to open another mdbase collection.
---
# Get started with the TaskNotes app
Source: https://tasknotes.dev/app/getting-started/
# Get started with the TaskNotes app
TaskNotes app is currently in beta. Features, availability, and setup steps may
change before the stable release.
The app supports TaskNotes v5 collections based on the mdbase 0.3.0
specification.
## 1. Open TaskNotes
Use [app.tasknotes.dev](https://app.tasknotes.dev/) in a supported browser, or
install TaskNotes from the
[App Store](https://apps.apple.com/app/tasknotes/id6797168033) or
[Google Play](https://play.google.com/store/apps/details?id=dev.tasknotes.app).
The web and native applications use the same task interface.
On the web you can try TaskNotes without an account: it opens a collection
saved only in that browser.
## 2. Choose a collection
TaskNotes opens every collection through mdbase. Sign in, then create a new
collection or choose one you already have. To use a folder on your computer,
such as an Obsidian vault, sync it with the mdbase Connect desktop app first.
Read [What is mdbase?](/app/mdbase/) if this is new to you, then
[Choose a collection](/app/collections/) to compare the options.
Follow [Connect TaskNotes to mdbase](/app/connect-mdbase/) for the steps.
## 3. Create a task
Use **Add task**, enter a title, and save. Capture understands the collection's
configured status, priority, project, context, and tag values.
## 4. Review the starter views
Open **Today** for current work, **Upcoming** for scheduled tasks, and **Views**
for the complete collection of lists, boards, calendars, and project views.
Navigation belongs to the current collection and can be reordered from Views.
## 5. Check collection status
Open **Settings** to see the collection location, connection state, last refresh,
notification access, task model settings, and appearance preference.
---
# mdbase and TaskNotes
Source: https://tasknotes.dev/app/mdbase/
# mdbase and TaskNotes
mdbase lets TaskNotes work with a portable Markdown collection instead of
hiding your tasks in a TaskNotes-only database. Every TaskNotes session opens
one mdbase collection.
## What is mdbase?
Two related names appear in TaskNotes:
- **mdbase** is the open collection format and specification. A collection is
a folder of Markdown files plus a small description of what those files mean.
- **mdbase Connect** is the service that keeps your collections, syncs them
with folders on your computers, and lets apps such as TaskNotes use them
with your permission. It includes a desktop app for macOS, Windows and Linux.
Read the [mdbase introduction](https://mdbase.dev/) for a visual explanation of
the wider ecosystem.
## What it gives TaskNotes
TaskNotes understands what a task looks like inside an mdbase collection. That
compatibility is defined by the TaskNotes v5 collection format and its mdbase
0.3.0 binding. That means TaskNotes can:
- use the same task fields, projects, tags, saved views, and settings on the
web, Android, and iOS;
- ask for access to one collection without seeing your other folders; and
- keep reminders running while TaskNotes is closed when your collection
supports them.
Behind the scenes, mdbase checks that each change is valid before saving it.
You still own readable Markdown files rather than a database that only
TaskNotes can open.
## Where your collection lives
mdbase keeps a copy of each collection online, and TaskNotes reads and writes
that copy. A collection can start in one of two places:
| Start with | What happens |
| --- | --- |
| A new collection | It is created online. You can sync it to a folder on a computer later. |
| A folder on your computer | The mdbase Connect desktop app syncs it with an online copy. The folder stays where it is. |
[Choose a collection](/app/collections/) compares these in more detail.
[Connect TaskNotes to mdbase](/app/connect-mdbase/) has the setup steps.
## Use a folder on your computer
Install the mdbase Connect desktop app to sync a folder on your computer, such
as an Obsidian vault.
1. Open the [mdbase Connect download page](https://mdbase.dev/downloads/) and
choose the desktop app for macOS, Windows, or Linux. Follow any
platform-specific beta installation notes on that page.
2. Open mdbase Connect and sign in.
3. Add the folder, then turn on sync for it.
4. In TaskNotes, sign in with the same account and choose the collection.
[Connect TaskNotes to mdbase](/app/connect-mdbase/#use-a-folder-on-your-computer)
has the exact steps. For an Obsidian vault, follow
[Use TaskNotes App with your vault](/obsidian/guides/tasknotes-app/).
## Do I need to leave my computer on?
No. TaskNotes uses the online copy, so it keeps working while your computer is
asleep or off. Changes made in TaskNotes reach the folder on your computer the
next time mdbase Connect is running there, and changes made in the folder
reach TaskNotes the same way.
For more detail about how Connect protects and routes your data, read
[How mdbase Connect works](https://mdbase.dev/connect/).
---
# App integration manifest
Source: https://tasknotes.dev/app/reference/manifest/
# App integration manifest
This page is generated from the integration manifest shipped by TaskNotes app 1.0.12.
| Field | Value |
| --- | --- |
| Application ID | `dev.tasknotes.app` |
| Manifest version | `1` |
| Homepage | [https://app.tasknotes.dev/](https://app.tasknotes.dev/) |
| Collection access | `full_collection` |
## Required contracts
- `tasknotes.task` version `0.3.0-rc.6`
- `tasknotes.settings` version `1.1.0`
- `mdbase.app-settings` version `2.0.0`
- `obsidian.base` version `1.0.0`
- `mdbase.view` version `1.0.0`
## File capabilities
No file capabilities declared.
## Notification criteria
- `task.reminder` listens for `mdbase.runtime.timer.fired` version `1.0.0`.
---
# Reminders in the TaskNotes app
Source: https://tasknotes.dev/app/reminders/
# Reminders in the TaskNotes app
Task records can contain relative reminders anchored to scheduled or due dates,
or absolute reminders fixed to a particular time. Saving reminder data does not
by itself guarantee notification delivery.
## Delivery by collection
| Collection | Reminder data | Notification delivery |
| --- | --- | --- |
| mdbase collection | Saved in the collection | Available after opt-in |
For mdbase collections, the authority schedules reminder events so delivery
does not depend on one TaskNotes screen remaining open. Notification payloads
are content-free; selecting one refreshes authorized collection state in the
app.
## Turn on reminders
Open **More**, select **Turn on reminders**, and approve the browser or operating
system permission. Some existing mdbase grants require **Review notification
access** before the channel can be enabled.
An unsupported or insecure browser reports that notification delivery is not
available. The reminder definitions remain in the task record.
---
# Work with tasks
Source: https://tasknotes.dev/app/tasks/
# Work with tasks
A task opens beside its source view on wider screens.
## Capture
Use **Add task** from navigation or from a saved view. When a view has safe
creation defaults, TaskNotes applies them automatically so the new task remains
in that view.
## Edit
A task can contain:
- Status and priority
- Scheduled and due dates
- Markdown notes
- Projects, contexts, and tags
- Dependencies and subtasks
- Collection-defined custom properties
- Time estimates and tracked sessions
- Recurrence and occurrence-note policies
- Relative and absolute reminder definitions
Background saves remain ordered if you navigate away while a write is still in
progress.
## Complete, archive, and delete
Complete a task from its row or detail screen. Archive retains the record and
may move its Markdown file according to collection settings. Delete offers a
short undo period before committing the removal.
## Search
Search runs across the current collection and matches titles, notes, projects,
contexts, and tags. Use **Refresh now** under **More** if a change made by
another tool does not appear yet.
---
# Troubleshoot the TaskNotes app
Source: https://tasknotes.dev/app/troubleshooting/
# Troubleshoot the TaskNotes app
Start by recording the app version, platform, collection type, collection
status shown under **More**, and the smallest sequence that reproduces the
problem.
## The collection is unavailable
Confirm that the device is online and try **Reconnect this collection**.
## An authorization error appears
Use the reconnect action for the current collection and review the access that
mdbase requests. If you no longer want to use that collection, use the
collection switcher in the sidebar, or **Settings → Collection**, to open
another one.
## A change did not save
TaskNotes writes directly to mdbase and does not queue failed changes for later.
Restore the connection, then retry the action. Capture and editing screens keep
recoverable input visible when they can do so safely.
## A change from another tool is missing
Open **More** and choose **Refresh now**. If the record still does not appear,
confirm that the other tool wrote to the same mdbase collection and that the
record uses a compatible TaskNotes task definition. For a change made in a
folder on your computer, such as an Obsidian vault, check that mdbase Connect
is running on that computer and sync is on for the folder.
## Notifications do not arrive
Confirm that the current collection is an mdbase collection, reminders are
enabled in **More**, the browser or operating system permission is granted, and
the task contains a valid future reminder.
---
# Views and navigation
Source: https://tasknotes.dev/app/views/
# Views and navigation
Views are saved ways of selecting, sorting, grouping, and presenting records in
a collection. They travel with the collection; the set pinned to navigation is
a preference on each device.
The Views manager controls navigation order and saved view definitions.
## Starter views
TaskNotes creates managed starter views such as Today, Upcoming, Calendar, and
Projects. They use the same saved-view catalog as user-created views while
providing focused presentations for common work.
## Presentations
- **Task list** supports grouping, visible properties, section moves, and manual ordering.
- **Kanban** groups tasks into columns and can update the grouped property when a task moves.
- **Calendar** shows task dates in month, week, day, and list layouts.
- **Mini calendar** combines a month picker with tasks for the selected day.
- **Projects** finds project records referenced by active tasks.
## Navigation
Open **Views** to add or remove a view from navigation and to change its order.
The first navigation item is the collection's home. Mobile displays the first
three views directly and keeps the rest in the Views destination.
## Create and edit views
The view editor controls the name, presentation, query, grouping, sort order,
visible properties, and safe defaults for tasks created from the view. View
documents remain ordinary collection resources rather than being stored only
inside the TaskNotes app.
---
# Portable task records
Source: https://tasknotes.dev/concepts/task-records/
# Portable task records
A TaskNotes task is an ordinary Markdown record with structured properties.
Those properties describe the task; the Markdown body remains available for
notes, checklists, links, and supporting detail.
## Collections
A collection is a group of records plus the configuration that explains how to
interpret them. The configuration defines field names, statuses, priorities,
custom properties, record locations, and saved views.
The TaskNotes app uses **collection** throughout. The Obsidian plugin usually
describes the containing folder as a **vault** and presents saved views through
Obsidian Bases.
## Source of truth
Where the authoritative copy lives depends on the client and connection:
| Client and collection | Source of truth | Availability |
| --- | --- | --- |
| TaskNotes app · mdbase collection | The collection's online copy, synced with any folders on your computers | Requires a network connection |
| Obsidian vault | Markdown files in the vault | Controlled by Obsidian and your sync choice |
## Portability and compatibility
Portable does not mean every client exposes every feature. Inline task widgets,
Obsidian commands, external calendar integrations, and companion plugins belong
to the Obsidian client. mdbase collection access and background reminder
delivery belong to the TaskNotes app.
Use the client-specific guide for interface instructions and the
[specification](/developers/specification/) for normative data semantics.
---
# 0. Overview
Source: https://tasknotes.dev/developers/specification/
## 0.0 About tasknotes
**TaskNotes** is an [Obsidian](https://obsidian.md) plugin that stores tasks as individual markdown files with YAML frontmatter in a user's vault. Each task is a first-class file: readable and editable with any text editor, version-controllable, and searchable without special tooling.
A minimal task file looks like this:
```markdown
---
title: Buy groceries
status: open
priority: normal
due: 2026-02-21
tags: [task]
dateCreated: 2026-02-20T11:15:00Z
dateModified: 2026-02-20T11:15:00Z
---
Buy fruit and cleaning supplies.
```
Tasks are identified within the vault by a configurable detection method — by default, by the presence of a specific tag (e.g. `#task` in body or frontmatter). The plugin stores its configuration in `.obsidian/plugins/tasknotes/data.json` within the vault root.
**This specification** was derived from the behavior of the tasknotes plugin and is intended to serve as a stable, testable contract for:
- CLI tools and scripts that process task files outside Obsidian,
- any application that wants to interoperate with a tasknotes vault.
The spec is deliberately language-agnostic. It does not require any particular runtime, and the executable conformance suite (in `conformance/`) can be driven by an adapter written in any language.
The tasknotes plugin is the primary reference for how this spec was derived, but **the specification is normative** — where the spec and the plugin behavior differ, the spec defines the intended behavior. Known deviations are disclosed via conformance claims (§7.5).
## 0.1 Status and authority
This document is part of `tasknotes-spec` version `0.3.0`.
This specification is normative for implementations that claim conformance.
No single implementation is normative; implementations are expected to conform to the specification.
## 0.2 Motivation
TaskNotes-style systems store tasks as markdown files with YAML frontmatter. This model has practical advantages:
- Task records are plain files that can be inspected and edited without proprietary tooling.
- Data remains portable across environments.
- Files are suitable for version control and collaboration workflows.
As soon as more than one tool reads and writes the same task files, implicit assumptions become an interoperability risk. In practice, these risks appear in three areas:
1. Field semantics and naming drift.
2. Date and timezone interpretation differences.
3. Recurring-task state transitions that are handled differently by different clients.
When these rules are not explicit, users can get inconsistent results from equivalent operations. A shared specification reduces that risk by making behavior testable and versioned.
## 0.3 Objectives
This specification defines a stable contract for:
- Representing task records in markdown frontmatter.
- Mapping storage keys to canonical semantic roles.
- Defining effective collection configuration via provider model (for example `tasknotes.yaml` and/or TaskNotes `data.json`).
- Interpreting date and datetime values consistently.
- Applying recurrence, per-instance completion/skip behavior, and optional materialized occurrence notes.
- Managing time tracking sessions and `time_entries` lifecycle behavior.
- Parsing and resolving links consistently across task fields.
- Defining dependency and reminder behavior.
- Optionally applying deterministic create-time templating behavior.
- Executing write operations with predictable side-effects.
- Validating task records and reporting issues.
## 0.4 Non-objectives
This specification does not standardize:
- UI layout, styling, command palettes, or interaction design.
- Internal caching architecture or rendering pipelines.
- Transport protocols (HTTP, IPC, etc.) except where they affect persisted task semantics.
- Rich template-language features beyond the portable create-time templating contract in §5/§7/§9.
## 0.5 Scope
This specification is standalone. It does not require conformance to any other specification.
Implementations MAY internally reuse other libraries or specifications, but conformance claims under `tasknotes-spec` are evaluated only against this document.
Templating is optional and profile-gated; implementations that do not claim the templating profile remain conformant without template support.
References to TaskNotes plugin behavior, Obsidian behavior, or external specifications are informative context only unless this specification explicitly marks a requirement as normative.
## 0.6 Design principles
### 0.6.1 File-first persistence
Task state is represented in user-visible files. Derived indexes and caches are non-canonical.
### 0.6.2 Deterministic semantics
Equivalent inputs MUST produce equivalent persisted outputs under the same configuration and active runtime timezone.
### 0.6.3 Explicit mapping
Semantic roles are canonical. Storage key names are configurable and therefore must be mapped explicitly.
### 0.6.4 Backward evolution
The specification supports migration from legacy keys and historical behaviors through explicit compatibility rules.
## 0.7 Conformance
Conformance is profile-based (see §7). A minimal implementation can conform to a narrow profile while remaining interoperable for core operations.
## 0.8 Normative language
The key words **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**, and **MAY** are to be interpreted as described in RFC 2119.
## 0.9 Example collection
A default tasknotes vault looks like this:
```text
MyVault/
├── TaskNotes/
│ ├── Tasks/
│ │ ├── buy-groceries.md ← task file (title-derived filename by default)
│ │ └── weekly-review.md
│ └── Archive/ ← archive folder (if moveArchivedTasks=true)
├── .obsidian/
│ └── plugins/
│ └── tasknotes/
│ └── data.json ← plugin settings (primary config provider)
└── tasknotes.yaml ← optional spec-level config (secondary provider)
```
Task files are identified by the `#task` tag by default (configurable). The full default collection state is described in §9.21.
Configuration provider semantics and effective configuration rules are defined in §9. An implementation MAY use either provider, both, or additional providers, based on its documented precedence policy.
A task file example (using default field mapping):
```markdown
---
title: Buy groceries
status: open
priority: normal
due: 2026-02-21
tags: [task, errands]
contexts: ["town"]
dateCreated: 2026-02-20T11:15:00Z
dateModified: 2026-02-20T11:15:00Z
---
Buy fruit and cleaning supplies.
```
## 0.10 Versioning policy
This specification uses semantic versioning.
- A **major** version introduces breaking semantic changes.
- A **minor** version introduces additive behavior or optional features.
- A **patch** version clarifies wording or fixes non-breaking defects.
Implementations MUST reject unsupported major versions when strict mode is enabled.
## 0.11 Change governance
Specification changes SHOULD be accompanied by:
- a motivation statement,
- precise normative edits,
- migration notes when behavior changes,
- updated examples.
---
# TaskNotes for Obsidian
Source: https://tasknotes.dev/obsidian/
# TaskNotes for Obsidian
This guide covers the TaskNotes plugin for Obsidian. It follows the "one note per task" principle: each task is a Markdown file with structured metadata in YAML frontmatter.
## Requirements
TaskNotes 4.18.3 requires **Obsidian 1.12.2** or later and depends on the **Bases** core plugin. Before you begin, open Obsidian Settings and confirm Bases is enabled under Core Plugins.
Trying the opt-in v5 beta? Read [Upgrading from v4 to v5](migration-v4-to-v5.md) before installing it. The guide covers backups, synced devices, and returning to v4. The installation and requirements below describe the stable release.
## Getting Started
### 1. Install and Enable
Install TaskNotes from Community Plugins in Obsidian settings, then enable it. If Bases is still disabled, enable it right away so TaskNotes views can open correctly.
### 2. Create Your First Task
Press Ctrl+P (or Cmd+P on macOS), run **TaskNotes: Create new task**, fill in the modal, and save. If you prefer inline workflows, start with a checkbox like `- [ ] Buy groceries` and convert it using the inline task command.
### 3. Open the Task List
Open your first view from the TaskNotes ribbon icon or by running **TaskNotes: Open tasks view** from the command palette. This opens the default Task List `.base` file inside `TaskNotes/Views`.
### 4. Explore
Use [Core Concepts](core-concepts.md) to understand the data model, [Features](features.md) for workflow capabilities, [Views](views.md) for interface behaviour, and [Settings](settings.md) to tune TaskNotes for your vault. If you already have task-like notes, start with [Adopt TaskNotes in an existing vault](getting-started/existing-vault.md).
## Quick Links
---
# Companion Plugins
Source: https://tasknotes.dev/obsidian/companion-plugins/
Companion plugins are optional Obsidian plugins that build on TaskNotes without adding every workflow to the core plugin. They run inside the same Obsidian app, use TaskNotes' runtime API for live task reads and writes, and keep task data in ordinary Markdown files.
Use companion plugins when you want a deeper product surface than a script or webhook, but you still want TaskNotes itself to stay focused on task storage, editing, views, time tracking, and calendar behavior.
## Available Companion Plugins
| Plugin | Purpose | Documentation |
| --- | --- | --- |
| Canvas Bases | TaskNotes canvas companion for Obsidian Bases views, with canvas-style boards, JSON Canvas snapshots, optional TaskNotes badges, actions, and relationship edges. | [Canvas Bases](companion-plugins/canvas-bases.md) |
| TaskNotes Workflows | Markdown-defined automation for TaskNotes tasks, schedules, events, and manual command-palette workflows. | [TaskNotes Workflows](companion-plugins/tasknotes-workflows.md) |
More companion plugins may be documented here over time.
## How Companion Plugins Relate to TaskNotes
TaskNotes remains the source of truth for task behavior. Companion plugins should use the [TaskNotes JavaScript Runtime API](javascript-api.md) for live vault operations instead of rewriting TaskNotes frontmatter directly. This keeps task updates consistent with TaskNotes settings, task cache, events, calendar behavior, time tracking, and future data-model changes.
Companion plugins can also publish their own runtime surface through `api.extensions`. Other plugins and scripts can discover those extension APIs from TaskNotes:
```js
const tasknotes = app.plugins.getPlugin("tasknotes");
const workflows = tasknotes?.api?.extensions.get("tasknotes-workflows");
```
The extension registry is useful when companion plugins need to expose commands, validation helpers, catalogs, or run APIs to other in-vault tools.
## Choosing an Integration Surface
| Use case | Prefer |
| --- | --- |
| A user-facing Obsidian UI that works with TaskNotes tasks | Companion plugin |
| In-vault scripting with Templater, QuickAdd, MetaBind, or another plugin | [JavaScript Runtime API](javascript-api.md) |
| Local tools outside Obsidian | [HTTP API](HTTP_API.md) or [TaskNotes Obsidian CLI](obsidian-cli.md) |
| Notifications to external services when tasks change | [Webhooks](webhooks.md) |
| Direct file analysis without Obsidian running | [mdbase-tasknotes CLI](mdbase-tasknotes-cli.md) |
## Compatibility Expectations
Companion plugins should:
- Check `api.apiVersion` and `api.hasCapability(...)` before using runtime features.
- Use `api.catalog` and canonical runtime query DTOs from `api.query` instead of reaching into TaskNotes filter/view internals.
- Include a `source` value when mutating tasks so TaskNotes events are debuggable.
- Avoid reacting to their own mutations unless the behavior is explicit.
- Keep user data in the vault where possible, using readable Markdown or JSON files.
- Treat TaskNotes task notes and Bases files as user-owned documents.
TaskNotes does not need every companion plugin installed. If a companion plugin is disabled, TaskNotes task notes remain normal Markdown files and TaskNotes core views continue to work.
---
# Core Concepts
Source: https://tasknotes.dev/obsidian/core-concepts/
TaskNotes follows the "one note per task" principle, where each task lives as a separate Markdown note with structured metadata in YAML frontmatter.
## The Note-Per-Task Approach
Individual Markdown notes replace centralized databases or proprietary formats. Each task file can be read, edited, and backed up with any text editor or automation tool.
### Task Structure
A TaskNotes task is a standard Markdown file with YAML frontmatter:
```markdown
---
tags:
- task
title: Review quarterly report
status: in-progress
priority: high
due: 2025-01-15
scheduled: 2025-01-14
contexts:
- office
projects:
- "[[Q1 Planning]]"
---
## Notes
Key points to review:
- Revenue projections
- Budget allocations
## Meeting Notes
Discussion with finance team on 2025-01-10...
```
The frontmatter contains structured, queryable properties. The note body holds freeform content—research findings, meeting notes, checklists, or links to related documents.
### Obsidian Integration
Since tasks are proper notes, they work with Obsidian's core features:
- **Backlinks**: See which notes reference a task
- **Graph View**: Visualize task relationships and project connections
- **Tags**: Use Obsidian's tag system for additional categorization
- **Search**: Find tasks using Obsidian's search
- **Links**: Reference tasks from daily notes, meeting notes, or project documents
This approach creates many small files. TaskNotes stores tasks in a configurable folder (default: `TaskNotes/Tasks/`) to keep them organized.
In practice, this lets TaskNotes fit into existing vault habits instead of replacing them. You keep using normal note workflows, and TaskNotes adds structure, filtering, and commands on top.
## YAML Frontmatter
Task properties are stored in YAML frontmatter, a standard format with broad tool support.
Treat frontmatter as the machine-readable layer and the note body as the human-readable layer. TaskNotes automations and Bases filters rely on frontmatter; your project notes and context stay in the body.
### Property Types
TaskNotes uses several property types:
| Type | Example | Description |
|------|---------|-------------|
| Text | `title: Buy groceries` | Single text value |
| List | `tags: [work, urgent]` | Multiple values |
| Date | `due: 2025-01-15` | ISO 8601 date format |
| DateTime | `scheduled: 2025-01-15T09:00` | Date with time |
| Link | `projects: ["[[Project A]]"]` | Obsidian wikilinks |
| Number | `timeEstimate: 60` | Numeric values (minutes) |
### Field Mapping
Property keys are configurable. If your vault uses `deadline` instead of `due`, you can map TaskNotes to use your existing field names without modifying your files.
The exact rules for how fields map to semantic roles, how dates are interpreted, and how operations like completion and recurrence behave are defined in the [TaskNotes Specification](spec.md). The spec is the shared contract between the Obsidian plugin, the terminal UI, and any other tool that reads or writes TaskNotes data.
### Custom Fields
Add any frontmatter property to your tasks. User-defined fields work in filtering, sorting, and templates. Define custom fields in `Settings -> TaskNotes -> Task Properties` to include them in task modals and views.
## Bases Integration
TaskNotes v4 uses Obsidian's Bases core plugin for its main views. Bases provides:
- **Filtering**: Query tasks using AND/OR conditions
- **Sorting**: Order tasks by any property
- **Grouping**: Organize tasks by status, priority, project, or custom fields
- **Views**: Task List, Kanban, Calendar, and Agenda are all Bases views
Views are stored as `.base` files in `TaskNotes/Views/`. These files contain YAML configuration that defines the view's query and display settings. You can duplicate, modify, or create new views by editing these files.
This makes view behavior inspectable and predictable. If a task appears in the wrong place, you can open the `.base` file and see exactly which filter or grouping rule produced that result.
### Enabling Bases
Bases is a core plugin included with Obsidian 1.10.1+:
1. Open `Settings -> Core Plugins`
2. Enable "Bases"
3. TaskNotes views will now function
---
# Recurring Tasks
Source: https://tasknotes.dev/obsidian/features/recurring-tasks/
TaskNotes recurring tasks use RFC 5545 RRule strings with `DTSTART` support and dynamic next-occurrence scheduling. The model separates recurrence patterns from the next planned instance, and can also create normal task notes for individual occurrences when an instance needs its own content.
If you are new to recurring tasks in TaskNotes, think of the recurrence rule as the long-term plan and the `scheduled` field as the next concrete commitment. Most day-to-day editing affects `scheduled`, while recurrence editing changes the plan itself.
## Core Concepts
Recurring tasks operate on two independent levels:
1. **Recurring Pattern**: Defines when pattern instances appear (controlled by `DTSTART` in the recurrence rule)
2. **Next Occurrence**: The specific date/time when you plan to work on the next instance (controlled by the `scheduled` field)
3. **Materialized Occurrence Notes**: Optional child task notes for specific occurrence dates, used when an occurrence needs its own checklist, status, time tracking, or body content
This separation lets you reschedule the next occurrence without changing the pattern.
## Setting Up Recurring Tasks
In practice, setup is usually a two-step flow: choose a pattern, then check whether the next scheduled occurrence matches how you actually want to execute the next instance.
### Creating Recurrence Patterns
You can create recurring tasks through:
1. **Recurrence Context Menu** in task modals for presets or custom options
2. **Preset Options** such as daily, weekly, or monthly
3. **Custom Recurrence Modal** with date/time pickers and RRule configuration
### Required Components
Recurring tasks require:
- **Recurrence Rule**: RRule string with `DTSTART`
- **Scheduled Date**: Next occurrence date (independent from the pattern)
Materialized occurrence notes add two system fields to the occurrence note:
- `recurrence_parent`: link/path back to the recurring parent task
- `occurrence_date`: the occurrence date represented by the note
### DTSTART Integration
`DTSTART` is the anchor for pattern generation. It controls where the rule begins and, when time is included, the default time for future pattern instances.
- **Date-only**: `DTSTART:20250804;FREQ=DAILY`
- **Date and time**: `DTSTART:20250804T090000Z;FREQ=DAILY`
## Recurring Task Due Date
When a recurring task is completed, `scheduled` advances to the next occurrence. By default, `due` does not change.
Enable `Maintain due date offset in recurring tasks` in **Settings → TaskNotes → Features → Recurring Tasks** to preserve due/scheduled spacing.
Example:
- Scheduled: `2025-01-01`
- Due: `2025-01-03`
- Recurrence: weekly
If the task advances to `scheduled: 2025-01-08`, the due date becomes `2025-01-10` when this setting is enabled.
This setting is most useful when due dates represent a fixed lead/lag relative to scheduled work (for example, "due two days after execution"). If due dates are independent deadlines, leaving the setting off is usually clearer.
## Recurrence Pattern Examples
```text
DTSTART:20250804T090000Z;FREQ=DAILY
→ Daily at 9:00 AM, starting August 4, 2025
DTSTART:20250804T140000Z;FREQ=WEEKLY;BYDAY=MO,WE,FR
→ Monday, Wednesday, Friday at 2:00 PM, starting August 4, 2025
DTSTART:20250815;FREQ=MONTHLY;BYMONTHDAY=15
→ 15th of each month (all-day), starting August 15, 2025
DTSTART:20250831;FREQ=MONTHLY;BYMONTHDAY=-1
→ Last day of each month (all-day), starting August 31, 2025
DTSTART:20250801T100000Z;FREQ=MONTHLY;BYDAY=-1FR
→ Last Friday of each month at 10:00 AM, starting August 1, 2025
```
## Dynamic Scheduled Dates
The `scheduled` field automatically tracks the next uncompleted occurrence:
1. Initially set to the `DTSTART` date
2. Advances when occurrences are completed
3. Recalculates when the rule changes
4. Can be manually rescheduled independently
This behavior keeps recurring tasks practical in real planning: you can preserve a stable weekly/monthly pattern while still adapting the immediate next occurrence to calendar realities.
## Materialized Occurrence Notes
Most recurring tasks can remain virtual: the parent task stores `complete_instances` and `skipped_instances`, and TaskNotes renders each calendar/list instance from that parent. Materialized occurrence notes are for heavier instances where the date-specific work needs its own note.
Good uses include:
- A weekly review where each week needs a separate agenda and notes
- A maintenance task where each visit needs photos, links, or a checklist
- A recurring meeting where every occurrence should have its own time entries and completion state
To create one manually, right-click a recurring task card or calendar occurrence and choose **Open or create occurrence note**. The Task Action Palette also exposes **Open or create occurrence note** for recurring tasks. If a matching note already exists for the same parent and date, TaskNotes opens it instead of creating a duplicate.
An occurrence note is an ordinary TaskNotes task. It appears in views, can be edited like any other task, and shows an occurrence pill that links back to the recurring parent. On the calendar, a materialized occurrence replaces the matching virtual parent occurrence for the same parent/date pair, so you do not see both the generated instance and the note-backed instance at the same time.
Its frontmatter includes:
```yaml
recurrence_parent: "[[Tasks/Weekly review]]"
occurrence_date: "2026-06-01"
scheduled: "2026-06-01T09:30"
timeEstimate: 45
```
When TaskNotes creates an occurrence note, it copies the parent fields that describe how that instance should be planned: title, priority, scheduled time, due offset, contexts, projects, tags, reminders, dependencies, details, custom properties, and time estimate. Date-like fields are rebased onto the occurrence date, so a parent scheduled at `09:30` creates an occurrence scheduled at `09:30` on the selected date, and a due date one day after the parent scheduled date stays one day after the occurrence scheduled date.
Occurrence notes can use a separate template from regular new tasks. Set `occurrence_template` on the recurring parent to point at a template note, or configure **Settings → Features → Body template → Occurrence note template file** as a global fallback. Parent-level `occurrence_template` wins over the global fallback. If neither occurrence-specific template is configured, occurrence note creation keeps the normal body template behavior.
The parent task remains the source of the recurrence rule and series history. Occurrence notes do not copy the parent's `recurrence`, `complete_instances`, `skipped_instances`, `completedDate`, calendar provider IDs, or `timeEntries`. New time entries belong to the occurrence note once you track time there.
### Occurrence Filenames
By default, materialized occurrence notes use the existing filename behavior: the parent title followed by a numeric suffix. To opt in to custom filenames, set **Occurrence filename template** under **Settings → Task Properties → Title**. For example, `{{title}} — {{occurrenceDate}}` produces `Weekly review — 2026-08-01.md`.
Occurrence filename templates support all regular filename variables plus these occurrence-specific variables:
- `{{occurrenceDate}}` - occurrence date, such as `2026-08-01`
- `{{occurrenceWeek}}` - ISO week, such as `2026-W31`
- `{{occurrenceMonth}}` - month, such as `2026-08`
- `{{occurrenceYear}}` - year, such as `2026`
- `{{occurrenceMonthName}}` - full month name, such as `August`
Choose the date granularity explicitly in the template; TaskNotes does not infer it from the recurrence rule. A recurring parent can override the global template with the frontmatter property configured by **Occurrence template override property** (by default, `occurrenceFilenameTemplate`):
```yaml
occurrenceFilenameTemplate: "{{title}} ({{occurrenceWeek}})"
```
Leaving the global template empty preserves the existing filename behavior. TaskNotes never renames existing occurrence notes, and filename collisions continue to receive a numeric suffix.
### Occurrence Note Policies
Each recurring parent has an **Occurrence notes** submenu under its recurrence menu:
- **Create manually**: occurrence notes are only created by explicit action.
- **Create next after completion**: after you complete a materialized occurrence note, TaskNotes creates the next occurrence note.
- **Rolling window**: defined by the TaskNotes spec, but not automated in the plugin yet.
When **Create next after completion** is enabled, creating the first occurrence is still a deliberate action. After that, completing the occurrence note advances the parent recurrence state and materializes the next scheduled occurrence.
HTTP API and MCP clients can create occurrence notes without using the desktop context menu. Use `POST /api/tasks/:id/materialize-occurrence` or the MCP `tasknotes_materialize_occurrence` tool with a parent task path and occurrence date. Completing a recurring instance through the API or MCP also respects existing occurrence notes and the **Create next after completion** policy.
The same submenu also controls the next-note trigger:
- **Completion only**: create the next occurrence note only when the current occurrence is completed.
- **Completion or skip**: create the next occurrence note when the current occurrence is completed or skipped.
Skip/unskip controls appear on materialized occurrence notes when a skipped status is configured. Skipping an occurrence preserves the note, updates its status, and reconciles the parent `skipped_instances` list.
### Completion Reconciliation
When a materialized occurrence note is completed, TaskNotes updates both sides of the relationship:
- The occurrence note is completed like a normal task.
- The parent adds the occurrence date to `complete_instances`.
- The parent removes that date from `skipped_instances` if needed.
- The parent recalculates `scheduled` to the next uncompleted occurrence.
- If the parent policy is **Create next after completion**, TaskNotes creates the next occurrence note idempotently.
Uncompleting an occurrence note removes the date from the parent's `complete_instances` list, but it does not delete later occurrence notes that were already created.
### Example Behavior
```yaml
# Initial state
recurrence: "DTSTART:20250804T090000Z;FREQ=DAILY"
scheduled: "2025-08-04T09:00"
complete_instances: []
# After completing Aug 4
recurrence: "DTSTART:20250804T090000Z;FREQ=DAILY"
scheduled: "2025-08-05T09:00"
complete_instances: ["2025-08-04"]
# After manually rescheduling next occurrence
recurrence: "DTSTART:20250804T090000Z;FREQ=DAILY"
scheduled: "2025-08-05T14:30"
complete_instances: ["2025-08-04"]
```
## Calendar Drag and Drop
Calendar interactions follow the same model distinction: drag the concrete next item to reschedule execution, or drag a pattern instance to redefine the recurrence anchor.
Recurring tasks can show:
- **Next occurrence** (solid border): dragging updates only `scheduled`
- **Pattern instances** (dashed border): dragging updates `DTSTART` and future pattern instances
- **Materialized occurrence notes**: dragging updates the occurrence note's own `scheduled` or `due` date like a normal task, without changing the parent's recurrence rule
Materialized occurrence notes keep `occurrence_date` as their identity. If you drag the note for the June 1 occurrence to June 2, it is still the June 1 recurrence instance, now scheduled for June 2. TaskNotes suppresses the June 1 virtual parent event and leaves the June 2 virtual occurrence alone unless that date also has its own materialized note.
## Completion Tracking
Each occurrence can be completed or skipped independently (task cards, calendar menus, task edit modal completion calendar).
Completed instances are stored in:
```yaml
complete_instances: ["2025-08-04", "2025-08-06", "2025-08-08"]
```
Skipped instances are stored in:
```yaml
skipped_instances: ["2025-08-05"]
```
When completion changes, `scheduled` updates to the next uncompleted instance. If a materialized occurrence note exists for a date, that note's own status takes precedence for that occurrence, and TaskNotes reconciles the parent compatibility lists during completion, uncompletion, skip, and unskip actions.
This means completion history and next-action planning stay synchronized automatically, without manually advancing recurring tasks.
## Flexible Scheduling
TaskNotes intentionally allows off-pattern scheduling so recurring tasks can absorb real-world disruptions without rewriting the entire recurrence rule.
The next occurrence can be:
- Before `DTSTART`
- Outside the pattern day
- At a different time than pattern instances
- Far ahead while pattern continues unchanged
### Examples
```yaml
# Early start before DTSTART
recurrence: "DTSTART:20250810T090000Z;FREQ=WEEKLY;BYDAY=MO"
scheduled: "2025-08-07T14:00"
```
```yaml
# Off-pattern next occurrence
recurrence: "DTSTART:20250804T090000Z;FREQ=WEEKLY;BYDAY=MO"
scheduled: "2025-08-06T15:30"
```
## Timezone Handling
Recurring task logic uses a UTC anchor approach:
- Pattern generation uses UTC dates
- `DTSTART` dates are interpreted as UTC anchors
- Display adapts to local timezone
- Prevents common off-by-one date issues
In other words, calculations stay stable internally while display remains local, which avoids drift when traveling or sharing vaults across timezones.
## Backward Compatibility
Recurring behavior remains compatible with older task data, so upgrades do not require manual note rewrites.
- Legacy RRule strings without `DTSTART` continue to work using `scheduled` as anchor
- Legacy recurrence objects are converted to RRule format
- Existing tasks continue to function without migration steps
- Mixed formats are handled transparently
---
# Task Management
Source: https://tasknotes.dev/obsidian/features/task-management/
This page covers task creation, properties, projects, dependencies, recurring tasks, and reminders. For the underlying architecture, see [Core Concepts](../core-concepts.md).
Use this page as the operational overview: how tasks are captured, how they are structured, and how relationships/automation behave. Detailed reference content for recurrence and reminders is split into dedicated pages linked near the end.
## Creating and Editing Tasks
You can create and edit tasks in a variety of ways. The primary method is through the **Task Creation Modal**, which can be accessed via the "Create new task" command or by clicking on dates or time slots in the calendar views. This modal provides an interface for setting all available task properties, including title, status, priority, and due dates.
TaskNotes keeps a storage title and a filename-safe title separate. When **Store title in filename** is enabled, forbidden filename characters are removed from the filename while the task title is preserved whenever it cannot be represented exactly by that filename. With another filename format, such as timestamp or UUID, the full title is stored in frontmatter.
For existing tasks, the **Quick actions for current task** command opens a keyboard-searchable action palette. It includes status, priority, time-tracking, archive, edit, and date actions, including built-in due and scheduled date presets such as today, tomorrow, this weekend, next week, and next month.
TaskNotes also supports **Natural Language Creation**, which allows you to create tasks by typing descriptions in plain English. The built-in parser can extract structured data from phrases like "Buy groceries tomorrow at 3pm @home #errands high priority."
In most workflows, users combine both approaches: fast capture with natural language, then occasional structured edits in the modal when more precision is needed.
### Auto-Suggestions in Natural Language Input
The natural language input field includes auto-suggestion functionality that activates when typing specific trigger characters:
- **@** - Shows available contexts from existing tasks
- **#** - Shows available tags from existing tasks
- **+** - Shows files from your vault as project suggestions
- **\*** - Shows available status options (configurable trigger in Settings → Features)
In task creation and edit fields, focusing the tags or contexts input also opens the available suggestions immediately, so you can pick from the current vocabulary without typing a first character.
#### Project Suggestions
When typing `+` in the natural language input, you'll see up to 20 suggestions from your vault's markdown files. The suggestions display additional information to help identify files:
```
project-alpha [title: Alpha Project Development | aliases: alpha, proj-alpha]
meeting-notes [title: Weekly Team Meeting Notes]
simple-project
work-file [aliases: work, office-tasks]
```
Project suggestions search across:
- File names (basename without extension)
- Frontmatter titles (using your configured field mapping)
- Frontmatter aliases
- Optional filtering by required tags, folders, and a specific frontmatter property/value defined in Settings → Appearance & UI → Project Autosuggest
Selecting a project suggestion inserts it as `+[[filename]]`, creating a wikilink to the file while maintaining the `+` project marker that the natural language parser recognizes.
#### Enhanced Project Auto‑suggester (configurable cards)
Project suggestions can display configurable multi‑row cards and support smarter search. Configure up to 3 rows using a simple token syntax in Settings → Appearance & UI → Project Autosuggest.
- Properties: file.basename, file.name, file.path, file.parent, title, aliases, and any frontmatter key
- Flags:
- n or n(Label) → show the field name/label before the value
- s → include this field in + search (in addition to defaults)
- Literals: you can mix in fixed text or emojis between tokens
Examples
- "{title|n(Title)}" → Title: Alpha Project
- "🔖 {aliases|n(Aliases)}" → 🔖 Aliases: alpha, proj-alpha
- "{file.path|n(Path)|s}" → include path in + search as well as display it
Search behavior
- Defaults: + search always includes file basename, title (via your field mapping), and aliases
- |s flag: add more searchable fields on top of the defaults (e.g., file.path or a custom frontmatter key like customer)
- Fuzzy: optional fuzzy matching can be enabled in settings for broader, multi‑word matches
Performance tips
- Keep rows to three or fewer for clarity and performance (the UI supports up to 3)
- Prefer specific searchable fields with |s on large vaults
Demo
#### Status Suggestions
When typing the status trigger character (default `*`) in the natural language input, you'll see suggestions for all configured status options:
Status suggestions allow quick selection of statuses when creating tasks. For example, typing `*in` shows "In Progress" as a suggestion if that's one of your configured statuses.
Clicking a task card's status indicator cycles through statuses in the order configured under **Settings → Task Properties → Status**. A status can optionally define a specific **Next status** for forward cycling; otherwise TaskNotes uses the configured order. Statuses marked **Skip when cycling** are left out of the ordered click cycle, but remain available through menus, suggestions, direct edits, and explicit next-status jumps.
Additionally, you can convert any line type in your notes to TaskNotes using the **Instant Conversion** feature. This works with checkboxes, bullet points, numbered lists, blockquotes, headers, and plain text lines.
## Task Properties
Tasks store their data in YAML frontmatter with properties for status, priority, dates, contexts, projects, tags, time estimates, recurrence, and reminders. Custom fields can extend this structure.
This frontmatter-first design keeps task data editable and portable while supporting consistent behavior across views and widgets.
For property types and examples, see [Core Concepts](../core-concepts.md#yaml-frontmatter). For configuration options, see [Task Properties Settings](../settings/task-properties.md).
## Projects
TaskNotes supports organizing tasks into projects using note-based linking. Projects are represented as links to actual notes in your vault, allowing you to leverage Obsidian's linking and backlinking features for project management.
This model avoids creating a separate project database. Any note can become a project anchor, and task/project relationships remain visible through normal Obsidian link tooling.
### Project Assignment
Tasks can be assigned to one or more projects through the task creation or editing interface. When creating or editing a task, click the "Add Project" button to open the project selection modal. This modal provides fuzzy search functionality to quickly find and select project notes from your vault.
### Project Links
Projects are stored as wikilinks in the task's frontmatter (e.g., `projects: ["[[Project A]]", "[[Project B]]"]`). These links are clickable in the task interface and will navigate directly to the project notes when clicked. Any note in your vault can serve as a project note simply by being linked from a task's projects field.
### Organization and Filtering
Tasks can be filtered and grouped by their associated projects in all Bases-driven task views. Use the Bases filter editor to add `note.projects` conditions, and configure the grouping menu to organize Task List or Kanban boards by project. Tasks assigned to multiple projects will appear in each relevant project group, providing flexibility in project-based organization.
### Project Indicators
TaskCards display visual indicators when tasks are used as projects. These indicators help identify which tasks have other tasks linked to them as subtasks, making project hierarchy visible at a glance.
### Subtask Creation
Tasks can have subtasks created directly from their context menu. When viewing a task that serves as a project, you can select "Create subtask" to create a new task automatically linked to the current project.
## Dependencies
Task dependencies capture prerequisite work using RFC 9253 terminology. Dependencies are stored in frontmatter as structured objects:
```yaml
blockedBy:
- uid: "[[Operations/Order hardware]]"
reltype: FINISHTOSTART
gap: P1D
```
- `uid` references the blocking task, typically through an Obsidian wikilink.
- `reltype` is stored with each dependency and defaults to `FINISHTOSTART` for dependencies created in the UI.
- `gap` is optional and uses ISO 8601 duration syntax (for example `PT4H` or `P2D`).
Whenever a dependency is added, TaskNotes updates the upstream note’s `blocking` list so the reverse relationship stays synchronized. Removing a dependency automatically clears both sides.
### Selecting dependencies in the UI
- The task creation and edit modals expose “Blocked by” and “Blocking” buttons that launch a fuzzy task selector. The picker only offers valid tasks, excludes the current note, and prevents duplicate entries.
- The task context menu provides the same selector, enabling dependency management directly from the Task List, Kanban, and calendar views.
- Task cards show a fork icon whenever a task blocks other work. Clicking it expands an inline list of downstream tasks without triggering the parent card’s modal, so you can inspect dependents in place.
These controls currently create and manage finish-to-start style blockers. Advanced `reltype` values and `gap` data are preserved in frontmatter, but blocking evaluation is currently based on whether unresolved dependencies exist rather than relationship-type-specific scheduling rules.
## Automation
### Auto-Archiving
TaskNotes can automatically archive tasks when they transition into a status that has auto-archiving enabled. This keeps completed work out of your active lists without requiring manual cleanup.
Configure auto-archiving per status from **Settings → Task Properties → Task Statuses**. Each status card includes an **Auto-archive** toggle and a **Delay (minutes)** input (1–1440). When you turn the toggle on for a status, any task moved into that status is queued for archiving once the delay elapses. Moving the task to a different status before the timer expires cancels the pending archive automatically.
The auto-archive queue runs in the background and persists across plugin restarts. If TaskNotes was closed while an archive was pending, the task will be archived shortly after the plugin loads again as long as it still matches the configured status.
This automation is intended to keep active views focused without manual cleanup, while still preserving archived task history in your vault.
## File Management and Templates
TaskNotes supports configurable task folder locations, filename generation patterns, archive behavior, and body templates for newly created tasks.
These settings let you align task files with existing vault conventions (for example, date-based folders, project-based routing, or template-driven task note scaffolds).
For configuration details, see [Task Defaults](../settings/task-defaults.md).
For template variables, see [Template Variables Reference](template-variables.md).
## Recurring Tasks
TaskNotes recurring tasks use RFC 5545 RRule syntax with `DTSTART`, separate pattern definition from next occurrence scheduling, and support independent instance completion. When an individual recurrence needs its own checklist, time entries, or notes, you can create a materialized occurrence note from the task or calendar context menu.
For full behavior, examples, and edge cases, see [Recurring Tasks](recurring-tasks.md).
## Task Reminders
Task reminders support relative offsets from due/scheduled dates and absolute date-time reminders. You can add reminders from task modals, task cards, and context menus.
For full setup, data format, defaults, and UI behavior, see [Task Reminders](reminders.md).
---
# Use TaskNotes App with your vault
Source: https://tasknotes.dev/obsidian/guides/tasknotes-app/
# Use TaskNotes App with your vault
TaskNotes App is TaskNotes for the web, iPhone and Android. It works with the same Markdown task notes as the Obsidian plugin, so a task you edit in the app is the same note you see in Obsidian.
- Web: [app.tasknotes.dev](https://app.tasknotes.dev/)
- iPhone: [TaskNotes in the App Store](https://apps.apple.com/app/tasknotes/id6797168033)
- Android: [TaskNotes on Google Play](https://play.google.com/store/apps/details?id=dev.tasknotes.app)
In TaskNotes releases after 5.0.0-beta.9, **Settings → TaskNotes → TaskNotes App** in Obsidian has the same links, QR codes for the App Store and Google Play, and the setup steps below. The **TaskNotes: Set up TaskNotes App** command opens that page.
## Try it first
Open [app.tasknotes.dev](https://app.tasknotes.dev/) in a browser. Without an account, it opens an empty collection that is saved only in that browser, so you can try it straight away. It does not show the tasks in your vault until you sync the vault, as described below.
## How TaskNotes App reaches your vault
TaskNotes App cannot open files on your computer by itself. The mdbase Connect desktop app syncs your vault folder with your mdbase Connect account, and TaskNotes App signs in to the same account. The vault stays where it is, as ordinary Markdown files, and Obsidian keeps working with it as before.
You need:
- TaskNotes 5.0 beta or later in Obsidian, on every device that uses the vault. TaskNotes 4 can overwrite the task definitions that TaskNotes App uses.
- The [mdbase Connect desktop app](https://mdbase.dev/downloads/) for macOS, Windows or Linux, on the computer that has your vault. mdbase Connect is in beta.
- An mdbase Connect account. You can create one from the desktop app.
Back up your vault before you start. See [Backup, restore, and removal](backup-recovery.md).
## Set up
1. In Obsidian, turn on the mdbase type definitions, so TaskNotes writes `mdbase.yaml` and the task type that TaskNotes App reads:
- After 5.0.0-beta.9: **Settings → TaskNotes → TaskNotes App → Turn on type definitions**.
- In 5.0.0-beta.9 and earlier: **Settings → TaskNotes → Calendars & integrations → Generate mdbase type definitions**.
Vaults updated from TaskNotes 4 have this off until you turn it on.
2. Install [mdbase Connect](https://mdbase.dev/downloads/) on the computer that has your vault and open it. Choose **Sign in with your browser**, sign in or create an account, then choose **Approve computer**.
3. In mdbase Connect, choose **Add existing folder** and select your vault's folder: the folder that contains the hidden `.obsidian` folder. In releases after 5.0.0-beta.9, **Copy folder path** on the TaskNotes App settings page copies it.
4. Open **Collections**, open the vault's **…** menu and choose **Turn on sync**, then choose **Turn on sync** again. mdbase Connect uploads the files in the folder and keeps them in sync. The folder stays where it is.
5. Open TaskNotes App on the web, iPhone or Android, sign in with the same account, choose the collection and choose **Open TaskNotes**.
6. The first time, TaskNotes App asks to set up the collection. Choose **Set up**, or **Continue** if nothing needs to change.
**Before step 6,** update TaskNotes to version 5 on every device that uses the vault. TaskNotes App's setup writes the task type whether or not type definitions are turned on in Obsidian, and a device still running TaskNotes 4 with **Generate mdbase type definitions** turned on can overwrite it.
After step 3, the TaskNotes App settings page shows the vault as added to mdbase Connect.
## Use one sync service per vault
Once mdbase Connect syncs the vault, stop syncing it with any other service, such as Obsidian Sync, iCloud Drive, Dropbox, OneDrive, Google Drive or Syncthing. Two services syncing the same folder can create conflicting copies of your notes.
- **Other computers:** install mdbase Connect on each computer where you use the vault in Obsidian, sync the collection to a folder there, and open that folder as a vault in Obsidian.
- **Phones:** Obsidian on iPhone and Android cannot sync through mdbase Connect. On your phone, use TaskNotes App for your tasks.
If you rely on another service to use the whole vault in Obsidian on your phone, keep using it, and don't sync the vault with mdbase Connect.
## What changes in your vault
- `mdbase.yaml` and the `_mdbase/` folder hold the task definitions and the TaskNotes settings record that the plugin and the app share. TaskNotes hides them in the file explorer by default. See [mdbase collections](../migration-v4-to-v5.md#mdbase-collections).
- mdbase Connect keeps its sync state in the hidden `.mdbase/` folder. Don't edit or delete it.
- Tasks created or changed in TaskNotes App are ordinary task notes, written in the same format as the plugin's.
## Use your tasks from Claude
The same setup lets AI apps such as Claude reach your tasks, even when Obsidian is closed. Add the [mdbase MCP server](https://mdbase.dev/apps/mcp/) to your AI app and approve the collection. TaskNotes' own [HTTP API](../HTTP_API.md) and MCP server work only while Obsidian is open on that computer.
## Stop syncing
In mdbase Connect, remove the collection. Apps stop using it, and the folder and its files stay where they are.
---
# TaskNotes HTTP API
Source: https://tasknotes.dev/obsidian/HTTP_API/
The TaskNotes HTTP API provides local HTTP access to tasks, time tracking, pomodoro, calendars, webhooks, and NLP parsing.
## Availability
- Desktop only
- Disabled by default
- Started when Obsidian starts and TaskNotes API is enabled
- Bound to loopback (`127.0.0.1`) only, not the local network
- Browser CORS requests are allowed only from loopback origins such as
`localhost`, `127.0.0.1`, and `[::1]`
- Not available on mobile
Enable it under **Settings → TaskNotes → Integrations → HTTP API** in v4, or **Settings → TaskNotes → Advanced → HTTP API** in the v5 beta.
## Base URL
`http://localhost:{PORT}`
Default port is `8080`.
## Authentication
Authentication is required for both HTTP API and MCP requests in **TaskNotes 4.13.0 and later**, including the v5 beta.
- Send `Authorization: Bearer ` using the TaskNotes token from the HTTP API settings page described above.
- If `apiAuthToken` is empty at startup, TaskNotes generates and saves a token before starting the server.
- Clearing the token does not enable unauthenticated access; requests are rejected until a token is configured or generated at the next server start.
- Existing clients that omitted authentication must be updated to send the token. Keep it private.
### Token storage in the v5 beta
In v4, the HTTP API token is stored in `data.json`. In v5, it moves to Obsidian Secret Storage on each device. Syncing or committing `data.json` does not share the v5 token. A synced device that starts after the token has been removed from `data.json` generates its own token and shows a notice. Copy that device's token into its API and MCP clients. See [Synced devices](migration-v4-to-v5.md#synced-devices).
Example:
```bash
curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8080/api/health
```
## Connecting Claude Desktop with MCP
Use a **TaskNotes API token**, not a Claude/Anthropic API key. The local MCP endpoint uses bearer authentication, not OAuth registration.
1. Open **Settings → TaskNotes → Integrations** in v4, or **Advanced** in the v5 beta, and enable **HTTP API** and **MCP server**.
2. If the TaskNotes token is empty, restart Obsidian to generate one. An existing token can be reused; do not clear it unless you intend to replace it in all clients.
3. Return to the same settings page and copy the generated token. Keep it private.
4. In Claude Desktop, open **Settings → Developer → Edit Config** and add this entry, preserving any other MCP servers:
```json
{
"mcpServers": {
"Tasknotes": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"http://127.0.0.1:8080/mcp",
"--header",
"Authorization:${AUTH_HEADER}"
],
"env": {
"AUTH_HEADER": "Bearer YOUR_TASKNOTES_API_TOKEN"
}
}
}
}
```
Replace `YOUR_TASKNOTES_API_TOKEN` with the token from TaskNotes, keeping the `Bearer ` prefix. Change `8080` if you configured a different port. Node.js/npm must be installed so Claude can run `npx`.
5. Fully quit and reopen Claude Desktop. Keep Obsidian running while using the tools.
If Claude reports **Server Disconnected**, first check that the bearer header contains the current TaskNotes token. A missing or rejected token can cause the client to attempt OAuth registration, which this endpoint does not provide. After replacing a token, update every client and restart Claude. Do not disable authentication as a workaround.
## Response Format
Success:
```json
{
"success": true,
"data": {}
}
```
Error:
```json
{
"success": false,
"error": "Error message"
}
```
## Endpoint Index
### System
- `GET /api/health`
- `GET /api/docs`
- `GET /api/docs/ui`
- `POST /api/nlp/parse`
- `POST /api/nlp/create`
### Tasks
- `GET /api/tasks`
- `POST /api/tasks`
- `GET /api/tasks/:id`
- `PUT /api/tasks/:id`
- `DELETE /api/tasks/:id`
- `POST /api/tasks/:id/toggle-status`
- `POST /api/tasks/:id/archive`
- `POST /api/tasks/:id/complete-instance`
- `POST /api/tasks/:id/materialize-occurrence`
- `POST /api/tasks/query`
- `GET /api/filter-options`
- `GET /api/stats`
### Bases
- `POST /api/bases/default-files/update`
### Time Tracking
- `POST /api/tasks/:id/time/start`
- `POST /api/tasks/:id/time/start-with-description`
- `POST /api/tasks/:id/time/stop`
- `GET /api/tasks/:id/time`
- `GET /api/time/active`
- `GET /api/time/summary`
### Pomodoro
- `POST /api/pomodoro/start`
- `POST /api/pomodoro/stop`
- `POST /api/pomodoro/pause`
- `POST /api/pomodoro/resume`
- `GET /api/pomodoro/status`
- `GET /api/pomodoro/sessions`
- `GET /api/pomodoro/stats`
### Calendars
- `GET /api/calendars`
- `GET /api/calendars/google`
- `GET /api/calendars/microsoft`
- `GET /api/calendars/subscriptions`
- `GET /api/calendars/events`
### Webhooks
- `POST /api/webhooks`
- `GET /api/webhooks`
- `DELETE /api/webhooks/:id`
- `GET /api/webhooks/deliveries`
See `docs/webhooks.md` for event and transform details.
## Route Details
## Health
### `GET /api/health`
Returns service state plus vault metadata.
```bash
curl http://localhost:8080/api/health
```
## Tasks
### `GET /api/tasks`
Basic task listing with pagination only.
Query params:
- `limit` (default `50`, max `200`)
- `offset` (default `0`)
Important:
- Filtering params such as `status`, `priority`, `tag`, `project`, `context`, `due_before`, `due_after`, `overdue`, `completed`, `archived`, and `sort` are rejected on this endpoint with HTTP `400`.
- Use `POST /api/tasks/query` for filtering.
Example:
```bash
curl "http://localhost:8080/api/tasks?limit=25&offset=0"
```
Response fields:
- `data.tasks`
- `data.pagination` with `total`, `offset`, `limit`, `hasMore`
- `data.vault`
- `data.note`
- Task objects include configured TaskNotes user fields in `customProperties`, keyed by their frontmatter property key.
### `POST /api/tasks`
Create one task.
Required:
- `title`
Common optional fields:
- `details`, `status`, `priority`, `due`, `scheduled`
- `tags`, `contexts`, `projects`
- `recurrence`, `recurrence_anchor`, `timeEstimate`, `reminders`
- `blockedBy`
`blockedBy` accepts an array of dependency objects:
- `uid`: link or identifier for the blocking task, such as `[[Project setup]]`
- `reltype`: one of `FINISHTOSTART`, `FINISHTOFINISH`, `STARTTOSTART`, or `STARTTOFINISH`
- `gap`: optional ISO 8601 duration, such as `P1D`
`blocking` is a read-only reverse relationship in API responses. To make a task block existing tasks, update those existing tasks' `blockedBy` fields.
```bash
curl -X POST http://localhost:8080/api/tasks \
-H "Content-Type: application/json" \
-d '{"title":"Review docs","priority":"high","blockedBy":[{"uid":"[[Draft docs]]","reltype":"FINISHTOSTART"}]}'
```
Returns HTTP `201` with created task data.
### `GET /api/tasks/:id`
Get one task by path id.
- `:id` must be URL-encoded task path.
- Single-task reads include the task body in `details`.
- Configured TaskNotes user fields are returned in `customProperties`, keyed by their frontmatter property key.
```bash
curl "http://localhost:8080/api/tasks/TaskNotes%2FTasks%2FReview%20docs.md"
```
### `PUT /api/tasks/:id`
Update task with partial payload.
Configured TaskNotes user fields can be updated either by their frontmatter property key or via `customProperties`.
```bash
curl -X PUT "http://localhost:8080/api/tasks/TaskNotes%2FTasks%2FReview%20docs.md" \
-H "Content-Type: application/json" \
-d '{"status":"in-progress"}'
```
### `DELETE /api/tasks/:id`
Delete task file.
### `POST /api/tasks/:id/toggle-status`
Toggle task status via configured workflow.
### `POST /api/tasks/:id/archive`
Toggle archive state.
### `POST /api/tasks/:id/complete-instance`
Complete recurring instance.
Request body:
- Optional `date` (ISO string). If omitted, uses current date context.
When the recurring parent uses materialized occurrence notes, this endpoint completes the matching occurrence note if one exists. If the parent is set to **Create next after completion** and no matching occurrence note exists yet, TaskNotes creates and completes that occurrence note instead of only recording a virtual `complete_instances` entry.
### `POST /api/tasks/:id/materialize-occurrence`
Create or return a materialized occurrence note for a recurring task date. This endpoint is idempotent for the same parent and date.
Request body:
- Required `date` (ISO date string, for example `2026-06-01`)
### `POST /api/tasks/query`
Advanced filtering.
Request body is a `FilterQuery` object. `FilterQuery` is still the supported advanced query shape for the HTTP API.
The root object is a group with:
- `type: "group"`
- `id`
- `conjunction: "and" | "or"`
- `children` (conditions or groups)
Optional top-level query options:
- `sortKey`, `sortDirection`
- `groupKey`, `subgroupKey`
Example:
```json
{
"type": "group",
"id": "root",
"conjunction": "and",
"children": [
{
"type": "condition",
"id": "c1",
"property": "status",
"operator": "is",
"value": "open"
}
],
"sortKey": "due",
"sortDirection": "asc"
}
```
Filter tasks by context:
```json
{
"type": "group",
"id": "root",
"conjunction": "and",
"children": [
{
"type": "condition",
"id": "context",
"property": "contexts",
"operator": "contains",
"value": "@office"
}
],
"sortKey": "due",
"sortDirection": "asc"
}
```
Filter active, unarchived tasks, similar to the default available-task view:
```json
{
"type": "group",
"id": "root",
"conjunction": "and",
"children": [
{
"type": "condition",
"id": "not-archived",
"property": "archived",
"operator": "is-not-checked"
},
{
"type": "condition",
"id": "not-completed",
"property": "status.isCompleted",
"operator": "is-not-checked"
}
],
"sortKey": "due",
"sortDirection": "asc",
"groupKey": "none"
}
```
Condition fields:
- `type`: `"condition"`
- `id`: any stable string for your client
- `property`: a task property, such as `title`, `status`, `priority`, `tags`, `contexts`, `projects`, `blockedBy`, `blocking`, `due`, `scheduled`, `completedDate`, `dateCreated`, `dateModified`, `archived`, `hasSubtasks`, `dependencies.isBlocked`, `dependencies.isBlocking`, `timeEstimate`, `recurrence`, or `status.isCompleted`
- `operator`: one of `is`, `is-not`, `contains`, `does-not-contain`, `is-before`, `is-after`, `is-on-or-before`, `is-on-or-after`, `is-empty`, `is-not-empty`, `is-checked`, `is-not-checked`, `is-greater-than`, `is-less-than`, `is-greater-than-or-equal`, or `is-less-than-or-equal`
- `value`: required for comparison operators, omitted for empty/checked operators
For user-defined fields, use `property: "user:"`.
Response:
- `data.tasks`
- `data.total`
- `data.filtered`
- `data.vault`
### `GET /api/filter-options`
Returns filter options for UI builders.
### `GET /api/stats`
Returns summary counts:
- `total`, `completed`, `active`, `overdue`, `archived`, `withTimeTracking`
## Bases
### `POST /api/bases/default-files/update`
Overwrite the configured default TaskNotes `.base` files with templates generated from the current TaskNotes settings. This is the same write operation as **Settings -> TaskNotes -> Views & base files -> Update files** and replaces manual edits in those configured default files.
```bash
curl -X POST http://localhost:8080/api/bases/default-files/update
```
Response fields:
- `data.created`: default files created because they were missing
- `data.updated`: existing default files overwritten with current templates
- `data.skipped`: configured default files skipped
## Time Tracking
### `POST /api/tasks/:id/time/start`
Starts a new active time entry for that task.
### `POST /api/tasks/:id/time/start-with-description`
Starts time tracking and writes `description` on the new active entry.
Request body:
```json
{
"description": "Implementation"
}
```
### `POST /api/tasks/:id/time/stop`
Stops active time entry for that task.
### `GET /api/tasks/:id/time`
Returns per-task time summary and entries.
### `GET /api/time/active`
Returns currently active sessions across tasks.
Important:
- Multiple active sessions can exist across different tasks.
### `GET /api/time/summary`
Returns aggregate time summary.
Query params:
- `period` (for example `today`, `week`, `month`, `all`)
- `from` (ISO date)
- `to` (ISO date)
Example:
```bash
curl "http://localhost:8080/api/time/summary?period=week"
```
## Pomodoro
### `POST /api/pomodoro/start`
Starts a session.
Optional request fields:
- `taskId` (URL path of task)
- `duration` (number)
### `POST /api/pomodoro/stop`
Stops and resets current session.
### `POST /api/pomodoro/pause`
Pauses running session.
### `POST /api/pomodoro/resume`
Resumes paused session.
### `GET /api/pomodoro/status`
Returns current state plus computed totals (`totalPomodoros`, `currentStreak`, `totalMinutesToday`).
### `GET /api/pomodoro/sessions`
Returns history.
Query params:
- `limit`
- `date` (`YYYY-MM-DD`)
### `GET /api/pomodoro/stats`
Returns stats for today or provided date.
Query params:
- `date` (`YYYY-MM-DD`)
## Calendars
### `GET /api/calendars`
Returns provider connectivity overview and subscription counts.
### `GET /api/calendars/google`
Returns Google provider details.
- If disconnected, returns `{ "connected": false }`.
### `GET /api/calendars/microsoft`
Returns Microsoft provider details.
- If disconnected, returns `{ "connected": false }`.
### `GET /api/calendars/subscriptions`
Returns ICS subscriptions with runtime fields such as `lastFetched` and `lastError`.
### `GET /api/calendars/events`
Returns merged event list from connected providers and ICS subscriptions.
Query params:
- `start` (ISO date/datetime)
- `end` (ISO date/datetime)
Response includes:
- `events`
- `total`
- `sources` (counts by provider)
## Webhooks
### `POST /api/webhooks`
Registers webhook.
Required fields:
- `url`
- `events` (non-empty array)
Optional fields:
- `id`
- `secret`
- `active`
- `transformFile`
- `corsHeaders`
### `GET /api/webhooks`
Lists registered webhooks. Stored secrets are not returned.
### `DELETE /api/webhooks/:id`
Deletes webhook.
### `GET /api/webhooks/deliveries`
Returns last 100 delivery records.
## OpenAPI Docs
### `GET /api/docs`
Returns OpenAPI JSON generated from registered controllers.
### `GET /api/docs/ui`
Returns Swagger UI.
## Errors
Common status codes:
- `400` invalid request or invalid state
- `401` missing/invalid bearer token (when auth token is configured)
- `404` missing task/webhook/resource
- `500` internal error
## Security Notes
Current behavior:
- CORS allows all origins (`*`).
- Transport is HTTP only (no TLS).
- Node server is started with `server.listen(port)` and does not explicitly bind to `127.0.0.1`.
Practical guidance:
- Set an auth token.
- Treat API port as sensitive and keep it firewalled.
- If you expose this port outside localhost, route through a trusted reverse proxy and TLS.
## Troubleshooting
### API unavailable
1. Confirm API is enabled in settings.
2. Confirm Obsidian is running.
3. Confirm selected port is free.
4. Reload plugin or restart Obsidian after changing API enable/port.
### `401 Authentication required`
1. Check token value.
2. Check `Bearer ` prefix.
3. Remove whitespace around token.
### Unexpected task list behavior
If you pass filters to `GET /api/tasks`, the endpoint returns `400` by design. Use `POST /api/tasks/query`.
---
# Upgrading from v4 to v5
Source: https://tasknotes.dev/obsidian/migration-v4-to-v5/
# Upgrading from v4 to v5
!!! info "TaskNotes v5 beta"
This guide covers **5.0.0-beta.5**. The beta is opt-in; TaskNotes v4 remains the recommended stable release. The main documentation describes v4 unless a section is labelled for v5.
TaskNotes v5 keeps your task files, Base files, and settings. Most of the upgrade happens automatically on first launch. This guide covers what changes, what moves, and what to check afterwards.
!!! warning "Back up before upgrading"
Back up the complete vault, including the hidden `.obsidian` directory, before upgrading. Finish syncing first and avoid simultaneous metadata updates on other devices, especially on mobile. See [Backup and recovery](guides/backup-recovery.md#interrupted-mdbase-metadata-updates).
## Requirements
- **Obsidian 1.13.1 or later**. Obsidian does not offer TaskNotes v5 to older Obsidian versions.
- **Bases core plugin enabled** (Settings → Core plugins → Bases), as in v4.
If you are upgrading from a release earlier than 4.13.0, HTTP API and MCP clients also need a TaskNotes API token. See [HTTP API authentication](HTTP_API.md#authentication).
## What happens on first launch
1. Your existing `data.json` settings are read and kept. New settings receive their defaults. If TaskNotes cannot read the settings or determine whether the file exists, startup stops rather than saving defaults over it. Resolve the storage or sync error and restart.
2. The HTTP API token moves from `data.json` to Obsidian Secret Storage on that device. The last-seen and last-notified release versions move to per-device storage. These values are removed from `data.json` once they have been stored.
3. If the mdbase integration is enabled, TaskNotes-generated mdbase v0.2 metadata is upgraded to v0.3. See [mdbase collections](#mdbase-collections).
Task notes are not rewritten during the upgrade.
## Synced devices
Upgrade every device that syncs the vault. Running v4 and v5 against the same `data.json` is not supported.
Obsidian Secret Storage is kept on each device and is not synced. After upgrading:
- **HTTP API**: each device that runs the HTTP API has its own token. A device that starts TaskNotes v5 after another device has already removed the token from `data.json` generates a new token and shows a notice. Copy the new token into the API and MCP clients on that device from **Settings → TaskNotes → Advanced**.
- **Calendar accounts**: OAuth credentials and account tokens have been stored in Secret Storage since 4.x. Devices that were not connected before need to be connected separately, as in 4.x.
## Settings are reorganized
Settings now use Obsidian's native settings pages, navigation, and search. Individual settings can be found from Obsidian's settings search. Existing preferences are retained, but grouped differently:
| Page | Contains |
| --- | --- |
| Task files | Task identification, folders, filenames, and frontmatter |
| Properties | Property mappings, statuses, priorities, and custom properties |
| Task creation | Defaults, templates, natural-language input, and form fields |
| Appearance & interaction | Task cards, inline tasks, click behaviour, and view defaults |
| Time & reminders | Notifications, time tracking, recurrence, Pomodoro, and timeblocking |
| Calendars & integrations | Calendar accounts, subscriptions, task export, and interoperability |
| Advanced | Indexing, HTTP API, webhooks, and diagnostics |
These are the v5 settings routes. The main [Settings reference](settings.md) describes v4's tabs; use Obsidian's settings search to find individual options in v5.
## Stable task IDs
New and converted tasks receive a UUID in the `id` frontmatter property. The ID stays the same when a task file is renamed or moved, so integrations can refer to a task without depending on its path.
Existing tasks without an `id` remain valid and are not changed. Path-based integrations continue to work. The JavaScript API adds `getByPath()` and `getById()`; see the [v5 beta JavaScript API reference](https://github.com/callumalpass/tasknotes/blob/5.0.0-beta.5/docs/javascript-api.md).
## mdbase collections
If the mdbase integration is enabled, TaskNotes v5 publishes the portable `tasknotes.task` contract (version 0.3.0-rc.5) used by TaskNotes App and other compatible tools. It is the same contract, byte for byte, that TaskNotes App installs, so the plugin and the app can share a collection. Tasks can list assignees as links to person notes; the property is optional.
When the collection's only active type is an unmodified TaskNotes-generated v0.2 type, TaskNotes upgrades the metadata to mdbase v0.3 automatically. Generated formats from 4.3.2 through 4.13.7 are recognized using their historical writers and your saved settings, including BOM/CRLF formatting and reordered YAML mapping keys. Exact historical output containing v4's invalid unquoted status values can also be regenerated safely from those settings. The original bytes of `mdbase.yaml`, the task type and replaced support resources are kept under `.tasknotes/migrations/`; task notes are never rewritten.
If v4 added its generated task type to an existing v0.3 collection, TaskNotes upgrades that file in place and preserves foreign types and configuration instead of creating an overlapping task type.
Incomplete synced metadata is not treated as a new collection. If type or support files arrive before `mdbase.yaml`, TaskNotes waits without creating another type. The upgrade retries when the configuration or task type arrives. Finish syncing all metadata before diagnosing a blocked upgrade.
Additional v0.2 types or genuinely edited task/support definitions are preserved for review. The notice names the affected file. Back up the vault, finish syncing and restart first. If still blocked, restore the unmodified generated type **and matching saved settings** from a known-good backup, or use mdbase to migrate a separate copy and review all type definitions before replacing the active metadata. Do not delete a user-maintained type merely to make ownership recognition succeed. Known generated support resources tolerate line-ending changes; custom commentary or schema edits are not silently overwritten.
If you used a 5.0 beta, TaskNotes updates its task type to the current contract when the vault opens and tells you once. The previous type is backed up under `.tasknotes/migrations/`. The upgrade keeps existing property-role mappings (including custom stable IDs), binding policies, archive tags, occurrence horizons, custom schema constraints, extensions and Markdown body. It lifts the contract version and adds optional assignee support without rebuilding these policies from plugin defaults. Ordinary settings changes update only plugin-owned options. Text, number, date, boolean and list custom properties retain their declarations through migration and later settings saves, including legacy coercion-compatible schemas. An owned property whose type cannot be resolved stops settings import with a named diagnostic instead of disappearing. A leading UTF-8 BOM and CRLF line endings are accepted for canonical metadata as well as historical metadata; recovery copies retain the original bytes. Task files are not changed. Collections that TaskNotes App has already updated retain their task definitions. If a beta added a second task type named `tasknotes-task` after TaskNotes App updated the collection, TaskNotes moves that duplicate into a unique folder under `.tasknotes/migrations/`, preserving its relative path and actual bytes. Explicit record membership keeps the provider in place with a notice naming the type and record. A concurrent edit is preserved and blocks cleanup; task references are never rewritten.
### Interrupted updates and blocked collections
Both v0.2 migrations and beta metadata upgrades are backed up and journaled. Metadata is staged in sibling temporary files and read back. On desktop and mobile, each replacement first moves the actual active revision into a unique recovery path under `.tasknotes/migrations/metadata-swaps/` and compares those moved bytes with the expected original. The verified stage is published only after the active path is empty. When the adapter exposes a vault filesystem path and Node filesystem access, publication uses an atomic no-replace operation even when Obsidian emulates mobile. A late arrival remains active and blocks the update. On non-native storage, automatic migration remains enabled using the adapter's empty-destination move. A verified publication copy is moved while the intended stage, displaced original and journal are retained until active-byte read-back passes. If read-back differs from the intended stage, TaskNotes reports a conflict and keeps that evidence instead of reporting success. A changed revision captured at displacement is retained, restored to the active path if still empty, and reported as a conflict. Native files and containing directories are flushed where supported. The type is updated before activating its new contract, and configuration is committed last. A write failure restores unchanged original metadata. Restarting TaskNotes first recovers interrupted swaps, including an empty active path with its moved original present, then recovers the enclosing transaction before attempting another upgrade.
On iOS/Android adapters that internally check whether the destination exists and then rename, there is still a residual window between those steps. A revision arriving in that window can be overwritten; read-back cannot detect it if the final active bytes equal the intended stage. This adapter path is not an atomic no-replace guarantee. Finish syncing before upgrading, avoid simultaneous metadata updates on other devices, and retain a separate full-vault backup. See [Backup and recovery](guides/backup-recovery.md#interrupted-mdbase-metadata-updates).
A settings-save synchronization failure shows recovery details immediately, while distinguishing saved plugin settings from a completed metadata update. Repeated failures for the same pending journal do not repeat the notice during the session.
Recovery does **not** overwrite an external edit. If recovery is blocked, the notice identifies the pending journal (`.tasknotes/migrations/metadata-swaps/.json`, `mdbase-v0.2-pending.json` or `mdbase-v0.3-pending.json`), backup folder, and affected file. Close Obsidian on all syncing devices, make another full-vault backup, and compare the journal's snapshots/intended writes and backup manifest with the active files. Swap journals identify the expected original, intended bytes, stage and actual-revision recovery path; keep all those files. Preserve external changes separately before restoring a coherent config/type/support set. Do not delete a pending journal or restore only the contract file to force an upgrade; reload TaskNotes after resolving the conflict or file permissions. See [Backup and recovery](guides/backup-recovery.md).
When more than one TaskNotes provider remains, startup lists every candidate path and keeps the last-known-good plugin configuration. Review which provider the plugin should manage. Keep explicitly referenced providers until you have reviewed their membership; do not delete a definition merely to clear the warning. The App can support multiple providers, but the plugin's writable configuration currently requires one. The same unchanged multiple-provider notice is not repeated during a session.
Adapters without safe metadata replacement or move support stop with a notice rather than deleting existing files. Resolve the adapter limitation on a supported device before retrying.
Symlinked metadata directories are refused before changes are made. Use physical directories inside the vault and update `mdbase.yaml` to match; the engine also rejects symlinked type folders.
If the integration is not enabled, nothing changes.
Existing collection membership settings are retained: omitting `explicit_type_keys` means the engine's `type` and `types` defaults, and an explicit empty list remains empty. Only genuinely new plugin collections choose `mdbase_type`. TaskNotes encodes excluded folders as automatic task-type path predicates, including nested folders but not similarly named siblings; it does not globally exclude records of other types. Explicit membership in `type`, `types` or configured keys takes precedence over automatic matching, so explicitly typed tasks in those folders remain engine members even when hidden from plugin views. Collection-wide `settings.exclude` and `include_subfolders: false` still exclude those paths from the collection.
TaskNotes additively includes `md` and `base` record extensions and Base includes for `TaskNotes/Views` and folders containing configured view files. Existing extensions, includes and other collection configuration are never removed. When `record_extensions` is absent, its initial values preserve the engine's effective legacy `settings.extensions` (with Markdown always included) before adding `base`. Invalid extension settings stop reconciliation instead of silently narrowing record coverage; collection checks and duplicate-reference inventory use the same extension precedence. Invalid canonical mappings or binding policies are reported with the type's path and validation details; plugin settings remain at their last valid values. Review `implements.fields` (especially required `status` and `dateCreated`) and `binding`, then retry after correcting the configuration.
### TaskNotes App setup is separate
Metadata compatibility is not pack installation. TaskNotes does **not** create or stamp `mdbase.lock.yaml` or pack provenance. The first time TaskNotes App opens the collection, approve its one-time **Set up** step: the engine assesses and installs or upgrades packs, including saved-view/Base contracts. An `install` or `upgrade` assessment before that consent is expected, even when the task contract is already current. Existing pack locks are retained until engine-approved setup.
That setup writes the task type whether or not **Generate mdbase type definitions** is turned on in the plugin. Update TaskNotes to version 5 on every device that uses the vault first: a device still running TaskNotes 4 with that setting turned on can overwrite the type. See [Use TaskNotes App with your vault](guides/tasknotes-app.md).
### Check existing task records
Metadata migration never silently repairs old notes. A tag-identified task may lack the portable contract's required creation timestamp, or contain a status outside the configured vocabulary. Run **TaskNotes: Check collection** from the command palette after upgrading:
1. Review the invalid records and their schema/contract errors. Checking alone changes no notes. The check uses the collection's effective scope, including collection-wide exclusions, subfolder settings, nested collection boundaries and explicit membership. It includes explicitly typed tasks hidden by plugin folder exclusions, but never offers repairs outside the collection. Supported nested `fields_present` and `match.where` references use dotted paths, `[]` selectors or JSON Pointers, following the engine's first resolved value. String or array `path_glob` predicates are respected. Unparseable membership or unsupported predicate forms stop the scan rather than reporting a partial scan as clean.
2. For missing creation dates, **Back up and fix** offers the file's creation time. Check that time in the confirmation; copying files between devices can change filesystem creation times.
3. For invalid statuses, choose a replacement separately for each record. No status mapping is inferred. The all-record action applies only selected replacements and missing-date fixes; it leaves other errors untouched.
4. Confirm the exact listed changes. Each original note is verified in `.tasknotes/migrations/` before its change, and the repair refuses to overwrite a note or collection membership changed since the check. The current provider, status vocabulary and proposed schema/contract output are rechecked when applying the repair; a stale preview must be checked again. Cancel keeps every note unchanged.
5. Recheck the results. Other invalid fields, malformed notes and custom schema constraints need manual review. Custom CEL match expressions not generated by TaskNotes require engine validation rather than guessed membership.
For independent verification, use `mdbase -C validate`, `types list`, `query --types ` and `packs assess` with the App's manifest/resources. Compare task counts and mapped values, not just metadata version numbers. `Check collection` checks task record schemas, portable contract projections and status vocabulary; engine validation also checks collection-wide rules and links.
If the integration is not enabled, migration does nothing. The collection-check command requires existing canonical mdbase metadata.
## Interface changes
- The Statistics and Pomodoro statistics dashboards have been removed in beta.5. Close old statistics tabs after upgrading. Time tracking, Pomodoro history, the timer, and existing Base files are retained.
- Newly generated default Bases include Today, Inbox, and Archived review views and archive filters. Existing Base files remain unchanged unless you run **Update default base files**; back up any custom edits before doing so.
- Task cards show dates within a week of today as relative days, such as "Due: Yesterday" or "Scheduled: Monday". The full date appears on hover. To keep absolute dates, choose ISO dates under **Appearance & interaction → Display formatting**.
- The task context menu keeps status, priority, dates, reminders, time tracking, edit, and open at the top level. Other actions are under **More**.
- Kanban swimlanes can be collapsed from their label. Empty swimlanes start collapsed.
- New vaults hide the identifying task tag on task cards by default. Existing vaults keep their current setting.
## Returning to v4
To return to TaskNotes 4.x, restore the backup you made before upgrading. If you downgrade without restoring:
- 4.x no longer finds the HTTP API token in `data.json` and generates a new one when the API starts. Update your clients.
- 4.x no longer finds its last-seen version in `data.json`, so it treats the vault as a new install and may create the TaskNotes starter note. You can delete that note.
- If an mdbase upgrade ran, restore a coherent pre-upgrade set of `mdbase.yaml`, task type, and contract/schema resources together with matching plugin settings. Do not restore only one metadata file. Preserve newer task notes and external edits separately before restoring the pre-upgrade vault backup; see [Migration recovery](guides/backup-recovery.md#interrupted-mdbase-metadata-updates).
## Getting help
If something does not look right after upgrading, see [Troubleshooting](troubleshooting.md) or [report the problem](https://github.com/callumalpass/tasknotes/issues) with the output of Obsidian's **Show debug info** command.
---
# Command reference
Source: https://tasknotes.dev/obsidian/reference/commands/
This page is generated from the commands registered by TaskNotes. Command IDs are stable integration identifiers; names are the English labels shown in Obsidian.
| Command | ID | Available in |
| --- | --- | --- |
| Open mini calendar view | `open-calendar-view` | Global |
| Open calendar view | `open-advanced-calendar-view` | Global |
| Open tasks view | `open-tasks-view` | Global |
| Open agenda view | `open-agenda-view` | Global |
| Open Pomodoro timer | `open-pomodoro-view` | Global |
| Open Kanban board | `open-kanban-view` | Global |
| Update default base files | `update-default-base-files` | Global |
| Open Pomodoro statistics | `open-pomodoro-stats` | Global |
| Open task & project statistics | `open-statistics` | Global |
| Create new task | `create-new-task` | Global |
| Convert current note to task | `convert-current-note-to-task` | Global |
| Convert checkbox task to TaskNote | `convert-to-tasknote` | Editor |
| Convert all tasks in note | `batch-convert-all-tasks` | Editor |
| Insert tasknote link | `insert-tasknote-link` | Editor |
| Create new inline task | `create-inline-task` | Editor |
| Quick actions for current task | `quick-actions-current-task` | Global |
| Quick actions for task under cursor | `quick-actions-task-under-cursor` | Editor |
| Edit current task | `edit-current-task` | Global |
| Repeat current task | `repeat-current-task` | Global |
| Cycle current task status | `cycle-current-task-status` | Global |
| Cycle current task priority | `cycle-current-task-priority` | Global |
| Add project to current task | `add-project-to-current-task` | Global |
| Add subtask to current note | `add-subtask-to-current-note` | Global |
| Go to today's note | `go-to-today` | Global |
| Start Pomodoro timer | `start-pomodoro` | Global |
| Stop Pomodoro timer | `stop-pomodoro` | Global |
| Pause/resume Pomodoro timer | `pause-pomodoro` | Global |
| Refresh cache | `refresh-cache` | Global |
| Export all tasks as ICS file | `export-all-tasks-ics` | Global |
| Sync all tasks to Google Calendar | `sync-all-tasks-google-calendar` | Global |
| Sync current task to Google Calendar | `sync-current-task-google-calendar` | Global |
| View release notes | `view-release-notes` | Global |
| Start time tracking for current task | `start-time-tracking-current-task` | Global |
| Stop time tracking for current task | `stop-time-tracking-current-task` | Global |
| Stop active time tracking | `stop-active-time-tracking` | Global |
| Start time tracking (select task) | `start-time-tracking-with-selector` | Global |
| Edit time entries (select task) | `edit-time-entries` | Global |
| Create or open task | `create-or-open-task` | Global |
| Create or open task and start time tracking | `create-or-open-task-with-time-tracking` | Global |
| Postpone overdue scheduled tasks to today | `rollover-overdue-scheduled-tasks` | Global |
_Generated from 40 registered commands._
---
# HTTP route index
Source: https://tasknotes.dev/obsidian/reference/http-routes/
This index is generated from controller route decorators. The build fails if an implemented route is absent from the narrative [HTTP API guide](/HTTP_API/) or [NLP API guide](/nlp-api/).
| Method | Path | Controller |
| --- | --- | --- |
| `POST` | `/api/bases/default-files/update` | `BasesController` |
| `GET` | `/api/calendars` | `CalendarsController` |
| `GET` | `/api/calendars/events` | `CalendarsController` |
| `GET` | `/api/calendars/google` | `CalendarsController` |
| `GET` | `/api/calendars/microsoft` | `CalendarsController` |
| `GET` | `/api/calendars/subscriptions` | `CalendarsController` |
| `GET` | `/api/docs` | `SystemController` |
| `GET` | `/api/docs/ui` | `SystemController` |
| `GET` | `/api/filter-options` | `TasksController` |
| `GET` | `/api/health` | `SystemController` |
| `POST` | `/api/nlp/create` | `SystemController` |
| `POST` | `/api/nlp/parse` | `SystemController` |
| `POST` | `/api/pomodoro/pause` | `PomodoroController` |
| `POST` | `/api/pomodoro/resume` | `PomodoroController` |
| `GET` | `/api/pomodoro/sessions` | `PomodoroController` |
| `POST` | `/api/pomodoro/start` | `PomodoroController` |
| `GET` | `/api/pomodoro/stats` | `PomodoroController` |
| `GET` | `/api/pomodoro/status` | `PomodoroController` |
| `POST` | `/api/pomodoro/stop` | `PomodoroController` |
| `GET` | `/api/stats` | `TasksController` |
| `GET` | `/api/tasks` | `TasksController` |
| `POST` | `/api/tasks` | `TasksController` |
| `DELETE` | `/api/tasks/:id` | `TasksController` |
| `GET` | `/api/tasks/:id` | `TasksController` |
| `PUT` | `/api/tasks/:id` | `TasksController` |
| `POST` | `/api/tasks/:id/archive` | `TasksController` |
| `POST` | `/api/tasks/:id/complete-instance` | `TasksController` |
| `POST` | `/api/tasks/:id/materialize-occurrence` | `TasksController` |
| `GET` | `/api/tasks/:id/time` | `TimeTrackingController` |
| `POST` | `/api/tasks/:id/time/start` | `TimeTrackingController` |
| `POST` | `/api/tasks/:id/time/start-with-description` | `TimeTrackingController` |
| `POST` | `/api/tasks/:id/time/stop` | `TimeTrackingController` |
| `POST` | `/api/tasks/:id/toggle-status` | `TasksController` |
| `POST` | `/api/tasks/query` | `TasksController` |
| `GET` | `/api/time/active` | `TimeTrackingController` |
| `GET` | `/api/time/summary` | `TimeTrackingController` |
| `GET` | `/api/webhooks` | `WebhookController` |
| `POST` | `/api/webhooks` | `WebhookController` |
| `DELETE` | `/api/webhooks/:id` | `WebhookController` |
| `GET` | `/api/webhooks/deliveries` | `WebhookController` |
_Generated from 40 implemented routes._
---
# Settings source reference
Source: https://tasknotes.dev/obsidian/reference/settings-source/
TaskNotes currently exposes 6 settings tabs. This inventory is generated from the tab renderer and English translation source so additions cannot silently disappear from the documentation.
## General
Source: `src/settings/tabs/generalTab.ts`
| Setting | Purpose |
| --- | --- |
| Default tasks folder | Default location for new tasks. Supports folder template variables like {{currentNotePath}}, {{currentNoteTitle}}, and {{projectFilePath}}, plus Daily Notes-style date tokens like YYYY/MM/DD. |
| Folder for inline-created tasks | Folder where tasks created from inline commands or checkbox conversion will be created. Leave empty to use the default tasks folder. Use {{currentNotePath}} for the current note's folder, or {{currentNoteTitle}} for a subfolder named after the current note. |
| Move archived tasks to folder | Automatically move archived tasks to an archive folder |
| Archive folder | Folder to move tasks to when archived. Supports template variables like {{year}}, {{month}}, {{priority}}, etc. |
| Identify tasks by | Choose whether to identify tasks by tag or by a frontmatter property |
| Task tag | Tag that identifies notes as tasks (without #). Existing .base view filters keep their old tag when this changes; update default Base files or edit those filters. |
| Hide identification tags in task cards | When enabled, tags matching the task identification tag (including hierarchical matches like 'task/project') will be hidden from task card displays |
| Hidden tag scope | Choose whether hiding identification tags also hides nested tags. |
| Task property name | The frontmatter property name (e.g., "category") |
| Task property value | The value that identifies a note as a task (e.g., "task"). Leave empty to treat every note that has this property as a task, whatever its value. |
| Auto-create default files | Automatically create missing default base view files on startup. Disable to prevent deleted sample files from being recreated. |
| Create default files | Create the default .base files in TaskNotes/Views/ directory. Existing files will not be overwritten. |
| Update default files | Overwrite the configured default .base files with templates generated from your current TaskNotes settings. |
| Export v3 saved views to Bases | Convert all your saved views from TaskNotes v3 into a single .base file with multiple views. This helps migrate your v3 filter configurations to the new Bases system. |
| Excluded folders | Comma-separated list of folders to exclude from task indexing and project suggestions |
| UI language | Select the language used for TaskNotes interface text |
| Use Markdown links in frontmatter | Generate markdown links (`[text](path)`) instead of wikilinks ([[link]]) in frontmatter properties. ⚠️ Requires the 'obsidian-frontmatter-markdown-links' plugin to work correctly. |
| Show release notes after update | Automatically open release notes when TaskNotes is updated to a new version |
| Check for new releases on startup | Check GitHub once when TaskNotes starts and show a notice when a newer compatible release is available |
| View release notes | See what's new in the latest version of TaskNotes |
## Task properties
Source: `src/settings/tabs/taskPropertiesTab.ts`
| Setting | Purpose |
| --- | --- |
| No static controls detected | This tab is assembled dynamically. |
## Modal fields
Source: `src/settings/tabs/modalFieldsTab.ts`
| Setting | Purpose |
| --- | --- |
| Split layout on wide screens | When enabled, the details editor appears in a right column on screens 900px or wider. When disabled, the modal uses a stacked layout. |
| Tab moves focus in details editor | When enabled, Tab moves from the details editor to the next modal field and Shift+Tab moves to the previous field. When disabled, Tab and Shift+Tab use the markdown editor's indentation behavior. |
| Sync user fields | Click to sync custom user fields from task properties settings into this configuration. |
| Reset to defaults | Reset all field configurations to their default values. This will remove any custom configurations. |
## Appearance & UI
Source: `src/settings/tabs/appearanceTab.ts`
| Setting | Purpose |
| --- | --- |
| Default visible properties | Choose which properties appear on task cards by default. |
| Group complete and skip actions in a submenu | Nest the complete and skip actions under a submenu in the task context menu. Turn off to show them directly in the menu. |
| Time format | Display time in 12-hour or 24-hour format throughout the plugin |
| Default view | The calendar view shown when opening the calendar tab |
| Custom view day count | Number of days to show in custom multi-day view |
| First day of week | Which day should be the first column in week views |
| Show weekends | Display weekends in calendar views |
| Show week numbers | Display week numbers in calendar views |
| Show today highlight | Highlight the current day in calendar views |
| Show current time indicator | Display a line showing the current time in timeline views |
| Selection mirror | Show a visual preview while dragging to select time ranges |
| Calendar locale | Calendar locale for date formatting and calendar system (e.g., "en", "fa" for Farsi/Persian, "de" for German). Leave empty to auto-detect from browser. |
| Show scheduled tasks | Display tasks with scheduled dates by default |
| Show due dates | Display task due dates by default |
| Show due dates when scheduled | Display due dates even for tasks that already have scheduled dates |
| Show time entries | Display completed time tracking entries by default |
| Show recurring tasks | Display recurring task instances by default |
| Show ICS events | Display events from ICS subscriptions by default |
| Time slot duration | Duration of each time slot in timeline views |
| Time slot height | Height of each time slot in timeline views (pixels). Lower it to keep a long time range, or short slots such as 15 minutes, from needing a scrollbar. |
| Start time | Earliest time shown in timeline views (HH:MM format) |
| End time | Latest time shown in timeline views (HH:MM format). Use values above 24:00 to show early next-day hours, such as 26:00 for 2 AM. |
| Initial scroll time | Time to scroll to when opening timeline views (HH:MM format) |
| Event minimum height | Minimum height for events in timeline views (pixels) |
| Show tracked tasks in status bar | Display currently tracked tasks in Obsidian's status bar |
| Show relationships widget | Display a widget showing all relationships for the current note (subtasks, projects, dependencies) |
| Relationships position | Where to position the relationships widget |
| Show task card in note | Display a task card widget at the top of task notes showing the task details and actions |
| Strike through completed task titles | Draw a line through completed task card titles. Turn off to keep completed tasks easier to read |
| Show expandable subtasks | Allow expanding/collapsing subtask sections in task cards |
| Expand subtasks by default | Show project subtasks expanded when task cards are rendered |
| Subtask chevron position | Position of expand/collapse chevrons in task cards |
| Views button alignment | Alignment of the views/filters button in the task interface |
| Single-click action | Action performed when single-clicking a task card |
| Double-click action | Action performed when double-clicking a task card |
## Features
Source: `src/settings/tabs/featuresTab.ts`
| Setting | Purpose |
| --- | --- |
| Task link overlay | Show interactive overlays when hovering over task links |
| Disable overlay for aliased links | Do not show the task widget if the link contains an alias (e.g. [[Task\|Alias]]). |
| Inline task card properties | Select which properties to show in inline task cards. |
| Show convert button next to checkboxes | Display an inline button next to Markdown checkboxes that converts them to TaskNotes |
| Keep checkbox when converting | Leave the original Markdown checkbox marker in place when converting a checkbox to a TaskNote link |
| Enable natural language task input | Parse due dates, priorities, and contexts from natural language when creating tasks |
| Default to scheduled | When NLP detects a date without context, treat it as scheduled rather than due |
| Enter saves task | In the natural language input, press Enter to save the task. Shift+Enter inserts a newline, and Ctrl/Cmd+Enter still saves. |
| NLP language | Language for natural language processing patterns and date parsing |
| Open task after creation | Choose whether the task creation modal opens the new task note after saving. |
| Use body template | Use a template file for task body content |
| Body template file | Path to template file for task body content. Supports template variables like {{title}}, {{date}}, {{time}}, {{priority}}, {{status}}, etc. |
| Use occurrence note template | Use a separate fallback template for materialized occurrence notes when the recurring task has no occurrence_template |
| Occurrence note template file | Path to template file for materialized occurrence notes. A recurring task's occurrence_template field takes priority over this fallback. |
| Template variables: | See the setting in Obsidian for contextual details. |
| Use task defaults on instant convert | Apply default task settings when converting text to tasks instantly |
| Work duration | Duration of work intervals in minutes |
| Short break duration | Duration of short breaks in minutes |
| Long break duration | Duration of long breaks in minutes |
| Long break interval | Number of work sessions before a long break |
| Auto-start breaks | Automatically start break timers after work sessions |
| Auto-start work | Automatically start work sessions after breaks |
| Pomodoro notifications | Show notifications when Pomodoro sessions end |
| Show Pomodoro in status bar | Display the active Pomodoro countdown in Obsidian's status bar |
| Sound enabled | Play sound when Pomodoro sessions end |
| Sound volume | Volume for Pomodoro sounds (0-100) |
| Pomodoro data storage | Configure where Pomodoro session data is stored and how it's managed. |
| Mobile sidebar | Where to open the Pomodoro timer on mobile devices |
| Enable notifications | Enable task reminder notifications |
| Notification type | Type of notifications to show |
| Send test reminder | Send a test reminder using the current notification type and sound settings. |
| Notification sound | Play a sound when task reminders trigger |
| Sound volume | Volume for task reminder sounds (0-100) |
| Preview notification sound | Play the configured task reminder sound |
| Hide completed tasks from overdue | Exclude completed tasks from overdue task calculations |
| Disable note indexing | Disable automatic indexing of note content for better performance |
| Suggestion debounce | Delay in milliseconds before showing suggestions |
| Auto-stop time tracking | Automatically stop time tracking when a task is marked complete |
| Time tracking stop notification | Show notification when time tracking is automatically stopped |
| Maintain due date offset in recurring tasks | Keep the offset between due date and scheduled date when recurring tasks are completed |
| Reset checkboxes on recurrence | Reset all Markdown checkboxes in the task body when a recurring task is completed and rescheduled |
| Reset status after each occurrence | When an occurrence is completed or skipped, move the task to the Next status of the first completed status. Turn off to keep the task's status. |
| Enable timeblocking | Enable timeblocking feature for lightweight scheduling in daily notes. When enabled, 'Timeblock' option appears in the calendar drag context menu. |
| Attachment search order | Controls how files are ordered in the Add Attachment search window for timeblocks. |
| Show timeblocks | Display timeblocks from daily notes by default |
| Default timeblock color | The default color used when creating new timeblocks |
| Enable debug logging | Log detailed drag-and-drop and view diagnostics to the developer console. Useful for troubleshooting. |
## Integrations
Source: `src/settings/tabs/integrationsTab.ts`
| Setting | Purpose |
| --- | --- |
| Generate mdbase type definitions | See the setting in Obsidian for contextual details. |
| Disable calendar integrations on mobile | Skip Google, Microsoft, and ICS calendar loading on Obsidian mobile. Desktop calendar integrations are unchanged. |
| Calendar integrations are disabled on this mobile device | See the setting in Obsidian for contextual details. |
| Enable task export | When enabled, tasks with dates will be automatically synced to Google Calendar as events. |
| Target calendar | See the setting in Obsidian for contextual details. |
| Sync trigger | Which task date should trigger calendar event creation. |
| Create as all-day events | When enabled, tasks are created as all-day events. When disabled, uses time estimate for duration. |
| Show all-day task events as free | All-day task exports do not block availability, including tasks converted to all-day. Timed events stay busy. Run sync all tasks to apply changes to existing events. |
| Default event duration | Duration in minutes for timed events (used when task has no time estimate). |
| Event title template | Template for event titles. Available variables: {{title}}, {{status}}, {{priority}} |
| Include task details in description | Add task metadata (priority, status, tags, etc.) to the event description. |
| Include Obsidian link | Add a link back to the task in Obsidian in the event description. |
| Default reminder | Add popup reminders to timed Google Calendar events. Enter minutes before the event, separated by commas. Leave empty to use calendar defaults. Common values: 15, 30, 60, 1440. |
| Automatic sync behavior | See the setting in Obsidian for contextual details. |
| Sync on task create | Automatically create calendar event when a new task is created. |
| Sync on task update | Automatically update calendar event when a task is modified. |
| Sync on task complete | Update calendar event when a task is completed (adds checkmark to title). |
| Delete event on task delete | Remove calendar event when the corresponding task is deleted. |
| Manual sync actions | See the setting in Obsidian for contextual details. |
| Sync all tasks | Sync all existing tasks to Google Calendar. This will create events for tasks that haven't been synced yet. |
| Unlink all tasks | Remove all task-event links without deleting calendar events. |
| Sync timeblocks | Create, update and delete calendar events as you add, edit and remove timeblocks. Existing timeblocks are synced the next time you edit them. |
| Timeblock calendar | See the setting in Obsidian for contextual details. |
| Timeblock event title template | Template for timeblock event titles. Available variables: {{title}}, {{date}}, {{startTime}}, {{endTime}} |
| Default note template | Path to template file for notes created from ICS events |
| Default note folder | Folder for notes created from ICS events |
| ICS note filename format | How filenames are generated for notes created from ICS events |
| Custom ICS filename template | Template for custom ICS event filenames |
| Use ICS event end time as task due date | When enabled, tasks created from calendar events will have their due date set to the event's end time. For all-day events, the due date will be set to the event date. For timed events, the due date will include the end time. |
| Recurring event related notes | Choose whether notes linked to one recurrence of an external calendar event appear across the loaded series or only on the selected instance. |
| Add calendar subscription | Add a new calendar subscription from ICS/iCal URL or local file |
| Refresh all subscriptions | Manually refresh all enabled calendar subscriptions |
| Enable automatic export | Automatically keep an ICS file updated with all your tasks |
| Export file path | Path where the ICS file will be saved (relative to vault root) |
| Update interval (between 5 and 1440 minutes) | How often to update the export file |
| Use task duration for event length | When enabled, uses the task's time estimate (duration) instead of due date for the calendar event end time. This is useful for GTD workflows where scheduled + duration represents work planning, while due date represents deadlines. |
| Exclude completed tasks | When enabled, completed tasks are omitted from ICS exports. Completed statuses are taken from your task statuses settings. |
| Exclude archived tasks | When enabled, archived tasks are omitted from ICS exports. |
| Require due date | When enabled, only tasks with a due date are included in ICS exports. |
| Require scheduled date | When enabled, only tasks with a scheduled date are included in ICS exports. |
| Export now | Manually trigger an immediate export |
| Export status: | See the setting in Obsidian for contextual details. |
| Enable HTTP API | Start local HTTP server for API access |
| API port | Port number for the HTTP API server |
| API authentication token | TaskNotes token, not your AI provider's API key. To generate one, enable HTTP API, leave this field empty, and restart Obsidian. Then copy the generated token into your client's bearer authentication settings. Update clients whenever this token changes. |
| Enable MCP server | Expose TaskNotes tools via Model Context Protocol at /mcp endpoint. Requires HTTP API to be enabled. |
| Add webhook | Register a new webhook endpoint |
| Transform file | Path to a .json template file in your vault that transforms webhook payloads |
| Include custom headers | Include TaskNotes headers (event type, signature, delivery ID). Turn off for Discord, Slack, and other services with strict CORS policies. |
| Webhook URL | The endpoint where webhook payloads will be sent |
| Transform file | Path to a .json template file in your vault that transforms webhook payloads |
| Include custom headers | Include TaskNotes headers (event type, signature, delivery ID). Turn off for Discord, Slack, and other services with strict CORS policies. |
## Complete default settings snapshot
The following JSON is generated from `DEFAULT_SETTINGS`. Empty strings and disabled flags are intentional defaults.
```json
{
"tasksFolder": "TaskNotes/Tasks",
"moveArchivedTasks": false,
"archiveFolder": "TaskNotes/Archive",
"taskTag": "task",
"taskIdentificationMethod": "tag",
"hideIdentifyingTagsInCards": false,
"hideIdentifyingTagsMode": "all",
"taskPropertyName": "",
"taskPropertyValue": "",
"excludedFolders": "",
"defaultTaskPriority": "normal",
"defaultTaskStatus": "open",
"taskOrgFiltersCollapsed": false,
"taskFilenameFormat": "zettel",
"storeTitleInFilename": true,
"customFilenameTemplate": "{{title}}",
"occurrenceFilenameTemplate": "",
"occurrenceFilenameTemplateProperty": "occurrenceFilenameTemplate",
"taskCreationDefaults": {
"defaultContexts": "",
"defaultTags": "",
"defaultProjects": "",
"useParentNoteForTaskCreation": false,
"useParentNoteAsProject": false,
"useParentHeaderAsProject": false,
"inheritParentTaskProperties": false,
"defaultTimeEstimate": 0,
"defaultRecurrence": "none",
"defaultDueDate": "none",
"defaultDueTime": "none",
"defaultScheduledDate": "today",
"defaultScheduledTime": "none",
"bodyTemplate": "",
"useBodyTemplate": false,
"occurrenceBodyTemplate": "",
"useOccurrenceBodyTemplate": false,
"defaultReminders": []
},
"openTaskAfterCreation": "none",
"calendarViewSettings": {
"defaultView": "dayGridMonth",
"customDayCount": 3,
"slotDuration": "00:30:00",
"slotHeight": 24,
"slotMinTime": "00:00:00",
"slotMaxTime": "24:00:00",
"scrollTime": "08:00:00",
"firstDay": 1,
"timeFormat": "24",
"showWeekends": true,
"locale": "",
"defaultShowScheduled": true,
"defaultShowDue": true,
"defaultShowDueWhenScheduled": true,
"defaultShowScheduledToDueSpan": false,
"defaultShowTimeEntries": false,
"defaultShowRecurring": true,
"defaultShowICSEvents": true,
"enableTimeblocking": false,
"defaultShowTimeblocks": true,
"defaultTimeblockColor": "#6366f1",
"timeblockAttachmentSearchOrder": "name-asc",
"nowIndicator": true,
"selectMirror": true,
"weekNumbers": false,
"showTodayHighlight": true,
"eventMinHeight": 15,
"slotEventOverlap": true,
"eventMaxStack": null,
"dayMaxEvents": true,
"dayMaxEventRows": false
},
"pomodoroWorkDuration": 25,
"pomodoroShortBreakDuration": 5,
"pomodoroLongBreakDuration": 15,
"pomodoroLongBreakInterval": 4,
"pomodoroAutoStartBreaks": true,
"pomodoroAutoStartWork": false,
"pomodoroNotifications": true,
"pomodoroSoundEnabled": true,
"pomodoroSoundVolume": 50,
"pomodoroStorageLocation": "plugin",
"pomodoroMobileSidebar": "tab",
"showPomodoroInStatusBar": true,
"enableTaskLinkOverlay": true,
"disableOverlayOnAlias": false,
"enableInstantTaskConvert": true,
"useDefaultsOnInstantConvert": true,
"preserveCheckboxOnConvert": false,
"taskModalTabMovesFocus": true,
"enableNaturalLanguageInput": true,
"nlpDefaultToScheduled": true,
"nlpEnterToSubmit": false,
"nlpLanguage": "en",
"uiLanguage": "system",
"statusSuggestionTrigger": "*",
"nlpTriggers": {
"triggers": [
{
"propertyId": "tags",
"trigger": "#",
"enabled": true
},
{
"propertyId": "contexts",
"trigger": "@",
"enabled": true
},
{
"propertyId": "projects",
"trigger": "+",
"enabled": true
},
{
"propertyId": "status",
"trigger": "*",
"enabled": true
},
{
"propertyId": "priority",
"trigger": "!",
"enabled": false
}
]
},
"singleClickAction": "edit",
"doubleClickAction": "openNote",
"projectAutosuggest": {
"enableFuzzy": false,
"rows": [
"{title|n(Title)}",
"{aliases|n(Aliases)}",
"{file.path|n(Path)}"
],
"showAdvanced": false,
"requiredTags": [],
"includeFolders": [],
"propertyKey": "",
"propertyValue": ""
},
"inlineTaskConvertFolder": "{{currentNotePath}}",
"disableNoteIndexing": false,
"suggestionDebounceMs": 0,
"fieldMapping": {
"title": "title",
"status": "status",
"priority": "priority",
"due": "due",
"scheduled": "scheduled",
"contexts": "contexts",
"projects": "projects",
"attachments": "attachments",
"assignees": "assignees",
"timeEstimate": "timeEstimate",
"completedDate": "completedDate",
"dateCreated": "dateCreated",
"dateModified": "dateModified",
"recurrence": "recurrence",
"recurrenceAnchor": "recurrence_anchor",
"recurrenceOriginalDate": "recurrence_original_date",
"recurrenceParent": "recurrence_parent",
"occurrenceDate": "occurrence_date",
"occurrenceMaterialization": "occurrence_materialization",
"occurrenceNextTrigger": "occurrence_next_trigger",
"occurrenceTemplate": "occurrence_template",
"occurrencePastHorizon": "occurrence_past_horizon",
"occurrenceFutureHorizon": "occurrence_future_horizon",
"archiveTag": "archived",
"timeEntries": "timeEntries",
"completeInstances": "complete_instances",
"skippedInstances": "skipped_instances",
"blockedBy": "blockedBy",
"pomodoros": "pomodoros",
"icsEventId": "icsEventId",
"icsEventTag": "ics_event",
"googleCalendarEventId": "googleCalendarEventId",
"googleCalendarExceptionEventId": "googleCalendarExceptionEventId",
"googleCalendarExceptionOriginalScheduled": "googleCalendarExceptionOriginalScheduled",
"googleCalendarMovedOriginalDates": "googleCalendarMovedOriginalDates",
"reminders": "reminders",
"sortOrder": "tasknotes_manual_order"
},
"customStatuses": [
{
"id": "none",
"value": "none",
"label": "None",
"color": "#cccccc",
"isCompleted": false,
"excludeFromCycle": false,
"order": 0,
"autoArchive": false,
"autoArchiveDelay": 5
},
{
"id": "open",
"value": "open",
"label": "Open",
"color": "#808080",
"isCompleted": false,
"excludeFromCycle": false,
"order": 1,
"autoArchive": false,
"autoArchiveDelay": 5
},
{
"id": "in-progress",
"value": "in-progress",
"label": "In progress",
"color": "#0066cc",
"isCompleted": false,
"excludeFromCycle": false,
"order": 2,
"autoArchive": false,
"autoArchiveDelay": 5
},
{
"id": "done",
"value": "done",
"label": "Done",
"color": "#00aa00",
"isCompleted": true,
"excludeFromCycle": false,
"nextStatus": "open",
"order": 3,
"autoArchive": false,
"autoArchiveDelay": 5
}
],
"customPriorities": [
{
"id": "none",
"value": "none",
"label": "None",
"color": "#cccccc",
"weight": 0
},
{
"id": "low",
"value": "low",
"label": "Low",
"color": "#00aa00",
"weight": 1
},
{
"id": "normal",
"value": "normal",
"label": "Normal",
"color": "#ffaa00",
"weight": 2
},
{
"id": "high",
"value": "high",
"label": "High",
"color": "#ff0000",
"weight": 3
}
],
"recurrenceMigrated": false,
"showReleaseNotesOnUpdate": true,
"checkForUpdatesOnStartup": true,
"starterNoteCreated": false,
"showTrackedTasksInStatusBar": false,
"autoStopTimeTrackingOnComplete": true,
"autoStopTimeTrackingNotification": false,
"showRelationships": true,
"relationshipsPosition": "bottom",
"showTaskCardInNote": true,
"showCompletedTaskStrikethrough": true,
"completionMenuAsSubmenu": true,
"showExpandableSubtasks": true,
"expandSubtasksByDefault": false,
"subtaskChevronPosition": "right",
"viewsButtonAlignment": "right",
"hideCompletedFromOverdue": true,
"icsIntegration": {
"defaultNoteTemplate": "",
"defaultNoteFolder": "",
"icsNoteFilenameFormat": "title",
"customICSNoteFilenameTemplate": "{title}",
"enableAutoExport": false,
"autoExportPath": "tasknotes-calendar.ics",
"autoExportInterval": 60,
"useDurationForExport": false,
"excludeArchivedFromExport": false,
"excludeCompletedFromExport": false,
"requireDueDateForExport": false,
"requireScheduledDateForExport": false,
"useICSEndAsDue": false,
"recurringEventRelatedNotesMode": "series"
},
"savedViews": [],
"enableNotifications": true,
"notificationType": "system",
"notificationSoundEnabled": false,
"notificationSoundVolume": 50,
"enableAPI": false,
"apiPort": 8080,
"apiAuthToken": "",
"enableMCP": false,
"webhooks": [],
"userFields": [],
"enableModalSplitLayout": true,
"defaultVisibleProperties": [
"status",
"priority",
"due",
"scheduled",
"projects",
"contexts",
"tags",
"blocked",
"blocking"
],
"inlineVisibleProperties": [
"status",
"priority",
"due",
"scheduled",
"recurrence"
],
"enableBases": true,
"enableMdbaseSpec": false,
"autoCreateDefaultBasesFiles": true,
"commandFileMapping": {
"open-calendar-view": "TaskNotes/Views/mini-calendar-default.base",
"open-kanban-view": "TaskNotes/Views/kanban-default.base",
"open-tasks-view": "TaskNotes/Views/tasks-default.base",
"open-advanced-calendar-view": "TaskNotes/Views/calendar-default.base",
"open-agenda-view": "TaskNotes/Views/agenda-default.base",
"pomodoro-stats-base": "TaskNotes/Views/pomodoro-stats.base",
"relationships": "TaskNotes/Views/relationships.base"
},
"maintainDueDateOffsetInRecurring": false,
"resetCheckboxesOnRecurrence": false,
"resetRecurringStatusAfterOccurrence": true,
"useFrontmatterMarkdownLinks": false,
"enableGoogleCalendar": false,
"enableMicrosoftCalendar": false,
"disableCalendarOnMobile": false,
"enabledGoogleCalendars": [],
"googleCalendarSyncTokens": {},
"enabledMicrosoftCalendars": [],
"microsoftCalendarSyncTokens": {},
"googleCalendarExport": {
"enabled": false,
"targetCalendarId": "",
"syncOnTaskCreate": true,
"syncOnTaskUpdate": true,
"syncOnTaskComplete": true,
"syncOnTaskDelete": true,
"eventTitleTemplate": "{{title}}",
"includeDescription": true,
"eventColorId": null,
"syncTrigger": "scheduled",
"createAsAllDay": true,
"showAllDayAsFree": false,
"defaultEventDuration": 60,
"includeObsidianLink": true,
"defaultReminderMinutes": null,
"syncTimeblocks": false,
"timeblockTargetCalendarId": "",
"timeblockEventTitleTemplate": "{{title}}"
},
"enableDebugLogging": false
}
```
---
# Release Notes
Source: https://tasknotes.dev/obsidian/releases/
Welcome to the TaskNotes release notes. Here you can find detailed information about each version, including new features, bug fixes, and improvements.
## Latest Releases
### Version 4.x (Current)
- [4.18.3](releases/4.18.3.md)
- [4.18.2](releases/4.18.2.md)
- [4.18.1](releases/4.18.1.md)
- [4.18.0](releases/4.18.0.md)
- [4.17.0](releases/4.17.0.md)
- [4.16.1](releases/4.16.1.md)
- [4.16.0](releases/4.16.0.md)
- [4.15.0](releases/4.15.0.md)
- [4.14.0](releases/4.14.0.md)
- [4.13.10](releases/4.13.10.md)
- [4.13.9](releases/4.13.9.md)
- [4.13.8](releases/4.13.8.md)
- [4.13.7](releases/4.13.7.md)
- [4.13.6](releases/4.13.6.md)
- [4.13.5](releases/4.13.5.md)
- [4.13.4](releases/4.13.4.md)
- [4.13.3](releases/4.13.3.md)
- [4.13.2](releases/4.13.2.md)
- [4.13.1](releases/4.13.1.md)
- [4.13.0](releases/4.13.0.md)
- [4.12.5](releases/4.12.5.md)
- [4.12.4](releases/4.12.4.md)
- [4.12.3](releases/4.12.3.md)
- [4.12.2](releases/4.12.2.md)
- [4.12.1](releases/4.12.1.md)
- [4.12.0](releases/4.12.0.md)
- [4.11.1](releases/4.11.1.md)
- [4.11.0](releases/4.11.0.md)
- [4.10.2](releases/4.10.2.md)
- [4.10.1](releases/4.10.1.md)
- [4.10.0](releases/4.10.0.md)
- [4.9.2](releases/4.9.2.md)
- [4.9.1](releases/4.9.1.md)
- [4.9.0](releases/4.9.0.md)
- [4.8.1](releases/4.8.1.md)
- [4.8.0](releases/4.8.0.md)
- [4.7.2](releases/4.7.2.md)
- [4.7.1](releases/4.7.1.md)
- [4.7.0](releases/4.7.0.md)
- [4.6.0](releases/4.6.0.md)
- [4.5.3](releases/4.5.3.md)
- [4.5.2](releases/4.5.2.md)
- [4.5.1](releases/4.5.1.md)
- [4.5.0](releases/4.5.0.md)
- [4.4.0](releases/4.4.0.md)
- [4.3.3](releases/4.3.3.md)
- [4.3.2](releases/4.3.2.md)
- [4.3.1](releases/4.3.1.md)
- [4.3.0](releases/4.3.0.md)
- [4.2.1](releases/4.2.1.md)
- [4.2.0](releases/4.2.0.md)
- [4.1.3](releases/4.1.3.md)
- [4.1.2](releases/4.1.2.md)
- [4.1.1](releases/4.1.1.md)
- [4.1.0](releases/4.1.0.md)
- [4.0.5](releases/4.0.5.md)
- [4.0.4](releases/4.0.4.md)
- [4.0.3](releases/4.0.3.md)
- [4.0.2](releases/4.0.2.md)
- [4.0.1](releases/4.0.1.md)
- [4.0.0-beta.3](releases/4.0.0-beta.3.md)
- [4.0.0-beta.2](releases/4.0.0-beta.2.md)
- [4.0.0-beta.1](releases/4.0.0-beta.1.md)
- [4.0.0-beta.0](releases/4.0.0-beta.0.md)
### Version 3.x
- [3.25.6](releases/3.25.6.md)
- [3.25.4](releases/3.25.4.md)
- [3.25.3](releases/3.25.3.md)
- [3.25.2](releases/3.25.2.md)
- [3.25.1](releases/3.25.1.md)
- [3.25.0](releases/3.25.0.md)
- [3.24.6](releases/3.24.6.md)
- [3.24.5](releases/3.24.5.md)
- [3.24.4](releases/3.24.4.md)
- [3.24.3](releases/3.24.3.md)
- [3.24.2](releases/3.24.2.md)
- [3.24.1](releases/3.24.1.md)
- [3.24.0](releases/3.24.0.md)
- [3.23.4](releases/3.23.4.md)
- [3.23.3](releases/3.23.3.md)
- [3.23.2](releases/3.23.2.md)
- [3.23.1](releases/3.23.1.md)
- [3.23.0](releases/3.23.0.md)
- [3.22.1](releases/3.22.1.md)
- [3.22.0](releases/3.22.0.md)
- [3.21.0](releases/3.21.0.md)
- [3.20.1](releases/3.20.1.md)
- [3.20.0](releases/3.20.0.md)
- [3.19.1](releases/3.19.1.md)
- [3.19.0](releases/3.19.0.md)
- [3.18.2](releases/3.18.2.md)
- [3.18.1](releases/3.18.1.md)
- [3.18.0](releases/3.18.0.md)
- [3.17.1](releases/3.17.1.md)
- [3.17.0](releases/3.17.0.md)
- [3.16.4](releases/3.16.4.md)
- [3.16.3](releases/3.16.3.md)
- [3.16.2](releases/3.16.2.md)
- [3.16.1](releases/3.16.1.md)
- [3.16.0](releases/3.16.0.md)
- [3.15.1](releases/3.15.1.md)
- [3.15.0](releases/3.15.0.md)
- [3.14.0](releases/3.14.0.md)
- [3.13.4](releases/3.13.4.md)
- [3.13.3](releases/3.13.3.md)
- [3.13.2](releases/3.13.2.md)
- [3.13.1](releases/3.13.1.md)
- [3.13.0](releases/3.13.0.md)
- [3.12.2](releases/3.12.2.md)
- [3.12.1](releases/3.12.1.md)
- [3.12.0](releases/3.12.0.md)
- [3.11.2](releases/3.11.2.md)
- [3.11.1](releases/3.11.1.md)
- [3.11.0](releases/3.11.0.md)
- [3.10.0](releases/3.10.0.md)
- [3.9.1](releases/3.9.1.md)
- [3.9.0](releases/3.9.0.md)
- [3.8.7](releases/3.8.7.md)
- [3.8.6](releases/3.8.6.md)
- [3.8.5](releases/3.8.5.md)
- [3.8.1](releases/3.8.1.md)
- [3.7.1](releases/3.7.1.md)
- [3.7.0](releases/3.7.0.md)
- [3.6.0](releases/3.6.0.md)
- [3.5.1](releases/3.5.1.md)
- [3.4.2](releases/3.4.2.md)
- [3.4.1](releases/3.4.1.md)
- [3.4.0](releases/3.4.0.md)
- [3.3.0](releases/3.3.0.md)
- [3.1.1](releases/3.1.1.md)
- [3.1.0](releases/3.1.0.md)
- [3.0.1](releases/3.0.1.md)
- [3.0.0](releases/3.0.0.md)
### Version 2.x
- [2.2.3](releases/2.2.3.md)
- [2.2.2](releases/2.2.2.md)
- [2.2.1](releases/2.2.1.md)
- [2.2.0](releases/2.2.0.md)
- [2.1.0](releases/2.1.0.md)
- [2.0.4](releases/2.0.4.md)
- [2.0.3](releases/2.0.3.md)
- [2.0.2](releases/2.0.2.md)
- [2.0.1](releases/2.0.1.md)
- [2.0.0](releases/2.0.0.md)
### Version 1.x
- [1.2.0](releases/1.2.0.md)
- [1.1.0](releases/1.1.0.md)
- [1.0.0](releases/1.0.0.md)
### Early Versions (0.x)
- [0.8.0](releases/0.8.0.md)
- [0.7.0](releases/0.7.0.md)
- [0.6.3](releases/0.6.3.md)
- [0.6.2](releases/0.6.2.md)
- [0.6.1](releases/0.6.1.md)
- [0.6.0](releases/0.6.0.md)
- [0.4.2](releases/0.4.2.md)
- [0.4.1](releases/0.4.1.md)
- [0.4.0](releases/0.4.0.md)
- [0.3.0](releases/0.3.0.md)
- [0.2.4](releases/0.2.4.md)
- [0.2.3](releases/0.2.3.md)
- [0.2.2](releases/0.2.2.md)
## Getting Updates
To update TaskNotes:
1. Open Obsidian
2. Go to Settings → Community Plugins
3. Find TaskNotes and click "Update"
4. Restart Obsidian if prompted
## Feedback
Found a bug or have a feature request? Please:
- Check existing [GitHub Issues](https://github.com/callumalpass/tasknotes/issues)
- Create a new issue with details
---
# Settings
Source: https://tasknotes.dev/obsidian/settings/
This page describes **TaskNotes v4**. Settings are organized into tabs, each controlling a different part of plugin behavior.
For the **v5 beta**, settings use Obsidian's native navigation and search. See [Settings are reorganized](migration-v4-to-v5.md#settings-are-reorganized) for the v5 categories.
## General
The General tab controls task identification, storage locations, and task-card click behavior. Use this tab when your vault already has conventions such as custom tags, property-based identification, or specific folder structures.
For more information, see the [General Settings](settings/general.md) documentation.
## Task Properties
Task Properties defines the schema TaskNotes writes to frontmatter, including status, priority, dates, reminders, projects, and user fields. Each property card lets you remap key names and behavior so TaskNotes can match existing metadata rather than forcing a migration.
For more detailed information, see the [Task Properties Settings](settings/task-properties.md) documentation.
## Modal Fields
Modal Fields controls the task create/edit experience by deciding which fields are visible and in what order. If your workflow depends on a handful of fields, you can surface only those and reduce form noise.
For more information, see the [Modal Fields Settings](settings/modal-fields.md) documentation.
## Appearance & UI
Appearance & UI handles task card density, calendar defaults, time formatting, and visual toggles for supporting widgets. Use this tab to tune how much information is visible at a glance.
For more detailed information, see the [Appearance & UI Settings](settings/appearance.md) documentation.
## Features
Features groups behavior toggles for inline tasks, natural language input, Pomodoro, reminders, and performance-related options. It is where you enable advanced workflow capabilities and then refine defaults.
For more information, see the [Features Settings](settings/features.md) documentation.
## Integrations
Integrations covers external connectivity: Bases view wiring, Google/Microsoft OAuth calendar sync, ICS subscriptions, automatic ICS export, HTTP API settings, and webhook endpoints.
For more detailed information, see the [Integrations Settings](settings/integrations.md) documentation.
---
# Troubleshooting
Source: https://tasknotes.dev/obsidian/troubleshooting/
Common issues and solutions for TaskNotes.
When debugging, start with one affected task and one affected view. Record the TaskNotes version from the plugin list, the Obsidian version from **About**, the operating system, and whether the problem also occurs in a fresh default Base.
## First checks
1. Confirm Obsidian meets the current [version requirement](reference/compatibility.md) and **Bases** is enabled.
2. Open the affected task as Markdown and validate the `---` frontmatter delimiters and indentation.
3. Confirm the task matches **Settings → TaskNotes → General → Task identification** and is not in an excluded folder.
4. Run **TaskNotes: Refresh cache** from the command palette.
5. Close and reopen the affected `.base` file.
6. Restart Obsidian only after the targeted checks above.
If the issue remains, enable **Settings → TaskNotes → Features → Debug logging**, reproduce it once, and inspect the developer console with `Ctrl/Cmd + Shift + I`. Disable debug logging after collecting the relevant entries.
## Bases and Views (v4)
### Views Not Loading
**Symptoms**: TaskNotes views show errors or don't display tasks
First confirm Bases is enabled (`Settings -> Core Plugins -> Bases`), then restart Obsidian once. If views are still missing, verify `.base` files exist in `TaskNotes/Views/`. If needed, regenerate defaults from `Settings -> TaskNotes -> General -> Views & base files` (`Create files`).
### Commands Open Wrong Files
**Symptoms**: Ribbon icons or commands open unexpected files
Check command mappings in `Settings -> TaskNotes -> General` (`View Commands`). Reset mappings that were changed unintentionally, then verify each referenced `.base` file exists at the configured path.
## Common Issues
### Tasks Not Appearing in Views
**Symptoms**: Tasks you've created don't show up in TaskNotes views
Follow this decision tree:
1. **Does Quick actions for current task work on the note?**
- **No:** compare its tag or identification property with **General → Task identification**.
- **Yes:** task recognition works; continue to the Base filter.
2. **Is the note inside an excluded folder?**
- **Yes:** move it or update **Excluded folders**.
- **No:** continue.
3. **Does a newly generated default task Base show it?**
- **Yes:** the custom Base has a stale property name or filter.
- **No:** run **TaskNotes: Refresh cache** and validate the frontmatter.
4. **Did identification or field mapping change recently?**
- **Yes:** update the default Base files or edit their filters and columns. Generated files do not update automatically when settings change.
### Task Link Widgets Not Working
**Symptoms**: Links to task files appear as normal wikilinks instead of interactive widgets
Check that **Task link overlay** is enabled, then verify linked files are actually recognized as tasks (matching tag/property configuration). Links to normal notes will render as normal links by design.
### Instant Conversion Buttons Missing
**Symptoms**: Convert buttons don't appear next to checkbox tasks
Instant convert buttons only appear when the feature is enabled, in edit mode, and with cursor proximity to list items. Enable the feature, switch from reading mode to edit mode, and place the cursor near the target checkbox.
### Calendar View Performance Issues
**Symptoms**: Calendar views are slow or unresponsive
Reduce visible event layers first (scheduled/due/recurring/time entries), then increase ICS refresh intervals and shorten displayed date ranges. If slowness persists, apply the general performance guidance below.
### Natural Language Parsing Not Working
**Symptoms**: Natural language input doesn't extract expected task properties
Enable NLP in `Settings -> TaskNotes -> Features`, then verify your trigger characters (`@`, `#`, `!` by default) and any custom status/priority mappings. If parsing still seems inconsistent, compare input against the syntax in [NLP API](nlp-api.md).
### Time Tracking Issues
**Symptoms**: Time tracking doesn't start/stop properly or data is lost
Most tracking issues come from overlapping sessions, interrupted shutdowns, or save failures. Stop active sessions before starting new ones, confirm files are writable, and restart interrupted sessions. If needed, repair malformed time entries directly in frontmatter.
## Data Issues
### Corrupted Task Files
**Symptoms**: Tasks appear broken or cause errors in views
Open the task file directly and validate frontmatter syntax. Quote values that include special characters, validate YAML if necessary, and restore from backup for severe corruption.
### Missing Task Properties
**Symptoms**: Tasks missing expected properties or using default values unexpectedly
Check field mappings first, then confirm Task Defaults. If properties are absent on older notes, add them manually or re-save through TaskNotes so current mapping rules are applied.
### Date Format Issues
**Symptoms**: Dates not displaying correctly or causing parse errors
Use supported formats (`YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SS`), quote where needed, and re-enter problematic dates via TaskNotes date pickers to normalize formatting and timezone handling.
## Performance Troubleshooting
### Slow View Loading
To improve loading times, reduce external calendar subscriptions, increase ICS refresh intervals, exclude large folders, and disable event types you do not use.
## External Calendar Issues
### OAuth Calendar Not Connecting
**Symptoms**: Google Calendar or Microsoft Outlook won't connect
Verify credentials and loopback redirect configuration (`127.0.0.1` with dynamic local port), ensure app publication/test-user access is correct, and retry after disconnecting. Also check popup blockers. For provider-specific setup details, use [Calendar Setup](calendar-setup.md).
### OAuth Calendar Not Syncing
**Symptoms**: Connected calendar shows old events or doesn't update
Run manual refresh, check last-sync timestamps, reconnect if needed, and verify events exist in the source provider before debugging TaskNotes behavior.
### ICS Subscriptions Not Loading
**Symptoms**: ICS calendar events don't appear in calendar views
Confirm the ICS URL/file is reachable, run manual refresh, validate the feed format, and inspect subscription status errors for provider-side failures.
### Calendar Sync Problems
**Symptoms**: External calendar changes not reflected in TaskNotes
Check refresh intervals and force a manual refresh first. If source data is current but TaskNotes remains stale, remove and re-add the subscription to clear cached state.
## Getting Help
### Reporting Issues
Report bugs on [GitHub Issues](https://github.com/callumalpass/tasknotes/issues). Include:
- Exact TaskNotes and Obsidian versions
- Operating system
- The smallest affected task frontmatter with private values removed
- The `.base` path and whether a regenerated default has the same problem
- Steps to reproduce from a fresh Obsidian start
- Relevant console errors and TaskNotes debug entries
- Screenshots if relevant
### Configuration Reset
Use a reversible reset only after the checks above:
1. Close Obsidian
2. Navigate to `.obsidian/plugins/tasknotes/`
3. Copy `data.json` to a backup outside the plugin directory
4. Rename the original to `data.json.backup-YYYY-MM-DD`
5. Restart Obsidian
!!! warning
A reset affects settings, status and priority configurations, integration state, saved views, and plugin-stored Pomodoro history. Keep the backup until the problem is resolved. Restore it only while Obsidian is closed.
For full restore and uninstall guidance, see [Backup, restore, and removal](guides/backup-recovery.md).
---
# Views
Source: https://tasknotes.dev/obsidian/views/
TaskNotes provides multiple views for managing tasks and tracking productivity. All task-focused views operate as `.base` files located in the `TaskNotes/Views/` directory and require Obsidian's Bases core plugin to be enabled.
For details on Bases integration and how to enable it, see [Core Concepts](core-concepts.md#bases-integration). For view templates and configuration examples, see [Default Base Templates](views/default-base-templates.md).
## Task-Focused Views
Task-focused views are different entry points into the same underlying task notes. The [Task List View](views/task-list.md) is a common starting view for day-to-day planning because it exposes filters, sorting, and grouping in list format.
When you want workflow by status, [Kanban View](views/kanban-view.md) organizes cards into columns and can optionally add swimlanes for an extra organizational layer. [Calendar Views](views/calendar-views.md) are useful when schedule and timing matter more than backlog shape, with month/week/day/year/list modes plus drag-and-drop scheduling and time-block support.
[Agenda View](views/agenda-view.md) is a preconfigured list-oriented calendar layout designed for short-horizon planning, while [MiniCalendar View](views/calendar-views.md#mini-calendar-view) gives a compact month heatmap and fast keyboard navigation.
## Productivity-Focused Views
These views support time management and work tracking.
[Pomodoro View](views/pomodoro-view.md) supports focused intervals directly inside Obsidian, and [Pomodoro Stats View](views/pomodoro-view.md#pomodoro-stats-view) summarizes completed sessions so you can see pace and consistency over time.
Screenshots in this section are captured via the Playwright docs suite (`npm run e2e:docs`).
---
# TaskNotes privacy overview
Source: https://tasknotes.dev/privacy/
# TaskNotes privacy overview
Last updated: November 15, 2026
TaskNotes products are built around portable Markdown records. The storage and
network boundaries depend on the client and collection you choose.
TaskNotes is run by Callum Alpass, in Melbourne, Australia.
## TaskNotes app
- The TaskNotes app opens every collection through mdbase and requires a
connection to read or change it.
- A hosted collection stores the authoritative Markdown with the hosted
provider.
- A computer collection keeps the authoritative Markdown on that computer.
TaskNotes reaches it through an end-to-end encrypted relay that cannot read
record contents; the computer must remain reachable and run mdbase Connect.
- TaskNotes keeps only a temporary in-memory session cache. It does not retain
a separate offline collection after the app or page closes.
- Reminder notifications for mdbase collections require explicit permission
and use content-free event payloads. Task content is refreshed through the
authorized collection connection.
## Obsidian plugin
The plugin keeps task and note content in the local Obsidian vault. Plugin
settings live in Obsidian's plugin configuration. Network access occurs only
for enabled features that require it, including release checks, calendar
providers, ICS subscriptions, webhooks, and remotely loaded API documentation
assets.
## TaskNotes Calendar (hosted service)
TaskNotes Calendar is an optional service that shows your Google Calendar
events in the TaskNotes web and mobile apps and lets you create, edit and
delete them there. It is only used if you sign in to it.
**What we receive from Google.** When you sign in, we receive your Google
account identifier, email address and name. When you connect calendars, we
receive access to the list of calendars you subscribe to and to the events on
them.
**What we store.**
- Your Google account identifier, email address and name, until you delete
your account.
- Google access credentials, encrypted, until you disconnect, reconnect or
delete your account.
- The details of your calendars, such as their names, until you disconnect or
delete your account.
- Digests of your device sessions, which expire after 30 days without use.
**What we do not store.** Your calendar events pass through the service when
you view or change them. They are not saved on our servers.
**How we protect your data.**
- All traffic between the TaskNotes apps, the service and Google is encrypted
in transit with HTTPS (TLS).
- Your Google access and refresh tokens are encrypted with AES-256-GCM before
they are stored. Each connection has its own encryption key, which is itself
encrypted with a master key held in Cloudflare's secret storage, separate
from the database. Each encrypted credential is bound to your account and
connection, so it cannot be used for anyone else.
- Google credentials never leave the service. They are not sent to the
TaskNotes apps, written to logs or placed in URLs.
- We store only keyed digests (HMAC-SHA-256) of device session credentials,
never the credentials themselves. The web app's session cookie is `Secure`,
`HttpOnly` and `SameSite=Strict`.
- Every request is checked against your signed-in account, and the service
only accesses the calendars of that account.
- Access to the production service, its database and its keys is limited to
the operator. No person reads your calendar data, except with your
permission, to investigate abuse or a security problem, or where the law
requires it.
**Logs.** Our logs record the route, method, status, duration and any error
code of each request, along with a short code for the cause of a failure and a
count of calendars or events that could not be shown. They do not include your
identity, IP address, calendar data or event content. Logs are kept for up to 7
days.
**Who processes this data.** The service runs on Cloudflare, which hosts it
and its database. Calendar data is exchanged with Google. We do not sell your
data, use it for advertising, or share it with anyone else, except where the
law requires it.
**Your choices.** You can disconnect your calendars or delete your account in
the app's settings at any time. Either one deletes our stored Google
credential and asks Google to revoke our access. Deleting your account removes
the data listed above, apart from a keyed digest of your identity, kept for
about an hour so that sign-ins already in progress cannot recreate the
account. Deleted data can remain in database backups for up to 30 days. You
can also remove access from your Google Account's linked apps page. Deleting
your account does not change your Google events or your tasks.
**Google API Services.** TaskNotes' use and transfer to any other app of
information received from Google APIs will adhere to the [Google API Services User Data Policy](https://developers.google.com/terms/api-services-user-data-policy),
including the Limited Use requirements.
See the [TaskNotes Calendar terms](/terms/).
## Browser extension
The TaskNotes browser extension creates tasks from web pages. It sends a task
only to the destination you choose in its settings.
- **What it reads.** The extension reads a page only when you open its popup,
use its right-click menu or type `task` in the address bar. It then reads the
tab's title, address and any selected text. It does not run on pages in the
background, and it does not read your browsing history.
- **Obsidian.** Tasks go to the TaskNotes plugin's HTTP API on your own
computer (`localhost`). Nothing leaves the computer.
- **mdbase.** Tasks go to the mdbase collection you sign in to and choose,
through mdbase Connect. The task's title, details and source page address,
and any text you selected, are stored there as a Markdown record. The
extension asks only to read the collection and to create records.
- **What it stores.** Settings (the destination, the Obsidian port and API
token, default tags and link options) are kept in the browser's extension
storage, which the browser syncs between your devices if browser sync is on.
The chosen mdbase collection and the mdbase sign-in stay in the extension's
own storage on this device. Unsaved drafts are kept in session storage and are cleared
when the browser closes.
- **No other services.** The extension has no analytics, advertising or
tracking, and sends nothing to TaskNotes or anyone else.
Removing the extension deletes its stored settings and sign-in. Tasks already
created stay in your vault or collection.
## Analytics
TaskNotes does not include a product telemetry or analytics pipeline. TaskNotes
Calendar keeps the operational logs described above. Services
you choose to connect may keep their own operational, account, security, or
billing records under their respective policies.
## Removal
Removing a client does not necessarily remove its authoritative collection.
Use the hosted provider's controls for a hosted collection, or manage the
Markdown folder on the computer that owns a computer collection. Back up
records before removing an authoritative copy.
## Questions and source code
Use the relevant TaskNotes GitHub repository to report a privacy problem or
inspect the implementation:
- [TaskNotes app](https://github.com/callumalpass/tasknotes-app)
- [TaskNotes Obsidian plugin](https://github.com/callumalpass/tasknotes)
- [TaskNotes browser extension](https://github.com/callumalpass/tasknotes-browser-extension)
---
# TaskNotes Calendar terms
Source: https://tasknotes.dev/terms/
# TaskNotes Calendar terms
Last updated: November 7, 2026
These terms cover the optional hosted TaskNotes Calendar service, run by Callum
Alpass in Melbourne, Australia. By signing in, you agree to them.
**The service.** It connects TaskNotes to your Google Calendar. It may change,
be interrupted or be withdrawn. We will try to give notice before withdrawing
it.
**Your account.** You need a Google account, and you are responsible for the
changes you make to your calendars through TaskNotes.
**Acceptable use.** Do not attack, overload, reverse-engineer for abuse, or use
the service to break the law or Google's terms.
**No warranty.** The service is provided as is. To the extent the law allows, we
are not liable for lost or incorrect calendar data or for indirect losses.
**Ending use.** You can delete your account at any time in the app. We may
suspend accounts that break these terms.
**Changes and law.** We will publish changes on this page with a new date. These
terms are governed by the law of Victoria, Australia.
**Contact.** [Open an issue](https://github.com/callumalpass/tasknotes/issues).
See also the [privacy overview](/privacy/).
