taskmd
Markdown-based task management designed for both humans and AI coding assistants.
taskmd provides:
- A standardized format for task files — Tasks stored as readable
.md files with YAML frontmatter, version-controlled alongside your code
- A CLI for managing them — Create, update, filter, validate, and visualize tasks from the terminal
- A web dashboard for visualization — Kanban board, dependency graphs, and project metrics in your browser
- A set of AI skills — Slash commands for AI assistants to create, update, and work through tasks
- 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
Homebrew (macOS and Linux)
brew tap driangle/tap
brew install taskmd
taskmd --version
Docker (CLI and web dashboard, nothing to install)
# Web dashboard
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
Go
go install github.com/driangle/taskmd/apps/cli/cmd/taskmd@latest
go install builds the CLI only; the web dashboard is not included because the
built frontend is not part of the Go module.
Pre-built binaries for Linux, macOS, and Windows, and building from source, are covered on the installation page.
30-Second Setup
-
Initialize taskmd in your project:
cd my-project
taskmd init # Creates tasks/, .taskmd.yaml, task templates, the spec, and an agent config file
-
Create your first task:
taskmd add "My first task" --priority high
-
List your tasks:
taskmd list
-
Launch the web interface:
taskmd web start --open
Tasks are plain markdown files under tasks/, so you can also create and edit them in your editor. The tutorial walks through dependencies, recommendations, and validation from here.
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 --task-dir tasks/ --open
Web Interface
taskmd web start --open
- Tasks: sortable, filterable table
- Board: kanban grouped by status, priority, effort, type, group, tag, or phase, with drag-and-drop
- Graph: interactive dependency graph
- Stats, Next, Tracks, Phases, Feed, Validate: one page each
The server binds 127.0.0.1 and the API is unauthenticated; before exposing it with --host 0.0.0.0, read Network Access in the web guide.
Claude Code Plugin
Use taskmd directly inside Claude Code with slash commands:
/taskmd:next-task # Find next task to work on
/taskmd:do-task 015 # Pick up and work on a task
/taskmd:list-tasks --status pending # List pending tasks
/taskmd:add-task Fix login bug # Create a new task
/taskmd:complete-task 015 # Mark a task done
/taskmd:validate-tasks # Validate task files
Three plugins are available. taskmd provides slash command skills that drive the CLI. taskmd-mcp provides an MCP server so Claude can call task operations as tools, and can be installed alongside taskmd. taskmd-lite re-implements the skills with Claude's file tools for environments where the binary cannot be installed. See the plugin guide for which to pick.
# Add the taskmd marketplace
claude plugin marketplace add driangle/taskmd
# Install slash command skills (/taskmd:do-task, /taskmd:next-task, etc.)
claude plugin install taskmd@taskmd-marketplace --scope project
# Optional: add the MCP server for direct tool access
claude plugin install taskmd-mcp@taskmd-marketplace --scope project
# Or, with no taskmd binary available:
claude plugin install taskmd-lite@taskmd-marketplace --scope project
See claude-code-plugin/README.md for full details.
Documentation
Read the full documentation →
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_at: 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:
# .taskmd.yaml - Place in project root or home directory
dir: ./tasks # Default task directory
web:
port: 8080 # Default web server port
auto_open_browser: true # Auto-open browser on web start
taskmd loads one config file: the nearest .taskmd.yaml walking up from the current directory to the repository root, else ~/.taskmd.yaml. The two are not merged, so a project file means the home file is ignored. Command-line flags and TASKMD_* environment variables override whatever the file says.
See docs/.taskmd.yaml.example for a complete example with all supported options.
Task Layout
my-project/
├── tasks/ # Task files
│ ├── 001-task.md
│ ├── 002-task.md
│ └── cli/ # Optional subdirectories
│ └── 003-task.md
└── .taskmd.yaml # Optional project config
Contributing
- CONTRIBUTING.md: what belongs in core, how to extend taskmd, and the PR process
- AGENTS.md: local setup, build and test commands, lint rules, and versioning (
CLAUDE.md is a symlink to it)
- Task Specification: task format conventions
cd apps/cli
make build # CLI only; make build-full embeds the web UI
make check # tests, lint, vet
License
MIT License - see LICENSE for details.
Support
