Claude Task Master Visual Interface

A VS Code/Cursor extension that provides a rich visual interface for task-master-ai projects. Transform your task management workflow with intuitive tree views, progress tracking, and seamless IDE integration.

🎯 Purpose: This extension is designed as a pure enhancement to task-master-ai, providing a modern visual interface without competing with the original functionality. It requires an existing task-master-ai project and works alongside the CLI and MCP tools.

✨ Features

🌳 Visual Task Management

• Hierarchical Tree View: See all your tasks in an organized, expandable tree structure
• Dropdown Subtasks: Click to expand/collapse subtasks with visual progress indicators
• Smart Grouping: View tasks by status (Todo, In Progress, Completed, Blocked) or priority
• Progress Overview: Real-time completion statistics and visual progress bars

⚡ Robust Operation

• CLI Fallback System: Automatically falls back to task-master-ai CLI when MCP server is unavailable
• Real-time Updates: Auto-refresh when task files change
• Cross-platform: Works on Windows, macOS, and Linux
• Error Recovery: Graceful handling of all error scenarios

🎯 Productivity Features

• Context Menus: Right-click tasks for quick actions (edit, delete, change status, add subtasks)
• Smart Icons: Color-coded status and priority indicators
• Next Task Recommendations: AI-powered suggestions for what to work on next
• Search & Filter: Find tasks quickly by status, priority, or content
• Task Details: Rich detail views with implementation notes and test strategies

🛠️ Developer Experience

• Zero Configuration: Works immediately in any task-master-ai project
• Progressive Enhancement: Basic features without MCP, advanced features with MCP
• Comprehensive Testing: 87 tests with 100% pass rate
• Professional Documentation: Complete setup and usage guides

🚀 Quick Start

Prerequisites

1. Task Master AI: You need task-master-ai set up in your project
2. VS Code or Cursor: VS Code 1.70.0+ or Cursor IDE
3. Workspace: The extension works only in workspace/folder contexts (not single files)

⚠️ Important: This extension requires an existing task-master-ai project with a .taskmaster directory.

Installation

Option 1: From VS Code Marketplace (Recommended)

1. Open VS Code/Cursor
2. Go to Extensions (Ctrl+Shift+X)
3. Search for "Claude Task Master Visual Interface"
4. Click Install

Option 2: Install from VSIX

1. Download the latest .vsix file from releases
2. Open VS Code/Cursor
3. Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (macOS)
4. Type "Extensions: Install from VSIX"
5. Select the downloaded .vsix file

Setup

1. Initialize Task Master AI in your project:

   # Via CLI
   npx task-master-ai init
   
   # Or via Claude AI chat (if MCP is set up)
   "Initialize task-master-ai in my project"
   

2. Open your project in VS Code/Cursor

3. Look for the Claude Task Master panel in the sidebar - it should appear automatically if a .taskmaster directory is detected

🔧 Configuration

Basic Configuration

The extension can be configured via VS Code settings:

{
  "claudeTaskMaster.autoRefresh": true,
  "claudeTaskMaster.taskmasterPath": ".taskmaster",
  "claudeTaskMaster.developmentMode": false,
  "claudeTaskMaster.enableLogging": false,
  "claudeTaskMaster.enableFileLogging": false
}

Settings Reference

MCP Server Configuration (Optional)

For advanced features like AI-powered task expansion, set up the MCP server:

1. Copy the MCP configuration:

   cp .cursor/mcp.json.example .cursor/mcp.json
   

2. Add your API keys:

   {
     "mcpServers": {
       "task-master-ai": {
         "command": "npx",
         "args": ["-y", "--package=task-master-ai", "task-master-ai"],
         "env": {
           "ANTHROPIC_API_KEY": "your-actual-key-here",
           "PERPLEXITY_API_KEY": "your-actual-key-here"
         }
       }
     }
   }
   

3. Restart VS Code/Cursor

📋 For detailed setup instructions, see SETUP_ENVIRONMENT.md
🔒 For security guidelines, see SECURITY.md

📖 Usage Guide

Tree View Navigation

The extension organizes tasks in a hierarchical structure:

📊 Progress Overview
   ├── Total Tasks: 12
   ├── ✅ Completed: 8 (67%)
   ├── 🔄 In Progress: 2 (17%)
   ├── ⭕ Todo: 1 (8%)
   └── ❌ Blocked: 1 (8%)

📋 Todo (1)
   └── 🔴 001: Set up authentication system [HIGH] ▶

🔄 In progress (2)
   ├── 🟡 002: Implement user dashboard ↳ 1 deps ▶
   └── 🔴 003: Add payment integration [CRITICAL] ▶

✅ Completed (8)
   ├── ✅ 004: Design wireframes
   └── ... (more completed tasks)

Working with Tasks

Viewing Task Details

• Single Click: Select a task to see basic information
• Right Click → Show Task Details: View comprehensive task information
• Expand Arrow (▶): Click to show/hide subtasks

Quick Actions

• Right-click any task for context menu:
  • 📋 Show Task Details
  • ▶️ Start Working
  • ✅ Mark Completed / 🔄 Mark In Progress / ⭕ Mark Todo / ❌ Mark Blocked
  • ➕ Add Subtask
  • 🔧 Expand Task (break into subtasks)
  • ✏️ Edit Task / Edit Title
  • 🔗 Set Dependencies
  • 📋 Copy Task Details
  • 🗑️ Delete Task

Status Management

• Use context menu or toolbar buttons to change task status
• Visual indicators show current status:
  • ⭕ Todo: Ready to work on
  • 🔄 In Progress: Currently being worked on
  • ✅ Completed: Finished and verified
  • ❌ Blocked: Cannot proceed due to dependencies

Keyboard Shortcuts

Advanced Features

Task Expansion (Requires MCP)

• Right-click a complex task → "Expand Task"
• The extension will use AI to break down the task into manageable subtasks
• Each subtask gets implementation details and test strategies

Next Task Recommendations

• Click the "Next Task" button in the toolbar
• The extension analyzes dependencies and priorities to suggest what to work on next
• Helps maintain optimal workflow and avoid dependency conflicts

Search and Filtering

• Use the search icon in the toolbar
• Filter by status, priority, or text content
• Quickly find specific tasks in large projects

🔄 CLI Fallback System

The extension includes a robust CLI fallback system that ensures full functionality even when the MCP server is unavailable:

How It Works

1. Automatic Detection: The extension detects when MCP server is unavailable
2. Seamless Fallback: Automatically switches to CLI commands
3. Full Functionality: All operations work via CLI fallback

Supported Operations

• ✅ Add Task → npx task-master-ai add-task
• ✅ Add Subtask → npx task-master-ai add-subtask
• ✅ Set Status → npx task-master-ai set-status
• ✅ Update Task → npx task-master-ai update-task
• ✅ Expand Task → npx task-master-ai expand

Performance Notes

• MCP Operations: Fast (< 1 second)
• CLI Operations: Slower (2-5 seconds) but reliable
• No Broken Functionality: Everything works regardless of MCP status

🏗️ Contributing

We welcome contributions! This extension is designed to enhance the task-master-ai ecosystem.

Development Setup

1. Clone the repository:

   git clone https://github.com/DevDreed/claude-task-master-extension.git
   cd claude-task-master-extension
   

2. Install dependencies:

   npm install
   

3. Set up test environment:

   # Create a test project with task-master-ai
   mkdir test-project
   cd test-project
   npx task-master-ai init
   cd ..
   

4. Open in VS Code:

   code .
   

5. Run the extension:

   • Press F5 to launch Extension Development Host
   • Open your test project in the new window
   • The extension should activate automatically

Development Commands

# Compile TypeScript
npm run compile

# Watch for changes (development)
npm run watch

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Package extension
npm run package

Testing

The extension has comprehensive test coverage:

• 87 tests covering all major functionality
• 100% pass rate with robust error handling
• Mock frameworks for isolated testing
• Cross-platform compatibility testing

# Run all tests
npm test

# Run specific test suite
npm test -- --grep "TaskProvider"

# Generate coverage report
npm run test:coverage

Code Quality

We maintain high code quality standards:

• TypeScript with strict type checking
• ESLint for code style consistency
• Comprehensive error handling
• Performance optimization
• Security best practices

Contribution Guidelines

1. Fork the repository and create a feature branch
2. Write tests for new functionality
3. Ensure all tests pass: npm test
4. Follow TypeScript best practices
5. Update documentation as needed
6. Submit a Pull Request with clear description

Areas for Contribution

• 🎨 UI/UX Improvements: Enhanced styling, animations, accessibility
• ⚡ Performance: Optimization for large task lists
• 🔌 Integrations: Additional IDE features, external tool integrations
• 🧪 Testing: Additional test scenarios, edge cases
• 📖 Documentation: Examples, tutorials, use cases
• 🌐 Internationalization: Multi-language support

Code of Conduct

• Be respectful and inclusive
• Focus on constructive feedback
• Help maintain a welcoming community
• Follow the project's coding standards

🛠️ Troubleshooting

Common Issues

Extension Not Activating

• ✅ Ensure you have a .taskmaster directory in your workspace
• ✅ Try running task-master-ai init in your project
• ✅ Restart VS Code/Cursor
• ✅ Check the Output panel for error messages

Tasks Not Displaying

• ✅ Verify tasks.json exists in .taskmaster/tasks/
• ✅ Check file permissions
• ✅ Try refreshing the tree view (refresh button)
• ✅ Enable development mode for detailed logging

MCP Features Not Working

• ✅ Verify MCP configuration in .cursor/mcp.json
• ✅ Check API keys are properly set
• ✅ Restart VS Code/Cursor after MCP changes
• ✅ Check if CLI fallback is working instead

Performance Issues

• ✅ Disable auto-refresh if you have many tasks: "claudeTaskMaster.autoRefresh": false
• ✅ Check for very large task files
• ✅ Enable development mode to identify bottlenecks

Getting Help

1. Check the documentation: SETUP_ENVIRONMENT.md, SECURITY.md
2. Search existing issues: GitHub Issues
3. Enable debug logging: Set "claudeTaskMaster.developmentMode": true
4. Create an issue: Include VS Code version, extension version, and error messages

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• task-master-ai: The core task management system this extension enhances
• VS Code Team: For the excellent extension API and development tools
• Community Contributors: Thank you to everyone who helps improve this extension

📊 Project Status

• ✅ Stable Release: Version 1.0.0 ready for production use
• ✅ Comprehensive Testing: 87 tests with 100% pass rate
• ✅ Professional Documentation: Complete setup and usage guides
• ✅ Cross-platform Support: Windows, macOS, Linux
• ✅ Active Development: Regular updates and feature additions

Ready for production use in professional development workflows.

Made with ❤️ for the task-master-ai community