Introduction
A CLI tool that stores your entire project — issues, milestones, docs — as plain markdown files in a .mdp/ folder. No database, no server. Just files on disk that you can read, edit, and commit with git.
All Data is Stored Locally as Files
project-root/
└── .mdp/
├── project.json
├── issues/
│ ├── ISS-1-add-authentication/
│ │ └── ISS-1-add-authentication.md
│ └── ISS-2-database-schema/
│ └── ISS-2-database-schema.md
├── milestones/
│ └── M-1-v1-release/
│ └── M-1-v1-release.md
├── docs/
└── templates/Each issue and milestone lives in its own folder. The folder can hold extra files — screenshots, design docs, logs — alongside the main markdown file.
What’s in a File
Every issue is a markdown file with YAML frontmatter for structured fields and a free-form body:
---
id: ISS-2
title: Implement JWT tokens
type: task
status: In Progress
priority: High
labels:
- backend
- security
assignee: agent-1
milestone: M-1
checklist:
- text: Access token generation
done: true
- text: Refresh token rotation
done: false
---
Implement JWT-based authentication with access and refresh tokens.See Issues for the full field reference, file naming rules, and all commands. Milestones follow the same structure — grouping issues toward a shared goal.
Designed for AI Agents
The CLI is non-interactive. All input comes from flags and stdin, all output is structured JSON. This makes it ideal for AI agents and automation that need to manage project state programmatically.
- Markdown is the source of truth. All project state lives in
.mdp/as human-readable files. - Git-compatible by design. File-per-issue storage means clean diffs, meaningful merge conflicts, and natural branch-based workflows.
- Convention over configuration. Presets populate your configuration at project creation, so you can start immediately.
JSON Output
All commands return a JSON envelope:
// Success
{
"ok": true,
"data": { ... },
"warnings": []
}
// Error (written to stderr)
{
"ok": false,
"error": {
"code": "ISSUE_NOT_FOUND",
"message": "Issue ISS-42 not found",
"details": { "id": "ISS-42" }
}
}The warnings array contains non-fatal issues. Table format is available via --format table.
Exit Codes
Command Groups
- Projects —
project create,add,list,remove,tag,settings,stats,fix - Issues —
issue create,list,get,update,delete,log {add,list,get,update,delete},batch-create,batch-update - Milestones —
milestone create,list,get,update,delete,progress,log {add,list,get,update,delete}
Last updated on