@yeongjaeyou/claude-code-config 0.22.0 → 0.23.0

package/.claude/skills/gpu-parallel-pipeline/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: gpu-parallel-pipeline
+description: Design and implement PyTorch GPU parallel processing pipelines for maximum throughput. Use when scaling workloads across multiple GPUs (ProcessPool, CUDA_VISIBLE_DEVICES isolation), optimizing single GPU utilization (CUDA Streams, async inference, model batching), or building I/O + compute pipelines (ThreadPool for loading, batch inference). Triggers on "multi-GPU", "GPU parallel", "batch inference", "CUDA isolation", "GPU utilization", "ProcessPool GPU", "PyTorch multi-GPU".
+---
+
+# GPU Parallel Pipeline
+
+## Overview
+
+This skill provides patterns for maximizing GPU throughput in data processing pipelines.
+
+**Three core patterns:**
+1. **Multi-GPU Distribution** - ProcessPool with GPU isolation via CUDA_VISIBLE_DEVICES
+2. **Single GPU Optimization** - CUDA Streams, async inference, model batching
+3. **I/O + Compute Pipeline** - ThreadPool for I/O parallelization + batch inference
+
+## Quick Reference
+
+| Pattern | Use Case | Speedup |
+|---------|----------|---------|
+| Multi-GPU ProcessPool | Large dataset, multiple GPUs | ~N x (N = GPU count) |
+| ThreadPool I/O + Batch | I/O bottleneck (image loading) | 2-5x |
+| CUDA Streams | Multiple models on single GPU | 1.5-3x |
+
+## Multi-GPU Architecture
+
+```
+Main Process (Coordinator)
+    |
+    +-- GPU 0: ProcessPool Worker (CUDA_VISIBLE_DEVICES=0)
+    |       +-- ThreadPool (I/O)
+    |       +-- Model batch inference
+    |
+    +-- GPU 1: ProcessPool Worker (CUDA_VISIBLE_DEVICES=1)
+    |       +-- ThreadPool (I/O)
+    |       +-- Model batch inference
+    |
+    +-- GPU N: ...
+```
+
+### Key Implementation Steps
+
+1. **Worker initialization with GPU isolation**
+```python
+def _worker_init_with_gpu(gpu_id: int) -> None:
+    os.environ["CUDA_VISIBLE_DEVICES"] = str(gpu_id)
+    # Initialize model here (once per worker)
+    global _model
+    _model = load_model()
+```
+
+2. **Spawn context (not fork)**
+```python
+ctx = mp.get_context("spawn")  # Required for CUDA
+with ProcessPoolExecutor(max_workers=n_gpus, mp_context=ctx) as executor:
+    ...
+```
+
+3. **Chunk distribution**
+```python
+chunk_size = (n_total + n_gpus - 1) // n_gpus
+chunks = [records[i*chunk_size:(i+1)*chunk_size] for i in range(n_gpus)]
+```
+
+## I/O + Compute Pipeline
+
+Separate I/O (disk read) from compute (GPU inference) using ThreadPool:
+
+```python
+def _load_images_parallel(paths: list[str], max_workers: int = 8) -> dict:
+    with ThreadPoolExecutor(max_workers=max_workers) as executor:
+        futures = {executor.submit(cv2.imread, p): p for p in paths}
+        return {futures[f]: f.result() for f in as_completed(futures)}
+
+def process_batch_hybrid(batch: list[dict]) -> list[dict]:
+    # 1. ThreadPool I/O
+    images = _load_images_parallel([r["path"] for r in batch])
+    # 2. GPU batch inference
+    results = model.predict_batch(list(images.values()))
+    return results
+```
+
+## Detailed References
+
+- **[architecture.md](references/architecture.md)**: Multi-GPU ProcessPool design, worker lifecycle, error handling
+- **[single-gpu-patterns.md](references/single-gpu-patterns.md)**: CUDA Streams, async inference, model parallelism
+- **[troubleshooting.md](references/troubleshooting.md)**: spawn vs fork, OOM, CUDA_VISIBLE_DEVICES issues
+
+## Memory Planning
+
+Before implementation, check GPU memory:
+```bash
+python scripts/check_gpu_memory.py
+```
+
+**Rule of thumb:**
+- Workers per GPU = GPU_Memory / Model_Memory
+- Example: 24GB GPU, 5GB model = 4 workers/GPU max
+- Leave 2-3GB headroom for CUDA overhead

package/.claude/skills/gpu-parallel-pipeline/references/architecture.md

@@ -0,0 +1,194 @@
+# Multi-GPU Architecture
+
+## Table of Contents
+- [ProcessPool with GPU Isolation](#processpool-with-gpu-isolation)
+- [Chunk Distribution Pattern](#chunk-distribution-pattern)
+- [Complete Multi-GPU Orchestration](#complete-multi-gpu-orchestration)
+- [Worker Lifecycle](#worker-lifecycle)
+- [Error Handling Strategy](#error-handling-strategy)
+- [Progress Tracking](#progress-tracking)
+- [Performance Considerations](#performance-considerations)
+
+## ProcessPool with GPU Isolation
+
+### Why ProcessPool over ThreadPool for GPU?
+
+Python's GIL doesn't affect GPU operations, but CUDA context initialization requires process isolation for reliable multi-GPU usage. Each process should own exactly one GPU.
+
+### CUDA_VISIBLE_DEVICES Isolation
+
+```python
+import os
+import multiprocessing as mp
+from concurrent.futures import ProcessPoolExecutor, as_completed
+
+# Process-local state
+_model = None
+_gpu_id = None
+
+def _worker_init_with_gpu(gpu_id: int) -> None:
+    """Initialize worker with GPU isolation.
+
+    Must be called at the start of each worker process.
+    CUDA_VISIBLE_DEVICES makes this GPU appear as device:0 to PyTorch/TF.
+    """
+    global _model, _gpu_id
+
+    os.environ["CUDA_VISIBLE_DEVICES"] = str(gpu_id)
+    _gpu_id = gpu_id
+
+    # Import ML framework AFTER setting CUDA_VISIBLE_DEVICES
+    import torch
+    _model = YourModel().cuda()  # Now on device:0 (the isolated GPU)
+```
+
+### Chunk Distribution Pattern
+
+```python
+def distribute_to_gpus(records: list, n_gpus: int) -> list[tuple]:
+    """Distribute records evenly across GPUs.
+
+    Returns list of (chunk, gpu_id, position) tuples.
+    """
+    if n_gpus < 1:
+        raise ValueError(f"n_gpus must be >= 1, got {n_gpus}")
+
+    n_total = len(records)
+    chunk_size = (n_total + n_gpus - 1) // n_gpus  # ceiling division
+
+    chunks = []
+    for i in range(n_gpus):
+        start = i * chunk_size
+        end = min(start + chunk_size, n_total)
+        if start < n_total:
+            chunks.append((records[start:end], i, i))  # (data, gpu_id, tqdm_position)
+
+    return chunks
+```
+
+### Complete Multi-GPU Orchestration
+
+```python
+def run_multi_gpu(
+    records: list[dict],
+    n_gpus: int = 4,
+    batch_size: int = 128,
+) -> list[dict]:
+    """Orchestrate multi-GPU parallel processing.
+
+    Args:
+        records: Data records to process
+        n_gpus: Number of GPUs to use
+        batch_size: Batch size per GPU
+
+    Returns:
+        Processed records with results
+    """
+    if not records:
+        return []
+
+    # Distribute data
+    chunks = distribute_to_gpus(records, n_gpus)
+    print(f"Distributing {len(records):,} items across {len(chunks)} GPUs")
+
+    # CRITICAL: Use spawn context for CUDA
+    ctx = mp.get_context("spawn")
+
+    # Track GPU assignments for error recovery
+    gpu_to_chunk = {gpu_id: chunk for chunk, gpu_id, _ in chunks}
+
+    all_results = []
+    failed_chunks = []
+
+    with ProcessPoolExecutor(max_workers=len(chunks), mp_context=ctx) as executor:
+        futures = {
+            executor.submit(_process_gpu_chunk, chunk, gpu_id, batch_size, pos): gpu_id
+            for chunk, gpu_id, pos in chunks
+        }
+
+        for future in as_completed(futures):
+            gpu_id = futures[future]
+            try:
+                results = future.result()
+                all_results.extend(results)
+            except Exception as e:
+                print(f"[ERROR] GPU {gpu_id} failed: {e}")
+                failed_chunks.append((gpu_id, gpu_to_chunk[gpu_id]))
+
+    # Handle failures gracefully (don't lose data)
+    if failed_chunks:
+        for gpu_id, chunk in failed_chunks:
+            for record in chunk:
+                record["_error"] = f"GPU {gpu_id} failed"
+                all_results.append(record)
+
+    return all_results
+```
+
+## Worker Lifecycle
+
+```
+spawn context creates new process
+    |
+    v
+_worker_init_with_gpu(gpu_id)
+    - Set CUDA_VISIBLE_DEVICES
+    - Import ML framework
+    - Load model to GPU
+    |
+    v
+Process batches in loop
+    |
+    v
+ProcessPool cleanup (model freed)
+```
+
+### Error Handling Strategy
+
+1. **Per-GPU failure isolation**: One GPU failure shouldn't crash others
+2. **Data preservation**: Failed chunks get marked, not dropped
+3. **Graceful degradation**: Continue with remaining GPUs
+
+```python
+# Track failures
+failed_chunks: list[tuple[int, list]] = []
+
+try:
+    results = future.result(timeout=300)  # 5-min timeout
+except Exception as e:
+    failed_chunks.append((gpu_id, original_chunk))
+
+# After all futures complete
+if failed_chunks:
+    print(f"[WARN] {len(failed_chunks)} GPU(s) failed")
+    # Add failed records with error markers
+```
+
+## Progress Tracking
+
+Use tqdm with position parameter for multi-bar display:
+
+```python
+from tqdm import tqdm
+
+def _process_gpu_chunk(records, gpu_id, batch_size, position):
+    _worker_init_with_gpu(gpu_id)
+
+    batches = [records[i:i+batch_size] for i in range(0, len(records), batch_size)]
+    results = []
+
+    for batch in tqdm(batches, desc=f"GPU {gpu_id}", position=position, leave=False):
+        batch_results = process_batch(batch)
+        results.extend(batch_results)
+
+    return results
+```
+
+## Performance Considerations
+
+| Factor | Recommendation |
+|--------|---------------|
+| Batch size | Start with 64-128, tune based on GPU memory |
+| Workers per GPU | Usually 1 for large models, 2-4 for small models |
+| I/O workers | 4-8 ThreadPool workers per GPU worker |
+| Chunk size | Balanced across GPUs (ceiling division) |

package/.claude/skills/gpu-parallel-pipeline/references/single-gpu-patterns.md

@@ -0,0 +1,225 @@
+# Single GPU Optimization Patterns
+
+## Table of Contents
+- [CUDA Streams for Concurrent Operations](#cuda-streams-for-concurrent-operations)
+- [Async Inference Pattern](#async-inference-pattern)
+- [Model Batching for Multiple Small Models](#model-batching-for-multiple-small-models)
+- [Dynamic Batching](#dynamic-batching)
+- [Memory Optimization](#memory-optimization)
+- [Throughput Measurement](#throughput-measurement)
+- [Best Practices Summary](#best-practices-summary)
+
+## CUDA Streams for Concurrent Operations
+
+CUDA streams allow overlapping data transfer and computation:
+
+```python
+import torch
+
+def process_with_streams(batches: list, model):
+    """Process batches using CUDA streams for overlap."""
+    streams = [torch.cuda.Stream() for _ in range(2)]
+    results = []
+
+    for i, batch in enumerate(batches):
+        stream = streams[i % 2]
+
+        with torch.cuda.stream(stream):
+            # Transfer to GPU
+            data = batch.cuda(non_blocking=True)
+            # Compute
+            output = model(data)
+            results.append(output)
+
+    # Synchronize all streams
+    torch.cuda.synchronize()
+    return results
+```
+
+## Async Inference Pattern
+
+For pipelines with I/O and compute stages:
+
+```python
+import asyncio
+from concurrent.futures import ThreadPoolExecutor
+
+class AsyncInferencePipeline:
+    def __init__(self, model, io_workers: int = 4):
+        self.model = model
+        self.io_executor = ThreadPoolExecutor(max_workers=io_workers)
+        self.batch_queue = asyncio.Queue(maxsize=2)  # Prefetch 2 batches
+
+    async def load_batch(self, paths: list[str]):
+        """Load batch in thread pool (non-blocking)."""
+        loop = asyncio.get_event_loop()
+        images = await loop.run_in_executor(
+            self.io_executor,
+            lambda: [load_image(p) for p in paths]
+        )
+        return torch.stack(images)
+
+    async def producer(self, all_paths: list[str], batch_size: int):
+        """Continuously load batches."""
+        for i in range(0, len(all_paths), batch_size):
+            batch_paths = all_paths[i:i+batch_size]
+            batch = await self.load_batch(batch_paths)
+            await self.batch_queue.put(batch)
+        await self.batch_queue.put(None)  # Signal end
+
+    async def consumer(self):
+        """Process batches as they arrive."""
+        results = []
+        while True:
+            batch = await self.batch_queue.get()
+            if batch is None:
+                break
+            with torch.no_grad():
+                output = self.model(batch.cuda())
+            results.append(output.cpu())
+        return results
+
+    async def run(self, paths: list[str], batch_size: int = 32):
+        producer_task = asyncio.create_task(self.producer(paths, batch_size))
+        results = await self.consumer()
+        await producer_task
+        return results
+```
+
+## Model Batching for Multiple Small Models
+
+Run multiple small models on single GPU:
+
+```python
+class MultiModelPipeline:
+    """Run multiple models efficiently on single GPU."""
+
+    def __init__(self, models: list):
+        self.models = [m.cuda() for m in models]
+        self.streams = [torch.cuda.Stream() for _ in models]
+
+    def forward_all(self, inputs: list[torch.Tensor]) -> list[torch.Tensor]:
+        """Run all models concurrently using streams."""
+        outputs = [None] * len(self.models)
+
+        # Launch all models
+        for i, (model, stream, x) in enumerate(zip(self.models, self.streams, inputs)):
+            with torch.cuda.stream(stream):
+                outputs[i] = model(x.cuda(non_blocking=True))
+
+        # Wait for all
+        torch.cuda.synchronize()
+        return outputs
+```
+
+## Dynamic Batching
+
+Maximize GPU utilization with variable batch sizes:
+
+```python
+class DynamicBatcher:
+    """Accumulate inputs until batch is full or timeout."""
+
+    def __init__(self, model, max_batch: int = 64, timeout_ms: int = 10):
+        self.model = model
+        self.max_batch = max_batch
+        self.timeout_ms = timeout_ms
+        self.pending = []
+        self.last_submit = time.time()
+
+    def add(self, item):
+        self.pending.append(item)
+
+        should_process = (
+            len(self.pending) >= self.max_batch or
+            (time.time() - self.last_submit) * 1000 > self.timeout_ms
+        )
+
+        if should_process and self.pending:
+            return self._process_batch()
+        return None
+
+    def _process_batch(self):
+        batch = torch.stack(self.pending[:self.max_batch])
+        self.pending = self.pending[self.max_batch:]
+        self.last_submit = time.time()
+
+        with torch.no_grad():
+            return self.model(batch.cuda())
+```
+
+## Memory Optimization
+
+### Gradient Checkpointing (Training)
+
+```python
+from torch.utils.checkpoint import checkpoint
+
+class EfficientModel(nn.Module):
+    def forward(self, x):
+        # Checkpoint intermediate layers to save memory
+        x = checkpoint(self.layer1, x)
+        x = checkpoint(self.layer2, x)
+        x = self.head(x)
+        return x
+```
+
+### Mixed Precision Inference
+
+```python
+with torch.cuda.amp.autocast():
+    output = model(input)  # Uses FP16 automatically
+```
+
+### Memory-Efficient Attention (for transformers)
+
+```python
+# Use torch.nn.functional.scaled_dot_product_attention (PyTorch 2.0+)
+# Automatically uses FlashAttention when available
+from torch.nn.functional import scaled_dot_product_attention
+
+attn_output = scaled_dot_product_attention(q, k, v, is_causal=True)
+```
+
+## Throughput Measurement
+
+```python
+import time
+import torch
+
+def benchmark_throughput(model, input_shape, n_iterations=100, warmup=10):
+    """Measure model throughput in samples/second."""
+    model.eval()
+    dummy_input = torch.randn(*input_shape).cuda()
+
+    # Warmup
+    for _ in range(warmup):
+        with torch.no_grad():
+            _ = model(dummy_input)
+
+    torch.cuda.synchronize()
+    start = time.perf_counter()
+
+    for _ in range(n_iterations):
+        with torch.no_grad():
+            _ = model(dummy_input)
+
+    torch.cuda.synchronize()
+    elapsed = time.perf_counter() - start
+
+    batch_size = input_shape[0]
+    throughput = (n_iterations * batch_size) / elapsed
+    print(f"Throughput: {throughput:.1f} samples/sec")
+    return throughput
+```
+
+## Best Practices Summary
+
+| Technique | When to Use | Memory Impact |
+|-----------|-------------|---------------|
+| CUDA Streams | Multiple independent ops | Minimal |
+| Async I/O | I/O bottleneck | Minimal |
+| Multi-model | Multiple small models | +1 model per stream |
+| Dynamic batching | Variable input rate | Configurable |
+| Mixed precision | Large models, Ampere+ GPU | -50% |
+| Checkpointing | Training large models | -60% (slower) |

package/.claude/skills/gpu-parallel-pipeline/references/troubleshooting.md

@@ -0,0 +1,247 @@
+# Troubleshooting Guide
+
+## Table of Contents
+- [spawn vs fork Context](#spawn-vs-fork-context)
+- [CUDA_VISIBLE_DEVICES Issues](#cuda_visible_devices-issues)
+- [GPU Memory OOM](#gpu-memory-oom)
+- [Pickling Errors](#pickling-errors)
+- [Process Hangs](#process-hangs)
+- [Debugging Checklist](#debugging-checklist)
+- [Quick Fixes](#quick-fixes)
+
+## spawn vs fork Context
+
+### Problem: Silent Failures with fork
+
+When using `fork` context with CUDA:
+- Worker processes inherit CUDA context from parent
+- Functions may fail to pickle correctly
+- Workers might return None silently instead of crashing
+
+### Symptom
+```
+# Processing completes in seconds instead of hours
+# All results are None
+# No error messages
+```
+
+### Solution: Always Use spawn
+
+```python
+import multiprocessing as mp
+
+# WRONG
+with ProcessPoolExecutor(max_workers=4) as executor:
+    ...
+
+# CORRECT
+ctx = mp.get_context("spawn")
+with ProcessPoolExecutor(max_workers=4, mp_context=ctx) as executor:
+    ...
+```
+
+### Why spawn works
+
+| Context | Behavior | CUDA Safe |
+|---------|----------|-----------|
+| fork | Copy parent process memory | No |
+| spawn | Start fresh process | Yes |
+| forkserver | Fork from server process | Partial |
+
+## CUDA_VISIBLE_DEVICES Issues
+
+### Problem: All Workers Use Same GPU
+
+Workers share parent's CUDA context if not isolated.
+
+### Solution: Set Early in Worker
+
+```python
+def _worker_init(gpu_id: int):
+    # MUST be first line - before any CUDA import
+    os.environ["CUDA_VISIBLE_DEVICES"] = str(gpu_id)
+
+    # NOW import PyTorch
+    import torch
+
+    # device:0 is now the isolated GPU
+    model = Model().to("cuda:0")
+```
+
+### Verification
+
+```python
+def _worker_init(gpu_id: int):
+    os.environ["CUDA_VISIBLE_DEVICES"] = str(gpu_id)
+    import torch
+
+    # Should print only 1 device
+    print(f"Worker {gpu_id}: {torch.cuda.device_count()} device(s)")
+    print(f"Device name: {torch.cuda.get_device_name(0)}")
+```
+
+### Common Mistake
+
+```python
+# WRONG: Setting after import
+import torch
+os.environ["CUDA_VISIBLE_DEVICES"] = str(gpu_id)  # Too late!
+
+# WRONG: Using device index directly
+model.to(f"cuda:{gpu_id}")  # Sees all GPUs, doesn't isolate
+```
+
+## GPU Memory OOM
+
+### Symptom
+```
+RuntimeError: CUDA out of memory. Tried to allocate X MiB
+```
+
+### Diagnosis
+
+```python
+def check_memory():
+    import torch
+    for i in range(torch.cuda.device_count()):
+        props = torch.cuda.get_device_properties(i)
+        total = props.total_memory / 1e9
+        reserved = torch.cuda.memory_reserved(i) / 1e9
+        allocated = torch.cuda.memory_allocated(i) / 1e9
+        print(f"GPU {i}: {allocated:.1f}GB allocated, {reserved:.1f}GB reserved, {total:.1f}GB total")
+```
+
+### Solutions
+
+1. **Reduce batch size**
+```python
+batch_size = 64  # Start small, increase until OOM
+```
+
+2. **Enable mixed precision**
+```python
+with torch.cuda.amp.autocast():
+    output = model(input)
+```
+
+3. **Clear cache between batches**
+```python
+torch.cuda.empty_cache()  # Use sparingly, has overhead
+```
+
+4. **Reduce workers per GPU**
+```python
+# If model uses 8GB on 24GB GPU
+workers_per_gpu = 24 // 8 - 1  # Leave headroom = 2 workers
+```
+
+### Memory Planning Formula
+
+```
+available_memory = total_gpu_memory - cuda_overhead (2-3GB)
+model_memory = model_size * precision_multiplier
+  - FP32: model_params * 4 bytes
+  - FP16: model_params * 2 bytes
+  - INT8: model_params * 1 byte
+
+workers_per_gpu = floor(available_memory / model_memory)
+```
+
+## Pickling Errors
+
+### Symptom
+```
+_pickle.PicklingError: Can't pickle <local object>
+```
+
+### Common Causes
+
+1. **Lambda functions**
+```python
+# WRONG
+executor.submit(lambda x: process(x), data)
+
+# CORRECT
+def process_wrapper(data):
+    return process(data)
+executor.submit(process_wrapper, data)
+```
+
+2. **Nested functions**
+```python
+# WRONG
+def outer():
+    def inner(x):
+        return x * 2
+    executor.submit(inner, data)
+
+# CORRECT: Define at module level
+def inner(x):
+    return x * 2
+```
+
+3. **CUDA tensors**
+```python
+# WRONG: Passing CUDA tensor to worker
+executor.submit(process, tensor.cuda())
+
+# CORRECT: Pass CPU tensor, move to GPU in worker
+executor.submit(process, tensor.cpu())
+```
+
+## Process Hangs
+
+### Symptom
+- Workers never complete
+- No progress bar updates
+- CPU/GPU utilization drops to 0
+
+### Diagnosis
+
+```python
+# Add timeout to futures
+for future in as_completed(futures, timeout=300):
+    try:
+        result = future.result(timeout=60)
+    except TimeoutError:
+        print(f"Worker timed out")
+```
+
+### Common Causes
+
+1. **Deadlock in worker**
+   - Check for locks that never release
+   - Ensure thread-safe data structures
+
+2. **CUDA synchronization hang**
+```python
+# Add sync points for debugging
+torch.cuda.synchronize()
+print("Sync point reached")
+```
+
+3. **I/O blocking**
+```python
+# Set timeouts on I/O operations
+img = cv2.imread(path)  # Can hang on network storage
+```
+
+## Debugging Checklist
+
+1. [ ] Using spawn context?
+2. [ ] CUDA_VISIBLE_DEVICES set before imports?
+3. [ ] Functions defined at module level (not nested)?
+4. [ ] No CUDA tensors passed between processes?
+5. [ ] Sufficient GPU memory for batch size?
+6. [ ] Timeouts set for futures?
+7. [ ] Progress tracking (tqdm) enabled?
+
+## Quick Fixes
+
+| Issue | Quick Fix |
+|-------|-----------|
+| Silent None returns | Add spawn context |
+| All workers on GPU 0 | Set CUDA_VISIBLE_DEVICES first |
+| OOM | Reduce batch_size by 50% |
+| Pickle error | Move function to module level |
+| Process hangs | Add timeout, check I/O |

package/.claude/skills/gpu-parallel-pipeline/scripts/check_gpu_memory.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python
+"""GPU memory check utility for parallel pipeline planning.
+
+Reports available GPU memory and recommends workers per GPU based on model size.
+
+Usage:
+    python check_gpu_memory.py
+    python check_gpu_memory.py --model-memory 5.0  # Specify model memory in GB
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+
+def check_gpu_memory(model_memory_gb: float | None = None) -> None:
+    """Check GPU memory and recommend worker count.
+
+    Args:
+        model_memory_gb: Estimated model memory usage in GB (optional)
+    """
+    try:
+        import torch
+    except ImportError:
+        print("PyTorch not installed. Install with: pip install torch")
+        sys.exit(1)
+
+    if not torch.cuda.is_available():
+        print("CUDA not available")
+        sys.exit(1)
+
+    n_gpus = torch.cuda.device_count()
+    print(f"Found {n_gpus} GPU(s)\n")
+    print("=" * 60)
+
+    total_available = 0
+    cuda_overhead_gb = 2.5  # Reserved for CUDA context
+
+    for i in range(n_gpus):
+        props = torch.cuda.get_device_properties(i)
+        total_gb = props.total_memory / 1e9
+        available_gb = total_gb - cuda_overhead_gb
+
+        print(f"GPU {i}: {props.name}")
+        print(f"  Total memory: {total_gb:.1f} GB")
+        print(f"  Available (after CUDA overhead): {available_gb:.1f} GB")
+
+        if model_memory_gb:
+            workers = int(available_gb / model_memory_gb)
+            print(f"  Recommended workers (for {model_memory_gb}GB model): {workers}")
+
+        total_available += available_gb
+        print()
+
+    print("=" * 60)
+    print(f"Total available memory: {total_available:.1f} GB")
+
+    if model_memory_gb:
+        total_workers = int(total_available / model_memory_gb)
+        print(f"Total recommended workers: {total_workers}")
+        print(f"\nSuggested command:")
+        print(f"  --n-gpus {n_gpus} --batch-size 64")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Check GPU memory for parallel pipeline")
+    parser.add_argument(
+        "--model-memory",
+        type=float,
+        default=None,
+        help="Estimated model memory usage in GB",
+    )
+    args = parser.parse_args()
+
+    check_gpu_memory(args.model_memory)
+
+
+if __name__ == "__main__":
+    main()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeongjaeyou/claude-code-config",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Claude Code CLI custom commands, agents, and skills",
   "bin": {
     "claude-code-config": "./bin/cli.js"