@jerryan/pi-pyvenv

A pi 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

pi install npm:@jerryan/pi-pyvenv

Or install from git:

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