README
¶
ccvm
Documentation: English | 繁體中文
A version manager for Claude Code, similar to nvm for Node.js.
Background
Claude Code updates frequently. Sometimes a new version introduces bugs that affect daily usage. For example, issue #14407 reported a timeout problem that broke the tool for many users.
When this happens, the only option is to manually downgrade by editing package.json or running npm install with a specific version. This process is tedious and error-prone.
ccvm solves this problem by managing multiple versions of Claude Code locally. You can install any version, switch between them instantly, and roll back when a new release causes issues.
How it works
Claude Code's native installation stores its code in ~/.claude/local/node_modules. User data like settings, history, and projects are stored elsewhere in ~/.claude/, so they are not affected by version switching.
ccvm installs different versions to ~/.ccvm/versions/ and uses symlinks to switch the active version. On first switch, it backs up the original node_modules to ~/.ccvm/backup/ for safety.
Requirements
- Linux or macOS
- Claude Code installed via native installation method
- npm available in PATH
Installation
Using Go
go install github.com/davidleitw/ccvm/cmd/ccvm@latest
Using curl
curl -fsSL https://raw.githubusercontent.com/davidleitw/ccvm/master/install.sh | bash
The script installs ccvm to ~/.local/bin. Add it to your PATH if needed:
export PATH="$PATH:$HOME/.local/bin"
Usage
Check environment
Before using ccvm, verify that your environment is set up correctly:
ccvm doctor
This checks for Claude Code installation, npm availability, and current version status.
List available versions
# Show recent 10 versions
ccvm list
# Show all versions
ccvm list --all
# Show only locally installed versions
ccvm list --installed
Output markers:
*(green) - currently active version+(yellow) - installed locally
Show current version
ccvm current
Install a version
ccvm install 2.0.70
# Force reinstall
ccvm install 2.0.70 --force
This downloads the specified version to ~/.ccvm/versions/. It does not affect your current Claude Code installation.
Switch version
ccvm use 2.0.70
On first switch, ccvm backs up the original node_modules directory. Subsequent switches simply update the symlink.
If Claude Code is running, restart it after switching.
Remove a version
ccvm uninstall 2.0.70
# Skip confirmation
ccvm uninstall 2.0.70 --force
Aliases: ccvm rm, ccvm remove
Safety checks prevent removing:
- The currently active version
- The only installed version
Directory structure
~/.ccvm/
├── versions/ # Installed versions
│ ├── 2.0.70/
│ │ └── node_modules/
│ └── 2.0.71/
│ └── node_modules/
└── backup/
└── node_modules.original/ # Backup of original installation
Limitations
- Only supports Claude Code installed via native installation method
- Does not support Windows
- Requires npm to be available for installing versions
License
MIT
Directories