Do-It.nvim

Do-It.nvim is a modular task management framework for Neovim, providing a clean, distraction-free interface to manage your tasks and notes directly within your editor.

Do-It.nvim began as a way to track tasks and keep simple markdown notes per project. As a Principal Engineer with many disparate things to keep track of, I wanted a simple way to do that without leaving my editor. I've tried many task managers, but they all seemed too complex - I just needed to know what I needed to do, without bells and whistles.

This project is a fork of Dooing by atiladefreitas, expanded with a modular framework and additional plugins such ash project notes, and calendar..

Features

• Modular Framework - Use only the components you need
• Task Management - Create, organize, and track to-dos
• Project Notes - Maintain project-specific documentation
• Tags & Filtering - Categorize tasks with #tags
• Due Dates - Set deadlines with calendar integration
• Priorities - Assign and sort by importance
• Time Estimation - Track estimated completion time
• Import/Export - Backup or share your tasks
• Lualine Integration - Show active tasks in your statusline
• Tmux Add-on - Optional tmux integration with shared data (see below)

Quick Start

Installation with Lazy.nvim

return {
    "bearded-giant/do-it.nvim",
    config = function()
        require("doit").setup()
    end,
}

Basic Usage

1. Open todos: :Doit or <leader>td
2. Add a todo: Press n in the todo window
3. Toggle status: Press x on a todo
4. Open notes: :DoItNotes or <leader>dn

Installation Options

Prerequisites

• Neovim >= 0.10.0
• Lazy.nvim as your plugin manager

Full Framework (Recommended)

return {
    "bearded-giant/do-it.nvim",
    config = function()
        require("doit").setup({
            modules = {
                todos = { enabled = true },
                notes = { enabled = true }
            }
        })
    end,
}

Standalone Modules

Use individual modules without the framework:

-- Just todos
return {
    "bearded-giant/do-it.nvim",
    config = function()
        require("doit_todos").setup()
    end,
}

-- Just notes
return {
    "bearded-giant/do-it.nvim",
    config = function()
        require("doit_notes").setup()
    end,
}

-- Calendar (v2.0) - macOS only, requires icalbuddy
return {
    "bearded-giant/do-it.nvim",
    config = function()
        require("doit").setup({
            modules = {
                calendar = { enabled = true }
            }
        })
    end,
}

Commands & Keybindings

See Complete Keybindings Reference for all commands and keyboard shortcuts.

Quick Reference

Framework Commands:

• :DoItDashboard - Open main DoIt dashboard
• :DoItPlugins list - List installed modules
• :DoItPlugins info <module> - Show module details

Module Commands:

Todos:

• :DoIt - Open main todo window
• :DoItList - Quick todo list (floating)
• :DoItLists - Manage multiple todo lists

Notes:

• :DoItNotes - Open notes window
• :DoItNotesNew - Create new project note
• :DoItNotesSearch - Search across notes

Calendar (macOS only):

• :DoItCalendar - Toggle calendar window
• :DoItCalendarDay - Open in day view
• :DoItCalendar3Day - Open in 3-day view
• :DoItCalendarWeek - Open in week view

Basic Keys (in todo window):

• n - Add new todo
• x - Toggle status
• d - Delete todo
• ? - Show full help
• L - List manager
• q - Close window

The keybindings documentation is auto-generated from a central source to ensure consistency. Run make update-help to regenerate after changes.

Modules

Todos Module

The todos module provides task management functionality: Full Documentation

• Create, edit, and organize to-dos
• Tag-based filtering and organization
• Priority-based sorting
• Due dates with calendar integration
• Time estimation tracking
• Import/export capabilities

Notes Module

The notes module provides project-specific notes: Full Documentation | Work in Progress

• Project-specific notes based on Git repository
• Global notes mode for system-wide documentation
• Markdown syntax highlighting
• Floating window interface
• Automatic saving

Calendar Module (v2.0)

The calendar module provides macOS calendar integration: Full Documentation | Module Docs

• icalbuddy Integration: View events from macOS Calendar app
• Multiple Views: Day, 3-day, and week views
• Smart Parsing: Handles 100% of icalbuddy event formats
• UTF-8 Support: Correctly displays special characters
• Auto-refresh: Updates when switching views
• All Calendar Sources: iCloud, Google, Exchange support

Note: Requires macOS with icalbuddy installed (brew install icalbuddy)

Documentation

• User Guide: See :help doit in Neovim
• Framework Documentation: :help doit-framework
• Developer Documentation: docs/ directory
• API Reference: :help doit-api

Configuration

Do-It.nvim uses a nested configuration structure that separates core framework settings from module-specific options. This makes it easier to navigate and customize.

Configuration Structure

require("doit").setup({
    -- Core framework settings
    development_mode = false,
    quick_keys = true,
    timestamp = { enabled = true },
    lualine = { enabled = true, max_length = 30 },
    project = {
        enabled = true,
        detection = { use_git = true, fallback_to_cwd = true },
    },

    -- Module configurations
    modules = {
        todos = {
            enabled = true,
            ui = {
                window = {
                    width = 55,
                    height = 20,
                    border = "rounded",
                },
                -- More UI settings...
            },
            formatting = {
                pending = { icon = "○" },
                in_progress = { icon = "◐" },
                done = { icon = "✓" },
            },
            priorities = {
                { name = "critical", weight = 16 },
                { name = "urgent", weight = 8 },
                { name = "important", weight = 4 },
            },
            -- More todos settings...
        },
        notes = {
            enabled = true,
            ui = {
                window = {
                    -- Absolute sizing
                    width = 80,   -- columns
                    height = 30,  -- lines
                    -- Or relative sizing
                    relative_width = 0.6,   -- 60% of screen
                    relative_height = 0.6,  -- 60% of screen
                    use_relative = true,    -- toggle mode
                    position = "center",    -- or top-left, bottom-right, etc.
                },
            },
            storage = {
                path = vim.fn.stdpath("data") .. "/doit/notes",
                mode = "project", -- or "global"
            },
            -- More notes settings...
        },
    },
})

Key Configuration Points

• Core settings (top level): Framework-wide configurations like development_mode, lualine, and project detection
• Module settings (modules.todos and modules.notes): Specific to each module, organized into logical groups like ui, storage, formatting, etc.
• Backward compatibility: The plugin maintains support for the legacy flat configuration structure

For a complete list of all configuration options with detailed descriptions, see lua/doit/config.lua.

Also see :help doit-configuration in Neovim for interactive documentation.

Lualine Integration

Do-It.nvim provides several lualine components to display todo information in your statusline:

require("lualine").setup({
  sections = {
    lualine_c = {
      -- Show current list and todo count
      { require("doit").lualine.current_list },

      -- Show todo statistics (done/in-progress/pending)
      { require("doit").lualine.todo_stats },

      -- Show active (in-progress) todo
      { require("doit").lualine.active_todo }
    }
  }
})

Available components:

• current_list - Shows current list name and todo count: 📋 work (5)
• todo_stats - Shows todo statistics: ✓3 ◐1 ○2 (done/in-progress/pending)
• active_todo - Shows the current in-progress todo (if any)

Tmux Integration (Optional Add-on)

Note: The tmux integration is a separate, optional add-on that shares data with the Neovim plugin. You can use doit.nvim without tmux, or use both together for a seamless experience across your terminal workflow.

The tmux add-on provides todo management directly from tmux, with status bar integration and an interactive fzf-based manager. Changes sync automatically between Neovim and tmux.

Prerequisites

• tmux with TPM
• fzf for interactive mode
• jq for JSON parsing

Installation

Add to your tmux.conf:

set -g @plugin 'bearded-giant/do-it.nvim'

Then install with prefix + I.

Keybindings

With prefix key (prefix + d + ...):

Key	Action
t	Quick todo popup
i	Interactive manager (fzf)
x	Toggle current todo done
n	New todo
N	Start next pending todo

Direct shortcuts (Alt+Shift):

Key	Action
Alt+Shift+T	Quick todo popup
Alt+Shift+I	Interactive manager
Alt+Shift+X	Toggle todo done
Alt+Shift+N	New todo

In interactive manager:

Key	Action
Enter	Toggle done
s	Start/In-progress
x	Stop in-progress
X	Revert to pending
n	New todo
e	Edit todo text
d	Delete (can undo)
u	Undo last delete
?	Show help
q	Quit

In create/edit mode: type text, Enter twice to save, Esc to cancel.

Configuration

# Change the prefix key (default: d)
set -g @doit-key "t"

# Disable Alt+Shift shortcuts
set -g @doit-alt-bindings "off"

# Use $EDITOR (nvim, vim) for create/edit instead of inline input
set -g @doit-use-editor "true"

Status Bar Integration

If using bearded-giant-tmux theme, add todo to your status modules:

set -g @bearded_giant_status_modules_right "meetings todo"

For other themes, use the status script directly:

set -g status-right "#(~/.tmux/plugins/do-it.nvim/tmux/scripts/todo-status.sh)"

Contributing

See the developer documentation for:

• Development setup and debugging
• Framework architecture
• Module development guide
• Implementation notes

Roadmap

• Reorder To-dos
• Active To-do to Top
• Project Notes
• Modular Framework
• To-do Categories (with filtering)
• Cross-module Integration (todo-note linking)
• Module Registry (internal modules)
• Named (Multiple) To-do Lists
• Categories View Window
• External/Custom Module Loading

Acknowledgments

Do-It.nvim started as fork of Dooing by atiladefreitas. Special thanks to him for creating the original plugin.

The project notes feature was inspired by maple.nvim's project notes functionality.

The framework architecture was inspired by other modular Neovim plugins like mini.nvim and snack.nvim.