# CVC — Cognitive Version Control | Complete Documentation

> **Git saves your code. CVC saves your AI's brain.**
>
> Save. Branch. Rewind. Merge. — Your AI agent just got an undo button.

---

## Table of Contents

- [What is CVC?](#what-is-cvc)
- [The Problem We Solve](#the-problem-we-solve)
- [How CVC Works](#how-cvc-works)
- [Architecture Overview](#architecture-overview)
- [Three Modes of Operation](#three-modes-of-operation)
- [The CVC Agent — Sofia](#the-cvc-agent--sofia)
- [Sub-Agent System](#sub-agent-system)
- [The Cognitive Proxy](#the-cognitive-proxy)
- [MCP Server Integration](#mcp-server-integration)
- [Time Machine Features](#time-machine-features)
- [17 Built-in Tools](#17-built-in-tools)
- [34 CLI Commands](#34-cli-commands)
- [31 Slash Commands](#31-slash-commands)
- [20 MCP Tools](#20-mcp-tools)
- [Provider Adapters & Models](#provider-adapters--models)
- [14 IDE & Tool Integrations](#14-ide--tool-integrations)
- [Storage Architecture](#storage-architecture)
- [Cross-Mode Interoperability](#cross-mode-interoperability)
- [Multi-Workspace Support](#multi-workspace-support)
- [Git Integration & VCS Bridge](#git-integration--vcs-bridge)
- [Security & Audit Trail](#security--audit-trail)
- [Context Autopilot](#context-autopilot)
- [Persistent Memory System](#persistent-memory-system)
- [Project Scaffolding Wizard](#project-scaffolding-wizard)
- [Arrow-Key Interactive Menus](#arrow-key-interactive-menus)
- [Trust Mode System](#trust-mode-system)
- [Cost Tracking](#cost-tracking)
- [PageIndex — Tier 4 Document Intelligence](#pageindex--tier-4-document-intelligence)
- [Enterprise Features](#enterprise-features)
- [Installation Guide](#installation-guide)
- [Quick Start](#quick-start)
- [Configuration Reference](#configuration-reference)
- [Roadmap](#roadmap)
- [Version History](#version-history)

---

## What is CVC?

**CVC (Cognitive Version Control)** is a revolutionary open-source middleware that gives AI coding agents something they've never had before: **a memory that actually works**.

Think of it this way:

- **Git** saves versions of your **source code**.
- **GitHub** stores those code versions **in the cloud**.
- **CVC** does the same thing — but for the **AI's brain**, not the code.

Every thought, every decision, every conversation turn your AI agent makes is captured, versioned, and stored in an immutable, cryptographic data structure called a **Merkle DAG** — the same fundamental architecture that powers Git itself.

CVC is published on [PyPI](https://pypi.org/project/tm-ai/) as **`tm-ai`** (Time Machine for AI). Install it with one command:

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

**Website:** [jaimeena.com/cvc](https://jaimeena.com/cvc)  
**GitHub:** [github.com/mannuking/cvc](https://github.com/mannuking/cvc)  
**Current Version:** v1.8.51

---

## The Problem We Solve

### AI Agents Are Brilliant — For About 20 Minutes

Every developer who has used AI coding tools — Claude Code, Cursor, GitHub Copilot, Aider, Codex — has experienced the same frustrating pattern:

1. **Start a session.** The AI is sharp, focused, and helpful.
2. **20 minutes pass.** The AI starts forgetting what it already fixed.
3. **30 minutes pass.** The AI contradicts its own plan.
4. **45 minutes pass.** The AI loops on the same error, over and over.
5. **1 hour passes.** You give up and start a brand new session, losing everything.

This isn't a bug in the AI. It's a fundamental limitation called **context rot**.

### The Four Symptoms of Context Rot

| Symptom | What Happens | Impact |
|---|---|---|
| **Context Rot** | After ~60% context window utilization, LLM reasoning quality drops off a cliff | Quality degrades mid-session |
| **Error Loops** | The AI makes the same mistake repeatedly because it can't remember its own fixes | Wasted time and tokens |
| **No Memory** | Restart VS Code, crash, or close a tab — everything is gone | Hours of work lost |
| **Token Waste** | Every new session requires re-processing the same context from scratch | 10x higher API costs |

### Why Bigger Context Windows Don't Fix This

Many people think the solution is larger context windows — 128K, 200K, 1M tokens. **Research proves this is wrong.**

> *"After 60% context utilization, LLM reasoning quality degrades regardless of window size. A bigger context window just gives the problem more room to spread."*  
> — ContextBranch paper (2025)

A 200K context window doesn't make the AI smarter at 150K tokens. It just means the AI degrades at 120K instead of 60K. The problem scales with the window.

### The Real Solution: Cognitive State Management

What AI agents actually need isn't more context — it's **better context management**. The same lesson the software industry learned 30 years ago with version control for code.

Before Git, developers saved their code as `project_v2_final_FINAL.zip`. After Git, they had branches, commits, merges, and the ability to rewind to any point in history.

**CVC does the same thing for AI thinking.** Save a checkpoint. Branch to try something risky. Rewind if it doesn't work. Merge the insights that do. The AI never forgets again.

---

## How CVC Works

### The Git Analogy

CVC mirrors Git's conceptual model, but applies it to AI context instead of source code:

| What Developers Do with Git | What CVC Does for AI Agents |
|---|---|
| `git commit` — save a milestone | `cvc commit` — checkpoint the AI's brain state |
| `git branch` — try a risky idea in isolation | `cvc branch` — let the AI explore without polluting main context |
| `git checkout HEAD~5` — go back 5 versions | `cvc restore <hash>` — rewind the AI to any previous thought |
| `git merge` — bring changes back | `cvc merge` — semantically merge AI insights from branches |
| `git log` — see history | `cvc log` — see the full history of AI decisions |
| `git diff` — see what changed | `cvc diff` — see what changed in the AI's understanding |
| GitHub — cloud storage for code | CVC Cloud (coming 2026) — cloud sync for AI memory |

### The Five Core Powers

1. **Save (Commit)** — Checkpoint the agent's brain at any stable moment. Every conversation turn, every decision, every piece of reasoning is captured as an immutable snapshot.

2. **Branch** — Explore risky ideas in isolation without polluting the main context. Want the AI to try a different approach? Branch. If it works, merge. If it doesn't, discard.

3. **Rewind (Restore)** — Stuck in a loop? Time-travel back to any previous state instantly. The AI's brain is fully restored to exactly how it was at that checkpoint.

4. **Merge** — Combine insights from different branches semantically — not just concatenating text, but intelligently merging the AI's learnings.

5. **Search (Recall)** — Find when the AI solved similar problems before. Semantic search across all past conversations, across all projects.

### Research-Backed Results

| Metric | Result | Source |
|---|---|---|
| Context reduction via branching | **58.1%** | ContextBranch paper |
| Task success improvement with rollback | **3.5×** | GCC paper |
| Cost reduction via prompt caching | **~90%** | Anthropic/OpenAI caching docs |
| Latency reduction on restores | **~85%** | Anthropic prompt caching |

---

## Architecture Overview

### The Three-Tier Local Storage Engine

CVC uses a sophisticated three-tier storage engine, all running locally on your machine:

```
┌──────────────────────────────────────────────────────┐
│                    .cvc/ (Local)                      │
│                                                      │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────┐  │
│  │   Tier 1    │  │    Tier 2    │  │   Tier 3   │  │
│  │   SQLite    │  │  CAS Blobs   │  │   Chroma   │  │
│  │             │  │              │  │            │  │
│  │ Commit graph│  │ Zstd-        │  │ Vector     │  │
│  │ Branch ptrs │  │ compressed   │  │ embeddings │  │
│  │ Metadata    │  │ context      │  │ for        │  │
│  │             │  │ snapshots    │  │ semantic   │  │
│  │ (.git/      │  │ (immutable,  │  │ search     │  │
│  │  equivalent)│  │ content-     │  │            │  │
│  │             │  │ addressed)   │  │ (optional) │  │
│  └─────────────┘  └──────────────┘  └────────────┘  │
│                                                      │
│  ┌─────────────────────────────────────────────────┐ │
│  │                   Tier 4                         │ │
│  │              PageIndex (Optional)                │ │
│  │                                                  │ │
│  │  PDF & document intelligence with TOC-based      │ │
│  │  hierarchical tree search                        │ │
│  └─────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────┘
```

**Tier 1 — SQLite:** The commit graph, branch pointers, and metadata. Fast traversal, zero configuration. This is your `.git/` equivalent.

**Tier 2 — CAS Blobs (Content-Addressable Storage):** Every context snapshot is Zstandard-compressed and stored as an immutable, content-addressed blob — exactly like Git objects. Deduplicated and efficient. Each snapshot is identified by its own cryptographic hash.

**Tier 3 — Chroma (Vector DB, optional):** Semantic embeddings of every commit so you can search by meaning. "When did the agent solve a similar database migration issue?" — Chroma finds it instantly.

**Tier 4 — PageIndex (Optional):** Document intelligence layer that ingests PDFs and documents using real VectifyAI/PageIndex architecture. Table-of-Contents extraction, hierarchical tree nodes, LLM-guided tree search — no arbitrary chunking.

### The Merkle DAG

The data structure tying everything together is a **Merkle DAG** — the same cryptographic structure Git uses. Every commit is content-addressed. Every snapshot is immutable. Every commit points to its parent, forming an auditable chain of the AI's reasoning.

```
  commit-001 ──> commit-002 ──> commit-003 ──> commit-004 (HEAD)
                      │                             │
                      └──> commit-005 ──> commit-006 (experiment branch)
```

This means:
- **You cannot tamper with history.** Any modification to a past commit changes its hash, breaking the chain.
- **You have a complete audit trail.** "What was the AI thinking when it generated this code?" — answerable, forever.
- **Deduplication is automatic.** Identical context snapshots share the same blob.

### Middleware Architecture

CVC operates as **transparent middleware** between your AI tool and the LLM provider:

```
Your AI Tool              CVC Middleware              LLM Provider
┌──────────────┐   Every   ┌──────────────┐           ┌──────────┐
│ Claude Code  │──message─>│  CVC Proxy   │──────────>│ Anthropic│
│ Cursor       │           │  (:8000)     │           │ OpenAI   │
│ Copilot      │           │  ┌────────┐  │           │ Google   │
│ Aider        │           │  │Cognitive│  │           │ Ollama   │
│ Your Agent   │           │  │ Engine  │  │           └──────────┘
└──────────────┘           │  └────┬───┘  │
                           └───────┼──────┘
                                   │ saves every turn
                                   ▼
                           ┌──────────────┐
                           │  .cvc/       │
                           │  (Local DB)  │
                           └──────────────┘
```

The AI tool doesn't know CVC is there. The LLM provider doesn't know CVC is there. But every single conversation turn is being silently versioned. **Zero workflow disruption.**

---

## Three Modes of Operation

CVC provides three different interfaces to the same cognitive state, and all share the same `.cvc/` database:

### 1. Agent Mode — Built-in AI Coding Assistant

Just type `cvc` in your terminal. You get a full-featured AI coding assistant (named **Sofia**) with 17 built-in tools, 31 slash commands, and complete Time Machine capabilities.

```bash
cvc                     # Launch the agent
cvc agent               # Same thing (explicit)
cvc agent --provider openai --model gpt-5.2  # Specific provider
```

**Best for:** Terminal-focused developers who want an all-in-one AI assistant with version control built in.

### 2. Proxy Mode — Universal AI Tool Wrapper

CVC runs as a transparent FastAPI proxy server. Any AI tool that accepts a custom API endpoint can be wrapped with CVC's time machine — without changing anything in the tool itself.

```bash
cvc serve               # Start the proxy on localhost:8000
cvc launch claude       # Auto-launch Claude Code through CVC
cvc launch aider        # Auto-launch Aider through CVC
cvc launch cursor       # Auto-launch Cursor through CVC
```

**Best for:** Users who already love their AI tool (Claude Code, Cursor, Aider) and want to add time-travel capabilities without switching tools.

### 3. MCP Mode — IDE Integration via Model Context Protocol

CVC runs as an MCP (Model Context Protocol) server that integrates directly with AI IDEs like VS Code, Cursor, Windsurf, and Claude Desktop.

```bash
cvc mcp                 # Start MCP server (stdio transport)
```

**Best for:** VS Code users who want CVC capabilities directly inside GitHub Copilot, or any MCP-compatible IDE.

### Cross-Mode Interoperability

All three modes share the same `.cvc/` database. You can start a conversation in the CLI agent, continue it in VS Code via MCP, and pick it up again through the proxy — it's the same brain, three different interfaces:

```
Day 1: Design in CLI      →  commit d4e5f6a7 (mode: cli)
Day 2: Implement in VS Code →  commit g7h8i9j0 (mode: mcp)
Day 3: Test via Proxy      →  commit k1l2m3n4 (mode: proxy)
```

CVC detects mode transitions automatically and logs them:
```
🔄 Cross-mode restore: 10 messages from CLI → MCP (commit d4e5f6a7)
```

---

## The CVC Agent — Sofia

Sofia is CVC's built-in AI coding assistant. She's not just a chatbot — she's a full agentic coding companion with time-travel capabilities.

### Identity & Personality

Sofia is designed to match your energy. For code tasks, she's a hands-on coding agent that reads, writes, edits, and debugs directly. For non-code tasks, she responds naturally — witty, warm, and genuine.

### Workflow Orchestration

Sofia follows six core principles, all operating invisibly:

1. **Plan First** — For any task with 2+ steps, Sofia plans internally before acting. She formats plans as numbered steps that render in a styled panel with optional approval gates.

2. **Subagent Strategy** — Complex problems are decomposed into focused sub-tasks and delegated to specialized sub-agents.

3. **Self-Improvement Loop** — After any correction, Sofia silently updates `.cvc/lessons.md` with the pattern. These lessons persist across sessions and are auto-loaded at startup.

4. **Verification Before Done** — Sofia never declares a task complete without proving it works — running tests, checking for errors, diffing before/after.

5. **Demand Elegance** — For non-trivial changes, Sofia pauses and asks "is there a more elegant solution?" — no hacky workarounds.

6. **Autonomous Bug Fixing** — Given a bug report, Sofia just fixes it. She reads logs, errors, and failing tests, then resolves them autonomously.

### Auto-Context Intelligence

On startup, Sofia automatically:
- Indexes the file tree (up to 4 levels deep, 200 files)
- Reads 14+ project manifest formats (pyproject.toml, package.json, Cargo.toml, go.mod, etc.)
- Extracts files from error tracebacks (Python, Node.js, Rust)
- Loads persistent memory from past sessions
- Loads lessons learned from `.cvc/lessons.md`
- Loads Git status and recent commits
- Loads project instructions from `CVC.md`
- Respects `.cvcignore` for file exclusion

### Trust Mode System

Three permission modes for tool execution:

| Mode | Behavior | Best For |
|---|---|---|
| `strict` | Always prompt for risky operations | High-security environments |
| `smart` (default) | Auto-allow safe commands, prompt for risky ones | Balanced daily use |
| `yolo` | Trust everything | Move fast, break things |

**Smart Risk Detection:** 40+ safe commands auto-allowed (ls, cat, npm test, git status), 30+ risky patterns require approval (rm, sudo, git push --force, docker, eval).

### Interactive Permission Panel

When a permission prompt appears, you get rich options:
- `y` — Allow once
- `a` — Allow all this session
- `t` — Trust this command type always
- `n` — Deny
- `r` — Deny and suggest alternative

### Plan Detection & Display

Sofia auto-detects "Plan:" blocks and renders them as styled panels:
- `plan-approve` — Show plan + wait for approval before executing
- `plan-auto` — Show plan + auto-execute
- `plan-quiet` — Skip display, execute silently

### Diff Preview

After file edits, inline color-coded diffs appear:
- Uses unified diff format (+/- highlighting)
- Max 15 lines shown, summary for larger diffs
- Shows additions, deletions, and affected line count

### Turn Summary

End-of-turn action recap grouped by category:
- Files Read, Files Edited, Commands Run, Subagent Calls
- Token usage + cost breakdown per turn

---

## Sub-Agent System

CVC implements a Claude Code-inspired sub-agent architecture. The parent agent can spawn lightweight child agents with:
- Isolated context windows (no shared history)
- Restricted tool sets
- Configurable max turns and models
- Single-string result returned to parent

### 7 Built-in Sub-Agents

| Agent | Description | Tools | Max Turns |
|---|---|---|---|
| **Explore** | Fast read-only codebase exploration and search. Uses cheapest model tier. | Read-only | 10 |
| **Plan** | Analyze and produce implementation plans without modifying anything. | Read-only | 15 |
| **Security** | Vulnerability scanning (OWASP Top 10, CVEs, secrets), dependency auditing, hardening recommendations. | Research | 20 |
| **AI** | AI/ML engineering — LLM integration, RAG pipelines, model training, inference optimization. | Coding | 25 |
| **UI** | UI/UX design and frontend engineering — React, Vue, Tailwind, terminal TUI, accessibility. | Coding | 20 |
| **Data** | Data analytics, SQL, ETL pipelines, visualization, statistical analysis. | Coding | 20 |
| **Orchestrator** | Meta-agent that coordinates other specialized agents for complex multi-domain tasks. | Orchestration | 30 |

### Tool Tier System

| Tier | Tools Included | Purpose |
|---|---|---|
| `READ_ONLY_TOOLS` | read_file, grep, glob, list_dir, cvc_status, cvc_log, cvc_search, cvc_diff | Safe exploration |
| `RESEARCH_TOOLS` | Read-only + bash, web_search, document search | Research & web |
| `CODING_TOOLS` | Read + write_file, edit_file, patch_file, bash, web_search, cvc_commit, cvc_branch | Full development |
| `ORCHESTRATION_TOOLS` | Everything + agent (can call other sub-agents), cvc_restore, cvc_merge, document tools | Meta-coordination |

### Custom Agents

Define your own agents in `.cvc/agents/<name>/agent.md` with YAML frontmatter:

```markdown
---
name: Reviewer
description: Code review specialist
tools: [read_file, grep, glob, list_dir, bash]
max_turns: 15
---

You are an expert code reviewer. Your job is to review code changes for:
- Correctness and logic errors
- Performance implications
- Security vulnerabilities
- Code quality and maintainability
```

---

## The Cognitive Proxy

The CVC Proxy is a FastAPI server that acts as transparent middleware between your AI tools and LLM providers.

### Endpoints

- **OpenAI-compatible API:** `/v1/chat/completions` — Works with any tool that speaks the OpenAI API format
- **Anthropic-native API:** `/v1/messages` — Direct Anthropic Messages API passthrough
- **CVC Status:** `/cvc/status` — Check proxy health and CVC state

### How It Intercepts

1. Your AI tool sends a request to `localhost:8000`
2. CVC captures the conversation context
3. CVC forwards the request to the real LLM provider
4. CVC captures the response
5. CVC auto-commits at configurable intervals
6. Your AI tool receives the response as normal

The tool never knows CVC is there. The provider never knows CVC is there. But every conversation is versioned.

### Zero-Config Launch

CVC can auto-launch your favorite AI tool with the proxy pre-configured:

```bash
cvc launch claude       # Claude Code CLI — auto-configures ANTHROPIC_API_KEY + base URL
cvc launch aider        # Aider — auto-configures OpenAI-compatible endpoint
cvc launch codex        # Codex CLI — auto-configures API endpoint
cvc launch gemini       # Gemini CLI — MCP server auto-configured
cvc launch cursor       # Cursor IDE — auto-configures MCP
cvc launch windsurf     # Windsurf — auto-configures MCP
cvc launch vscode       # VS Code — auto-configures MCP
```

---

## MCP Server Integration

CVC's MCP (Model Context Protocol) server enables native integration with AI IDEs.

### What is MCP?

MCP is an open standard developed by Anthropic that allows AI assistants to securely interact with external tools and data sources. CVC exposes its full version control system through MCP, allowing AI assistants to call CVC operations naturally during conversations.

### 20 MCP Tools

**Core Operations:** cvc_status, cvc_commit, cvc_branch, cvc_merge, cvc_restore, cvc_log

**Context Management:** cvc_set_workspace, cvc_capture_context, cvc_get_context

**Power User:** cvc_recall, cvc_export, cvc_inject, cvc_diff, cvc_stats, cvc_compact, cvc_timeline

**Enterprise:** cvc_sync_push, cvc_sync_pull, cvc_sync_status, cvc_audit

### Supported IDEs

| IDE | Connection Method |
|---|---|
| VS Code + GitHub Copilot | MCP server |
| Cursor | MCP server (`mcp.json`) |
| Windsurf | MCP server (`mcp_config.json`) |
| Claude Desktop | MCP server |
| Continue.dev | MCP server (`config.yaml`) |
| Cline / Roo | MCP server (VS Code extension) |
| Gemini CLI | MCP server |
| Kiro CLI | MCP server |
| Firebase Studio | MCP server |

### Setup Example (VS Code)

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

Then just ask Copilot: *"Save a CVC checkpoint called 'auth complete'"* — Copilot calls `cvc_commit` automatically.

---

## Time Machine Features

### Auto-Checkpoint

CVC automatically saves a cognitive checkpoint every N assistant turns (default: every 2 turns in Agent mode, every 1 turn in Time Machine proxy mode). You never lose context.

```bash
# Configure auto-commit interval
CVC_AGENT_AUTO_COMMIT=3 cvc agent    # Commit every 3 turns
```

### Session Resume

When you restart CVC, it automatically restores the last session:
1. Loads HEAD commit from database
2. Falls back to persistent cache if no commits
3. Falls back to empty state as last resort

No manual `/restore` needed. You pick up exactly where you left off.

### Crash Recovery

Even if CVC crashes or is force-quit:
- Every message is saved to `.cvc/context_cache.json` (persistent cache)
- The cache survives crashes, force-quits, and power failures
- On next startup, the cache is automatically loaded

### Time-Travel

Restore the agent's full brain state to any previous checkpoint:

```bash
cvc restore abc1234     # Rewind to commit abc1234
# or in the agent:
/restore abc1234
```

The AI's entire context — every message, every decision, every piece of reasoning — is perfectly restored.

---

## 17 Built-in Tools

The CVC Agent comes with 17 tools that the AI can call autonomously:

### File Operations
| Tool | Description |
|---|---|
| `read_file` | Read files with optional line ranges |
| `write_file` | Create or overwrite files, auto-creates directories |
| `edit_file` | Find-and-replace with fuzzy matching fallback (60% similarity) |
| `patch_file` | Apply unified diff patches (multi-hunk support) |

### Shell Execution
| Tool | Description |
|---|---|
| `bash` | Execute shell commands (PowerShell on Windows, bash on Unix) |

### Search & Discovery
| Tool | Description |
|---|---|
| `glob` | Find files matching patterns |
| `grep` | Search text/regex across files |
| `list_dir` | List directory contents |

### Web
| Tool | Description |
|---|---|
| `web_search` | Search the web via DuckDuckGo (no API key required) |

### Time Machine
| Tool | Description |
|---|---|
| `cvc_status` | Show branch, HEAD, context size |
| `cvc_log` | View commit history |
| `cvc_commit` | Create a cognitive checkpoint |
| `cvc_branch` | Create and switch to a branch |
| `cvc_restore` | Time-travel to any previous state |
| `cvc_merge` | Semantic three-way merge |
| `cvc_search` | Search commit history by keyword |
| `cvc_diff` | Compare conversation states |

---

## 34 CLI Commands

### Tier 0 — Entry Points
| Command | Description |
|---|---|
| `cvc` | Launch agent (setup wizard on first run) |
| `cvc up` | One-command start: setup + init + serve |
| `cvc agent` | Interactive AI coding agent with Time Machine |
| `cvc launch <tool>` | Zero-config auto-launch any AI tool through CVC |
| `cvc setup` | Interactive setup wizard |

### Tier 1 — Core Version Control
| Command | Description |
|---|---|
| `cvc init` | Initialize `.cvc/` in current project |
| `cvc status` | Show branch, HEAD, context size |
| `cvc log` | View commit history |
| `cvc commit -m "..."` | Create a cognitive checkpoint |
| `cvc branch <name>` | Create and switch to exploration branch |
| `cvc merge <source>` | Semantic three-way merge |
| `cvc restore <hash>` | Time-travel to any previous state |

### Tier 1.5 — Infrastructure
| Command | Description |
|---|---|
| `cvc serve` | Start the Cognitive Proxy server |
| `cvc mcp` | Start MCP server |
| `cvc connect [tool]` | Interactive connection wizard for 14 tools |
| `cvc doctor` | Health check for entire CVC environment |

### Tier 2 — Power User
| Command | Description |
|---|---|
| `cvc recall "query"` | Natural-language search across all conversations |
| `cvc context --show` | Display stored conversation content |
| `cvc export --markdown` | Export conversation as shareable Markdown |
| `cvc inject <project>` | Cross-project context transfer |
| `cvc diff <hash1> [hash2]` | Knowledge diff between commits |
| `cvc stats` | Analytics dashboard |
| `cvc compact --smart` | AI-powered context compression |
| `cvc timeline` | ASCII timeline visualization |
| `cvc sessions` | View proxy session history |

### Tier 2.5 — VCS Bridge
| Command | Description |
|---|---|
| `cvc install-hooks` | Install Git hooks for CVC ↔ Git sync |
| `cvc capture-snapshot` | Capture CVC state linked to Git commit |
| `cvc restore-for-checkout` | Restore CVC state on Git checkout |

### Tier 3 — Enterprise
| Command | Description |
|---|---|
| `cvc sync push <path>` | Push cognitive commits to remote |
| `cvc sync pull <path>` | Pull cognitive commits from remote |
| `cvc sync status` | Show sync remote status |
| `cvc sync remote <path>` | Register a remote repository |
| `cvc audit` | Security audit trail with compliance scoring |

---

## 31 Slash Commands

Available inside the CVC Agent interactive session:

| Command | Description |
|---|---|
| `/help` | Show all commands |
| `/status` | CVC status (branch, HEAD, provider, model) |
| `/log` | Commit history |
| `/commit <msg>` | Manual checkpoint |
| `/branch <name>` | Create and switch branch |
| `/checkout <name>` | Switch to existing branch |
| `/branches` | List all branches |
| `/merge <source>` | Merge branch |
| `/restore <hash>` | Time-travel |
| `/search <query>` | Search commit history |
| `/files [pattern]` | List workspace files |
| `/summary` | Codebase structure summary |
| `/diff [file]` | Show diffs |
| `/continue` | Continue AI response |
| `/model [name]` | Switch model interactively |
| `/provider` | Switch provider |
| `/undo` | Undo last file change |
| `/web <query>` | Web search |
| `/git` | Git status + subcommands |
| `/cost` | Session cost summary |
| `/analytics` | Detailed usage analytics |
| `/image <path>` | Attach and analyze image |
| `/paste` | Attach clipboard image |
| `/memory` | View persistent memory |
| `/serve` | Start proxy in new terminal |
| `/init` | Initialize CVC |
| `/compact` | Compress conversation |
| `/clear` | Clear conversation |
| `/trust` | Toggle trust mode |
| `/plan` | Toggle plan mode |
| `/think` | Toggle thinking level |
| `/fast` | Use fast model for current turn |
| `/agents` | List available sub-agents |
| `/exit` / `/quit` / `/q` | Exit agent |

---

## 20 MCP Tools

Exposed via Model Context Protocol for IDE integration:

### Core: `cvc_status`, `cvc_commit`, `cvc_branch`, `cvc_merge`, `cvc_restore`, `cvc_log`
### Context: `cvc_set_workspace`, `cvc_capture_context`, `cvc_get_context`
### Power: `cvc_recall`, `cvc_export`, `cvc_inject`, `cvc_diff`, `cvc_stats`, `cvc_compact`, `cvc_timeline`
### Enterprise: `cvc_sync_push`, `cvc_sync_pull`, `cvc_sync_status`, `cvc_audit`

---

## Provider Adapters & Models

CVC is **provider-agnostic**. Switch providers without losing your AI's memory.

### 4 Provider Adapters

| Provider | Authentication | Special Features |
|---|---|---|
| **Anthropic** | API key | Prompt caching, extended thinking |
| **OpenAI** | API key | Structured outputs |
| **Google** | API key | Configurable thinking levels (LOW/MEDIUM/HIGH) |
| **Ollama** | None (local) | 100% offline, free, private |

### 16 Supported Models

| Provider | Model | Tier | Cost |
|---|---|---|---|
| Anthropic | claude-opus-4-6 | Frontier | $15/$75 per MTok |
| Anthropic | claude-opus-4-5 | Frontier | $15/$75 per MTok |
| Anthropic | claude-sonnet-4-5 | Standard | $3/$15 per MTok |
| Anthropic | claude-haiku-4-5 | Budget | $0.80/$4 per MTok |
| OpenAI | gpt-5.2 | Frontier | Provider pricing |
| OpenAI | gpt-5.2-codex | Frontier | Provider pricing |
| OpenAI | gpt-5-mini | Mid-tier | Provider pricing |
| OpenAI | gpt-4.1 | Mid-tier | Provider pricing |
| Google | gemini-3.1-pro-preview | Premium | Provider pricing |
| Google | gemini-3-pro-preview | Premium | Provider pricing |
| Google | gemini-3-flash-preview | Standard | Provider pricing |
| Ollama | qwen2.5-coder:7b | Local (~4 GB) | **Free** |
| Ollama | qwen3-coder:30b | Local (~18 GB) | **Free** |
| Ollama | devstral:24b | Local (~14 GB) | **Free** |
| Ollama | deepseek-r1:8b | Local (~5 GB) | **Free** |

---

## 14 IDE & Tool Integrations

CVC connects to virtually every AI coding tool on the market:

| # | Tool | Connection Method |
|---|---|---|
| 1 | VS Code | MCP server (GitHub Copilot) |
| 2 | Antigravity | MCP server |
| 3 | Cursor | MCP server |
| 4 | Windsurf | MCP server |
| 5 | Continue.dev | MCP server |
| 6 | Cline / Roo | MCP server |
| 7 | GitHub Copilot (BYOK) | Cognitive Proxy |
| 8 | Claude Code CLI | Cognitive Proxy |
| 9 | Gemini CLI | MCP server |
| 10 | Kiro CLI | MCP server |
| 11 | Aider | Cognitive Proxy |
| 12 | Open WebUI | Cognitive Proxy |
| 13 | Firebase Studio | MCP server |
| 14 | Codex CLI | Cognitive Proxy |

---

## Storage Architecture

### Directory Structure

```
.cvc/
├── cvc.db              # SQLite: commit graph, branches, metadata
├── objects/            # Zstandard-compressed context snapshots (CAS blobs)
├── context_cache.json  # Persistent cache (uncommitted work, crash recovery)
├── chroma/             # Optional vector embeddings for semantic search
├── pageindex/          # Optional document indices (Tier 4)
├── lessons.md          # Agent self-improvement patterns
├── memory.md           # Cross-session persistent memory
├── settings.toml       # Trust mode, plan display preferences
└── agents/             # Custom agent definitions
    └── <name>/
        └── agent.md
```

### Compression & Efficiency

- **Zstandard compression** for context snapshots (high compression ratio, fast decompression)
- **Anchor commits** (full snapshots) every N commits; intermediate commits are delta-compressed
- **Content-addressable storage** ensures deduplication — identical contexts share blobs
- **Prompt caching integration** reduces LLM costs by ~90% on restores

---

## Cross-Mode Interoperability

All three modes (Agent, Proxy, MCP) share the same `.cvc/` database. Start in one, continue in another:

- **Same commits** — All sessions stored in the same Merkle DAG
- **Same branches** — Work across modes seamlessly
- **Same context** — Conversations persist regardless of which mode created them
- **Mode tracking** — Every commit records its origin (cli/proxy/mcp)
- **Auto-detection** — CVC detects and logs mode transitions

---

## Multi-Workspace Support

Each project gets its own `.cvc/` folder. CVC auto-detects workspaces by looking for:
1. `.cvc/` directory (existing CVC project)
2. `.git/` directory (Git repository)
3. `pyproject.toml` (Python project)
4. `package.json` (Node.js project)
5. Other project markers

For multi-workspace scenarios, use `cvc_set_workspace` to switch explicitly.

---

## Git Integration & VCS Bridge

CVC bridges with Git so your cognitive state and code state stay synchronized:

- **Git hooks** (`post-commit`, `post-checkout`) — automatically capture/restore CVC state on Git operations
- **Shadow branches** — CVC branches mirror Git branches
- **Git notes** — link CVC commits to Git commits
- **`cvc install-hooks`** — one-command hook installation

---

## Security & Audit Trail

### Local-First Privacy

- **Everything stays local.** No cloud, no telemetry, no data sent anywhere.
- **Zero network calls** (except to the LLM provider you chose).
- **Works fully offline** with Ollama + local models.
- **Your AI's private reasoning stays private.**

### Enterprise Audit

`cvc audit` provides a compliance-ready security dashboard:
- Event filtering by type, risk level, and date range
- Compliance scoring (0–100%)
- Risk levels: Low, Medium, High, Critical
- Export to JSON or CSV for regulatory compliance

---

## Context Autopilot

CVC automatically manages context utilization:

| Threshold | Action |
|---|---|
| **40%** | Progressive thinning — remove less important early context |
| **60%** | Smart compaction — AI-powered summarization of older context |
| **80%** | Aggressive action — major compaction with CVC checkpoint saved first |

A CVC checkpoint is always saved before any compaction, so you can always rewind.

---

## Persistent Memory System

- Cross-session memory stored in `~/.cvc/memory.md` + `memory_index.json`
- Automatically summarizes each session: topics, workspace, model, cost
- Workspace-aware recall — prioritizes memories from the same project
- Injected into system prompt for continuity
- Up to 50 memory entries across sessions

---

## Project Scaffolding Wizard

CVC detects empty workspaces and offers guided project creation:

1. **Project type selection** — Web App, API/Backend, CLI Tool, Library, AI Agent, Mobile, Desktop, Other
2. **Tech stack picker** — Dynamic options per project type (e.g., Mobile → React Native / Flutter / Kotlin / Swift)
3. **Confirmation + scaffold** — Generates a structured prompt that the LLM executes using official CLI tools

All selection uses arrow-key navigation — zero typing required.

---

## Arrow-Key Interactive Menus

Every interactive prompt in CVC uses smooth arrow-key navigation:

- Up/Down/j/k navigation
- Enter to select, Esc to cancel
- 1-9 quick jump shortcuts
- `▸` cursor indicator with CVC theme colors
- Works in all terminals
- **16 prompts converted** from typed input to arrow-key menus

No more typing numbers or letters. Just arrow and enter.

---

## Cost Tracking

- Per-turn and per-session cost calculation
- Cache-aware pricing (cache-read tokens at 10% of input cost)
- Supports pricing for all 16 models
- Real-time display via `/cost` slash command
- Analytics via `/analytics` for detailed breakdowns

---

## PageIndex — Tier 4 Document Intelligence

CVC integrates the [VectifyAI/PageIndex](https://github.com/VectifyAI/PageIndex) architecture for document understanding:

### Real Architecture (Not Arbitrary Chunking)

- **PDF Pipeline:** TOC detection → TOC extraction → transformation → page offset mapping → hierarchical tree → recursive splitting → LLM summary enrichment → document description
- **Markdown Pipeline:** Header-based tree construction from `#`/`##`/`###` structure
- **Plain Text Pipeline:** LLM-generated pseudo-TOC for documents without structure
- **LLM-Guided Tree Search:** Reads node summaries at each level, selects the most relevant branches, recurses to leaf nodes

### Page-Indexed Structure

Each node stores: `{title, node_id, start_index, end_index, summary, nodes[]}` — exact page references, not arbitrary character offsets.

---

## Enterprise Features

### Team Collaboration (Sync)

```bash
cvc sync push /path/to/remote    # Push cognitive commits to shared repo
cvc sync pull /path/to/remote    # Pull team's AI knowledge
cvc sync status                  # Check sync state
```

### Security Audit Trail

```bash
cvc audit                        # Full compliance dashboard
cvc audit --risk-level high      # Filter by risk
cvc audit --export-format json   # Export for compliance
```

### Cross-Project Context Transfer

```bash
cvc inject another-project       # Pull conversation from another project
```

---

## Installation Guide

### One-Line Installer (Recommended)

```bash
# macOS / Linux / WSL
curl -fsSL https://jaimeena.com/cvc/install.sh | bash

# Windows PowerShell
irm https://jaimeena.com/cvc/install.ps1 | iex
```

### Via pip / uv

```bash
pip install "tm-ai[all]"                # All providers
uv tool install "tm-ai[all]"           # uv (recommended, faster)
pip install "tm-ai[anthropic]"          # Claude only
pip install "tm-ai[openai]"             # GPT only
pip install "tm-ai[google]"             # Gemini only
```

### Requirements

- **Python 3.11+** (3.12 or 3.13 recommended)
- **Git** (optional, for VCS bridge features)
- API key from any supported provider (or Ollama for free local models)

---

## Quick Start

```bash
# Install
pip install tm-ai

# Launch (setup wizard runs on first use)
cvc

# That's it! You now have an AI assistant with a time machine.
```

Or wrap an existing tool:

```bash
cvc launch claude       # Claude Code with time travel
cvc launch cursor       # Cursor with time travel
cvc launch aider        # Aider with time travel
```

---

## Configuration Reference

### Environment Variables

| Variable | Description | Default |
|---|---|---|
| `ANTHROPIC_API_KEY` | Anthropic API key | — |
| `OPENAI_API_KEY` | OpenAI API key | — |
| `GOOGLE_API_KEY` | Google API key | — |
| `CVC_WORKSPACE` | Override workspace path | auto-detect |
| `CVC_AGENT_AUTO_COMMIT` | Auto-commit interval (turns) | 2 |
| `CVC_TIME_MACHINE_INTERVAL` | Time Machine commit interval | 1 |
| `CVC_AUTO_COMMIT_INTERVAL` | Proxy auto-commit interval | 3 |

### Settings (`.cvc/settings.toml`)

```toml
[trust]
mode = "smart"          # strict | smart | yolo

[plan]
display = "plan-approve"  # plan-approve | plan-auto | plan-quiet
```

---

## Roadmap

### Shipped (v1.0–v1.8)
- ✅ Three-tier storage engine (SQLite + CAS + Chroma)
- ✅ Full agent with 17 tools, 31 slash commands
- ✅ Proxy mode for wrapping any AI tool
- ✅ MCP server for IDE integration
- ✅ 14 IDE connection guides
- ✅ 4 provider adapters, 16 models
- ✅ Cross-mode interoperability
- ✅ Multi-workspace support
- ✅ Arrow-key interactive menus
- ✅ Trust mode system
- ✅ 7 specialized sub-agents
- ✅ Tier 4 PageIndex document intelligence
- ✅ Project scaffolding wizard
- ✅ Git VCS bridge
- ✅ Enterprise audit trail

### Coming Next
- 🔜 CVC Cloud — team sync, shared memory, cloud backup
- 🔜 Analytics dashboard — visual metrics, cost trends, productivity insights
- 🔜 Plugin system — third-party integrations
- 🔜 VS Code extension — native CVC sidebar panel
- 🔜 Web UI — browser-based CVC management

---

## Version History

CVC has evolved rapidly from v1.2.8 (initial MCP server) to v1.8.51:

| Version | Highlight |
|---|---|
| v1.8.3 | 5 specialized sub-agents (Security, AI, UI, Data, Orchestrator) |
| v1.8.0 | Arrow-key interactive menus + project scaffolding wizard |
| v1.7.9 | Complete UI/UX overhaul — trust modes, permission panels, narration |
| v1.7.4 | Invisible planning — Claude Code-style agent intelligence |
| v1.7.2 | Workflow orchestration — 6 engineering principles |
| v1.7.0 | Tier 4 PageIndex — real document intelligence |
| v1.4.4 | Cross-mode interoperability (CLI ↔ Proxy ↔ MCP) |
| v1.4.0 | Zero data loss — persistent cache + auto-restore |
| v1.3.0 | Multi-workspace support + workspace auto-detection |
| v1.2.8 | Initial MCP server (6 core tools) |

---

<div align="center">

**Git for code. CVC for context. Your AI agent just got an undo button.**

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

</div>
