doc/tasks_nvim.txt — rendered from the plugin's own vimdoc
*tasks_nvim.txt* Task files in a Markdown vault: engine, :Tasks, headless CLI Author: Stefan Bartl License: MIT
CONTENTS
1. Introduction ........................................ |tasks_nvim| 2. Requirements ........................................ |tasks_nvim-requirements| 3. Setup and configuration ............................. |tasks_nvim-setup| 4. Commands ............................................ |:Tasks| 5. Dashboard and form keys ............................. |tasks_nvim-keys| 6. Task file format .................................... |tasks_nvim-format| 7. Headless CLI ........................................ |tasks_nvim-cli| 8. Health .............................................. |tasks_nvim-health| 9. Machine contract .................................... |tasks_nvim-contract|
1. INTRODUCTION
One Markdown file per task (flat YAML frontmatter), one generated overview per area (<area>/ROADMAP/TASKS.md), finished tasks in<area>/Backlog/. The engine is pure Lua; |:Tasks| is the editor front end (dashboard, form, preview);scripts/tasks.luais the headless CLI. Both use the same engine. Capturing is one call with a title and never asks for more. A task without blockers, plan or estimate is valid and stays visible everywhere.
2. REQUIREMENTS
Neovim 0.11+ and lib.nvim (required). Optional: snacks.nvim (dashboard), mdview.nvim (browser preview), ui.nvim (your theme preset for the confirmations; lib.nvim ships a copy of the kit), pickers.nvim (:Tasks folder), cascade.nvim (form), git (dates for--stale=refs).
3. SETUP AND CONFIGURATION
require("tasks_nvim").setup({
vault = "~/vault",
extra_areas = { "ALL" },
links = "plain", -- "plain" | "wikilink"
dashboard = { watch = true, debounce_ms = 250, backend = "auto" },
staleness = { git_timeout_ms = 20000, budget_ms = 30000, repo_bases = {} },
ci = { lint_timeout_ms = 120000 },
next = { popup = true, cdx_hint = true },
chain = { marker_docs = {} },
steps = { ask_finish = false },
reminders = { on_start = true },
completion = { finished = true }, -- true, false or N days
quick_wins = { min_value = 4, max_effort = "S" },
lists = {},
tree = true, -- true, false or { keys = { done =, claim = } }
ai = "auto", -- false, true or "auto"
})
vault The vault folder (one folder per area). When unset
$TASKS_VAULT is read. There is no built-in path.
extra_areas Folders that are areas although they hold neither
ROADMAP/ nor Backlog/. The headless CLI reads
$TASKS_EXTRA_AREAS (comma separated) for the same.
links How set, new, the dashboard's assign and a move
write a reference in blocked_by, after and plan:
"plain" ids (default) or Obsidian wikilinks ("wikilink":
"[[slug]]", the vault path with the id as alias when
the slug is in several areas). A value the file holds
keeps its form, both forms are always read. The
headless CLI reads $TASKS_LINKS (Neovim too while
setup() sets no links). |tasks_nvim-wikilinks|
dashboard.watch Refresh the dashboard when task files change.
dashboard.debounce_ms Quiet period before a refresh (default 250).
dashboard.backend Picker of :Tasks list: "snacks", "kit" (lib.nvim, no snacks;
Alt-chord keys), "select", or "auto" (snacks if installed, else kit).
staleness.git_timeout_ms One git log call is killed after this long.
staleness.budget_ms All git calls of one --stale=refs run together.
staleness.repo_bases Folders holding the repos by name (<base>/<area>).
ci.lint_timeout_ms The vault's md_lint.lua is killed after this long.
ci.trust_vault_lint Allow ci to run the vault's own md_lint.lua.
next.popup After done: a dialog with the next task (else a message).
next.cdx_hint Name ready tasks written cdx apart, never as your next task.
chain.marker_docs Documents whose <!-- GENERATED:plan scope=... --> blocks are
refreshed after a task is finished (only these files). The
headless CLI reads $TASKS_MARKER_DOCS (comma separated).
quick_wins.min_value A quick win has at least this value (1-5) ...
quick_wins.max_effort ... and at most this effort (XS..XL or days like 0.5d).
lists Named lists, `{ ["name"] = { effort = "<=S", value = ">=4",
sort = "roi", desc = "..." } }`: the option words of
:Tasks list. Run with --list={name} or tasks list @name.
A later setup() replaces the set; see :Tasks lists.
steps.ask_finish In a task buffer, ticking the last ## Plan step asks to finish
the task (off by default: it adds an autocommand).
reminders.on_start One line shortly after startup when reminders (remind:) are due
(once per session, only with a UI; false turns it off).
tree The vault in a tree view that reads lib.nvim's tree registry (the
own tree of filetree.nvim): a count of open tasks next to an area
folder, a view tasks (areas, below them their open tasks), and
the actions "finish" and "claim" on a task in the tree's menu.
{ keys = { done = "gD", claim = "gC" } } puts the actions on
keys of the tree buffer; false registers nothing. The count is
read from the heading of ROADMAP/TASKS.md, never by a scan.
ai The AI functions of the ai family (handing a task to an
agent): false = none at all (no command, no key, no
menu entry), true = always, "auto" (default) = only
where ai.nvim can be loaded or ai-desktop is installed
or running (its manifest in the appkit-family folder
or its hub.json; only files are read). It shows or
hides |:Tasks| agent. See |tasks_nvim-health|.
keys.dashboard Dashboard list keys: action = key, or false.
keys.dashboard_input Dashboard input-window keys (normal and insert).
form.mode Window of the :Tasks new form: "float" (default), "split",
"vsplit" or "current"; :Tasks new mode=... for one call.
keys.form Keys of the :Tasks new form.
Actions: see |tasks_nvim-keys|.
A wrong key or value is ignored with a message and listed in
:checkhealth tasks_nvim; the default stays.
vim.g.tasks_nvim_no_command = true keeps the plugin from registering |:Tasks|.
4. COMMANDS
:Tasks list [{area}|all] [filters] [--sort=] [--to=] [--format=] [--force]
Open tasks: a dashboard, or a table to a buffer, the clipboard, the
quickfix list, a file, a browser preview. An existing file is only
overwritten after a yes in a dialog; --force skips the question.
Filters: --status= --prio= --effort= --kind= --category= --severity=
--value=4,5|>=4 --actor=cdx|me|pair|none
--tag= --stale=<days>|refs --blocked --reminders
--waits-for=<key>,...|none (parked tasks by their reason)
:Tasks new [{area} [{title}...]] [kind= prio= effort= value= actor=
tags= category= severity= status=] [--folder]
Without arguments a Markdown form (<C-s> submits).
:Tasks new --draft {text}... The form, filled in from a free text
(or the selected lines) by ai-desktop's
job draft-task or one answer of
ai.nvim; asks before the text leaves
the machine; <C-s> creates the task.
:Tasks set {id} {key}={value} ... Change frontmatter; an empty value
removes the key. A finished task takes
remind= only. waits_for={key} parks
the task and says what it waits for;
any other status drops the reason.
:Tasks waits [{area}|all] What the parked tasks wait for: tasks
and areas per waits_for key, the
parked ones without a reason, the total.
:Tasks release {key} [--dry-run] [--yes]
Set every parked task that waits for
{key} to open (asks first; --dry-run
only names them).
:Tasks done {id} [done_in= commits= date=] [--yes]
commits=repo@sha,... lists the commits
made for the task (added to its own).
Finish and move to Backlog/; names
what it freed and offers the next task.
:Tasks agent [{id}] [mode=prefill|run] [kind=handoff|review-done|draft-task|
prepare-decision|split-plan]
Hand the task (default: the buffer's)
to ai-desktop's job intake: its
dashboard shows it as a new job
(prefill, the default) or runs it
(run). Local only: hub.json and
control.secret of ai-desktop are
read, the secret is never shown.
Without a running ai-desktop,
ai.nvim answers once in the buffer
tasks://agent/{id} (run asks first).
kind=review-done checks a finished
task (an id in Backlog/) against
its acceptance; the review comes back
to tasks://review/{id} and goes into
the task as section ## Prüfung only
after a yes (a proposed follow-up
task after a second yes).
kind=prepare-decision (a task in
status decision) adds ## Vorschlag
and ## Offene Fragen after a yes;
the status stays, |:Tasks| answer
decides. kind=split-plan takes a
plan id: its drafts come to
tasks://split/{plan} to tick ([x]);
:w creates the ticked ones after a
yes (a new phase after its own yes).
Hidden while the option ai is off.
:Tasks plan [{area}|all] [--for={id}|--plan={id}] [filters] [--ready] [--with-steps]
[--format=] [--to=] [--write={file} [--scope=] [--check]]
Ready now, decisions by leverage,
stages, critical path.
:Tasks planfile {area} {title...} [--areas=] [--phases=] [--gate=hard] [--target=]
Create a plan file under ROADMAP/plans/.
:Tasks next [{area}|all] [--n=] [--actor=]
The best ready task, with the reason.
:Tasks estimate [{area}|all] [--for={id}] [filters] [--walk]
Sums of effort and value, what is
missing; --walk asks for them.
:Tasks lists Pick a named list and open it as the dashboard.
:Tasks list --list={name} [more options] Run a named list; options you give win.
:Tasks quickwins [{area}|all] [filters] [--to=] [--format=md|tsv|ids] [--by-actor] [--paths] [--report={file}]
The quick wins, best return first, and the
small tasks that miss a value.
:Tasks attach {id} {file} [name=] Copy a file into assets/.
kind=video|image|screenshot: into the
folder of its kind below it.
:Tasks folderize {id} Make a plain task a folder task.
:Tasks template [--to=] The task file template.
:Tasks open {id|part} Open the task file; a part of the name is
enough when it points at one task.
:Tasks preview {id} Browser preview (mdview.nvim).
:Tasks index [{area}] [--all] [--check]
(Re)write the generated overviews;
--check writes nothing.
:Tasks folder {area} [folder] [--action=] [--list] [--to=]
Picker over a folder of an area.
:TasksVault {verb} [{area}] [{part}] [--rel] [--file]
verbs: open clipboard paste link find grep tree cdx; {part} is backlog (default),
features, tasks, roadmap or all.
:TasksVault new feature|task {title...} [--area=] A dated note in the Backlog.
:TasksVault create [{dir}] [{area}...] [--force] [--yes]
Create a vault folder (--yes: no question).
:TasksVault status The vault in use.
An id is <area>/<slug>. <Tab> completes verbs, areas, ids, values and the
settable keys. Details: docs/COMMANDS.md. Scenarios: docs/WORKFLOWS.md.
The vault in Obsidian (Bases, Dataview, what to edit there): docs/OBSIDIAN.md.
5. DASHBOARD AND FORM KEYS
No global key is mapped. In the dashboard list (g?shows this): <CR> open <Tab> mark s status p prio D finish f filter chip o sort e export gp preview r rescan gb backlog gr roadmap ga attach a screenshot (clipboard image, else the newest screenshot) gl lists (apply, save the current view as a list, rename or delete one) gh / gH hand the task to an agent (|:Tasks| agent, prefill / run); only while the AI functions are on (ai), else no key and no help line In the input window the same actions are on `<M-s> <M-p> <M-d> <M-f> <M-l> <M-o> <M-e> <M-r> <M-i> <M-b> <M-m> <M-v> <M-?>(and<M-h> <M-H>` for the agent) (they shadow some snacks defaults). In the task form:<Space>/<CR>tick a line,<C-s>submit,q/<C-q>cancel (asks when text was typed),g?help.
6. TASK FILE FORMAT
---
title: Fix the thing
status: open # doing | decision | blocked | open | parked
kind: bug # feature | task | bug | idea | research
prio: 2 # 1 (highest) .. 3
effort: S # XS S M L XL, or 0.5d, 3d
tags: [ui]
category: [bug] # bug security performance docs ruleset
# ux bindings refactor tests ci learning
blocked_by: [other-area/other-task]
refs: [lua/foo/init.lua]
created: 2026-10-05
updated: 2026-10-05
---
One summary paragraph, then free Markdown.
Onlytitleandstatusare required. Unknown keys are kept when a file is rewritten. Full reference: docs/ENGINE.md. *tasks_nvim-waits_for* A parked task may say what it waits for from outside:waits_for: mac(one word of your own: lower-case letters, digits and-). `:Tasks set {id} waits_for=mac` parks the task with that reason, any other status drops it;:Tasks waitscounts the reasons,:Tasks list --waits-for=maclists a group and:Tasks release macsets it back to open. *tasks_nvim-wikilinks*blocked_by,afterandplanalso take Obsidian wikilinks, in quotes as Obsidian writes them:"[[area/slug]]","[[area/slug|Alias]]", the vault path ("[[area/ROADMAP/tasks/slug]]") and"[[slug]]"when exactly one task or plan of the vault has that slug.checkreports a slug that names nothing (wikilink-dangling) or several tasks (wikilink-ambiguous, with the candidates). The plan,next,estimateand the index see the id. Thetargetof a plan file takes the same forms (plan-new --target=[[slug]]).
7. HEADLESS CLI
nvim --headless -u NONE -l scripts/tasks.lua list --status=doing
nvim --headless -u NONE -l scripts/tasks.lua done my-area/slug --done-in=repo@abc
nvim --headless -u NONE -l scripts/tasks-ci.lua
The vault is--vault=<dir>or$TASKS_VAULT. Exit codes: 0 success, 1 a finding or failed operation, 2 a usage error.scripts/tasks-ci.luarunscheck,index --checkand the vault'smd_lint.lua. That script is RUN, so it is refused unless you pass--trust-vault-lint(or--md-lint=<own copy>). A task file that is a symbolic link or a junction is not read (checkreportssymlink-task), and a folder of the vault that leads out of it is not scanned.
8. HEALTH
:checkhealth tasks_nvimreports Neovim and lib.nvim, the resolved vault and its areas, options thatsetup()ignored, whether |:Tasks| is registered, which optional pieces are present, and under "AI functions" the optionaiwith what is found of ai.nvim and ai-desktop.
9. MACHINE CONTRACT
For apps, agents and pipelines: versioned JSON documents. The
shapes, rules and errors are in docs/CONTRACT.md; the JSON Schemas are in
schemas/tasks-export/1/.
nvim --headless -u NONE -l scripts/tasks.lua call hello
nvim --headless -u NONE -l scripts/tasks.lua call snapshot
nvim --headless -u NONE -l scripts/tasks.lua call list --params='{"limit":20}'
nvim --headless -u NONE -l scripts/tasks.lua call task --params='{"id":"area/slug"}'
Methods:hello,snapshot,list,task,next,areas,done_previewandops, the write door (set,new,reorder,done,move_area). Exit codes: 0 an answer, 2invalid_argument, 1 any other error (atasks.errordocument, also on stdout; forops: any operation failed).--params=-reads the JSON from stdin. From Lua:require("tasks_nvim.api").call(), which never throws. A document has no path of this machine, a missing number is unknown (never 0), a broken task is listed withvalid: false, and each task carries anetag;revanddigestsay whether anything changed.