tm-ai 1.6.2
Time Machine for AI Agents — Cognitive Version Control for LLM context
Requires Python: >=3.11
Keywords: agents, ai, context, llm, merkle, version-control

<div align="center">

<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!--                            HEADER & LOGO                                -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/badge/%E2%8F%B3-CVC-8B0000?style=for-the-badge&labelColor=000000&logoColor=white">
  <source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/badge/%E2%8F%B3-CVC-8B0000?style=for-the-badge&labelColor=FFFFFF&logoColor=black">
  <img alt="CVC Logo" src="https://img.shields.io/badge/%E2%8F%B3-CVC-8B0000?style=for-the-badge&labelColor=000000&logoColor=white" width="200">
</picture>

# 🧠 **CVC** — Cognitive Version Control

### *Time Machine for AI Agents*

> Git for code. **CVC for context.**  
> Save. Branch. Rewind. Merge. — **Your AI agent just got an undo button.**

<br>

<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!--                              QUICK INSTALL                               -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->

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

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

<br>

<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!--                                 BADGES                                   -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->

[![PyPI Version](https://img.shields.io/pypi/v/tm-ai?style=for-the-badge&logo=pypi&logoColor=white&label=PyPI&color=8B0000&labelColor=2C0000)](https://pypi.org/project/tm-ai/)
[![License: MIT](https://img.shields.io/badge/License-MIT-CC3333.svg?style=for-the-badge&labelColor=2C0000)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/Python-3.11+-CC3333?style=for-the-badge&logo=python&logoColor=white&labelColor=2C0000)](https://www.python.org/)
[![Status](https://img.shields.io/badge/Status-Production_Ready-FF4444?style=for-the-badge&labelColor=2C0000)](https://github.com/mannuking/CVC)

[![Downloads](https://img.shields.io/pypi/dm/tm-ai?style=for-the-badge&logo=pypi&logoColor=white&label=Downloads&labelColor=2C0000&color=8B0000)](https://pypi.org/project/tm-ai/)
[![PRs Welcome](https://img.shields.io/badge/PRs-Welcome-55AA55?style=for-the-badge&logoColor=white&labelColor=1a5f1f)](http://makeapullrequest.com)
[![Code Style](https://img.shields.io/badge/Code_Style-Black-000000?style=for-the-badge&labelColor=2C0000)](https://github.com/psf/black)
[![Tests](https://img.shields.io/badge/Tests-Passing-55AA55?style=for-the-badge&labelColor=1a5f1f)](https://github.com/mannuking/CVC)

[![Website](https://img.shields.io/badge/🌐_Website-jaimeena.com%2Fcvc-8B0000?style=for-the-badge&labelColor=2C0000)](https://jaimeena.com/cvc)

<br>

<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!--                          SOCIAL & STATS                                  -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->

[![GitHub Stars](https://img.shields.io/github/stars/mannuking/CVC?style=social&label=Star)](https://github.com/mannuking/CVC/stargazers)
[![GitHub Forks](https://img.shields.io/github/forks/mannuking/CVC?style=social&label=Fork)](https://github.com/mannuking/CVC/network/members)
[![GitHub Watchers](https://img.shields.io/github/watchers/mannuking/CVC?style=social&label=Watch)](https://github.com/mannuking/CVC/watchers)
[![GitHub Contributors](https://img.shields.io/github/contributors/mannuking/CVC?style=social&label=Contributors)](https://github.com/mannuking/CVC/graphs/contributors)

<br>

<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!--                           NAVIGATION MENU                                -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->

<table>
<tr>
<td align="center"><a href="#-why-cvc"><b>Why CVC?</b></a></td>
<td align="center"><a href="#-features"><b>Features</b></a></td>
<td align="center"><a href="#-quick-start"><b>Quick Start</b></a></td>
<td align="center"><a href="#-documentation"><b>Docs</b></a></td>
<td align="center"><a href="#-architecture"><b>Architecture</b></a></td>
</tr>
<tr>
<td align="center"><a href="#-integrations"><b>Integrations</b></a></td>
<td align="center"><a href="#-community"><b>Community</b></a></td>
<td align="center"><a href="#-contributing"><b>Contribute</b></a></td>
<td align="center"><a href="#-roadmap"><b>Roadmap</b></a></td>
<td align="center"><a href="#-faq"><b>FAQ</b></a></td>
</tr>
<tr>
<td align="center" colspan="5"><a href="https://jaimeena.com/cvc"><b>🌐 jaimeena.com/cvc — Full Website, Docs & Installation</b></a></td>
</tr>
</table>

</div>

<br>
<br>

---

<br>

<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!--                            THE PROBLEM                                   -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->

<div align="center">

## 💥 **The Problem**

<br>

### Your AI coding agent is brilliant — for about 20 minutes.

Then it **forgets** what it already fixed, **contradicts** its own plan,  
and **loops** on the same error for eternity.

<br>

### ***Sound familiar?***

<br>

</div>

<table align="center">
<tr>
<td align="center" width="25%">
<h3>😵‍💫</h3>
<b>Context Rot</b><br>
<sub>After 60% context fill,<br>quality falls off a cliff</sub>
</td>
<td align="center" width="25%">
<h3>🔁</h3>
<b>Error Loops</b><br>
<sub>Same mistake,<br>different turn</sub>
</td>
<td align="center" width="25%">
<h3>🧠</h3>
<b>No Memory</b><br>
<sub>Can't remember<br>what it just did</sub>
</td>
<td align="center" width="25%">
<h3>💸</h3>
<b>Token Waste</b><br>
<sub>Re-processing the<br>same context</sub>
</td>
</tr>
</table>

<br>

<div align="center">

> ### **Bigger context windows don't fix this.**
> ### **They just give the problem more room to spread.**

<br>

## ✨ **The Solution: CVC**

Give AI agents what they've never had: **memory that actually works.**

</div>

<br>

---

<br>

<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!--                            WHY CVC?                                      -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->

## 🎯 **Why CVC?**

<div align="center">

**CVC** is Git for the AI's brain.  
Instead of versioning source code, it versions the agent's **entire cognitive state** — every thought, every decision, every conversation turn — as an immutable, cryptographic **Merkle DAG**.

</div>

<br>

<table>
<thead>
<tr>
<th align="center" width="20%">💾<br><b>Save</b></th>
<th align="center" width="20%">🌿<br><b>Branch</b></th>
<th align="center" width="20%">⏪<br><b>Rewind</b></th>
<th align="center" width="20%">🔀<br><b>Merge</b></th>
<th align="center" width="20%">🔍<br><b>Search</b></th>
</tr>
</thead>
<tbody>
<tr>
<td align="center">Checkpoint the agent's brain at any stable moment</td>
<td align="center">Explore risky ideas in isolation without polluting main context</td>
<td align="center">Stuck in a loop? Time-travel back instantly</td>
<td align="center">Merge <em>learnings</em> back — semantic, not syntactic</td>
<td align="center">Find when the agent solved similar problems before</td>
</tr>
</tbody>
</table>

<br>

### 📊 **Research-Backed Results**

<div align="center">

<table>
<tr>
<td align="center" width="25%">
<h2>58.1%</h2>
<sub>Context reduction<br>via branching<br><br><a href="https://arxiv.org/abs/2512.13914">ContextBranch paper →</a></sub>
</td>
<td align="center" width="25%">
<h2>3.5×</h2>
<sub>Success rate improvement<br>with rollback<br><br><a href="https://arxiv.org/abs/2508.00031">GCC paper →</a></sub>
</td>
<td align="center" width="25%">
<h2>~90%</h2>
<sub>Cost reduction through<br>prompt caching<br><br><a href="https://www.prompthub.us/blog/prompt-caching">Caching study →</a></sub>
</td>
<td align="center" width="25%">
<h2>~85%</h2>
<sub>Latency reduction<br>on restores<br><br><a href="https://anthropic.com/news/prompt-caching">Anthropic docs →</a></sub>
</td>
</tr>
</table>

</div>

<br>

---

<br>

<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!--                              FEATURES                                    -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->

## 🚀 **Features**

<div align="center">

<table>
<thead>
<tr>
<th align="center" width="33%">🤖 <b>Built-in Agent</b></th>
<th align="center" width="33%">🔌 <b>Universal Proxy</b></th>
<th align="center" width="34%">⏱️ <b>Time Machine</b></th>
</tr>
</thead>
<tbody>
<tr>
<td align="center">
Just type <code>cvc</code> for a powerful<br>AI coding assistant with<br><b>17 built-in tools</b> and<br><b>4-provider support</b>
</td>
<td align="center">
Run <b>any AI tool</b> through<br>CVC's time machine via<br><b>API proxy</b> or <b>MCP server</b><br>Zero configuration required
</td>
<td align="center">
<b>Auto-checkpoint</b> every N turns<br><b>Never lose context</b><br><b>Crash recovery</b> built-in<br>Time-travel to any point
</td>
</tr>
</tbody>
</table>

</div>

<br>

### 🆚 **How CVC Compares**

<div align="center">

<table>
<thead>
<tr>
<th width="20%"><b>FEATURE</b></th>
<th align="center" width="25%"><b>CLAUDE CODE / CODEX</b></th>
<th align="center" width="30%"><b>ANTIGRAVITY / CURSOR / VS CODE</b></th>
<th align="center" width="25%"><b>🔥 CVC AGENT</b></th>
</tr>
</thead>
<tbody>
<tr>
<td><b>Context Memory</b></td>
<td align="center">Linear (Lost on restart)</td>
<td align="center">Session-based / Linear</td>
<td align="center">✅ <b>Time-Travel (Project Isolated)</b></td>
</tr>
<tr>
<td><b>Branching</b></td>
<td align="center">No branching / rollback</td>
<td align="center">Not supported</td>
<td align="center">✅ <b>Full Branch Support</b></td>
</tr>
<tr>
<td><b>Undo Capability</b></td>
<td align="center">Single step (maybe)</td>
<td align="center">Single step / Ctrl+Z</td>
<td align="center">✅ <b>Instant Rewind (Any State)</b></td>
</tr>
<tr>
<td><b>Search History</b></td>
<td align="center">Current session only</td>
<td align="center">Current session only</td>
<td align="center">✅ <b>Global Semantic Search</b></td>
</tr>
<tr>
<td><b>Providers</b></td>
<td align="center">Single provider (usually)</td>
<td align="center">Vendor locked often</td>
<td align="center">✅ <b>Agnostic (4+ Providers)</b></td>
</tr>
<tr>
<td><b>Cost</b></td>
<td align="center">Full Re-prompting</td>
<td align="center">Full Re-prompting</td>
<td align="center">✅ <b>~90% Cheaper (Cached)</b></td>
</tr>
<tr>
<td><b>Local / Offline</b></td>
<td align="center">Cloud Dependent</td>
<td align="center">Cloud Dependent</td>
<td align="center">✅ <b>100% Local / Offline Capable</b></td>
</tr>
<tr>
<td><b>Context Merging</b></td>
<td align="center">Not available</td>
<td align="center">Not available</td>
<td align="center">✅ <b>Semantic Merge</b></td>
</tr>
<tr>
<td><b>Image Analysis</b></td>
<td align="center">Limited</td>
<td align="center">Limited</td>
<td align="center">✅ <b>Built-in Vision</b></td>
</tr>
<tr>
<td><b>Auto-checkpoint</b></td>
<td align="center">Not available</td>
<td align="center">Not available</td>
<td align="center">✅ <b>Configurable</b></td>
</tr>
<tr>
<td><b>Crash Recovery</b></td>
<td align="center">Session lost</td>
<td align="center">Session lost</td>
<td align="center">✅ <b>Full Restoration</b></td>
</tr>
</tbody>
</table>

</div>

<br>

---

<br>

<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!--                            QUICK START                                   -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->

## ⚡ **Quick Start**

### **Installation**

#### 🎯 **Recommended: One-Line Installer** (Installs Python if needed)

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

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

<details>
<summary><b>📦 Alternative: pip / uv</b></summary>

<br>

```bash
# pip (all providers)
pip install "tm-ai[all]"

# uv (faster, recommended)
uv tool 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
```

</details>

<br>

### **Usage**

```bash
# 🤖 Agent Mode - Just type 'cvc'
cvc

# 🔌 Proxy Mode - Zero-config launch
cvc launch claude          # Claude Code CLI
cvc launch aider           # Aider
cvc launch cursor          # Cursor IDE

# Or manual setup
cvc up                     # Setup + init + serve
```

<br>

### **Set API Keys**

```bash
# Environment variables
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export GOOGLE_API_KEY="AIza..."

# Or interactive setup
cvc setup
```

<br>

**That''s it! 🎉**

<br>

---

<br>

<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!--                           DOCUMENTATION                                  -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->

## 📖 **Documentation**

<div align="center">

<table>
<tr>
<td align="center" width="25%">
<h3>🤖</h3>
<b><a href="docs/CLI_AGENT_GUIDE.md">Agent CLI Guide</a></b><br>
<sub>Complete guide to the built-in agent</sub>
</td>
<td align="center" width="25%">
<h3>⌨️</h3>
<b><a href="docs/CLI_SLASH_COMMANDS.md">Slash Commands</a></b><br>
<sub>All slash commands reference</sub>
</td>
<td align="center" width="25%">
<h3>🔧</h3>
<b><a href="docs/CVC_TOOLS_REFERENCE.md">Tools Reference</a></b><br>
<sub>17 built-in tools documentation</sub>
</td>
<td align="center" width="25%">
<h3>🔌</h3>
<b><a href="docs/MCP_DOCUMENTATION.md">MCP Integration</a></b><br>
<sub>Model Context Protocol setup</sub>
</td>
</tr>
<tr>
<td align="center" width="25%">
<h3>🗺️</h3>
<b><a href="docs/CROSS_MODE_GUIDE.md">Cross-Mode Guide</a></b><br>
<sub>Agent + Proxy + MCP workflows</sub>
</td>
<td align="center" width="25%">
<h3>📁</h3>
<b><a href="docs/MULTI_WORKSPACE.md">Multi-Workspace</a></b><br>
<sub>Multiple project management</sub>
</td>
<td align="center" width="25%">
<h3>📚</h3>
<b><a href="docs/documentation.md">Full Docs</a></b><br>
<sub>Complete documentation</sub>
</td>
<td align="center" width="25%">
<h3>📝</h3>
<b><a href="docs/CHANGELOG.md">Changelog</a></b><br>
<sub>Version history</sub>
</td>
</tr>
<tr>
<td align="center" colspan="4">
<h3>🌐</h3>
<b><a href="https://jaimeena.com/cvc">Official Website</a></b><br>
<sub>Full docs, installation guides, examples & more at <a href="https://jaimeena.com/cvc">jaimeena.com/cvc</a></sub>
</td>
</tr>
</table>

</div>

<br>

---

<br>

<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!--                           INTEGRATIONS                                   -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->

## 🔌 **Integrations**

<div align="center">

### **Run ANY AI tool through CVC''s Time Machine**

</div>

<br>

<table>
<thead>
<tr>
<th width="25%">Tool</th>
<th width="40%">How to Connect</th>
<th width="35%">Command</th>
</tr>
</thead>
<tbody>
<tr><td><b>💎 Claude Code CLI</b></td><td><code>export ANTHROPIC_BASE_URL=http://127.0.0.1:8000</code></td><td><code>cvc launch claude</code></td></tr>
<tr><td><b>🛠️ Aider</b></td><td>Standard OpenAI-compatible endpoint</td><td><code>cvc launch aider</code></td></tr>
<tr><td><b>⌨️ Codex CLI</b></td><td><code>model_provider = "cvc"</code> in config</td><td><code>cvc launch codex</code></td></tr>
<tr><td><b>🖱️ Cursor</b></td><td>Settings → Override Base URL</td><td><code>cvc launch cursor</code></td></tr>
<tr><td><b>💎 VS Code + Copilot</b></td><td>BYOK or MCP integration</td><td><code>cvc launch code</code></td></tr>
<tr><td><b>🏄 Windsurf</b></td><td>MCP integration</td><td><code>cvc launch windsurf</code></td></tr>
<tr><td><b>🚀 Antigravity</b></td><td>MCP integration</td><td><code>cvc mcp</code></td></tr>
<tr><td><b>🔄 Continue.dev</b></td><td>Base URL → <code>http://127.0.0.1:8000/v1</code></td><td><code>cvc serve</code></td></tr>
<tr><td><b>🤖 Cline</b></td><td>Base URL → <code>http://127.0.0.1:8000/v1</code></td><td><code>cvc serve</code></td></tr>
<tr><td><b>🦜 LangChain</b></td><td>Use CVC''s function-calling tools</td><td><code>cvc serve</code></td></tr>
<tr><td><b>👥 CrewAI</b></td><td>Use CVC''s function-calling tools</td><td><code>cvc serve</code></td></tr>
<tr><td><b>🤝 AutoGen</b></td><td>Use CVC''s function-calling tools</td><td><code>cvc serve</code></td></tr>
<tr><td><b>🌐 Open WebUI</b></td><td>Standard OpenAI-compatible endpoint</td><td><code>cvc serve</code></td></tr>
</tbody>
</table>

<br>

> **🔑 Auth pass-through:** External tools can send their own API keys — CVC forwards them to the upstream provider.

<br>

Run `cvc connect` for interactive setup instructions.

<br>

---

<br>

<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!--                           ARCHITECTURE                                   -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->

## 🗝️ **Architecture**

<div align="center">

### **Three-Tiered Local Storage**

<br>

<table>
<tr>
<td align="center" width="33%">
<h3>🗄️ SQLite</h3>
<b>Commit graph</b><br>
<b>Branch pointers</b><br>
<b>Metadata</b><br>
<sub>Fast traversal, zero-config</sub>
</td>
<td align="center" width="33%">
<h3>📦 CAS Blobs</h3>
<b>Context snapshots</b><br>
<b>Zstandard compression</b><br>
<b>Content-addressable</b><br>
<sub>Deduplicated, efficient</sub>
</td>
<td align="center" width="34%">
<h3>🔍 Chroma</h3>
<b>Semantic embeddings</b><br>
<b>Vector search</b><br>
<b>Optional</b><br>
<sub>"Have I solved this before?"</sub>
</td>
</tr>
</table>

<br>

✨ **Everything stays in `.cvc/` inside your project**  
🔒 **No cloud • No telemetry • Your agent''s thoughts are yours**

</div>

<br>

### 📦 **Project Structure**

```
cvc/
├── agent/          # Built-in AI coding agent
│   ├── chat.py     # REPL loop, slash commands
│   ├── llm.py      # Unified LLM client (4 providers)
│   ├── tools.py    # 17 tool definitions
│   └── executor.py # Tool execution engine
├── adapters/       # Provider-specific formatting
│   ├── anthropic.py # Prompt caching support
│   ├── openai.py
│   ├── google.py
│   └── ollama.py
├── core/           # Data layer
│   ├── models.py   # Merkle DAG, Pydantic schemas
│   └── database.py # SQLite + CAS + Chroma
├── operations/     # CVC engine
│   ├── engine.py   # Commit, branch, merge, restore
│   └── state_machine.py # LangGraph routing
└── vcs/            # Git bridge
    └── bridge.py   # Shadow branches, Git notes, hooks
```

<br>

---

<br>

<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!--                              PROVIDERS                                   -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->

## 🤖 **Supported Providers**

<table>
<thead>
<tr>
<th width="15%">Provider</th>
<th width="30%">Default Model</th>
<th width="35%">Alternatives</th>
<th width="20%">Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td><b>🟣 Anthropic</b></td>
<td><code>claude-opus-4-6</code></td>
<td><code>claude-opus-4-5</code>, <code>claude-sonnet-4-5</code>, <code>claude-haiku-4-5</code></td>
<td>Prompt caching</td>
</tr>
<tr>
<td><b>🟢 OpenAI</b></td>
<td><code>gpt-5.2</code></td>
<td><code>gpt-5.2-codex</code>, <code>gpt-5-mini</code>, <code>gpt-4.1</code></td>
<td>Auto prefix caching</td>
</tr>
<tr>
<td><b>🔵 Google</b></td>
<td><code>gemini-3-pro-preview</code></td>
<td><code>gemini-3-flash-preview</code>, <code>gemini-2.5-pro</code>, <code>gemini-2.5-flash</code></td>
<td>Multimodal + reasoning</td>
</tr>
<tr>
<td><b>⚪ Ollama</b></td>
<td><code>qwen2.5-coder:7b</code></td>
<td><code>qwen3-coder:30b</code>, <code>devstral:24b</code>, <code>deepseek-r1:8b</code></td>
<td>100% local, no API key</td>
</tr>
</tbody>
</table>

<br>

---

<br>

<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!--                              COMMUNITY                                   -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->

## 💬 **Community**

<div align="center">

### **Join thousands of developers using CVC**

<br>

<table>
<tr>
<td align="center" width="25%">
<h3>🌐</h3>
<b>Website</b><br>
<sub><a href="https://jaimeena.com/cvc">jaimeena.com/cvc →</a></sub>
</td>
<td align="center" width="25%">
<h3>🛠</h3>
<b>Issues</b><br>
<sub><a href="https://github.com/mannuking/CVC/issues">Report bugs →</a></sub>
</td>
<td align="center" width="25%">
<h3>💡</h3>
<b>Discussions</b><br>
<sub><a href="https://github.com/mannuking/CVC/discussions">Share ideas →</a></sub>
</td>
<td align="center" width="25%">
<h3>𝕏</h3>
<b>Twitter</b><br>
<sub><a href="https://twitter.com/cvc_ai">Follow updates →</a></sub>
</td>
</tr>
</table>

</div>

<br>

---

<br>

<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!--                            CONTRIBUTING                                  -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->

## 🤝 **Contributing**

<div align="center">

**This repo is public and open to collaboration.**

Whether you''re fixing a typo or building an entirely new provider adapter —  
**contributions are welcome.**

<br>

**Fork** → **Branch** → **Commit** → **Push** → **PR**

</div>

<br>

### 🎯 **Areas Where Help Is Needed**

<table>
<thead>
<tr>
<th width="60%">Area</th>
<th width="40%" align="center">Difficulty</th>
</tr>
</thead>
<tbody>
<tr><td>🔌 Additional Provider Adapters (Mistral, Cohere)</td><td align="center">🟡 Medium</td></tr>
<tr><td>🧪 Tests & edge cases</td><td align="center">🟢 Easy–Medium</td></tr>
<tr><td>🖥️ VS Code Extension (graph visualization)</td><td align="center">🔴 Hard</td></tr>
<tr><td>📊 Metrics & observability dashboard</td><td align="center">🟡 Medium</td></tr>
<tr><td>🔒 Security audit</td><td align="center">🟠 Medium–Hard</td></tr>
<tr><td>📚 Documentation improvements</td><td align="center">🟢 Easy</td></tr>
<tr><td>🌐 Web UI for visualization</td><td align="center">🔴 Hard</td></tr>
<tr><td>🐳 Docker/Kubernetes deployment</td><td align="center">🟡 Medium</td></tr>
</tbody>
</table>

<br>

### 🛠️ **Dev Setup**

```bash
git clone https://github.com/mannuking/CVC.git
cd CVC
uv sync --extra dev
```

<br>

---

<br>

<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!--                              ROADMAP                                     -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->

## 🗺️ **Roadmap**

<table>
<thead>
<tr>
<th width="60%">Feature</th>
<th width="40%">Status</th>
</tr>
</thead>
<tbody>
<tr><td>🤖 Built-in Agent CLI</td><td>✅ <b>Shipped v1.5.4</b> — 17 tools, 4 providers</td></tr>
<tr><td>☁️ All 4 Provider Adapters</td><td>✅ <b>Shipped</b> — Anthropic, OpenAI, Google, Ollama</td></tr>
<tr><td>🔌 MCP Server</td><td>✅ <b>Shipped</b> — stdio + SSE transports</td></tr>
<tr><td>🚀 Zero-config Launch</td><td>✅ <b>Shipped</b> — <code>cvc launch</code> for all tools</td></tr>
<tr><td>🔗 Git Bridge</td><td>✅ <b>Shipped</b> — Shadow branches, hooks, notes</td></tr>
<tr><td>🎨 VS Code Extension</td><td>📜 <b>Q2 2026</b> — Visual commit graph, time-travel</td></tr>
<tr><td>🌐 Web UI</td><td>📜 <b>Q2 2026</b> — Browser visualization & management</td></tr>
<tr><td>👥 Multi-agent support</td><td>📜 <b>Q3 2026</b> — Shared DB with conflict resolution</td></tr>
<tr><td>☁️ Cloud sync</td><td>📜 <b>Q3 2026</b> — S3/MinIO for teams</td></tr>
<tr><td>📊 Metrics dashboard</td><td>📜 <b>Q4 2026</b> — Cache hits, context utilization, analytics</td></tr>
</tbody>
</table>

<br>

---

<br>

<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!--                                FAQ                                       -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->

## ❓ **FAQ**

<details>
<summary><b>What is CVC?</b></summary>

<br>

CVC (Cognitive Version Control) is Git for AI agent context. It versions the agent''s entire cognitive state as an immutable Merkle DAG, enabling time-travel, branching, and merging for AI conversations.

</details>

<details>
<summary><b>How is CVC different from Claude Code or Cursor?</b></summary>

<br>

CVC adds: ⏪ Time-travel • 🌿 Branching • 🔍 Semantic search • 🔀 Context merging • 💾 Auto-checkpoint • 🔄 Crash recovery • 🤖 Multi-provider support (4 vs 1)

</details>

<details>
<summary><b>Does CVC work with my existing AI tools?</b></summary>

<br>

**Yes!** CVC works in two modes:  
1. **Agent mode** — built-in AI assistant  
2. **Proxy mode** — transparent proxy for Claude Code, Aider, Cursor, VS Code, Windsurf, Continue, Cline, LangChain, CrewAI, AutoGen, and more

</details>

<details>
<summary><b>Is my data sent to the cloud?</b></summary>

<br>

**No.** Everything stays local in `.cvc/`. CVC has:  
🔒 No telemetry • 🔒 No cloud sync • 🔒 No data collection  
Your agent''s thoughts are **yours**.

</details>

<details>
<summary><b>How much does it cost?</b></summary>

<br>

CVC itself is **free and open source**. You only pay for LLM API calls (Anthropic/OpenAI/Google), but CVC makes them **~90% cheaper** via prompt caching and **58.1% less context** via branching.

</details>

<details>
<summary><b>Can I use CVC offline?</b></summary>

<br>

**Yes!** Use Ollama with local models like `qwen2.5-coder:7b`, `deepseek-r1:8b`, etc. 100% local, no API key needed.

</details>

<details>
<summary><b>What providers are supported?</b></summary>

<br>

- 🟣 **Anthropic** (Claude Opus 4.6, Sonnet 4.5, Haiku 4.5)  
- 🟢 **OpenAI** (GPT-5.2, GPT-5.2-Codex, GPT-5-mini)  
- 🔵 **Google** (Gemini 3 Pro, Gemini 2.5 Pro/Flash)  
- ⚪ **Ollama** (Qwen, DeepSeek, Devstral, etc.)

</details>

<details>
<summary><b>Is there a GUI?</b></summary>

<br>

Not yet! But coming soon:  
🎨 **VS Code extension** (Q2 2026)  
🌐 **Web UI** (Q2 2026)  

For now, use the beautiful terminal UI with Rich formatting.

</details>

<details>
<summary><b>Can I use CVC in production?</b></summary>

<br>

**Yes!** CVC is production-ready (v1.5.4) with crash-resistant local storage, used by solo developers, teams, and enterprises.

</details>

<br>

---

<br>

<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!--                              RESEARCH                                    -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->

## 📚 **Research**

<div align="center">

**CVC is grounded in published research**

</div>

<br>

<table>
<thead>
<tr>
<th width="35%">Paper</th>
<th width="65%">Key Finding</th>
</tr>
</thead>
<tbody>
<tr><td><a href="https://arxiv.org/abs/2512.13914"><b>ContextBranch</b></a></td><td>58.1% context reduction via branching</td></tr>
<tr><td><a href="https://arxiv.org/abs/2508.00031"><b>GCC</b></a></td><td>11.7% → 40.7% success with rollback (3.5× improvement)</td></tr>
<tr><td><a href="https://research.protocol.ai/publications/merkle-crdts-merkle-dags-meet-crdts/psaras2020.pdf"><b>Merkle-CRDTs</b></a></td><td>Structural deduplication for content-addressable DAGs</td></tr>
<tr><td><a href="https://www.prompthub.us/blog/prompt-caching-with-openai-anthropic-and-google-models"><b>Prompt Caching</b></a></td><td>Anthropic/OpenAI/Google token reuse patterns</td></tr>
</tbody>
</table>

<br>

---

<br>

<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!--                              LICENSE                                     -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->

## 📜 **License**

<div align="center">

**MIT License** — see [LICENSE](LICENSE)

This project is free and open source. Use it however you want.

</div>

<br>

---

<br>

<!-- ═══════════════════════════════════════════════════════════════════════ -->
<!--                              FOOTER                                      -->
<!-- ═══════════════════════════════════════════════════════════════════════ -->

<div align="center">

<br>

## ✨ **Because AI agents deserve an undo button** ✨

<br>

**Made with ❤️ by developers who got tired of AI agents forgetting what they just did.**

<br>

---

<br>

### **⭐ Star this repo if you believe in giving AI agents memory that actually works**

<br>

[![GitHub Stars](https://img.shields.io/github/stars/mannuking/CVC?style=social&label=Star)](https://github.com/mannuking/CVC/stargazers)
[![GitHub Forks](https://img.shields.io/github/forks/mannuking/CVC?style=social&label=Fork)](https://github.com/mannuking/CVC/network/members)
[![GitHub Watchers](https://img.shields.io/github/watchers/mannuking/CVC?style=social&label=Watch)](https://github.com/mannuking/CVC/watchers)

<br>

<table>
<tr>
<td align="center"><a href="https://jaimeena.com/cvc"><b>🌐 Website</b></a></td>
<td align="center"><a href="https://github.com/mannuking/CVC"><b>⭐ Star</b></a></td>
<td align="center"><a href="https://github.com/mannuking/CVC/issues"><b>🛠 Bug Report</b></a></td>
<td align="center"><a href="https://github.com/mannuking/CVC/issues"><b>💡 Feature Request</b></a></td>
<td align="center"><a href="https://github.com/mannuking/CVC/pulls"><b>🔀 Pull Request</b></a></td>
<td align="center"><a href="https://discord.gg/cvc"><b>💬 Discord</b></a></td>
</tr>
</table>

<br>

---

<br>

<sub>Built with Python 🐍 • FastAPI ⚡ • SQLite 🗄️ • LangGraph 🦜 • Rich 🎨</sub>

<br>

</div>