# neno-is-ooo/claude-task-master architecture

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

- Interactive diagram: https://gitdiagram.com/neno-is-ooo/claude-task-master
- Repository: https://github.com/neno-is-ooo/claude-task-master

## Overview

##### Project Type and Purpose
- Task Master is an AI-driven **CLI tool** plus an **MCP server** (Model Control Protocol) that integrates into editors (Cursor, Windsurf, VS Code).
- It parses PRDs, generates and manages tasks in a `.taskmaster` workspace, and invokes LLMs via modular AI providers.

##### Top-Level Components
a. **Editor / IDE**
- Examples: Cursor, Windsurf, VS Code
- Loads MCP server (via `.cursor/mcp.json`, `.vscode/mcp.json`)
- Presents AI chat pane and CLI interface

b. **MCP Server** (`mcp-server/`)
- Entry point: `mcp-server/server.js`
- Exposes MCP protocol over stdio
- Core layer: `task-master-core.js`, `direct-functions/*` (one per command)
- Custom SDK: `src/custom-sdk/*` (message conversion, schema)
- Tools layer: `tools/*` (CLI wrappers for direct functions)

c. **CLI Tool**
- Entry point: `bin/task-master.js` & `index.js`
- Uses `src/task-master.js`, `src/commands`, `src/prompts`, `src/utils`
- Scripted helpers: `scripts/*.js` and `scripts/modules/*`

d. **Domain / Core Modules** (`src/`)
- **AI Providers** (`src/ai-providers/*`): wrappers for Claude, OpenAI, Gemini, etc.
- **Provider Registry** (`src/provider-registry`): selects the active provider by config
- **Profiles** (`src/profiles`): editor-specific or use-case profiles
- **Prompts** (`src/prompts`): JSON templates + schemas
- **Constants & Utils** (`src/constants`, `src/utils`)

e. **Persistence & Workspace**
- Project state: `.taskmaster/state.json`, `.taskmaster/tasks/tasks.json`
- Templates: `.taskmaster/templates/`
- Generated docs & reports: `.taskmaster/docs/`, `.taskmaster/reports/`

f. **Configuration**
- `mcp.json` / `.env` / `env.example` for API keys & server config
- `package.json` / `tsconfig.json` / `biome.json` / `jest.config.js`

g. **External Services**
- AI endpoints: Anthropic (Claude), OpenAI, Google Gemini, xAI, Perplexity, Ollama, etc.
- Git (for `.gitignore` management)

##### Relationships & Data Flows
- **Editor** → (MCP protocol over stdio) → **MCP Server**
- **Editor** → (CLI invocation via npx) → **CLI Tool**
- Both MCP Server & CLI Tool → load **Core Modules** → invoke **AI Providers** → receive LLM responses
- Responses → **Direct Functions / Command Handlers** → update **.taskmaster** files → return output to Editor/CLI
- **Scripts** can be invoked directly or by the CLI for maintenance (e.g., `scripts/init.js`, `scripts/dev.js`)
- **Tests** (`tests/`, `mcp-server/src/core/__tests__`) validate unit, integration, E2E

##### Architectural Patterns & Principles
- **Layered Architecture**: UI (Editor/CLI), Application (MCP Server/CLI), Domain (direct-functions), Infrastructure (AI providers, file I/O)
- **Modularity**: one file per command, one provider per file, provider-registry decouples domain logic from AI endpoints
- **Hexagonal (“Ports & Adapters”)**: prompts & direct-functions are “ports”; AI providers & file system are “adapters”
- **Separation of Concerns**:
- `mcp-server/` for MCP protocol
- `bin/` for CLI bootstrap
- `scripts/` for tooling
- `apps/extension/` for a VS Code GUI

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Editor/IDE Layer
    subgraph "Editor/IDE Layer"
        VSCodeExt["VS Code Extension"]:::ui
        CursorConfig[".cursor/mcp.json"]:::ui
        VSCodeConfig[".vscode/mcp.json"]:::ui
    end

    %% Application Layer
    subgraph "Application Layer"
        subgraph "MCP Server" 
            ServerEntry["server.js"]:::app
            CoreModule["task-master-core.js"]:::app
            DirectFunctions["direct-functions/"]:::app
            CustomSDK["custom-sdk/"]:::app
            ToolsLayer["tools/"]:::app
        end
        subgraph "CLI Tool"
            CLIBin["bin/task-master.js"]:::app
            CLIIndex["index.js"]:::app
            CLIMain["src/task-master.js"]:::app
            CLIUtils["src/utils/"]:::app
            Scripts["scripts/"]:::app
        end
    end

    %% Domain / Core Modules
    subgraph "Domain Core Modules"
        AIProviders["ai-providers/"]:::domain
        ProviderRegistry["provider-registry"]:::domain
        Profiles["profiles/"]:::domain
        Prompts["prompts/"]:::domain
        Constants["constants/"]:::domain
    end

    %% Persistence & Workspace
    subgraph "Persistence & Workspace (.taskmaster)"
        StateJSON["state.json"]:::storage
        TasksJSON["tasks/tasks.json"]:::storage
        Templates["templates/"]:::storage
        Docs["docs/"]:::storage
        Reports["reports/"]:::storage
    end

    %% Configuration & Metadata
    subgraph "Configuration & Metadata"
        EnvExample[".env.example"]:::infra
        MCPConfig["mcp.json"]:::infra
        PackageJSON["package.json"]:::infra
        TSConfig["tsconfig.json"]:::infra
        Biome["biome.json"]:::infra
        JestConfig["jest.config.js"]:::infra
    end

    %% External Services
    ExternalAI["External AI Services\n(Anthropic, OpenAI,\nGoogle Gemini, etc.)"]:::external

    %% Connections
    VSCodeExt -->|"MCP request\n(stdio)"| ServerEntry
    CursorConfig -->|"Config load"| ServerEntry
    VSCodeConfig -->|"Config load"| ServerEntry

    VSCodeExt -->|"CLI command"| CLIBin

    ServerEntry -->|"loads"| CoreModule
    ServerEntry -->|"executes"| DirectFunctions
    ServerEntry -->|"uses SDK"| CustomSDK
    ServerEntry -->|"tools layer"| ToolsLayer

    CLIBin -->|"requires"| CLIIndex
    CLIIndex -->|"bootstraps"| CLIMain
    CLIMain -->|"utilizes"| CLIUtils
    CLIMain -->|"scripts"| Scripts

    CoreModule -->|"invokes"| DirectFunctions
    CoreModule -->|"reads/prompts"| Prompts
    CoreModule -->|"calls"| ProviderRegistry
    DirectFunctions -->|"use"| AIProviders
    ProviderRegistry -->|"selects adapter"| AIProviders
    AIProviders -->|"LLM prompt"| ExternalAI
    ExternalAI -->|"LLM response"| AIProviders
    AIProviders -->|"response"| DirectFunctions
    DirectFunctions -->|"update"| StateJSON
    DirectFunctions -->|"update"| TasksJSON
    DirectFunctions -->|"read/write"| Templates
    DirectFunctions -->|"generate"| Docs
    DirectFunctions -->|"generate"| Reports

    %% Config usage
    ServerEntry -->|"env/config"| EnvExample
    ServerEntry -->|"protocol config"| MCPConfig
    CLIBin -->|"metadata"| PackageJSON
    CLIMain -->|"ts setup"| TSConfig
    Scripts -->|"lint/format"| Biome
    Scripts -->|"tests config"| JestConfig

    %% Styling
    classDef ui fill:#ffe4e1,stroke:#333,stroke-width:1px
    classDef app fill:#e0ffff,stroke:#333,stroke-width:1px
    classDef domain fill:#fafad2,stroke:#333,stroke-width:1px
    classDef storage fill:#e6e6fa,stroke:#333,stroke-width:1px
    classDef infra fill:#f0fff0,stroke:#333,stroke-width:1px
    classDef external fill:#d3d3d3,stroke:#333,stroke-width:1px

    %% Click Events
    click VSCodeExt "https://github.com/neno-is-ooo/claude-task-master/blob/main/apps/extension/src/index.ts"
    click CursorConfig "https://github.com/neno-is-ooo/claude-task-master/blob/main/.cursor/mcp.json"
    click VSCodeConfig "https://github.com/neno-is-ooo/claude-task-master/blob/main/.vscode/mcp.json"

    click ServerEntry "https://github.com/neno-is-ooo/claude-task-master/blob/main/mcp-server/server.js"
    click CoreModule "https://github.com/neno-is-ooo/claude-task-master/blob/main/mcp-server/src/core/task-master-core.js"
    click DirectFunctions "https://github.com/neno-is-ooo/claude-task-master/tree/main/mcp-server/src/core/direct-functions/"
    click CustomSDK "https://github.com/neno-is-ooo/claude-task-master/tree/main/mcp-server/src/custom-sdk/"
    click ToolsLayer "https://github.com/neno-is-ooo/claude-task-master/tree/main/mcp-server/src/tools/"

    click CLIBin "https://github.com/neno-is-ooo/claude-task-master/blob/main/bin/task-master.js"
    click CLIIndex "https://github.com/neno-is-ooo/claude-task-master/blob/main/index.js"
    click CLIMain "https://github.com/neno-is-ooo/claude-task-master/blob/main/src/task-master.js"
    click CLIUtils "https://github.com/neno-is-ooo/claude-task-master/tree/main/src/utils/"
    click Scripts "https://github.com/neno-is-ooo/claude-task-master/tree/main/scripts/"

    click AIProviders "https://github.com/neno-is-ooo/claude-task-master/tree/main/src/ai-providers/"
    click ProviderRegistry "https://github.com/neno-is-ooo/claude-task-master/blob/main/src/provider-registry/index.js"
    click Profiles "https://github.com/neno-is-ooo/claude-task-master/tree/main/src/profiles/"
    click Prompts "https://github.com/neno-is-ooo/claude-task-master/tree/main/src/prompts/"
    click Constants "https://github.com/neno-is-ooo/claude-task-master/tree/main/src/constants/"

    click StateJSON "https://github.com/neno-is-ooo/claude-task-master/blob/main/.taskmaster/state.json"
    click TasksJSON "https://github.com/neno-is-ooo/claude-task-master/blob/main/.taskmaster/tasks/tasks.json"
    click Templates "https://github.com/neno-is-ooo/claude-task-master/tree/main/.taskmaster/templates/"
    click Docs "https://github.com/neno-is-ooo/claude-task-master/tree/main/.taskmaster/docs/"
    click Reports "https://github.com/neno-is-ooo/claude-task-master/tree/main/.taskmaster/reports/"

    click EnvExample "https://github.com/neno-is-ooo/claude-task-master/blob/main/.env.example"
    click MCPConfig "https://github.com/neno-is-ooo/claude-task-master/blob/main/mcp.json"
    click PackageJSON "https://github.com/neno-is-ooo/claude-task-master/blob/main/package.json"
    click TSConfig "https://github.com/neno-is-ooo/claude-task-master/blob/main/tsconfig.json"
    click Biome "https://github.com/neno-is-ooo/claude-task-master/blob/main/biome.json"
    click JestConfig "https://github.com/neno-is-ooo/claude-task-master/blob/main/jest.config.js"
```
