# CVC Update — April 6, 2026

## Version: 2.2.1

---

## Summary of Changes

This update is a major architectural simplification. The dual-process model (separate proxy + gateway) has been collapsed into a single unified server. Users no longer need to manage or understand a "proxy" at all.

---

## What Was Removed

- **`cvc serve`** — deprecated and hidden. This command started the old standalone proxy on port 19333. It is no longer needed. Redirects users to `cvc gateway start`.
- **Port 19333** — the old proxy port. Completely removed from all user-facing surfaces.
- **Separate proxy process** — the gateway no longer spawns a child proxy process on startup.

---

## What Was Added / Changed

### 1. Unified CVC Gateway (Port 17888)

The gateway is now the **single server** that handles everything:
- Dashboard UI (always was)
- LLM proxy interception (new)
- Workspace routing (new)
- Session tracking (new)
- Auto-commit / Time Machine (new)

**Start it with:**
```bash
cvc gateway start
```

The dashboard is at `http://127.0.0.1:17888`.

---

### 2. Workspace-Routed URLs

Each project gets a unique workspace ID when registered with the gateway. AI tools are pointed at a workspace-specific URL:

```
http://127.0.0.1:17888/ws/{workspace_id}/v1/messages     ← Claude Code / Anthropic
http://127.0.0.1:17888/ws/{workspace_id}/v1/chat/completions  ← OpenAI-compatible tools
```

This allows **multiple projects to share one running gateway** simultaneously — each with its own isolated context, branches, and commits.

---

### 3. `cvc launch` — Zero-Config Auto-Launch

The `cvc launch <tool>` command is the new primary way to connect any AI tool to CVC. It:

1. Auto-starts the gateway in the background (if not running)
2. Registers the current project directory as a workspace
3. Configures the tool's environment variables to route through CVC
4. Launches the tool

```bash
# In any project directory:
cvc launch claude        # Claude Code
cvc launch aider         # Aider
cvc launch codex         # OpenAI Codex CLI
cvc launch gemini        # Gemini CLI
cvc launch kiro          # Kiro CLI
cvc launch cursor        # Cursor IDE
cvc launch vscode        # VS Code / Copilot
cvc launch windsurf      # Windsurf
```

**No prior `cvc setup` required.** If no config exists, CVC automatically initialises in passthrough mode.

---

### 4. Passthrough Mode (New Provider)

Users who have a Claude Code subscription (or any AI tool with its own authentication) no longer need an Anthropic API key to use CVC.

**New provider option: `passthrough`**

- CVC captures all conversations and saves them to `.cvc/`
- The AI tool's own API key / subscription is forwarded as-is to Anthropic
- No CVC API key required
- All core CVC features work: branching, commits, restore, recall, diff, timeline, stats

**Setup (optional — auto-configured if skipped):**
```bash
cvc setup
# Select "Passthrough (recommended for Claude Code users)"
# Done — no API key needed
```

Or just skip setup entirely:
```bash
cvc launch claude   # auto-creates passthrough config
```

---

### 5. Supported Providers for CVC's Own Features

When users want CVC's internal AI features (`cvc agent`, semantic merge, etc.), they can use:

| Provider | Command | Notes |
|----------|---------|-------|
| Anthropic | `cvc setup --provider anthropic` | Uses `ANTHROPIC_API_KEY` |
| Google Gemini | `cvc setup --provider google` | Uses `GOOGLE_API_KEY` |
| GitHub Copilot | `cvc setup --provider github` | Browser device auth, uses `GITHUB_TOKEN` |
| OpenAI | `cvc setup --provider openai` | Uses `OPENAI_API_KEY` |
| Ollama | `cvc setup --provider ollama` | Local, no key needed |
| LM Studio | `cvc setup --provider lmstudio` | Local, no key needed |
| Passthrough | `cvc setup --provider passthrough` | No key, tool uses its own |

---

### 6. Streaming Fix (502 Error Resolved)

**Before:** Claude Code users were hitting `502 {"detail":"Upstream error: Expecting value: line 1 column 1 (char 0)"}` errors.

**Root cause:** Claude Code sends streaming requests (`"stream": true`) by default. The old proxy called `resp.json()` on a streaming SSE response, which fails because SSE is not JSON.

**Fix:** Both `/ws/{id}/v1/messages` and `/ws/{id}/v1/chat/completions` now fully support streaming:
- Anthropic messages endpoint streams SSE directly to the client while capturing text for CVC in the background
- OpenAI completions endpoint wraps the full adapter response as proper SSE chunks when the client requests streaming

---

## New Quick Start (Replace Old Docs)

### Fastest path (Claude Code users):

```bash
pip install tm-ai
cd /your/project
cvc launch claude
```

That's it. Three commands. CVC auto-configures everything.

---

### Step-by-step path:

```bash
# 1. Install
pip install tm-ai

# 2. (Optional) Configure a provider for CVC's own AI features
cvc setup
# → Pick "Passthrough" if you just want context capture
# → Pick "Google" / "Anthropic" / "GitHub" if you want cvc agent too

# 3. Start the gateway (keep this terminal open, or use --daemon)
cvc gateway start

# 4. In your project directory, launch your AI tool
cd /my/project
cvc launch claude      # or aider, codex, gemini, kiro, cursor, vscode, windsurf
```

---

### How to see your captured conversations:

```bash
cvc log                        # All commits (auto-checkpoints + manual)
cvc recall "what you remember" # Semantic search across all past sessions
cvc status                     # Current branch, HEAD hash
cvc timeline                   # ASCII timeline of all interactions
cvc stats                      # Token usage, costs, patterns
```

Data is stored in `.cvc/` inside each project:
- `.cvc/cvc.db` — SQLite: commit graph, branches, metadata
- `.cvc/objects/` — zstandard-compressed context blobs
- `.cvc/chroma/` — semantic vector embeddings

Dashboard (visual view): `http://127.0.0.1:17888`

---

## Command Reference Changes

| Old Command | New Command | Notes |
|-------------|-------------|-------|
| `cvc serve` | `cvc gateway start` | Old command still exists but shows deprecation warning |
| Manual `ANTHROPIC_BASE_URL=http://127.0.0.1:19333` | `cvc launch claude` | Fully automatic now |
| Required `cvc setup` before launch | Optional | Auto-initialises in passthrough mode |

### Commands that replace `cvc serve`:

```bash
cvc gateway start          # Start gateway (foreground with logs)
cvc gateway start --daemon # Background daemon (coming soon)
cvc up                     # One command: setup + init + gateway
cvc launch <tool>          # Auto-starts gateway + launches tool
```

---

## Version History Note

- `v2.1.x` — Last version with separate proxy on port 19333
- `v2.2.0` — Unified gateway, workspace routing, streaming fix, passthrough mode
- `v2.2.1` — Current release on PyPI (`pip install tm-ai`)

---

## PyPI Package

Package name: **`tm-ai`**  
Current version: **2.2.1**  
Install: `pip install tm-ai`  
PyPI: https://pypi.org/project/tm-ai/
