Todo Dev

A VS Code extension that keeps your project's todo list in a plain Todo.md at the workspace root, shows it in a sidebar panel, and keeps it in two-way sync with the TODO comments in your code.

What it does

• Todo.md as the single source of truth — standard Markdown checklist, human readable and version-controllable. No hidden database.
• Sidebar panel — click the Todo Dev icon in the activity bar to add, edit, delete, tick off and filter todos.
• Soft TODO highlighting — // TODO: something gets a very light amber wash plus a mark in the overview ruler. Present, but never loud enough to fight your syntax colours.
• Two-way sync — a TODO comment you write appears in Todo.md; deleting the comment removes the entry; renaming or deleting the entry (in the panel or in Todo.md) rewrites or removes the comment in your code.

Todo.md format

# Todo

- [ ] a task added from the sidebar
- [x] a finished task
- [ ] a task that came from code <!-- source:src/app.ts:41:1a2b3c4d -->

The trailing HTML comment records where the todo came from — file path, line number and a hash of the text. HTML comments do not render in Markdown, so the file still looks clean everywhere else. The line number is only a hint: if code moves around, the comment is relocated by its content hash. When it truly cannot be found, the entry is kept and flagged source lost rather than being deleted.

Lines that are not checklist items (headings, prose, blank lines) are preserved exactly as written, so you can keep notes in the same file.

Recognised comments

Any of these forms, with a space or a colon after the keyword, case-insensitive:

// TODO: with a colon
// TODO without a colon
/* TODO: block comment */
 * TODO: jsdoc line
# TODO: python, shell, yaml
<!-- TODO: html, markdown -->
-- TODO: sql, lua
; TODO: ini

Commands

Settings

Development

npm install
npm run compile      # bundle src/extension.ts -> dist/extension.js
npm run watch        # rebuild on change
npm run typecheck    # tsc --noEmit

Press F5 (or run the Run Extension launch configuration) to open an Extension Development Host. Open a folder there, then:

1. Click the Todo Dev icon in the activity bar — the panel opens.
2. Add a todo — Todo.md appears at the workspace root with the entry in it.
3. Write // TODO: try me in a file and save — the comment gets a soft highlight and the todo shows up in the panel with a file:line badge.
4. Delete that comment and save — the entry disappears from the panel and from Todo.md.
5. Rename the entry in the panel — the comment text in your code is rewritten to match.
6. Delete the entry in the panel — the comment is removed from your code.
7. Edit Todo.md by hand — the panel updates, and edits to code-backed entries flow back into the comments.

Known limitations

• Todos are matched to comments by content, so two identical TODO texts in the same file cannot be told apart; the second one is treated as a duplicate of the first.
• Detection is regex-based, not language-aware. A cheap guard checks quote state on the line, so a TODO inside a single-line string literal (const s = "/* TODO: x */";) is ignored in both directions and is never rewritten or deleted. It cannot see across lines, so a TODO inside a multi-line string / template literal or heredoc can still be mistaken for a comment — the scanner treats each line in isolation.
• Ticking a box does not change your code. Completion state lives in Todo.md only, so finishing a task never rewrites source files; the comment stays until you delete it.
• Everyday syncing covers files you open or save. Use Scan Workspace for a full import — it reads up to 2000 matching files, which can take a moment on very large repositories.
• Only the first workspace folder is used; multi-root workspaces keep a single Todo.md at that folder's root.
• Editing a code comment and its Todo.md entry at the same time within one debounce window is resolved last-writer-wins.

License

MIT