Todoey

A lean, developer-focused VS Code extension that turbocharges task and changelog management. Manage tasks right in a TODO.md with zero-friction, in-editor flow, and when you finish a task, it automatically lands in your changelog via seamless semantic-release integration for effortless changelog generation and precise versioning. Boost productivity, keep your backlog clean, and ship with confidence.

Features

• TODO.md-based task management - Human-readable, git-friendly task format
• AI Friendly - Give your agent a Todoey task and watch it mark it complete once finished.
• Work-in-Progress (WIP) tracking - Focus on one task at a time
• Rich metadata support - Tags, mentions, estimates, due dates, and ticket IDs
• Embedded task scanning - Automatically detect, display and highlight TODO, FIXME, BUG comments in your code
• Syntax highlighting & color coding - Configurable colors for tasks, tags, mentions, and metadata
• Semantic-release integration - Automated conventional commits and changelog generation
• VS Code native integration - Tree view, commands, and status bar
• CI/CD compatible - Integrate with Github, Gitlab etc.
• Track unreleased tasks - Generate a list of completed but unreleased tasks directly from VS Code

Quick Start

1. Install the Todoey extension from the VS Code Marketplace
2. Use the command pallette to create your first task or manually create a TODO.md file in your project root

That's it! Continue to use the command palette or TODO.md to manage your tasks.

Detailed Overview

Once Todoey is installed Todoey will prompt you to create a TODO.md file (if one doesn't exist), click Create TODO.md. An example task list will be generated and opened.

# TODO

## Current Sprint

- [ ] feat: Example task #feature ~2h
  - [ ] chore: Sub-task example
- [ ] fix: Another task #bug ~30m @developer

## Backlog

- [ ] feat: Future enhancement #enhancement ~1h due:2025-11-02
- [ ] docs: Documentation update #docs ~45m

The generated file provides an example of all of Todoey's features. You can use it as a template for your own TODO.md file. At its core, the todo file is just basic markdown.

Tasks can be divided into sections via markdown ## headers - these can be anything you like. Tasks are tracked via markdown checkboxes ([ ]). The most basic task would look like this:

- [ ] Example task

But Todoey becomes more powerful when you add metadata to your tasks:

- [ ] feat: Example task #ui-enhancement ~2h @developer due:2025-11-02

In the above example we have added:

• Conventional commit: feat:
• Tags: #ui-enhancement
• Mentions: @developer
• Estimate: ~2h
• Due Date: due:2025-11-02

By starting your task with a conventional commit type Todoey will automatically git commit the changes with a conventional commit message when it is completed. You can then (optionally) configure your CI/CD platform to automatically updated your apps version and include completed tasks in a changelog.

Don't want to break your flow and jump back to the TODO.md file? No problem! Todoey will also detect inline or embedded comments such as:

// TODO: fix: This needs fixing
function add(a, b) {
    return a - b;
}

The above task will be highlighted inline and will appear in the task tree interface.

Working with tasks

While you can create tasks manually in the TODO.md file, Todoey also provides a number of other ways to make managing your tasks easier.

One task at a time can be marked as work in progress (WIP). This allows you to quickly apply actions to this one task such as complete, complete and commit.

Command palette

All of Todoey's features can be accessed via the command palette (using ctrl/cmd+shift-p). Available commands:

• Initialize TODO.md - Create a new TODO.md file with example tasks
• Create Task - Add a new task with full metadata support and prompts
• Create Child Task - Add a sub-task under an existing task
• Quick Create Task - Quickly add a simple task without metadata prompts
• Mark as WIP - Set the current task as work-in-progress
• Set Task as WIP at Cursor - Mark task at cursor as WIP (keybind: ctrl/cmd+w in TODO.md)
• Clear WIP - Remove WIP status from the current task
• Complete and Commit - Select and complete a task from TODO.md or embedded tasks, then create a git commit
• Complete WIP Task - Complete the current WIP task
• Complete Task at Cursor - Complete task at cursor position in TODO.md or embedded task comment in code (keybind: ctrl/cmd+enter)
• Mark Complete (No Commit) - Select and complete a task from TODO.md or embedded tasks without creating a commit
• Mark as Incomplete - Revert a completed task back to incomplete
• Commit Completed Tasks - Create git commits for all completed tasks
• Move Task to Section - Move a task to a different section
• Remove Task - Delete a task from TODO.md
• Delete Task at Cursor - Delete task at cursor (keybind: alt+d in TODO.md)
• Show WIP Status - Display the current work-in-progress task
• Show Unreleased Tasks - View tasks that have been completed but not released
• Refresh Embedded Tasks - Manually refresh the embedded code comment tasks
• Refresh Embedded Task Colors - Update embedded task color highlighting
• Navigate to Task - Quick navigation to any task in your TODO.md file or inline
• Open Settings - Open Todoey settings

Tree view

Located under the document explorer the tree view provides a list of all tasks from both the TODO.md and any inline/embedded tasks. Basic task management can be completed from this interface of click on a task to be taken directly to it.

Tasks can be completed or marked as WIP directly from the treeview by using the icons to the right of the task.

Status bar

The status bar provides either:

1. A summary of tasks to do vs. tasks completed (click it to be taken to the TODO.md file)
2. A quick overview of the current work-in-progress task (click it to complete the task)

Settings

The extension is fully customisable via the standard VS Code settings page.

Color Customization

The extension provides rich syntax highlighting with configurable colors:

• Task States: Completed (✓ green), cancelled (✗ red), WIP (* orange), incomplete (☐ white text with natural orange checkboxes)
• Section Headers: Cyan headings for better visibility
• Metadata: Tags (#feature blue), mentions (@user purple), estimates (~2h cyan), due dates (due:2024-12-31 red), WIP markers (%WIP% yellow), commit types (feat: underlined)
• Formatting: Bold, italic, strikethrough, and code blocks

Access color settings via VS Code settings: Search for "todoey colors"

Embedded Tasks

Todoey automatically scans your codebase for embedded tasks in comments and displays them in the TODO Tasks explorer:

// TODO: Add input validation
function processData(data) {
    // FIXME: Handle edge cases properly
    if (!data) return null;
    
    // BUG: This doesn't work with negative numbers
    return data.map(item => item * 2);
}

// NOTE: Consider using a more efficient algorithm
// HACK: Temporary workaround until API is fixed
// XXX: This entire function needs refactoring

Supported comment patterns:

• // TODO:, // FIXME:, // BUG:, // HACK:, // NOTE:, // XXX:
• /* TODO: ... */ (block comments)
• # TODO: (Python, shell scripts)
• <!-- TODO: ... --> (HTML/XML)
• -- TODO: (SQL, Lua)

Features:

• Multi-language support - Works with JavaScript, TypeScript, Python, Java, C/C++, C#, PHP, Ruby, Go, Rust, Swift, and more
• Grouped by type - Tasks are organized by type (TODO, FIXME, BUG, etc.)
• Click to navigate - Click any embedded task to jump to the file and line
• Complete embedded tasks - Right-click in tree view or use ctrl/cmd+enter at cursor to complete and remove the comment (optionally commits to git)
• Auto-refresh - Automatically updates when files change (configurable)
• Manual refresh - Use the refresh button in the tree view

Configuration:

• todoey.embeddedTasks.enabled - Enable/disable embedded task scanning and display in tree view and command palette (default: true)
• todoey.embeddedTasks.autoRefresh - Auto-refresh when files change (default: true)

CI/CD Setup

The project includes automated semantic-release integration for version management and changelog generation.

1. Required CI/CD Variables:

   GitLab (Settings → CI/CD → Variables):

   • GITLAB_TOKEN: Personal Access Token with write_repository scope
   • CI_PUSH_TOKEN: Same token (for automated version commits)

   GitHub (Settings → Secrets and variables → Actions):

   • GITHUB_TOKEN: Personal Access Token with repo scope
   • GH_TOKEN: Same token (for automated version commits)

2. Create Personal Access Token:

   GitLab:

   • Go to GitLab → Preferences → Access Tokens
   • Create token with write_repository and read_repository scopes
   • Add to project CI/CD variables (make sure to check "Mask variable")

   GitHub:

   • Go to GitHub → Settings → Developer settings → Personal access tokens
   • Create token with repo scope (full repository access)
   • Add to repository secrets

   VS Code Marketplace (for VSCE_TOKEN):

   • Go to https://marketplace.visualstudio.com/manage
   • Create Personal Access Token with Marketplace (manage) scope

   Open VSX Registry (for OPEN_VSX_TOKEN):

   • Go to https://open-vsx.org/
   • Sign in → User Settings → Access Tokens
   • Create new token

3. Automated Release Process:

   • Push conventional commits to main branch
   • CI automatically runs tests and build
   • Semantic-release analyzes commits and:
     • Updates package.json version
     • Generates CHANGELOG.md entries
     • Creates GitLab release with tags
     • Commits version changes back to repository

Conventional Commit Types

• feat: → Minor version bump (new features)
• fix: → Patch version bump (bug fixes)
• feat!: or BREAKING CHANGE: → Major version bump
• chore:, docs:, test: → No version bump