aven-nvim

Link Aven tasks to lines in documents edited with Neovim. Create, update, complete, inspect, and delete linked tasks from Neovim, then open or safely remove their source lines from the Aven TUI.

Features

• Create or update an Aven task from a #AVEN line in Neovim.
• Store the source document and line number as Aven metadata.
• Complete, inspect, or delete the linked task without copying task references.
• Open a linked document at the correct line from the Aven TUI.
• Delete a task and its linked document line from the Aven TUI with validation, backup, and rollback safeguards.
• Infer Aven projects from the document directory when project path mappings are configured.

Requirements

• Aven with custom TUI command support (tested with Aven 0.1.39)
• Neovim 0.10 or newer with vim.system() support
• Bash
• jq
• Standard Unix tools: awk, grep, sha256sum, mktemp, and cp

The Aven TUI custom-command API is currently experimental.

Installation

Clone the repository:

git clone https://github.com/alxhall/aven-nvim.git ~/Code/other/aven-nvim
cd ~/Code/other/aven-nvim

Create the destination directories:

mkdir -p ~/.config/nvim/lua/user_functions
mkdir -p ~/.config/aven/commands

Link the Neovim module and Aven commands:

ln -s ~/Code/other/aven-nvim/nvim/lua/user_functions/tasks.lua \
  ~/.config/nvim/lua/user_functions/tasks.lua

ln -s ~/Code/other/aven-nvim/aven/commands/open-linked-document-task \
  ~/.config/aven/commands/open-linked-document-task

ln -s ~/Code/other/aven-nvim/aven/commands/delete-linked-document-task \
  ~/.config/aven/commands/delete-linked-document-task

The commands must be executable:

chmod 755 ~/Code/other/aven-nvim/aven/commands/*

These commands intentionally fail when a destination already exists. Back up or remove an existing file before creating its symlink.

Neovim configuration

Load the module from your Neovim configuration, for example in lua/config/keymaps.lua:

require("user_functions.tasks")

Restart Neovim after installing or updating the module. During development, it can be reloaded with:

:lua package.loaded["user_functions.tasks"] = nil; require("user_functions.tasks")

Aven configuration

Add the following entries under tui.commands in ~/.config/aven/config.yaml:

tui:
  commands:
    - name: open-linked-document-task
      description: Open the selected task's linked document in Neovim
      program: ~/.config/aven/commands/open-linked-document-task
      keys: [z o]
      detail_keys: [z o]
      target: focused
      execution: terminal
      on_success: refresh

    - name: delete-linked-document-task
      description: Delete the selected task and its linked document line
      program: ~/.config/aven/commands/delete-linked-document-task
      keys: [z d]
      detail_keys: [z d]
      target: focused
      execution: wait
      on_success: refresh

Merge this block with any existing tui configuration rather than adding a second tui key. Restart the Aven TUI after changing the configuration. Validate it with:

aven doctor

Usage

Create a linked task

Write a task marker in a named, saved document:

#AVEN Implement the parser

Place the cursor on the line and press <leader>Ta. The integration prompts for:

• Project name; leave blank to let Aven infer it from the document directory.
• Availability date or time.
• Due date.
• Space-separated labels. Missing labels are created automatically.

After creation, the line is commented using the current buffer's commentstring and receives the durable Aven task ID:

<!-- #AVEN Implement the parser :: AVEN: SXMF95GZH55ZTZ43 -->

The exact comment syntax depends on the file type.

Neovim keybindings

Key	Action
<leader>Ta	Create a task, or update the task linked to the current line
<leader>Tc	Set the linked task status to done
<leader>Td	Soft-delete the linked task and remove its line from the current buffer
<leader>Ti	Show full task information

Aven TUI commands

Select a linked task in the task list or detail view:

Key	Command	Action
z o	:open-linked-document-task	Suspend Aven and open Neovim at the linked line
z d	:delete-linked-document-task	Soft-delete the task, remove its document line, and refresh Aven

The commands are also available through Aven's : command palette.

Link metadata

The Neovim integration stores two metadata fields on each linked Aven task:

Field	Meaning
nvim_file	Absolute path to the source document
nvim_line	Cached one-based line number

The durable task ID stored in the document remains valid if the task moves to another Aven project. The Aven TUI commands treat this marker as the source of truth: they search the document for the exact task ID instead of trusting a potentially stale nvim_line. Opening a task refreshes the cached line number automatically, so inserting or removing text above a marker does not break navigation or deletion.

Deletion safety

delete-linked-document-task performs the following checks before changing anything:

1. Exactly one Aven task is selected.
2. The task has valid nvim_file metadata.
3. The target is a writable regular file, not a symlink.
4. The document contains exactly one #AVEN marker matching the selected task's ID or display reference.
5. The file has not changed during validation and backup.
6. The file is not loaded by a listening Neovim instance.

When the file is already open in Neovim, use <leader>Td in that buffer instead. This prevents unsaved edits or a later buffer write from restoring the deleted line.

Backups are written to:

~/.local/state/aven-nvim/deletions/

If replacing the source file fails after the Aven task is deleted, the command attempts to restore the task. After a successful deletion, line metadata for later linked tasks in the same document is refreshed.

Project inference

Aven can infer a project from the source document's directory. Configure a mapping once per checkout:

aven project path add PROJECT /path/to/repository

The Neovim integration runs Aven with the document directory as its working directory. If no mapping or project inference applies, enter a project when prompted.

Portability

nvim_file is currently an absolute path. Synced tasks can only open their linked documents on another computer when those documents have the same absolute paths there.

The scripts and Neovim module are portable, but Aven custom commands are local configuration and are not synced by Aven. Install the symlinks and merge the tui.commands configuration on each computer.

Repository layout

aven-nvim/
├── aven/
│   └── commands/
│       ├── delete-linked-document-task
│       └── open-linked-document-task
└── nvim/
    └── lua/user_functions/tasks.lua