vscode-todo-plus: task trees, time estimates and embedded todos inside VS Code

A plain text file that happens to drive a tree view

The extension registers a language called todo with the aliases Todo, Todos, Task and Tasks, and claims a set of file extensions: TODO, TODOS,.TODO,.TODOS, todolist.txt,.todo,.todos,.task,.tasks and.taskpaper. The grammar that drives syntax highlighting lives in./syntax/grammar.tmLanguage, and the default file name setting is TODO, with the other names listed as alternatives.

The important architectural point is that the file is the source of truth. A todo file is a plain text format that you can read and edit using any editor, and the extension adds a tree rendering, colouring and statistics on top of it. The README calls this portability a feature, and it is the feature that most separates this design from a hosted task tracker: your task list lives in the repository next to the code, and losing the extension costs you the view, not the data.

That choice also explains the extension's structure. The package.json lists main as out/extension.js, meaning the published package is a webpack bundle built from the TypeScript sources in src/, with webpack.config.js and tsconfig.json at the top level of the repository. The activationEvents entry is "*", so the extension activates on any window rather than waiting for a particular file type, which is what lets the embedded todos view scan the workspace in the background.

Embedded todos: reading TODO and FIXME out of source comments

The second half of the extension is a different mechanism with the same goal. Rather than requiring a separate file, it can find todos embedded in code as comments, the common //TODO or //FIXME pattern, and collect them into its own view. The command palette exposes Todo: Open Embedded for that view, plus Todo: Embedded View - Filter, Todo: Embedded View - Clear Filter and Todo: Embedded View - Toggle View All Files, which switches between the whole workspace and the current file.

The readme explains the practical case: it is common to have //TODO or //FIXME comments in our code, and leaving them there means the notes travel with the code they refer to. But a comment does not carry structure. There is no project grouping, no time estimate and no completion state in a bare //TODO line, so the extension's todo types, mapped to colours under todo.colors.types with entries such as TODO and FIXME, exist to give those comments a visual identity rather than a full metadata model.

The two views also collide in one respect. A todo file can itself contain lines that look like embedded comments, and a comment in a source file can look like a todo file line. Which file set each view scans is controlled by todo.file.include and todo.file.exclude, whose defaults are glob patterns for the files each view includes and excludes. Anyone with a mixed repository should read those two globs before assuming the two views stay separate.

Symbols, colours and tags as configuration surface

Everything about the appearance is a setting, and the settings list in the readme is long. Symbols come in three roles, box, done and cancelled, and each has a list of accepted alternatives. Each of the three has a default symbol, and each can be replaced by any alternative from its list. Colours are separate keys, for example todo.colors.done set to #a6e22e and todo.colors.cancelled set to #f92672, with separate dark and light theme objects so that a colour set can differ per theme.

Special tags are configurable too. todo.tags.names lists the tag names the extension treats specially, with the default set of critical, high, low and today, and todo.tags.namesInference is a boolean that lets the extension infer commonly used tag names from your own files. There is also a per-type colour map under todo.colors.types and background and foreground colour lists for tags under todo.colors.tags.background and todo.colors.tags.foreground.

This surface is genuinely large. A useful consequence is that the extension can be made to match an existing convention rather than forcing its own. The README makes that explicit for TaskPaper: set todo.symbols.box, todo.symbols.done and todo.symbols.cancelled to -, and the file becomes compatible with that format. The cost of that flexibility is a long configuration surface, and a lot of behaviour that is only discoverable by reading the settings list rather than the readme prose.

Time estimates, timekeeping and the statistics tokens

The most distinctive feature is that todos carry time. A todo can be estimated with a tag written as @est(3 hours), @est(2h30m) or @2h30m, and once estimates exist, four statistic tokens become useful: [est], [est-total], [est-finished] and [est-finished-percentage]. Estimates are therefore not decoration, they feed a report.

Timekeeping is a separate mechanism. A todo can be marked as started, and the time between started and completion is recorded. The settings control the format of the timestamps written into the tags, with todo.timekeeping.started.format and todo.timekeeping.finished.format both defaulting to YY-MM-DD HH:mm, and todo.timekeeping.elapsed.format defaulting to short-compact for the @lasted and @wasted tags. The @created tag is off by default while the @done or @cancelled tag is on, and the settings note that the finished tag is always enabled if you explicitly start a todo or if you use only one symbol.

A timer can be shown in the status bar for started todos, controlled by todo.timer.statusbar.enabled and its alignment key. Taken together, this is more than a checkbox list. It is a small time accounting system that lives inside text files, and it is the part of the extension most likely to be worth the configuration effort and the part most likely to be ignored by the rest of a team.

The command palette and the six editing shortcuts

The extension adds 11 commands to the palette, and the readme lists them with a one line description each. The list is worth reading as the feature map, because it is the shortest complete inventory of what the extension does:

'Todo: Open' // Open or create your project's todo file
'Todo: Open Embedded' // Open embedded todos
'Todo: Toggle Box' // Toggle todo's box symbol
'Todo: Toggle Done' // Toggle todo's done symbol
'Todo: Toggle Cancelled' // Toggle todo's cancelled symbol
'Todo: Toggle Start' // Toggle a todo as started
'Todo: Toggle Timer' // Toggle the timer
'Todo: Archive' // Archive finished todos
'Todo: Embedded View - Filter' // Filter the embedded todos view
'Todo: Embedded View - Clear Filter' // Clear the filter in the embedded todos view
'Todo: Embedded View - Toggle View All Files' // Toggle between viewing all files or only the current one

Six shortcuts are added while editing a Todo file, and they are the fastest way to work: Cmd/Ctrl+Enter and Alt+Enter toggle the box, Alt+D toggles done, Alt+C toggles cancelled, Alt+S toggles started, and Cmd/Ctrl+Shift+A archives. The archive command is backed by the special Archive section whose name is set by todo.archive.name, and a set of related keys control how archiving behaves, including removing projects without todos, removing extra empty lines, and the @project tag with its separator.

The last key worth flagging is todo.archive.sortByDate, which sorts lines by finished date. A todo file is plain text, and the extension is willing to rewrite its ordering, so a team that treats the file as a hand-maintained document will find that a stray archive command reorders lines that people had arranged by hand.

Installation and a first file in a few steps

Installation is the usual Visual Studio Code route. The readme points to the Marketplace listing and gives a command palette command for it:

ext install fabiospampinato.vscode-todo-plus

After installation, the first real use is Todo: Open, which opens or creates your project's todo file. New files get default content from todo.file.defaultContent, and a small part of the relevant settings looks like this:

  "todo.file.name": "TODO", // Todo file name. Other supported names are: `*.todo`, `*.todos`, `*.task`, `*.tasks`, `*.taskpaper` and `todolist.txt`
  "todo.indentation": "  ", // String used for indentation
  "todo.archive.name": "Archive", // Name of the special "Archive" section

What you should see is a tree view of your tasks, and a Todo file that a colleague without the extension could still read. If the file name does not match one of the recognised patterns, the extension will not pick it up, and the fix is either renaming the file or changing todo.file.name.

Plain files versus a hosted tracker, and what the format does not give you

The obvious alternative is to keep tasks in a hosted tracker and treat the repository as the place where only code lives. The difference in approach is concrete rather than a matter of taste. A hosted tracker gives you assignment, comments, due dates enforced by a server, and a way for a colleague on another machine to see the same list without cloning anything. The plain text file in the repository gives you a history that comes free with version control, and it means the task list is reviewed in the same pull request as the change it describes.

Todo+ also offers a middle path in the form of TaskPaper compatibility, which is a different approach again: instead of storing your tasks in the extension's own convention, set the three symbol settings to - and the file follows TaskPaper's convention, which other software can open. The catch is that the deeper features are tied to the extension's own tags. Time estimates written as @est(3 hours), the statistics tokens and the special tag names are extensions to the format, not part of the TaskPaper convention, so a TaskPaper compatible file loses them.

The limits of the format are worth stating plainly. Everything lives in a text file, so there is no server side view of who is working on what, and the file's structure depends on indentation and on the symbols the extension expects. The extension is written in TypeScript and packaged through webpack, and the repository carries a changelog.md rather than published releases, so there is no GitHub release to pin to and no release note to read before an upgrade.

Editorial conclusion

Adopt vscode-todo-plus if your team already keeps task lists as plain text files in the repository and wants tree views, estimates and statistics without moving to a hosted tracker. Skip it if you need mobile access, shared assignment, or a task system that other tools can consume programmatically, since the file format is a convention the extension defines rather than a documented interchange format. Verify first that your existing TODO files parse under the default symbols, and that the version you install matches the 4.19.1 recorded in package.json, because the repository publishes no GitHub releases to compare against.

Frequently asked questions

Official sources

1. fabiospampinato/vscode-todo-plus on GitHub
2. Issues
3. License: MIT
4. README