home-lab/research/claude-task-master-ai-nix-packaging.md

Packaging Claude Task Master AI for NixOS

This document outlines suggestions for packaging the "Claude Task Master AI" Node.js application as a Nix package. The typical installation method for this tool is npm install -g task-master-ai.

1. Creating the Nix Package

Nixpkgs provides helpers for packaging Node.js applications. The primary function for this is buildNpmPackage.

A Nix expression for this package can be created in your packages directory, for example, at packages/claude-task-master-ai.nix.

Key Steps:

1. Find the Source: Determine the source of the task-master-ai package. This is usually the npm registry. You'll need the package name and version.
2. Nix Expression (default.nix or claude-task-master.nix): Create a Nix expression file.
3. Use buildNpmPackage: This function handles the download, build, and installation of npm packages.
4. npmDepsHash: You'll need to calculate a hash of the npm dependencies. This ensures reproducibility.
5. Binaries: Ensure that the executables provided by task-master-ai are correctly placed in the output's bin directory. buildNpmPackage usually handles this if the package.json of the application specifies bin entries.

Example Nix Expression:

{ lib, buildNpmPackage, fetchFromGitHub, nodejs }: # Add other dependencies if needed

buildNpmPackage rec {
  pname = "task-master-ai";
  version = "INSERT_PACKAGE_VERSION_HERE"; # Replace with the actual version

  src = fetchFromGitHub { # Or fetchurl if directly from npm/tarball
    owner = "eyaltoledano"; # Replace if this is not the correct source
    repo = "claude-task-master";  # Replace if this is not the correct source
    rev = "v${version}"; # Or specific commit/tag
    hash = "INSERT_SRC_HASH_HERE"; # lib.fakeSha256 for initial fetch, then replace
  };

  # If fetching directly from npm tarball:
  # src = fetchurl {
  #   url = "https://registry.npmjs.org/task-master-ai/-/task-master-ai-${version}.tgz";
  #   sha256 = "INSERT_TARBALL_HASH_HERE"; # lib.fakeSha256 for initial fetch, then replace
  # };

  npmDepsHash = "INSERT_NPMDEPSHASH_HERE"; # Calculate this after the first build attempt

  # buildInputs = [ nodejs ]; # buildNpmPackage usually brings in nodejs

  meta = with lib; {
    description = "Claude Task Master AI tool";
    homepage = "https://github.com/eyaltoledano/claude-task-master"; # Or actual homepage
    license = licenses.mit; # Check and replace with actual license
    maintainers = [ maintainers.yourGithubUsername ]; # Your username
    platforms = platforms.all;
  };
}

Obtaining npmDepsHash:

1. Initially, set npmDepsHash = lib.fakeSha256; or a placeholder like "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";.
2. Attempt to build the package (e.g., nix-build -A task-master-ai).
3. The build will fail, but it will output the expected hash. Copy this hash into your Nix expression. Alternatively, you can use prefetch-npm-deps if you have a package-lock.json:

   # In a directory with package.json and package-lock.json for task-master-ai
   nix-shell -p nodePackages.prefetch-npm-deps --run "prefetch-npm-deps package-lock.json"
   

   Since task-master-ai is installed globally, you might need to fetch its source first to get the package-lock.json.

Global Installation Aspect:

buildNpmPackage typically installs binaries specified in the package.json's bin field into $out/bin/. This makes them available when the package is installed in a Nix profile. If task-master-ai is made available this way, VS Code can invoke it using npx as shown in the MCP server configuration, or potentially directly if it's added to the PATH.

2. Integrating with VS Code as an MCP Server

Instead of running task-master-ai as a system-wide NixOS service, it can be integrated directly into VS Code (or other compatible editors) as an MCP (Model Context Protocol) server. This allows your editor to communicate with the AI for task management capabilities.

The Nix package created in the previous step ensures that task-master-ai is available in your environment, typically invokable via npx task-master-ai or directly if the Nix package adds it to your PATH.

VS Code settings.json Configuration:

You can configure VS Code to use task-master-ai as an MCP server by adding the following to your settings.json file:

{
  "mcpServers": {
    "taskmaster-ai": {
      "command": "npx",
      "args": ["-y", "--package=task-master-ai", "task-master-ai"],
      "env": {
        "ANTHROPIC_API_KEY": "YOUR_ANTHROPIC_API_KEY_HERE",
        "PERPLEXITY_API_KEY": "YOUR_PERPLEXITY_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"
      }
    }
  }
}

Key Points for MCP Configuration:

• command and args: These specify how to run task-master-ai. Using npx -y --package=task-master-ai task-master-ai ensures that npx fetches and runs the specified version of task-master-ai. If your Nix package makes task-master-ai directly available in the PATH, you might simplify the command to just task-master-ai and remove the args that specify the package for npx.
• env: This section is crucial. You must replace placeholder API keys (YOUR_ANTHROPIC_API_KEY_HERE, YOUR_PERPLEXITY_API_KEY_HERE) with your actual keys.
• You can customize other environment variables like MODEL, MAX_TOKENS, etc., according to your needs and the capabilities of task-master-ai.
• Ensure the Nix package for task-master-ai (and nodejs/npx) is installed and accessible in the environment where VS Code runs.

3. Finding Package Information

• NPM Registry: Search for task-master-ai on npmjs.com to find its exact version, dependencies, and potentially its source repository. The roadmap indicates the source is https://github.com/eyaltoledano/claude-task-master.git.
• GitHub Repository: The roadmap points to https://github.com/eyaltoledano/claude-task-master.git. This is likely the best source for package.json and understanding how the tool works.

This guide provides a starting point. You'll need to adapt the examples based on the specifics of the task-master-ai tool.