venv-manager

개발자 그리고 모든 AI 코딩 에이전트를 위한 하나의 Python 환경 제어 계층입니다.

Go로 작성되었습니다. 단일 정적 바이너리이며, 런타임 의존성은 python3(또는 사용 가능한 경우 uv)뿐입니다.

위 GIF는 실제입니다: venv-manager watch app.py --venv X는 파일을 모니터링하고, 작은 AST-lite 파서로 import를 스캔하여 누락된 패키지를 pip-install합니다 — 파일이 변경될 때마다. LLM이 반복 작업 중인 스크립트에 이 명령을 지정하면 코드가 발전함에 따라 venv도 수렴합니다.

왜 필요한가

Claude, Codex, Cursor 및 기타 코딩 에이전트는 이미 셸 명령을 실행하고, .venv를 생성하고, 민감한 작업 전에 승인을 요청할 수 있습니다. 그러나 이들이 공유하지 않는 것은 지속적인 Python 환경 상태입니다.

샌드박싱은 머신을 보호합니다. venv-manager는 워크플로우를 보호합니다: 실행 중인 클라이언트와 무관하게 모든 에이전트에게 동일한 환경, 메타데이터, 패키지 기록 및 복구 경로를 제공합니다.

이 도구를 만든 두 가지 실패 모드:

1. 인간의 무질서. venv가 ~ 전반에 걸쳐 증식하고, 캐시 디렉터리가 GB를 차지하며, 활성화 구문이 셸마다 다르고, "작동했던 환경"을 복제하려면 터미널 간에 pip freeze를 복사-붙여넣기해야 합니다.

2. 에이전트의 무질서. AI 에이전트는 잘못된 인터프리터에 설치하거나, 부분적인 변경을 남기거나, 클라이언트를 전환하거나 새 세션을 시작할 때 환경 컨텍스트를 잃을 수 있습니다.

venv-manager는 (1)을 깔끔한 CLI로 해결하고, (2)를 공유 Model Context Protocol 서버, 영구 레지스트리, 타입화된 스냅샷 및 diff, 되돌릴 수 있는 패키지 변경, OS 수준 샌드박싱을 갖춘 임시 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"]
    }
  }
}

노출된 도구 (stdio를 통한 JSON-RPC 2.0):

서버는 기본적으로 safe 정책을 사용합니다. 설치, 롤백, 제거 및 임의 실행에는 confirm: true가 필요합니다. 검사 전용 클라이언트에는 --policy read-only, 무제한 호환성에는 --policy full, 명시적 하위 집합만 노출하려면 --allow-tool NAME을 반복 사용하세요. 이러한 정책은 심층 방어입니다: 서로 다른 클라이언트가 서로 다른 승인 설정을 가져도 일관성을 유지합니다.

구현은 서드파티 MCP 의존성을 사용하지 않습니다. stdin/stdout에서 줄바꿈으로 구분된 JSON-RPC 2.0.

임시 실행 (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는 macOS에서 sandbox-exec, Linux에서 bwrap을 사용합니다. venv 경로, /tmp, 프로세스 관리를 위한 명시적 허용 목록이 있는 기본 거부 프로필. 네트워크는 비공유입니다.

파일 감시자

venv-manager watch app.py --venv myenv

부모 디렉터리에서 fsnotify (편집기의 원자적 이름 변경 쓰기에서도 생존), 500ms 디바운스, 그 후:

1. .py 파일의 AST-lite 정규식 스캔 (docstring, 상대 import, 로컬 모듈/패키지, .venv, .git, __pycache__, node_modules 같은 벤더 디렉터리 건너뜀)

2. 표준 라이브러리 모듈 집합으로 필터링

3. import 이름 → pip 패키지 별칭 해석 (cv2 → opencv-python, sklearn → scikit-learn, PIL → Pillow, bs4 → beautifulsoup4, yaml → PyYAML, ...)

4. 설치된 패키지와 diff

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 호출 간의 드리프트를 패키지 목록을 diff하는 대신 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 백엔드

PATH에 uv가 있고 use_uv: true이면 create는 uv venv를 실행합니다. 일반적으로 콜드 캐시에서 python -m venv보다 10~100배 빠릅니다.

개발

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는 Ubuntu + macOS에서 go vet, go test -race를 실행하고, 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