fix: auto-install WarpDemuX on demux environment activation

- Add auto-install logic to scripts/demux-activate.sh that clones and
  installs WarpDemuX on first use if not already present
- Remove erroneous $@ from warpdemux task in pixi.toml
- Update installation instructions in docs to reflect automatic install

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: jayhesselberth

CLAUDE.md

@@ -143,7 +143,7 @@ The pipeline supports optional barcode demultiplexing using WarpDemuX for pooled
 
 ### Enabling Demultiplexing
 
-1. **Install demux environment**: `pixi install -e demux && pixi run -e demux install-warpdemux`
+1. **Install demux environment**: `pixi install -e demux` (WarpDemuX is auto-installed on first use)
 2. **Create YAML sample file** with barcode assignments (see `config/samples-demux-example.yml`)
 3. **Enable in config**: Set `warpdemux.enabled: true`
 

docs/troubleshooting/common-errors.md

@@ -352,11 +352,10 @@ warpdemux: command not found
 
 **Solution:**
 
-Install the demux environment:
+Install the demux environment (WarpDemuX is auto-installed on first use):
 
 ```bash
 pixi install -e demux
-pixi run -e demux install-warpdemux
 ```
 
 ### Invalid Barcode Kit

docs/workflow/demultiplexing.md

@@ -35,10 +35,9 @@ Do **not** use when:
 
 ```bash
 pixi install -e demux
-pixi run -e demux install-warpdemux
 ```
 
-This installs the WarpDemuX package and its dependencies.
+This installs the demux environment dependencies. WarpDemuX itself is automatically installed on first use via the environment activation script.
 
 ### 2. Create YAML Sample File
 

pixi.toml

@@ -88,7 +88,7 @@ catboost = "*"
 
 [feature.demux.tasks]
 install-warpdemux = { cmd = "[ -d resources/tools/WarpDemuX ] || git clone --recursive https://github.com/KleistLab/WarpDemuX.git resources/tools/WarpDemuX && uv pip install -e resources/tools/WarpDemuX", description = "Clone and install WarpDemuX" }
-warpdemux = { cmd = "warpdemux $@", env = { LD_LIBRARY_PATH = "$CONDA_PREFIX/lib:$LD_LIBRARY_PATH" } }
+warpdemux = { cmd = "warpdemux", env = { LD_LIBRARY_PATH = "$CONDA_PREFIX/lib:$LD_LIBRARY_PATH" } }
 dry-run-demux = { cmd = "snakemake -n --configfile=config/config-demux-test.yml", description = "Dry run demux test" }
 
 [environments]

scripts/demux-activate.sh

@@ -2,3 +2,14 @@
 # Activation script for demux environment
 # Ensures conda libraries take precedence over system libraries for PyTorch compatibility
 export LD_LIBRARY_PATH="$CONDA_PREFIX/lib:$LD_LIBRARY_PATH"
+
+# Auto-install WarpDemuX if not present
+if ! python -c "import warpdemux" 2>/dev/null; then
+    echo "Installing WarpDemuX..."
+    SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    REPO_DIR="$SCRIPT_DIR/../resources/tools/WarpDemuX"
+    if [ ! -d "$REPO_DIR" ]; then
+        git clone --recursive https://github.com/KleistLab/WarpDemuX.git "$REPO_DIR"
+    fi
+    uv pip install -e "$REPO_DIR"
+fi