venv-manager

Один уровень управления Python-окружениями для разработчиков и каждого AI-кодинг-агента.

Написан на Go. Один статический бинарник, без зависимостей во время выполнения, кроме python3 (или uv, если доступен).

GIF выше — настоящий: venv-manager watch app.py --venv X отслеживает файл, сканирует его импорты с помощью крошечного AST-подобного парсера и pip-устанавливает всё недостающее — при каждом изменении файла. Укажите его на скрипт, над которым итерирует LLM, и venv сходится вместе с кодом.

Зачем

Claude, Codex, Cursor и другие кодинг-агенты уже умеют выполнять shell-команды, создавать .venv и запрашивать разрешение на чувствительные операции. Чего у них нет — так это долговременного состояния Python-окружения.

Песочница защищает машину. venv-manager защищает рабочий процесс: он даёт каждому агенту одни и те же окружения, метаданные, историю пакетов и путь восстановления, независимо от того, какой клиент запущен.

Два сценария отказа привели к созданию этого инструмента:

1. Человеческий хаос. Venv размножаются по ~, кэш-каталоги съедают гигабайты, синтаксис активации различается в зависимости от оболочки, а клонирование «того самого окружения» означает копирование pip freeze между терминалами.

2. Агентный хаос. AI-агенты могут устанавливать в неправильный интерпретатор, оставлять частичные изменения и терять контекст окружения при переключении клиента или начале новой сессии.

venv-manager решает (1) с помощью чистого CLI и (2) с помощью общего Model Context Protocol сервера, постоянного реестра, типизированных снимков и различий, обратимых изменений пакетов, временных venv с песочницей на уровне ОС и наблюдателя за файлами, который поддерживает venv в синхронизации с развивающимся кодом.

Что песочница агента не решает

Два уровня дополняют друг друга: разрешения агента контролируют что может произойти сейчас; venv-manager записывает что существует, что изменилось и как восстановить.

Related MCP server: Sympathy-MCP

Установка

Homebrew (macOS, Linux):

brew install jacopobonomi/tap/venv-manager

Однострочный скрипт установки (macOS, Linux):

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

Из исходников:

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

Требуется Go 1.24+ для сборки, Python 3.x во время выполнения.

Интеграция с AI

MCP-сервер

Предоставляет операции с venv как нативные инструменты Model Context Protocol. Claude, Codex, Cursor, Zed и другие MCP-клиенты вызывают одни и те же типизированные инструменты и работают с одним и тем же постоянным состоянием окружения, а не угадывают вызовы оболочки независимо.

Подключите его в Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

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

Предоставляемые инструменты (JSON-RPC 2.0 через stdio):

Сервер по умолчанию использует политику safe. Установка, откат, удаление и произвольное выполнение требуют confirm: true. Используйте --policy read-only для клиентов только для просмотра, --policy full для неограниченной совместимости и повторяйте --allow-tool NAME, чтобы открыть только явный поднабор. Эти политики — защита в глубину: они остаются согласованными, даже когда разные клиенты имеют разные настройки одобрения.

Реализация использует ноль сторонних MCP-зависимостей. JSON-RPC 2.0 с разделителями строк на stdin/stdout.

Временное выполнение (в стиле uvx, с песочницей)

# 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 использует sandbox-exec на macOS и bwrap на Linux. Профиль «запрещено по умолчанию» с явными списками разрешений для пути venv, /tmp и управления процессами. Сеть не разделяется.

Наблюдатель за файлами

venv-manager watch app.py --venv myenv

fsnotify на родительском каталоге (переживает атомарные перезаписи редактора), задержка 500 мс, затем:

1. AST-подобное регулярное сканирование .py-файлов (пропускает docstring'и, относительные импорты, локальные модули/пакеты и вендорные каталоги, такие как .venv, .git, __pycache__, node_modules)

2. Фильтрация по набору модулей стандартной библиотеки

3. Разрешение импорт-имени → псевдонимов pip-пакетов (cv2 → opencv-python, sklearn → scikit-learn, PIL → Pillow, bs4 → beautifulsoup4, yaml → PyYAML, ...)

4. Сравнение с установленными пакетами

5. pip install разницы

Venv всегда является надмножеством требований текущего файла. Это цикл, который демонстрирует GIF выше.

Постоянный реестр

Каждое окружение отслеживается в ~/.venvs/.venv-manager/registry.json с временными метками создания и последнего использования, необязательным путём проекта и тегами. Записи атомарны, и реестр самосогласуется с живыми каталогами venv.

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

prune использует last_used_at из реестра, а не время модификации каталога, когда метаданные доступны.

JSON-снимок как однократный контекстный праймер

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

Один вызов инструмента — всё, что нужно агенту для рассуждения об окружении. freeze_hash позволяет агенту обнаружить расхождение между двумя вызовами describe за O(1), а не сравнивать списки пакетов.

Команды

Большинство команд чтения также принимают --json для стабильного, машиночитаемого вывода.

Конфигурация

~/.config/venv-manager/config.json (учитывает $XDG_CONFIG_HOME и $VENV_MANAGER_CONFIG):

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

Инициализация: venv-manager config init.

Бэкенд uv

Если uv находится в PATH и use_uv: true, команда create выполняет uv venv. Обычно в 10–100 раз быстрее, чем python -m venv при холодном кэше.

Разработка

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 запускает go vet, go test -race на Ubuntu + macOS и интеграционные тесты на Ubuntu с Python 3.12.

Архитектура:

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

Лицензия

MIT.

Автор

Jacopo Bonomi