# CVC Getting Started Guide

> A complete walkthrough from zero to mastering CVC's cognitive version control. Website-ready.

---

## Quick Start — 60 Seconds

### Step 1: Install

```bash
pip install tm-ai
```

### Step 2: Launch

```bash
cvc
```

The setup wizard runs on first launch:
1. **Pick your provider** — Anthropic, OpenAI, Google, or Ollama (arrow-key selection)
2. **Enter API key** — paste your key (or skip for Ollama)
3. **Choose a model** — best models highlighted

That's it. You're coding with a time machine.

---

## Your First 10 Minutes with CVC

### Talk to Sofia

Sofia is CVC's built-in AI agent. Ask her anything:

```
You: Help me build a REST API with authentication using Express.js
Sofia: [creates project structure, implements routes, adds JWT auth]
```

### Save a Checkpoint

When the AI reaches a stable, correct state — save it:

```
/commit "auth API complete and working"
```

This creates an immutable snapshot of the entire AI conversation state. You can rewind to this exact moment at any time.

### Try an Experiment

Want to try something risky? Branch first:

```
/branch "add-rate-limiting"
You: Add rate limiting to all endpoints
Sofia: [implements rate limiting]
```

If the experiment succeeds — great, continue on this branch. If it fails:

```
/restore <commit-hash>
```

Instant rewind to before the experiment. Clean context, zero pollution.

### View Your History

```
/log
```

See every checkpoint, every branch, every decision. Your AI's full cognitive timeline.

### Search Past Knowledge

```
/search "database migration pattern"
```

CVC searches all your sessions by meaning — even across projects.

---

## Installation Options

### Standard Install (pip)

```bash
pip install tm-ai
```

### With UV (recommended for speed)

```bash
uv pip install tm-ai
```

### From Source

```bash
git clone https://github.com/mannuking/cvc
cd cvc
pip install -e .
```

### System Requirements

- **Python:** 3.11 or higher
- **OS:** Windows, macOS, Linux
- **RAM:** 512 MB minimum (more for local models)
- **Disk:** ~50 MB for CVC itself (storage grows with usage)

---

## Provider Setup

### Anthropic (Recommended)

```bash
cvc agent --provider anthropic --model claude-sonnet-4-20250514
```

**Models:** Claude Opus 4, Sonnet 4.5, Haiku 4.5  
**API Key:** Get from [console.anthropic.com](https://console.anthropic.com)  
**Best for:** High-quality coding, extended thinking, prompt caching

### OpenAI

```bash
cvc agent --provider openai --model gpt-4.1
```

**Models:** GPT-5.2, GPT-5.2-Codex, GPT-5-mini, GPT-4.1  
**API Key:** Get from [platform.openai.com](https://platform.openai.com)  
**Best for:** Structured outputs, fast responses

### Google

```bash
cvc agent --provider google --model gemini-2.5-pro
```

**Models:** Gemini 3.1 Pro, 3 Pro, 3 Flash  
**API Key:** Get from [aistudio.google.com](https://aistudio.google.com)  
**Best for:** Large context windows, configurable thinking budgets

### Ollama (Free, Offline)

```bash
# Install Ollama first
curl -fsSL https://ollama.com/install.sh | sh    # Linux/Mac
# Or download from ollama.com for Windows

# Pull a model
ollama pull qwen2.5-coder:7b

# Launch CVC
cvc agent --provider ollama --model qwen2.5-coder:7b
```

**Models:** Any Ollama model  
**Cost:** Free  
**Best for:** Offline development, privacy-sensitive projects

---

## The Three Modes

### Mode 1: Agent Mode (Default)

```bash
cvc
# or
cvc agent
```

A full AI coding assistant in your terminal. Includes:
- 17 built-in tools (file editing, terminal, web search, etc.)
- 31 slash commands (/commit, /branch, /restore, /search, etc.)
- 7 specialized sub-agents
- Arrow-key navigation for all menus
- Trust modes (strict/smart/yolo)
- Cost tracking per session

### Mode 2: Proxy Mode

```bash
cvc proxy
```

A transparent API server that sits between your AI tool and the LLM provider. The tool doesn't even know CVC is there — but every conversation is being version-controlled.

**Launch tools through the proxy:**
```bash
cvc launch claude     # Claude Code through CVC
cvc launch aider      # Aider through CVC
cvc launch codex      # Codex through CVC
```

### Mode 3: MCP Server Mode

```bash
cvc mcp
```

A Model Context Protocol server for IDE integration. Add to your AI IDE's MCP configuration:

**VS Code / Cursor / Windsurf:**
```json
{
  "servers": {
    "cvc": {
      "command": "cvc",
      "args": ["mcp"]
    }
  }
}
```

This gives your IDE's AI assistant access to 20 CVC tools — commit, branch, restore, search, and more — right inside the IDE.

---

## Essential Slash Commands

### Context Management

| Command | What It Does |
|---|---|
| `/commit "message"` | Save AI state with description |
| `/branch name` | Create new cognitive branch |
| `/restore hash` | Rewind to any commit |
| `/merge branch` | Merge a branch's insights |
| `/log` | View commit history |
| `/diff` | Compare two commits |
| `/compact` | Summarize & compress context |

### Search & Memory

| Command | What It Does |
|---|---|
| `/search "query"` | Semantic search across history |
| `/recall "query"` | Recall past conversations |
| `/memory` | View persistent memory |

### Session Control

| Command | What It Does |
|---|---|
| `/cost` | Show session token/cost stats |
| `/provider` | Switch LLM provider |
| `/model` | Switch model |
| `/clear` | Clear current context |
| `/export` | Export conversation |

### Tools & Agents

| Command | What It Does |
|---|---|
| `/tools` | List available tools |
| `/agents` | List available sub-agents |

### System

| Command | What It Does |
|---|---|
| `/help` | Show all commands |
| `/settings` | View/change settings |
| `/init` | Initialize CVC in current directory |
| `/status` | Show repository status |

---

## Core Workflows

### Workflow 1: The Safe Experimenter

```
# Working on a feature...
/commit "feature: stable state"

# Try something risky
/branch "risky-approach"
You: Refactor everything to use async/await
Sofia: [refactors...]

# If it works:
# Continue on this branch, commit, merge later

# If it fails:
/restore <stable-commit>
# Clean, instant rewind
```

### Workflow 2: The Knowledge Builder

```
# Working on Project A
You: Build a Redis caching layer
Sofia: [implements caching]
/commit "redis caching complete"

# Later, working on Project B
/search "redis caching layer"
# → Finds the commit from Project A
# → Surfaces the exact approach and code
```

### Workflow 3: The Cost-Conscious Developer

```
# End of day — save state
/commit "end of day checkpoint"

# Next morning — restore
cvc restore HEAD
# Full context restored at ~90% cost discount
# ~85% faster processing

/cost
# Total session: $0.12 instead of $1.50
```

### Workflow 4: The Multi-Tool Developer

```
# Morning: CLI agent
cvc agent
You: Design the database schema
/commit "schema design done"

# Afternoon: VS Code with Copilot + MCP
# CVC automatically restores the schema context
# Continue implementation in the IDE

# Evening: Quick fix with Aider
cvc launch aider
# Aider picks up the same CVC context
```

---

## Tips & Best Practices

### 1. Commit Early, Commit Often
Save a checkpoint whenever the AI reaches a correct state. It costs nothing and saves you from ever losing good work.

### 2. Branch Before Risky Operations
About to refactor? Branch first. About to try a new library? Branch first. The 2-second cost of branching is nothing compared to 30 minutes of lost context.

### 3. Use Semantic Search
Don't re-solve problems. Search your history first. CVC's semantic search finds relevant past sessions by meaning, not just keywords.

### 4. Let Context Autopilot Work
CVC monitors your context utilization and auto-compacts before the 60% degradation cliff. Trust the autopilot — it saves a checkpoint before compacting.

### 5. Leverage Sub-Agents
Don't use the main agent for everything. Ask Sofia to delegate:
- Security scans → Security agent
- UI work → UI agent
- Data analysis → Data agent
- Complex planning → Plan agent

### 6. Use /cost Regularly
Monitor your token usage and API costs per session. CVC tracks input tokens, output tokens, cache hits, and total cost.

---

## Troubleshooting Quick Reference

| Problem | Solution |
|---|---|
| `cvc` command not found | Ensure Python is in PATH. Try `python -m cvc` |
| API key error | Run `cvc` to re-enter setup wizard, or set env variable |
| Can't restore a commit | Check `cvc log` for valid commit hashes |
| MCP not connecting | Verify MCP config JSON syntax. Restart IDE. |
| Ollama not responding | Ensure Ollama is running: `ollama serve` |
| High token usage | Use `/compact` or branch to reduce context size |

---

## Next Steps

- **[Full Documentation](DOCUMENTATION.md)** — Every feature in detail
- **[FAQ](FAQ.md)** — 95 answers to common questions
- **[Feature Comparison](FEATURE_COMPARISON.md)** — How CVC compares to other tools
- **[Use Cases](USE_CASES.md)** — Real-world scenarios and success stories

---

<div align="center">

**Git for code. CVC for context.**

```bash
pip install tm-ai && cvc
```

[Website →](https://jaimeena.com/cvc) · [GitHub →](https://github.com/mannuking/cvc) · [PyPI →](https://pypi.org/project/tm-ai/)

</div>
