md2do

Manage TODO items in markdown files with powerful filtering, sorting, native Todoist sync, and open multi-source ingestion. Built with TypeScript, designed for developers who love markdown.

✨ Features

• 📝 Markdown-native - Works directly with your existing markdown files
• 🔍 Smart parsing - Extracts TODOs with rich metadata (assignees, priorities, due dates, tags)
• 🎯 Powerful filtering - Filter by assignee, priority, project, tags, due dates, and more
• 📊 Rich statistics - View task breakdowns by priority, assignee, project, or any metadata
• 🎨 Beautiful output - Color-coded priorities, clickable file paths (VS Code integration)
• ⚡ Fast - Built with performance in mind using fast-glob
• 🔧 Flexible - Output in pretty, table, or JSON formats
• 📁 Context-aware - Automatically extracts project and person context from folder structure
• 🔄 Todoist integration - Native two-way sync with the official Todoist API (import, sync, list, add)
• 🌐 Multi-source ingestion - Bring in tasks from Teams, Outlook, Slack, or any source via JSONL — no API credentials needed in md2do
• ⚙️ Configurable - Hierarchical config support (global, project, environment)
• 🤖 AI-powered - MCP server integration for Claude and other AI assistants
• 🟣 Obsidian plugin - Native task list view, autocomplete, and completion tracking in Obsidian

📦 Installation

npm

npm install -g @md2do/cli

pnpm

pnpm add -g @md2do/cli

yarn

yarn global add @md2do/cli

From source

git clone https://github.com/TeamNickHart/md2do.git
cd md2do
pnpm install
pnpm build
pnpm link:cli

🚀 Quick Start

1. Navigate to a directory with markdown files
2. List all tasks:

md2do list

3. View task statistics:

md2do stats

That's it! md2do will scan all .md files and extract your TODO items.

📖 Usage

Task Format

md2do recognizes standard markdown task syntax with rich metadata:

- [ ] Implement user authentication @jane !!! #backend #auth #due/2026-01-20
- [x] Write documentation @nick !! #docs {completed:2026-01-15}
- [ ] Fix bug in parser @alex ! #bug #due/2026-01-18

Supported metadata:

• @username - Task assignee
• !!! / !! / ! - Priority (urgent/high/normal)
• #tag - Tags
• #due/YYYY-MM-DD - Due date
• {completed:YYYY-MM-DD} - Completion date
• {todoist:ID} - Todoist sync ID (native integration)
• {slug:ID} - Any external source link (Teams, Outlook, Slack, etc.)
• - [x] - Completed task
• - [ ] - Incomplete task

Note: Legacy bracket syntax ([due: ...], [completed: ...], [todoist: ...]) is still parsed for backward compatibility.

List Command

Display tasks with filtering and sorting:

# List all tasks
md2do list

# Filter by assignee
md2do list --assignee nick

# Filter by priority
md2do list --priority urgent

# Filter by tag
md2do list --tag backend

# Show only incomplete tasks
md2do list --incomplete

# Show overdue tasks
md2do list --overdue

# Sort by priority
md2do list --sort priority

# Combine filters
md2do list --assignee nick --priority urgent --sort due

# Output as JSON
md2do list --format json

# Output as table
md2do list --format table

List Options:

| Option | Description | | --------------------------- | ---------------------------------------------------------- | | -p, --path <path> | Path to scan (defaults to current directory) | | --pattern <pattern> | Glob pattern for markdown files (default: **/*.md) | | --exclude <patterns...> | Patterns to exclude from scanning | | --completed | Show only completed tasks | | --incomplete | Show only incomplete tasks | | -a, --assignee <username> | Filter by assignee | | --priority <level> | Filter by priority (urgent/high/normal/low) | | --project <name> | Filter by project | | --person <name> | Filter by person (from 1-1 files) | | -t, --tag <tag> | Filter by tag | | --overdue | Show only overdue tasks | | --due-today | Show tasks due today | | --due-this-week | Show tasks due this week | | --due-within <days> | Show tasks due within N days | | -s, --sort <field> | Sort by field (due/priority/created/file/project/assignee) | | --reverse | Reverse sort order | | -f, --format <type> | Output format (pretty/table/json) | | --no-colors | Disable colors in output | | --no-paths | Hide file paths | | --context | Show context information (project, person, heading) |

Stats Command

View aggregated statistics about your tasks:

# Overall statistics
md2do stats

# Group by assignee
md2do stats --by assignee

# Group by priority
md2do stats --by priority

# Group by project
md2do stats --by project

# Group by tag
md2do stats --by tag

# Filter before grouping
md2do stats --assignee nick --by priority

Stats Options:

| Option | Description | | --------------------------- | ----------------------------------------------------- | | -p, --path <path> | Path to scan (defaults to current directory) | | --pattern <pattern> | Glob pattern for markdown files | | --exclude <patterns...> | Patterns to exclude from scanning | | --by <field> | Group by field (assignee/project/person/priority/tag) | | -a, --assignee <username> | Filter by assignee | | --project <name> | Filter by project | | --no-colors | Disable colors in output |

🤖 AI Integration (MCP)

md2do includes a Model Context Protocol (MCP) server that enables AI assistants like Claude to interact with your tasks. The MCP server exposes tools, resources, and prompts for task management through a standardized protocol.

What is MCP?

The Model Context Protocol is an open protocol developed by Anthropic that allows AI assistants to securely connect to external data sources and tools. Think of it like a "Language Server Protocol" for AI assistants.

Quick Setup for Claude Code:

# Build the MCP server
pnpm --filter @md2do/mcp build

# Add to your Claude Code configuration
# See packages/mcp/README.md for detailed instructions

Available Capabilities:

• 🔧 Tools: list_tasks, get_task_stats, search_tasks, get_task_by_id
• 📚 Resources: Access tasks by project, person, file, or all tasks
• 📋 Prompts: Daily standup, sprint summary, overdue review templates

Use Cases:

• Generate daily standup reports automatically
• Ask Claude to analyze your task backlog
• Get AI-powered task prioritization recommendations
• Create sprint summaries and progress reports

👉 Full MCP Documentation - Complete setup guide, API reference, and examples

📁 Project Structure & Context

md2do automatically extracts context from your file structure:

projects/
  acme-app/              # Project context: acme-app
    sprint-planning.md
    bugs.md
  widget-co/             # Project context: widget-co
    roadmap.md
1-1s/
  nick.md                # Person context: nick
  jane.md                # Person context: jane
personal/
  home.md

Tasks in projects/acme-app/*.md automatically get project: acme-app Tasks in 1-1s/nick.md automatically get person: nick

Note: Context extraction works when running md2do list from the repository root directory. The --path option currently doesn't preserve project/person context.

🎨 Output Examples

Pretty Format (Default)

Found 113 tasks
  ✓ 21 completed | ○ 92 incomplete

  ○ !!! Fix memory leak in WebSocket connection (2026-01-18) @nick #bug #critical
    file:///path/to/bugs.md:7

  ○ !! Design dashboard wireframes (2026-01-25) @emma #design #analytics
    file:///path/to/roadmap.md:9

Table Format

┌────────┬──────────┬──────────────────────────────┬──────────┬─────┬──────────────┐
│ Status │ Priority │ Task                         │ Assignee │ Due │ File         │
├────────┼──────────┼──────────────────────────────┼──────────┼─────┼──────────────┤
│ ○      │ !!!      │ Fix memory leak...           │ @nick    │     │ bugs.md:7    │
│ ○      │ !!       │ Design dashboard wireframes  │ @emma    │     │ roadmap.md:9 │
└────────┴──────────┴──────────────────────────────┴──────────┴─────┴──────────────┘

JSON Format

{
  "tasks": [
    {
      "id": "f777d4bd",
      "text": "Fix memory leak in WebSocket connection",
      "completed": false,
      "file": "bugs.md",
      "line": 7,
      "assignee": "nick",
      "priority": "urgent",
      "tags": ["bug", "critical"],
      "dueDate": "2026-01-18T00:00:00.000Z"
    }
  ],
  "metadata": {
    "total": 113,
    "completed": 21,
    "incomplete": 92
  }
}

🔧 Development

Prerequisites

• Node.js >= 18.0.0
• pnpm >= 9.0.0

Setup

# Clone the repository
git clone https://github.com/TeamNickHart/md2do.git
cd md2do

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

# Run tests in watch mode
pnpm test

# Type checking
pnpm typecheck

# Linting
pnpm lint

# Format code
pnpm format

# Run all quality checks
pnpm validate

Project Structure

md2do/
├── packages/
│   ├── core/          # Core parsing, filtering, and file writing
│   │   ├── src/
│   │   │   ├── parser/      # Markdown task parser (extractSources, formatSources)
│   │   │   ├── scanner/     # File scanner
│   │   │   ├── filters/     # Task filtering
│   │   │   ├── sorting/     # Task sorting
│   │   │   ├── writer/      # File modification (atomic updates)
│   │   │   ├── ingest/      # JSONL ingest engine (parseJsonl, ingestRecords)
│   │   │   └── types/       # TypeScript types (Task, SourceProvider, IngestRecord)
│   │   └── tests/
│   ├── cli/           # CLI interface
│   │   ├── src/
│   │   │   ├── commands/    # List and stats commands
│   │   │   ├── formatters/  # Output formatters
│   │   │   └── scanner.ts   # File scanning
│   │   └── tests/
│   ├── config/        # Configuration management
│   │   ├── src/
│   │   │   ├── schema.ts    # Zod schemas for validation
│   │   │   └── loader.ts    # Hierarchical config l