# TaskNotes plugin for Obsidian Task and note management plugin for [[Obsidian]] built on the principle of "one note per task". It stores task information in YAML frontmatter, enabling compatibility with other plugins and external tools while maintaining full portability. ![](https://youtu.be/2dEQ1ES8_6A) ## Core Design Principles - **Native Integration**: Uses Obsidian's native metadata cache as its primary data source, ensuring compatibility with other plugins and leveraging Obsidian's performance optimizations. - **Extensible Data Model**: Task data stored in YAML frontmatter allows custom fields and property name customization through field mapping to match your existing vault structure. - **Multiple Views**: Provides eight different view types including task lists, calendar views, Kanban boards, and agenda views. - **Workflow Agnostic**: Doesn't enforce specific task management methodology—supports GTD, timeboxing, project-based organization, and more. ## Features TaskNotes includes the following capabilities: - **Task Properties**: Each task can include a title, status, priority, due date, scheduled date, contexts, tags, time estimate, and recurrence pattern. You can also add custom fields. - **Time Tracking**: A time tracking feature allows you to record the amount of time that you spend on tasks. This data is stored in the task's frontmatter as time entries with start and stop times. - **View Types**: Eight different views are provided: Task List, Notes, Agenda, Kanban, Mini Calendar, Advanced Calendar, Pomodoro, and Pomodoro Stats. - **Editor Integration**: Inline task widgets display task information within your notes. An instant conversion feature transforms checkbox tasks into TaskNotes. A natural language parser can interpret phrases to create structured tasks. - **Calendar Integration**: The plugin can subscribe to external ICS calendars from Google Calendar, Outlook, and other calendar systems. Time-blocking features are also included. - **External Tool Compatibility**: The YAML frontmatter format is compatible with other Obsidian plugins and can be processed by external tools. ## Task Creation Methods ### Method 1: Instant Conversion (Quickest) Convert any line in your notes to a TaskNote: - Write `[ ] Task description` in a bullet point - Click the small dot icon that appears to the right of the checkbox - Task note is created and auto-filed to your tasks folder - Original line becomes a link to the task note This is what the dot icon looks like: ![[Obsidian Starter Kit - Tutorial - Task Management - TaskNote conversion.png]] ### Method 2: Task Creation Modal Access via "Create new task" command or clicking dates/time slots in calendar views. Provides interface for setting all task properties including: - Title, status, priority - Due dates and scheduled dates - Contexts, tags, projects - Time estimates and recurrence ### Method 3: Natural Language Creation Type task descriptions in plain English and the parser extracts structured data: - `"Buy groceries tomorrow at 3pm @home #errands high priority"` - Auto-suggestions activate with trigger characters: - `@` - Shows available contexts - `#` - Shows available tags - `+` - Shows vault files as project suggestions - `*` - Shows status options (configurable trigger) ## Task Properties Tasks are Markdown files with YAML frontmatter containing: **Core Properties**: - **Title**: Main task description - **Status**: Current state (e.g., "Open," "In Progress," "Done") - **Priority**: Importance level (e.g., "Low," "Normal," "High") - **Due Date**: Completion deadline - **Scheduled Date**: When you plan to work on it **Organization**: - **Contexts**: Location/tool-based groupings (@home, @work) - **Projects**: Links to project notes (wikilinks to vault notes) - **Tags**: Standard Obsidian tags for categorization - **Dependencies**: References to blocking/blocked tasks with relationship types **Time Management**: - **Time Estimate**: Estimated completion time in minutes - **Time Entries**: Recorded work sessions with start/stop times - **Reminders**: Custom notification triggers **Recurrence**: - **Recurrence Rule**: RRule pattern with DTSTART for repeating tasks - **Complete Instances**: Array of completed occurrence dates **Custom Fields**: Add any additional properties via YAML frontmatter ## Projects Tasks organize into projects using note-based linking: - **Project Assignment**: Tasks link to one or more project notes via wikilinks stored in frontmatter: `projects: ["[[Project A]]", "[[Project B]]"]` - **Project Selection**: Click "Add Project" button in task creation/editing to search and select project notes using fuzzy search - **Organization**: Filter and group tasks by projects in all views. Tasks with multiple projects appear in each relevant project group. - **Subtask Creation**: Create subtasks directly from task context menu—automatically links to parent project - **Project Indicators**: Visual indicators on TaskCards show when tasks have other tasks linked as subtasks ## Dependencies Capture prerequisite work using RFC 9253 terminology: ```yaml blockedBy: - uid: "[[Operations/Order hardware]]" reltype: FINISHTOSTART gap: P1D ``` **Relationship Types**: FINISHTOSTART (default), FINISHTOFINISH, STARTTOSTART, STARTTOFINISH **Gap Duration**: Optional ISO 8601 duration syntax (e.g., `PT4H` for 4 hours, `P2D` for 2 days) **Synchronization**: Adding dependency automatically updates upstream note's `blocking` list. Removing dependency clears both sides. **UI Controls**: - Fuzzy task selector in creation/edit modals - Context menu access from Task List, Kanban, calendar views - Fork icon on cards shows blocked tasks with inline expandable list ## Recurring Tasks Sophisticated recurring task management using RFC 5545 RRule standard with DTSTART support: **Two-Level System**: 1. **Recurring Pattern**: Defines when pattern instances appear (DTSTART in recurrence rule) 2. **Next Occurrence**: Specific date/time for next planned work (scheduled field) **DTSTART Integration**: - Date-only: `DTSTART:20250804;FREQ=DAILY` (all-day instances) - Date and time: `DTSTART:20250804T090000Z;FREQ=DAILY` (timed instances) **Visual Hierarchy in Calendar**: - **Next Scheduled Occurrence**: Solid border, full opacity (from `scheduled` field) - **Pattern Instances**: Dashed border, 70% opacity (from DTSTART + recurrence rule) **Drag and Drop Behavior**: - **Dragging solid border (next occurrence)**: Updates only `scheduled` field—reschedules that specific instance - **Dragging dashed border (pattern instance)**: Updates DTSTART time in recurrence rule—changes all future pattern instances **Completion Tracking**: - Complete individual occurrences via task cards, calendar context menu, or edit modal calendar - Completed instances stored in `complete_instances` array - `scheduled` field automatically advances to next uncompleted occurrence **Examples**: ``` 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 DTSTART:20250815;FREQ=MONTHLY;BYMONTHDAY=15 → 15th of each month (all-day) DTSTART:20250801T100000Z;FREQ=MONTHLY;BYDAY=-1FR → Last Friday of each month at 10:00 AM ``` ## Reminders Notification system using iCalendar VALARM specification: **Relative Reminders** (based on due/scheduled date): - 15 minutes before due date - 1 hour before scheduled date - 2 days before due date - 30 minutes after scheduled date **Absolute Reminders** (specific date/time): - October 26, 2025 at 9:00 AM - Tomorrow at 2:30 PM - Next Monday at 10:00 AM **Data Format**: ```yaml reminders: - id: "rem_1678886400000_abc123xyz" type: "relative" relatedTo: "due" offset: "-PT15M" description: "Review task details" - id: "rem_1678886400001_def456uvw" type: "absolute" absoluteTime: "2025-10-26T09:00:00" description: "Follow up with client" ``` **Quick Access**: Bell icon on task cards, context menu for common patterns, Reminder Modal for advanced management **Default Reminders**: Configure default reminders in settings that automatically apply to new tasks ## Automation **Auto-Archiving**: Automatically archive tasks when transitioning to specific statuses - Configure per status in Settings → Task Properties → Task Statuses - Set delay (1-1440 minutes) before archiving - Queue persists across plugin restarts - Moving task to different status cancels pending archive ## Time Tracking Record work sessions directly on tasks: - Time entries stored in frontmatter with start/stop times - Track actual time spent vs estimated time - View time data in Pomodoro and Pomodoro Stats views ## View Types Eight specialized views for different workflows: 1. **Task List**: Filterable, groupable list of tasks 2. **Notes**: Document-centric view 3. **Agenda**: Time-based task organization 4. **Kanban**: Visual board with drag-and-drop 5. **Mini Calendar**: Compact calendar view 6. **Advanced Calendar**: Full calendar with drag-and-drop scheduling 7. **Pomodoro**: Focus timer integration 8. **Pomodoro Stats**: Time tracking analytics ## Templates Customize task creation with templates: **YAML Templates**: Pre-fill common frontmatter values **Body Templates**: Add boilerplate text and structure **Variables**: `{{title}}`, `{{date}}`, `{{contexts}}`, `{{projects}}`, `{{parentNote}}` **Project Linking**: Use `{{parentNote}}` in YAML list format for automatic project linking ## File Management **Default Tasks Folder**: Specify where new tasks are created **Filename Generation**: Choose from title-based, timestamp-based, or Zettelkasten-style patterns **Field Mapping**: Map properties to custom frontmatter names for vault compatibility ## Integration **Calendar Integration**: Subscribe to external ICS calendars (Google Calendar, Outlook, etc.) **Plugin Compatibility**: YAML frontmatter format works with other Obsidian plugins **External Tools**: Task data processable by external scripts and tools **Native Features**: Leverages Obsidian's linking, backlinks, tags, and search ## HTTP API Local REST API for automation and external integrations. Desktop only, disabled by default. Enable in Settings > TaskNotes > Integrations > HTTP API. - **Base URL**: `http://localhost:8080` (port configurable) - **Auth**: optional Bearer token via `apiAuthToken` setting - **OpenAPI docs**: available at `/api/docs` (JSON) and `/api/docs/ui` (Swagger UI) ### Endpoint groups | Group | Endpoints | Purpose | |-------|-----------|---------| | Tasks | CRUD, query, toggle-status, archive, complete-instance | Full task management | | Time Tracking | start, stop, active sessions, summary | Per-task time recording | | [[Pomodoro technique\|Pomodoro]] | start, stop, pause, resume, status, sessions, stats | Focus timer sessions | | Calendars | providers, events, subscriptions | Google, Outlook, ICS | | Webhooks | register, list, delete, deliveries | Event-driven integrations | | NLP | parse, create | Natural language task parsing | **Filtering**: `GET /api/tasks` is pagination-only. Use `POST /api/tasks/query` with a `FilterQuery` object (groups, conditions, conjunctions) for advanced filtering, sorting, and grouping. ## NLP API Two endpoints for natural language task creation: - `POST /api/nlp/parse` — parse text, return extracted fields without creating a task - `POST /api/nlp/create` — parse text and create task in one call Extracts: dates/times, priority, status, tags (`#`), contexts (`@`), projects (`+`), time estimates, and recurrence patterns. Parser respects custom status/priority values from your configuration. ## Webhooks Push HTTP POST requests to external URLs when events occur. Supports task, time tracking, pomodoro, recurring, and reminder events. - **Delivery**: async, fire-and-forget with exponential backoff retries (up to 4 attempts) - **Security**: HMAC-SHA256 signature verification via `X-TaskNotes-Signature` header - **Transforms**: attach a `.js` or `.json` transform file (vault path) to reshape payloads per event type (e.g., Slack formatting) - **Auto-disable**: webhooks auto-disable after 10 cumulative failures ### Event types `task.created`, `task.updated`, `task.deleted`, `task.completed`, `task.archived`, `task.unarchived`, `time.started`, `time.stopped`, `pomodoro.started`, `pomodoro.completed`, `pomodoro.interrupted`, `recurring.instance.completed`, `recurring.instance.skipped`, `reminder.triggered` ## CLI tools Two CLI tools for terminal-based task management: ### tasknotes-cli (`tn`) Communicates with the Obsidian plugin over the HTTP API. Requires Obsidian to be running with the API enabled. ``` npm install -g tasknotes-cli ``` ### mdbase-tasknotes (`mtn`) Operates directly on markdown files via mdbase. Works without Obsidian (headless servers, CI pipelines, SSH sessions). Uses tasknotes-nlp-core for NLP parsing. ``` npm install -g mdbase-tasknotes ``` | | `tn` (tasknotes-cli) | `mtn` (mdbase-tasknotes) | |---|---|---| | Requires Obsidian | Yes | No | | Operates on | HTTP API | Markdown files directly | | Use when | Obsidian is open, want live sync | Obsidian is closed, scripting, CI | Both tools read/write the same task files and can be used interchangeably on the same vault. Supports: create (NLP), list/filter, show, complete, update, delete, archive, search, time tracking, projects, stats, and interactive REPL mode (`mtn i`). ## Requirements Requires Obsidian 1.10.1+ and the Bases core plugin. ## References - Website: https://tasknotes.dev - Documentation: https://tasknotes.dev/get-started/introduction - HTTP API docs: https://tasknotes.dev/HTTP_API/ - Webhooks docs: https://tasknotes.dev/webhooks/ - NLP API docs: https://tasknotes.dev/nlp-api - CLI (mdbase-tasknotes): https://tasknotes.dev/mdbase-tasknotes-cli/ - GitHub Repository: https://github.com/callumalpass/tasknotes - OSK Tutorial: [[Obsidian Starter Kit - Tutorial - Managing Tasks]] - My introduction video: https://youtu.be/2dEQ1ES8_6A - My introduction article: https://www.dsebastien.net/tasknotes-obsidian-plugin-task-management ## Related - [[Obsidian Starter Kit]] - [[Obsidian]] - [[Obsidian Community Plugins]] - [[Obsidian Starter Kit - System - Action System]] - [[Getting Things Done (GTD)]] - [[callumalpass]] - [[Tasks plugin for Obsidian]] - [[Kanban plugin for Obsidian]] - [[TaskNotes TUI]]