mdboard

Git-based project management dashboard. Zero dependencies. Reads markdown files with YAML frontmatter and serves a visual kanban board, table view, milestone tracker, and metrics dashboard.

Built for AI-assisted workflows — the project/ directory is plain text that both humans and AI agents can read and update.

Quick Start

# Run instantly with npx
npx mdboard

# Or install globally
npm install -g mdboard
mdboard

CLI Commands

mdboard — Start Dashboard

Starts the HTTP server and opens the dashboard at http://localhost:3333.

mdboard                          # Serve current directory
mdboard --port 4000              # Custom port
mdboard --project /path/to/repo  # Specify workspace root

mdboard init — Scaffold Project

Creates a project/ directory with starter templates.

mdboard init

Creates:

project/
├── PROJECT.md      # Project overview
├── metrics.md      # Velocity tracking
├── milestones/     # Milestone directories go here
└── archive/        # Completed milestones/sprints

mdboard --help

Show usage information.

mdboard --version

Print version number.

Project Structure

mdboard reads a project/ directory with this structure:

project/
├── PROJECT.md                              # Project overview and current state
├── metrics.md                              # Velocity, quality, sprint health
├── milestones/
│   └── {milestone}/
│       ├── README.md                       # Milestone description, done criteria
│       ├── epics/
│       │   └── {epic}/
│       │       ├── README.md               # Epic description, dependencies
│       │       └── backlog/
│       │           └── FEAT-NNN-slug.md    # Feature specs with acceptance criteria
│       └── sprints/
│           └── {sprint}/
│               ├── plan.md                 # Sprint goal, feature list, dates
│               ├── board.md                # Kanban state
│               └── review.md              # Sprint retrospective
└── archive/                                # Completed milestones/sprints

Frontmatter Schemas

PROJECT.md

---
name: "Project Name"
description: "One-line description"
created: 2026-01-01
---

Feature (FEAT-NNN-slug.md)

---
id: FEAT-001
title: "Feature title"
epic: epic-name
milestone: mvp
status: backlog          # backlog | todo | in-progress | in-review | done | blocked
sprint: null
priority: high           # urgent | high | medium | low
points: 5
assigned: []
created: 2026-01-01
started: null
completed: null
---

Milestone README.md

---
id: mvp
title: "Minimum Viable Product"
status: active           # planned | active | completed
deadline: null
created: 2026-01-01
---

Epic README.md

---
id: epic-name
title: "Epic Title"
milestone: mvp
status: active           # active | completed | blocked
priority: high
dependencies: []
created: 2026-01-01
---

Sprint plan.md

---
id: sprint-001
milestone: mvp
status: active           # planned | active | completed | cancelled
goal: "Sprint goal"
start_date: 2026-01-01
end_date: 2026-01-15
planned_points: 12
completed_points: 0
features: [FEAT-001, FEAT-002]
---

Dashboard Views

• Board — Kanban board with drag-and-drop. Filter by priority, epic, milestone.
• Table — Sortable table of all features with filters.
• Milestones — Progress view per milestone with epic breakdowns.
• Metrics — Status breakdown, priority distribution, velocity, project health.

API Endpoints

The server exposes a JSON API:

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/project | Project metadata | | GET | /api/milestones | All milestones with progress | | GET | /api/epics | All epics with progress | | GET | /api/features | All features (filterable via query params) | | GET | /api/sprints | All sprints | | GET | /api/sprint | Active sprint with board | | GET | /api/metrics | Metrics data | | GET | /api/health | Project health summary | | GET | /api/events | SSE stream for live updates | | PATCH | /api/features/:id | Update feature fields | | PATCH | /api/epics/:id | Update epic fields | | PATCH | /api/milestones/:id | Update milestone fields | | PATCH | /api/sprints/:id | Update sprint fields |

AI Agent Integration

The project/ directory is designed to be read and updated by AI agents. Agents can:

1. Read PROJECT.md to understand project context
2. Scan features to find work items
3. Update feature status via file edits or the PATCH API
4. Create new features by writing markdown files
5. Use the API to query project state programmatically

License

MIT