How jprbom/claude-task-master works
Project Type and Purpose
• Task Master is an open-source, AI-driven task management system that can be used as:
• A CLI tool (npm package / npx task-master-ai)
• An MCP microservice for editor integrations (Cursor, VS Code, Windsurf)
• A VS Code extension (under apps/extension).
• It orchestrates AI providers (Anthropic/Claude, OpenAI, Gemini, etc.) to parse PRDs, generate tasks, manage task state, and offer research workflows.
Top-Level Architectural Components
A. CLI Core
• Entrypoint: bin/task-master.js, index.js
• Command dispatcher: src/task-master.js
• Submodules:
• ai-providers/* – adapters to external LLM APIs
• provider-registry – dynamic provider selection
• prompts – JSON templates for each command
• constants, utils, ui – shared helpers
• Local persistence: .taskmaster/ folder (state.json, tasks.json, templates, reports)
B. MCP Server (microservice)
• Entrypoint: mcp-server/server.js
• Core command implementations (“direct-functions”) under mcp-server/src/core/direct-functions
• Wraps core logic (task-master-core) for the MCP protocol (stdin/stdout JSON-RPC)
• Custom-SDK layer: abstraction over LLM calls (under mcp-server/src/custom-sdk)
• Tools layer: CLI-style commands (mcp-server/src/tools) to invoke direct-functions
C. Editor Extension
• Under apps/extension: TypeScript code that registers an MCP client
• Relies on MCP server via configured command (npx task-master-ai)
D. Scripts and Tooling
• scripts/ modules for standalone tasks: configuration migration, PRD parsing, report generation
• Build/config files: package.json, .env.example, biome.json, tsconfig.json (extension)
E. External Dependencies
• AI provider APIs (Anthropic, OpenAI, Google, Perplexity, xAI, OpenRouter, etc.)
• Editor hosts via MCP protocol (Cursor, Windsurf, VS Code)
Component Interactions and Data Flow
• User/Editor issues a command (via CLI or chat UI).
• CLI (task-master-ai) or Editor extension invokes either:
• Direct CLI path: JS entrypoint → core modules → LLM API → local file updates
• MCP path: Editor → MCP protocol → mcp-server → direct-functions → LLM API → JSON response to Editor
• LLM API calls: use provider-registry to select the configured provider, send prompt from prompts/, receive JSON/text, parse into tasks.
• State persistence: .taskmaster/state.json and .taskmaster/tasks/tasks.json updated by core or direct-functions.
• Tests and CI: tests/, jest.config.js, GitHub workflows validate unit, integration, end-to-end behaviors.
Architectural Patterns and Principles
• Modular plugin architecture: providers, prompts, commands decoupled via registries
• Microservice isolation: MCP server encapsulates protocol handling, direct-functions, custom-SDK
• Single Source of Truth: .taskmaster/ directory for project state
• Command pattern: each CLI command and direct-function implements one operation
• Separation of concerns: core logic (task generation, parsing) separated from protocol (MCP) and UI integration
What
• Clear component names and roles:
• “CLI Entrypoint”
• “Core Command Dispatcher”
• “MCP Server (JSON-RPC)”
• “Direct-Functions”
• “Custom-SDK / LLM Adapter”
• “AI Provider APIs”
• “Local State (.taskmaster)”
• “Editor Extension”
• Core logic vs. persistence vs. external vs. integration
• Notes on patterns: “Plug-in providers”, “Command pattern”, “Microservice boundary”