# TaskNotes for Obsidian: Task Management Where Every Task Is a Markdown Note

> TaskNotes is an Obsidian plugin that stores each task as a separate Markdown note with YAML frontmatter, uses Obsidian Bases to power all views, and adds time tracking with Pomodoro support, calendar sync with Google and Microsoft, and natural language task creation.

**callumalpass/tasknotes** — Task and time-tracking management with calendar integration for Obsidian

- Repository: https://github.com/callumalpass/tasknotes
- Website: https://tasknotes.dev
- Stars: 2,166 · Forks: 226
- Language: TypeScript
- License: MIT
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/callumalpass-tasknotes

## What TaskNotes Is and Who Needs It

Most Obsidian task plugins store task state in Markdown checkboxes or in a plugin-specific database. TaskNotes takes a different approach: each task is a full Markdown note with YAML frontmatter for structured properties. The README describes this design choice as keeping data portable: tasks are plain Markdown files that any tool can read, transform with scripts, or migrate without a conversion step. There is no plugin-specific database.

The intended user is an Obsidian practitioner who wants the flexibility of a structured task system without leaving the Markdown file model. The plugin adds views, time tracking, calendar sync, and recurring task management on top of that file model rather than replacing it. All views are powered by Obsidian Bases, which is Obsidian's core plugin for turning notes into queryable databases. TaskNotes registers as a Bases data source and provides custom view types: `tasknotesTaskList`, `tasknotesKanban`, `tasknotesCalendar`, and `tasknotesMiniCalendar`.

A web app at app.tasknotes.dev and an iOS app on the App Store give access to the same task data outside the Obsidian desktop application, without requiring the Obsidian app on mobile.

## How TaskNotes Stores Tasks as Markdown Notes

A task in TaskNotes is a Markdown file with YAML frontmatter. The frontmatter carries the task's structured properties: title, status, due date, priority, contexts, projects, time estimate, and time entries.

```yaml
title: "Complete documentation"
status: "in-progress"
due: "2024-01-20"
priority: "high"
contexts: ["work"]
projects: ["[[Website Redesign]]"]
timeEstimate: 120
timeEntries:
  - startTime: "2024-01-15T10:30:00Z"
    endTime: "2024-01-15T11:15:00Z"
```

The `projects` field uses Obsidian's wikilink syntax, which means tasks link directly to project notes in the vault. The `timeEntries` array holds time-tracking sessions as start/end timestamps. All property names are configurable in settings: if your vault already uses `deadline` instead of `due`, you can remap it without migrating existing notes.

The frontmatter is extensible. The README gives the example of adding an `energy-level` or `client` field; any custom field added to a task note is immediately available in Bases for filtering and grouping without any plugin configuration. Because the views are `.base` files (plain text), you can edit filters and sorting directly or duplicate a view to create a specialised one.

## Views Powered by Obsidian Bases and Computed Formulas

TaskNotes ships with default .base files for the Task List, Kanban, Calendar, and Agenda views. These are stored in a TaskNotes/Views/ directory in the vault and can be opened with commands like TaskNotes: Open tasks view or TaskNotes: Open kanban board.

The default .base files include formula properties for computed values that are more useful than raw fields alone:

```yaml
formulas:
  daysUntilDue: if(due, ((number(date(due)) - number(today())) / 86400000).floor(), null)
  isOverdue: due && date(due) < today() && status != "done"
  urgencyScore: formula.priorityWeight + max(0, 10 - formula.daysUntilDue)
  efficiencyRatio: (timeTracked / timeEstimate * 100).round()
```

These formulas run inside Bases. `urgencyScore` combines priority weight and days-until-due into a sortable number, which lets the task list surface the most urgent items regardless of whether priority or due date dominates. `efficiencyRatio` computes the ratio of tracked time to estimated time as a percentage, useful for reviewing how well estimates held up.

Task creation uses natural language parsing. Typing "Buy groceries tomorrow #errands" in the creation dialog extracts the due date and context tag automatically. Natural language parsing supports English, German, Spanish, French, Italian, Japanese, Dutch, Portuguese, Russian, Swedish, Ukrainian, and Chinese.

## Time Tracking, Pomodoro, and Google Calendar Sync

Time tracking in TaskNotes works at the task level: each task can have multiple time entries, each recorded as a start time and end time in the YAML frontmatter. The plugin adds start/stop controls and a Pomodoro timer with session history, keeping time data in the same Markdown file as the task itself.

Calendar sync supports Google Calendar and Microsoft Calendar using OAuth Device Flow (RFC 8628), and any ICS feed. The README's .env.example explains the Device Flow model: the plugin displays a short code that the user enters at google.com/device, and the plugin polls for authorization. No client secret is bundled in the plugin; the .env.example carries the public GOOGLE_OAUTH_CLIENT_ID for users who bring their own OAuth credentials.

Users with a valid TaskNotes licence can use the built-in client ID for easier setup; users without a licence must supply their own OAuth credentials from the Google Cloud Console or Azure portal. The README does not specify the current price of a TaskNotes licence or how to acquire one; the external website at tasknotes.dev is the reference for that.

## Recurring Tasks and Materialized Occurrence Notes

Recurring tasks use RRULE format in the frontmatter's recurrence field. The plugin tracks which individual occurrences have been completed in a `complete_instances` array, so completing one instance of a weekly meeting does not mark all future instances as done.

```yaml
title: "Weekly meeting"
recurrence: "FREQ=WEEKLY;BYDAY=MO"
complete_instances: ["2024-01-08"]
```

When an individual occurrence needs its own note, TaskNotes can materialize it as a standalone task note. The occurrence note inherits planning metadata (scheduled time, due offset, tags, contexts, projects, reminders, and time estimate) from the parent but does not copy the parent's recurrence rule, completion history, or time entries.

```yaml
title: "Weekly meeting"
recurrence_parent: "[[Tasks/Weekly meeting]]"
occurrence_date: "2024-01-15"
scheduled: "2024-01-15T09:30"
timeEstimate: 60
```

Calendar views show the note-backed occurrence in place of the matching virtual recurrence instance. This design allows occasional exceptions, such as a meeting with a longer agenda that needs its own notes and time tracking, without disrupting the recurring pattern on other dates.

## Limitations and When TaskNotes Is Not the Right Tool

TaskNotes requires Obsidian and Obsidian Bases. The plugin is not a standalone task manager; it is built around Obsidian's file system and query layer. Anyone who does not already use Obsidian, or who wants tasks accessible without the Obsidian ecosystem, will find the dependency on Bases and vault structure restrictive. The iOS and web apps extend access beyond the desktop, but they run against the same vault data.

Obsidian itself is a local-first tool that stores data in the local filesystem. Sharing tasks with team members requires a sync mechanism (Obsidian Sync, iCloud, Git) that is external to the plugin. There is no built-in multi-user database; each user has their own vault.

Version 5.0.0 is currently in beta (5.0.0-beta.4 released 2026-09-28). The stable branch is 4.x, with 4.13.6 released 2026-09-26 and 4.13.5 released 2026-09-23. Teams that need production stability should stay on the 4.x stable releases until 5.0.0 exits beta. The 5.0.0 release presumably brings changes significant enough to warrant a major version bump.

## Related Tools, Maintenance, and Licensing

TaskNotes is MIT licensed. The MIT licence permits use, modification, and redistribution without restriction.

The last push to the main branch was on 2026-09-23. The release cadence is active: three releases in the week ending 2026-09-28. A browser extension and a CLI are available as separate repositories (tasknotes-browser-extension and tasknotes-cli in the README). Webhooks can notify external services on task changes. HTTP API documentation is at docs/HTTP_API.md in the repository.

The repository includes an e2e test suite using Playwright that generates screenshots for the documentation (the `npm run e2e:docs` script). This is a good sign for a plugin with complex UI behaviour: the test suite captures calendar views, task views, and feature screenshots directly from a running instance of the plugin.

## Conclusion

TaskNotes suits Obsidian users who want their tasks stored as portable Markdown files with no plugin-specific database lock-in, and who need time tracking and calendar sync alongside the task views. It is not the right choice for someone who wants a standalone task manager that works without Obsidian, or who needs a team-shared task database. Version 5.0.0 is in beta as of 2026-09-28; anyone who needs stability should stay on the 4.x stable releases until 5.0.0 reaches general availability.

## FAQ

### How do I use TaskNotes in Obsidian?

Create a task with the TaskNotes: Create new task command. Open views with TaskNotes: Open tasks view or TaskNotes: Open kanban board. The plugin parses natural language in task creation, so typing a date or context tag extracts them automatically.

### What is the difference between Obsidian TaskNotes and Tasks?

TaskNotes stores each task as a separate Markdown note with YAML frontmatter and powers all views through Obsidian Bases queries. The README states there is no plugin-specific database, so task files are portable plain text.

### How does TaskNotes compare to Todoist?

TaskNotes keeps all task data as Markdown files in your local Obsidian vault with no plugin-specific database. The README states tasks can be read by any tool, transformed with scripts, or migrated elsewhere.

## Sources

- [Official documentation](https://tasknotes.dev)
- [Official README](https://github.com/callumalpass/tasknotes#readme)
- [Project repository](https://github.com/callumalpass/tasknotes)
- [Release notes](https://github.com/callumalpass/tasknotes/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/callumalpass-tasknotes