CCHistory
Evidence-preserving history for AI coding assistants

English | 简体中文

---

CCHistory ingests, parses, and projects your AI coding assistant conversations into a unified, evidence-preserving model. It collects local session data from Codex, Claude Code, Cursor, AMP, Factory Droid, Antigravity and more, then organizes them by project identity — so you can search, review, and analyze everything you've asked across every tool.

Key Features

• Multi-platform ingestion — Collects conversations from multiple AI coding assistant platforms via local file parsing and app-local live probes where required
• Evidence-preserving — Raw evidence is retained and traceable; every UserTurn is derived, never authored directly
• Project-based linking — Turns are linked to projects via repo fingerprints, workspace paths, and manual overrides
• Full-text search — Search across all canonical turn text with project and source filters
• Token usage analytics — Track tokens across models, projects, sources, and time periods
• Export / Import / Merge — Portable bundles for backup, migration, and multi-host merging
• Data health monitoring — Drift and consistency metrics with source-level health matrix

Supported Platforms

Platform	Self-host v1 Tier	Source Location
Codex	Stable	~/.codex/sessions/
Claude Code	Stable	~/.claude/projects/
Cursor	Stable	Platform user-data + project history
AMP	Stable	~/.local/share/amp/threads/
Factory Droid	Stable	~/.factory/sessions/
Antigravity	Stable	Platform user-data User/ + ~/.gemini/antigravity/{conversations,brain}
OpenClaw	Experimental	~/.openclaw/agents/
OpenCode	Experimental	~/.local/share/opencode/{project,storage/session}
LobeChat	Experimental	~/.config/lobehub-storage/

Stable means real-world validated for the self-host v1 support bar. Experimental means the adapter is registered in code but is not yet validated enough for self-host v1 support claims.

Antigravity note: CCHistory uses two complementary paths for Antigravity. The running desktop app's local language-server trajectory API provides actual conversation content (user inputs, assistant replies, tool calls). Offline files (workspaceStorage, History, brain) are always scanned for project paths and workspace signals. If the desktop app is not running, only the offline path executes, which means no raw conversation content will be recovered — only project metadata and evidence artifacts.

Architecture

┌──────────────────────────────────────────────────────────────────────┐
│                         Local Source Files                            │
│  ~/.codex  ~/.claude  ~/.cursor  ~/.factory  ~/.local/share/amp ...  │
└──────────────┬───────────────────────────────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────────────────────────────┐
│                     Source Adapters (packages/source-adapters)        │
│  Platform-specific parsers: capture → extract → parse → atomize      │
│  Blobs → Records → Fragments → Atoms → Candidates                   │
└──────────────┬───────────────────────────────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────────────────────────────┐
│                     Storage (packages/storage)                       │
│  SQLite via Node.js built-in node:sqlite (DatabaseSync)              │
│  Ingestion, linking, projection, search index, lineage tracking      │
└──────────┬──────────────────────┬───────────────────┬────────────────┘
           │                      │                   │
           ▼                      ▼                   ▼
┌──────────────────┐  ┌───────────────────┐  ┌─────────────────────┐
│  CLI (apps/cli)  │  │  API (apps/api)   │  │   Web (apps/web)    │
│  Local operator  │  │  Fastify REST     │  │   Next.js 16        │
│  tool: sync,     │  │  server on :8040  │  │   React 19 on :8085 │
│  search, stats,  │  │  CORS, auth,      │  │   SWR, Tailwind,    │
│  export/import   │  │  probe, replay    │  │   Recharts           │
└──────────────────┘  └───────────────────┘  └─────────────────────┘

Quick Start

Prerequisites

• Node.js >= 22 (uses built-in node:sqlite; no external database needed)
• pnpm 10.x (enforced via packageManager field)

Install & Build

# Clone and install
git clone https://github.com/aaaAlexanderaaa/cchistory.git
cd cchistory
pnpm install

# Install web app dependencies (separate lockfile)
cd apps/web && pnpm install && cd ../..

# Build all packages
pnpm run build

Install the CLI globally

# Build and link the cchistory command globally
pnpm run cli:link

# Now you can use `cchistory` from anywhere
cchistory sync
cchistory ls projects
cchistory search "refactor"
cchistory stats

Or run without global install:

# Via pnpm script
pnpm cli -- sync
pnpm cli -- ls projects

# Or directly via node
node apps/cli/dist/index.js sync

Start the Web UI & API

# Start both services (API on :8040, Web on :8085)
pnpm services:start

# Open the dashboard
open http://localhost:8085

First sync

# Sync all auto-detected local sources
cchistory sync

# Check what was found
cchistory ls sources
cchistory ls projects
cchistory stats

To sync Antigravity with full turn coverage, start the Antigravity desktop app on the same machine before running cchistory sync.

Screenshots

All Turns — Turn Stream Browse every turn across all coding sessions with filters for project, link state, and value axis.	Turn Detail Panel Full user input, assistant replies, tool calls, token usage, and pipeline lineage.
Projects Project cards with committed/candidate counts, token usage, sessions, and workspace paths.	Inbox Triage unlinked and candidate turns. Link to projects, create new ones, or dismiss.
Sources Admin Configure sources, view sync status, add manual sources, override directories.	Data Health Drift timeline, consistency metrics, and per-source health diagnostics.

Documentation

For detailed guides, see the docs/guide/ directory:

• CLI Guide — All commands, flags, and output examples
• API Guide — REST endpoints, configuration, and request/response schemas
• Web UI Guide — Features, navigation, views, and configuration
• Source Notes — Technical notes for validated source storage layouts and ingestion paths
• Self-Host V1 Release Gate — Minimum release bar for a single-user self-hosted v1
• Roadmap — Current milestone-oriented development plan

Design documents are in docs/design/.

Project Structure

cchistory/
├── apps/
│   ├── api/                    # Fastify REST API server (:8040)
│   ├── cli/                    # Command-line tool (cchistory)
│   └── web/                    # Next.js 16 web frontend (:8085)
├── packages/
│   ├── domain/                 # Core domain contracts and types
│   ├── source-adapters/        # Platform-specific parsers
│   ├── storage/                # SQLite persistence and linking
│   ├── api-client/             # Shared API DTO contracts
│   └── presentation/           # DTO → UI type mapping
├── scripts/                    # Dev service lifecycle scripts
├── mock_data/                  # Sanitized fixture corpus
├── docs/
│   ├── guide/                  # User-facing guides (CLI, API, Web)
│   ├── design/                 # Internal design documents
│   └── screenshots/            # Web UI screenshots
└── LICENSE                     # MIT License

Development

# Build all non-web packages
pnpm run build

# Build web app
NODE_OPTIONS=--max-old-space-size=1536 pnpm --filter @cchistory/web build

# Run tests
pnpm --filter @cchistory/source-adapters test    # 27 tests
pnpm --filter @cchistory/storage test            # 59 tests
pnpm --filter @cchistory/presentation test       # 5 tests
pnpm --filter @cchistory/cli test                # 12 tests
pnpm --filter @cchistory/api test                # 10 tests

# Lint
cd apps/web && pnpm lint

# Dev services
pnpm services:start       # Start API + Web
pnpm services:stop        # Stop all
pnpm services:status      # Check status

License

MIT