Web User Guide

April 19, 2026 · View on GitHub

Complete guide to using the taskmd web interface.

What You'll Learn

Starting the web server
Navigating the interface
Using all views (Tasks, Board, Graph, Stats, Next, Tracks, Phases, Feed, Validate)
Task editing, filtering, and searching
Static site export and read-only mode
API endpoints
Keyboard shortcuts
Live reload functionality

Getting Started

Starting the Web Server

Basic command:

taskmd web start

The server will start on http://localhost:8080.

With options:

# Auto-open browser
taskmd web start --open

# Custom port
taskmd web start --port 3000 --open

# Specific tasks directory
taskmd web start --task-dir ./my-tasks --open

# Development mode (CORS for Vite)
taskmd web start --dev

What you'll see:

Starting taskmd web server...
Server running at http://localhost:8080
Watching for changes in: ./tasks
Press Ctrl+C to stop

Accessing the Interface

Open your browser to:

Default: http://localhost:8080
Custom port: http://localhost:[port]

Or use --open flag to launch automatically.

Live Reload

The interface automatically updates when task files change:

Edit task files in your text editor
Save the file
Web interface updates immediately

No page refresh needed!

Interface Overview

The top navigation bar provides quick access to all views:

taskmd (logo) - Click to return to task list
Tasks - Main task list view
Board - Kanban board view
Graph - Dependency visualization
Stats - Project statistics
Next - Task recommendations
Tracks - Parallel work tracks
Phases - Project phase overview
Feed - Chronological activity feed
Validate - Task validation results

Views

1. Tasks View (Default)

URL: http://localhost:8080/tasks

The main task list in a sortable, filterable table.

Features:

Sortable columns (click headers)
Search/filter functionality
Status badges with colors
Priority indicators
Clickable task IDs and titles
Dependency counts

Columns:

ID - Task identifier (clickable)
Title - Task name (clickable)
Status - Current status with color badge
Priority - Priority level
Effort - Estimated effort
Tags - Task tags
Deps - Dependency count (clickable)

Sorting:

Click any column header to sort
Click again to reverse sort order
Default sort: by ID

Searching:

Use the search box at the top
Searches across: ID, title, tags
Real-time filtering as you type

Filtering:

Filter by status using dropdown
Filter by priority
Filter by tags
Combine multiple filters

Task Details:

Click task ID or title to view full details
See complete markdown content
View dependencies
Check subtasks

2. Board View (Kanban)

URL: http://localhost:8080/board

Visual board with tasks organized in columns.

Features:

Cards grouped by selected field
Column headers with task counts
Color-coded by status
Scroll horizontally for many columns

Grouping Options:

Use the "Group by" dropdown to organize by:

Status (default):

Columns: pending, in-progress, completed, blocked, cancelled
Color-coded for quick status overview
Standard kanban workflow

Priority:

Columns: critical, high, medium, low
Helps prioritize work visually
Identify high-priority tasks at a glance

Effort:

Columns: small, medium, large
Plan capacity and quick wins
Balance workload

Group:

Columns: task groups (e.g., cli, web, docs)
Organize by project area
Team-based views

Type:

Columns: feature, bug, chore, docs, test
Work type classification
Useful for balancing feature vs. maintenance work

Tag:

Columns: one per unique tag
Tasks may appear in multiple columns
Feature-based organization

Phase:

Columns: one per configured phase
Release and milestone planning
Track progress toward specific deliverables

Card Contents:

Task title (clickable)
Task ID
Priority (if set)
Click to view full details

Best for:

Visual project overview
Sprint planning
Status at a glance
Team standup discussions

3. Graph View

URL: http://localhost:8080/graph

Interactive dependency visualization using @xyflow/react (ReactFlow).

Features:

Visual dependency graph
Nodes represent tasks
Arrows show dependencies
Color-coded by status
Interactive exploration

Node Colors:

🟡 Yellow - pending
🔵 Blue - in-progress
🟢 Green - completed
🔴 Red - blocked

Interactions:

Hover - Highlight task
Click - View task details (future enhancement)
Pan - Drag to move view
Zoom - Mouse wheel or pinch

Understanding the Graph:

Arrows - Point from dependency to dependent
- Task A → Task B means B depends on A
Chains - Long paths show critical paths
Bottlenecks - Tasks with many outgoing arrows block others
Clusters - Groups of related tasks

Best for:

Understanding dependencies
Identifying critical paths
Finding blockers
Planning parallel work
Detecting circular dependencies

4. Stats View

URL: http://localhost:8080/stats

Project metrics and analytics.

Metrics Displayed:

Overview:

Total tasks
Completion rate (percentage)
Tasks by status breakdown
- Pending count
- In-progress count
- Completed count
- Blocked count

Priority Breakdown:

Tasks by priority level
Critical, high, medium, low counts
Distribution visualization

Effort Breakdown:

Tasks by effort estimate
Small, medium, large counts
Capacity planning data

Dependency Analysis:

Critical path length (longest chain)
Maximum dependency depth
Average dependencies per task
Blocked tasks count

Best for:

Project health checks
Progress tracking
Sprint retrospectives
Stakeholder reports
Capacity planning

5. Next View (Recommendations)

URL: http://localhost:8080/next

AI-powered task recommendations showing which tasks to work on next.

Features:

Ranked task cards with priority scores
Explains why each task is recommended (unblocked dependencies, priority, effort)
Critical path indicators for tasks on the longest dependency chain
Downstream task count showing how many tasks each recommendation unblocks

Scoring factors:

Priority level (critical > high > medium > low)
Critical path membership (+15 bonus)
Number of downstream tasks (+3 per task, max +15)
Effort (smaller tasks get a slight bonus)

Best for:

Deciding what to work on next
Identifying high-impact tasks
Understanding task priority reasoning

6. Tracks View

URL: http://localhost:8080/tracks

Parallel work tracks showing tasks grouped by scope overlap.

Features:

Tasks organized into independent work streams based on touches scopes
Tasks in the same track share scopes and should run sequentially
Tasks in different tracks can run in parallel
"Flexible" tasks (no scope constraints) listed separately
Warnings for unknown or misconfigured scopes

Best for:

Planning parallel development work
Avoiding merge conflicts
Team task assignment
Identifying independent work streams

7. Phases View

URL: http://localhost:8080/phases

Overview of project phases with progress tracking.

Features:

Phase cards showing task counts, completion percentages, and progress bars
Status badges summarizing pending, in-progress, and completed counts
Unphased tasks section showing tasks not assigned to any phase
Defined via the phases key in .taskmd.yaml

Best for:

Release planning
Milestone tracking
Sprint progress overview

8. Feed View

URL: http://localhost:8080/feed

Chronological activity feed showing recent task changes from git history and worklogs.

Features:

Source filter to show all activity, git commits only, or worklog entries only
Time range filter (24 hours, 7 days, 30 days, or all time)
Scope filter to narrow to a specific task group (e.g. cli)
Entries show timestamp, author, commit message or worklog note, and linked task IDs
Git entries display per-file changes with field change badges (e.g. status transitions) and subtask completions
Worklog entries are distinguished with a separate icon

Best for:

Reviewing recent project activity
Understanding what changed and when
Tracking teammate contributions
Daily standup preparation

9. Validate View

URL: http://localhost:8080/validate

Validation results for task files, showing errors and warnings.

Features:

Errors and warnings grouped by file
Checks for missing required fields, invalid enum values, broken dependencies, duplicate IDs, and circular dependencies
Error and warning counts displayed as summary

Best for:

Catching formatting issues
Finding broken dependencies
Ensuring task file consistency

10. Task Detail View

URL: http://localhost:8080/tasks/{id}

Full detail page for a single task.

Features:

Complete metadata panel (status, priority, effort, type, tags, owner, dependencies)
Rendered markdown body with full task description
Worklog timeline (if worklogs exist for the task)
Edit form for updating task fields directly in the browser
Edit button hidden in read-only mode

Best for:

Reading full task descriptions
Updating task fields without leaving the browser
Reviewing worklog history

Web Features

Task Editing

The web UI supports editing tasks directly from the browser.

Task Detail Edit Form:

Click the Edit button on any task detail page
Editable fields: title, status, priority, effort, type, owner, parent, tags, and body (markdown)
Only changed fields are sent to the server
Validation errors from the server are displayed inline

Board Drag-and-Drop:

Drag task cards between columns to update the grouping field
Supported when grouping by: status, priority, effort, or type
Drag-and-drop is disabled when grouping by group or tag
Visual feedback: columns highlight when dragging over

Both editing features are disabled when the server runs in --readonly mode.

Static Site Export

Generate a self-contained static site from your tasks:

# Export to default directory (./taskmd-export)
taskmd web export

# Custom output directory
taskmd web export -o ./public

# For subfolder deployment (e.g., GitHub Pages)
taskmd web export --base-path /demo/

The exported site includes all views with pre-rendered data. No backend server required — deploy to GitHub Pages, Netlify, S3, or any static host.

Read-Only Mode

Start the server in read-only mode to prevent any modifications:

taskmd web start --readonly

When enabled:

The task edit form is hidden
Board drag-and-drop is disabled
The PUT /api/tasks/{id} endpoint returns 403 Forbidden
All read operations work normally

Board Filters

The Board page includes interactive pill-based filters:

Status — pending, in-progress, completed, blocked, cancelled
Priority — critical, high, medium, low
Effort — small, medium, large
Type — feature, bug, chore, docs, test
Tags — autocomplete dropdown with all available tags

Multiple values can be selected per category. The filter row automatically hides the field being used for grouping.

Graph Search and Highlighting

The Graph page includes a search box for finding tasks in the dependency graph:

Searches task IDs and titles (case-insensitive, instant results)
Matched nodes are highlighted with a blue ring; unmatched nodes dim to 40% opacity
The viewport auto-zooms to fit all matched nodes
Match count displayed next to the search box

Common Workflows

Daily Task Management

Morning Check-in:

Open web interface: taskmd web start --open
Check Stats view for project health
Switch to Board view (Group by: priority)
Identify today's priorities
Click tasks to review details

During Work:

Edit task files in your editor
Mark status as in-progress
Check off subtasks as completed
Watch web interface update automatically

End of Day:

Review Board view
Update any task statuses
Check Stats for completion progress
Plan tomorrow's priorities

Weekly Planning

Monday Planning:

Launch web interface
Stats view - Review last week's progress
Board view - Group by priority
Graph view - Identify dependencies and blockers
Tasks view - Filter by status=pending and priority=high
Plan week's priorities

Friday Review:

Stats view - Check completion metrics
Board view - Group by status
Tasks view - Filter by status=completed
Celebrate wins!

Project Planning

Initial Planning:

Create task files with dependencies
Open web interface
Graph view - Visualize project structure
Identify critical path
Board view - Group by effort for capacity planning
Adjust priorities and dependencies as needed

Ongoing Management:

Tasks view - Regular task list reviews
Board view - Visual status tracking
Graph view - Dependency management
Stats view - Progress monitoring

Team Collaboration

Stand-ups:

Share screen with web interface
Board view - Group by status
Discuss in-progress and blocked tasks
Graph view - Discuss dependencies

Sprint Reviews:

Stats view - Show metrics
Tasks view - Filter by status=completed
Demonstrate completed work
Review velocity

Sprint Planning:

Graph view - Understand dependencies
Board view - Group by effort
Tasks view - Filter and prioritize
Assign tasks

Features in Detail

Task List Features

Search/Filter:

Search box: Type to filter by ID, title, or tags
Status dropdown: Filter by specific status
Priority filter: Show only high-priority tasks

Sorting:

Click column headers to sort
Supported columns: ID, Title, Status, Priority, Effort
Click again to reverse sort

Task Cards:

Compact view for many tasks
Color-coded status badges
Priority indicators
Dependency counts (click to see deps)

Clicking Tasks:

Click ID or title → Full task details
See complete markdown
View all metadata
Read acceptance criteria

Board Features

Group By Options:

Each grouping provides different insights:

Status - Progress tracking
- See work distribution
- Identify bottlenecks
- Standard kanban flow
Priority - Urgency planning
- Focus on critical tasks
- Balance priorities
- Emergency vs. planned work
Effort - Capacity planning
- Quick wins (small tasks)
- Major projects (large tasks)
- Sprint sizing
Group - Area organization
- Feature teams
- Project components
- Responsibility areas
Tag - Cross-cutting views
- Frontend vs. backend
- Bug vs. feature
- Client-specific work

Visual Design:

Color-coded columns (status grouping)
Card hover effects
Responsive layout
Horizontal scroll for many columns

Graph Features

Dependency Visualization:

See the full task network
Understand relationships
Identify critical paths
Spot potential issues

Color Coding:

Completed tasks (green)
In-progress tasks (blue)
Pending tasks (yellow)
Blocked tasks (red)

Use Cases:

Planning parallel work streams
Finding tasks that unblock others
Understanding project structure
Detecting circular dependencies

Stats Features

Key Metrics:

Completion Rate
- Percentage of completed tasks
- Overall project progress
- Velocity indicator
Status Distribution
- Work in progress
- Backlog size
- Blocked count
Priority Analysis
- Focus areas
- Risk assessment
- Planning data
Dependency Metrics
- Critical path length
- Project duration estimate
- Complexity indicators

Practical Use:

Daily health check
Weekly reviews
Stakeholder updates
Process improvements

Live Reload

How It Works

The server watches task files and sends updates via Server-Sent Events (SSE):

You edit a task file in your editor
Server detects the file change
Server sends event to browser
Browser refetches data automatically
UI updates without page refresh

What Triggers Reload

Creating new .md files in tasks directory
Modifying existing task files
Deleting task files
Moving tasks between directories

Troubleshooting Live Reload

If updates don't appear:

Check console (F12 → Console)
- Look for SSE connection messages
- Check for errors
Verify file save
- Ensure file is actually saved
- Some editors use temporary files
Check file location
- File must be in watched directory
- Subdirectories are watched
Refresh manually
- Press F5 if needed
- Should reconnect automatically

Restart server

# Stop with Ctrl+C, then restart
taskmd web start --open

Keyboard Shortcuts

Click links - Navigate between views
Browser back/forward - Navigate history
Ctrl+Click - Open in new tab

General

F5 - Refresh page (rarely needed with live reload)
F12 - Open developer tools
Ctrl+F - Find in page

Future Enhancements

Planned keyboard shortcuts:

j/k - Navigate tasks up/down
Enter - Open task details
/ - Focus search
Esc - Clear filters/search
g + t - Go to Tasks view
g + b - Go to Board view
g + g - Go to Graph view
g + s - Go to Stats view

Tips and Best Practices

Performance

Large Projects:

Web interface handles 100s of tasks well
Graph view may be slow with >200 tasks
Use filtering to reduce displayed tasks
Consider organizing tasks in subdirectories

Browser Recommendations:

Chrome/Edge - Best performance
Firefox - Good performance
Safari - Good performance
Use modern browser versions

Workflow Tips

1. Keep web interface open

Background tab stays updated
Quick reference while coding
Check progress easily

2. Use multiple views

Tasks for detailed work
Board for planning
Graph for architecture
Stats for reporting

3. Share with team

Run on shared server
Port forward for remote access
Use for demos and reviews

4. Combine with CLI

Use CLI for automation
Use web for exploration
Best of both worlds

Organization Tips

Tags for Grouping:

tags:
  - frontend
  - backend
  - database
  - docs

Then use Board view → Group by: tag

Consistent Naming:

Use standard status values
Use standard priority levels
Use consistent tag names

Dependencies:

Keep chains short
Use Graph view to verify
Break up long chains

The taskmd web server is available as a Docker image from GitHub Container Registry. The image includes the web frontend and defaults to running taskmd web start on port 8080. Mount your tasks directory to /tasks inside the container.

# Run the web dashboard with your local tasks directory
docker run -p 8080:8080 -v $(pwd)/tasks:/tasks ghcr.io/driangle/taskmd:latest

# Custom port
docker run -p 3000:3000 -v $(pwd)/tasks:/tasks ghcr.io/driangle/taskmd:latest web start --port 3000

# Read-only mode
docker run -p 8080:8080 -v $(pwd)/tasks:/tasks:ro ghcr.io/driangle/taskmd:latest web start --readonly

Docker Compose:

services:
  taskmd:
    image: ghcr.io/driangle/taskmd:latest
    ports:
      - "8080:8080"
    volumes:
      - ./tasks:/tasks

You can also use the Docker image to run any taskmd CLI command, not just the web server. For example: docker run -v $(pwd)/tasks:/tasks ghcr.io/driangle/taskmd:latest taskmd list

Troubleshooting

Server Won't Start

Error: "Port already in use"

# Check what's using the port
lsof -i :8080

# Use different port
taskmd web start --port 3000

Error: "Permission denied"

# Don't use privileged ports (< 1024)
# Use ports 3000-9999
taskmd web start --port 8080

No Tasks Showing

Check:

Correct directory: --task-dir ./tasks
Files have .md extension
Files have valid YAML frontmatter
Browser console for errors (F12)

Debug:

# Validate tasks from CLI
taskmd validate ./tasks

# Check verbose output
taskmd web start --verbose

Live Reload Not Working

Check browser console:

Press F12
Look for SSE connection messages
Check for errors

Try:

Refresh page (F5)
Restart server
Clear browser cache
Try different browser

Graph Not Rendering

Graph rendering issues:

Wait a few seconds (large graphs take time)
Check browser console for errors
Try a different browser
Reduce task count with filters

Page Loads Slowly

For large projects:

Use filters to reduce data
Organize tasks in subdirectories
Archive completed tasks
Check network tab (F12) for slow requests

Advanced Usage

Custom Port and Access

Local development:

taskmd web start --port 3000 --dev

Remote access:

# Start server
taskmd web start --port 8080

# Port forward via SSH
ssh -L 8080:localhost:8080 user@remote-host

# Access from local browser
open http://localhost:8080

Multiple Projects

Switch directories:

# Project 1
taskmd web start --task-dir ~/project1/tasks --port 8081

# Project 2
taskmd web start --task-dir ~/project2/tasks --port 8082

Use tabs in your browser to manage multiple projects.

Integration with Development

Auto-start with project:

Create a start-dev.sh script:

#!/bin/bash

# Start taskmd in background
taskmd web start --task-dir ./tasks &
TASKMD_PID=$!

# Start your app
npm run dev

# Cleanup on exit
trap "kill $TASKMD_PID" EXIT

Generate a static site:

# Export full dashboard as static site
taskmd web export -o ./public

# For subfolder deployment
taskmd web export --base-path /demo/

Generate JSON snapshot:

# Create JSON snapshot
taskmd snapshot --derived > public/tasks.json

# Share via any web server
python -m http.server 8000

Screenshots for Reports:

Open web interface
Navigate to desired view
Take screenshot (OS screenshot tool)
Include in documentation

Mobile Access

Mobile Browsers

The web interface works on mobile browsers:

Responsive design
Touch-friendly
Scrollable views

Best views for mobile:

Tasks - Works well, but table is wide
Board - Horizontal scroll, good for quick checks
Stats - Excellent on mobile
Graph - May be hard to read on small screens

Tips for mobile:

Use landscape mode for tasks view
Board view works well in portrait
Stats view is mobile-optimized
Graph view may need zoom

Method	Path	Description
`GET`	`/api/tasks`	List all tasks (excludes body content)
`GET`	`/api/tasks/{id}`	Get a single task with full body and worklog metadata
`GET`	`/api/tasks/{id}/worklog`	Get worklog entries for a task
`PUT`	`/api/tasks/{id}`	Update task fields (disabled in read-only mode)
`GET`	`/api/search?q=<query>`	Full-text search across task titles and bodies

View Endpoints

Method	Path	Description
`GET`	`/api/board?groupBy=<field>`	Tasks grouped by field (`status`, `priority`, `effort`, `type`, `group`, `tag`)
`GET`	`/api/graph`	Dependency graph as JSON (nodes and edges)
`GET`	`/api/graph/mermaid`	Dependency graph in Mermaid syntax (returns `text/plain`)
`GET`	`/api/stats`	Project statistics and metrics
`GET`	`/api/next?limit=<n>&filter=<expr>`	Scored task recommendations with reasons (filter is repeatable)
`GET`	`/api/tracks?filter=<expr>&scope=<s>&limit=<n>`	Parallel work tracks grouped by scope overlap
`GET`	`/api/feed?source=<s>&since=<d>&scope=<g>&limit=<n>`	Chronological activity feed from git and worklogs
`GET`	`/api/validate`	Validation errors and warnings for all tasks

Other Endpoints

Method	Path	Description
`GET`	`/api/projects`	List registered projects (for multi-project setups)
`GET`	`/api/config`	Server config (read-only status, version)
`GET`	`/api/events`	Server-Sent Events stream for live reload

Examples

# List all tasks
curl http://localhost:8080/api/tasks

# Get a single task with full body
curl http://localhost:8080/api/tasks/042

# Get worklog for a task
curl http://localhost:8080/api/tasks/042/worklog

# Update a task's status
curl -X PUT http://localhost:8080/api/tasks/042 \
  -H 'Content-Type: application/json' \
  -d '{"status": "in-progress"}'

# Search tasks
curl 'http://localhost:8080/api/search?q=authentication'

# Board grouped by priority
curl 'http://localhost:8080/api/board?groupBy=priority'

# Top 3 recommended tasks
curl 'http://localhost:8080/api/next?limit=3'

# Graph in Mermaid format
curl http://localhost:8080/api/graph/mermaid

# Parallel work tracks
curl http://localhost:8080/api/tracks

# Validation results
curl http://localhost:8080/api/validate

# SSE stream (keeps connection open)
curl -N http://localhost:8080/api/events

PUT /api/tasks/{id}

Send a JSON body with only the fields you want to change:

{
  "title": "Updated title",
  "status": "in-progress",
  "priority": "high",
  "effort": "small",
  "type": "bug",
  "owner": "alice",
  "parent": "010",
  "tags": ["backend", "urgent"],
  "body": "# Updated description\n\nNew content..."
}

Valid values:

status: pending, in-progress, in-review, blocked, completed, cancelled
priority: low, medium, high, critical
effort: small, medium, large
type: feature, bug, improvement, chore, docs

Returns the updated task detail on success, or a 400 with validation errors.

Use Cases

Custom automation
External integrations
Mobile app development
Reporting tools

Configuration

Config File

Configuration is supported via .taskmd.yaml. See the CLI Guide for full details.

# .taskmd.yaml
dir: ./tasks
web:
  port: 8080
  auto_open_browser: true

Command-Line Flags

# Set port and auto-open
taskmd web start --port 3000 --open --task-dir ./tasks

# Or create a shell alias
alias tmweb='taskmd web start --port 8080 --open --task-dir ./tasks'

Environment Variables

# Override directory
export TASKMD_DIR=./my-tasks

# Start server
taskmd web start

Getting Help

Resources

Quick Start Guide - Get started fast
CLI Guide - Command-line reference
Task Specification - Task format

Debugging

Browser Developer Tools:

Press F12
Check Console tab for errors
Check Network tab for failed requests
Check Application tab for SSE status

Server Logs:

# Run with verbose output
taskmd web start --verbose

# Check for errors in output

Reporting Issues

When reporting problems, include:

taskmd version: taskmd --version
Browser and version
Operating system
Error messages from console
Steps to reproduce

Future Features

Planned enhancements:

Dark mode - Theme toggle
Keyboard shortcuts - Power user features
Filtering UI - Advanced filter builder
Export from UI - Download reports
User preferences - Save view settings
Real-time collaboration - Multi-user support

Next: Explore CLI commands for automation.