NotchList
NotchList is a local-first task list for VS Code and compatible editors (including Cursor). Tasks live in the Explorer sidebar next to Outline and Timeline: statuses, optional groups, filtering, bulk actions, optional import/export, and a focused Add to Chat flow for AI-assisted work.
There are no accounts, no cloud sync, and no telemetry in v1. Privacy: see the full policy in PRIVACY.md (what is stored locally, what can leave your machine, and how to get help).
Install
Open Extensions, search for NotchList (DaddooDev.notchlist), and install.
Also published on Open VSX for editors that use that marketplace.
Requirements: VS Code 1.96 or newer (see engines.vscode in package.json).
What you get
| Area |
What it does |
| Explorer tree |
Collapsible NotchList section per workspace folder (multi-root safe). |
| Statuses |
Not started, In progress, Completed — icons, row text, and tooltips; sensible sort order. |
| Groups |
One level of virtual folders; tasks live at the root or inside one group. |
| Completed visibility |
Hide all, show only recently completed (1–30 days), or show all — from settings and the eye title actions. |
| Filter |
Title action opens an input; matches title + description. Use #tag tokens (e.g. #bug #docs) to require tags in title/description. |
| Details |
Click a task to open a webview for long descriptions; Save, Add to Chat, Close. |
| Quick Add |
One-line task entry with optional :: description, @Group, status /ns /ip /c, /due=YYYY-MM-DD, /start=YYYY-MM-DD. |
| Import / export |
JSON and Markdown export; lenient JSON import (merge or replace). Completed tasks are skipped on import. |
| Archive |
Remove completed tasks after an optional export. |
| Add to Chat |
Builds Markdown + fenced JSON; opens Chat where supported, otherwise clipboard. Nothing auto-sends. |
| MCP |
Workspace file .notchlist/state.json mirrors tasks for the bundled MCP server and other tools. |
| Settings |
Command NotchList: Settings opens the Settings UI filtered to this extension. |
First run
A short welcome and display name prompt (default from git config user.name when available). You can change behavior anytime under NotchList: Settings.
How to use it
Tree and selection
- Left-click a task → Details (unless Click to cycle status is enabled in settings; then a single selected task may cycle status on click).
- Left-click a group → expand/collapse.
- Right-click tasks for Add to Chat, Status, rename, duplicate, delete, and (with multi-select) move/remove group and bulk delete.
- Hover a task for the inline Add to Chat action.
Completed tasks
notchlist.completedVisibilityMode: hide_all (default), show_recent, or show_all.notchlist.completedRecentDays: when mode is show_recent, how many days to keep visible (1–30). Tasks need a stored completion time to count as “recent.”- Title bar: NotchList: Cycle Completed Visibility and, in
show_recent mode, Set Completed Recency…
Legacy notchlist.hideCompleted is still present for compatibility; new installs should use completed visibility mode above.
Open NotchList: Quick Add Task… (view title or Command Palette). Example:
Fix auth redirect :: handle edge case in callback #bug @Milestone1 /ip /due=2026-05-01
:: splits title (left) from description (right).@Name assigns or creates a group named Name (case-insensitive match)./ns, /ip, /c (or long forms) set status./due=YYYY-MM-DD and /start=YYYY-MM-DD set optional dates when valid.#tags in the title/description are informal tags; use them in the filter as #tag.
Import and export
NotchList: Import / Export… from the view title.
- Prefer export → edit → import so the JSON shape stays valid.
- Import accepts common shape variations; invalid rows are skipped with a summary when possible.
- Completed tasks in a file are not imported (only active work is merged in).
Archiving
NotchList: Archive Completed… removes completed tasks for the current folder after optional JSON/Markdown export.
Add to Chat
Use the hover button, task context menu, Details toolbar, or the command palette. The editor may open a Chat tab with prefilled content; you still send the message yourself. If Chat is unavailable, the same payload is copied to the clipboard and you are notified.
MCP and agents
The extension keeps .notchlist/state.json (and backups alongside it) in sync with your list for MCP and scripts. Configure your MCP client with NOTCHLIST_AGENT_STATE pointing at that file (see NotchList: MCP Setup (Wizard) and related commands).
Screenshots
Gallery files live in docs/screenshots/. Captured in Cursor with a dark theme; your UI may differ.
Selected task
Context menu and status
Settings
Command Palette
JSON snapshot (import / export)
Use schemaVersion: 1. Top-level fields:
| Field |
Required |
Notes |
schemaVersion |
yes |
Must be 1. |
groups |
yes |
Array of { id, name, sortOrder? }. |
tasks |
yes |
Array of task objects (below). |
displayName |
no |
Shown in payloads / UX. |
onboardingCompleted |
no |
Onboarding flag. |
Each task:
| Field |
Required |
Notes |
id |
import: optional (generated if missing) |
Stable id for merge. |
title |
yes |
|
description |
yes |
May be "". |
status |
yes |
not_started | in_progress | completed. |
groupId |
yes |
String or null for root. |
startedAt |
no |
Date-ish string; often YYYY-MM-DD. |
dueDate |
no |
YYYY-MM-DD recommended. |
completedAt |
no |
Set when marked completed; used for “recent completed” visibility. |
Privacy and data
Short version:
- Nothing is sent to NotchList-operated services (there are none).
- Tasks live in VS Code workspace extension storage and in an optional
.notchlist/ mirror under your project for MCP; see PRIVACY.md for tables, retention, and what happens with Add to Chat / MCP / npm during setup.
Support
Help and bug reports: GitHub Issues for this repository.
Security vulnerabilities: SECURITY.md — use a private GitHub Security Advisory, not a public issue.
For contributors and publishers
Local development
npm ci
npm run build
npm run watch
Build a .vsix and publish
npm ci
npm run package
That produces notchlist-<version>.vsix in the repo root. Publish with vsce to the Visual Studio Marketplace and with ovsx to Open VSX. This repo includes npm scripts vscode:publish and openvsx:publish; Open VSX expects the OVSX_PAT environment variable.
Continuous integration (GitHub Actions) typechecks and packages the extension on pushes to main or master.
