*pending.txt* Buffer-centric task management for Neovim Author: Barrett Ruth License: MIT ============================================================================== INTRODUCTION *pending.nvim* pending.nvim is a buffer-centric task manager for Neovim. Tasks live in a plain, editable buffer — add with `o`, delete with `dd`, reorder with `dd`/`p`, rename by typing. Writing the buffer with `:w` computes a diff against the JSON store and applies only the changes. No floating windows, no special UI, no abstraction between you and your tasks. The buffer looks like this: > School ! Read chapter 5 Feb 28 Submit homework Feb 25 Errands Buy groceries Mar 01 Clean apartment < Category headers sit at column 0. Tasks are indented two spaces below them. `!` marks a priority task. Due dates appear as right-aligned virtual text. Completed tasks are rendered with strikethrough. Task IDs are embedded as concealed tokens and are never visible during editing. Features: ~ - Oil-style buffer editing: standard Vim motions for all task operations - Inline metadata syntax: `due:`, `cat:`, and `rec:` tokens parsed on `:w` - Relative date input: `today`, `tomorrow`, `+Nd`, `+Nw`, `+Nm`, weekday names, month names, ordinals, and more - Recurring tasks with automatic next-date spawning on completion - Two views: category (default) and queue (priority-sorted flat list) - Multi-level undo (up to 20 `:w` saves, persisted across sessions) - Quick-add from the command line with `:Pending add` - Quickfix list of overdue/due-today tasks via `:Pending due` - Configurable category folds (`zc`/`zo`) with custom foldtext - Omnifunc completion for `cat:`, `due:`, and `rec:` tokens (`

`) - Google Calendar one-way push via OAuth PKCE - Google Tasks bidirectional sync via OAuth PKCE ============================================================================== CONTENTS *pending-contents* 1. Introduction ............................................. |pending.nvim| 2. Requirements ..................................... |pending-requirements| 3. Install ............................................... |pending-install| 4. Usage ................................................... |pending-usage| 5. Commands .............................................. |pending-commands| 6. Mappings .............................................. |pending-mappings| 7. Views ................................................... |pending-views| 8. Filters ............................................... |pending-filters| 9. Inline Metadata ....................................... |pending-metadata| 10. Date Input .............................................. |pending-dates| 11. Recurrence ......................................... |pending-recurrence| 12. Configuration ........................................... |pending-config| 13. Store Resolution .......................... |pending-store-resolution| 14. Highlight Groups .................................... |pending-highlights| 15. Lua API ................................................... |pending-api| 16. Recipes ............................................... |pending-recipes| 17. Sync Backends ................................... |pending-sync-backend| 18. Google Calendar .......................................... |pending-gcal| 19. Google Tasks ............................................ |pending-gtasks| 20. Google Authentication ......................... |pending-google-auth| 21. Data Format .............................................. |pending-data| 22. Health Check ........................................... |pending-health| ============================================================================== REQUIREMENTS *pending-requirements* - Neovim 0.10+ - No external dependencies for local use - `curl` is required for the `gcal` and `gtasks` sync backends ============================================================================== INSTALL *pending-install* Install with lazy.nvim: >lua { 'barrettruth/pending.nvim' } < Install with luarocks: >vim luarocks install pending.nvim < No `setup()` call is needed. The plugin loads automatically and works with defaults. To customize behavior, set |vim.g.pending| before the plugin loads. See |pending-config|. ============================================================================== USAGE *pending-usage* Open the task buffer: >vim :Pending < The buffer named `pending://` opens in the current window. From there, use standard Vim editing: - `o` / `O` to add a new task line under or above the cursor - `dd` to remove a task (deletion is applied on `:w`) - `dd` + `p` to reorder tasks (pasted tasks receive new IDs) - `:w` to save — all additions, deletions, and edits are diffed against the store and committed atomically Buffer-local keys are set automatically when the buffer opens. See |pending-mappings| for the full list. The buffer uses `buftype=acwrite` so `:w` always routes through pending.nvim's write handler rather than writing to disk directly. The `pending://` buffer persists across window switches; reopening with `:Pending` focuses the existing window if one is open. The buffer is automatically reloaded from disk when entered unmodified. ============================================================================== COMMANDS *pending-commands* *:Pending* :Pending Open the task buffer. If the buffer is already displayed in a window, focus that window. Equivalent to |(pending-open)|. *:Pending-add* :Pending add {text} Quick-add a task without opening the buffer. Inline metadata tokens in {text} are parsed exactly as they are in the buffer. A `Category: ` prefix (uppercase first letter, colon, space) assigns the category directly: >vim :Pending add Buy groceries due:2026-03-15 :Pending add School: Submit homework :Pending add Errands: Pick up dry cleaning due:fri :Pending add Work: standup due:tomorrow rec:weekdays < If the buffer is currently open it is re-rendered after the add. *:Pending-archive* :Pending archive [{days}] Permanently remove done and deleted tasks whose completion timestamp is older than {days} days. {days} defaults to 30 if not provided. >vim :Pending archive " remove tasks completed more than 30 days ago :Pending archive 7 " remove tasks completed more than 7 days ago < *:Pending-due* :Pending due Populate the quickfix list with all tasks that are overdue or due today. Open the list with |:copen| to navigate to each task's category. *:Pending-auth* :Pending auth Authorize pending.nvim to access Google services (Tasks and Calendar). Prompts with |vim.ui.select| to choose gtasks, gcal, or both — all options run the same combined OAuth flow and produce a single shared token file. If no credentials are configured, the setup wizard runs first to collect a client ID and secret. See |pending-google-auth| for full details. *:Pending-gtasks* :Pending gtasks {action} Run a Google Tasks action. An explicit action is required. Actions: ~ `sync` Push local changes then pull remote changes. `push` Push local changes to Google Tasks only. `pull` Pull remote changes from Google Tasks only. Examples: >vim :Pending gtasks sync " push then pull :Pending gtasks push " push local → Google Tasks :Pending gtasks pull " pull Google Tasks → local < Tab completion after `:Pending gtasks ` lists available actions. See |pending-gtasks| for full details. *:Pending-gcal* :Pending gcal {action} Run a Google Calendar action. An explicit action is required. Actions: ~ `push` Push tasks with due dates to Google Calendar. Examples: >vim :Pending gcal push " push to Google Calendar < Tab completion after `:Pending gcal ` lists available actions. See |pending-gcal| for full details. *:Pending-filter* :Pending filter {predicates} Apply a filter to the task buffer. {predicates} is a space-separated list of one or more predicate tokens. Only tasks matching all predicates (AND semantics) are shown. Hidden tasks are not deleted — they are preserved in the store and reappear when the filter is cleared. >vim :Pending filter cat:Work :Pending filter overdue :Pending filter cat:Work overdue :Pending filter priority :Pending filter clear < When a filter is active the buffer's first line shows: > FILTER: cat:Work overdue < The user can edit this line inline and `:w` to change the active filter. Deleting the `FILTER:` line entirely and saving clears the filter. `:Pending filter clear` also clears the filter programmatically. Tab completion after `:Pending filter ` lists available predicates and category values. Already-used predicates are excluded from completions. See |pending-filters| for the full list of supported predicates. *:Pending-edit* :Pending edit {id} [{operations}] Edit metadata on an existing task without opening the buffer. {id} is the numeric task ID. One or more operations follow: >vim :Pending edit 5 due:tomorrow cat:Work +! :Pending edit 5 -due -cat -rec :Pending edit 5 rec:!weekly due:fri < Operations: ~ `due:` Set due date (accepts all |pending-dates| vocabulary). `cat:` Set category. `rec:` Set recurrence (prefix `!` for completion-based). `+!` Add priority flag. `-!` Remove priority flag. `-due` Clear due date. `-cat` Clear category. `-rec` Clear recurrence. Tab completion is available for IDs, field names, date values, categories, and recurrence patterns. *:Pending-undo* :Pending undo Undo the last `:w` save, restoring the task store to its previous state. Equivalent to the `U` buffer-local key (see |pending-mappings|). Up to 20 levels of undo are persisted across sessions. *:Pending-init* :Pending init Create a project-local `.pending.json` file in the current working directory. After creation, `:Pending` will use this file instead of the global store (see |pending-store-resolution|). Errors if `.pending.json` already exists in the current directory. *:PendingTab* :PendingTab Open the task buffer in a new tab. ============================================================================== MAPPINGS *pending-mappings* The following keys are set buffer-locally when the task buffer opens. They are active only in the `pending://` buffer. Buffer-local keys are configured via the `keymaps` table in |pending-config|. The defaults are shown below. Set any key to `false` to disable it. Default buffer-local keys: ~ Key Action ~ ------- ------------------------------------------------ `q` Close the task buffer (`close`) `` Toggle complete / uncomplete (`toggle`) `!` Toggle the priority flag (`priority`) `D` Prompt for a due date (`date`) `F` Prompt for filter predicates (`filter`) `` Switch between category / queue view (`view`) `U` Undo the last `:w` save (`undo`) `o` Insert a new task line below (`open_line`) `O` Insert a new task line above (`open_line_above`) `zc` Fold the current category section (requires `folding`) `zo` Unfold the current category section (requires `folding`) Text objects (operator-pending and visual): ~ Key Action ~ ------- ------------------------------------------------ `at` Select the current task line (`a_task`) `it` Select the task description only (`i_task`) `aC` Select a category: header + tasks + blanks (`a_category`) `iC` Select inner category: tasks only (`i_category`) `at` supports count: `d3at` deletes three consecutive tasks. `it` selects the description text between the checkbox prefix and trailing metadata tokens (`due:`, `cat:`, `rec:`), making `cit` the natural way to retype a task description without touching its metadata. `aC` and `iC` are no-ops in the queue view (no headers to delimit). Motions (normal, visual, operator-pending): ~ Key Action ~ ------- ------------------------------------------------ `]]` Jump to the next category header (`next_header`) `[[` Jump to the previous category header (`prev_header`) `]t` Jump to the next task line (`next_task`) `[t` Jump to the previous task line (`prev_task`) All motions support count: `3]]` jumps three headers forward. `]]` and `[[` are no-ops in the queue view. `]t` and `[t` work in both views. `dd`, `p`, `P`, and `:w` work as standard Vim operations. *(pending-open)* (pending-open) Open the task buffer. Maps to |:Pending| with no arguments. *(pending-close)* (pending-close) Close the task buffer window. *(pending-toggle)* (pending-toggle) Toggle complete / uncomplete for the task under the cursor. *(pending-priority)* (pending-priority) Toggle the priority flag for the task under the cursor. *(pending-date)* (pending-date) Prompt for a due date for the task under the cursor. *(pending-view)* (pending-view) Switch between category view and priority view. *(pending-undo)* (pending-undo) Undo the last `:w` save. *(pending-filter)* (pending-filter) Prompt for filter predicates via |vim.ui.input|. *(pending-open-line)* (pending-open-line) Insert a correctly-formatted blank task line below the cursor. *(pending-open-line-above)* (pending-open-line-above) Insert a correctly-formatted blank task line above the cursor. *(pending-a-task)* (pending-a-task) Select the current task line (linewise). Supports count. *(pending-i-task)* (pending-i-task) Select the task description text (characterwise). *(pending-a-category)* (pending-a-category) Select a full category section: header, tasks, and surrounding blanks. *(pending-i-category)* (pending-i-category) Select tasks within a category, excluding the header and blanks. *(pending-next-header)* (pending-next-header) Jump to the next category header. Supports count. *(pending-prev-header)* (pending-prev-header) Jump to the previous category header. Supports count. *(pending-next-task)* (pending-next-task) Jump to the next task line, skipping headers and blanks. *(pending-prev-task)* (pending-prev-task) Jump to the previous task line, skipping headers and blanks. (pending-tab) *(pending-tab)* Open the task buffer in a new tab. See |:PendingTab|. Example configuration: >lua vim.keymap.set('n', 't', '(pending-open)') vim.keymap.set('n', 'T', '(pending-toggle)') < ============================================================================== VIEWS *pending-views* Two views are available. Switch with `` or |(pending-view)|. Category view (default): ~ *pending-view-category* Tasks are grouped under their category header. Categories appear in the order tasks were added unless `category_order` is set (see |pending-config|). Blank lines separate categories. Within each category, pending tasks appear before done tasks. Priority tasks (`!`) are sorted first within each group. The within-category sort order is configurable via `category_sort` (see |pending-sort|). Category sections are foldable with `zc` and `zo`. Queue view: ~ *pending-view-queue* A flat list of all tasks sorted by priority, then by due date (tasks without a due date sort last), then by internal order. Done tasks appear after all pending tasks. The sort order is configurable via `queue_sort` (see |pending-sort|). Category names are shown as right-aligned virtual text alongside the due date virtual text so tasks remain identifiable across categories. The buffer is named `pending://queue`. ============================================================================== FILTERS *pending-filters* Filters narrow the task buffer to a subset of tasks without deleting any data. Hidden tasks are preserved in the store and reappear when the filter is cleared. Filter state is session-local — it does not persist across Neovim restarts. Set a filter with |:Pending-filter|, the `F` buffer key, or by editing the `FILTER:` line: >vim :Pending filter cat:Work overdue < Multiple predicates are separated by spaces and combined with AND logic — a task must match every predicate to be shown. Available predicates: ~ `cat:X` Show only tasks whose category is exactly `X`. Tasks with no category (assigned to `default_category`) are hidden unless `default_category` matches `X`. `overdue` Show only pending tasks with a due date strictly before today. `today` Show only pending tasks with a due date equal to today. `priority` Show only tasks with priority > 0 (the `!` marker). `clear` Special value for |:Pending-filter| — clears the active filter and shows all tasks. FILTER: line: ~ *pending-filter-line* When a filter is active, the first line of the task buffer is: > FILTER: cat:Work overdue < This line is editable. Write the buffer with `:w` to apply the updated predicates. Deleting the `FILTER:` line and saving clears the filter. The line is highlighted with |PendingFilter| and does not appear in the stored task data. ============================================================================== INLINE METADATA *pending-metadata* Metadata tokens may be appended to any task line before saving. Tokens are parsed from the right and consumed until a non-metadata token is reached. Supported tokens: ~ `due:YYYY-MM-DD` Set a due date using an absolute date. `due:` Resolve a named date (see |pending-dates| below). `cat:Name` Move the task to the named category on save. `rec:` Set a recurrence rule (see |pending-recurrence|). The token name for due dates defaults to `due` and is configurable via `date_syntax` in |pending-config|. The token name for recurrence defaults to `rec` and is configurable via `recur_syntax`. Example: > Buy milk due:2026-03-15 cat:Errands Take out trash due:monday rec:weekly < On `:w`, the description becomes `Buy milk`, the due date is stored as `2026-03-15` and rendered as right-aligned virtual text, and the task is placed under the `Errands` category header. Parsing stops at the first token that is not a recognised metadata token. Repeated tokens of the same type also stop parsing — only one `due:`, one `cat:`, and one `rec:` per task line are consumed. Omnifunc completion is available for `due:`, `cat:`, and `rec:` token types. In insert mode, type the token prefix and press `

` to see suggestions. ============================================================================== DATE INPUT *pending-dates* Named dates can be used anywhere a date is accepted: the `due:` inline token, the `D` prompt, and `:Pending add`. Token Resolves to ~ ----- ----------- `today` Today's date `tomorrow` Tomorrow's date `yesterday` Yesterday's date `eod` Today (end of day semantics) `+Nd` N days from today (e.g. `+3d`) `+Nw` N weeks from today (e.g. `+2w`) `+Nm` N months from today (e.g. `+1m`) `-Nd` N days ago (e.g. `-2d`) `-Nw` N weeks ago (e.g. `-1w`) `mon`–`sun` Next occurrence of that weekday `jan`–`dec` 1st of next occurrence of that month `1st`–`31st` Next occurrence of that day-of-month `sow` / `eow` Monday / Sunday of current week `som` / `eom` First / last day of current month `soq` / `eoq` First / last day of current quarter `soy` / `eoy` January 1 / December 31 of current year `later` / `someday` Sentinel date (default: `9999-12-30`) Custom formats: ~ *pending-dates-custom* Additional input formats can be configured via `input_date_formats` in |pending-config|. They are tried in order after all built-in keywords fail. See |pending-input-formats| for supported specifiers and examples. Time suffix: ~ *pending-dates-time* Any named date or absolute date accepts an `@` time suffix. Supported formats: `HH:MM` (24h), `H:MM`, bare hour (`9`, `14`), and am/pm (`2pm`, `9:30am`, `12am`). All forms are normalized to `HH:MM` on save. > due:tomorrow@2pm " tomorrow at 14:00 due:fri@9 " next Friday at 09:00 due:+1w@17:00 " one week from today at 17:00 due:tomorrow@9:30am " tomorrow at 09:30 due:2026-03-15@08:00 " absolute date with time due:2026-03-15T14:30 " ISO 8601 datetime (also accepted) < Tasks with a time component are not considered overdue until after the specified time. The time is displayed alongside the date in virtual text and preserved across recurrence advances. ============================================================================== RECURRENCE *pending-recurrence* Tasks can recur on a schedule. Add a `rec:` token to set recurrence: > - [ ] Take out trash due:monday rec:weekly - [ ] Pay rent due:2026-03-01 rec:monthly - [ ] Standup due:tomorrow rec:weekdays < When a recurring task is marked done with ``: 1. The current task stays as done (preserving history). 2. A new pending task is created with the same description, category, priority, and recurrence — with the due date advanced to the next occurrence. Shorthand patterns: ~ Pattern Meaning ~ ------- ------- `daily` Every day `weekdays` Monday through Friday `weekly` Every week `biweekly` Every 2 weeks (alias: `2w`) `monthly` Every month `quarterly` Every 3 months (alias: `3m`) `yearly` Every year (alias: `annual`) `Nd` Every N days (e.g. `3d`) `Nw` Every N weeks (e.g. `2w`) `Nm` Every N months (e.g. `6m`) `Ny` Every N years (e.g. `2y`) For patterns the shorthand cannot express, use a raw RRULE fragment: > rec:FREQ=MONTHLY;BYDAY=1MO < Completion-based recurrence: ~ *pending-recur-completion* By default, recurrence is schedule-based: the next due date advances from the original schedule, skipping to the next future occurrence. Prefix the pattern with `!` for completion-based mode, where the next due date advances from the completion date: > rec:!weekly < Schedule-based is like org-mode `++`; completion-based is like `.+`. Google Calendar: ~ Recurrence patterns map directly to iCalendar RRULE strings for future GCal sync support. Completion-based recurrence cannot be synced (it is inherently local). ============================================================================== CONFIGURATION *pending-config* Configuration is done via `vim.g.pending`. Set this before the plugin loads: >lua vim.g.pending = { data_path = vim.fn.stdpath('data') .. '/pending/tasks.json', default_view = 'category', default_category = 'Todo', date_format = '%b %d', date_syntax = 'due', recur_syntax = 'rec', someday_date = '9999-12-30', folding = true, category_order = {}, keymaps = { close = 'q', toggle = '', view = '', priority = '!', date = 'D', undo = 'U', filter = 'F', open_line = 'o', open_line_above = 'O', a_task = 'at', i_task = 'it', a_category = 'aC', i_category = 'iC', next_header = ']]', prev_header = '[[', next_task = ']t', prev_task = '[t', }, sync = { gcal = {}, gtasks = {}, }, } < All fields are optional. Unset fields use the defaults shown above. *pending.Config* Fields: ~ {data_path} (string) Path to the global JSON file where tasks are stored. Default: `stdpath('data') .. '/pending/tasks.json'`. The directory is created automatically on first save. See |pending-store-resolution| for how the active store is chosen at runtime. {default_view} ('category'|'priority', default: 'category') The view to use when the buffer is opened for the first time in a session. {default_category} (string, default: 'Todo') Category assigned to new tasks when no `cat:` token is present and no `Category: ` prefix is used with `:Pending add`. {date_format} (string, default: '%b %d') strftime format string used to render due dates as virtual text in the buffer. Examples: `'%Y-%m-%d'` for ISO dates, `'%d %b'` for day-first. {eol_format} (string, default: '%c %r %d') Format string controlling the order, content, and separators of end-of-line virtual text on task lines. Three specifiers are available: `%c` category icon + name (`PendingHeader`) `%r` recurrence icon + pattern (`PendingRecur`) `%d` due icon + date (`PendingDue` / `PendingOverdue`) Literal text between specifiers is rendered with the `Normal` highlight group and acts as a separator. When a specifier's data is absent (e.g. `%d` on a task with no due date), the specifier and any surrounding literal text up to the next specifier are omitted — missing fields never leave gaps. `%c` only renders in priority view (where `show_category` is true). In category view it is always omitted regardless of the format string. Examples: >lua vim.g.pending = { eol_format = '%d %r' } vim.g.pending = { eol_format = '%d | %r' } vim.g.pending = { eol_format = '%c %d %r' } < {input_date_formats} (string[], default: {}) *pending-input-formats* List of strftime-like format strings tried in order when parsing a `due:` token that does not match the built-in keywords or ISO `YYYY-MM-DD` format. Specifiers supported: `%Y` (4-digit year), `%y` (2-digit year, 00–69 → 2000s, 70–99 → 1900s), `%m` (numeric month), `%d` / `%e` (day), `%b` / `%B` (abbreviated or full month name, case-insensitive). When no year specifier is present the current year is used, advancing to next year if the date has already passed. Examples: >lua input_date_formats = { '%m/%d/%Y', -- 03/15/2026 '%d-%b-%Y', -- 15-Mar-2026 '%m/%d', -- 03/15 (year inferred) } < {date_syntax} (string, default: 'due') The token name for inline due-date metadata. Change this to use a different keyword, for example `'by'` to write `by:2026-03-15` instead of `due:2026-03-15`. {recur_syntax} (string, default: 'rec') The token name for inline recurrence metadata. Change this to use a different keyword, for example `'repeat'` to write `repeat:weekly`. {someday_date} (string, default: '9999-12-30') The date that `later` and `someday` resolve to. This acts as a "no date" sentinel for GTD-style workflows. {category_order} (string[], default: {}) Ordered list of category names. In category view, categories that appear in this list are shown in the given order. Categories not in the list are appended after the ordered ones in their natural order. {queue_sort} (string|string[], default: 'default') *pending-sort* Sort order for the queue (priority) view. Accepts a named preset string or an ordered list of sort keys. Presets: ~ `'default'` priority → due → order → id `'due-first'` due → priority → order → id `'alphabetical'` description → priority → order → id `'newest-first'` entry (desc) → priority → order → id `'recent'` modified (desc) → priority → order → id Sort keys: ~ `'priority'` Higher priority first (descending) `'due'` Earlier due date first (nil last) `'status'` Pending before done `'category'` Alphabetical by category `'description'` Alphabetical by task text `'entry'` Oldest creation date first `'modified'` Oldest modification first `'order'` Internal insertion order `'id'` Task creation order Prefix a key with `-` to flip its default direction (e.g. `'-due'` for latest-first). `'priority'` defaults to descending; all other keys default to ascending. Implicit `order`, `id` tiebreakers are appended when absent for stable, deterministic sort. When `'status'` appears in the key list, the pending-before-done split is disabled and status participates as a normal sort field. Otherwise pending tasks always appear before done tasks. Examples: >lua vim.g.pending = { queue_sort = 'due-first' } vim.g.pending = { queue_sort = { 'priority', '-due', 'description' }, } < {category_sort} (string|string[], default: 'default') Sort order for tasks within each category in category view. Same syntax as `queue_sort`. The `'default'` preset is priority → order → id. Example: >lua vim.g.pending = { category_sort = { 'due', 'priority', 'order' }, } < {folding} (boolean|table, default: true) *pending.FoldingConfig* Controls category-level folds in category view. When `true`, folds are enabled with the default foldtext `'%c (%n tasks)'`. When `false`, folds are disabled entirely. When a table, folds are enabled and the table may contain: {foldtext} (string|false, default: '%c (%n tasks)') Custom foldtext format string. Set to `false` to use Vim's built-in foldtext. Two specifiers are available: `%c` category name `%n` number of tasks in the fold The category icon is prepended automatically. When `false`, the default Vim foldtext is used. Folds only apply to category view; priority view is always fold-free regardless of this setting. Examples: >lua vim.g.pending = { folding = true } vim.g.pending = { folding = false } vim.g.pending = { folding = { foldtext = '%c (%n tasks)' }, } < {keymaps} (table, default: see below) *pending.Keymaps* Buffer-local key bindings. Each field maps an action name to a key string. Set a field to `false` to disable that binding. Unset fields use the default. See |pending-mappings| for the full list of actions and their default keys. {debug} (boolean, default: false) Enable diagnostic logging. When `true`, textobj motions, mapping registration, and cursor jumps emit messages at `vim.log.levels.DEBUG`. Use |:messages| to inspect the output. Useful for diagnosing keymap conflicts (e.g. `]t` colliding with Neovim defaults) or motion misbehavior. Example: >lua vim.g.pending = { debug = true } < {sync} (table, default: {}) *pending.SyncConfig* Sync backend configuration. Each key is a backend name and the value is the backend-specific config table. Built-in backends: `gcal`, `gtasks`. Both ship bundled OAuth credentials so no setup is needed beyond `:Pending auth`. {icons} (table) *pending.Icons* Icon characters displayed in the buffer. The {pending}, {done}, and {priority} characters appear inside brackets (`[icon]`) as an overlay on the checkbox. The {category} character prefixes both header lines and EOL category labels. Fields: {pending} Pending task character. Default: ' ' {done} Done task character. Default: 'x' {priority} Priority task character. Default: '!' {due} Due date prefix. Default: '.' {recur} Recurrence prefix. Default: '~' {category} Category prefix. Default: '#' ============================================================================== STORE RESOLUTION *pending-store-resolution* When pending.nvim opens the task buffer it resolves which store file to use: 1. Search upward from `vim.fn.getcwd()` for a file named `.pending.json`. 2. If found, use that file as the active store (project-local store). 3. If not found, fall back to `data_path` from |pending-config| (global store). This means placing a `.pending.json` file in a project root makes that project use an isolated task list. Tasks in the project store are completely separate from tasks in the global store; there is no aggregation. To create a project-local store in the current directory: >vim :Pending init < The `:checkhealth pending` report shows which store file is currently active. ============================================================================== HIGHLIGHT GROUPS *pending-highlights* pending.nvim defines the following highlight groups. All groups are set with `default`, so colorschemes can override them by defining the group without `default` before or after the plugin loads. *PendingHeader* PendingHeader Applied to category header lines (text at column 0). Default: links to `Title`. *PendingDue* PendingDue Applied to the due date virtual text shown at the right margin of each task line. Default: links to `DiagnosticHint`. *PendingOverdue* PendingOverdue Applied to the due date virtual text of overdue tasks. Default: links to `DiagnosticError`. *PendingDone* PendingDone Applied to the text of completed tasks. Default: links to `Comment`. *PendingPriority* PendingPriority Applied to the `! ` priority marker on priority tasks. Default: links to `DiagnosticWarn`. *PendingRecur* PendingRecur Applied to the recurrence indicator virtual text shown alongside due dates for recurring tasks. Default: links to `DiagnosticInfo`. *PendingFilter* PendingFilter Applied to the `FILTER:` header line shown at the top of the buffer when a filter is active. Default: links to `DiagnosticWarn`. To override a group in your colorscheme or config: >lua vim.api.nvim_set_hl(0, 'PendingDue', { fg = '#aaaaaa', italic = true }) < ============================================================================== LUA API *pending-api* The following functions are available on `require('pending')` for use in statuslines, autocmds, and other integrations. *pending.counts()* pending.counts() Returns a table of current task counts: >lua { overdue = 2, -- pending tasks past their due date/time today = 1, -- pending tasks due today (not yet overdue) pending = 10, -- total pending tasks (all statuses) priority = 3, -- pending tasks with priority > 0 next_due = "2026-03-01", -- earliest future due date, or nil } < The counts are read from a module-local cache that is invalidated on every `:w`, toggle, date change, archive, undo, and sync. The first call triggers a lazy `store.load()` if the store has not been loaded yet. Done, deleted, and `someday` sentinel-dated tasks are excluded from the `overdue` and `today` counts. The `someday` sentinel is the value of `someday_date` in |pending-config| (default `9999-12-30`). *pending.statusline()* pending.statusline() Returns a pre-formatted string suitable for embedding in a statusline: - `"2 overdue, 1 today"` when both overdue and today counts are non-zero - `"2 overdue"` when only overdue - `"1 today"` when only today - `""` (empty string) when nothing is actionable *pending.has_due()* pending.has_due() Returns `true` when `overdue > 0` or `today > 0`. Useful as a conditional for statusline components that should only render when tasks need attention. *PendingStatusChanged* PendingStatusChanged A |User| autocmd event fired after every count recomputation. Use this to trigger statusline refreshes or notifications: >lua vim.api.nvim_create_autocmd('User', { pattern = 'PendingStatusChanged', callback = function() vim.cmd.redrawstatus() end, }) < ============================================================================== RECIPES *pending-recipes* Configure blink.cmp to use pending.nvim's omnifunc as a completion source: >lua require('blink.cmp').setup({ sources = { per_filetype = { pending = { 'omni', 'buffer' }, }, }, }) < Lualine integration: >lua require('lualine').setup({ sections = { lualine_x = { { function() return require('pending').statusline() end, cond = function() return require('pending').has_due() end, }, }, }, }) < Heirline integration: >lua local Pending = { condition = function() return require('pending').has_due() end, provider = function() return require('pending').statusline() end, } < Manual statusline: >vim set statusline+=%{%v:lua.require('pending').statusline()%} < Startup notification: >lua vim.api.nvim_create_autocmd('User', { pattern = 'PendingStatusChanged', once = true, callback = function() local c = require('pending').counts() if c.overdue > 0 then vim.notify(c.overdue .. ' overdue task(s)') end end, }) < Event-driven statusline refresh: >lua vim.api.nvim_create_autocmd('User', { pattern = 'PendingStatusChanged', callback = function() vim.cmd.redrawstatus() end, }) < Nerd font icons: >lua vim.g.pending = { icons = { due = '', recur = '󰁯', category = '', }, } < Open tasks in a new tab on startup: >lua vim.api.nvim_create_autocmd('VimEnter', { callback = function() vim.cmd.PendingTab() end, }) < ============================================================================== SYNC BACKENDS *pending-sync-backend* Sync backends are Lua modules under `lua/pending/sync/.lua`. Each backend is exposed as a top-level `:Pending` subcommand: >vim :Pending gtasks {action} :Pending gcal {action} < Each module returns a table conforming to the backend interface: >lua ---@class pending.SyncBackend ---@field name string ---@field push? fun(): nil ---@field pull? fun(): nil ---@field sync? fun(): nil ---@field health? fun(): nil < Required fields: ~ {name} Backend identifier (matches the filename). Optional fields: ~ {push} Push-only action. Called by `:Pending push`. {pull} Pull-only action. Called by `:Pending pull`. {sync} Main sync action. Called by `:Pending sync`. {health} Called by `:checkhealth pending` to report backend-specific diagnostics (e.g. checking for external tools). Note: authorization is not a per-backend action. Use `:Pending auth` to authenticate all Google backends at once. See |pending-google-auth|. Backend-specific configuration goes under `sync.` in |pending-config|. ============================================================================== GOOGLE CALENDAR *pending-gcal* pending.nvim can push tasks with due dates to Google Calendar as all-day events. Each pending.nvim category maps to a Google Calendar of the same name. Calendars are created automatically on first push. This is a one-way push; changes made in Google Calendar are not pulled back. Configuration: >lua vim.g.pending = { sync = { gcal = {}, }, } < No configuration is required to get started — bundled OAuth credentials are used by default. Run `:Pending auth` and the browser opens immediately. *pending.GcalConfig* Fields: ~ {client_id} (string, optional) OAuth client ID. When set together with {client_secret}, these take priority over the credentials file and bundled defaults. {client_secret} (string, optional) OAuth client secret. See {client_id}. {credentials_path} (string, optional) Path to an OAuth client secret JSON file downloaded from the Google Cloud Console. Default: `stdpath('data')..'/pending/gcal_credentials.json'`. The file may be in the `installed` wrapper format that Google provides or as a bare credentials object. Credential resolution: ~ Credentials are resolved in order: 1. `client_id` + `client_secret` config fields (highest priority). 2. JSON file at `credentials_path` (or the default path). 3. Bundled credentials shipped with the plugin (always available). OAuth flow: ~ See |pending-google-auth|. Tokens are shared with the gtasks backend and stored at `stdpath('data')/pending/google_tokens.json`. `:Pending gcal push` behavior: ~ For each task in the store: - A pending task with a due date and no existing event: a new all-day event is created in the calendar matching the task's category. The event ID and calendar ID are stored in the task's `_extra` table. - A pending task with a due date and an existing event: the event summary and date are updated in place. - A done or deleted task with an existing event: the event is deleted. - A pending task with no due date that had an existing event: the event is deleted. ============================================================================== GOOGLE TASKS *pending-gtasks* pending.nvim can sync tasks bidirectionally with Google Tasks. Each pending.nvim category maps to a Google Tasks list of the same name. Lists are created automatically on first sync. Configuration: >lua vim.g.pending = { sync = { gtasks = {}, }, } < No configuration is required to get started — bundled OAuth credentials are used by default. Run `:Pending auth` and the browser opens immediately. *pending.GtasksConfig* Fields: ~ {client_id} (string, optional) OAuth client ID. When set together with {client_secret}, these take priority over the credentials file and bundled defaults. {client_secret} (string, optional) OAuth client secret. See {client_id}. {credentials_path} (string, optional) Path to an OAuth client secret JSON file downloaded from the Google Cloud Console. Default: `stdpath('data')..'/pending/gtasks_credentials.json'`. Accepts the `installed` wrapper format or a bare credentials object. Credential resolution: ~ Same three-tier resolution as the gcal backend (see |pending-gcal|). OAuth flow: ~ See |pending-google-auth|. Tokens are shared with the gcal backend and stored at `stdpath('data')/pending/google_tokens.json`. `:Pending gtasks` actions: ~ `:Pending gtasks` (or `:Pending gtasks sync`) runs push then pull. Use `:Pending gtasks push` or `:Pending gtasks pull` to run only one direction. Push (local → Google Tasks, `:Pending gtasks push`): - Pending task with no `_gtasks_task_id`: created in the matching list. - Pending task with an existing ID: updated in Google Tasks. - Done task with an existing ID: marked `completed` in Google Tasks. - Deleted task with an existing ID: deleted from Google Tasks. Pull (Google Tasks → local, `:Pending gtasks pull`): - GTasks task already known (matched by `_gtasks_task_id`): updated locally if `gtasks.updated` timestamp is newer than `task.modified`. - GTasks task not known locally: created as a new pending.nvim task in the category matching the list name. Field mapping: ~ {title} ↔ task description {status} `needsAction` ↔ `pending`, `completed` ↔ `done` {due} date-only; time component ignored (GTasks limitation) {notes} serializes extra fields: `pri:1 rec:weekly` The `notes` field is used exclusively for pending.nvim metadata. Any existing notes on tasks created outside pending.nvim are parsed for known tokens and the remainder is ignored. Recurrence (`rec:`) is stored in notes for round-tripping but is not expanded by Google Tasks (GTasks has no recurrence API). ============================================================================== GOOGLE AUTHENTICATION *pending-google-auth* Both the gcal and gtasks backends share a single OAuth client with combined scopes (`tasks` + `calendar`). One authorization flow covers both services and produces one token file. :Pending auth ~ Prompts with |vim.ui.select| offering three options: `gtasks`, `gcal`, and `both`. All three options run the identical combined OAuth flow — the choice is informational only. If no real credentials are configured (i.e. bundled placeholders are in use), the setup wizard runs first to collect a client ID and client secret before opening the browser. OAuth flow: ~ A PKCE (Proof Key for Code Exchange) flow is used: 1. A random 64-character `code_verifier` is generated. 2. Its SHA-256 hash is base64url-encoded as the `code_challenge`. 3. The Google authorization URL is opened in the browser via |vim.ui.open()|. 4. A temporary TCP server on port 18392 waits up to 120 seconds for the OAuth redirect. 5. The authorization code is exchanged for tokens via `curl`. 6. The refresh token is written to `stdpath('data')/pending/google_tokens.json` with mode `600`. 7. Subsequent syncs refresh the access token automatically when it is about to expire (within 60 seconds of the `expires_in` window). Credential resolution: ~ Credentials are resolved in order for the `google` config key: 1. `client_id` + `client_secret` under `sync.google` (highest priority). 2. JSON file at `sync.google.credentials_path` or the default path `stdpath('data')/pending/google_credentials.json`. 3. Bundled placeholder credentials (always available; trigger setup wizard). The `installed` wrapper format from the Google Cloud Console is accepted. ============================================================================== DATA FORMAT *pending-data* Tasks are stored as JSON at the active store path (see |pending-store-resolution|). The file is safe to edit by hand and is forward-compatible — unknown fields are preserved on every read/write cycle via the `_extra` table. Schema: > { "version": 1, "next_id": 42, "tasks": [ ... ] } < Task fields: ~ {id} (integer) Unique, auto-incrementing task identifier. {description} (string) Task text as shown in the buffer. {status} (string) `'pending'`, `'done'`, or `'deleted'`. {category} (string) Category name. Defaults to `default_category`. {priority} (integer) `1` for priority tasks, `0` otherwise. {due} (string) ISO date string `YYYY-MM-DD`, or absent. {recur} (string) Recurrence shorthand (e.g. `weekly`), or absent. {recur_mode} (string) `'scheduled'` or `'completion'`, or absent. {entry} (string) ISO 8601 UTC timestamp of creation. {modified} (string) ISO 8601 UTC timestamp of last modification. {end} (string) ISO 8601 UTC timestamp of completion or deletion. {order} (integer) Relative ordering within a category. Any field not in the list above is preserved in `_extra` and written back on save. This is used internally to store the Google Calendar event ID (`_gcal_event_id`) and Google Tasks IDs (`_gtasks_task_id`, `_gtasks_list_id`), and allows third-party tooling to annotate tasks without data loss. The `version` field is checked on load. If the file version is newer than the version the plugin supports, loading is aborted with an error message asking you to update the plugin. ============================================================================== HEALTH CHECK *pending-health* Run |:checkhealth| pending to verify your setup: >vim :checkhealth pending < ==============================================================================