ccvm

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