React + Vite frontend and a small Express API that reuse @asb/core to read local session data from the registry's configured providers (Cursor, Claude, and additional provider ids when registered).
| Service | Port | Env override |
|---|---|---|
| API | 3847 |
PORT |
| Vite dev | 3846 |
VITE_PORT |
Vite proxies /api/* to VITE_API_TARGET (default http://localhost:3847).
From repo root:
npm install
npm run install:all
npm run buildProduction-ish run (after build):
node packages/backend/dist/index.js
# serve packages/frontend/dist with any static host, or:
npx --yes serve -s packages/frontend/dist -l 3846npm run devStarts the API (with tsx watch on packages/backend) and the Vite dev server. Open the URL Vite prints (e.g. http://localhost:3846).
Set CURSOR_USER_DIR in the shell before npm run dev if Cursor’s data is not under the default path for your OS.
- Source filter (header): segmented control driven by
GET /api/providers(All Agents plus one segment per registered provider). Each provider chip uses the descriptor’sbadgeColor(CSS accent) andhealthStatus(unhealthy providers get a distinct style). Session counts per provider come from the latestGET /api/sessionsload: when a provider is unavailable, its count shows — (not0); hover the chip formessage/remediationfrom the unavailable entry. Persists as?source=<id>in the URL (allomits the param). Filters tree, workspaces, sessions, conversation fetch, and transcript search. - Unavailable banner: when
GET /api/sessionsreturns one or moreunavailableentries, an inline alert lists each provider’smessageand optionalremediation(scoped by?source=the same way as sessions). - Sidebar: hierarchical navigation (collapsed single-child chains). Grouping follows each provider’s
workspaceGroupingfrom the descriptor (fs-pathby default for built-ins;external-id/nonefor other providers). Contextual subtitle explains whether the selection filters the session list or narrows transcript search scope. - Sessions: sortable table — leading bookmark star column, then Source, ID, Name, Workspace (leaf; hover for all roots), Created, Updated. ID, Created, and Updated use single-line layout (
white-space: nowrap) so full UUIDs andYYYY-MM-DD HH:MMtimestamps do not wrap. When the API provides an excerpt (first user message from the session transcript, ≤80 chars), a muted sub-row beneath the main row spans ID through Actions: one-line ellipsis preview; omitted whenexcerptis null. Click the star to bookmark a session (outline when off, filled when on); bookmarks persist inlocalStorageasasb.sessionAnnotations(keyed${source}:${sessionId}). Bookmarked rows sort before non-bookmarked rows while Starred only is off; the active column sort (default Updated descending) applies within each group. In the Name column, an optional alias shows as{alias} ({provider name})when both exist, alias alone when the provider name is empty, or(no name)when neither is set. A pencil icon (visible on row hover/focus) opens inline alias edit — Enter or blur saves, Escape cancels; empty input clears the alias. Metadata is hidden by default; use the column-visibility control (columns icon, top-right of the table header) to show it. The choice persists inlocalStorageasasb.columns.metadata(show|hide). Actions column renders every entry in the row’sprimaryActionsarray (descriptor-driven): shell actions copy a command (same UX as legacy Resume; display may show\\\nafter&&); URL actions open in a new tab. Built-in providers still expose a singleresumecommand action;resumeCommandremains on each row for transcript search hits and backward compatibility. Metadata filter fields above the table (per-provider descriptor keys) work whether or not the Metadata column is visible. - Sessions filters: two-row filter panel — date range (From/To) with Created / Updated chosen via a clickable word in the header (persists in
localStorageasasb.filters.dateMode); workspace combobox, name/id text search with inline clear buttons (matches provider name, session id, and stored aliases client-side after Refresh); optional Starred only checkbox (persists asasb.filters.starredOnly, filters the current table instantly); tall outlined Refresh applies pending filter changes (disabled until inputs differ from the last successful fetch). - Message search (tab): case-insensitive substring search over agent JSONL transcript lines; optional session scoping via sidebar path prefix, exact workspace, and/or created/updated datetime range; optional
rolefilter on each line’s JSONrolefield; capped hit list (see API). Hits includesourceandresumeCommandwhen the source filter isall. Two-row filter bar aligned with Sessions filters: date row (Scan sessions by + clickable Created / Updated toggle, From → To) and text row (Message, Workspace, Role), with tall outlined Search transcripts anchored on the right. Created / Updated date scope persists independently inlocalStorageasasb.msgSearch.dateMode(defaultupdated; not shared withasb.filters.dateMode); changing the toggle does not auto-run search—the new mode applies on the next Search transcripts submit. Message, Workspace, and Role fields use inline clear (✕) controls (sharedFilterInputWithClearpattern). Search transcripts is disabled until Message text is non-empty (trimmed) and while a search request is in flight (loading / pulsing affordance). Seedocs/technical/changes/1339-message-search-filter-bar-parity.mdfor implementer detail.
GET /api/health—{ ok, cursorUserDir }GET /api/providers— registered session providers (drives source filter, badges, and health styling):[{ id, displayName, badgeColor?, metadataKeys, resumeCommandName?, workspaceGrouping, healthStatus }, …].workspaceGroupingis"fs-path"|"external-id"|"none".healthStatusis{ ok: true }or{ ok: false, reason, message, remediation? }withreasoninauth|network|not-installed|other.GET /api/tree?source=— navigation tree JSON (NavTreeNodeornull). Optionalsource: provider id from the registry, orall(default). Invalid values →400with accepted ids listed.GET /api/workspaces?source=—{ paths: string[] }(samesourcesemantics).GET /api/sessions?workspace=&q=&dateField=created|updated&rangeFrom=&rangeTo=&source=—{ sessions, unavailable }.sessionsis an array of row objects; each includessessionId,name, workspace fields, timestamps,source,resumeCommand,primaryActions([{ id, label, command?, url? }, …]from the provider descriptor),metadata(provider-specific key/value map ornull), andexcerpt(string | null— single-line preview of the first user message from the session JSONL, ≤80 chars;nullwhen no derivable message). Top-levelunavailablelists providers that could not scan:[{ providerId, reason, message, remediation? }, …]. Optionalsourcefilters bothsessionsandunavailablebefore other query params apply to the session list.GET /api/sessions/:sessionId/conversation?source=— full parsed JSONL transcript for one session (messageswith role, optional timestamp, and content blocks). The API resolves the source from?source=<id>when provided, otherwise from the indexed session list; it returns400when the source still cannot be determined and404when no JSONL exists.GET /api/transcript-search?q=&pathPrefix=&workspace=&dateField=created|updated&rangeFrom=&rangeTo=&limit=&role=&source=— searches JSONL lines. Optionalrolerestricts to lines that parse as a JSON object whose stringrolematches (trimmed, case-insensitive). OmitpathPrefix,workspace, and both date bounds to scan all transcript files (can be slow).limitdefaults to 200, max 5000. Hits are ordered newest first by per-line JSON timestamp when present (timestamp,messageTime,createdAt,time, including undermessage), otherwise by the containing session’s updated time. Response:{ hits, limit, capped }; each hit includessessionId,source,resumeCommand,role(top-level JSONrole, ornull),sortAt/sortAtIso(display/sort time), andtimeSource(messageorsession).
All endpoints are read-only.
Dark layout with cyan/blue accents (see packages/frontend/src/index.css).