Search, inspect, and reconstruct Claude Code sessions. Lightweight, read-only, offline-first — your ~/.claude/ stays untouched.
Switch between three visual themes with one click. Built-in token usage dashboard lets you review conversations in style.
| 📂 Archive | 🕐 Timeline | 💻 Terminal |
 |
 |
 |
ccRewind reads JSONL conversation logs from ~/.claude/projects/, builds a SQLite + FTS5 index, and provides browsing, searching, and exporting capabilities.
Session summaries are produced by a structured rule engine — intent extraction (skipping greetings), action breakdown (e.g. Edit×8, 5 files), and outcome inference (committed / tested / in-progress) — all at zero API cost. Tags are cross-inferred from three signals: message text, file paths, and tool usage patterns. A future BYOK (Bring Your Own Key) mode will offer higher-quality LLM summaries as an opt-in.
Everything is read-only. ccRewind never modifies any file under ~/.claude/. Your conversations, memory files, and settings remain untouched. Not a single byte.
When Claude Code deletes a session, ccRewind automatically archives that conversation. All messages, tags, and summaries stay in SQLite and won't disappear with the JSONL file.
Built for depth, not breadth.
Browsing & Search
| Feature | Description |
|---|---|
| Conversation Browser | User/assistant bubble UI with Markdown rendering + syntax highlighting |
| Tool Collapsing | tool_use / tool_result blocks collapsed by default, click to expand |
| Markdown Export | One-click export session to .md with metadata table + tool <details> blocks |
| Full-Text Search | FTS5 index with pagination, results grouped by session. Two modes: "Messages" (content) and "Tags/Files" (session metadata). Filter by date range (7d/30d/90d) and toggle between relevance or chronological sort |
| Search Context Preview | Expand any search result to see 2 surrounding messages without navigating away. Results show session date and outcome status badge |
Token & Context
| Feature | Description |
|---|---|
| Context Budget | Token breakdown (input/output/cache), context growth chart, output intensity heat bar — see at a glance how many tokens each session burned and how well cache hit |
| Token Insights | Auto-interpret the charts: detect context spikes and attribute them, evaluate cache efficiency, mark output hotspots, analyse growth trends — so the charts aren't just pretty, they're readable |
| Token Heat Indicators | Color bar on the left of assistant messages (green = good cache hit, red = high cost). Session list shows total tokens and supports token-based sorting |
| Accurate Token Stats | Detects when a single API response is split into multiple JSONL entries and deduplicates via requestId, fixing ~2.3x token inflation |
Statistics & Archaeology
| Feature | Description |
|---|---|
| Statistics Dashboard | Cross-session analytics: usage trend (dual-axis area chart), efficiency trend (tokens/turn), waste detection (high-token low-outcome sessions with click-to-navigate), project health (outcome stacked bar + trend arrows), tool/tag distribution, work pattern heatmap |
| Cross-Session Archaeology | File history drawer (click a file to see every session that touched it), related session recommendations (Jaccard similarity), expandable file chips |
| File Reverse Index | For every session, which files were touched and how (read/edit/write); click any file to trace its history across sessions |
| Session Auto-Summary | Structured rule engine: intent extraction (skipping greetings), action breakdown (e.g. Edit×8, 5 files), outcome inference (committed/tested/in-progress), and 20+ multi-signal tags |
| Subagent Browser | Automatically scans and indexes subagents/*.jsonl transcripts. Sessions with subagents display clickable chips (agent type + message count); clicking navigates into the subagent conversation with a breadcrumb bar for parent navigation |
Data & Storage
| Feature | Description |
|---|---|
| Data Preservation | Automatically archives conversations when JSONL files are deleted. No history is ever lost |
| Storage Management | Inspect index DB footprint (size, session/message counts, per-project breakdown with visual bars) and reclaim space via exclusion rules — exclude an entire project in one click, or a date range, or remove existing rules. Every destructive action funnels through a unified confirm dialog (checkbox acknowledgement + red banner above 50% impact), with an apply-token IPC handshake closing the renderer trust-boundary gap |
| DB Compaction | Storage page surfaces reclaimable space (freelist × page_size from live PRAGMA reads) with a one-click VACUUM button that releases pages left behind by SQLite DELETE. The confirm dialog spells out that compaction only reorganizes file structure and never deletes conversations |
| Incremental Indexing | Scans all JSONL on first launch, processes only new/modified files afterwards. Resumed sessions are automatically UUID-deduplicated, preventing duplicate messages |
| Auto DB Migration | Schema changes applied automatically on startup, seamless upgrades for large databases |
UI & Interaction
| Feature | Description |
|---|---|
| Three Themes | Archive, Timeline, and Terminal themes, one-click toggle |
| Active Time | Session duration prioritizes active time (excluding >5min idle periods), with wall-clock time shown in parentheses. Dashboard averages use active time |
| Update Notification | Detects new GitHub releases on launch, one-click to open download page |
| Virtual Scrolling | Handles large session lists smoothly (@tanstack/react-virtual) |
| Internationalization | Traditional Chinese (zh-TW) and English UI, toggled from the title bar. All UI strings flow through a type-safe MessageKey catalog (zh-TW default), persisted in localStorage |
| Font Scale | Three-tier font zoom (normal 1.0× / large 1.1× / xlarge 1.25×) driven by a --font-scale CSS variable on :root, with a synchronous boot-time script preventing FOUC |
| Sync Awareness | Auto-reindex when the window regains focus (in-flight Promises de-duplicate to prevent indexer thrashing), manual "Sync now" button, and a "Last indexed Xs ago" staleness label |
| Sidebar Keyboard Navigation | Project list, session list, message search, and session search all support ↑↓ arrow navigation. ArrowDown from the search bar hands focus to the first result. Virtualized lists use aria-activedescendant so focus stays stable as the active row scrolls in and out of the viewport |
| Accessibility | WCAG 2.1 AA contrast, ARIA labels (incl. radio keyboard pattern), focus management |
See docs/USER-GUIDE_EN.md for detailed usage — Session Summaries & Tags, Search, Context Budget, Dashboard, Cross-Session Archaeology, Storage Management.
graph TB
subgraph Main Process
FS[File Scanner<br>~/.claude/projects/] --> JP[JSONL Parser]
JP --> SM[Summary Engine<br>intent + outcome + tags]
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 Exporter] --> IPC
AT[Apply-Token Handshake<br>one-time UUID · 60s TTL] --> IPC
end
subgraph Renderer Process
SB[Sidebar<br>Project List + Session List + Search]
CV[ChatView<br>Conversation Reader + Token Budget<br>+ File Chips + Related Sessions]
DB_UI[Dashboard<br>Usage/Efficiency Trends · Project Health<br>Waste Detection · Tool/Tag Distribution · Work Patterns]
FH[FileHistoryDrawer<br>Cross-Session File History Timeline]
SP[StoragePage<br>Overview cards · Project bars<br>Exclusion rules · Confirm Dialog]
end
IPC <-->|invoke / handle| SB
IPC <-->|invoke / handle| CV
IPC <-->|invoke / handle| DB_UI
IPC <-->|invoke / handle| FH
IPC <-->|invoke / handle| SP
| Technology | Purpose | Notes |
|---|---|---|
| Electron 33 | Desktop app framework | macOS hiddenInset title bar |
| React 19 | UI framework | Function components + hooks |
| TypeScript 5.7 | Type safety | Strict mode |
| better-sqlite3 11 | SQLite binding | With FTS5 full-text search |
| electron-vite 5 | Build tool | Triple build: main + preload + renderer |
| recharts 3 | Chart library | Area, pie, donut charts (Context Budget + Dashboard) |
| Vitest 3 | Test framework | 355 tests, run through Electron |
Download the pre-built binary for your platform from Releases:
- macOS (arm64): DMG (drag into Applications) or ZIP (extract and run)
- Windows (x64): NSIS installer or ZIP
System requirements: macOS 11+ / Windows 10+
ccRewind is not yet signed with an Apple Developer ID or Microsoft code-signing certificate, so your OS will show the standard warning for unsigned apps on first launch:
- macOS: If you see "cannot verify developer", open System Settings → Privacy & Security, find ccRewind, and click Open Anyway
- Windows: If SmartScreen shows "Windows protected your PC", click More info → Run anyway
- Node.js >= 20, < 23
- pnpm >= 9
git clone https://github.com/tznthou/ccRewind.git
cd ccRewind
pnpm install
pnpm devpnpm build
pnpm distpnpm test # Run tests (Vitest via Electron)
pnpm typecheck # TypeScript type check
pnpm lint # ESLint auto-fixExpand the full directory tree
ccRewind/
├── src/
│ ├── main/ # Electron main process
│ │ ├── index.ts # App entry point
│ │ ├── scanner.ts # Project / session file scanner
│ │ ├── parser.ts # JSONL parser
│ │ ├── database.ts # SQLite + FTS5 management (incl. sessions_fts)
│ │ ├── indexer.ts # Incremental indexer
│ │ ├── summarizer.ts # Session auto-summary (heuristic)
│ │ ├── exporter.ts # Markdown export
│ │ ├── updater.ts # GitHub Release update checker
│ │ └── ipc-handlers.ts # IPC communication handlers
│ ├── preload/ # contextBridge security bridge
│ │ └── index.ts
│ ├── renderer/ # React frontend
│ │ ├── App.tsx # Root component
│ │ ├── components/
│ │ │ ├── Sidebar/ # Project list + session list + search
│ │ │ ├── ChatView/ # Conversation reader + Token heat indicators + File Chips + Subagent navigation + export
│ │ │ ├── Dashboard/ # Statistics dashboard: usage/efficiency trends, project health, waste detection, tool/tag distribution, work patterns
│ │ │ ├── Archaeology/ # Cross-session archaeology: FileHistoryDrawer, RelatedSessionsPanel
│ │ │ ├── Storage/ # Storage management: overview cards, project breakdown bars, exclusion rules, unified Confirm Dialog
│ │ │ ├── TokenBudget/ # Context Budget panel: area chart, pie chart, heat bar, Insights
│ │ │ ├── ThemeSwitcher/ # Three-theme toggle
│ │ │ ├── FontScaleSwitcher/ # Three-tier font zoom with ARIA radio keyboard pattern
│ │ │ └── UpdateBanner/ # Update notification banner
│ │ ├── hooks/ # useSession, useSessions, useProjects, useIndexerStatus, useListboxKeyNav
│ │ ├── i18n/ # LanguageSwitcher + message catalog + useI18n (zh-TW + en)
│ │ ├── utils/ # formatTokens, formatTime, formatDuration, pathDisplay, renderSnippet
│ │ └── context/ # AppContext + ThemeContext + FontScaleContext (locale / theme / font scale all persisted to localStorage)
│ └── shared/
│ └── types.ts # Shared types between main and renderer
├── tests/ # Vitest tests (355)
├── docs/ # PRD / SPEC / PLAN
├── electron-builder.yml
└── package.json
Conversations with Claude Code are scattered across ~/.claude/projects/ as JSONL files. Want to revisit a design decision from three days ago? You'd need to remember which session it was, manually cat the JSONL, and hunt through walls of JSON to find that exchange.
Existing solutions are either too heavy (RAG, vector search) or solving a different problem (memory injection, context management). I just wanted to quietly revisit past conversations, like flipping through an archaeologist's field notebook.
That's what ccRewind is: an indexed field notebook for AI archaeology.
ccRewind deliberately does not:
- No context injection: We don't interfere with future conversations, only look back at past ones
- No cloud sync: All data comes from local
~/.claude/, nothing gets uploaded - No file modification: Pure read-only app; we don't even touch the mtime of
~/.claude/ - No live monitoring: This isn't
tail -f, it's archaeology - LLM is always optional: All core features work without an API key. LLM summaries are a nice-to-have, not a requirement
If what you need is "make Claude remember what was said before," look at memory systems like claude-mem. ccRewind solves a different problem: letting humans review their collaboration history with AI.
See docs/ROADMAP.md for details.
| Phase | Status | Theme |
|---|---|---|
| 1 | ✅ Done | Foundation: table splitting, data preservation, pagination, grouping |
| 2 | ✅ Done | Session summary (heuristic), search context preview, scope expansion |
| 2.5 | ✅ Done | Context Budget: token usage tracking, area chart, pie chart, heat bar, sorting |
| 2.6 | ✅ Done | Token Insights Engine: auto-interpret charts (spike detection, cache assessment, hot spot marking, trend analysis) |
| 3 | ✅ Done | Summary quality upgrade + file reverse index (cross-session archaeology foundation) |
| 3.5 | ✅ Done | Statistics dashboard + cross-session archaeology UI |
| 4 | ✅ Done | Advanced dashboard: efficiency trends, waste detection, project health |
| 4.5 | ✅ Done | Search UX: date filter, sort toggle, intent_text search, result date & outcome badges |
| 5 | ✅ Done | Active time calculation + subagent indexing + requestId token dedup |
| 5.5 | ✅ Done | Subagent frontend UI: chip navigation + breadcrumb back |
| 6 | ✅ Done | Storage management: exclusion_rules + overview page + project breakdown + date-range rules + IPC apply-token handshake + indexer skip (v1.9.0) |
| 7 | ✅ Done | i18n + comprehensive a11y upgrade: bilingual UI (zh-TW + en), keyboard navigation, aria-live announcements, font scale, sync UX (v1.10.0) |
| 7.5 | ✅ Done | a11y polish + license relicense (AGPL-3.0 → GPL-3.0-or-later) + README bilingual restructure (v1.11.0) |
| 7.6 | ✅ Done | Dashboard readability pass: full i18n across 7 cards + a11y data exposure (chart values now reach screen readers) + visible outcome legend + outcome inference v2 (NULL 53% → 15.3%) (v1.12.0) |
| — | 📋 Future | Data compression (preserve-and-compact alternative to the absolute hard-delete of exclusion) |
| — | 📋 Future | In-app auto-update (requires Apple Developer ID code signing) |
This project is licensed under GPL-3.0-or-later.
tznthou / tznthou.com