diff --git a/README.md b/README.md new file mode 100644 index 0000000..d920f2c --- /dev/null +++ b/README.md @@ -0,0 +1,127 @@ +# Session Viewer + +Browse, filter, redact, and export Claude Code sessions as self-contained HTML files. + +Session Viewer reads session data from `~/.claude/projects/` and presents it in a dark-themed web interface with full-text search, message filtering, sensitive data redaction, and one-click HTML export. + +## Quick Start + +```bash +# Install dependencies +npm install + +# Run in development mode (starts both server and client with hot reload) +npm run dev + +# Or run from the CLI entry point (opens browser automatically) +node bin/session-viewer.js +``` + +The API server runs on `http://localhost:3848` and the Vite dev server on `http://localhost:3847` (proxying API requests to the backend). + +## Features + +### Session Navigation + +- **Project grouping** -- Sessions are organized by their originating project directory. +- **Session metadata** -- Each session displays its summary, first prompt, message count, duration, and last-modified date. +- **Sorted by recency** -- Most recently modified sessions appear first. + +### Message Display + +- **Nine message categories** -- `user_message`, `assistant_text`, `thinking`, `tool_call`, `tool_result`, `system_message`, `hook_progress`, `file_snapshot`, and `summary`, each with a distinct color indicator. +- **Collapsible sections** -- Thinking blocks, tool calls, and tool results collapse by default to reduce noise. +- **Diff rendering** -- Git-style diffs are auto-detected and rendered with line-level syntax coloring. +- **Code blocks** -- Fenced code blocks display a language label and a copy-to-clipboard button. +- **Time gap indicators** -- Gaps of more than five minutes between messages are shown as labeled dividers. +- **Hash anchor links** -- Each message has a copyable anchor link (`#msg-{uuid}`) for deep linking. + +### Search + +- **Full-text search** across message content and tool input. +- **Match cycling** -- Navigate between matches with `Enter`/`Shift+Enter` or `Ctrl+G`/`Ctrl+Shift+G`. +- **Match counter** -- Displays current position and total matches (e.g., "3/12"). +- **Minimap** -- A scrollbar overlay shows match positions as yellow ticks with a viewport indicator. Click a tick to jump to that match. +- **Dimming** -- Non-matching messages are visually dimmed while search is active. +- **Keyboard shortcut** -- Press `/` to focus the search bar; `Escape` to clear and blur. + +### Filtering + +- **Category toggles** -- Show or hide any of the nine message categories. Thinking and hook progress are hidden by default. +- **Filters compose with search** -- Category filters and search operate independently. + +### Redaction + +- **Manual redaction** -- Click the eye icon on any message to select it, then confirm to redact. Redacted messages are replaced by a visual divider. +- **Auto-redaction** -- Toggle automatic detection of sensitive data (API keys, tokens, secrets, PII) using 37 regex patterns derived from gitleaks. Matching content is replaced with `[REDACTED]` inline. +- **Export-aware** -- Both manual and auto-redaction states are respected during export. + +### Export + +- **Self-contained HTML** -- Export the current session view as a standalone HTML file with embedded CSS and syntax highlighting. +- **Respects filters** -- The export includes only visible messages and applies the current redaction state. +- **Clean filenames** -- Output files are named `session-{id}.html` with sanitized IDs. + +## Architecture + +``` +src/ + client/ React + Vite frontend + components/ UI components (SessionList, SessionViewer, MessageBubble, etc.) + hooks/ useSession, useFilters + lib/ Markdown rendering, sensitive redactor, types, utilities + styles/ CSS custom properties, Tailwind, design tokens + server/ Express backend + routes/ /api/sessions, /api/export + services/ Session discovery, JSONL parser, HTML exporter + shared/ Types shared between client and server +bin/ CLI entry point +tests/ + unit/ Vitest unit tests + e2e/ Playwright end-to-end tests + fixtures/ Test data +``` + +### Tech Stack + +| Layer | Technology | +| -------- | --------------------------------------- | +| Frontend | React 18, Tailwind CSS, Vite | +| Backend | Express 4, Node.js | +| Markdown | marked + marked-highlight + highlight.js| +| Testing | Vitest (unit), Playwright (e2e) | +| Language | TypeScript (strict mode) | + +### API Endpoints + +| Method | Path | Description | +| ------ | --------------------- | -------------------------------------- | +| GET | `/api/health` | Health check | +| GET | `/api/sessions` | List all sessions (30s server cache) | +| GET | `/api/sessions/:id` | Get session detail with parsed messages| +| POST | `/api/export` | Generate self-contained HTML export | + +## Scripts + +| Script | Description | +| ---------------- | ---------------------------------------------- | +| `npm run dev` | Start server + client with hot reload | +| `npm run build` | TypeScript compile + Vite production build | +| `npm run test` | Run unit tests (Vitest) | +| `npm run test:e2e` | Run end-to-end tests (Playwright) | +| `npm run typecheck` | TypeScript type checking | +| `npm run lint` | ESLint | + +## Configuration + +| Variable | Default | Description | +| -------------------------- | -------- | --------------------------------- | +| `PORT` | `3848` | API server port | +| `SESSION_VIEWER_OPEN_BROWSER` | unset | Set to `1` to auto-open browser on start | + +## Security + +- **Path traversal protection** -- Session discovery validates all paths stay within `~/.claude/projects/`. +- **HTML escaping** -- All user content is escaped before interpolation in exports. +- **Filename sanitization** -- Export filenames strip non-alphanumeric characters. +- **Localhost binding** -- Both the API server and Vite dev server bind to `127.0.0.1` only.