Sessions API Overview¶

The Claude Dashboard provides comprehensive session management with real-time log streaming capabilities.

Architecture¶

Session data is stored in two formats: - Session metadata: JSON files in ~/.claude/sessions/ - Session logs: JSONL files in ~/.claude/projects/*/

API Endpoints¶

Get All Sessions¶

GET /api/sessions

Returns a list of all active and recent sessions with metadata.

Get Session by ID¶

GET /api/sessions/:id

Returns detailed information about a specific session.

Get Session Logs (Streaming)¶

GET /api/sessions/:id/log?cursor=0&chunkSize=256

Query Parameters: - cursor (number): Byte offset to start reading from (default: 0) - chunkSize (number): Chunk size in KB (default: 256, range: 64-512)

Response Headers: - X-Next-Cursor: Byte offset for the next chunk - X-File-Size: Total file size in bytes - X-Has-More: Boolean indicating if more data is available

Response Body:

{
  "entries": [...],
  "nextCursor": 65536,
  "fileSize": 3003637,
  "hasMore": true
}

Implementation Details¶

Cursor-Based Pagination¶

Uses byte offsets instead of row IDs for O(1) seeking
Chunks aligned to last \n to avoid partial JSON lines
Efficient for large log files (tested with 3MB+ files)

Performance¶

Uses Bun's native file I/O: Bun.file().slice(offset, end)
Zero-copy where possible
Chunk size: 128KB-256KB per request (configurable)

Example Usage¶

// Load initial logs
const response = await fetch('/api/sessions/session-id/log?cursor=0&chunkSize=256');
const data = await response.json();

// Load more logs
const nextCursor = response.headers.get('X-Next-Cursor');
const moreLogs = await fetch(`/api/sessions/session-id/log?cursor=${nextCursor}&chunkSize=256`);