Skip to content

tznthou/ccRewind

BranchesTags

Repository files navigation

ccRewind

License: AGPL-3.0 TypeScript React Electron

English

Claude Code 對話回放與考古工具。輕量、只讀、離線優先的桌面應用程式，讓你回顧跟 Claude Code 的每一次協作對話。

ccRewind

ccRewind 應用程式預覽 ccRewind 品牌形象

三種佈景主題 × Context Budget 儀表板

一鍵切換三種視覺風格，搭配內建 Token 用量儀表板，對話考古也可以很有氛圍感。

📂 檔案室 Archive 🕐 時間線 Timeline 💻 終端回憶 Terminal
Archive 主題 — 暖色調檔案室風格，搭配 Context Budget 儀表板 Timeline 主題 — 冷色調時間線風格，搭配 Context Budget 儀表板 Terminal 主題 — 深色終端風格，搭配 Context Budget 儀表板

核心概念

ccRewind 讀取 ~/.claude/projects/ 下的 JSONL 對話紀錄，建立 SQLite + FTS5 索引，提供瀏覽、搜尋、匯出功能。

Session 摘要由結構化規則引擎產生（意圖提取 + 動作概要 + outcome 推斷），零 API 成本。標籤透過文字、路徑、工具模式三軌交叉推斷。未來規劃 BYOK（自備 API Key）模式，可以選擇用 LLM 產生更高品質的摘要。

所有操作都是唯讀的。ccRewind 絕不修改 ~/.claude/ 下的任何檔案，你的對話紀錄、記憶檔案、設定檔，一個位元組都不會動。

Claude Code 刪除 Session 後，ccRewind 會自動封存該筆對話。所有訊息、標籤、摘要都留在 SQLite 裡，不會隨 JSONL 檔案消失。

功能特色

功能 說明
對話瀏覽 user/assistant 氣泡介面，Markdown 渲染 + 程式碼語法高亮
三主題切換 檔案室（Archive）、時間線（Timeline）、終端回憶（Terminal），一鍵切換
Tool 摺疊 tool_use / tool_result 預設摺疊，點擊展開查看完整內容
Session 自動摘要 結構化摘要引擎：意圖提取（跳過 greeting）、動作概要（Edit×8, 5 files）、outcome 推斷（committed/tested/in-progress）、20+ 條多信號標籤
檔案反向索引 每個 session 操作了哪些檔案、什麼操作（read/edit/write），可點擊檔案追蹤跨 session 歷史
全文搜尋 FTS5 索引，分頁載入，結果按 Session 分組，支援「對話」與「標籤/檔案」兩種搜尋模式，可依日期範圍過濾（7天/30天/90天）、切換相關性或時間排序
搜尋上下文預覽 搜尋結果可展開顯示前後 2 則訊息，不用跳轉就能快速判斷相關性。結果顯示 Session 日期與 outcome 狀態 badge
資料保全 JSONL 被刪除時自動封存對話，不丟失任何歷史紀錄
Markdown 匯出 一鍵將 Session 匯出為 .md 檔案，含 Metadata 表格 + Tool 摺疊
Context Budget 視覺化 Token 用量追蹤：堆疊面積圖、圓餅圖、熱力條，一眼看出每個 Session 燒了多少 token、cache 命中率多高
Token Insights 自動解讀圖表：偵測 context spike 並歸因、評估 cache 效率、標記 output 熱點、分析成長趨勢，讓圖表不只好看還能看懂
Token 熱力指示 Assistant 訊息左側色碼條（綠=cache 命中佳、紅=高成本），Session 列表顯示 token 總量並可依 token 排序
統計儀表板 跨 session 分析：使用趨勢（雙軸面積圖）、效率趨勢（tokens/turn）、浪費偵測（高 token 低產出 session 一鍵跳轉）、專案健康度（outcome 堆疊條 + 趨勢箭頭）、工具/標籤分佈、工作模式熱力圖
跨 Session 考古 檔案歷史抽屜（點檔案看它在哪些 session 出現過）、相關 Session 推薦（Jaccard 相似度）、可展開 File Chips
更新通知 啟動時自動偵測 GitHub 新版本，一鍵開啟下載頁面
Active Time Session 時長優先顯示活動時間（排除 >5 分鐘閒置），括號附註掛鐘時間。儀表板平均時長同步使用 active time
Subagent 瀏覽 自動掃描 subagents/*.jsonl 並建立索引。有 subagent 的 Session 顯示可點擊 chips（agent type + 訊息數），點擊進入後以 breadcrumb 導覽回 parent session
儲存管理 檢視索引資料庫佔用（DB 大小、Session/Message 數、專案佔比視覺化 bar），以排除規則釋放空間——一鍵排除整個專案、依日期範圍排除，或從規則清單移除；所有刪除走統一雙重確認（checkbox + >50% 紅色警告 banner），IPC 層 apply-token handshake 防 renderer 繞過
精確 Token 統計 自動偵測同一 API response 被拆成多個 JSONL entries 的情況，透過 requestId 去重避免 token 重複計算（修正 ~2.3x 膨脹）
增量索引 首次啟動掃描所有 JSONL，後續僅處理新增/修改的檔案。Resumed session 自動 UUID 去重，不產生重複訊息
DB 自動遷移 schema 變更時自動升級，大型資料庫無痛升版
虛擬捲動 大量 Session 不卡頓（@tanstack/react-virtual）
無障礙 WCAG 2.1 AA 對比度、ARIA 標籤、鍵盤導覽、焦點管理

使用說明

  • 第一次使用 → docs/GETTING-STARTED.md（5 分鐘上手：安裝、索引、第一次瀏覽與搜尋）
  • 各功能詳細使用方式 → docs/USER-GUIDE.md（Session 摘要與標籤、搜尋、Context Budget、統計儀表板、跨 Session 考古、儲存管理）

系統架構

graph TB
    subgraph Main Process
        FS[檔案掃描器<br>~/.claude/projects/] --> JP[JSONL Parser]
        JP --> SM[摘要引擎<br>意圖+outcome+標籤]
        JP --> DB[(SQLite + FTS5<br>+ session_files<br>+ exclusion_rules)]
        SM --> DB
        DB --> IPC[IPC Handlers<br>sessions · search · stats · files<br>related · export · storage]
        EX[Markdown 匯出器] --> IPC
        AT[Apply-Token Handshake<br>one-time UUID · 60s TTL] --> IPC
    end

    subgraph Renderer Process
        SB[Sidebar<br>專案選擇 + Session 清單 + 搜尋]
        CV[ChatView<br>對話閱讀器 + Token Budget<br>+ File Chips + Related Sessions]
        DB_UI[Dashboard<br>使用/效率趨勢 · 專案健康度 · 浪費偵測<br>工具分佈 · 標籤分佈 · 工作模式熱力圖]
        FH[FileHistoryDrawer<br>跨 Session 檔案歷史時間軸]
        SP[StoragePage<br>總覽卡 · 專案佔用 bar<br>排除規則 · 統一 Confirm Dialog]
    end

    IPC <-->|invoke / handle| SB
    IPC <-->|invoke / handle| CV
    IPC <-->|invoke / handle| DB_UI
    IPC <-->|invoke / handle| FH
    IPC <-->|invoke / handle| SP
Loading

技術棧

技術 用途 備註
Electron 33 桌面應用框架 macOS hiddenInset title bar
React 19 UI 框架 函式元件 + hooks
TypeScript 5.7 型別安全 strict mode
better-sqlite3 11 SQLite binding 含 FTS5 全文搜尋
recharts 3 圖表庫 面積圖、圓餅圖、甜甜圈圖（Context Budget + Dashboard）
electron-vite 5 建構工具 main + preload + renderer 三路建構
Vitest 3 測試框架 294 個測試，透過 Electron 執行

下載安裝

從 Releases 頁下載對應平台的預編譯版：

  • macOS（arm64）：DMG 拖曳到 Applications，或 ZIP 解壓後直接執行
  • Windows（x64）：NSIS installer 或 ZIP

系統需求：macOS 11+ / Windows 10+

首次啟動警告

ccRewind 尚未取得 Apple Developer ID / Microsoft 程式碼簽章，首次執行時作業系統會顯示未簽章應用的警告，這是正常行為：

  • macOS：出現「無法驗證開發者」時，開啟「系統設定 → 隱私與安全性」，找到 ccRewind 並點擊「仍要打開」
  • Windows：SmartScreen 顯示「Windows 已保護您的電腦」時，點擊「其他資訊」→「仍要執行」

快速開始

環境需求

  • Node.js >= 20, < 23
  • pnpm >= 9

安裝與啟動

git clone https://github.com/tznthou/ccRewind.git
cd ccRewind
pnpm install
pnpm dev

建構發布

pnpm build
pnpm dist

其他指令

pnpm test        # 執行測試（透過 Electron 跑 Vitest）
pnpm typecheck   # TypeScript 型別檢查
pnpm lint        # ESLint 修正

專案結構

ccRewind/
├── src/
│   ├── main/                  # Electron main process
│   │   ├── index.ts           # 應用程式入口
│   │   ├── scanner.ts         # 專案 / Session 檔案掃描
│   │   ├── parser.ts          # JSONL 解析器
│   │   ├── database.ts        # SQLite + FTS5 管理（含 sessions_fts + session_files + 統計查詢 + Jaccard）
│   │   ├── indexer.ts         # 增量索引器
│   │   ├── summarizer.ts      # 結構化摘要引擎（意圖提取 + outcome 推斷 + 多信號標籤 + session_files）
│   │   ├── exporter.ts        # Markdown 匯出
│   │   ├── updater.ts         # GitHub Release 更新偵測
│   │   └── ipc-handlers.ts    # IPC 通訊處理
│   ├── preload/               # contextBridge 安全橋接
│   │   └── index.ts
│   ├── renderer/              # React 前端
│   │   ├── App.tsx            # 根元件
│   │   ├── components/
│   │   │   ├── Sidebar/       # 專案選擇 + Session 清單 + 搜尋
│   │   │   ├── ChatView/      # 對話閱讀器 + Token 熱力指示 + File Chips + Subagent 導覽 + 匯出
│   │   │   ├── Dashboard/     # 統計儀表板：使用/效率趨勢、專案健康度、浪費偵測、工具/標籤分佈、工作模式
│   │   │   ├── Archaeology/   # 跨 Session 考古：FileHistoryDrawer、RelatedSessionsPanel
│   │   │   ├── Storage/       # 儲存管理：總覽卡、專案佔用 bar、排除規則、統一 Confirm Dialog
│   │   │   ├── TokenBudget/   # Context Budget 面板：面積圖、圓餅圖、熱力條、Insights
│   │   │   ├── ThemeSwitcher/ # 三主題切換按鈕
│   │   │   └── UpdateBanner/  # 更新通知橫幅
│   │   ├── hooks/             # useSession, useSessions, useProjects
│   │   ├── utils/             # formatTokens, formatTime, formatDuration, pathDisplay, renderSnippet
│   │   └── context/           # AppContext + ThemeContext（主題持久化）
│   └── shared/
│       └── types.ts           # 主程序與渲染程序共用型別
├── tests/                     # Vitest 測試（294 個）
├── docs/                      # PRD / SPEC / PLAN
├── electron-builder.yml
└── package.json

隨想

為什麼做這個

跟 Claude Code 協作的對話散落在 ~/.claude/projects/ 底下，每個 Session 是一個 JSONL 檔案。想回頭看三天前的設計決策？你得記得是哪個 Session、手動 cat JSONL、在密密麻麻的 JSON 裡面找到那段對話。

現有的方案要嘛太重（RAG、向量搜尋），要嘛方向不對（記憶注入、Context 管理）。我只是想安靜地回顧過去的對話，像翻閱考古現場的筆記本。

所以 ccRewind 就是這個：一本有索引的考古筆記本。

Non-goals

ccRewind 刻意不做這些事：

  • 不做 Context Injection：不干預未來的對話，只回顧過去的
  • 不做雲端同步：所有資料來自本地 ~/.claude/，不上傳任何東西
  • 不修改任何檔案：純唯讀應用，連 ~/.claude/ 的 mtime 都不會動
  • 不做即時監控：不是 tail -f，是考古學
  • LLM 永遠是可選的：沒有 API Key 也能用所有核心功能，LLM 摘要是錦上添花

如果你需要的是「讓 Claude 記住之前說過什麼」，去看 claude-mem 之類的記憶系統。ccRewind 解決的是不同的問題：讓人類回顧與 AI 的協作歷史。

Roadmap

詳見 docs/ROADMAP.md。

Phase 狀態 主題
1 ✅ 完成 基礎建設：表拆分、資料保全、分頁、分組
2 ✅ 完成 Session 摘要（規則式）、搜尋上下文預覽、Scope 擴展
2.5 ✅ 完成 Context Budget 視覺化：token 用量追蹤、面積圖、圓餅圖、熱力條、排序
2.6 ✅ 完成 Token Insights Engine：自動解讀圖表（spike 偵測、cache 評估、熱點標記、趨勢分析）
3 ✅ 完成 摘要品質升級 + 檔案反向索引（跨 Session 考古地基）
3.5 ✅ 完成 統計儀表板 + 跨 Session 考古 UI（護城河版本）
4 ✅ 完成 Dashboard 進階功能：效率趨勢、浪費偵測、專案健康度
4.5 ✅ 完成 搜尋體驗強化：日期過濾、排序切換、intent_text 搜尋、結果日期與 outcome badge
5 ✅ 完成 Active Time 計算 + Subagent 索引 + requestId Token 去重
5.5 ✅ 完成 Subagent 前端 UI：chips 導覽 + breadcrumb 返回
6 ✅ 完成 儲存管理：exclusion_rules + 總覽頁 + 專案佔用 + 日期範圍排除 + IPC apply-token handshake + indexer skip（v1.9.0）
— 📋 遠期 資料壓縮功能（保留可還原，補 exclusion 硬刪的絕對性）
— 📋 遠期 In-App 自動更新（待 Apple Developer ID code signing）

授權

本專案採用 AGPL-3.0 授權。

作者

子超 (tznthou) / tznthou.com

About

Claude Code 對話回放與考古工具 — Replay & search your Claude Code conversations. Lightweight, read-only, offline-first.

github.com/tznthou/ccRewind

Topics

electron react typescript sqlite developer-tools fts5 conversation-viewer claude-code

Resources

Readme

License

AGPL-3.0 license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 23

ccRewind v1.9.2 Latest
Apr 21, 2026
+ 22 releases

Packages

 
 
 

Contributors

Languages