tasks.nvim: Markdown-native task management for Neovim

tasks.nvim, a small Neovim plugin for managing tasks from plain markdown files.

I have been using markdown notes for a long time (since 2018). Some notes are daily diary entries, some are project notes, some are meeting notes, some are rough scratch docs.

I had tried Obsidian tasks to manage tasks for a few weeks in 2025. I felt Obsidian’s vim mode was too slow while making multiple quick motions in NORMAL mode or switching between NORMAL/INSERT modes.

I liked the markdown nativeness of the tasks on Obsidian and I wanted to do it in my Neovim workflow to be fast and simpler. So yea, it’s a heavily copied version of Obsidian’s task management but as a Neovim plugin.

A task in this setup is a markdown checkbox with #task on it:

- [ ] #task Ship the API changes  [due:: 2026-03-25]  [priority:: high]
- [/] #task Review the migration plan [[tasks/migration-plan]]
- [x] #task Fix auth middleware  [completion:: 2026-03-21]

There is some optional metadata on the same line. Due dates, priorities, labels, completion dates, wiki links etc.

Task dashboard

:Tasks opens a floating dashboard built by scanning the markdown vault (a directory of markdown files in my case) with ripgrep, parsing matching markdown lines, and grouping them using simple queries.

The default sections are mostly urgency based like overdue, due today, and pending. The sections are configurable. Updating a task changes the original markdown line in the original file.

Basic statuses:

[ ] todo
[/] in-progress
[x] done
[-] cancelled

Marking a task done or cancelled adds a completion date.

Notes attached to tasks

For some tasks, they may also need some more notes. A 1:1 task and associated note mapping doesn’t exist with tasks plugin in Obsidian AFAIK.

- [/] #task Refactor payment service [[tasks/refactor-payments]]  [due:: 2026-03-25]

The [[tasks/refactor-payments]] link points to a normal markdown file. The dashboard can open that note inline in the same floating window which I can edit, save and return to the task list.

Labels and search

Labels are hashtags (except #task, that’s a special label to denote a “task”).

- [ ] #task #api-team Deploy API service  [due:: 2026-03-28]
- [ ] #task #otel Estimate timelines for OTel migration

The dashboard can filter by label and switch into a status grouped view for that label. There is also a fuzzy search over task description, date, priority, and tags.

I also added inline highlighting for #task and labels in normal markdown buffers. It is cosmetic mostly for me to easily scan through my eyes.

My Setup

Here are configs of my tasks.nvim, sections I use etc.

require("tasks.nvim").setup({
    vault_path = "~/notes",       -- root of markdown vault
    diary_path = "~/notes/diary", -- where diary entries live
    tasks_path = "tasks",         -- note files dir (relative to vault_path)

    sections = {
        { name = "P0 (Overdue)",  query = "not done\ndue before today\nsort by due" },
        { name = "P1 (Due Today)", query = "not done\ndue today\nsort by due" },
        { name = "All Pending",   query = "not done\n(due after today) OR (no due date)" },
    },

    symbols = {
        todo        = "✗",
        in_progress = "◐",
        done        = "✓",
        cancelled   = "●",
    },

    width  = 0.6, -- float width as fraction of editor
    height = 0.7,
})

macOS menu bar

I also made tasks.macos, a tiny macOS menu bar app for the same task format.

It is a read-only view of the tasks that would show up in the dashboard. This is useful for times when I don’t have my Neovim opened and I can have a quick look at the active tasks