taskmd-mcp

taskmd

Markdown-based task management designed for both humans and AI coding assistants.

taskmd provides:

1. A standardized format for task files — Tasks stored as readable .md files with YAML frontmatter, version-controlled alongside your code
2. A CLI for managing them — Create, update, filter, validate, and visualize tasks from the terminal
3. A web dashboard for visualization — Kanban board, dependency graphs, and project metrics in your browser
4. A set of AI skills — Slash commands for AI assistants to create, update, and work through tasks
5. An MCP server exposing task management tools — Direct tool access for AI assistants via the Model Context Protocol

Everything runs locally. Task data stays in your repo and is never shared externally.

Quick Start

Installation

Option 1: Homebrew (macOS and Linux)

# Add the tap
brew tap driangle/tap

# Install taskmd
brew install taskmd

# Verify installation
taskmd --version

Option 2: Download Pre-built Binary

# Download from the releases page
# https://github.com/driangle/taskmd/releases

# Extract the archive
tar -xzf taskmd-v*.tar.gz  # or unzip for Windows

# Move to PATH
sudo mv taskmd /usr/local/bin/  # macOS/Linux

Option 3: Install with Go

go install github.com/driangle/taskmd/apps/cli/cmd/taskmd@latest

Option 4: Build from Source

git clone https://github.com/driangle/taskmd.git
cd taskmd/apps/cli
make build-full

Option 5: Docker

# Web dashboard (default)
docker run --rm -p 8080:8080 -v ./tasks:/tasks:ro ghcr.io/driangle/taskmd

# CLI commands
docker run --rm -v ./tasks:/tasks ghcr.io/driangle/taskmd taskmd list

30-Second Setup

1. Create a tasks directory:

   mkdir -p my-project/tasks
   cd my-project
   

2. Create your first task (tasks/001-first-task.md):

   ---
   id: "001"
   title: "My first task"
   status: pending
   priority: high
   ---
   
   # My First Task
   
   ## Objective
   This is my first task using taskmd!
   
   ## Tasks
   - [ ] Learn taskmd basics
   - [ ] Create more tasks
   

3. List your tasks:

   taskmd list tasks/
   

4. Launch the web interface:

   taskmd web start --open
   

That's it! You're ready to manage tasks with taskmd.

Usage

CLI Commands

# List tasks
taskmd list tasks/

# Validate task files
taskmd validate tasks/

# View task statistics
taskmd stats tasks/

# Find next task to work on
taskmd next tasks/

# Visualize dependencies
taskmd graph tasks/ --format ascii

# Start web interface
taskmd web start --dir tasks/ --open

Web Interface

Start the web server and open your browser:

taskmd web start --open --port 8080

The web interface provides:

• Task List: Sortable, filterable table view
• Board View: Kanban-style board with drag-and-drop
• Graph View: Interactive dependency visualization
• Statistics: Project metrics and progress tracking

Documentation

Read the full documentation →

• Quick Start Guide - Get productive in 5 minutes
• CLI Guide - Comprehensive CLI reference
• Web Interface - Web dashboard walkthrough
• Task Specification - Task file format reference
• FAQ - Frequently asked questions

Task Format

Tasks are markdown files with YAML frontmatter:

---
id: "001"
title: "Implement feature X"
status: pending
priority: high
effort: medium
dependencies: []
tags:
  - feature
  - backend
created: 2026-02-08
---

# Implement Feature X

## Objective
Build the new feature X that allows users to...

## Tasks
- [ ] Design API endpoints
- [ ] Implement backend logic
- [ ] Write tests
- [ ] Update documentation

## Acceptance Criteria
- All tests pass
- API documentation complete
- Performance meets requirements

See the Task Specification for complete format details.

Configuration

taskmd supports .taskmd.yaml configuration files for setting default options: