# @jerryan/pi-pyvenv

A [pi](https://github.com/earendil-works/pi-mono) extension that transparently ensures every `python`, `python3`, `pip`, and `pip3` invocation resolves to a virtual environment — never to the system Python.

## Why

Coding agents love running `pip install` against the system Python. This breaks or pollutes the user's system packages. `pi-pyvenv` makes this impossible by automatically activating a venv at the **process level** before the agent starts working.

## What it does

On every session start, `pi-pyvenv` picks a venv in this order:

1. **Respect existing activation** — If `VIRTUAL_ENV` is already set (e.g. the user activated a venv in their shell before launching pi), do nothing.
2. **Discover project venv** — If `.venv/` or `venv/` exists in the current working directory, activate that.
3. **Shared fallback venv** — Otherwise, activate (or create) a shared user-level venv at `~/.pi/agent/pyvenv/`.

The activation mutates `process.env.PATH` and `process.env.VIRTUAL_ENV` **once** at the Node.js process level. All subsequently spawned child processes inherit it automatically — no command rewriting, no `spawnHook`, no tool interception.

## Installation

```bash
pi install npm:@jerryan/pi-pyvenv
```

Or install from git:

```bash
pi install git:https://github.com/JerryAZR/pi-pyvenv.git
```

Then restart pi or run `/reload`.

## Commands

| Command | Description |
|---|---|
| `/pyvenv status` | Show the currently active venv |
| `/pyvenv recreate` | Delete and rebuild the shared fallback venv |

## What it is NOT

This extension is **not** a project-level venv manager. It does not:

- Create `.venv/` in your project directory
- Switch venvs when you change directories
- Handle `requirements.txt`, `pyproject.toml`, or lockfiles
- Wrap Conda, Poetry, `uv`, or `pipenv`

If you are working on a real Python project, create your own `.venv/` and `pi-pyvenv` will discover and use it automatically.

## Design decisions

- **No system prompt injection** — The agent does not need to know a venv is active. This is pure infrastructure.
- **No command rewriting** — We trust `PATH` precedence. Absolute paths like `/usr/bin/pip` are rare and not worth the fragility of interception.
- **No `spawnHook`** — Process-level env mutation covers `bash` tool, `!` commands, `pi.exec()`, and other extensions.
- **MS Store shim detection** — On Windows, broken `python3` shims (exit code 49) are automatically skipped during Python discovery.
- **Dead venv recovery** — If the shared venv's underlying Python was removed or upgraded, it is detected and recreated on the next session start.

## License

MIT