cc-vault 0.1.0

Automatic Claude Code session sync

Prompt Vault

Automatic Claude Code session backup and search. Your conversations, synced and searchable.

Features

• Auto-Sync: Automatically uploads sessions after each claude command
• Manual Sync: Bulk sync recent sessions with pv sync
• Full-Text Search: Search across all your conversations
• Web Dashboard: Browse and view sessions from any device
• Multi-User: Each user's data is isolated with Row Level Security
• Raw File Storage: Complete session files stored in Supabase Storage

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Claude Shim    │────▶│   FastAPI       │────▶│   Supabase      │
│  (Auto-upload)  │     │   Backend       │     │   PostgreSQL    │
└─────────────────┘     └─────────────────┘     │   + Storage     │
                               ▲                └─────────────────┘
                               │
┌─────────────────┐            │
│   Next.js       │────────────┘
│   Frontend      │
└─────────────────┘

Quick Start

1. Install CLI

git clone https://github.com/rstar327/prompt-vault.git
cd prompt-vault
pip install -e .

2. Authenticate

pv auth

This opens your browser for GitHub login. Once approved, the CLI stores a refresh token locally.

3. Enable Auto-Sync

pv install

This installs a shim that intercepts claude commands and automatically uploads sessions when they complete.

4. Use Claude Normally

claude

Sessions are automatically synced after each conversation.

CLI Commands

Command	Description
pv auth	Authenticate with GitHub via device flow
pv sync	Manually sync recent sessions (last 7 days)
pv sync --days 30	Sync sessions from last 30 days
pv install	Install the claude shim for auto-sync
pv uninstall	Remove the claude shim
pv status	Show authentication and shim status

Web Dashboard

Visit your deployed frontend to:

• Browse all synced sessions
• Search across conversations
• View full message threads
• Filter by project

Project Structure

prompt-vault/
├── src/prompt_vault/       # Python CLI package
│   ├── cli.py              # CLI commands (pv)
│   ├── auth.py             # Device flow authentication
│   ├── sync.py             # Session parsing and upload
│   ├── shim.py             # Claude command interceptor
│   ├── install.py          # Shim installation
│   └── config.py           # Config management
├── backend/
│   ├── app.py              # FastAPI server
│   ├── storage.py          # Supabase Storage integration
│   ├── store.py            # Device flow token management
│   └── supabase_client.py  # Database operations
├── frontend/
│   ├── app/                # Next.js App Router
│   ├── components/         # React components
│   └── lib/                # API client
├── database/
│   ├── schema.sql          # Main database schema
│   └── add_storage_path.sql # Storage path migration
├── scripts/
│   ├── install.sh          # One-line installer
│   └── uninstall.sh        # Uninstaller
└── pyproject.toml          # Python package config

Deployment

Prerequisites

• Supabase account (free tier)
• Clerk account (free tier)
• Vercel account (free tier)
• Render account (free tier)

1. Supabase Setup

1. Create a new project
2. Run database/schema.sql in SQL Editor
3. Run database/add_storage_path.sql for storage support
4. Create a Storage bucket named sessions
5. Get your project URL and keys from Settings > API

2. Clerk Setup

1. Create a new application
2. Enable GitHub OAuth
3. Get your publishable key and secret key

3. Backend (Render)

Deploy as a Web Service with these environment variables:

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-service-role-key
CLERK_SECRET_KEY=sk_live_...
JWT_SECRET=your-random-secret-for-cli-tokens

4. Frontend (Vercel)

Deploy with these environment variables:

NEXT_PUBLIC_API_URL=https://your-backend.onrender.com
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_...
CLERK_SECRET_KEY=sk_live_...

How It Works

Device Flow Authentication

1. User runs pv auth
2. CLI requests a device code from backend
3. Browser opens to approval page
4. User logs in with GitHub via Clerk
5. CLI polls for approval, receives refresh token
6. Refresh token stored in ~/.config/prompt-vault/config.yaml

Auto-Sync (Shim)

1. pv install creates a shim script in ~/.local/bin/claude
2. Shim records session files before running real claude
3. After claude exits, shim detects new/modified sessions
4. Sessions are silently uploaded in background

Data Storage

• PostgreSQL: Session metadata and searchable messages
• Supabase Storage: Raw JSONL files for complete history

Configuration

CLI config is stored at ~/.config/prompt-vault/config.yaml:

api_base_url: https://your-backend.onrender.com
refresh_token: eyJ...
user_id: user_abc123

Claude Code Data Location

Sessions are read from:

• Windows: %LOCALAPPDATA%\claude\projects\
• Mac/Linux: ~/.claude/projects/

License

MIT