Comment Tasks

A universal Neovim plugin that bridges 10+ task management systems with code comments across multiple programming languages. Create, update, and manage tasks directly from your comments without leaving your editor.

📖 Rendered documentation: docs.georgeharker.com/comment-tasks.nvim

🚀 Features

Manage tasks from code without losing focus. Maintain task references in code.

Transform your TODO comments into actionable tasks across 10+ platforms while keeping task URLs embedded in your codebase for perfect traceability.

• 🔗 Universal Multi-Provider Support: Works with 10+ task management systems
• 🎯 Custom Status System: Configurable workflows for each provider
• 🌍 Multi-Language Support: Works with 15+ programming languages using Tree-sitter
• ✨ Smart Comment Detection: Handles single-line, block comments, and docstrings
• 🔄 Intelligent URL Insertion: Context-aware URL placement
• ⚡ Unified Command Interface: Same commands work across all providers
• 📁 File Reference Management: Structured file associations with tasks
• 🧹 Comment Prefix Trimming: Automatically clean TODO, FIXME, and other prefixes
• 🎨 Language Override: Force specific language detection when needed
• 🔧 Modular Architecture: Extensible system for easy provider addition

📊 Supported Providers

Provider	Type	Custom Status	Bulk Operations	File References
🎯 ClickUp	Full	✅	✅	✅
📋 Asana	Full	✅	❌	✅
⚡ Linear	Full	✅	❌	✅
🏢 Jira	Full	✅	❌	✅
📝 Notion	Full	✅	❌	✅
📈 Monday.com	Full	✅	❌	✅
🐙 GitHub Issues	Basic	❌	❌	✅
🦊 GitLab Issues	Basic	❌	❌	✅
📦 Trello	Basic	❌	❌	✅
✅ Todoist	Basic	❌	❌	✅

Full: Complete workflow customization with any status names
Basic: Open/closed or list-based status management

🌍 Supported Languages

Works with 15+ programming languages including: Python • JavaScript/TypeScript • Lua • Rust • C/C++ • Go • Java • Ruby • PHP • CSS • HTML • Bash • Vim Script • YAML • JSON

📦 Installation

Using lazy.nvim

{
    "georgeharker/comment-tasks.nvim",
    config = function()
        require("comment-tasks").setup({
            default_provider = "clickup", -- Choose your preferred provider
            
            providers = {
                clickup = {
                    enabled = true,
                    api_key_env = "CLICKUP_API_KEY",
                    list_id = "your_clickup_list_id",
                    statuses = {
                        new = "To Do",
                        in_progress = "In Progress",
                        review = "Code Review", 
                        completed = "Complete",
                    }
                },
                -- Add other providers as needed
            },
        })
    end
}

Environment Setup:

export CLICKUP_API_KEY="your_api_key_here"

📖 Detailed Installation: docs/installation.md

🚀 Quick Start

1. Install the plugin with your preferred package manager
2. Configure your task management provider(s)
3. Set environment variables for API authentication
4. Create tasks from comments using commands

Example Workflow

# TODO: Implement user authentication system
# This needs proper validation and error handling

Place cursor on the comment and run :ClickUpTask new →

# TODO: Implement user authentication system  
# This needs proper validation and error handling
# https://app.clickup.com/t/task_id

Update task status as you progress:

:ClickUpTask in_progress  " When you start working  
:ClickUpTask review       " When ready for code review
:ClickUpTask close        " When finished (uses completed status)

⚡ Core Commands

Provider-Specific Commands (Recommended)

" ClickUp (Full custom status support)
:ClickUpTask              " Create task (default)
:ClickUpTask new          " Create task (explicit)
:ClickUpTask in_progress  " Update to 'In Progress' status
:ClickUpTask review       " Update to 'Code Review' status
:ClickUpTask close        " Complete task (uses completed status)
:ClickUpTask addfile      " Add current file to task

" GitHub Issues (Basic support)
:GitHubTask               " Create issue (default)
:GitHubTask new           " Create issue (explicit)
:GitHubTask close         " Close issue
:GitHubTask addfile       " Add file reference

" Asana (Full custom status support)
:AsanaTask                " Create task (default)
:AsanaTask new            " Create task (explicit)
:AsanaTask blocked        " Update to 'Blocked' status
:AsanaTask close          " Complete task

Generic Commands (Uses default_provider)

:CommentTask             " Create task with default provider (default)
:CommentTask new         " Create task with default provider (explicit)
:CommentTask close       " Complete task with default provider
:CommentTask addfile     " Add file reference with default provider
:CommentTaskClose        " Complete task with default provider
:CommentTaskAddFile      " Add file reference with default provider

Available commands are generated dynamically from your status configuration.

⚙️ Configuration

Basic Setup

require("comment-tasks").setup({
    default_provider = "clickup",  -- Provider for generic commands
    
    providers = {
        clickup = {
            enabled = true,
            api_key_env = "CLICKUP_API_KEY",
            list_id = "123456789",
            statuses = {
                new = "To Do",           -- Special: creates tasks
                completed = "Complete",  -- Special: completes tasks
                review = "Code Review",  -- Custom: creates :ClickUpTask review  
                blocked = "Blocked",     -- Custom: creates :ClickUpTask blocked
            }
        }
    }
})

Status System

Commands are automatically generated from your status configuration:

statuses = {
    new = "Backlog",        -- → :ClickUpTask new (creates with "Backlog")
    completed = "Done",     -- → :ClickUpTask completed (updates to "Done")  
    review = "In Review",   -- → :ClickUpTask review (updates to "In Review")
    testing = "QA Testing", -- → :ClickUpTask testing (updates to "QA Testing")
}

📖 Complete Configuration: docs/configuration.md

📁 Project-Level Configuration

Override provider settings per-project by placing a .comment-tasks.json file at your project root. This lets different repositories target different task lists, boards, or projects without changing your personal Neovim config.

How Root Detection Works

When a command runs, the plugin walks upward from the current file's directory:

1. .comment-tasks.json is checked first at every level — if found, that directory is the project root
2. Root markers (.git, pyproject.toml, package.json, etc.) act as a ceiling
3. If no marker is found, falls back to git worktree detection

This means .comment-tasks.json always wins as the root anchor, even if it lives in a subdirectory above nested package.json files.

Example .comment-tasks.json

{
    "default_provider": "clickup",
    "providers": {
        "clickup": { "list_id": "9012345678", "team_id": "1234567" },
        "github":  { "repo_owner": "acme-corp", "repo_name": "backend-api" },
        "jira":    { "project_key": "BACKEND", "server_url": "https://acme.atlassian.net" }
    }
}

Only project-targeting fields are overridden (list IDs, project keys, etc.). API keys and enabled flags always come from your Neovim config — they are never read from the project file.

Customising Root Markers

The default root markers cover most ecosystems. Override them in setup():

require("comment-tasks").setup({
    root_markers = { ".git", "pyproject.toml", "Cargo.toml", ".my-marker" },
    -- ...
})

📖 Full details: docs/configuration.md

📚 Documentation

Setup Guides

• 📦 Installation Guide - Complete installation instructions
• ⚙️ Configuration Reference - All configuration options

Provider Guides

• 🎯 ClickUp Setup
• 📋 Asana Setup
• 🐙 GitHub Issues Setup
• ⚡ Linear Setup
• 🏢 Jira Setup
• 📝 Notion Setup
• 📈 Monday.com Setup
• 📦 Trello Setup
• 🦊 GitLab Issues Setup
• ✅ Todoist Setup

Reference

• 🔧 API Reference - Lua API & keybinding examples

🔧 Keybinding Examples

vim.keymap.set("n", "<leader>tcc", function()
    require("comment-tasks").create_clickup_task_from_comment()
end, { desc = "Create ClickUp task" })

vim.keymap.set("n", "<leader>tgh", function() 
    require("comment-tasks").create_github_task_from_comment()
end, { desc = "Create GitHub issue" })

vim.keymap.set("n", "<leader>tc", function()
    require("comment-tasks").create_task_from_comment()
end, { desc = "Create task (default provider)" })

vim.keymap.set("n", "<leader>tu", function()
    require("comment-tasks").update_task_status_from_comment("completed")
end, { desc = "Complete task" })

vim.keymap.set("n", "<leader>tx", function()
    require("comment-tasks").close_task_from_comment()
end, { desc = "Close task" })

🤝 Contributing

We welcome contributions! See our Contributing Guide for:

• 🆕 Adding new providers
• 🐛 Bug reports and fixes
• 📖 Documentation improvements
• 💡 Feature suggestions

Development Setup

git clone https://github.com/georgeharker/comment-tasks.nvim.git
cd comment-tasks.nvim

📄 License

MIT License - see LICENSE for details.

🙏 Support

• 📖 Documentation: Check the Installation Guide and Configuration Reference for detailed guides
• 🐛 Issues: Report bugs on GitHub Issues
• 💬 Discussions: Ask questions in GitHub Discussions

---

Ready to get started? Check out the Installation Guide and choose your provider setup.