todo-txt.nvim

A Neovim plugin for managing your todo.txt files directly from within Neovim. This plugin provides a clean and efficient interface for working with todo.txt format files, following the todo.txt format specification.

Features

• Create and manage todo items with automatic date prefixing
• Mark tasks as complete with completion dates
• Edit existing tasks through a floating window interface
• View all tasks in a formatted list
• Clean and minimal UI with customizable floating windows
• Native Neovim integration
• Archive completed tasks to a separate file

Installation

Using lazy.nvim:

{
    'cche/todo-txt.nvim',
    dependencies = {
        'hrsh7th/nvim-cmp'
    config = function()
        require('todo-txt').setup()
    end
}

Configuration

The plugin comes with sensible defaults, but you can customize it to your needs:

require('todo-txt').setup({
    todo_file = vim.fn.expand("~/todo.txt"), -- Path to your todo.txt file
    done_file = vim.fn.expand("~/done.txt"), -- Optional: Path to your done.txt file (defaults to done.txt in the same directory as todo.txt)
    window = {
        width = 60,     -- Width of the floating window
        height = 10,    -- Height of the floating window
        border = "rounded", -- Border style of windows
    },
    disable_default_mappings = true -- Disable default key mappings
})

The floating window will cover 80% of the screen space by default, but you can adjust the width and height as needed.

In order to disable the default key mappings, you can pass disable_default_mappings to the setup function, and then define your own mappings:

require('todo-txt').setup({ disable_default_mappings = true })

-- Define your own key mappings
vim.keymap.set("n", "<leader>tt", ":TodoList<CR>", { desc = "Todo List", noremap = true, silent = true })
vim.keymap.set("n", "<leader>ta", ":TodoAdd<CR>", { desc = "Add Todo", noremap = true, silent = true })
vim.keymap.set("n", "<leader>td", ":TodoDue<CR>", { desc = "Due Tasks", noremap = true, silent = true })
vim.keymap.set("n", "<leader>tz", ":TodoArchive<CR>", { desc = "Archive Done Tasks", noremap = true, silent = true })

Usage

The plugin provides several commands for managing your todos:

• :TodoList - Show all todo items in a floating window
• :TodoAdd - Open a window to create a new todo item
• :TodoDue - Show only due tasks in a floating window
• :TodoArchive - Move all completed tasks to done.txt

The :TodoList and :TodoDue will show a list of your todo items in a floating window, with the ability to mark them as complete, edit existing entries or add a priority. The :TodoAdd command will open a floating window to create a new todo item. You can also add a todo item by pressing 'a' in the Todo or Due Tasks windows.

When editing or adding a todo item, you can press to save the changes. When you press you will be in normal mode where will save and pressing will cancel.

Key Mappings

Default leader key mappings (can be disabled with disable_default_mappings):

• <leader>tt - Show todo list
• <leader>ta - Add new todo
• <leader>td - Show due tasks
• <leader>tz - Archive completed tasks

When in the todo list window:

• <CR> - Marks the selected todo item as complete
• q - Close the window
• e - Edit the selected item
• a - Add a new todo item
• p - Set priority for the selected item

When editing a todo item:

• <CR> - Save changes
• <Esc> - Cancel editing

When setting priority:

• Enter a single capital letter (A-Z) and press <CR> to set the priority
• Press <Esc> to cancel
• To remove priority, press <CR> without entering a letter

Task Format

Tasks follow the todo.txt format:

• Priority is indicated with capital letters in parentheses: (A) High priority task
• Creation date is automatically added: 2025-01-13 Do something
• Due dates can be specified with due:YYYY-MM-DD

Example tasks:

(A) 2025-01-13 High priority task due:2025-01-20
2025-01-13 Normal priority task
(B) 2025-01-13 Medium priority task with @context and +project

License

MIT

Contributing

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

Acknowledgments

This plugin is inspired by the todo.txt format created by Gina Trapani. This plugin was built while testing Cascade in Windsurf, an editor developed by Codeium.