frontline.nvim

A Neovim plugin for integrating Taskwarrior task management directly into Markdown files.

Features

  • ๐Ÿ“ Embed Taskwarrior queries in Markdown headers
  • ๐Ÿ”„ Automatic task list updates on file open/save
  • โœ… Task status indicators: [ ] pending, [S] started, [x] completed, [-] deleted
  • ๐ŸŽฏ Priority, dependency, and reverse dependency markers
  • โš™๏ธ Configurable blank lines after task lists
  • โŒจ๏ธ Interactive task management with keybindings
  • ๐Ÿ”Ž Compact task View with annotations, dependencies and inline TODO toggling
  • ๐Ÿ• Local timezone display for dates and times
  • ๐Ÿ—‚๏ธ Multiple Taskwarrior workspaces support with @workspace syntax
  • ๐ŸŽจ Smart autocomplete for projects, tags, dates, workspaces, and priorities
  • ๐Ÿ”ƒ Configurable task sorting: global default and per-view sort: / sort.reverse: directives
  • ๐Ÿ–Œ๏ธ Configurable task line format, globally or per workspace: pick the placeholders and the bullet you want
  • ๐Ÿท๏ธ Opt-in tags next to the dates, filtered with globs (bug,review,meeting*)

Installation

Using lazy.nvim

{
  "yourusername/frontline.nvim",
  config = function()
    require('frontline').setup({
      newlines_after_tasks = 2,  -- Number of blank lines after tasks (default: 2)
    })
  end,
}

Using packer.nvim

use {
  "yourusername/frontline.nvim",
  config = function()
    require('frontline').setup()
  end,
}

Usage

Basic Query Syntax

Add Taskwarrior queries to your Markdown headers using the pipe | separator:

# My Pending Tasks | status:pending

# High Priority Work | project:work priority:H

# Due This Week | due.before:eow

Task Sorting

Tasks within each view are sorted by urgency by default. You can change the default sort globally via config, or override it per-view using sort: and sort.reverse: directives in the header.

Per-view sort syntax:

# Due Soon | +PENDING due.before:eow sort:due

# Recently Completed | +COMPLETED sort.reverse:completed

# By Project | @work +PENDING sort:project

sort:field sorts ascending; sort.reverse:field sorts descending. Active tasks always appear before completed/deleted tasks regardless of the sort field.

Supported sort fields:

FieldDescription
urgencyTaskwarrior urgency score (default)
priorityPriority, ordered as configured in Taskwarrior (uda.priority.values)
dueDue date (earliest first)
scheduledScheduled date (earliest first)
completed / endCompletion date
projectProject name (alphabetical)

Tasks with no value for the chosen field sort last (e.g. tasks without a due date when sorting by due).

Global default sort:

require('frontline').setup({
  default_sort = { field = "due", reverse = false },  -- default: urgency ascending
})

Multiple Workspaces

Frontline supports multiple Taskwarrior databases (workspaces) using the @workspace syntax in your queries:

# Personal Tasks | @personal status:pending

# Work Tasks | @work project:myproject status:pending

# Default Workspace Tasks | status:pending

Configuration:

require('frontline').setup({
  workspaces = {
    personal = "~/.config/taskwarrior/personal/.taskrc",
    work = "~/.config/taskwarrior/work/.taskrc",
  },
  default_workspace = "personal",  -- Used when no @workspace specified
})

A workspace can also be given in table form, with its own options โ€” the Taskwarrior rc file, where its notes go, and how its task lines are formatted:

require('frontline').setup({
  workspaces = {
    personal = "~/.config/taskwarrior/personal/.taskrc",
    work = {
      rc = "~/.config/taskwarrior/work/.taskrc",
      notes_directory = "~/notes/work",
      note_template = "templates/task.md",
      task_format = "{{description}} {{project}} {{icons}}",
      task_bullet = "-",
      show_tags = "bug,review",
    },
  },
})

Each option falls back to its global value when the workspace does not set it, and a workspace given as a plain rc string uses the global values throughout.

Key Points:

  • Use @workspace_name in your query to specify which workspace to use
  • If no workspace is specified, the default_workspace is used
  • If default_workspace is nil, the system’s default Taskwarrior database is used
  • A notification displays the current workspace when opening a file
  • All task operations (create, modify, toggle, etc.) use the current workspace context
  • Override workspace in task operations: Include @workspace in task creation input to override the current buffer’s workspace

Workspace Override Examples:

When creating a task, you can override the current workspace:

# In a buffer with @personal workspace
# Press <leader>tn to create a new task

# Create in current workspace (personal):
New task: Fix bug in app project:mobile

# Override to create in work workspace:
New task: @work Review PR project:backend priority:H

This allows you to quickly create tasks in different workspaces without switching buffers.

Task Format

Tasks are displayed as Markdown list items:

<bullet> <status> <task_format> `<uid>`
* [ ] Fix authentication bug (โฑ๏ธ2025-11-15 10:00) [โฐ2025-11-20 17:00] [H๐Ÿ”’] `abcd1234`
* [ ] Simple task `abcd1234`
* [ ] Task with due date only [โฐ2025-11-20 17:00] `abcd1234`
* [x] Shipped it {โœ…2025-11-18} `abcd1234`

Three parts of the line are fixed:

  • <status> โ€” the checkbox carrying the task status: [ ] pending, [S] started, [x] completed, [-] deleted.
  • `<uid>` โ€” the first 8 characters of the task UUID, in backticks. Every keybinding finds its task by this, so it is always appended at the end of the line.
  • The single space separating them from the rest.

Everything in between is the task_format template, and the bullet is set with task_bullet:

require('frontline').setup({
  task_format = "{{description}} {{icons}}",  -- default
  task_bullet = "*",                          -- default ("-", "+", or "" for no bullet)
})

Both are per-workspace options: set them inside a workspace entry and that workspace’s views render their own way, falling back to the global value above when it sets none.

require('frontline').setup({
  task_format = "{{description}} {{icons}}",  -- used by everything else
  workspaces = {
    work = {
      rc = "~/.config/taskwarrior/work/.taskrc",
      task_format = "{{description}} {{project}} {{due}}",
      task_bullet = "-",
    },
    personal = "~/.config/taskwarrior/personal/.taskrc",  -- keeps the global format
  },
})
# Work | @work status:pending
- [ ] Fix the login bug backend [โฐ2025-12-25] `abcd1234`

# Personal | @personal status:pending
* [ ] Book the dentist (โฑ๏ธ2025-12-20) [โฐ2025-12-25] [H] `ef567890`

The format is resolved per view, from the @workspace in its header (or default_workspace when the header names none), so two views in the same file can render differently.

Placeholders

Placeholders use the same Jinja-like {{name}} syntax as copy_task_format. A placeholder with nothing to show renders as an empty string, and the gap it leaves is collapsed, so a task without dates does not trail spaces.

PlaceholderRendersExample
{{description}}Task descriptionFix the login bug
{{icons}}Everything the default layout shows besides the description: the tags selected by show_tags, completion, scheduled, due, markers+bug {โœ…2025-12-01} (โฑ๏ธ2025-12-20) [โฐ2025-12-25] [H๐Ÿ”’]
{{due}}Due date, in squared brackets with โฐ[โฐ2025-12-25]
{{scheduled}}Scheduled date, in rounded parenthesis with โฑ๏ธ(โฑ๏ธ2025-12-20)
{{completed}}Completion date of a completed task, in curly brackets with โœ… (alias: {{end}}){โœ…2025-12-01}
{{markers}}The bracketed marker group: priority, blocked, blocking, recurring[H๐Ÿ”’โš“๐Ÿ”]
{{priority}}Priority, as configured in priority_labelsH
{{blocked}}๐Ÿ”’ when the task depends on tasks that are not done yet๐Ÿ”’
{{blocking}}โš“ when other tasks depend on this oneโš“
{{recurring}}๐Ÿ” when the task is an instance of a recurring task๐Ÿ”
{{project}}Project namework
{{tags}}All the tags, each with a + prefix (not filtered by show_tags)+urgent +backend
{{urgency}}Urgency score15.5

Add .raw to any placeholder to drop its decoration โ€” brackets, icon, or prefix โ€” and get the bare value:

PlaceholderRendersExample
{{due.raw}}Due date without [โฐ ]2025-12-25
{{scheduled.raw}}Scheduled date without (โฑ๏ธ )2025-12-20
{{completed.raw}}Completion date without {โœ… }2025-12-01
{{priority.raw}}Priority value, ignoring priority_labelsH
{{tags.raw}}Tags without the + prefixurgent backend

.raw on a placeholder that has no decoration ({{description.raw}}, {{project.raw}}) renders the same text as without it.

Dates in every placeholder follow convert_dates_to_local and relative_dates โ€” see Date Display below.

Examples

-- Default: the full layout
task_format = "{{description}} {{icons}}"
-- * [ ] Fix the login bug (โฑ๏ธ2025-12-20) [โฐ2025-12-25] [H๐Ÿ”’] `abcd1234`

-- Description only, for a distraction-free list
task_format = "{{description}}"
-- * [ ] Fix the login bug `abcd1234`

-- Only the dates you plan around, no priority or dependency markers
task_format = "{{description}} {{due}} {{scheduled}}"
-- * [ ] Fix the login bug [โฐ2025-12-25] (โฑ๏ธ2025-12-20) `abcd1234`

-- Only the due date
task_format = "{{description}} {{due}}"
-- * [ ] Fix the login bug [โฐ2025-12-25] `abcd1234`

-- Project and tags alongside the usual icons
task_format = "{{description}} {{project}} {{tags}} {{icons}}"
-- * [ ] Fix the login bug work +urgent +backend (โฑ๏ธ2025-12-20) [โฐ2025-12-25] [H๐Ÿ”’] `abcd1234`

-- Your own decoration, using the raw values
task_format = "{{description}} @{{project}} due:{{due.raw}} !{{priority.raw}}"
-- * [ ] Fix the login bug @work due:2025-12-25 !H `abcd1234`

-- A dash bullet, for vaults that use "- [ ]" checkboxes
task_bullet = "-"
-- - [ ] Fix the login bug (โฑ๏ธ2025-12-20) [โฐ2025-12-25] [H๐Ÿ”’] `abcd1234`

Notes

  • {{icons}} is the composition <show_tags> {{completed}} {{scheduled}} {{due}} {{markers}}, where <show_tags> is empty unless show_tags is set, and with the scheduled date left out for completed tasks, where what was planned no longer matters. Listing the placeholders yourself gives you full control of the order; {{scheduled}} on its own always renders when the task has one.
  • {{completed}} renders for completed tasks only. A deleted task carries an end date too, but it did not complete.
  • {{status}}, {{uid}} and the bullet are not placeholders: the checkbox and the uid are always rendered, and the bullet is set with task_bullet. Naming them in task_format, along with any unknown placeholder or modifier, produces a warning at startup (naming the workspace, for a per-workspace format) and renders nothing.

Showing Tags

Tags are not part of the default line: a task can carry many, and they take a lot of room. Set show_tags to the tags you want to see, and {{icons}} shows the ones a task has, before the dates:

require('frontline').setup({
  show_tags = "bug,review,meeting*",
  -- or as a list: show_tags = { "bug", "review", "meeting*" }
})
* [ ] Prepare the demo +review +meeting-weekly [โฐ2025-12-25] [H] `abcd1234`

Each entry is a glob matched against the whole tag:

GlobMatches
bugbug only โ€” not debug, not Bug (matching is case-sensitive)
meeting*meeting, meeting-weekly, meetings
*bugbug, debug
v?v1, v2, but not v10
*every tag

Tags are listed in the task’s own order, each once, in the same form as {{tags}}. show_tags can be set per workspace too, like task_format; set it to "" in a workspace to turn tags off there while they are on globally. The {{tags}} placeholder is not affected: it always lists every tag.

Date Display

Dates are converted from Taskwarrior’s UTC timestamps to your local timezone, and a whole-day date (midnight) is shown as a bare day, without a time:

* [ ] Fix authentication bug (2025-11-15 10:00) [2025-11-20 17:00] `abcd1234`
* [ ] Whole-day deadline [2025-11-20] `abcd1234`

Set relative_dates = true to show due and scheduled dates as today, tomorrow, +3 days, 2 weeks ago and so on. In that format the day alone says nothing about something happening in a few hours, so a date falling today shows its time instead:

* [ ] Dentist [โฐ2pm] `abcd1234`
* [ ] Standup (โฑ๏ธ10am) `abcd1234`
* [ ] Odd time [โฐ11:35am] `abcd1234`
* [ ] Whole-day deadline [โฐtoday] `abcd1234`
* [ ] Not until tomorrow [โฐtomorrow] `abcd1234`

A time on its own always means today. A whole-day (midnight) event has no time to show and keeps saying today.

The โœ… end date of a completed task is the exception: it is a fact to look up rather than something to plan around, so it always shows the ISO day, in either format:

* [x] Shipped it {โœ…2026-08-24} `abcd1234`

Priority Display

Priority is a Taskwarrior UDA, so the set of values and their order is whatever uda.priority.values says. Frontline therefore displays the value itself rather than mapping it to a fixed icon, and it stays correct if you redefine the values:

uda.priority.values=H,M,L,     ->  * [ ] Fix the parser [H๐Ÿ”’] `a1b2c3d4`
uda.priority.values=A,B,,C     ->  * [ ] Fix the parser [A๐Ÿ”’] `a1b2c3d4`

The empty entry marks where tasks with no priority rank. In A,B,,C above, C sorts below a task with no priority at all; sort:priority honours this.

To show something other than the raw value, map it in priority_labels. Pick glyphs of the same width so task lines stay aligned:

require('frontline').setup({
  priority_labels = { H = "โ†‘", M = "-", L = "โ†“" },
})

Values without an entry keep showing as-is.

Automatic Refresh

The plugin automatically refreshes task lists:

  • When you open a Markdown file (BufReadPost)
  • Before you save a Markdown file (BufWritePost)

Manual Refresh

Use the command to manually trigger a refresh:

:FrontlineRefresh

Interactive Task Management

Place your cursor on any task line and use these default keybindings:

KeybindingActionDescription
<leader>tdToggle DoneMark task as complete or reopen it
<leader>tsStart TaskStart working on the task (does nothing if it is already active)
<leader>tSStop TaskStop working on the task (does nothing if it is not active)
<leader>tvView TaskOpen the compact task View (see below)
<leader>taAdd AnnotationAdd a note to the task
<leader>ttAdd TODO AnnotationAdd a note pre-filled with TODO:
<leader>tmModify TaskModify task properties (prompts for input)
<leader>teEdit TaskOpen task in Taskwarrior’s interactive editor
<leader>tnCreate TaskCreate new task with smart context-aware pre-fill
<leader>tBAdd DependencyCreate new task as dependency of current task
<leader>tuUndo TaskUndo last action on task
<leader>tbShow DependenciesShow task dependencies and reverse dependencies
<leader>trShow Blocked TasksShow tasks blocked by this task
<leader>tcCopy TaskCopy the task to the clipboard (see Copy Task Format)
<leader>toOpen URLOpen a URL or file path found in the task’s annotations
<leader>tjCreate NoteCreate a Markdown note linked to the task

Task View

<leader>tv opens a floating window with everything worth knowing about the task under the cursor:

โ•ญโ”€ Task โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ
โ”‚[S] Refactor the annotation shortcuts             `a2f1c3d8` โ”‚
โ”‚H ยท frontline.nvim ยท +nvim +ux ยท urgency 12.4                โ”‚
โ”‚โฑ๏ธ 2026-07-31 (tomorrow) ยท โฐ 2026-08-02 (+3 days)            โ”‚
โ”‚                                                             โ”‚
โ”‚Annotations (3)                                              โ”‚
โ”‚  โ˜ 2026-07-29  TODO: decide the floating window size        โ”‚
โ”‚  โ˜‘ 2026-07-29  DONE: survey existing mappings               โ”‚
โ”‚  โ€ข 2026-07-28  NOTE: "~/notes/frontline-view.md"            โ”‚
โ”‚                                                             โ”‚
โ”‚Blocked by (2 ยท 1 open)                                      โ”‚
โ”‚  โ˜ Design the View layout                      `9b7e0c11`   โ”‚
โ”‚  โ˜‘ Read the mappings module                    `41d0a6f2`   โ”‚
โ”‚Blocking (1)                                                 โ”‚
โ”‚  โ˜ Release v0.5.0                              `77aa31b9`   โ”‚
โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ

The layout is dense on purpose: the status marker on the title line already says pending/started/completed, every date shares one line, and project, tags, priority and urgency share another. Each element appears only when it is set, so most tasks are far shorter than the one above:

โ•ญโ”€ Task โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฎ
โ”‚[ ] Buy milk                       `3fa9c201` โ”‚
โ”‚home ยท urgency 1.2                            โ”‚
โ”‚โฐ 2026-07-31 (tomorrow)                       โ”‚
โ•ฐโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•ฏ

A task with nothing but a description renders as a single line.

The window is sized to its content and grows with the terminal: the four size options are read as a fraction of the screen when they are 1 or less, and as absolute columns or rows otherwise. min_height defaults to 70% of the screen so the window keeps a steady size whether or not the content fills it โ€” a short task in a snug window reads as if something has scrolled out of sight. max_width keeps long annotations from stretching across a wide monitor, and max_height decides when a task with many annotations starts to scroll instead of growing.

Highlight groups

Each element of the View has its own highlight group, so a colorscheme or your own config can restyle any one of them. All are defined as links with default = true, so an existing definition always wins:

GroupLinks toApplies to
FrontlineViewDescriptionTitleThe task description on the title line
FrontlineViewHashCommentShort hashes, on the title and dependency lines
FrontlineViewPriorityStatementThe priority value
FrontlineViewProjectDirectoryThe project name
FrontlineViewTagsSpecialThe +tag list
FrontlineViewRecurSpecialThe recurrence period
FrontlineViewWaitingCommentThe waiting marker
FrontlineViewUrgencyCommentThe urgency value
FrontlineViewSeparatorCommentThe ยท between fields
FrontlineViewOverdueWarningMsgA due date in the past
FrontlineViewSectionTitleThe Annotations / Blocked by / Blocking headers
FrontlineViewTodoWarningMsgThe โ˜ marker of an open annotation
FrontlineViewDoneCommentA completed annotation
FrontlineViewAnnotationDateCommentThe date prefix on an annotation
FrontlineViewDepOpenNormalAn incomplete dependency
FrontlineViewDepDoneCommentA completed dependency
vim.api.nvim_set_hl(0, "FrontlineViewProject", { fg = "#7aa2f7", bold = true })
vim.api.nvim_set_hl(0, "FrontlineViewTags", { fg = "#9ece6a", italic = true })

Inside the View:

KeyAction
q, <Esc>Close the View
aAdd an annotation
xToggle the annotation under the cursor between TODO:/DONE: (or [ ]/[x])
dToggle done
sToggle started
eEdit the task in Taskwarrior’s interactive editor, the same one <leader>te opens
<CR>On an annotation: open its URL or file path. On a dependency: open that task’s View
yOn an annotation: copy its URL or file path to the clipboard (+) and unnamed register, prompting when there is more than one
<BS>Go back to the previous task after drilling into a dependency
?Show these keys

Only q and <Esc> close the window. Every other key re-renders the View in place, so actions can be repeated without reopening it โ€” add three annotations in a row, tick off several TODOs, or start and stop a task while watching its urgency change. Files opened with <CR> load into the window the View was opened from and are waiting behind it once you close the View.

e is the exception: Taskwarrior’s editor needs a full window, so the View steps aside, the editor takes over the window the View was opened from, and the View comes back on the same task once you write and quit โ€” including the drill-down history, so <BS> still walks back out of the dependencies you followed to get there. Cancelling the edit brings the View back untouched.

x is the quickest way to clear the outstanding TODOs that block task completion when require_todo_annotations_done is enabled. Taskwarrior has no “edit annotation” command, so the toggle removes the annotation and re-adds it with the new text โ€” the annotation’s timestamp is reset as a result.

Smart Task Creation with Autocomplete

The plugin provides intelligent autocomplete when creating tasks (<leader>tn) or adding dependencies (<leader>tB).

Autocomplete Features:

  • Projects (project:): Suggests existing projects from your Taskwarrior database
  • Tags (+): Suggests existing tags (excluding virtual tags like PENDING, COMPLETED)
  • Dates (due:, scheduled:): Suggests common date shortcuts (today, tomorrow, eow, 1w, etc.)
  • Workspaces (@): Suggests configured workspaces
  • Priority (priority:): Suggests the values configured in Taskwarrior (H, M, L by default)

How to Use Autocomplete:

  1. Press <leader>tn to create a new task (opens command-line mode with :FrontlineCreateTask)
  2. The command line will be pre-filled with context-aware attributes if available
  3. Type your task description and/or attributes (e.g., project:, +, due:, @)
  4. Press <Tab> to trigger autocomplete suggestions
  5. Use <Tab> and <Shift-Tab> to cycle through suggestions, or continue typing to filter
  6. Press <Enter> to execute the command and create the task
  7. Press <Ctrl-c> or <Esc> to cancel

Examples:

# After pressing <leader>tn:
:FrontlineCreateTask Fix bug project:<Tab>
  โ†’ Suggests: backend, frontend, mobile, web

:FrontlineCreateTask Update docs +<Tab>
  โ†’ Suggests: bug, feature, documentation, urgent

:FrontlineCreateTask Review PR due:<Tab>
  โ†’ Suggests: today, tomorrow, eow, 1w, 2w, 1m

:FrontlineCreateTask @<Tab>
  โ†’ Suggests: personal, work

Alternative: Use Commands Directly

You can also type the commands directly in command mode:

:FrontlineCreateTask Fix authentication bug project:backend priority:H due:tomorrow
:FrontlineCreateDependency Setup database project:backend

Smart Context-Aware Pre-fill:

  • When creating from a task line: inherits workspace, project, due date, and scheduled date
  • When creating from a header: inherits all filters from the header query
  • The command line opens pre-filled with these context attributes
  • Project and tags are cached for 5 minutes to improve performance

Examples:

" On a task line, press <leader>td to mark it done
" Press <leader>td again to reopen it

" Press <leader>ts to start working on a task
" Press <leader>ts again to stop

" Press <leader>tm and enter: priority:H due:tomorrow
" Press <leader>ta and enter: "Started working on this"

" Press <leader>tv to see the whole task: dates, tags, annotations, dependencies

" Press <leader>te to open the full Taskwarrior editor in a split
" Edit all task properties, save and close to update

After any modification, the task list automatically refreshes to show the updated state.

Configuration

require('frontline').setup({
  newlines_after_tasks = 2,  -- Number of blank lines after task lists (default: 2)
  workspaces = {
    personal = "~/.config/taskwarrior/personal/.taskrc",
    work = "~/.config/taskwarrior/work/.taskrc",
  },
  default_workspace = "personal",  -- Default workspace when none specified (nil = system taskwarrior)
  enable_reverse_dependencies = true,  -- Show anchor icon for tasks blocking others (default: true)
  reverse_dependencies_warn_threshold = 1000,  -- Warn if queries take > 1000ms (default: 1000)
  view = {
    min_width = 0.5,          -- Narrowest the View gets
    max_width = 0.9,          -- Widest the View gets
    min_height = 0.7,         -- Shortest the View gets
    max_height = 0.85,        -- Tallest the View gets
    border = "rounded",       -- Any border accepted by nvim_open_win
    show_urgency = true,      -- Show urgency on the attribute line
    show_dependencies = true, -- Show the "Blocked by" / "Blocking" sections
    annotation_dates = true,  -- Prefix annotations with their date
  },
  mappings = {
    toggle_done = "<leader>td",      -- Toggle task done/undone
    start_task = "<leader>ts",       -- Start task (no-op if already active)
    stop_task = "<leader>tS",        -- Stop task (no-op if not active)
    view_task = "<leader>tv",        -- Open the task View
    add_annotation = "<leader>ta",   -- Add task annotation
    modify_task = "<leader>tm",      -- Modify task properties
    edit_task = "<leader>te",        -- Edit task in Taskwarrior editor
    show_blocking_dependencies = "<leader>tb",  -- Show dependencies
    add_dependency = "<leader>tB",   -- Add task as dependency
    undo_task = "<leader>tu",        -- Undo last action
    create_task = "<leader>tn",      -- Create new task
  },
})

Breaking changes

<leader>ta used to list a task’s annotations and <leader>tA added one. Since annotations are created far more often than they are listed, the two have been reworked:

  • <leader>ta now adds an annotation (this matches what this README has always documented).
  • <leader>tA is no longer bound by default.
  • <leader>tv opens the task View, which shows annotations along with the rest of the task.

The standalone annotation list is still available as mappings.show_annotations; it simply has no default binding any more. If you bind it back to <leader>ta, your binding wins over add_annotation and the plugin warns once at startup.

require('frontline').setup({
  mappings = {
    show_annotations = "<leader>tA",  -- keep the old list on a different key
  },
})

Available Options

OptionTypeDefaultDescription
newlines_after_tasksnumber2Number of blank lines to add after each task list
convert_dates_to_localbooleantrueConvert Taskwarrior’s UTC timestamps to the local timezone
relative_datesbooleanfalseShow due/scheduled dates as tomorrow, +3 days, 2 weeks ago, and today’s dates as their time (2pm). See Date Display above.
workspacestable{}Map of workspace names to Taskwarrior rc file paths
default_workspacestringnilDefault workspace name (nil uses system taskwarrior)
enable_reverse_dependenciesbooleantrueEnable reverse dependency tracking (โš“ icon and “tasks this task is blocking” view)
reverse_dependencies_warn_thresholdnumber1000Warn if reverse dependency queries take longer than this (in milliseconds). Set to 0 to disable warnings.
default_sorttable{ field = "urgency", reverse = false }Default sort for all views. field can be urgency, priority, due, scheduled, completed, or project. Set reverse = true to flip the order.
copy_task_formatstring"{{description}}"Template for the <leader>tc copy-to-clipboard action. See Copy Task Format below.
custom_actionstable{}Your own mappings that run a shell command on the task under the cursor. See Custom Actions below.
task_formatstring"{{description}} {{icons}}"Template for each task line in a filter view. Overridable per workspace. See Task Format above.
show_tagsstring or listnilTags shown in {{icons}}, as globs ("bug,review,meeting*", "*" for all). Disabled when unset. Overridable per workspace. See Showing Tags above.
task_bulletstring"*"Markdown list bullet each task line starts with ("-", "+", or "" for none). Overridable per workspace.
priority_labelstable{}Text shown for each priority value. Empty means the value itself is displayed. See Priority Display below.
notes_directorystringnilDirectory where task notes are created (nil = current working directory). Overridden per workspace.
note_templatestringnilMarkdown file used as the note template (nil = built-in template). See Task Notes below.
view.min_widthnumber0.5Narrowest the task View gets
view.max_widthnumber0.9Widest the task View gets
view.min_heightnumber0.7Shortest the task View gets
view.max_heightnumber0.85Tallest the task View gets
view.borderstring"rounded"Border style for the task View window
view.show_urgencybooleantrueShow urgency on the View’s attribute line
view.show_dependenciesbooleantrueShow the “Blocked by” / “Blocking” sections in the View
view.annotation_datesbooleantruePrefix annotations in the View with their date
mappings.toggle_donestring"<leader>td"Keybinding to toggle task done/undone
mappings.start_taskstring"<leader>ts"Keybinding to start the task; reports instead if it is already active
mappings.stop_taskstring"<leader>tS"Keybinding to stop the task; reports instead if it is not active
mappings.toggle_startedstringnilKeybinding to toggle started/stopped (no default; see below)
mappings.view_taskstring"<leader>tv"Keybinding to open the task View
mappings.modify_taskstring"<leader>tm"Keybinding to modify task
mappings.add_annotationstring"<leader>ta"Keybinding to add annotation
mappings.show_annotationsstringnilKeybinding to list annotations only (no default; the View covers this)
mappings.add_todo_annotationstring"<leader>tt"Keybinding to add an annotation pre-filled with TODO:
mappings.edit_taskstring"<leader>te"Keybinding to edit task in Taskwarrior editor
mappings.show_blocking_dependenciesstring"<leader>tb"Keybinding to show dependencies (forward and reverse)
mappings.add_dependencystring"<leader>tB"Keybinding to add task as dependency
mappings.undo_taskstring"<leader>tu"Keybinding to undo last action
mappings.create_taskstring"<leader>tn"Keybinding to create new task

Note: Set any mapping to false to disable it:

require('frontline').setup({
  mappings = {
    toggle_done = "<leader>td",
    stop_task = false,  -- Disable this mapping
    modify_task = "<leader>tm",
    add_annotation = "<leader>ta",
  },
})

Starting and stopping tasks

Start and stop are separate keys rather than one toggle: in a regular markdown note you cannot see whether a task is active, so a toggle cannot tell you what it is about to do. Both keys are safe to press again: <leader>ts on an active task only reports Already active since 10:32: <description>, and <leader>tS on an inactive one reports Not active: <description>. When they do act, the message names the task, and stopping also shows how long it was active: โ–  Stopped: Fix login bug (active 42m).

To get the old single-key toggle back, bind toggle_started yourself (it takes precedence over start_task if both use the same key):

require('frontline').setup({
  mappings = {
    toggle_started = "<leader>ts",
    start_task = false,
    stop_task = false,
  },
})

In the task View, s still toggles, since the View shows the task’s state.

Copy Task Format

The copy_task_format option controls what gets copied to the clipboard when you press <leader>tc. It uses a Jinja-like {{placeholder}} syntax:

require('frontline').setup({
  -- Examples:
  copy_task_format = "{{description}}",                                   -- default
  copy_task_format = "* [ ] {{description}}",                             -- bullet + checkbox
  copy_task_format = "* [ ] {{description}} +{{project}} due:{{due}}",    -- full detail
  copy_task_format = "{{description}} {{tags}}",                          -- with tags
  copy_task_format = "{{description}} `{{short_uuid}}`",                  -- with short hash
})

Available placeholders:

PlaceholderDescriptionExample
{{description}}Task descriptionFix the login bug
{{uuid}}Full UUIDabcdef12-3456-...
{{short_uuid}}First 8 chars of UUIDabcdef12
{{status}}Task statuspending
{{project}}Project namework
{{priority}}Priority valueH, M, or L by default
{{tags}}Space-separated tagsurgent backend
{{due}}Due date2025-12-25 10:30
{{scheduled}}Scheduled date2025-12-20
{{urgency}}Urgency score15.5

Empty placeholders are replaced with an empty string and trailing whitespace is trimmed.

Custom Actions

custom_actions adds your own mappings that run a shell command on the task under the cursor. Use them for anything <leader>tc doesn’t cover: another clipboard tool, a second copy format, a notification, a script of your own.

require('frontline').setup({
  custom_actions = {
    -- Copy "description tags" with wl-copy
    { key = "<leader>tca", desc = "Copy with tags", cmd = "wl-copy", input = "{{description}} {{tags}}" },
    -- Same thing on X11
    { key = "<leader>tcx", desc = "Copy (xclip)", cmd = "xclip -selection clipboard", input = "{{description}}" },
    -- Placeholders can go straight into the command too
    { key = "<leader>tN", desc = "Notify", cmd = "notify-send {{project}} {{description}}", notify = false },
    -- Run your own script
    { key = "<leader>tS", desc = "Send to Slack", cmd = "~/bin/slack-task {{short_uuid}}" },
  },
})

Each entry takes:

FieldRequiredDescription
keyyesNormal-mode key sequence, bound in Markdown buffers like the built-in mappings
cmdyesShell command, run through Neovim’s 'shell'. {{placeholders}} in it are replaced by shell-escaped values
inputnoTemplate rendered like copy_task_format and written to the command’s stdin
descnoDescription shown in :map / which-key and in the notifications (defaults to cmd)
notifynoSet to false to skip the success notification. Failures are always reported

Placeholders are the same as for Copy Task Format.

Quoting: every placeholder in cmd is shell-escaped on its own, so a description containing quotes, $ or backticks is passed as plain text and never run by the shell. Because of that, don’t wrap placeholders in quotes yourself: write notify-send {{description}}, not notify-send "{{description}}". To pass several fields as one piece of text, put them in input and let the command read stdin: cmd = "wl-copy", input = "{{description}} {{tags}}", not cmd = 'echo "{{description}} {{tags}}" | wl-copy'.

The command runs in the background, so programs that keep running (such as wl-copy) don’t freeze the editor. When it finishes, frontline shows its output, or “done” if there was none. If it exits with an error, frontline shows the exit code and stderr. Entries without a key or cmd are skipped with a warning at setup().

Task Notes

<leader>tj creates a Markdown note for the task under the cursor, links it back to the task with a NOTE: "path" annotation, and opens it. The file is created in notes_directory (or the current working directory), and the proposed path can be edited in the prompt.

By default the note uses the built-in template:

---
task: `abcdef12`
---

# Fix the login bug

Set note_template to use one of your own templates instead โ€” typically a file already living in your vault:

require('frontline').setup({
  notes_directory = "~/notes",
  note_template = "templates/task.md",  -- relative paths resolve inside notes_directory
  -- note_template = "~/notes/templates/task.md",  -- absolute paths work too

  -- Both options can also be set per workspace:
  workspaces = {
    work = {
      rc = "~/.config/taskwarrior/work/.taskrc",
      notes_directory = "~/notes/work",
      note_template = "templates/work-task.md",
    },
  },
})

The per-workspace value wins over the global one, which wins over the built-in template. If the configured file cannot be read, frontline warns and falls back to the built-in template rather than failing the note creation.

The task: metadata is always added by frontline. A template โ€” built-in or your own โ€” never has to (and never can) provide the link to Taskwarrior:

  • No frontmatter in the template โ†’ frontline prepends a block containing task:.
  • Frontmatter present โ†’ task: is added to it, keeping your other keys.
  • A task: key already in the frontmatter โ†’ frontline overwrites its value.

So a template like this:

---
tags: [task, work]
created: {{date}}
---

# {{title}}

## Context

## Next steps

produces:

---
tags: [task, work]
created: 2025-12-25
task: `abcdef12`
---

# Fix the login bug

## Context

## Next steps

Templates support the same placeholders as Copy Task Format, plus:

PlaceholderDescriptionExample
{{title}}Task description (alias of {{description}})Fix the login bug
{{date}}Current date2025-12-25
{{time}}Current time10:30

Unlike the copy format, placeholders frontline does not recognise are left in the note untouched, so templates shared with other plugins keep working.

Requirements

  • Neovim 0.5+
  • Taskwarrior installed and configured
  • Tasks in your Taskwarrior database

Local Testing

Test the plugin without installing it:

cd /path/to/frontline.nvim
nvim -u test_config.lua test.md

Example Markdown File

# Today's Tasks | +today status:pending

# Work Project | project:work

# High Priority | priority:H status:pending

When opened in Neovim, each section will automatically populate with matching tasks.

Compatibility

This plugin aims for compatibility with Taskwiki’s header query format.

Development

Running Tests

nvim --headless -c "PlenaryBustedDirectory tests/"

All tests should pass (33/33):

  • Integration tests: 5
  • Parser tests: 6
  • Task Client tests: 4
  • Renderer tests: 18

License

MIT

Contributing

Contributions welcome! Please feel free to submit a Pull Request.