venv-manager

Una capa de control de entornos Python para desarrolladores y para cada agente de IA.

Escrito en Go. Un único binario estático, sin dependencias de ejecución más allá de python3 (o uv, si está disponible).

El GIF anterior es real: venv-manager watch app.py --venv X monitoriza un archivo, escanea sus imports con un pequeño analizador tipo AST-lite, e instala con pip lo que falte — cada vez que el archivo cambia. Apúntalo a un script sobre el que un LLM esté iterando y el venv converge a medida que lo hace el código.

Por qué

Claude, Codex, Cursor y otros agentes de codificación ya pueden ejecutar comandos de shell, crear un .venv y pedir aprobación antes de operaciones sensibles. Lo que no comparten es un estado de entorno Python duradero.

El sandboxing protege la máquina. venv-manager protege el flujo de trabajo: da a cada agente los mismos entornos, metadatos, historial de paquetes y ruta de recuperación, independientemente del cliente que esté ejecutándose.

Dos modos de fallo impulsaron esta herramienta:

1. Dispersión humana. Los venvs se multiplican en ~, los directorios de caché consumen GB, la sintaxis de activación varía según el shell, y clonar "el entorno que funcionó" significa copiar y pegar pip freeze entre terminales.

2. Dispersión de agentes. Los agentes de IA pueden instalar en el intérprete equivocado, dejar cambios parciales y perder el contexto del entorno al cambiar de cliente o iniciar una nueva sesión.

venv-manager resuelve (1) con una CLI limpia y (2) con un servidor Model Context Protocol compartido, un registro persistente, snapshots y diffs tipados, cambios de paquetes reversibles, venvs efímeros con sandboxing a nivel de SO, y un vigilador de archivos que mantiene un venv sincronizado con el código en evolución.

Lo que el sandbox del agente no resuelve

Las dos capas se complementan: los permisos del agente controlan lo que puede ocurrir ahora; venv-manager registra qué existe, qué cambió y cómo recuperarse.

Related MCP server: Sympathy-MCP

Instalación

Homebrew (macOS, Linux):

brew install jacopobonomi/tap/venv-manager

Script de instalación de una línea (macOS, Linux):

curl -sSL https://raw.githubusercontent.com/jacopobonomi/venv_manager/main/install.sh | bash

Desde el código fuente:

git clone https://github.com/jacopobonomi/venv_manager && cd venv_manager
make install

Requiere Go 1.24+ para compilar, Python 3.x en tiempo de ejecución.

Integración con IA

Servidor MCP

Expone operaciones de venv como herramientas nativas de Model Context Protocol. Claude, Codex, Cursor, Zed y otros clientes MCP llaman a las mismas herramientas tipadas y operan sobre el mismo estado de entorno persistente en lugar de adivinar invocaciones de shell de forma independiente.

Conéctalo en Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "venv-manager": {
      "command": "venv-manager",
      "args": ["mcp", "--policy", "safe"]
    }
  }
}

Herramientas expuestas (JSON-RPC 2.0 sobre stdio):

El servidor usa por defecto la política safe. La instalación, el rollback, la eliminación y la ejecución arbitraria requieren confirm: true. Usa --policy read-only para clientes solo de inspección, --policy full para compatibilidad sin restricciones, y repite --allow-tool NAME para exponer solo un subconjunto explícito. Estas políticas son defensa en profundidad: siguen siendo consistentes incluso cuando diferentes clientes tienen distintos ajustes de aprobación.

La implementación usa cero dependencias MCP de terceros. JSON-RPC 2.0 delimitado por nuevas líneas en stdin/stdout.

Ejecución efímera (estilo uvx, con sandbox)

# create → install → run → destroy, all in one call
venv-manager exec --with requests -- python -c "import requests; print(requests.__version__)"

# with an OS sandbox: no network, no writes outside /tmp + the ephemeral venv
venv-manager exec --sandbox --with pandas -- python untrusted.py

--sandbox usa sandbox-exec en macOS y bwrap en Linux. Perfil de denegación por defecto con listas de permitidos explícitas para la ruta del venv, /tmp y la gestión de procesos. La red no está compartida.

Vigilador de archivos

venv-manager watch app.py --venv myenv

fsnotify en el directorio padre (sobrevive a escrituras de renombrado atómico del editor), 500 ms de debounce, luego:

1. Escaneo regex tipo AST-lite de archivos .py (omite docstrings, imports relativos, módulos/paquetes locales y directorios vendored como .venv, .git, __pycache__, node_modules)

2. Filtro contra un conjunto de módulos de la stdlib

3. Resuelve alias de nombre-de-import → paquete-pip (cv2 → opencv-python, sklearn → scikit-learn, PIL → Pillow, bs4 → beautifulsoup4, yaml → PyYAML, ...)

4. Diff contra los paquetes instalados

5. pip install del delta

El venv es siempre un superconjunto de los requisitos del archivo actual. Este es el bucle que ejercita el GIF de demostración anterior.

Registro persistente

Cada entorno se rastrea en ~/.venvs/.venv-manager/registry.json con marcas de tiempo de creación y último uso, una ruta de proyecto opcional y etiquetas. Las escrituras son atómicas y el registro se reconcilia con los directorios de venv vivos.

venv-manager registry
venv-manager registry set research --project ~/work/paper --tag data,ai
venv-manager registry research

prune usa last_used_at del registro en lugar del tiempo de modificación del directorio cuando los metadatos están disponibles.

Snapshot JSON como preparación de contexto en una sola llamada

venv-manager describe myenv

{
  "name": "myenv",
  "path": "/Users/me/.venvs/myenv",
  "python_version": "3.12.6",
  "python_path": "/Users/me/.venvs/myenv/bin/python",
  "pip_path": "/Users/me/.venvs/myenv/bin/pip",
  "packages": ["requests==2.34.2", "rich==15.0.0", ...],
  "package_count": 12,
  "size_bytes": 45123456,
  "size_human": "43.03 MB",
  "modified_at": "2026-07-20T15:41:35Z",
  "freeze_hash": "sha256:2c58d830...",
  "activation": {
    "bash": "source '/Users/me/.venvs/myenv/bin/activate'",
    "zsh":  "source '/Users/me/.venvs/myenv/bin/activate'",
    "fish": "source '/Users/me/.venvs/myenv/bin/activate.fish'"
  }
}

Una llamada de herramienta, todo lo que un agente necesita para razonar sobre el entorno. freeze_hash permite a un agente detectar desviación entre dos llamadas describe en O(1) en lugar de comparar listas de paquetes.

Comandos

La mayoría de los comandos de lectura también aceptan --json para una salida estable y analizable por máquina.

Configuración

~/.config/venv-manager/config.json (respeta $XDG_CONFIG_HOME y $VENV_MANAGER_CONFIG):

{
  "base_dir": "/custom/path/to/venvs",
  "default_python": "3.12",
  "use_uv": true,
  "prune_after_days": 90
}

Inicialización: venv-manager config init.

Backend uv

Si uv está en PATH y use_uv: true, create ejecuta uv venv. Normalmente 10–100× más rápido que python -m venv con caché fría.

Desarrollo

make build            # go build -o bin/venv-manager
make test             # unit tests
make demo             # regenerate scripts/demo/demo.gif via VHS
go test -tags=integration ./internal/manager/...   # integration tests (real pip, real PyPI)

El CI ejecuta go vet, go test -race en Ubuntu + macOS, y pruebas de integración en Ubuntu con Python 3.12.

Arquitectura:

cmd/venv-manager/           cobra CLI
internal/manager/           core operations (create, install, snapshot, scan, watch, exec, describe, ...)
internal/config/            XDG-aware JSON config
internal/mcp/               JSON-RPC 2.0 MCP server (stdio)
internal/tui/               Bubble Tea browser
internal/utils/             platform helpers, size formatting

Licencia

MIT.

Autor

Jacopo Bonomi