@nelsonkwesi/track-master NPM

Track Master

By Nelson Anane

A fork of Task Master by @eyaltoledano & @RalphEcom with enhanced Supabase integration and centralized backend.

A task management system for AI-driven development with Claude, designed to work seamlessly with Cursor AI. Features Supabase integration for cloud synchronization and multi-device support!

Requirements

Anthropic API key (Claude API)
OpenAI SDK (for Perplexity API integration, optional)
Supabase account and project (for cloud sync, optional)

See API-KEYS.md for detailed instructions on setting up required API keys.

Quick Start

Option 1 | MCP (Recommended):

MCP (Model Control Protocol) provides the easiest way to get started with Track Master directly in your editor.

Add the MCP config to your editor (Cursor recommended, but it works with other text editors):

{
	"mcpServers": {
		"track-master": {
			"command": "npx",
			"args": ["-y", "--package=track-master", "track-master-mcp"],
			"env": {
				"ANTHROPIC_API_KEY": "YOUR_API_KEY_HERE",
				"PERPLEXITY_API_KEY": "YOUR_API_KEY_HERE",
				"MODEL": "claude-3-7-sonnet-20250219",
				"PERPLEXITY_MODEL": "sonar-pro",
				"MAX_TOKENS": "64000",
				"TEMPERATURE": "0.2",
				"DEFAULT_SUBTASKS": "5",
				"DEFAULT_PRIORITY": "medium"
			}
		}
	}
}

Enable the MCP in your editor
Prompt the AI to initialize Task Master:

Can you please initialize taskmaster-ai into my project?

Use common commands directly through your AI assistant:

Can you parse my PRD at scripts/prd.txt?
What's the next task I should work on?
Can you help me implement task 3?
Can you help me expand task 4?

Option 2: Using Command Line

Installation

# Install globally
npm install -g task-master-ai

# OR install locally within your project
npm install task-master-ai

Initialize a new project

# If installed globally
task-master init

# If installed locally
npx task-master-init

This will prompt you for project details and set up a new project with the necessary files and structure.

Common Commands

# Initialize a new project
task-master init

# Parse a PRD and generate tasks
task-master parse-prd your-prd.txt

# List all tasks
task-master list

# Show the next task to work on
task-master next

# Generate task files
task-master generate

Features

🤖 AI-Driven Task Management: Generate tasks from PRDs, break them down, and analyze complexity
☁️ Cloud Synchronization: Sync your tasks across devices with Supabase integration

Supabase Integration

Track Master includes robust Supabase integration for cloud synchronization and multi-device support!

Quick Setup

Set up environment variables in your .env file:

# Supabase Configuration - Choose one of these authentication methods:

# Option 1: Anon key with authentication (recommended, respects RLS)
SUPABASE_URL=https://your-project-id.supabase.co
SUPABASE_KEY=your-anon-public-key
ENABLE_SUPABASE_SYNC=true

# Option 2: Service role key (bypasses RLS, use cautiously)
SUPABASE_URL=https://your-project-id.supabase.co
SUPABASE_SECRET_KEY=your-service-role-key
ENABLE_SUPABASE_SYNC=true

Authenticate with Supabase (only needed for anon key method):

./tm-login

Sync your tasks:

# Standard bidirectional sync (recommended)
node sync-tasks.js

# Force push local tasks to Supabase
node sync-tasks.js push

# Force pull tasks from Supabase to local
node sync-tasks.js pull

# Direct sync script with enhanced field mapping
node sync-to-supabase.js

Valid Status Values

Track Master automatically maps task status values to compatible values in your Supabase database:

Local Status	Supabase Status
'pending'	'pending'
'in-progress'	'in_progress'
'done'	'done'
'canceled'	'cancelled'
'todo'	'pending'

For detailed instructions on setting up Supabase, see the Supabase Integration Guide.

Documentation

For more detailed information, check out the documentation in the docs directory:

Installation
Usage
Commands
Configuration
API Reference
Supabase Integration
Tutorial - Step-by-step guide to getting started with Task Master
Command Reference - Complete list of all available commands
Task Structure - Understanding the task format and features
Example Interactions - Common Cursor AI interaction examples

Troubleshooting

If `task-master init` doesn't respond:

Try running it with Node directly:

node node_modules/claude-task-master/scripts/init.js

Or clone the repository and run:

git clone https://github.com/eyaltoledano/claude-task-master.git
cd claude-task-master
node scripts/init.js

Contributors

Star History

Licensing

Task Master is licensed under the MIT License with Commons Clause. This means you can:

✅ Allowed:

Use Task Master for any purpose (personal, commercial, academic)
Modify the code
Distribute copies
Create and sell products built using Task Master

❌ Not Allowed:

Sell Task Master itself
Offer Task Master as a hosted service
Create competing products based on Task Master

See the LICENSE file for the complete license text and licensing details for more information.

vibe-task-master

Supabase Setup

To use Track Master with Supabase, you need to set up the proper environment variables.

Required Environment Variables

Create a .env file in the root directory with the following variables:

SUPABASE_URL=your-supabase-project-url
SUPABASE_KEY=your-supabase-anon-key
ENABLE_SUPABASE_SYNC=true

Service Role Key for CLI (Required)

Because the Track Master CLI accesses Supabase directly (unlike a web app), you need to provide a service role key to bypass Row Level Security (RLS) policies:

Go to your Supabase dashboard at https://app.supabase.com
Select your project
Go to "Project Settings" > "API"
Under "Project API keys", copy the "service_role" key (not the anon/public key)
Add it to your .env file:

SUPABASE_SECRET_KEY=your-service-role-key

Important security note: The service role key has full access to your database and bypasses RLS. Never expose this key in client-side code or check it into version control. It should only be used for server-side or local CLI applications.

Automatic Setup

Run the following command to automatically configure your Track Master environment:

node final-solution.js

This will guide you through setting up the necessary configuration.

Field Mapping

Valid Status Values

Through testing, we've confirmed that the following status values are accepted by your Supabase schema:

Local Status	Supabase Status
'pending'	'pending'
'in-progress'	'in_progress'
'done'	'done'
'canceled'	'cancelled'

Note: The value 'todo' is NOT a valid status in your Supabase schema. The CLI automatically maps 'todo' to 'pending' behind the scenes.

When syncing tasks between Track Master and Supabase, the following field mappings are applied:

Status Field

Track Master Status → Supabase Status
------------------------------------
pending           → todo
in-progress       → in_progress
done              → done

Priority Field

Track Master Priority → Supabase Priority
--------------------------------------
low                 → 1
medium              → 2
high                → 3
critical            → 4

These mappings ensure compatibility between the CLI tool and your existing web application.

Resolving Supabase Issues

Fixed Issues

Wrong Table Reference: Updated adapter to use project_tasks table instead of tasks
Field Types: Fixed priority and status fields to use text values instead of numbers:
- Priority: Used text values ('low', 'medium', 'high') instead of numbers
- Status: Ensured only valid status values ('todo', 'in_progress', 'done', 'cancelled') are used
Row Level Security (RLS): Used service role key for CLI tool while maintaining RLS in web app
Schema Compatibility: Adapted CLI schema to match exactly what the web app uses

Required Setup

Service Role Key: The CLI tool requires a service role key to bypass RLS policies
- Add this to your .env file: SUPABASE_SECRET_KEY=your-service-role-key
- You can get this from your Supabase dashboard: Project Settings > API > Service Role Key
Valid Status Values: The following status mappings are enforced:
- pending → todo
- in-progress → in_progress
- done → done
- cancelled/canceled → cancelled
Valid Priority Values: The following priority mappings are used:
- low → low (text value)
- medium → medium (text value)
- high → high (text value)
- critical → high (text value)

Troubleshooting

If you encounter issues with task statuses: 1. Use node sync-remaining-tasks.js to sync only tasks with 'pending' status 2. Check the database schema for the exact allowable values for the status field 3. Update your local task statuses to match what's acceptable in your Supabase schema

claude task management ai development cursor anthropic llm mcp context supabase cloud sync

ora cors open uuid boxen chalk dotenv figlet helmet openai express fastmcp fuse.js inquirer commander lru-cache cli-table3 jsonwebtoken gradient-string @anthropic-ai/sdk @supabase/supabase-js

1.0.0

6 months ago

Track Master

By Nelson Anane

Requirements

Quick Start

Option 1 | MCP (Recommended):

Option 2: Using Command Line

Installation

Initialize a new project

Common Commands

Features

Supabase Integration

Quick Setup

Valid Status Values

Documentation

Troubleshooting

If task-master init doesn't respond:

Contributors

Star History

Licensing

vibe-task-master

vibe-task-master

Supabase Setup

Required Environment Variables

Service Role Key for CLI (Required)

Automatic Setup

Field Mapping

Valid Status Values

Status Field

Priority Field

Resolving Supabase Issues

Fixed Issues

Required Setup

Troubleshooting

If `task-master init` doesn't respond: