NEW registry · snapshot diff · MCP policy

One Python runtime layer. Every AI agent.

Claude, Codex and other coding agents can run Python. venv-manager gives all of them the same persistent, observable and reversible environment state.

Install venv-manager Read the source
Single binary MIT licensed No daemon
~/projects/agent-workspace
❯ venv-manager create research --python 3.12 ✨ Created virtual environment 'research' ❯ venv-manager watch app.py --venv research watching app.py — syncing imports on change [14:22:08] installing missing: pandas, rich [14:22:10] ok: 2 installed ❯ venv-manager snapshot research -l before-agent-run 📸 Snapshot created · 27 packages ❯ venv-manager exec --sandbox --with requests -- python task.py isolated run complete · environment removed ❯
1static Go binary
16typed MCP tools
0background daemons
3interfaces: CLI, TUI, MCP

Get running

Install once.
Use everywhere.

Requires Python 3 at runtime. Use Homebrew, grab a release binary, or build from source with Go 1.24+.

$ brew install jacopobonomi/tap/venv-manager

Then run venv-manager doctor to verify Python, uv and your environment directory.

Beyond create & delete

More than sandboxing. Durable environment control.

Agent permissions decide what may happen now. venv-manager records what exists, what changed and how to recover — across clients and sessions.

01 / STATE

Snapshot before the risky part.

Capture pip freeze, label the state, compare it later and roll back without deleting the working environment first.

02 / SYNC

Let the environment follow the code.

Watch Python files, detect third-party imports, ignore local modules and install only what is missing — serially and safely.

03 / ISOLATE

Ephemeral exec

Create → install → run → destroy. Add --sandbox for OS-level network and write restrictions.

04 / EXPLAIN

Know why it is there

why myenv numpy walks reverse dependencies back to the top-level package.

05 / INSPECT

Machine-readable truth

describe returns paths, versions, packages, size, activation commands and a stable freeze hash.

06 / REGISTRY

Usage metadata that persists

Track creation, real last use, project associations and tags. prune acts on metadata instead of guesses.

Native MCP server

The sandbox protects your machine. This protects your workflow.

Run venv-manager mcp and give Claude, Codex, Cursor, Zed or any MCP client one consistent source of truth instead of separate terminal sessions full of assumptions.

  • Shared state: switch agents without losing environment context.
  • Observable changes: see exactly which packages an agent added, removed or upgraded.
  • Recovery: snapshot before a run and roll back when an installation goes wrong.
  • Consistent policy: keep read-only, safe or allowlisted tools across different clients.
Permissions control what an agent may do. venv-manager records what it did and gives you a path back.
Configure MCP
describe_venvlist_venvs create_venvremove_venv exec_ephemeralrun_in_venv install_packagessnapshot_venv list_snapshotsrollback_venv diff_snapshotsscan_imports whylist_registry set_registry_metadatadoctor

One workflow, three interfaces

Human-friendly outside.
Predictable inside.

01

Use the CLI in scripts

Concise commands, structured JSON output and shell completion for repeatable automation.

venv-manager list --json
02

Browse through the TUI

Inspect environment sizes and packages, clean caches and remove stale runtimes interactively.

venv-manager tui
03

Connect an AI client

The same manager operations become typed tools over stdio, with validation at the boundary.

venv-manager mcp

Give every AI agent the same Python environment truth.

Install now