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

``bash


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:

`markdown
- [ ] Implement user authentication @jane !!! #backend #auth (2026-01-20)
- [x] Write documentation @nick !! #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

$3

`bash
md2do list --assignee nick
`

$3

`bash
md2do list --priority urgent
`

$3

`bash
md2do list --overdue
`

$3

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

$3

`bash


Overall stats

md2do stats

Group by assignee

md2do stats --by assignee
`

$3

`bash


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:

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

⚙️ Configuration

Set up md2do with an interactive wizard:

`bash


Interactive setup

md2do config init

Or configure specific values

md2do config set workday.startTime "09:00"
md2do config set defaultAssignee "alice"

View current config

md2do config list
`

Quick config for common settings:

- Work hours (for time-based due dates)
- Default assignee (for filtering)
- Output preferences (format, colors)
- Warning levels (strict/recommended/off)

Full configuration guide →

🔄 Todoist Integration

Sync your markdown tasks with Todoist:

`bash


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:

`bash


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