Installation Guide

Install CVC
Cognitive Version Control

Multiple installation methods for every setup — from a 30-second one-liner to Docker and source builds. Works on macOS, Linux, and Windows.

3.11+Python version

~80 MBInstall size

512 MBRAM required

< 200 MBDisk space

Quick Start

Fastest path — one command handles everything

bash

curl -fsSL https://jaimeena.com/cvc/install.sh | bash

Installs Python 3.11+ via pyenv if needed, then installs CVC. Works on macOS 12+ and Ubuntu 20.04+.

The one-line installer automatically checks for Python 3.11+, installs it via pyenv if missing, then installs CVC with all providers. After it finishes, just run cvc.

System Requirements

CVC is lightweight and runs on virtually every developer machine

Operating System

macOS 12 (Monterey) or later
Ubuntu 20.04 / Debian 11 or later
Windows 10 / 11 (PowerShell 5.1+)
Any Linux with glibc 2.31+
WSL 2 on Windows

Python

Python 3.11, 3.12, or 3.13 (recommended)
Python 3.14 (experimental support)
pip 23+ or uv 0.4+ for package management
conda / mamba also supported

Hardware

RAM: 512 MB minimum (2 GB+ recommended)
Disk: ~200 MB for CVC + dependencies
CPU: Any modern x86_64 or ARM64
GPU: Not required — all compute via API

Network

Internet for cloud providers (Anthropic/OpenAI/Google)
100% offline with Ollama or LM Studio
Proxy support via HTTP_PROXY env vars
Outbound HTTPS (port 443) only

Installation Methods

Choose the method that fits your workflow

Method 1 — pip

Standard

The standard Python package manager. Works with any Python 3.11+ install.

bash

# All providers (recommended)
pip install "tm-ai[all]"

# Specific provider only
pip install "tm-ai[anthropic]"   # Claude
pip install "tm-ai[openai]"      # GPT
pip install "tm-ai[google]"      # Gemini
pip install tm-ai                # Core only (Ollama / LM Studio)

The [all] extra installs Anthropic + OpenAI + Google SDK clients. For Ollama and LM Studio, only the core package is needed (they use plain HTTP).

Method 2 — uv

Recommended for power users

10–100× faster than pip. Manages Python versions and virtual environments automatically.

bash

# Install uv first (skip if already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh          # macOS / Linux
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"  # Windows

# Install CVC as a global tool (available in every terminal)
uv tool install "tm-ai[all]"

# Or install into a project virtualenv
uv add "tm-ai[all]"

# Upgrade
uv tool upgrade tm-ai

Method 3 — conda / mamba

Data Science

Ideal if you use Anaconda, Miniconda, or Mamba for ML/data workflows.

bash

# Create a dedicated environment
conda create -n cvc-env python=3.12 -y
conda activate cvc-env

# Install CVC via pip inside the conda env
pip install "tm-ai[all]"

cvc --version

Method 4 — Docker

Containerized

Fully isolated container. Great for CI/CD pipelines and reproducible environments.

bash

# Interactive agent mode
docker run -it --rm \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -v $(pwd):/workspace -w /workspace \
  ghcr.io/mannuking/cvc:latest

# Proxy server in background
docker run -d --name cvc-proxy \
  -p 8000:8000 \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  ghcr.io/mannuking/cvc:latest cvc serve

Mount your project with -v $(pwd):/workspace. The .cvc/ state directory is created inside the mounted folder.

Method 5 — From Source

Development

For contributors and power users who want the latest features or want to modify CVC.

bash

# Clone the private repository (requires access)
cd cvc

# With uv (recommended)
uv sync --extra dev

# With pip
pip install -e ".[dev]"

cvc --version

CVC is a private, closed-source project. Source installs require authorized access. For production use PyPI.

Provider Setup & API Keys

Connect CVC to your preferred AI provider

Anthropic (Claude)

Best reasoning quality + prompt caching = 90% cheaper in practice

Recommended

Install command

pip install "tm-ai[anthropic]"

Environment variable

ANTHROPIC_API_KEY

Get your API key at console.anthropic.com/settings/keys

bash

# macOS / Linux / WSL
export ANTHROPIC_API_KEY="your-api-key-here"

# Windows PowerShell
$env:ANTHROPIC_API_KEY = "your-api-key-here"

# Or use CVC interactive wizard
cvc setup

Supported models

claude-opus-4-6, claude-sonnet-4-5, claude-haiku-4-5

Use the setup wizard. Running cvc setup walks you through provider and model selection interactively. Config is saved to ~/.cvc/config.json.

First Run

Get CVC running in under 2 minutes

Verify installation

bash

cvc --version
# Expected: cvc version 1.9.0

cvc doctor
# Checks Python, config, Git, and API connectivity

Initialize CVC in your project

bash

cd my-project
cvc init
# Creates .cvc/ directory (your time machine storage)
# Optionally add to .gitignore:
echo ".cvc/" >> .gitignore

Start the AI agent

bash

cvc
# Starts the interactive AI coding session

# Key slash commands inside the agent:
# /save "checkpoint name"   - save current brain state
# /branch feature-x         - create an isolated branch
# /log                       - view all checkpoints
# /rewind <hash>             - restore any checkpoint
# /status                    - current branch + HEAD

Usage Modes

CVC works in three powerful modes

Agent Mode

Built-in AI coding assistant with 17 tools. Just type cvc.

cvc

Proxy Mode

Wrap Claude Code, Cursor, Aider with CVC time-travel.

cvc launch claude

MCP Mode

IDE integration via Model Context Protocol.

cvc mcp

Tool Integrations

Run any AI tool through CVC's time machine

Tool	Launch Command	Notes
Claude Code	cvc launch claude	Auto-sets ANTHROPIC_BASE_URL. Zero config.
Aider	cvc launch aider	All Aider options work as normal + time-travel.
Cursor	cvc launch cursor	Opens Cursor with Base URL pointed to CVC proxy.
VS Code (MCP)	cvc mcp	Add to .vscode/mcp.json. Works with Copilot chat.
Windsurf	cvc mcp	Add as MCP server in Windsurf settings.
Continue / Cline	cvc serve	Point to http://127.0.0.1:8000/v1 as base URL.
Codex CLI	cvc launch codex	Set model_provider to cvc in codex config.
LangChain	cvc serve	Use CVC function-calling tools in your chain.

json— VS Code MCP setup

// .vscode/mcp.json
{
  "servers": {
    "cvc": { "command": "cvc", "args": ["mcp"], "type": "stdio" }
  }
}

Updating CVC

Stay on the latest version for new features and bug fixes

bash

# pip
pip install --upgrade tm-ai

# uv
uv tool upgrade tm-ai

# Check current version
cvc --version

# See what changed
cvc --changelog

Uninstalling

Clean removal — CVC leaves nothing behind

bash

# Remove CVC package
pip uninstall tm-ai
# or
uv tool uninstall tm-ai

# Remove global config (optional)
rm -rf ~/.cvc                      # macOS / Linux
Remove-Item -Recurse ~/.cvc        # Windows PowerShell

# Remove project data (optional)
rm -rf .cvc     # WARNING: deletes all your checkpoints

Important: The .cvc/ folder contains all your saved checkpoints. Deleting it is irreversible. Export important sessions first with cvc export.

Troubleshooting

Common issues and how to fix them instantly

"command not found: cvc" after install

Python scripts directory is not in PATH.

bash

# Find where pip installs scripts:
python -m site --user-scripts

# Add to PATH (bash/zsh):
export PATH="$HOME/.local/bin:$PATH"

# Windows: add %APPDATA%\Python\Scripts to System PATH

API key error / AuthenticationError

Check that your key is correctly set and has sufficient credits.

bash

# Verify key is set
echo $ANTHROPIC_API_KEY

# Re-run setup
cvc setup

# Test connectivity
cvc doctor --check-api

Ollama connection refused

Ollama service is not running. Start it first.

bash

# macOS / Linux
ollama serve &

# Windows: Start from system tray or run ollama.exe serve

# Verify running:
curl http://localhost:11434/api/tags

pip install fails with build errors

Some dependencies need a C compiler. Install build tools.

bash

# Ubuntu / Debian
apt install build-essential python3-dev

# macOS
xcode-select --install

# Windows: install Visual C++ Build Tools

Permission denied on install

Use --user flag or a virtual environment.

bash

# Install for current user only (no sudo needed)
pip install --user "tm-ai[all]"

# Or use a virtual environment
python -m venv .venv && source .venv/bin/activate
pip install "tm-ai[all]"

CVC running slowly or high memory use

Use branching to reduce context size.

bash

# Inside the agent, branch before large tasks
/branch big-refactor

# Merge back when done:
/checkout main

Run cvc doctor for an automated health check — it tests Python version, config, Git, and API connectivity and tells you exactly what needs fixing.

CVC installed? Explore more.

Read the full documentation or return to the CVC overview.

Full Documentation CVC Overview PyPI

Install CVCCognitive Version Control

Quick Start

System Requirements

Operating System

Python

Hardware

Network

Installation Methods

Method 1 — pip

Method 2 — uv

Method 3 — conda / mamba

Method 4 — Docker

Method 5 — From Source

Provider Setup & API Keys

Anthropic (Claude)

First Run

Usage Modes

Agent Mode

Proxy Mode

MCP Mode

Tool Integrations

Updating CVC

Uninstalling

Troubleshooting

CVC installed? Explore more.

Install CVC
Cognitive Version Control