recall-player 1.0.0

package/README.md

@@ -0,0 +1,238 @@
+# Recall
+
+A local-first web application that lets you **replay AI coding sessions** like a video player. Watch how features were built, decisions made, and problems solved across multiple AI coding agents.
+
+**Supported Agents:**
+- **Claude Code** - Anthropic's CLI coding assistant
+- **Codex CLI** - OpenAI's command-line coding tool
+- **Gemini CLI** - Google's terminal-based AI assistant
+
+---
+
+## Quick Start
+
+### Prerequisites
+
+- **Node.js 18+** (check with `node --version`)
+- At least one AI coding agent with session history:
+  - Claude Code sessions in `~/.claude/projects/`
+  - Codex CLI sessions in `~/.codex/sessions/`
+  - Gemini CLI sessions in `~/.gemini/tmp/`
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/anthropics/recall.git
+cd recall
+
+# Install backend dependencies
+cd backend
+npm install
+
+# Install frontend dependencies
+cd ../frontend
+npm install
+```
+
+### Running the Application
+
+You need to run both the backend and frontend servers:
+
+**Terminal 1 - Backend:**
+```bash
+cd backend
+npm run dev
+```
+Backend will start on http://localhost:3001
+
+**Terminal 2 - Frontend:**
+```bash
+cd frontend
+npm run dev
+```
+Frontend will start on http://localhost:5173 (or next available port)
+
+### Using Recall
+
+1. Open your browser to http://localhost:5173
+2. You'll see a list of all your AI coding sessions
+3. Use the filter tabs (All, Claude, Codex, Gemini) to filter by agent
+4. Click on any session to open the replay player
+5. Use the playback controls to step through the session
+
+---
+
+## Features
+
+### Session Browser
+- View all sessions across Claude, Codex, and Gemini
+- Filter by agent type, date range, and duration
+- Search sessions by project name or content
+- See session metadata (duration, event count, first message)
+
+### Session Player
+- **Frame-by-frame playback** of coding sessions
+- **Frame types:** User messages, AI responses, AI thinking, Tool executions
+- **Filter controls** to show/hide specific frame types
+- **Keyboard shortcuts** for navigation (arrow keys, space, etc.)
+- **Search** within sessions to find specific content
+
+### Multi-Agent Support
+- Automatically detects and parses sessions from all supported agents
+- Agent-specific badges and colors in the UI
+- Normalized frame format for consistent playback experience
+
+---
+
+## Project Structure
+
+```
+recall/
+├── backend/                 # Node.js + Express + TypeScript
+│   ├── src/
+│   │   ├── parser/          # Agent-specific parsers
+│   │   │   ├── agent-detector.ts    # Detects agent from file path
+│   │   │   ├── base-parser.ts       # Abstract parser base class
+│   │   │   ├── claude-parser.ts     # Claude Code parser
+│   │   │   ├── codex-parser.ts      # Codex CLI parser
+│   │   │   ├── gemini-parser.ts     # Gemini CLI parser
+│   │   │   └── parser-factory.ts    # Parser selection factory
+│   │   ├── routes/          # API endpoints
+│   │   ├── db/              # Database layer
+│   │   └── types/           # TypeScript types
+│   └── package.json
+│
+├── frontend/                # React + Vite + TypeScript
+│   ├── src/
+│   │   ├── pages/           # Main pages (SessionList, SessionPlayer)
+│   │   ├── components/      # Reusable components
+│   │   ├── api/             # API client
+│   │   └── types/           # TypeScript types
+│   └── package.json
+│
+└── README.md
+```
+
+---
+
+## API Reference
+
+### List Sessions
+```bash
+# Get all sessions
+curl 'http://localhost:3001/api/sessions'
+
+# Filter by agent
+curl 'http://localhost:3001/api/sessions?agent=claude'
+curl 'http://localhost:3001/api/sessions?agent=codex'
+curl 'http://localhost:3001/api/sessions?agent=gemini'
+
+# Pagination
+curl 'http://localhost:3001/api/sessions?limit=10&offset=20'
+```
+
+### Get Available Agents
+```bash
+curl 'http://localhost:3001/api/agents'
+# Returns: { "agents": ["claude", "codex", "gemini"], "counts": {...} }
+```
+
+### Get Session Details
+```bash
+curl 'http://localhost:3001/api/sessions/{sessionId}'
+```
+
+### Get Session Frames
+```bash
+curl 'http://localhost:3001/api/sessions/{sessionId}/frames'
+```
+
+---
+
+## Keyboard Shortcuts (Session Player)
+
+| Key | Action |
+|-----|--------|
+| `Space` | Play/Pause |
+| `←` / `→` | Previous/Next frame |
+| `Home` / `End` | First/Last frame |
+| `n` / `p` | Next/Previous search match |
+| `?` | Toggle help panel |
+
+---
+
+## Development
+
+### Backend Development
+```bash
+cd backend
+npm run dev      # Development with hot reload
+npm run build    # Build for production
+npm start        # Run production build
+npm test         # Run tests
+```
+
+### Frontend Development
+```bash
+cd frontend
+npm run dev      # Development with hot reload
+npm run build    # Build for production
+npm run lint     # Run ESLint
+npm run preview  # Preview production build
+```
+
+---
+
+## Session File Locations
+
+Recall automatically scans these directories for sessions:
+
+| Agent | Directory | File Format |
+|-------|-----------|-------------|
+| Claude Code | `~/.claude/projects/{project}/` | `*.jsonl` |
+| Codex CLI | `~/.codex/sessions/` | `*.jsonl` (with date subdirs) |
+| Gemini CLI | `~/.gemini/tmp/{hash}/chats/` | `session-*.json` |
+
+---
+
+## Troubleshooting
+
+### No sessions showing up?
+1. Make sure you have session files in one of the supported directories
+2. Check the backend console for any errors
+3. Try the API directly: `curl http://localhost:3001/api/agents`
+
+### Backend won't start?
+1. Make sure you're in the `backend` directory
+2. Run `npm install` to install dependencies
+3. Check that port 3001 is available
+
+### Frontend won't start?
+1. Make sure you're in the `frontend` directory
+2. Run `npm install` to install dependencies
+3. The frontend will automatically find an available port if 5173 is taken
+
+---
+
+## Security Notes
+
+- **Local-only**: This app is designed for local use only
+- **Read-only**: Session files are read but never modified
+- **Sensitive data**: Session files may contain API keys, credentials, or sensitive code - do not expose this app to the internet
+
+---
+
+## License
+
+MIT
+
+---
+
+## Credits
+
+Built with:
+- [Node.js](https://nodejs.org/) + [Express](https://expressjs.com/)
+- [React](https://react.dev/) + [Vite](https://vitejs.dev/)
+- [TypeScript](https://www.typescriptlang.org/)
+- [Tailwind CSS](https://tailwindcss.com/)

package/backend/dist/db/connection.d.ts

@@ -0,0 +1,47 @@
+import Database from 'better-sqlite3';
+/**
+ * Creates and configures a new SQLite database connection
+ *
+ * Opens the claude-mem database in read-only mode for safety.
+ * This prevents accidental modifications to the user's session history.
+ *
+ * @returns {Database.Database} Configured SQLite database instance
+ * @throws {Error} If database file doesn't exist at DB_PATH
+ *
+ * @example
+ * const db = getDatabase();
+ * const result = db.prepare('SELECT COUNT(*) as count FROM sdk_sessions').get();
+ * console.log(`Found ${result.count} sessions`);
+ */
+export declare function getDatabase(): Database.Database;
+/**
+ * Get the singleton database instance
+ *
+ * Creates a new connection on first call, then reuses it for subsequent calls.
+ * This is safe because SQLite handles concurrent reads well in read-only mode.
+ *
+ * @returns {Database.Database} Singleton database instance
+ *
+ * @example
+ * import { getDbInstance } from './connection';
+ *
+ * const db = getDbInstance();
+ * const sessions = db.prepare('SELECT * FROM sdk_sessions LIMIT 10').all();
+ */
+export declare function getDbInstance(): Database.Database;
+/**
+ * Close the database connection and clear the singleton
+ *
+ * Should be called during graceful shutdown (SIGTERM, SIGINT).
+ * Ensures the database file is properly closed.
+ *
+ * @example
+ * process.on('SIGTERM', () => {
+ *   server.close(() => {
+ *     closeDatabase();
+ *     process.exit(0);
+ *   });
+ * });
+ */
+export declare function closeDatabase(): void;
+//# sourceMappingURL=connection.d.ts.map

package/backend/dist/db/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/db/connection.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AAUtC;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,IAAI,QAAQ,CAAC,QAAQ,CAc/C;AAQD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,IAAI,QAAQ,CAAC,QAAQ,CAKjD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAKpC"}

package/backend/dist/db/connection.js

@@ -0,0 +1,88 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDatabase = getDatabase;
+exports.getDbInstance = getDbInstance;
+exports.closeDatabase = closeDatabase;
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+/**
+ * Default path to the claude-mem database
+ * Located in user's home directory: ~/.claude-mem/claude-mem.db
+ */
+const DB_PATH = path_1.default.join(process.env.HOME || '', '.claude-mem', 'claude-mem.db');
+/**
+ * Creates and configures a new SQLite database connection
+ *
+ * Opens the claude-mem database in read-only mode for safety.
+ * This prevents accidental modifications to the user's session history.
+ *
+ * @returns {Database.Database} Configured SQLite database instance
+ * @throws {Error} If database file doesn't exist at DB_PATH
+ *
+ * @example
+ * const db = getDatabase();
+ * const result = db.prepare('SELECT COUNT(*) as count FROM sdk_sessions').get();
+ * console.log(`Found ${result.count} sessions`);
+ */
+function getDatabase() {
+    if (!fs_1.default.existsSync(DB_PATH)) {
+        throw new Error(`Database not found at ${DB_PATH}. Make sure claude-mem is installed and has recorded sessions.`);
+    }
+    const db = new better_sqlite3_1.default(DB_PATH, {
+        readonly: true, // Prevent accidental writes
+        fileMustExist: true // Fail if file doesn't exist
+    });
+    // Enable better error messages for foreign key violations
+    db.pragma('foreign_keys = ON');
+    return db;
+}
+/**
+ * Global database instance (singleton)
+ * Reused across all requests to avoid connection overhead
+ */
+let dbInstance = null;
+/**
+ * Get the singleton database instance
+ *
+ * Creates a new connection on first call, then reuses it for subsequent calls.
+ * This is safe because SQLite handles concurrent reads well in read-only mode.
+ *
+ * @returns {Database.Database} Singleton database instance
+ *
+ * @example
+ * import { getDbInstance } from './connection';
+ *
+ * const db = getDbInstance();
+ * const sessions = db.prepare('SELECT * FROM sdk_sessions LIMIT 10').all();
+ */
+function getDbInstance() {
+    if (!dbInstance) {
+        dbInstance = getDatabase();
+    }
+    return dbInstance;
+}
+/**
+ * Close the database connection and clear the singleton
+ *
+ * Should be called during graceful shutdown (SIGTERM, SIGINT).
+ * Ensures the database file is properly closed.
+ *
+ * @example
+ * process.on('SIGTERM', () => {
+ *   server.close(() => {
+ *     closeDatabase();
+ *     process.exit(0);
+ *   });
+ * });
+ */
+function closeDatabase() {
+    if (dbInstance) {
+        dbInstance.close();
+        dbInstance = null;
+    }
+}
+//# sourceMappingURL=connection.js.map

package/backend/dist/db/connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../src/db/connection.ts"],"names":[],"mappings":";;;;;AAwBA,kCAcC;AAsBD,sCAKC;AAgBD,sCAKC;AAtFD,oEAAsC;AACtC,gDAAwB;AACxB,4CAAoB;AAEpB;;;GAGG;AACH,MAAM,OAAO,GAAG,cAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,EAAE,aAAa,EAAE,eAAe,CAAC,CAAC;AAElF;;;;;;;;;;;;;GAaG;AACH,SAAgB,WAAW;IACzB,IAAI,CAAC,YAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,yBAAyB,OAAO,gEAAgE,CAAC,CAAC;IACpH,CAAC;IAED,MAAM,EAAE,GAAG,IAAI,wBAAQ,CAAC,OAAO,EAAE;QAC/B,QAAQ,EAAE,IAAI,EAAO,4BAA4B;QACjD,aAAa,EAAE,IAAI,CAAE,6BAA6B;KACnD,CAAC,CAAC;IAEH,0DAA0D;IAC1D,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC;IAE/B,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;GAGG;AACH,IAAI,UAAU,GAA6B,IAAI,CAAC;AAEhD;;;;;;;;;;;;;GAaG;AACH,SAAgB,aAAa;IAC3B,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,UAAU,GAAG,WAAW,EAAE,CAAC;IAC7B,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAgB,aAAa;IAC3B,IAAI,UAAU,EAAE,CAAC;QACf,UAAU,CAAC,KAAK,EAAE,CAAC;QACnB,UAAU,GAAG,IAAI,CAAC;IACpB,CAAC;AACH,CAAC"}

package/backend/dist/db/queries.d.ts

@@ -0,0 +1,172 @@
+import type { Session, SessionEvent, SessionListQuery, SessionEventsQuery } from './schema';
+/**
+ * Get all sessions with optional filtering and pagination
+ *
+ * Fetches sessions from the claude-mem database with support for:
+ * - Pagination (offset/limit)
+ * - Project filtering
+ * - Date range filtering
+ *
+ * Results are ordered by most recent first (started_at_epoch DESC).
+ *
+ * @param {SessionListQuery} query - Query parameters
+ * @param {number} [query.offset=0] - Number of sessions to skip
+ * @param {number} [query.limit=20] - Maximum number of sessions to return
+ * @param {string} [query.project] - Filter by project name (exact match)
+ * @param {string} [query.dateStart] - Filter sessions started after this date (ISO 8601)
+ * @param {string} [query.dateEnd] - Filter sessions started before this date (ISO 8601)
+ * @returns {{ sessions: Session[]; total: number }} Paginated sessions and total count
+ *
+ * @example
+ * // Get first 10 sessions
+ * const result = getSessions({ limit: 10, offset: 0 });
+ * console.log(`Found ${result.total} total sessions`);
+ * console.log(`Showing ${result.sessions.length} sessions`);
+ *
+ * @example
+ * // Filter by project and date
+ * const result = getSessions({
+ *   project: 'my-project',
+ *   dateStart: '2026-02-01T00:00:00.000Z',
+ *   limit: 20
+ * });
+ */
+export declare function getSessions(query: SessionListQuery): {
+    sessions: Session[];
+    total: number;
+};
+/**
+ * Get a single session by its UUID
+ *
+ * Fetches session metadata from the sdk_sessions table.
+ * Returns null if the session doesn't exist.
+ *
+ * @param {string} sessionId - Claude session UUID (claude_session_id)
+ * @returns {Session | null} Session object or null if not found
+ *
+ * @example
+ * const session = getSessionById('550e8400-e29b-41d4-a716-446655440000');
+ * if (session) {
+ *   console.log(`Project: ${session.project}`);
+ *   console.log(`Prompts: ${session.prompt_counter}`);
+ * }
+ */
+export declare function getSessionById(sessionId: string): Session | null;
+/**
+ * Get statistics for a session
+ *
+ * Calculates the total number of events, prompts, and observations
+ * for a given session. Useful for displaying session metadata.
+ *
+ * @param {string} sessionId - Claude session UUID
+ * @returns {{ eventCount: number; promptCount: number; observationCount: number } | null}
+ *          Statistics object or null if session not found
+ *
+ * @example
+ * const stats = getSessionStats('550e8400-e29b-41d4-a716-446655440000');
+ * if (stats) {
+ *   console.log(`Total events: ${stats.eventCount}`);
+ *   console.log(`Prompts: ${stats.promptCount}`);
+ *   console.log(`Observations: ${stats.observationCount}`);
+ * }
+ */
+export declare function getSessionStats(sessionId: string): {
+    eventCount: number;
+    promptCount: number;
+    observationCount: number;
+} | null;
+/**
+ * Get session timeline events with TIME-FIRST ordering
+ *
+ * This is the core timeline reconstruction algorithm, validated in Phase 0.
+ * Events are ordered chronologically with prompts appearing before observations.
+ *
+ * **Ordering Algorithm:**
+ * 1. PRIMARY: Timestamp (ts ASC) - Chronological order
+ * 2. SECONDARY: Prompt number (COALESCE(prompt_number, 999999) ASC) - Group by prompt
+ * 3. TERTIARY: Kind rank (kind_rank ASC) - Prompts before observations
+ * 4. FINAL: Row ID (row_id ASC) - Stable tiebreaker
+ *
+ * **JSON Field Parsing:**
+ * The following fields are automatically parsed from JSON strings:
+ * - facts
+ * - concepts
+ * - files_read
+ * - files_modified
+ *
+ * **Validation:**
+ * This query has been validated on sessions with up to 902 events and passes
+ * all ordering checks (monotonic timestamps, prompt-before-observation, etc.)
+ *
+ * @param {string} sessionId - Claude session UUID
+ * @param {SessionEventsQuery} query - Filter and pagination options
+ * @param {number} [query.offset=0] - Number of events to skip
+ * @param {number} [query.limit=100] - Maximum number of events to return
+ * @param {string} [query.types] - Comma-separated observation types (e.g., "feature,bugfix")
+ * @param {number} [query.afterTs] - Only return events after this timestamp (epoch ms)
+ * @returns {{ events: SessionEvent[]; total: number }} Ordered events and total count
+ *
+ * @example
+ * // Get first 100 events
+ * const result = getSessionEvents(sessionId, { limit: 100, offset: 0 });
+ * console.log(`Total events: ${result.total}`);
+ * console.log(`Fetched: ${result.events.length}`);
+ *
+ * @example
+ * // Get only feature observations
+ * const result = getSessionEvents(sessionId, {
+ *   types: 'feature',
+ *   limit: 50
+ * });
+ *
+ * @example
+ * // Infinite scroll pagination
+ * const page1 = getSessionEvents(sessionId, { limit: 100, offset: 0 });
+ * const page2 = getSessionEvents(sessionId, { limit: 100, offset: 100 });
+ */
+export declare function getSessionEvents(sessionId: string, query: SessionEventsQuery): {
+    events: SessionEvent[];
+    total: number;
+};
+/**
+ * Get a single event by its type and ID
+ *
+ * Fetches either a prompt or observation by its database row ID.
+ * For observations, JSON fields are automatically parsed.
+ *
+ * @param {('prompt' | 'observation')} eventType - Type of event to fetch
+ * @param {number} eventId - Database row ID of the event
+ * @returns {SessionEvent | null} Event object or null if not found
+ *
+ * @example
+ * // Get a prompt
+ * const prompt = getEventById('prompt', 123);
+ * if (prompt) {
+ *   console.log(`Prompt: ${prompt.text}`);
+ * }
+ *
+ * @example
+ * // Get an observation
+ * const obs = getEventById('observation', 456);
+ * if (obs) {
+ *   console.log(`Type: ${obs.obs_type}`);
+ *   console.log(`Title: ${obs.title}`);
+ *   console.log(`Files modified: ${obs.files_modified?.join(', ')}`);
+ * }
+ */
+export declare function getEventById(eventType: 'prompt' | 'observation', eventId: number): SessionEvent | null;
+/**
+ * Get a list of all unique project names
+ *
+ * Returns all distinct project names from the sessions table,
+ * sorted alphabetically. Useful for project filter dropdowns.
+ *
+ * @returns {string[]} Array of project names
+ *
+ * @example
+ * const projects = getProjects();
+ * console.log(`Found ${projects.length} projects:`);
+ * projects.forEach(p => console.log(`  - ${p}`));
+ */
+export declare function getProjects(): string[];
+//# sourceMappingURL=queries.d.ts.map

package/backend/dist/db/queries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../src/db/queries.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,OAAO,EACP,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,UAAU,CAAC;AAalB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG;IAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAuD3F;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAUhE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG;IAClD,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;CAC1B,GAAG,IAAI,CA8BP;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,kBAAkB,GACxB;IAAE,MAAM,EAAE,YAAY,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAmI3C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,QAAQ,GAAG,aAAa,EAAE,OAAO,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAoDtG;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,IAAI,MAAM,EAAE,CAUtC"}