Snakehug

---
name: snakehug
description: Configure and activate conda/mamba/pixi environment for Python commands. Checks project CLAUDE.md for environment config.
version: 0.1.0
author: Anaconda, Inc.
license: MIT
user-invocable: false
---

# Python Environment Activation

Before running Python-related commands, check if an environment is configured and activate it.

## Configuration

Check the project's CLAUDE.md for a "Python Environment" section. It should contain the **complete, working activation command**:

```markdown
## Python Environment
```bash
source ~/miniconda3/etc/profile.d/conda.sh && conda run -n myenv <command>
```
```

## Running Commands

When running Python commands (python, pip, pytest, mypy, ruff, black, isort, jupyter, jlpm, etc.):

1. Check project's CLAUDE.md for "Python Environment" section
2. If configured, use the **exact saved command pattern**, replacing `<command>` with the actual command
3. If not configured, follow the Setup flow below

## Setup (No Config Found)

If the project's CLAUDE.md has no "Python Environment" section:

1. **Detect available environment managers** - Check what's installed on the system:
   - Use `which` to find tools in PATH (conda, mamba, micromamba, pixi)
   - Check common installation locations (see **Common Installation Locations** below)

2. **ALWAYS ask which environment manager to use**: Use AskUserQuestion
   - Question: "Which environment manager do you use?"
   - **Only show options that were detected as available** (plus "none")
   - **You MUST ask even if only one manager is found**

3. **If "none" selected**: Skip environment setup, run commands directly

4. **List available environments** using the selected manager and patterns from the **Activation Patterns** section below

5. **ALWAYS ask which environment to use**: Use AskUserQuestion
   - **You MUST ask even if an environment name matches the project folder**
   - Show environments that match or relate to the project folder name first
   - Include envs from ALL installations found by that manager
   - Add "Create new environment" option

6. **If "Create new" selected**: Create environment with the selected manager

7. **Test the activation** - Try running a simple command (e.g., `python --version`) with the activation pattern from the **Activation Patterns** section below

8. **CRITICAL - Save the COMPLETE working command to project CLAUDE.md**:
   
   Save the **exact command that successfully ran**, including ALL parts:
   - Shell hook or source command (if needed)
   - Full environment path (not just name if path was required)
   - The run command pattern
   
   **Good example** (saves complete working command):
   ```markdown
   ## Python Environment
   ```bash
   source ~/miniconda3/etc/profile.d/conda.sh && conda run -p /opt/homebrew/Cellar/micromamba/2.4.0/envs/myproject <command>
   ```
   ```
   
   **Bad example** (incomplete, may not work in fresh shell):
   ```markdown
   ## Python Environment
   Use `conda run -p /opt/homebrew/Cellar/micromamba/2.4.0/envs/myproject` for Python commands.
   ```
   
   The saved command must be copy-paste reproducible in a fresh, non-interactive shell.

9. **Run the original command** using the saved pattern

## Commands to Wrap

These commands need environment activation:
- python, python3
- pip, pip3
- pytest, py.test, tox, nox
- mypy, ruff, black, isort, flake8, pylint
- jupyter, ipython, jlpm
- poetry, pdm, hatch, flit
- pre-commit
- uvicorn, gunicorn, flask, django-admin, celery

## Activation Patterns

Always save the FULL working command including any required shell hooks.

### Conda

**Bash (using profile.d script — works in non-interactive shells):**
```bash
source <conda_prefix>/etc/profile.d/conda.sh && conda activate <env> && <command>
```

**Bash (using shell hook):**
```bash
eval "$(conda shell.bash hook)" && conda activate <env> && <command>
```

**Zsh:**
```zsh
eval "$(conda shell.zsh hook)" && conda activate <env> && <command>
```

### Mamba

**Bash:**
```bash
eval "$(mamba shell hook --shell bash)" && mamba activate <env> && <command>
```

**Bash with explicit path (macOS Homebrew):**
```bash
eval "$(/opt/homebrew/bin/mamba shell hook --shell bash)" && mamba activate <env> && <command>
```

**Zsh:**
```zsh
eval "$(mamba shell hook --shell zsh)" && mamba activate <env> && <command>
```

**Fallback — using conda's hook with mamba (if `mamba shell hook` fails):**
```bash
eval "$(conda shell.bash hook)" && mamba activate <env> && <command>
```

### Micromamba

**Bash:**
```bash
eval "$(micromamba shell hook --shell bash)" && micromamba activate <env> && <command>
```

**Zsh:**
```zsh
eval "$(micromamba shell hook --shell zsh)" && micromamba activate <env> && <command>
```

### Pixi

**Run command directly (preferred):**
```bash
pixi run <command>
```

**With specific environment:**
```bash
pixi run -e <environment> <command>
```

**Shell hook for activation (Bash):**
```bash
cd <project_dir> && eval "$(pixi shell-hook --shell bash)" && <command>
```

**Shell hook for activation (Zsh):**
```zsh
cd <project_dir> && eval "$(pixi shell-hook --shell zsh)" && <command>
```

## Common Installation Locations

**macOS:**
- `~/miniconda3/`
- `~/anaconda3/`
- `~/miniforge3/`
- `~/mambaforge/`
- `/opt/homebrew/Caskroom/miniconda/base/`
- `/usr/local/Caskroom/miniconda/base/`

**Linux:**
- `~/miniconda3/`
- `~/anaconda3/`
- `~/miniforge3/`
- `~/mambaforge/`
- `/opt/conda/`
- `/opt/miniconda3/`
- `/usr/local/miniconda3/`
- `/home/<user>/anaconda3/`

**Micromamba:**
- `~/.local/bin/micromamba`
- `/opt/homebrew/bin/micromamba`
- `/usr/local/bin/micromamba`
- `~/bin/micromamba`

## Finding the Tool Path

If the tool isn't in PATH, find it:
```bash
which conda
which mamba
which micromamba
which pixi
```

Or check common locations:
```bash
# macOS Homebrew
ls /opt/homebrew/bin/{mamba,micromamba,conda,pixi} 2>/dev/null
ls /usr/local/bin/{mamba,micromamba,conda,pixi} 2>/dev/null

# User installations
ls ~/miniconda3/bin/conda 2>/dev/null
ls ~/miniforge3/bin/mamba 2>/dev/null
ls ~/mambaforge/bin/mamba 2>/dev/null
ls ~/.local/bin/micromamba 2>/dev/null
ls ~/.pixi/bin/pixi 2>/dev/null
```

## If Activation Fails

If a saved command stops working:

1. Re-test with a simple command like `python --version`
2. Try different activation patterns from the **Activation Patterns** section above
3. Once working, **update CLAUDE.md with the new complete command**

**Common issues:**
- **"CommandNotFoundError: Your shell has not been properly configured"** — Run `conda init <shell>` or use the profile.d sourcing method instead of shell hook.
- **Environment activation doesn't persist in scripts** — Use `eval "$(conda shell.bash hook)"` at the start of your script, or source the profile.d script.
- **`mamba activate` fails** — Try using `conda shell.bash hook` with `mamba activate`; they're compatible.
- **`pixi shell-hook` hangs** — Use `pixi run <command>` instead for better reliability.