# Obsidian Tasks rewrites your notes when you tick a box in a query

> The Obsidian Tasks plugin does not keep a task database. It reads markdown checkboxes out of your notes, renders them through a small query language, and writes the change back to the file when you change a status, which is why the documentation spends as much time on hotkeys and performance limits as on the query syntax. The engineering underneath is a TypeScript plugin with a Svelte interface, approval tested output and a dependency cycle check that emits an image.

**obsidian-tasks-group/obsidian-tasks** — Task management for the Obsidian knowledge base.

- Repository: https://github.com/obsidian-tasks-group/obsidian-tasks
- Website: https://publish.obsidian.md/tasks/
- Stars: 4,047 · Forks: 392
- Language: TypeScript
- License: MIT
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/obsidian-tasks-group-obsidian-tasks

## It edits the source file, so the notes are the database

The one line that explains the whole design is in italics near the top: you can toggle a task status in any view or query and it will update the source file. So there is no database, no import step and no sync problem. Tasks are ordinary markdown checkboxes in ordinary notes, and the plugin's job is to find them, render them and write back the character that changed. The rest of the feature description follows from that: it tracks tasks across an entire vault, supports due dates, recurrence, done dates, a sub-set of checklist items and filtering, and a set of queries gathers tasks from wherever they live. The cost of that choice is that every state change is a file write in a live editor, which is what the performance note and the hotkey advice in the setup steps are about.

## Installation ends with a hotkey conflict you have to fix by hand

The setup is four steps, and the fourth is the one people miss. Find the plugin in the community plugin browser, enable it, look at the settings, and then replace the hotkey that toggles a checkbox status with the plugin's own command. The recommendation is to remove the original toggle hotkey entirely and bind the plugin command to the platform's standard confirm combination, control plus return on Windows and Linux and command plus return on a Mac. That recommendation is a workaround for a real conflict, not a style preference: the editor already has a checkbox toggle, and the plugin needs a different key to do the same thing with the extra state a task carries. The third step is also a warning, since the settings make sense to configure early, specifically the global filter.

## A task is a checkbox with an emoji date on the end

The getting started section shows three lines that define the whole data format, and they are worth reading as a specification rather than as an example. A plain checkbox is a task with no date at all. A second line adds a due date, written as an emoji followed by an ISO formatted day. A third adds a scheduled date, written as a recurrence emoji with a natural language rule, followed by a start date in the same emoji style. The three examples are:

```text
- [ ] Something non-important, with no date
- [ ] Remember to do that important thing - with a due date 2022-12-17
``` So the format is markdown plus emoji, which means a task is readable without the plugin, portable to any other tool that understands checkboxes, and lossy if the emoji are stripped by an editor that does not preserve them. The plugin supports the sub-set of checklist items it recognises rather than all of the markdown checkbox variants.

## Queries are a small language with a performance warning in them

A query is written in a fenced block inside a note, and the documented example is annotated line by line, which is the best documentation in the project. The first comment explains the three accepted spellings of an open task and adds that indented tasks work but only when they are on a single line. Then come the operators: one for tasks that are not done, one for tasks due today or earlier. Then the limit clause, and the comment attached to it is the most useful sentence in the file: if you ask for many hundreds or thousands of tasks, the editor's own performance really slows down, so the example caps at one hundred. The rest of the example groups by filename, sorts by due date in reverse and then by description, and ends with an instruction asking the plugin to explain how it read the query.

## The screenshots assume a global filter nobody has set

The screenshots section opens with two disclaimers that tell you how to reproduce what you see. All the screenshots assume a global filter with a particular tag in it, and that filter is explicitly not set by default, which means a first time user comparing their own vault to the documentation will see nothing and conclude the plugin is broken. The second line says the screenshots use the default theme, which is a smaller surprise. The demo material is three notes: one ordinary note with a few tasks, one named as an important project with more tasks, and one that gathers every task in the vault and displays them through queries. A fourth command, described as helping when editing a task, is what the create or edit path uses.

## Two scripts install the plugin into a real vault

The package manifest has more going on than a typical plugin. The dev and build commands are the same bundler script with a mode argument, and the lint command is four tools in a row: two linter passes with a fix flag, a type check in no emit mode, and a component checker. Testing is split in two configurations, one for unit tests and one for integration tests, plus a watch mode for development. Then there are two deployment scripts, one in Node and one in PowerShell, both of which run the plugin inside a local Obsidian instance, which is how you test a change against the real application rather than a mock. The output is a single main file at the package root, so what gets shipped is one bundle.

## Dependency cycles are checked into the repository as text and an image

Two scripts in the manifest exist to police import structure rather than behaviour. One writes a textual dependency report to a file that is committed at the root, and the other asks a dependency graph tool for circular dependencies across the source and renders the result as an image. A plugin with this many user interface components and this much shared query logic accumulates cycles, and both a text file and a picture at the root are the way a reviewer notices them in a change. Two more files follow the same pattern of generated artefact committed next to its source: a documentation snippets directory with a manifest that describes which snippets get embedded where, and a versions file.

## The toolchain floor is Node 22.12, and the interface is Svelte

The declared engine is a specific patch-level minimum, which tells you how recent the runtime assumptions are, and the interface is built with a Svelte plugin and checked by a Svelte type checker in the lint command. Translations are extracted by a parser and then normalised by a second script, which is the mechanism behind the Spanish and French versions that arrived in the recent minor release, and the documentation has its own linter with a fix mode. The authorship line names three people, the creator and two maintainers, and the donations section says the plugin is free to use and has been supported since May 2022 by one of them, with money going to computing and tooling licences. The release titles double as a changelog, and the last three describe a column view with drag and drop for dates and priorities, group counts, and a fix for a settings tab that used to jump to the top when a status was edited.

## Conclusion

The plugin suits someone who already keeps notes in plain markdown and wants their to-do items queryable without moving them into another application. It does not suit a vault of thousands of tasks, because the documentation says outright that asking for hundreds of results slows the editor down, and it does not replace a dedicated task manager with reminders. Before installing, set the global filter early and rebind the status hotkey, and remember that every status change rewrites the source note.

## FAQ

### What is obsidian tasks?

A plugin that adds task management to an Obsidian vault. It tracks tasks across the whole vault, supports due dates, recurrence, done dates, a sub-set of checklist items and filtering, and lets you toggle a status in any view or query, which updates the source file.

### How do I use the obsidian tasks plugin?

Install it from the community plugin browser, enable it, set the global filter early if you want one, and replace the built in checkbox toggle hotkey with the plugin's toggle command, which the readme suggests binding to control or command plus return. Then write tasks as markdown checkboxes and put a query block in a note to view them.

### How do I use obsidian tasks queries?

Write a query block inside a note. The documented example filters for tasks that are not done and tasks due today or earlier, caps the result at one hundred because the editor slows down on hundreds or thousands, then groups by filename and sorts by due date in reverse. An explain instruction can be added to have the plugin report how it read the query.

## Sources

- [License: MIT](https://github.com/obsidian-tasks-group/obsidian-tasks/blob/main/LICENSE)
- [obsidian-tasks-group/obsidian-tasks on GitHub](https://github.com/obsidian-tasks-group/obsidian-tasks)
- [Project website](https://publish.obsidian.md/tasks/)
- [README](https://github.com/obsidian-tasks-group/obsidian-tasks/blob/main/README.md)
- [Releases](https://github.com/obsidian-tasks-group/obsidian-tasks/releases)

---

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