venv-manager

開発者とすべてのAIコーディングエージェントのための、単一のPython環境制御レイヤー。

Goで書かれています。単一の静的バイナリで、python3（または利用可能な場合はuv）以外のランタイム依存関係はありません。

上のGIFは実際の動作です: venv-manager watch app.py --venv X はファイルを監視し、小さなASTライトパーサーでインポートをスキャンし、不足しているものをpipインストールします — ファイルが変更されるたびに。LLMが反復処理しているスクリプトにこれを向けると、venvはコードの進化に合わせて収束します。

なぜ

Claude、Codex、Cursor、その他のコーディングエージェントは、すでにシェルコマンドを実行したり、.venvを作成したり、機密操作の前に承認を求めることができます。しかし、彼らが共有しないのは、永続的なPython環境の状態です。

サンドボックスはマシンを保護します。venv-managerはワークフローを保護します: 実行中のクライアントに関係なく、すべてのエージェントに同じ環境、メタデータ、パッケージ履歴、復旧パスを提供します。

このツールを生んだ2つの障害モード:

1. 人間の乱雑さ。 venvが~全体に増殖し、キャッシュディレクトリがGBを消費し、アクティベーション構文がシェルごとに異なり、「動作した環境」を複製するには、ターミナル間でpip freezeをコピー＆ペーストする必要があります。

2. エージェントの乱雑さ。 AIエージェントは誤ったインタープリタにインストールしたり、部分的な変更を残したり、クライアントを切り替えたり新しいセッションを開始すると環境コンテキストを失ったりする可能性があります。

venv-managerは、(1)をクリーンなCLIで解決し、(2)を共有のModel Context Protocolサーバー、永続的なレジストリ、型付きのスナップショットと差分、元に戻せるパッケージ変更、OSレベルのサンドボックスを備えた一時的なvenv、そして進化するコードとvenvを同期させるファイルウォッチャーで解決します。

エージェントサンドボックスが解決しないこと

2つのレイヤーは相互に補完します: エージェントの権限は今何が起こるかを制御し、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ライト正規表現スキャン（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'"
  }
}

1回のツール呼び出しで、エージェントが環境を推論するために必要なすべてを取得できます。freeze_hashにより、エージェントはパッケージリストの差分を取る代わりに、2つの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 バックエンド

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