vscode-todo

<p align="center"> <img src="https://github.com/ai-autocoder/vscode-todo/blob/e044e89bdf974a6c6cbc81717be9f44f944fe12f/icon.png?raw=true" width="128" alt="Logo"> </p> <h1 align="center">VS Code Todo</h1> <h3 align="center">Todos and notes your AI agent can read and update. In your editor, synced to your phone.</h3> <p align="center"> A built-in <a href="#mcp-server-ai-agent-integration">MCP server</a> lets Claude Code, Cursor, or any MCP client manage your lists. Works in VS Code, Cursor, Windsurf, VSCodium, and other VS Code-based editors. The same lists open on your phone at <strong><a href="https://plans-app.pages.dev">plans-app.pages.dev</a></strong>. </p> <p align="center"> <a href="https://marketplace.visualstudio.com/items?itemName=FrancescoAnzalone.vsc-todo"><img alt="VS Marketplace Installs" src="https://vsmarketplacebadges.dev/installs-short/FrancescoAnzalone.vsc-todo.svg?label=VS%20Marketplace%20installs" /></a> <a href="https://open-vsx.org/extension/FrancescoAnzalone/vsc-todo"><img alt="Open VSX Downloads" src="https://img.shields.io/open-vsx/dt/FrancescoAnzalone/vsc-todo?label=Open%20VSX%20downloads" /></a> <a href="https://github.com/ai-autocoder/vscode-todo/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/ai-autocoder/vscode-todo/ci.yml?branch=master&label=CI&logo=github" /></a> <a href="https://github.com/ai-autocoder/vscode-todo/blob/master/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg" /></a> </p> <p align="center"> <a href="https://plans-app.pages.dev"><img alt="Try it on your phone: plans-app.pages.dev" src="https://img.shields.io/badge/Try_it_on_your_phone-plans--app.pages.dev-1558B8?logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0iI2ZmZiI%2BPHBhdGggZD0iTTE3IDEuMDEgNyAxYy0xLjEgMC0yIC45LTIgMnYxOGMwIDEuMS45IDIgMiAyaDEwYzEuMSAwIDItLjkgMi0yVjNjMC0xLjEtLjktMS45OS0yLTEuOTl6TTE3IDE5SDdWNWgxMHYxNHoiLz48L3N2Zz4%3D" /></a> </p> <p align="center"> <img src="./assets/screenshots/UI-overview.gif" alt="Claude Code reviews cart.ts, files the bugs as tagged todos in VS Code Todo, then completes the next one" /> </p> <p align="center"> <strong>Install:</strong> <a href="https://marketplace.visualstudio.com/items?itemName=FrancescoAnzalone.vsc-todo">VS Code Marketplace</a> | <a href="https://open-vsx.org/extension/FrancescoAnzalone/vsc-todo">Open VSX</a> (Cursor, Windsurf, VSCodium) </p> <p align="center"> <a href="#getting-started">Getting started</a> | <a href="https://github.com/ai-autocoder/vscode-todo/blob/master/ARCHITECTURE.md">Architecture</a> | <a href="https://github.com/ai-autocoder/vscode-todo/issues">Report an issue</a> </p> <p align="center"> ⭐ If this saves you time, a <a href="https://github.com/ai-autocoder/vscode-todo">star on GitHub</a> helps other developers find it. </p>

Table of Contents

• Introduction
• Getting Started
• Key Features
  • MCP Server (AI Agent Integration)
  • User, Workspace & File-specific Management
  • Sync Modes (User and Workspace)
  • Plans (Mobile PWA Companion)
  • Markdown Support for Todos and Notes
  • Syntax Highlighting
  • Mermaid Diagram Support
  • KaTeX Math Support
  • Customizable Sorting
  • Tags
  • Auto delete completed todos after a specified number of days
  • Collapsed item preview lines
  • Webview Font Settings
  • Status Bar Integration
  • Import from JSON / Markdown
  • Export to JSON / Markdown
• Architecture
• Contributing
• License
• Support

Introduction

VS Code Todo is a todo list and note-taking extension for Visual Studio Code, with a companion web app at plans-app.pages.dev that opens the same lists on your phone.

Capture tasks, checklists, and notes with Markdown, Mermaid diagrams, KaTeX math, and syntax highlighting, organized by profile, workspace, or file and accessible from the status bar or activity bar. Sync via GitHub Gist or VS Code Settings Sync, and store reusable AI prompts, code review checklists, and meeting note templates alongside your tasks.

Getting Started

Quick start:

1. Open the Todo Panel

   • Status bar icon or activity bar button.

2. Select a Tab

   • Pick where items live:
     • User (per profile): tasks across all workspaces in the current profile (local by default; see Sync Modes (User and Workspace)).
     • Workspace: tasks for the current project (default)
     • File: tasks for the active file (can be pinned)

3. Add a Todo

   • Enter text in the input box and press Enter.

4. Manage Items

   • Item menu (Todo/Note, markdown, delete); drag to reorder; multi-select for batch actions (Ctrl/Cmd, Shift).

5. Use the Toolbar

   • Wide view, import/export (JSON / Markdown), bulk delete.

Key Features

• Local MCP server for AI agents exposes your todos via the Model Context Protocol with optional read-only and scope restrictions.
• Todo and note scopes (profile, workspace, file) keep personal, project, and file-linked checklists organised.
• Cloud sync via GitHub Gist keeps user/workspace lists in sync across devices and profiles.
• Mobile PWA companion (Plans) opens the same gist-synced lists from your phone's browser or home screen.
• Markdown note-taking with syntax highlighting, Mermaid diagrams, and KaTeX math for rich technical docs.
• Keyboard-first capture with quick add, drag-and-drop ordering, and multi-select bulk actions.
• Status bar & activity bar access keeps your task list one click away anywhere in VS Code.
• Search, filters, and auto-cleanup surface the next task and archive completed work automatically.
• Import / export (JSON & Markdown) to back up, share, or move your todos and notes.

MCP Server (AI Agent Integration)

VS Code Todo can run a local Model Context Protocol (MCP) server so AI agents (Claude Code, Claude Desktop, Cursor, or any MCP-capable client) can read and manage your todos and notes directly, without you copy-pasting them into chat.

Once connected, you can ask an agent to:

• Capture work as you go: "Add a todo to refactor the auth module." or "Save these release steps as a note in the workspace list."
• Plan from your lists: "What's still open in my workspace todos? Suggest an order to tackle them."
• Keep lists tidy: "Mark the 'update changelog' todo as done." or "Delete the completed items in this file's list."
• Turn code findings into tasks: "Review this file and add a todo for each TODO comment you find."

The server is read-only by default and binds only to loopback (127.0.0.1), so nothing is exposed to the network and agents can't change anything until you opt in to writes.

Quick start

1. Enable the server (User or Workspace settings):

   {
     "vscodeTodo.mcp.enabled": true,
     // Set false to let agents add/edit/delete (default: true = read-only).
     "vscodeTodo.mcp.readOnly": true,
     // Listen port. Use 0 for a random free port.
     "vscodeTodo.mcp.port": 7337,
     // Optional shared-secret token. Leave empty to disable auth.
     "vscodeTodo.mcp.token": ""
   }
   

   Or run VS Code Todo: Start MCP Server from the Command Palette (and Stop MCP Server to turn it off). The workspace must be trusted.

2. Connect your agent. The server speaks streamable HTTP at http://127.0.0.1:<port>/mcp. Send Authorization: Bearer <token> if you set a token.

   For Claude Code:

   claude mcp add --transport http vscode-todo http://127.0.0.1:7337/mcp
   # With a token:
   claude mcp add --transport http vscode-todo http://127.0.0.1:7337/mcp \
     --header "Authorization: Bearer YOUR_TOKEN"
   

   For clients that use a JSON config (Claude Desktop, Cursor, .mcp.json):

   {
     "mcpServers": {
       "vscode-todo": {
         "type": "http",
         "url": "http://127.0.0.1:7337/mcp",
         "headers": { "Authorization": "Bearer YOUR_TOKEN" }
       }
     }
   }
   

3. Ask away using the example prompts above. The agent discovers the available actions automatically.

Capabilities

The agent works with three lists (scopes), matching the extension's tabs:

• user: your global list, shared across all projects
• workspace: the current project's list
• currentFile: todos attached to a specific file (the agent passes the file path)

It can list todos and notes (with filtering and paging, including by tag), add todos/notes, one at a time or as an ordered batch that preserves the given order (handy for laying down a multi-step plan), edit text, complete/reopen todos, convert between task and note, toggle Markdown rendering, tag items to group them (e.g. all steps of a plan, then track progress with a tag-scoped count), and delete items. All edits are rejected while readOnly is true.

You can also narrow what's reachable with vscodeTodo.mcp.allowedScopes (default ["user", "workspace", "file"]). For example, drop "file" so agents can't touch per-file lists.

Tips for CLAUDE.md / agent instructions

<details> <summary>Add a note to your project's <code>CLAUDE.md</code> / <code>AGENTS.md</code> (click to expand)</summary>

Drop this into your project's CLAUDE.md, AGENTS.md, or equivalent so the agent uses the lists consistently, and only when the work actually calls for it (so it doesn't read your todos on every unrelated turn):

## Task tracking (VS Code Todo MCP)

When the `todo_*` tools are connected, the MCP is this project's task tracker. Reach for it
when the task at hand actually involves tracked work. Don't call it on every turn:

- **When the user refers to tasks, todos, plans, or "what's next"** (or you need to find
  existing tracked work), read with `todo_list_items` / `todo_count_items` (`workspace` scope)
  before searching the repo. The MCP is the source of truth for outstanding work.
- **When you produce a multi-step plan worth keeping**, save it with `todo_add_items`
  (`workspace`) and tag every step with one shared plan tag via `todo_set_tags`; re-read it
  with the `tag` filter.
- **When you finish a tracked step**, mark it with `todo_set_completed` (don't delete).

Skip it for quick questions or one-off edits that aren't about tracked work. Each tool's
description covers scopes, notes, filtering, and read-only behavior.

For read-only setups (vscodeTodo.mcp.readOnly: true), drop the "save"/"mark" lines and keep only the "read existing tracked work" guidance.

</details> <details> <summary>Full tool &amp; resource reference (click to expand)</summary>

Tools: most tools take a scope of user, workspace, or currentFile (for currentFile, also pass filePath); todo_count_items and todo_list_files span all scopes and take no scope. Write tools are rejected in read-only mode.

| Tool | What it does | | --- | --- | | todo_list_items | List todos/notes for a scope. Optional filters: kind (task/note/all), completed (open/done), textPrefix (prefix match), search (substring match anywh