tasks.nvim · Project & repos · vimdoc

:help tasks_nvim

Task files in a Markdown vault: engine, :Tasks, headless CLI

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 *tasks_nvim-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 *tasks_nvim*

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.lua is 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 *tasks_nvim-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 *tasks_nvim-setup*

  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*

  :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 *tasks_nvim-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 *tasks_nvim-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.
Only title and status are 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 waits counts the reasons, :Tasks list --waits-for=mac lists a group
and :Tasks release mac sets it back to open.

                                                          *tasks_nvim-wikilinks*
blocked_by, after and plan also 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. check reports a slug that names nothing
(wikilink-dangling) or several tasks (wikilink-ambiguous, with the
candidates). The plan, next, estimate and the index see the id. The
target of a plan file takes the same forms (plan-new --target=[[slug]]).

7. HEADLESS CLI *tasks_nvim-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.lua runs
check, index --check and the vault's md_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 (check reports
symlink-task), and a folder of the vault that leads out of it is not scanned.

8. HEALTH *tasks_nvim-health*

:checkhealth tasks_nvim reports Neovim and lib.nvim, the resolved vault and
its areas, options that setup() ignored, whether |:Tasks| is registered,
which optional pieces are present, and under "AI functions" the option ai
with what is found of ai.nvim and ai-desktop.

9. MACHINE CONTRACT *tasks_nvim-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_preview
and ops, the write door (set, new, reorder, done, move_area). Exit codes: 0 an answer, 2 invalid_argument, 1 any other error (a
tasks.error document, also on stdout; for ops: 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 with valid: false,
and each task carries an etag; rev and digest say whether anything
changed.