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. |
| New Task |
Title + optional description from the view + or Command Palette. |
| 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 |
Each workspace folder gets .notchlist/state.json (and backups) kept in sync with your list for the bundled MCP server and other tools. |
| Settings |
Command NotchList: Settings opens the Settings UI filtered to this extension. |
First run
The first time you use NotchList in this editor, a short welcome explains the basics (once globally — not again when you open another project). Each workspace folder may prompt once for a local display name (default from git config user.name when available). Task lists are scoped per project folder and do not mix when you switch workspaces. 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: eye cycles completed visibility; in
show_recent mode, Set Completed Recency… is under the More menu (⋯).
Legacy notchlist.hideCompleted is still present for compatibility; new installs should use completed visibility mode above.
Import and export
NotchList: Import / Export… from the view More menu (⋯) or Command Palette.
- 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
For each opened workspace folder, the extension keeps .notchlist/state.json (and backups alongside it) in sync with that folder’s task list for MCP and scripts. The file is stamped with the folder path so a copy from another project is not applied to the wrong list. Configure your MCP client with NOTCHLIST_AGENT_STATE pointing at that folder’s file (see NotchList: MCP Setup (Wizard) and related commands). Add .notchlist/ to .gitignore if you do not want the mirror committed.
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 (per workspace folder) and in a
.notchlist/ mirror under each folder 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.
