Skillget

ccvault

skill
Security Audit
Warn
Health Warn
  • License — License: MIT
  • No description — Repository has no description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 9 GitHub stars
Code Pass
  • Code scan — Scanned 5 files during light audit, no dangerous patterns found
Permissions Pass
  • Permissions — No dangerous permissions requested

No AI report is available for this listing yet.

README.md

ccvault

Archive and search your Claude Code conversation history.

Inspired by msgvault, ccvault provides offline search, analytics, and AI integration for Claude Code sessions stored in ~/.claude.

image

Features

  • Full-text search across all conversations with Gmail-like query syntax
  • Interactive TUI for browsing and analyzing sessions
  • DuckDB analytics for fast aggregate queries over Parquet exports
  • MCP server for AI assistant integration

Installation

Homebrew (macOS/Linux)

brew install 2389-research/tap/ccvault

Using go install

Requires Go 1.25 or later:

go install github.com/2389-research/ccvault/cmd/ccvault@latest

Make sure $GOPATH/bin (or $HOME/go/bin) is in your PATH.

Build from source

git clone https://github.com/2389-research/ccvault.git
cd ccvault
go build -o ccvault ./cmd/ccvault
sudo mv ccvault /usr/local/bin/

Verify installation

ccvault version

Quick Start

# Sync conversations from ~/.claude
ccvault sync

# Launch interactive TUI
ccvault tui

# Search conversations
ccvault search "debugging async"
ccvault search "project:myapp model:opus"

# View statistics
ccvault stats

Commands

Command Description
quickstart Interactive setup guide for new users
orient Database state summary for AI agents (use --json)
sync Sync conversations from Claude Code
tui Launch interactive terminal UI
search [query] Full-text search across conversations
stats Show archive statistics
list-projects List all indexed projects
list-sessions List sessions (optionally filtered by project)
show [session-id] Display a specific session
export [session-id] Export a session to markdown
build-cache Build Parquet analytics cache
mcp Start MCP server for AI integration
version Print the version number

Search Syntax

ccvault supports Gmail-like query syntax:

project:name     Filter by project path/name
model:opus       Filter by model (partial match)
tool:Bash        Sessions using specific tool
file:path        Filter by file path
before:date      Sessions before date (YYYY-MM-DD)
after:date       Sessions after date
has:error        Sessions with errors
has:subagent     Sessions with subagent usage
"exact phrase"   Exact phrase match

Examples:

ccvault search "debugging the API endpoint"
ccvault search "project:myapp after:2024-01-01"
ccvault search "tool:Edit model:opus"
ccvault search '"error handling" project:backend'

MCP Server

ccvault includes an MCP (Model Context Protocol) server for AI assistant integration.

ccvault mcp

Available tools:

  • search_conversations - Full-text search across conversations
  • get_session_summary - Quick overview of a session (metadata, stats, tools used)
  • get_turns - Paginated turns from a session
  • get_session - Full session in markdown format
  • list_sessions - List recent sessions
  • list_projects - List all indexed projects
  • get_stats - Archive statistics
  • get_analytics - Detailed usage analytics

Claude Desktop Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "ccvault": {
      "command": "ccvault",
      "args": ["mcp"]
    }
  }
}

Claude Code Skill

ccvault ships with a Claude Code skill that teaches AI agents how to effectively mine conversation history. It includes search strategy patterns, workflow prompts for session orientation and on-demand recall, and a full tool/query reference card.

See skills/ccvault/ for the full skill.

Configuration

ccvault uses sensible defaults but can be configured via environment variables:

Variable Default Description
CCVAULT_CLAUDE_HOME ~/.claude Claude Code data directory
CCVAULT_DATA_DIR ~/.ccvault ccvault data directory

Data Storage

  • SQLite database: ~/.ccvault/ccvault.db - Session data with FTS5 full-text search
  • Analytics cache: ~/.ccvault/analytics/sessions.parquet - Parquet export for DuckDB queries

Architecture

ccvault/
├── cmd/ccvault/     # CLI entry point
├── pkg/
│   ├── models/      # Data structures
│   └── parser/      # JSONL session parser
└── internal/
    ├── config/      # Configuration
    ├── db/          # SQLite layer with FTS5
    ├── sync/        # Incremental sync logic
    ├── search/      # Query parsing and execution
    ├── export/      # Markdown export
    ├── tui/         # Bubble Tea terminal UI
    ├── analytics/   # DuckDB/Parquet export
    └── mcp/         # MCP server

License

MIT

Reviews (0)

No results found