# jprbom/claude-task-master architecture

> Architecture diagram of the GitHub repository jprbom/claude-task-master, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jprbom/claude-task-master
- Repository: https://github.com/jprbom/claude-task-master

## Overview

##### 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”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors
    User["User"]:::integration
    EditorHost["Editor Host\n(Cursor, VS Code, Windsurf)"]:::integration

    %% CLI Path
    subgraph "CLI Interface"
        direction TB
        CLIEntrypoint["CLI Entrypoint\n(bin/task-master.js)"]:::core
        CLIEntrypoint2["Secondary Entrypoint\n(index.js)"]:::core
        CmdDispatcher["Core Command Dispatcher\n(src/task-master.js)"]:::core
    end

    %% Core Modules
    subgraph "CLI Core Modules"
        direction TB
        AIProviders["AI Providers Adapters\n(src/ai-providers/)"]:::core
        ProvRegistry["Provider Registry\n(src/provider-registry/index.js)"]:::core
        Prompts["Prompt Templates\n(src/prompts/)"]:::core
        Constants["Shared Constants\n(src/constants/)"]:::core
        Utils["Shared Utilities\n(src/utils/)"]:::core
        UIHelpers["CLI UI Helpers\n(src/ui/)"]:::core
    end

    %% Persistence
    Persist[["Local State\n(.taskmaster/)"]]:::persistence

    %% MCP Path
    subgraph "Editor Extension"
        direction TB
        ExtPkg["Extension Package\n(apps/extension/package.json)"]:::integration
        ExtSrc["Extension Source\n(apps/extension/src/index.ts)"]:::integration
        ExtCfg["Extension Config\n(apps/extension/tsconfig.json)"]:::integration
        ExtPkg --> ExtSrc
    end

    EditorHost -->|"Invokes via MCP"| ExtSrc

    subgraph "MCP Server (JSON-RPC)" 
        style MCPServer fill:#f8e0b1,stroke:#e29e0a,stroke-width:2px
        direction TB
        MCPIndex["Server Startup\n(mcp-server/src/index.js)"]:::microservice
        MCPEntrypoint["MCP Entrypoint\n(mcp-server/server.js)"]:::microservice
        MCPLogger["Logger\n(mcp-server/src/logger.js)"]:::microservice
        subgraph "Core Layer"
            direction TB
            DirectFuncs["Direct-Functions\n(mcp-server/src/core/direct-functions/)"]:::microservice
            TMCore["Task-Master Core Logic\n(mcp-server/src/core/task-master-core.js)"]:::microservice
            MCCoreUtils["Core Utils\n(mcp-server/src/core/utils/)"]:::microservice
        end
        subgraph "Custom-SDK"
            direction TB
            CustomSDK["Custom-SDK Layer\n(mcp-server/src/custom-sdk/)"]:::microservice
        end
        subgraph "Tools Layer"
            direction TB
            Tools["CLI-style Tools\n(mcp-server/src/tools/)"]:::microservice
        end
        MCPProviders["MCP Protocol Adapter\n(mcp-server/src/providers/mcp-provider.js)"]:::microservice
        MCPIndex --> MCPEntrypoint --> DirectFuncs
        DirectFuncs --> TMCore
        TMCore --> MCCoreUtils
        DirectFuncs --> CustomSDK --> AIProvidersAPI
        DirectFuncs --> Tools
        MCPEntrypoint --> MCPLogger
        MCPProviders --> MCPEntrypoint
    end

    %% External Services
    AIProvidersAPI["AI Provider APIs\n(Anthropic, OpenAI, Gemini...)"]:::external

    %% Scripts & CI
    subgraph "Support & CI"
        direction TB
        Scripts["Scripts\n(scripts/)"]:::support
        ScriptsModulesTM["Task Scripts\n(scripts/modules/task-manager/)"]:::support
        ScriptsConfig["Config/Prompt Scripts\n(scripts/modules/config-manager.js\nscripts/modules/prompt-manager.js)"]:::support
        ScriptsUtils["Script Utilities\n(scripts/modules/utils/)"]:::support
        BuildConfig["Build & Config Files\n(package.json, .env.example,\nbiome.json, tsconfig.json)"]:::support
        Tests["Tests & CI\n(tests/, jest.config.js,\n.github/workflows/)"]:::support
        E2E["E2E Test Helpers\n(tests/e2e/)"]:::support
        Unit["Unit Tests\n(tests/unit/)"]:::support
    end

    %% Flows
    User -->|"CLI Command"| CLIEntrypoint
    CLIEntrypoint2 --> CmdDispatcher
    CLIEntrypoint --> CmdDispatcher
    CmdDispatcher --> AIProviders
    CmdDispatcher --> ProvRegistry
    CmdDispatcher --> Prompts
    CmdDispatcher --> Constants
    CmdDispatcher --> Utils
    CmdDispatcher --> UIHelpers
    Prompts -->|"Prompt→"| AIProvidersAPI
    ProvRegistry --> AIProvidersAPI
    AIProvidersAPI -->|"Response JSON"| CmdDispatcher
    CmdDispatcher -->|"Update State"| Persist

    EditorHost -->|"CLI Command via npx"| CLIEntrypoint
    EditorHost -->|"MCP JSON-RPC"| MCPEntrypoint
    MCPEntrypoint -->|"JSON-RPC Request"| DirectFuncs
    DirectFuncs -->|"Prompt→"| AIProvidersAPI
    AIProvidersAPI -->|"Response JSON"| DirectFuncs
    DirectFuncs -->|"Update State"| Persist
    DirectFuncs -->|"JSON-RPC Response"| EditorHost

    %% Click Events
    click CLIEntrypoint "https://github.com/jprbom/claude-task-master/blob/main/bin/task-master.js"
    click CLIEntrypoint2 "https://github.com/jprbom/claude-task-master/blob/main/index.js"
    click CmdDispatcher "https://github.com/jprbom/claude-task-master/blob/main/src/task-master.js"
    click AIProviders "https://github.com/jprbom/claude-task-master/tree/main/src/ai-providers/"
    click ProvRegistry "https://github.com/jprbom/claude-task-master/blob/main/src/provider-registry/index.js"
    click Prompts "https://github.com/jprbom/claude-task-master/tree/main/src/prompts/"
    click Constants "https://github.com/jprbom/claude-task-master/tree/main/src/constants/"
    click Utils "https://github.com/jprbom/claude-task-master/tree/main/src/utils/"
    click UIHelpers "https://github.com/jprbom/claude-task-master/tree/main/src/ui/"
    click Persist "https://github.com/jprbom/claude-task-master/tree/main/.taskmaster/"
    click MCPEntrypoint "https://github.com/jprbom/claude-task-master/blob/main/mcp-server/server.js"
    click MCPIndex "https://github.com/jprbom/claude-task-master/blob/main/mcp-server/src/index.js"
    click MCPLogger "https://github.com/jprbom/claude-task-master/blob/main/mcp-server/src/logger.js"
    click DirectFuncs "https://github.com/jprbom/claude-task-master/tree/main/mcp-server/src/core/direct-functions/"
    click TMCore "https://github.com/jprbom/claude-task-master/blob/main/mcp-server/src/core/task-master-core.js"
    click MCCoreUtils "https://github.com/jprbom/claude-task-master/tree/main/mcp-server/src/core/utils/"
    click CustomSDK "https://github.com/jprbom/claude-task-master/tree/main/mcp-server/src/custom-sdk/"
    click Tools "https://github.com/jprbom/claude-task-master/tree/main/mcp-server/src/tools/"
    click MCPProviders "https://github.com/jprbom/claude-task-master/blob/main/mcp-server/src/providers/mcp-provider.js"
    click ExtPkg "https://github.com/jprbom/claude-task-master/blob/main/apps/extension/package.json"
    click ExtSrc "https://github.com/jprbom/claude-task-master/blob/main/apps/extension/src/index.ts"
    click ExtCfg "https://github.com/jprbom/claude-task-master/blob/main/apps/extension/tsconfig.json"
    click Scripts "https://github.com/jprbom/claude-task-master/tree/main/scripts/"
    click ScriptsModulesTM "https://github.com/jprbom/claude-task-master/tree/main/scripts/modules/task-manager/"
    click ScriptsConfig "https://github.com/jprbom/claude-task-master/blob/main/scripts/modules/config-manager.js"
    click ScriptsConfig "https://github.com/jprbom/claude-task-master/blob/main/scripts/modules/prompt-manager.js"
    click ScriptsUtils "https://github.com/jprbom/claude-task-master/tree/main/scripts/modules/utils/"
    click BuildConfig "https://github.com/jprbom/claude-task-master/blob/main/package.json"
    click Tests "https://github.com/jprbom/claude-task-master/tree/main/tests/"
    click E2E "https://github.com/jprbom/claude-task-master/tree/main/tests/e2e/"
    click Unit "https://github.com/jprbom/claude-task-master/tree/main/tests/unit/"

    %% Styles
    classDef core fill:#d0e7ff,stroke:#0047b3,stroke-width:1px
    classDef persistence fill:#e2f7e1,stroke:#237a2a,stroke-width:1px
    classDef external fill:#f3e1ff,stroke:#7a2aae,stroke-width:1px
    classDef microservice fill:#ffe7c4,stroke:#e29e0a,stroke-width:1px
    classDef integration fill:#c4f0ff,stroke:#0a7ea2,stroke-width:1px
    classDef support fill:#f0f0f0,stroke:#888888,stroke-width:1px
```
