md2do

Turn your markdown files into a powerful task management system.

md2do scans your markdown notes for TODO items and gives you a CLI to filter, sort, and sync them with Todoist. Perfect for developers who live in plain text but want the power of a real task manager.

⚡ Quick Start

# Try it instantly (no install required)
npx @md2do/cli list

# Or install globally
npm install -g @md2do/cli
md2do list

That's it! md2do will scan all .md files in your current directory and show you all your tasks.

✨ Features

• 📝 Markdown-native - Works with standard - [ ] task syntax
• 🔍 Smart parsing - Extracts assignees (@user), priorities (!!!), tags (#tag), due dates
• 🎯 Powerful filtering - Filter by any metadata, combine multiple filters
• 📊 Rich statistics - View task breakdowns by assignee, priority, project
• 🎨 Beautiful output - Color-coded, clickable file paths, multiple formats (pretty/table/JSON)
• 🔄 Todoist sync - Two-way sync foundation with Todoist API
• 🤖 AI-powered - MCP server for Claude Code integration
• ⚡ Fast - Built with TypeScript and fast-glob

📖 Task Format

md2do recognizes standard markdown tasks with optional metadata:

- [ ] Implement user authentication @nick !!! #backend #auth (2026-01-20)
- [x] Write documentation @jane !! #docs (2026-01-15)
- [ ] Fix bug in parser @alex ! #bug (2026-01-18)

Metadata:

• @username - Assignee
• !!! / !! / ! - Priority (urgent/high/normal)
• #tag - Tags
• (YYYY-MM-DD) - Due date
• [todoist:ID] - Todoist sync marker

🎯 Common Use Cases

Filter tasks by assignee

md2do list --assignee nick

Show only urgent tasks

md2do list --priority urgent

Find overdue tasks

md2do list --overdue

Combine multiple filters

md2do list --assignee nick --priority urgent --tag backend

View task statistics

# Overall stats
md2do stats

# Group by assignee
md2do stats --by assignee

Different output formats

# Pretty format (default)
md2do list

# Table format
md2do list --format table

# JSON for scripting
md2do list --format json

📁 Context-Aware

md2do automatically extracts context from your folder structure:

projects/
  acme-app/              # Project: acme-app
    sprint-planning.md
    bugs.md
1-1s/
  nick.md                # Person: nick
  jane.md                # Person: jane

Then filter by context:

md2do list --project acme-app
md2do list --person jane

🔄 Todoist Integration

Sync your markdown tasks with Todoist:

# Import a specific task to Todoist
md2do todoist import tasks.md:15

# Sync completion status (dry run first)
md2do todoist sync --dry-run
md2do todoist sync

Full Todoist setup guide →

🤖 AI Integration (MCP)

Use Claude Code or other AI assistants to query your tasks through the Model Context Protocol:

# Build and configure the MCP server
npm install -g @md2do/mcp

Then ask Claude:

• "What urgent tasks does @nick have?"
• "Generate my daily standup report"
• "Show me task breakdown by project"

Full MCP setup guide →

📚 Full Documentation

This README covers the basics. For complete documentation:

• Full Documentation - Complete guide, examples, and tutorials
• GitHub Repository - Source code, issues, contributions
• CLI Reference - All commands and options
• Configuration Guide - Config file setup

🤝 Contributing

Contributions are welcome! Please see our Contributing Guide.

📄 License

MIT © Nick Hart

Made with ❤️ for developers who love markdown

Report Bug • Request Feature • Documentation