md2do

Manage TODO items in markdown files with powerful filtering, sorting, and Todoist sync. 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 - Import tasks and sync completion status with official Todoist API
• ⚙️ 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
• - [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
│   │   │   ├── scanner/     # File scanner
│   │   │   ├── filters/     # Task filtering
│   │   │   ├── sorting/     # Task sorting
│   │   │   ├── writer/      # File modification (atomic updates)
│   │   │   └── types/       # TypeScript types
│   │   └── 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 loading
│   │   └── tests/
│   ├── todoist/       # Todoist API integration
│   │   ├── src/
│   │   │   ├── client.ts    # API client wrapper
│   │   │   └── mapper.ts    # Task format conversion
│   │   └── tests/
│   ├── mcp/           # MCP server for AI integration
│   │   ├── src/
│   │   │   ├── tools/       # MCP tools (list, stats, search)
│   │   │   ├── resources/   # MCP resources (task URIs)
│   │   │   ├── prompts/     # MCP prompt templates
│   │   │   └── utils/       # Scanner utilities
│   │   └── tests/
│   └── obsidian/      # Obsidian community plugin
│       └── src/
│           ├── views/       # Task list sidebar view
│           ├── commands/    # Command palette commands
│           ├── providers/   # Autocomplete suggest provider
│           └── utils/       # Scanner & task writer
├── docs/              # Documentation
│   ├── todoist-setup.md              # Todoist configuration guide
│   └── todoist-implementation-plan.md # Technical roadmap
├── examples/          # Example markdown files
└── .claude/          # Claude Code configuration

Running Locally

# Build the project
pnpm build

# Link the CLI globally (choose one method)

# Method 1: Using convenience script (recommended)
pnpm link:cli

# Method 2: Run directly without global install
pnpm cli -- list --path examples
pnpm cli -- stats --path examples

# Method 3: Link from package directory
cd packages/cli && pnpm link --global

# Test it out (if using Method 1 or 3)
md2do list --path examples
md2do stats --path examples

# Unlink when done
pnpm unlink:cli

Testing

We use Vitest for testing with high coverage:

# Run all tests
pnpm test:run

# Run tests in watch mode
pnpm test

# Run tests for a specific package
pnpm --filter @md2do/core test

# Run tests with UI
pnpm --filter @md2do/core test:ui

Test Coverage:

• 359 tests across 14 test suites
• Parser tests (70 tests)
• Scanner tests (43 tests)
• Filter tests (41 tests)
• Sorting tests (26 tests)
• Pattern matching tests (43 tests)
• Date utility tests (45 tests)
• Writer tests (15 tests)
• Config tests (26 tests)
• Todoist tests (31 tests)
• And more!

📖 Additional Documentation

• Todoist Setup Guide - Complete guide to configuring Todoist integration
• Todoist Implementation Plan - Technical roadmap and architecture
• Config Package - Configuration management documentation
• Todoist Package - Todoist API integration documentation
• MCP Package - Model Context Protocol server documentation
• Obsidian Plugin - Obsidian community plugin documentation

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and validation (pnpm validate)
5. Commit your changes (git commit -m 'Add some amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Code Quality

This project maintains high code quality standards:

• ✅ TypeScript with strict mode
• ✅ ESLint for code linting
• ✅ Prettier for code formatting
• ✅ Husky for git hooks
• ✅ lint-staged for pre-commit checks
• ✅ Comprehensive test coverage
• ✅ Smart CI - Skips code quality checks for docs-only changes (30s vs 90s)

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with Commander.js for CLI parsing
• Styled with Chalk for terminal colors
• Tables powered by cli-table3
• File scanning with fast-glob
• Date handling with date-fns
• AI integration powered by Model Context Protocol SDK by Anthropic

🗺️ Roadmap

• MCP (Model Context Protocol) integration - ✅ Complete! See MCP docs
• Configuration file support - ✅ Complete! Hierarchical config with .md2do.json/.yaml
• Todoist integration foundation - ✅ Complete! API client, task mapping, file writer
  • CLI commands (md2do todoist sync, md2do todoist push, etc.)
  • Bidirectional sync logic
  • Interactive token setup
  • Validation warnings for {todoist:ID} markers
    • Detect malformed IDs
    • Verify ID exists in Todoist
    • Warn about orphaned/deleted tasks

CLI Enhancements

• Markdown output format (--format markdown)
  • Machine-readable markdown with preserved metadata
  • Easy copy/paste to other markdown files
• Watch mode for continuous monitoring
• Custom output templates
• List all assignees/tags across files (md2do list --assignees, md2do list --tags)
  • Detect duplicates and near-matches (e.g., @nick vs @Nick)
  • Show usage frequency and statistics
• Edit support for normalizing metadata
  • Normalize assignees across files (fix capitalization inconsistencies)
  • Normalize tags (consolidate synonyms)
  • Interactive mode for reviewing and approving changes
  • --fix flag to auto-fix common issues
• Multiple value filters (--priority high,urgent, --tag backend,frontend)
• Negative filters (--no-assignee, --no-priority, --no-tags)
• Date range filtering (--due-after DATE, --due-before DATE)
• Result limiting (--limit N)
• Config inspection (md2do config show)
• Date simulation for testing (--simulate-date YYYY-MM-DD)

Configuration & Customization

• Granular warning control (.md2do-warnings.json similar to .markdownlint.json)
  • Enable/disable specific warning types
  • Warning severity levels
  • Per-project warning configuration
  • Warnings off by default, opt-in per project
• Configurable priority-based due date defaults
  • Customize default timeframes per priority level
  • Example: urgent=today, high=tomorrow, normal=end-of-week, low=next-week
  • Shared config between CLI and editor extensions
• Case-insensitive tags and assignees by default
  • Configurable case sensitivity
  • Canonical form preservation

Smart Features & Automation

• Due date inference based on priority
  • Optional auto-assignment when due date missing
  • Respects configured priority timeframes
• Multiple assignees support
  • Primary assignee (first @mention)
  • Secondary assignees (additional @mentions)
  • Filter by any assignee on task
• Enhanced date format support
  • Short formats: 1/25/26, 1/25
  • Natural language: tomorrow, next week, next Monday, in 3 days
  • Time of day: (2026-01-25 9am), (tomorrow 2pm)
  • ISO 8601 with time: 2026-01-25T14:00
• ML-powered suggestions
  • Suggest priority based on task content and patterns
  • Suggest tags based on task text
  • Suggest assignees based on historical patterns
• Auto-completion and smart defaults in VS Code extension
• Autocomplete suggestions for assignees and tags
  • Learn from existing usage across all files
  • Context-aware suggestions (file, project, recent usage)
  • Fuzzy matching and typo correction

Dashboard & Visualization

• Configurable dashboard with markdown templating
  • Leverage existing templating solution (investigate: Handlebars, Mustache, Liquid)
  • Customizable widgets and layouts
  • Export to HTML/PDF
• VS Code extension dashboard integration
  • Side panel with "pretty" dashboard view
  • Live updates as files change
  • Click-through to source tasks

VS Code Extension

• Core extension with task viewing and filtering
• IntelliSense for task metadata (@assignees, #tags, priorities)
• Due date auto-completion with smart defaults
• Quick actions (mark complete, change priority, set due date)
• Integrated dashboard view
• CodeLens showing task counts per file
• Autocomplete for assignees and tags (learned from workspace)
• Inline suggestions with fuzzy matching

Integrations

• GitHub Issues integration
• Linear integration
• Jira integration
• Notion integration

📞 Support

• 🐛 Report bugs
• 💡 Request features
• 📖 Documentation

---

Made with 🤖 + ❤️ by Nick Hart