List Tasks
vault_list_tasksQuery vault-wide checkbox tasks with structured filters for status, dates, priority, tags, folder, and heading, returning each task's file path, line, and heading so results are actionable.
Instructions
List checkbox tasks across the whole vault with structured filters — the Tasks-plugin data model over MCP. Both task metadata formats are indexed: emoji signifiers (📅 due, ⏳ scheduled, 🛫 start, ➕ created, ✅ done, ❌ cancelled, 🔺⏫🔼🔽⏬ priority, 🔁 recurrence, 🏁 onCompletion, 🆔/⛔ dependencies) and Dataview inline fields ([due:: 2026-07-04], [priority:: high], ...). Every result says where the task lives (path, line, heading; see Returns), so no follow-up reads are needed to locate it. Task lines inside fenced code blocks and %% %% comment blocks are not indexed. Checkboxes typed NON_TASK in the Tasks plugin's status registry are also excluded.
Example: vault_list_tasks({ due: { before: "2026-07-04" } }) — overdue triage; the default status (not_done) and sort (due ascending) make this the "what's overdue?" call Example: vault_list_tasks({ path: "Code Projects/vault-cortex/TASKS.md", heading: ["Active", "Up Next", "Waiting On"], sort_by: "position" }) — actionable Kanban lanes in board order Example: vault_list_tasks({ folder: "Code Projects/vault-cortex" }) — all open tasks across a project tree (TASKS.md + task-notes/ subdirectories) Example: vault_list_tasks({ status: "done", done: { after: "2026-06-26" } }) — what got completed this week Example: vault_list_tasks({ top_level_only: true, path: "TASKS.md" }) — board cards only, excluding checklist sub-items
When to use: Reading task status and order on one board (path + sort_by: "position"; add status: "all" to include done and cancelled cards). Also any vault-wide task triage question — "what's overdue?", "what's open per project?", "what did I finish this week?" — in one call instead of per-board reads. Prefer vault_read_note (heading mode) only when you need a lane's verbatim Markdown or a task's state right after a write. Prefer vault_search for full-text queries over note content.
Behavior: A file change takes a few seconds to appear here, so a task written moments ago may still show its old state.
Parameters:
status: "not_done" and "all" expand in arrays — ["not_done", "done"] matches todo + in_progress + done.
due / scheduled / start / done / created / cancelled: a date filter only matches tasks that HAVE that date.
folder: a whole folder, subfolders included ("Projects" covers "Projects/Archive" but not "ProjectsOld/"), ignoring ASCII letter case.
Errors:
"invalid due.before date: …" (any date filter's bound) — the bound isn't in YYYY-MM-DD form; use that form
"… is not a calendar date" — the bound has the YYYY-MM-DD form but names a day that doesn't exist, such as 2026-02-30; pass a real date
"path must end in .md" — add the ".md" extension
"tag must not be empty …" — tag is "#" alone; pass the tag name
No matches returns { total: 0, tasks: [] }, not an error
"[SqliteError]: …" / "[IndexIntegrityError]: …" — the search index failed, not the call; the message says what to do
Returns: JSON { total, tasks }. Every task carries path, line, status, status_char, description, folder, depth (0 for top-level, 1+ for sub-tasks), is_kanban_task, depends_on, and tags (the arrays are [] when empty). Every other field appears only when the task has it: heading (nearest heading above the task), created/scheduled/start/due/done/cancelled dates, priority, recurrence, on_completion, task_id, block_id, parent_block_id (sub-tasks whose parent carries a ^block-id), done_lanes (Kanban boards only), and subtask_progress — { done, total } over the task's DIRECT checklist children, present only when the task has a checklist; done counts status "done" only (a cancelled child counts toward total, not done), and the counts ignore the query's filters — so a filtered or top_level_only read still shows each card's checklist progress.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| due | No | Due date (📅 / [due:: ]) bounds | |
| tag | No | Tag on the task line, "#" optional; matches nested tags, any letter case | |
| done | No | Done date (✅ / [completion:: ]) bounds | |
| path | No | Restrict to one note (vault-relative path ending ".md", case-sensitive) | |
| limit | No | Max results (default 50); total always reports the full match count | |
| start | No | Start date (🛫 / [start:: ]) bounds | |
| folder | No | Restrict to a folder (e.g. "Code Projects/vault-cortex") | |
| status | No | Status filter, OR-combined (default "not_done" = todo + in_progress, excluding done and cancelled). "all" includes every status. | not_done |
| created | No | Created date (➕ / [created:: ]) bounds | |
| heading | No | Exact heading text or array of headings, OR-combined, case-sensitive (e.g. "Active" or ["Active", "Up Next"]) | |
| sort_by | No | Sort key (default "due"). Date sorts cascade through related fields when the primary is absent (through the rest of due → scheduled → start → created, in that order; done does not cascade); each fallback uses its own natural direction. "position" sorts by file path then line number — the natural order for Kanban boards. | due |
| priority | No | Priority levels, OR-combined; "none" selects tasks with no priority signifier | |
| cancelled | No | Cancelled date (❌ / [cancelled:: ]) bounds | |
| scheduled | No | Scheduled date (⏳ / [scheduled:: ]) bounds | |
| sort_direction | No | Sort direction. Default per field: "asc" for due/scheduled/priority/position, "desc" for start/created/done/note_mtime. Within a date cascade, each fallback uses its own default; an explicit value overrides all fields uniformly. | |
| top_level_only | No | When true, only top-level tasks (depth 0) are returned — excludes indented sub-tasks and checklist items. Default false. |