Your markdown files are already your task system
CLI task manager where checkboxes in your .md files are the database.
Tasks live inside your PRDs, READMEs, and notes. No server, no GUI, no second system. Humans and AI agents read the same format.
npm install -g mdtask ; mdtask --help # Project
- [ ] MD-001 setup CI/CD @iter:mvp
Configure GitHub Actions for automated testing.
...
- [x] MD-002 basic cli
Initial implementation of the parser.
... # API
- [ ] API-010 Auth endpoint !high
Implement JWT authentication logic.
... $mdtask list ID TITLE PRI TAGS PROPS [ ] MD-001 setup CI/CD @iter:mvp [ ] API-010 Auth endpoint !high 2 tasks pending.
The format is everything
Every task is a markdown checkbox with an ID and inline metadata. Standard syntax, no extensions. Write it by hand, parse it with grep, read it with any LLM.
Status
ID
Title
Tags
Priority
Property
The Three Pains
AI Visibility
LLMs and AI agents can't "see" inside your Jira or Linear without complex API setups. If your tasks are in the file, the agent already knows what to do.
# claude / codex / opencode ❯Read docs/features/search.md and complete all marked #urgent
Zero Overhead
No new accounts. No "Second Brain" apps. If you have a code editor, you have a task manager. Tasks are version controlled with your code.
$git commit \
-m "feat: finish CORE-01" Single Source
Specs and backlogs stay in sync because they are the same document.
No more "the README says one thing, Jira says another."
# PRD - Search
- [ ] API-010 Pagination
Implement cursor-based pagination for results.
...
- [x] API-011 Filters
Filter by date and priority.
... Everything you need, nothing you don't
mdtask --help $ mdtask <command> [options]
list [...filters]List tasks view <id>View task details done <id>Toggle task done/open open <id>Open task in $EDITOR move <id> <file>Move task to another file validateCheck task integrity set <...args>Add metadata to tasks idsAuto-assign IDs to unidentified tasks Got questions?
Will my AI agent pick up tasks automatically?
Any agent that reads files in your repo already sees your tasks. Standard markdown — no setup, no MCP server needed. Point the agent at your .md file and it has the full backlog.
Does it work in an existing project?
Yes. mdtask scans all .md files recursively. Your current README, PRD, notes — if there's a checkbox, it's already a task. Run mdtask ids to assign IDs.
What happens when the project grows to hundreds of tasks?
CLI uses ripgrep under the hood — search is instant at any scale. Filter by #tag, !priority, or scope to specific directories with --path. mdtask validate catches integrity problems before they accumulate.
How do I sync across machines?
git push. All operations are text edits in files you already version-control.
Can multiple people work on the same task files?
Yes. Same as any markdown file in git — branch, edit, merge. Conflicts are human-readable text, not binary blobs.
Start with the files you already have
Navigate to any project with markdown files and run the indexer. It will find existing checkboxes and offer to ID them.
$cd my-project && npx mdtask ids Enter prefix for README.md: KTL - [ ] KTL-001 Basic boiling with auto shut-off - [ ] KTL-002 Tea presets with custom temperatures - [ ] KTL-003 Schedule boiling for morning routine