cvm documentation
Technical reference for isolating and sharing Claude Code environments with cvm.
Getting started
Install cvm, wire shell hooks, create your first environment.
Command reference
Every public subcommand, flag, and alias in one place.
Core concepts
CLAUDE_CONFIG_DIR, shims, activation protocol, and directory layout.
Examples
Copy-paste workflows for day-to-day Claude Code isolation.
What cvm is
cvm (Claude Virtualenv Manager) isolates Claude Code configuration the way Python venv isolates packages. Each environment is a directory under ~/.cvm/envs/<name>. When active, cvm points Claude Code at that directory via CLAUDE_CONFIG_DIR — without patching Claude Code.
Beyond isolation, cvm shares reproducible setups through a secrets-free cvm.yaml, can seed environments from ~/.claude, auto-activates from a project .cvm file, and runs several Claude sessions in parallel.
Audience
- Developers juggling multiple Claude Code configs (clients, repos, personal vs work).
- Teams that want matching MCP servers and skills without committing tokens.
- Anyone wiring statuslines or shell tooling around
CVM_ENV.
Mental model
- Create an environment — directory, optional credentials, optional inherited skills,
bin/shims. - Activate with
cvm use(shell hooks) or run once withcvm open/cvm run. - Claude Code reads and writes under that environment’s config directory.
- Optionally export / import the non-secret surface as
cvm.yaml.
use / deactivate. A child process cannot mutate its parent shell. Install hooks with cvm init.How-to guides
Create & open
One-shot --open and everyday activate flows.
Inherit skills
Seed from ~/.claude with --inherit.
Share with the team
Export/import cvm.yaml without leaking secrets.
Auto-activate
Project-local .cvm files like a lightweight direnv.
Parallel sessions
Several cvm open processes side by side.
Per-env secrets
Edit .env safely; values never export.