Venv-manager, a Python venv runtime for Humans and AI agents

Notifications You must be signed in to change notification settings

Fork 0

Star 35

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

24 Commits

24 Commits

.github/workflows

.github/workflows

cmd/venv-manager

cmd/venv-manager

internal

internal

scripts

scripts

.gitignore

.gitignore

CHANGELOG.md

CHANGELOG.md

LICENSE

LICENSE

Makefile

Makefile

README.md

README.md

go.mod

go.mod

go.sum

go.sum

install.sh

install.sh

terminal_example.gif

terminal_example.gif

Repository files navigation

A Python virtual-environment runtime for humans and AI agents.

Written in Go. One static binary, no runtime deps beyond python3 (or uv, if available).

The GIF above is real: venv-manager watch app.py --venv X monitors a file, scans its imports with a tiny AST-lite parser, and pip-installs whatever is missing — every time the file changes. Point it at a script an LLM is iterating on and the venv converges as the code does.

Why

Two failure modes drove this tool:

Human sprawl. Venvs multiply across ~, cache directories eat GB, activation syntax varies by shell, and cloning "the env that worked" means copy-pasting pip freeze between terminals.

Agent sprawl. LLMs generating Python routinely pip install into the wrong interpreter, forget to set VIRTUAL_ENV, leave half-installed packages behind after a crash, and have no typed API to reason about environment state — only shells.

venv-manager solves (1) with a clean CLI and (2) with a Model Context Protocol server, typed JSON snapshots, ephemeral venvs with OS-level sandboxing, and a file watcher that keeps a venv in sync with an evolving script.

Install

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

Or from source:

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

Requires Go 1.21+ to build, Python 3.x at runtime.

AI integration

MCP server

Exposes venv operations as native Model Context Protocol tools. Agentic clients (Claude Desktop, Cursor, Zed) call typed tools with JSON Schemas instead of guessing shell invocations.

Wire it up in Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

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

Tools exposed (JSON-RPC 2.0 over stdio):

Tool Purpose

list_venvs Names of all managed venvs.

create_venv {name, python_version?} → new venv, uses uv if configured.

remove_venv {name} → recursive delete.

describe_venv {name} → full snapshot: python version, packages, size, freeze hash, activation commands per shell.

install_packages `{name, packages[]

run_in_venv {name, command[]} → exec in the venv with VIRTUAL_ENV set and PATH prepended. Captured output.

exec_ephemeral {packages[], python_version?, command[]} → create-install-run-destroy in a single call.

snapshot_venv {name, label?} → capture pip freeze; enables rollback_venv.

list_snapshots {name} → newest-first.

rollback_venv {name, snapshot_id?} → uninstall all, reinstall from snapshot.

scan_imports {path, venv?} → third-party imports found; when venv is passed, reports which are missing.

doctor Python versions on PATH, uv availability, broken venvs.

Implementation: ~350 LOC, zero third-party MCP deps. Newline-delimited JSON-RPC 2.0 on stdin/stdout.

Ephemeral execution (uvx-style, 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 uses sandbox-exec on macOS and bwrap on Linux. Deny-by-default profile with explicit allow-lists for the venv path, /tmp, and process management. Network is unshared.

File watcher

venv-manager watch app.py --venv myenv

fsnotify on the parent directory (survives editor atomic-rename writes), 500 ms debounce, then:

AST-lite regex scan of .py files (skips docstrings, relative imports, and vendored dirs like .venv, .git, pycache, node_modules)

Filter against a stdlib module set

Resolve import-name → pip-package aliases (cv2 → opencv-python, sklearn → scikit-learn, PIL → Pillow, bs4 → beautifulsoup4, yaml → PyYAML, ...)

Diff against installed packages

pip install the delta

The venv is always a superset of the current file's requirements. This is the loop the demo GIF above exercises.

JSON snapshot as a single-call context 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", "pwsh": "/Users/me/.venvs/myenv/bin\\Activate.ps1", "cmd": "/Users/me/.venvs/myenv/bin\\activate.bat" } }

One tool call, everything an agent needs to reason about the environment. freeze_hash lets an agent detect drift between two describe calls in O(1) instead of diffing package lists.

Commands

Command Description

create [--python VER] Create a venv. Uses uv when use_uv: true in config.

list [--json] List venvs.

remove Delete a venv.

rename Rename and re-generate activation scripts via python -m venv --upgrade.

clone Fresh venv seeded with pip freeze of source.

packages [--json] Installed packages.

install pip install -r.

upgrade [name] [--global] Upgrade outdated packages (per venv or all).

clean [name] [--global] Purge pip cache + pycache dirs.

size [name] [--global] [--json] Disk usage.

activate Print shell command for eval $(...).

deactivate Print deactivate.

run -- Execute in a venv without activating; inherited stdio.

exec [--with pkgs] [-r req] [--python V] [--sandbox] [--keep] -- Ephemeral venv run.

describe Full JSON snapshot (see above).

scan [--venv N] [--json] Extract third-party imports; check against venv.

watch --venv N Auto-install missing imports on file change.

snapshot [-l LABEL] Capture pip-freeze state.

snapshots [--json] List snapshots (newest first).

rollback [snapshot-id] Uninstall all, reinstall from snapshot.

export Print portable manifest (name + python version + freeze) as JSON.

import Recreate venv from manifest.

prune [--days N] [--dry-run] [--json] Remove venvs unused for N days.

doctor [--json] Diagnose python versions, uv, broken venvs.

`config show path

mcp Model Context Protocol server on stdio.

tui Bubble Tea TUI browser.

`completion [bash zsh

Most read commands also accept --json for stable, machine-parseable output.

Configuration

~/.config/venv-manager/config.json (respects $XDG_CONFIG_HOME and $VENV_MANAGER_CONFIG):

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

Bootstrap: venv-manager config init.

uv backend

If uv is on PATH and use_uv: true, create runs uv venv. Typically 10–100× faster than python -m venv on cold cache.

Development

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 runs go vet, go test -race on Ubuntu + macOS, and integration tests on Ubuntu with Python 3.12.

Architecture:

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

License

MIT.

Author

Jacopo Bonomi

About

A powerful CLI tool for managing Python virtual environments with ease.

Topics

python

venv

cli-tool

virtual-environment

Resources

Readme

License

MIT license

Uh oh!

There was an error while loading. Please reload this page.

Activity

Stars

35 stars

Watchers

1 watching

Forks

0 forks

Report repository

Releases 7

v0.1.0

Latest

Jul 20, 2026

+ 6 releases

Uh oh!

There was an error while loading. Please reload this page.

Contributors

Uh oh!

There was an error while loading. Please reload this page.

Languages

Go 96.4%

Shell 2.5%

Makefile 1.1%