Tasks for Markdown

Obsidian Tasks-compatible task management for Markdown files in VS Code and Cursor.

Website · Korean README

This extension started from the Tasks plugin for Obsidian. It rebuilds that plugin's task syntax, query language and years of careful design for VS Code and Cursor. Thank you to its authors and contributors — see Credits.

Why Tasks for Markdown

- [ ] Write the report #work ⏫ 🔁 every week 🛫 2026-09-20 ⏳ 2026-09-22 📅 2026-09-25
  - Ask finance for the Q3 numbers
- [x] Tidy meeting notes ✅ 2026-09-21

The extension indexes every - [ ] line in the workspace. You can see, query and complete tasks wherever you are: the editor, a sidebar, a kanban board, a calendar or the Markdown preview. Completing a task rewrites the line in the file. It adds a done date, and for a recurring task it adds the next instance.

Highlights

• Same syntax as Obsidian Tasks — emoji and Dataview fields, written in Obsidian's field order, so files stay interchangeable.
• Editor assistance — auto-suggest with natural-language dates (English and Korean), CodeLens, hover cards, overdue highlighting, diagnostics with quick fixes.
• Sidebar — Today, Next 7 days, Overdue, In progress, Blocked, All open, Done; saved queries with grouped results.
• Query language — the Obsidian Tasks query language in ```tasks blocks, saved queries and a visual query builder.
• Recurrence, statuses, dependencies — 🔁 every month on the last, custom statuses with presets, 🆔/⛔ dependencies with blocked detection, urgency score.
• Rendered view — an interactive preview: tick, edit, postpone, add notes, show or hide columns, live query results (Ctrl+Shift+R).
• Notes — indented bullets under a task are its notes; add them from the rendered view with 💬.
• More views — create/edit dialog, kanban, calendar, weekly statistics, archive, daily notifications.
• AI and automation — MCP server for AI agents, public extension API, commands, CLI and library (see Use it with AI and Extend it).

Getting started

1. Open a folder with Markdown files. Every - [ ] line in it becomes a task, and the Tasks icon appears in the Activity Bar.
2. Create tasks. Write a checklist line such as - [ ] Write the report 📅 2026-09-25, or press Ctrl+Shift+C (the Ctrl key on macOS too) to open the create/edit dialog. Ctrl+Shift+Enter on a task line marks it done.
3. Filter with a query block, then view the note. A ```tasks block lists the tasks that match its lines; Ctrl+Shift+R opens the note in the rendered view with the results in place. (VS Code's own Markdown preview shows the results too, but its checkboxes are display-only.) Common query lines: Query syntax.

```tasks
not done
due before next week
sort by urgency
group by filename
```

See it in action

Write tasks with help. Auto-suggest offers fields as you type, and natural-language dates like next fri become real dates.

Create and edit in a dialog. Ctrl+Shift+C on an empty line opens a form for a new task. On an existing task it opens the same form to edit it, with priority, dates in plain words, tags and repeat presets.

Complete with one key. Ctrl+Shift+Enter marks a task done. A recurring task gets its next occurrence automatically.

Work in the rendered view. Tick checkboxes, add notes with 💬, and show or hide columns. Query blocks update live.

Plan on a board and a calendar. Drag cards between status columns, or drag a task to another day to reschedule it.

Use it with AI

Tasks for Markdown ships an MCP server, so any MCP-capable AI agent can read and change your tasks as tools: Claude Code, Cursor's agent, VS Code's agent mode, Claude Desktop. Connect it once, then ask in plain language. The recording below is a real Claude Code session. The note in the editor updates while the agent works.

Connect (Node.js 18+ is needed, because the server runs from npm with npx):

# Claude Code, in your notes folder
claude mcp add tasks -- npx -y @hastycapybara/tasks-cli mcp --root "$PWD"

Cursor — .cursor/mcp.json:

{ "mcpServers": { "tasks": { "command": "npx", "args": ["-y", "@hastycapybara/tasks-cli", "mcp", "--root", "${workspaceFolder}"] } } }

VS Code (agent mode) — .vscode/mcp.json:

{ "servers": { "tasks": { "type": "stdio", "command": "npx", "args": ["-y", "@hastycapybara/tasks-cli", "mcp", "--root", "${workspaceFolder}"] } } }

Claude Desktop — claude_desktop_config.json, with the absolute path of your notes folder:

{ "mcpServers": { "tasks": { "command": "npx", "args": ["-y", "@hastycapybara/tasks-cli", "mcp", "--root", "/path/to/notes"] } } }

Ask things like:

• "What is overdue? Mark the vendor contract review done and add a note: Legal approved clause 3."
• "Plan my week: list everything due before Sunday, sorted by urgency."
• "Postpone all #home tasks due today to Saturday."
• "Create a task to renew the passport, high priority, due next Friday."

What the agent can do: query with the full query language, get and create tasks, update fields, set status, postpone, add notes, remove, and explain a query. The agent reads a syntax reference first, so the lines it writes are valid Obsidian Tasks syntax. Every write carries the exact text of the line it read, and the write is refused if the line changed meanwhile. Your edits are never overwritten by an agent working from an old copy. Full tool list: MCP server.

Extend it

Tasks for Markdown is built to be built on. Another extension, a keybinding, a script or a CI job can use the same tasks through a stable, versioned public API. You don't need to parse Markdown yourself.

What you could build:

• a time tracker that starts a timer when a task moves to In progress (events.onDidChangeStatus)
• a status bar counter or dashboard of overdue work (query.run + events.onDidChangeTasks)
• a bridge that posts completed tasks to a team chat or closes an issue (events.onDidCompleteTask)
• a daily report in CI that fails the build when release tasks are overdue (the CLI)
• your own views on top of the same index: timelines, focus lists, reviews

import type { TasksExtensionExports } from '@hastycapybara/tasks-api';

const ext = vscode.extensions.getExtension<TasksExtensionExports>('HastyCapybara.tasks-for-markdown');
const tasks = (await ext!.activate()).getAPI(1, { extensionId: 'me.my-extension' });

const r = await tasks.query.run('not done\ndue before tomorrow\nsort by urgency');
tasks.events.onDidChangeStatus(({ before, after }) => console.log(after.description, before.status.name, '→', after.status.name));
if (tasks.features?.includes('notes.add')) await tasks.edit.addNote(r.tasks[0], 'Started');

The API version stays 1 while features are only added, so your extension keeps working across updates. Writes are confirmed once per caller by default (tasksmd.api.writePolicy), errors are plain { code, message } objects, and stale writes are refused. Read the public API reference.

Query syntax

A ```tasks block holds one instruction per line. Every line in the result must pass all filter lines (they combine with AND). It is the Obsidian Tasks query language, so the same block works in Obsidian.

Dates accept words such as today, next friday, in 2 weeks, ranges such as this month and 2026-W40, and exact dates. Full reference: filters, sorting and grouping in the Obsidian Tasks docs.

You don't have to write queries by hand. Tasks: Open query builder assembles one from drop-downs and shows the matching count as you go. The Explain CodeLens above a block shows how each line was understood.

Commands (Command Palette → "Tasks:")

Settings (tasksmd.*)

Documentation

• Public API (extension API, commands, library, CLI, MCP server)

• Publishing guide (Korean) · Postmortems and incident log (Korean)

• User guide (Korean)

• Requirements · Design · Development checklist · Performance

Development

pnpm install
pnpm build              # extension + webview bundles
pnpm test               # unit tests (vitest)
pnpm test:integration   # runs a VS Code instance
pnpm package            # production build + .vsix + latest.json

Press F5 in VS Code to launch an Extension Development Host.

Credits

This extension would not exist without Obsidian Tasks. The task syntax, the query language and parts of the core logic (parser, recurrence, urgency) are ported from it (MIT license), and its documentation is the reference for how each feature behaves. Many thanks to Martin Schenck, who created the plugin, Clare Macrae, who has led it for years, and every contributor.

• If you use Obsidian, try the original plugin: Tasks documentation · repository
• You can support the original project: GitHub Sponsors (Clare Macrae)
• Ported code and license notices: NOTICE.md

This project is not affiliated with or endorsed by the Obsidian Tasks project or Obsidian (Dynalist Inc.).

License

MIT