TaskMaster Visualizer

Interactive mind map visualization for TaskMaster projects. Visualize task hierarchies, dependencies, and progress with an intuitive web interface.

Built for TaskMaster by @eyaltoledano & @RalphEcom

Quick Start

npx tmvisuals

This will automatically build and start the visualizer at http://localhost:3001. Use the file browser to navigate to your TaskMaster project directory.

Features

• Interactive Mind Maps: ReactFlow-based visualization of task relationships
• Hierarchy Support: Parent tasks with subtask progress tracking
• Dependency Visualization: Animated connections showing task dependencies
• Status Management: Visual indicators and status updates
• Editor Integration: Open tasks directly in VSCode or Cursor
• Multiple Layouts: Grid view for organization, graph view for dependencies
• Cross-Platform: File browser works on Windows, macOS, and Linux
• Theme Support: Light, dark, and system theme options

Screenshots

Requirements

• Node.js 16+
• A TaskMaster project with tasks stored in .taskmaster/tasks/tasks.json.
• Legacy tasks/tasks.json projects are still supported but will be migrated in a future release.
• Individual task_*.txt files are also supported.

Installation Options

NPX (Recommended)

npx tmvisuals                # Latest version
npx tmvisuals --port 8080    # Custom port

Global Installation

npm install -g tmvisuals
tmvisuals

Local Development

git clone https://github.com/zudsniper/tmvisuals.git
cd tmvisuals
npm install
npm run dev:full

TaskMaster Integration

This visualizer is designed specifically for TaskMaster projects. TaskMaster generates structured task files that this tool can visualize.

Supported Task Formats

tasks.json Format (Primary):

{
  "tasks": [
    {
      "id": 1,
      "title": "Task Title",
      "description": "Task description",
      "status": "pending",
      "priority": "high",
      "dependencies": [2, 3],
      "subtasks": [...]
    }
  ]
}

Individual Files: task_001.txt, task_002.txt, etc.

Usage

1. Start the visualizer: npx tmvisuals
2. Navigate to your project: Use the file browser to find your TaskMaster project
3. Load tasks: Click "Load Tasks" when you reach the project directory
4. Interact: Click nodes for details, drag to reposition, update status

Layout Modes

• Grid Layout: Organized grid view, ideal for task lists
• Graph Layout: Timeline-based dependency flow, shows relationships

Status Management

Update task status directly in the interface:

• Pending (gray)
• In Progress (blue)
• Done (green)

Command Line Options

tmvisuals --help          # Show help
tmvisuals --version       # Show version
tmvisuals --port 3002     # Custom port

Configuration

Tasks are now stored in .taskmaster/tasks/tasks.json; legacy tasks/tasks.json projects are still supported but will be migrated in a future release. AI model configuration is loaded from .taskmaster/config.json.

The visualizer remembers your preferences:

• Selected layout mode
• Theme preference
• Editor choice (VSCode/Cursor)
• Custom node positions

Environment Variables

You can customize ports and other settings using environment variables. Copy .env.example to .env and modify as needed:

# Backend API Server Port (default: 3001)
PORT=3001

# Frontend Development Server Port (default: 5550) 
VITE_PORT=5550

# Alternative backend port specification
API_PORT=3001

# Node Environment
NODE_ENV=development

Examples:

# Start backend on custom port
PORT=8080 npm run server

# Start frontend dev server on custom port
VITE_PORT=3000 npm run dev

# Start both with custom ports
PORT=8080 VITE_PORT=3000 npm run dev:full

Troubleshooting

"No Tasks Found" Error

If you see the "No Tasks Found" message, follow these steps:

1. Check Project Structure

Ensure your project has this structure:

your-project/
├── tasks/
│   ├── tasks.json     # Primary format
│   │                  # OR
│   ├── task_001.txt   # Individual files
│   ├── task_002.txt
│   └── ...
└── other project files

2. Quick Setup Options

When no tasks are found, the visualizer provides several options:

• Create Sample Tasks: Automatically generates example tasks in your project
• Download Template: Get a tasks.json template to customize
• Select Different Folder: Choose a different project directory
• View Documentation: Access this README and setup guides

3. Manual Setup

Create a tasks/tasks.json file with this structure:

{
  "tasks": [
    {
      "id": 1,
      "title": "Setup Project",
      "description": "Initialize the project structure",
      "status": "done",
      "priority": "high",
      "dependencies": [],
      "subtasks": [
        { "id": 1, "title": "Create directory", "status": "done" },
        { "id": 2, "title": "Initialize files", "status": "done" }
      ]
    },
    {
      "id": 2,
      "title": "Development",
      "description": "Main development tasks",
      "status": "in-progress",
      "priority": "medium",
      "dependencies": [1],
      "subtasks": [
        { "id": 1, "title": "Plan features", "status": "done" },
        { "id": 2, "title": "Implement core", "status": "in-progress" },
        { "id": 3, "title": "Testing", "status": "pending" }
      ]
    }
  ]
}

Common Issues

Permission Errors

• Windows: Run as Administrator if needed
• macOS/Linux: Check file permissions with ls -la
• Solution: Ensure read access to the project directory

Invalid JSON Format

• Error: "Invalid task file format"
• Solution: Validate your JSON at jsonlint.com
• Tip: Use the "Download Template" button for a valid starting point

Server Connection Issues

• Error: "Connection error"
• Check: Is the server running on the correct port?
• Solution: Restart with npx tmvisuals --port 3001

Live Updates Not Working

• Check: File watcher permissions
• Solution: Refresh manually or restart the application
• Note: Live updates require a valid tasks/ directory

Getting Help

If you're still having issues:

1. Use the Feedback System: Click "Having trouble? Send feedback" in the app
2. Check TaskMaster Documentation: TaskMaster Repository
3. Open an Issue: Create an issue with:
   • Your operating system
   • Node.js version (node --version)
   • Project structure
   • Error messages

Task File Formats

tasks.json (Recommended)

Complete task definitions with all features:

• Dependencies
• Subtasks
• Priorities
• Custom metadata

Individual Files

Alternative format for simple projects:

• task_001.txt: First line is title, rest is description
• task_002.md: Markdown format supported
• Automatically generates basic task structure

API Endpoints

• GET /api/health - Health check
• GET /api/browse?dir=path - Browse directories
• GET /api/tasks?projectPath=path - Load TaskMaster tasks
• GET /api/drives - Get system drives

Development

Local Development

npm run dev:full     # Start both frontend and backend
npm run dev          # Frontend only (port 5173)
npm run dev:server   # Backend only (port 3001)

Building

npm run build        # Build for production
npm run preview      # Preview production build

Technology Stack

• Frontend: React 18, TypeScript, Tailwind CSS
• Visualization: ReactFlow 11
• State Management: Zustand
• Backend: Express.js, Node.js
• Build: Vite

Contributing

Contributions welcome! This project visualizes TaskMaster data - for the core task management system, see TaskMaster.

Credits

• TaskMaster: @eyaltoledano & @RalphEcom - Repository
• Visualizer: @zudsniper - Repository

License

MIT License - see LICENSE for details.

Links

• TaskMaster: https://github.com/eyaltoledano/claude-task-master
• Visualizer: https://github.com/zudsniper/tmvisuals
• NPM Package: https://www.npmjs.com/package/tmvisuals