# 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.