venv-manager

Eine Kontrollebene für Python-Umgebungen für Entwickler und jeden KI-Coding-Agenten.

Geschrieben in Go. Eine statische Binärdatei, keine Laufzeitabhängigkeiten außer python3 (oder uv, falls verfügbar).

Das obige GIF ist echt: venv-manager watch app.py --venv X überwacht eine Datei, scannt ihre Importe mit einem winzigen AST-lite-Parser und installiert per pip, was fehlt – bei jeder Änderung der Datei. Richten Sie es auf ein Skript, an dem ein LLM arbeitet, und die venv konvergiert mit dem Code.

Warum

Claude, Codex, Cursor und andere Coding-Agenten können bereits Shell-Befehle ausführen, ein .venv erstellen und vor sensiblen Operationen um Genehmigung bitten. Was sie nicht teilen, ist ein dauerhafter Zustand der Python-Umgebung.

Sandboxing schützt die Maschine. venv-manager schützt den Workflow: Es gibt jedem Agenten dieselben Umgebungen, Metadaten, Paketverlauf und Wiederherstellungspfade, unabhängig vom gerade laufenden Client.

Zwei Fehlermodi haben dieses Tool angetrieben:

1. Menschliche Ausbreitung. Venvs vermehren sich über ~, Cache-Verzeichnisse fressen GB, die Aktivierungssyntax variiert je nach Shell, und das Klonen von „der Umgebung, die funktioniert hat" bedeutet, pip freeze zwischen Terminals zu kopieren.

2. Agenten-Ausbreitung. KI-Agenten können in den falschen Interpreter installieren, partielle Änderungen hinterlassen und den Umgebungskontext verlieren, wenn Sie den Client wechseln oder eine neue Sitzung starten.

venv-manager löst (1) mit einer sauberen CLI und (2) mit einem gemeinsamen Model Context Protocol Server, einem persistenten Registry, typisierten Snapshots und Diffs, umkehrbaren Paketänderungen, ephemeren Venvs mit OS-Level-Sandboxing und einem Datei-Watcher, der eine venv mit sich entwickelndem Code synchron hält.

Was die Agenten-Sandbox nicht löst

Die beiden Ebenen ergänzen sich: Agentenberechtigungen kontrollieren, was jetzt passieren darf; venv-manager zeichnet auf, was existiert, was sich geändert hat und wie man es wiederherstellt.

Related MCP server: Sympathy-MCP

Installation

Homebrew (macOS, Linux):

brew install jacopobonomi/tap/venv-manager

Einzeiliges Installationsskript (macOS, Linux):

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

Aus dem Quellcode:

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

Erfordert Go 1.24+ zum Bauen, Python 3.x zur Laufzeit.

KI-Integration

MCP-Server

Stellt venv-Operationen als native Model Context Protocol-Tools bereit. Claude, Codex, Cursor, Zed und andere MCP-Clients rufen dieselben typisierten Tools auf und arbeiten mit demselben persistenten Umgebungszustand, anstatt unabhängig Shell-Aufrufe zu erraten.

Einrichtung in Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

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

Verfügbare Tools (JSON-RPC 2.0 über stdio):

Der Server verwendet standardmäßig die safe-Richtlinie. Installation, Rollback, Entfernung und beliebige Ausführung erfordern confirm: true. Verwenden Sie --policy read-only für reine Inspektions-Clients, --policy full für uneingeschränkte Kompatibilität, und wiederholen Sie --allow-tool NAME, um nur eine explizite Teilmenge freizugeben. Diese Richtlinien sind Defense in Depth: Sie bleiben konsistent, auch wenn verschiedene Clients unterschiedliche Genehmigungseinstellungen haben.

Die Implementierung verwendet keine Drittanbieter-MCP-Abhängigkeiten. Newline-getrenntes JSON-RPC 2.0 auf stdin/stdout.

Ephemere Ausführung (uvx-Stil, sandboxed)

# 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 verwendet sandbox-exec auf macOS und bwrap auf Linux. Deny-by-default-Profil mit expliziten Allow-Listen für den venv-Pfad, /tmp und Prozessverwaltung. Netzwerk ist nicht geteilt.

Datei-Watcher

venv-manager watch app.py --venv myenv

fsnotify auf dem übergeordneten Verzeichnis (überlebt atomare Rename-Schreibvorgänge des Editors), 500 ms Entprellung, dann:

1. AST-lite-Regex-Scan von .py-Dateien (überspringt Docstrings, relative Importe, lokale Module/Pakete und vendored Verzeichnisse wie .venv, .git, __pycache__, node_modules)

2. Filter gegen einen Stdlib-Modulsatz

3. Auflösung von Importname → pip-Paket-Aliassen (cv2 → opencv-python, sklearn → scikit-learn, PIL → Pillow, bs4 → beautifulsoup4, yaml → PyYAML, ...)

4. Diff gegen installierte Pakete

5. pip install des Deltas

Die venv ist immer eine Obermenge der aktuellen Dateianforderungen. Dies ist die Schleife, die das Demo-GIF oben ausführt.

Persistente Registry

Jede Umgebung wird in ~/.venvs/.venv-manager/registry.json mit Erstellungs- und letzte-Nutzung-Zeitstempeln, einem optionalen Projektpfad und Tags verfolgt. Schreibvorgänge sind atomar und die Registry gleicht sich mit Live-venv-Verzeichnissen ab.

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

prune verwendet die Registry-last_used_at anstelle der Verzeichnisänderungszeit, wenn Metadaten verfügbar sind.

JSON-Snapshot als Einzelaufruf-Kontext-Primer

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'"
  }
}

Ein Tool-Aufruf, alles, was ein Agent braucht, um über die Umgebung zu reasoning. freeze_hash ermöglicht einem Agenten, Drift zwischen zwei describe-Aufrufen in O(1) zu erkennen, anstatt Paketlisten zu diffen.

Befehle

Die meisten Lese-Befehle akzeptieren ebenfalls --json für stabile, maschinenlesbare Ausgabe.

Konfiguration

~/.config/venv-manager/config.json (berücksichtigt $XDG_CONFIG_HOME und $VENV_MANAGER_CONFIG):

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

Initialisierung: venv-manager config init.

uv-Backend

Wenn uv im PATH ist und use_uv: true gesetzt ist, führt create uv venv aus. Typischerweise 10–100× schneller als python -m venv bei kaltem Cache.

Entwicklung

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)

CI führt go vet, go test -race auf Ubuntu + macOS sowie Integrationstests auf Ubuntu mit Python 3.12 aus.

Architektur:

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

Lizenz

MIT.

Autor

Jacopo Bonomi