spiracha 2.0.0 → 2.2.0

package/AGENTS.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-This repo is a Bun-first local app for browsing, exporting, and exposing agent conversation history from Codex, Claude Code, Kiro, Qoder, Cursor, Antigravity, and OpenCode.
+This repo is a Bun-first local app for browsing, exporting, and exposing agent conversation history from Codex, Claude Code, Grok, Kiro, Qoder, Cursor, Antigravity, and OpenCode.
 
 The command-line exporter, MCP server, and Codex plugin were removed in the 2.0 hard cut. Do not add bridge commands, compatibility aliases, or deprecated entrypoints back. New client workflows should use the stable HTTP API exposed by the UI server or the stable `spiracha/client` package export.
 
@@ -52,10 +52,14 @@ Codex browser/export modules:
   - project/thread browsing queries, delete flows, dashboard summaries, DB path resolution
 - `src/lib/codex-browser-export.ts`
   - UI-facing thread download rendering
+- `src/lib/codex-browser-types.ts`
+  - Codex browser query and presentation contracts
 - `src/lib/codex-thread-types.ts`
   - Codex DB row and transcript rendering types
 - `src/lib/codex-transcript-renderer.ts`
   - Markdown/plain text rendering for Codex session files
+- `src/lib/codex-transcript-filter.ts`
+  - centralized hidden bootstrap and transcript-text filtering
 - `src/lib/codex-thread-parser.ts`
   - structured Codex event parsing used by analytics and the UI
 - `src/lib/codex-analytics.ts`
@@ -66,29 +70,35 @@ Codex browser/export modules:
   - Codex project recovery helpers
 
 Source-specific browser/export modules:
-- `src/lib/claude-code-db.ts`, `src/lib/claude-code-transcript-phase.ts`, `src/lib/claude-code-transcript.ts`
-- `src/lib/kiro-db.ts`, `src/lib/kiro-transcript-phase.ts`, `src/lib/kiro-transcript.ts`
-- `src/lib/qoder-db.ts`, `src/lib/qoder-transcript-phase.ts`, `src/lib/qoder-transcript.ts`
-- `src/lib/cursor-db.ts`, `src/lib/cursor-recovery.ts`, `src/lib/cursor-transcript.ts`
-- `src/lib/antigravity-db.ts`, `src/lib/antigravity-keychain.ts`
-- `src/lib/opencode-db.ts`, `src/lib/opencode-transcript-phase.ts`, `src/lib/opencode-think-tags.ts`, `src/lib/opencode-transcript.ts`
+- `src/lib/claude-code-db.ts`, `src/lib/claude-code-exporter-types.ts`, `src/lib/claude-code-transcript-phase.ts`, `src/lib/claude-code-transcript.ts`
+- `src/lib/grok-db.ts`, `src/lib/grok-exporter-types.ts`, `src/lib/grok-transcript-phase.ts`, `src/lib/grok-transcript.ts`
+- `src/lib/kiro-db.ts`, `src/lib/kiro-exporter-types.ts`, `src/lib/kiro-transcript-phase.ts`, `src/lib/kiro-transcript.ts`
+- `src/lib/qoder-db.ts`, `src/lib/qoder-acp-client.ts`, `src/lib/qoder-exporter-types.ts`, `src/lib/qoder-transcript-phase.ts`, `src/lib/qoder-transcript.ts`
+- `src/lib/cursor-db.ts`, `src/lib/cursor-exporter-types.ts`, `src/lib/cursor-recovery.ts`, `src/lib/cursor-transcript-phase.ts`, `src/lib/cursor-transcript.ts`
+- `src/lib/antigravity-db.ts`, `src/lib/antigravity-exporter-types.ts`, `src/lib/antigravity-keychain.ts`, `src/lib/antigravity-projects.ts`, `src/lib/antigravity-transcript-phase.ts`
+- `src/lib/opencode-db.ts`, `src/lib/opencode-exporter-types.ts`, `src/lib/opencode-transcript-phase.ts`, `src/lib/opencode-think-tags.ts`, `src/lib/opencode-transcript.ts`
 
 Shared utilities:
 - `src/lib/concurrency.ts`
 - `src/lib/model-label.ts`
 - `src/lib/path-transforms.ts`
+- `src/lib/portable-path.ts`
 - `src/lib/shared.ts`
 - `src/lib/sqlite-error.ts`
 - `src/lib/sqlite-retry.ts`
 - `src/lib/ui-cache.ts`
 - `src/lib/ui-export-archive.ts`
 - `src/lib/ui-export-files.ts`
+- `src/lib/ui-export-zip.ts`
+- `src/lib/conversation-zip-export.ts`
+- `src/lib/transcript-load-limiter.ts`
+- `src/coverage-check.ts`
 
-UI package:
+UI source tree:
 - `apps/ui/`
   - TanStack Start browser UI
   - API routes live under `apps/ui/src/routes/api.v1.*.ts`
-  - source routes include `/threads/$threadId`, `/claude-code-sessions/$sessionId`, `/kiro-sessions/$sessionId`, `/qoder-sessions/$sessionId`, `/cursor-threads/$composerId`, `/antigravity-conversations/$conversationId`, and `/opencode-sessions/$sessionId`
+  - source routes include `/threads/$threadId`, `/claude-code-sessions/$sessionId`, `/grok-sessions/$sessionId`, `/kiro-sessions/$sessionId`, `/qoder-sessions/$sessionId`, `/cursor-threads/$composerId`, `/antigravity-conversations/$conversationId`, and `/opencode-sessions/$sessionId`
 
 ## Stable API Contract
 
@@ -105,6 +115,9 @@ The local UI server exposes:
 - `POST /api/v1/conversation-query`
 - `GET /api/v1/conversations/:source/:id`
 - `GET /api/v1/conversations/:source/:id/export`
+- `DELETE /api/v1/conversations/:source/:id`
+- `POST /api/v1/conversations/delete`
+- `POST /api/v1/conversations/export`
 - `GET /api/v1/resolve?ref=<url-or-deeplink>`
 
 Defaults:
@@ -126,8 +139,9 @@ Current tests cover:
 - Cursor recovery/prune behavior
 - Antigravity discovery, transcript parsing, Keychain state, and artifact export rendering
 - OpenCode MiniMax `<think>` tag extraction, including code-literal preservation
-- UI component and adapter behavior through the Vitest suite wrapped by `src/ui-package.test.ts`
+- UI component and adapter behavior through the Vitest suite wrapped by `src/ui-suite.test.ts`
 - package manifest hard-cut guarantees through `src/package-manifest.test.ts`
+- a 90% line-coverage gate for both the root Bun suite and UI Vitest suite, with function and hotspot reporting
 
 When changing risky areas:
 - Stable API changes: update `src/lib/conversation-api.test.ts` and focused tests under `src/lib/conversation-data/`.
@@ -147,13 +161,14 @@ rtk bun run build
 rtk bun run coverage
 rtk bun start
 rtk bun run ui:preview
-rtk bun run --cwd apps/ui test
+rtk bun run test:ui
 ```
 
 ## Notes
 
 - Keep root-package source modules imported by the UI available through `@spiracha/lib/*`.
-- The UI package runs Vite through `bun --bun` because server functions depend on Bun-only modules like `bun:sqlite`.
+- The repository has one package manifest. Keep UI runtime dependencies needed by packaged `bunx spiracha` in root `dependencies` and build/test-only tooling in root `devDependencies`.
+- Root-owned UI Vite commands use `apps/ui` as their internal working directory and run through `bun --bun` because TanStack and server functions depend on that application root and Bun-only modules like `bun:sqlite`. Do not add a nested manifest to achieve this. UI Vitest commands use the normal Node runtime.
 - TanStack Start server functions should use `.validator(...)`, not deprecated `.inputValidator(...)`.
 - API routes should use route-level `server.handlers`.
 - Keep `*-transcript-phase.ts` modules browser-safe; UI client adapters import them directly.

package/README.md

@@ -7,7 +7,7 @@
 [![license](https://img.shields.io/npm/l/spiracha)](LICENSE.md)
 [![runtime](https://img.shields.io/badge/runtime-Bun-000000?logo=bun)](https://bun.sh)
 
-Spiracha is a local TanStack Start app for browsing and exporting agent conversation history from Codex, Claude Code, Kiro, Qoder, Cursor, Antigravity, and OpenCode.
+Spiracha is a Bun package with a local TanStack Start UI and a direct data client for browsing and exporting agent conversation history from Codex, Claude Code, Grok, Kiro, Qoder, Cursor, Antigravity, and OpenCode.
 
 The legacy CLI, MCP server, and Codex plugin surfaces have been removed in the 2.0 hard cut. Spiracha now exposes the UI and a stable local data API; client-specific workflows such as review collection belong in the client that calls the API.
 
@@ -24,17 +24,20 @@ Spiracha asks Vite for port 3000 and automatically uses the next available port
 For repository development:
 
 ```bash
-rtk bun install
-rtk bun start
+bun install
+bun start
 ```
 
 Open the local URL printed by Vite.
 
+Spiracha requires Bun 1.3.14 or newer. Set `PORT` to request a different starting port, for example `PORT=4100 bunx spiracha`; the launcher uses the next available port if that one is occupied.
+
 ## What It Does
 
-- Browse local conversations across Codex, Claude Code, Kiro, Qoder, Cursor, Antigravity, and OpenCode.
-- Inspect source-specific detail pages with transcript, tool, reasoning, metadata, raw event, export, and delete flows where supported by the source.
-- Export transcripts from the UI as Markdown, text, or zip bundles with source-specific commentary/final-answer filtering.
+- Browse local conversations across Codex, Claude Code, Grok, Kiro, Qoder, Cursor, Antigravity, and OpenCode.
+- Search Codex projects from the app shell, with results delegated to the shareable `/codex?q=...` inventory filter.
+- Inspect source-specific detail pages with transcript, tool, reasoning, metadata, raw event, export, and delete flows where supported by the source. Codex thread detail includes a tool-focused activity view plus recorded goals and sandbox policy.
+- Export transcripts from the UI as Markdown, text, or zip bundles with source-specific commentary/final-answer filtering. The last submitted export choices persist across dialog openings; canceled drafts do not.
 - Expose a stable API for local clients that need normalized conversation metadata and message payloads.
 - Resolve Spiracha UI links and native source links into normalized `{ source, id }` references for cross-thread context lookup.
 
@@ -54,11 +57,16 @@ GET  /api/v1/conversations?cwd=/absolute/project&include_messages=true
 POST /api/v1/conversation-query
 GET  /api/v1/conversations/:source/:id
 GET  /api/v1/conversations/:source/:id/export
+DELETE /api/v1/conversations/:source/:id
+POST /api/v1/conversations/delete
+POST /api/v1/conversations/export
 GET  /api/v1/resolve?ref=<url-or-deeplink>
 ```
 
 The default list selector is `last_final_answer`, which keeps `fgh --collect` style clients fast and small. Use `message_selector=all` when a client needs the full normalized thread.
 
+Batch delete requires an explicit source and ID list. It returns `deletedIds`, `missingIds`, and a result for each requested ID, so partial success is represented in a `200` response body. Batch export also requires an explicit source and ID list, but is atomic: any missing ID returns an error instead of a partial archive.
+
 Example:
 
 ```bash
@@ -90,13 +98,13 @@ Response envelope:
     }
   ],
   "meta": {
-    "hasNext": false,
+    "has_next": false,
     "next_cursor": null
   }
 }
 ```
 
-For serverless access from Bun, use the public client export:
+For direct access from Bun scripts and CLIs, use the public client export. Local mode reads the source data without starting the TanStack server:
 
 ```ts
 import { createConversationClient } from "spiracha/client";
@@ -109,12 +117,16 @@ const page = await client.listConversations({
 });
 ```
 
+Library and CLI use is quiet by default. Set `SPIRACHA_TRANSCRIPT_LOAD_LOGS=1` or
+`SPIRACHA_OPENCODE_DB_LOGS=1` only when diagnosing loader or OpenCode database timing.
+
 ## Source Locations
 
 | Source | Default location | Primary override |
 | --- | --- | --- |
 | Codex | shared Codex DB probe list | `SPIRACHA_CODEX_DB` |
 | Claude Code | `~/.claude/projects` | `SPIRACHA_CLAUDE_CODE_PROJECTS_DIR` |
+| Grok | `~/.grok/sessions` | `SPIRACHA_GROK_SESSIONS_DIR` |
 | Kiro | `~/Library/Application Support/Kiro/User/globalStorage/kiro.kiroagent/workspace-sessions` | `SPIRACHA_KIRO_WORKSPACE_SESSIONS_DIR` |
 | Qoder | `~/Library/Application Support/Qoder/User/globalStorage/state.vscdb` and `~/Library/Application Support/Qoder/User/workspaceStorage` | `SPIRACHA_QODER_GLOBAL_STATE_DB`, `SPIRACHA_QODER_WORKSPACE_STORAGE_DIR` |
 | Cursor | `~/Library/Application Support/Cursor/User` on macOS | `SPIRACHA_CURSOR_USER_DIR`, `SPIRACHA_CURSOR_PROJECTS_DIR` |
@@ -122,27 +134,38 @@ const page = await client.listConversations({
 | OpenCode | `${XDG_DATA_HOME:-~/.local/share}/opencode/opencode.db` | `SPIRACHA_OPENCODE_DB` |
 | UI exports | OS temp directory under `spiracha-ui-exports` | `SPIRACHA_UI_EXPORT_DIR` |
 
+### Qoder live ACP hydration
+
+Qoder detail/export reads first use persisted state and CLI transcript files. When those do not contain assistant messages and Qoder is running, Spiracha can connect to Qoder's local JSON-RPC ACP Unix socket, issue `initialize` and `session/load`, and collect the streamed session updates. The default socket is the Qoder `SharedClientCache/qoder.sock`; override it with `SPIRACHA_QODER_SOCKET_PATH` (or the legacy environment spelling `SPIRACHA_QODER_SOCKET`). Connection failures and timeouts fall back to the persisted transcript rather than preventing the session from loading.
+
 ## UI Routes
 
 - `/codex` and `/codex/$project` for Codex inventory and project threads.
 - `/threads/$threadId` for Codex thread detail.
-- `/claude-code`, `/kiro`, `/qoder`, `/cursor`, `/antigravity`, and `/opencode` for source inventories.
-- Source detail routes include `/claude-code-sessions/$sessionId`, `/kiro-sessions/$sessionId`, `/qoder-sessions/$sessionId`, `/cursor-threads/$composerId`, `/antigravity-conversations/$conversationId`, and `/opencode-sessions/$sessionId`.
-- `/analytics` for Codex token and tool-call analytics.
+- `/claude-code`, `/grok`, `/kiro`, `/qoder`, `/cursor`, `/antigravity`, and `/opencode` for source inventories.
+- Source detail routes include `/claude-code-sessions/$sessionId`, `/grok-sessions/$sessionId`, `/kiro-sessions/$sessionId`, `/qoder-sessions/$sessionId`, `/cursor-threads/$composerId`, `/antigravity-conversations/$conversationId`, and `/opencode-sessions/$sessionId`.
+- `/analytics` for project-scoped Codex token totals, average and median thread size, archive counts, tool usage, model tokens, client sources, and reasoning-effort breakdowns.
+- `/settings` for transcript path conversion and username redaction. Export dialogs remember their own last submitted options.
 
 ## Development
 
 ```bash
-rtk bun test
-rtk bun run lint
-rtk bun run typecheck
-rtk bun run build
-rtk bun run coverage
-rtk bun start
-rtk bun run --cwd apps/ui test
+bun test
+bun run lint
+bun run typecheck
+bun run build
+bun run coverage
+bun start
+bun run test:ui
 ```
 
-The UI package runs Vite through `bun --bun` because server functions import Bun-only modules such as `bun:sqlite`.
+`bun run coverage` enforces at least 90% line coverage independently for the root Bun suite and the UI Vitest suite, and reports function coverage and per-file hotspots for follow-up.
+
+Run one root test file with `bun test src/lib/shared.test.ts`. Run one UI test file with `bun run test:ui --run apps/ui/src/components/export-dialog.vitest.tsx`.
+
+Spiracha has one package manifest. The `apps/ui` directory remains a source boundary, but all UI and direct-client commands and dependencies are owned at the repository root. Root-owned Vite commands use `apps/ui` as their internal working directory and run through `bun --bun` because TanStack server functions import Bun-only modules such as `bun:sqlite`; Vitest uses its normal Node runtime.
+
+TanStack Router generates `apps/ui/src/routeTree.gen.ts` during development/build. Do not edit it manually; after adding or renaming route files, run `bun run build` (or start the dev server) and include the generated update.
 
 ## Breaking Consequences
 

package/apps/ui/AGENTS.md

@@ -2,22 +2,26 @@
 
 ## Purpose
 
-This package is the local browser UI for Spiracha. It reads Codex, Claude Code, Kiro, Qoder, Cursor, Antigravity, and OpenCode local data through TanStack Start server functions and shared root-package helpers.
+This directory is the local browser UI source tree for Spiracha. It reads Codex, Claude Code, Grok, Kiro, Qoder, Cursor, Antigravity, and OpenCode local data through TanStack Start server functions and shared root-package helpers.
 
 ## Commands
 
 ```bash
-rtk bun run dev
+rtk bun start
 rtk bun run build
-rtk bun run test
+rtk bun run test:ui
 rtk bun run typecheck
 rtk bun run coverage
 ```
 
+Run these commands from the repository root. There is intentionally no nested UI package manifest.
+
 Important:
 
-- `dev`, `build`, and `preview` run through `bun --bun ...` on purpose. Do not switch them back to plain `vite` or Node execution, because the server functions import Bun-only modules such as `bun:sqlite`.
-- The root package mirrors UI runtime dependencies needed by the packaged `bunx spiracha` launcher. Keep `apps/ui/package.json` and the root `dependencies` aligned when browser/runtime dependencies change.
+- `start`, `build`, and `ui:preview` run Vite through `bun --bun ...` on purpose. Do not switch them back to Node execution, because the server functions import Bun-only modules such as `bun:sqlite`.
+- Those root-owned Vite scripts use `apps/ui` as their internal working directory because TanStack Start derives part of its dev-server plan from the process working directory.
+- Keep UI runtime dependencies needed by the packaged `bunx spiracha` launcher in the root `dependencies`. Keep build and test tooling in the root `devDependencies`.
+- Keep Vitest on its normal Node runtime; forcing it through `bun --bun` breaks test-environment module and global behavior.
 
 ## Routing
 
@@ -29,12 +33,13 @@ Important:
 - Codex project inventory and project-thread search use route search params. `/codex` and `/codex/$project` use `q`.
 - Codex analytics uses the `project` route search param so filtered analytics links can be bookmarked and reloaded.
 - Claude Code session detail lives at `/claude-code-sessions/$sessionId`.
+- Grok session detail lives at `/grok-sessions/$sessionId`.
 - Kiro session detail lives at `/kiro-sessions/$sessionId`.
 - Qoder session detail lives at `/qoder-sessions/$sessionId`.
 - Cursor thread detail lives at `/cursor-threads/$composerId`.
 - Antigravity conversation detail lives at `/antigravity-conversations/$conversationId`.
 - OpenCode session detail lives at `/opencode-sessions/$sessionId`.
-- Keep the Codex, Claude Code, Kiro, Qoder, Cursor, Antigravity, and OpenCode list/detail pages aligned around the same table-driven index/detail pattern when adding new source integrations.
+- Keep the Codex, Claude Code, Grok, Kiro, Qoder, Cursor, Antigravity, and OpenCode list/detail pages aligned around the same table-driven index/detail pattern when adding new source integrations.
 
 ## Shared Data Layer
 
@@ -48,6 +53,9 @@ The UI depends on root-package helpers via `@spiracha/*` path aliases:
 - `@spiracha/lib/claude-code-db`
 - `@spiracha/lib/claude-code-transcript-phase`
 - `@spiracha/lib/claude-code-transcript`
+- `@spiracha/lib/grok-db`
+- `@spiracha/lib/grok-transcript-phase`
+- `@spiracha/lib/grok-transcript`
 - `@spiracha/lib/kiro-db`
 - `@spiracha/lib/kiro-transcript-phase`
 - `@spiracha/lib/kiro-transcript`
@@ -73,10 +81,10 @@ The `*-transcript-phase` helpers are intentionally browser-safe and may be impor
 
 Use the existing layers consistently:
 
-- TanStack Start server functions in `src/lib/codex-server.ts`, `src/lib/claude-code-server.ts`, `src/lib/kiro-server.ts`, `src/lib/qoder-server.ts`, `src/lib/cursor-server.ts`, `src/lib/antigravity-server.ts`, and `src/lib/opencode-server.ts`
+- TanStack Start server functions in `src/lib/codex-server.ts`, `src/lib/claude-code-server.ts`, `src/lib/grok-server.ts`, `src/lib/kiro-server.ts`, `src/lib/qoder-server.ts`, `src/lib/cursor-server.ts`, `src/lib/antigravity-server.ts`, and `src/lib/opencode-server.ts`
   - Use for any browser-triggered read/write that needs Bun-only modules, DB access, filesystem access, Keychain access, or shared root-package helpers.
   - Use `.validator(...)` for input validation. Do not add new `.inputValidator(...)` calls.
-- TanStack Query query options in `src/lib/codex-queries.ts`, `src/lib/claude-code-queries.ts`, `src/lib/kiro-queries.ts`, `src/lib/qoder-queries.ts`, `src/lib/cursor-queries.ts`, `src/lib/antigravity-queries.ts`, and `src/lib/opencode-queries.ts`
+- TanStack Query query options in `src/lib/codex-queries.ts`, `src/lib/claude-code-queries.ts`, `src/lib/grok-queries.ts`, `src/lib/kiro-queries.ts`, `src/lib/qoder-queries.ts`, `src/lib/cursor-queries.ts`, `src/lib/antigravity-queries.ts`, and `src/lib/opencode-queries.ts`
   - Use for client-side fetching, caching, retries, and invalidation of server-function results.
 - Shared root-package helpers under `@spiracha/lib/*`
   - Extend these when the behavior should stay shared between the UI and the stable data API.
@@ -103,7 +111,7 @@ For URL-backed route state, use `src/lib/route-search.ts` instead of ad hoc pars
 - UI component tests live under `src/**/*.vitest.tsx`.
 - Source-specific transcript adapter tests live next to their adapter files under `src/lib/*.vitest.ts`.
 - Route search parsing tests live next to the helper in `src/lib/route-search.vitest.ts`.
-- The root package wraps this Vitest suite from `src/ui-package.test.ts` so `rtk bun test` at the repo root exercises both the Bun suite and the UI suite.
+- The root package wraps this Vitest suite from `src/ui-suite.test.ts` so `rtk bun test` exercises both the Bun suite and the UI suite.
 
 ## Design
 
@@ -113,5 +121,5 @@ For URL-backed route state, use `src/lib/route-search.ts` instead of ad hoc pars
 ## Constraints
 
 - Do not add a second database.
-- Do not duplicate transcript parsing or export rendering in this package.
+- Do not duplicate transcript parsing or export rendering in the UI source tree.
 - Use the shared root-package helpers instead.

package/apps/ui/README.md

@@ -1,6 +1,6 @@
 # Spiracha UI
 
-The browser UI for browsing local Codex, Claude Code, Kiro, Qoder, Cursor, Antigravity, and OpenCode history, inspecting transcript details, exporting chats, and analyzing Codex usage patterns.
+The browser UI for browsing local Codex, Claude Code, Grok, Kiro, Qoder, Cursor, Antigravity, and OpenCode history, inspecting transcript details, exporting chats, and analyzing Codex usage patterns.
 
 ## Stack
 
@@ -17,10 +17,13 @@ The browser UI for browsing local Codex, Claude Code, Kiro, Qoder, Cursor, Antig
 
 - lists derived Codex projects from the Codex SQLite database
 - lists Codex threads within a project in chronological order
-- shows Codex thread timelines, tool calls, metadata, and raw event context
-- exports Codex, Claude Code, Kiro, Qoder, Cursor, and OpenCode sessions or threads as Markdown, plain text, or optional zip archives with optional metadata, commentary, and tool-call inclusion
+- shows Codex thread timelines, a dedicated tool activity and definition view, recorded goals, readable sandbox policy, metadata, and raw event context
+- searches Codex projects from the app shell through the URL-backed `/codex?q=...` inventory filter
+- exports Codex, Claude Code, Grok, Kiro, Qoder, Cursor, and OpenCode sessions or threads as Markdown, plain text, or optional zip archives with optional metadata, commentary, and tool-call inclusion; the last submitted choices persist while canceled drafts are discarded
 - lists Claude Code workspaces and sessions from local `~/.claude/projects` JSONL files
 - shows dedicated Claude Code session detail pages with reasoning, tool calls, token metadata, and export actions
+- lists Grok workspaces and sessions from local Grok session archives
+- shows dedicated Grok session detail pages with compacted-history recovery, tool calls, metadata, export, and delete actions
 - lists Kiro workspaces and sessions from local Kiro workspace session files
 - shows dedicated Kiro session detail pages with image attachments, prompt logs, execution-derived tool calls, metadata, and export actions
 - lists Qoder workspaces and sessions from local Qoder history and checkpoint storage
@@ -33,26 +36,26 @@ The browser UI for browsing local Codex, Claude Code, Kiro, Qoder, Cursor, Antig
 - unlocks Antigravity transcript export through macOS Keychain and exports conversations or artifacts as Markdown
 - lists OpenCode workspaces and sessions from the local OpenCode SQLite database
 - shows dedicated OpenCode session detail pages with reasoning, tool parts, MiniMax `<think>` blocks, token metadata, and export actions
-- shows dashboard and analytics summaries, including Codex token totals and tool-call frequency
+- shows dashboard and project-scoped Codex analytics for token totals, average and median thread size, archive counts, tool usage, model tokens, client sources, and reasoning effort
 - keeps Codex inventory search and analytics project filters in URL search params for reloadable and shareable views
 - keeps source-specific commentary hidden by default while preserving final answers, with matching export filtering for Claude Code, Kiro, Qoder, and OpenCode
 
 ## Commands
 
 ```bash
-rtk bun run dev
+rtk bun start
 rtk bun run build
-rtk bun run test
+rtk bun run test:ui
 rtk bun run typecheck
 ```
 
 ## Runtime Note
 
-This package runs `vite` through `bun --bun ...`.
+Run these commands from the repository root. The UI is part of the root package and intentionally has no nested package manifest.
 
-That is required because the TanStack Start server functions import shared root-package modules that use Bun-only features such as `bun:sqlite`.
+Root-owned Vite commands use `apps/ui` as their internal working directory and run through `bun --bun`. That is required because TanStack Start derives part of its server plan from the application directory and the server functions use Bun-only modules such as `bun:sqlite`.
 
-If you change the scripts back to plain `vite` or a Node execution path, the UI server functions will fail at runtime.
+Vitest uses its normal Node runtime.
 
 ## Configuration
 
@@ -67,9 +70,17 @@ Runtime configuration is intentionally small:
 - `SPIRACHA_ANALYTICS_TRANSCRIPT_CONCURRENCY`
   - Optional positive integer for Codex analytics transcript parsing concurrency.
   - Defaults to `8`.
+- `SPIRACHA_TRANSCRIPT_LOAD_CONCURRENCY`
+  - Optional positive integer for detail-page transcript loading concurrency across sources.
+  - Defaults to `3` and is capped at `16` to protect the server from excessive parallel disk and database work.
+- `SPIRACHA_TRANSCRIPT_LOAD_LOGS`
+  - Set to `1` to log transcript-loader queue and timing diagnostics. Disabled by default so library and CLI consumers stay quiet.
 - `SPIRACHA_CLAUDE_CODE_PROJECTS_DIR`
   - Optional absolute path to the Claude Code projects directory.
   - If unset, Spiracha reads `${SPIRACHA_CLAUDE_CODE_DATA_DIR:-~/.claude}/projects`. `SPIRACHA_CLAUDE_CODE_DIR` and `SPIRACHA_CLAUDE_HOME` are also accepted aliases for the Claude Code data directory.
+- `SPIRACHA_GROK_SESSIONS_DIR`
+  - Optional path to the Grok sessions directory.
+  - If unset, Spiracha reads `${SPIRACHA_GROK_HOME:-~/.grok}/sessions`. `SPIRACHA_GROK_DIR` is accepted as a Grok home-directory alias.
 - `SPIRACHA_KIRO_WORKSPACE_SESSIONS_DIR`
   - Optional absolute path to the Kiro workspace sessions directory.
   - If unset, Spiracha reads `${SPIRACHA_KIRO_DATA_DIR:-~/Library/Application Support/Kiro/User/globalStorage/kiro.kiroagent}/workspace-sessions`. `SPIRACHA_KIRO_AGENT_DIR` and `SPIRACHA_KIRO_DIR` are also accepted aliases for the Kiro data directory.
@@ -82,6 +93,11 @@ Runtime configuration is intentionally small:
 - `SPIRACHA_OPENCODE_DB`
   - Optional absolute path to the OpenCode SQLite database.
   - If unset, Spiracha reads `${SPIRACHA_OPENCODE_DATA_DIR:-${XDG_DATA_HOME:-~/.local/share}/opencode}/opencode.db`. `SPIRACHA_OPENCODE_DIR` is also accepted as an OpenCode data-directory alias.
+- `SPIRACHA_OPENCODE_DB_CONCURRENCY`
+  - Optional positive integer for concurrent OpenCode database reads.
+  - Defaults to `2`.
+- `SPIRACHA_OPENCODE_DB_LOGS`
+  - Set to `1` to log OpenCode database queue and timing diagnostics. Disabled by default.
 - `SPIRACHA_CURSOR_USER_DIR`
   - Optional absolute path to Cursor's `User` directory.
   - If unset, Spiracha reads the platform default Cursor user-data directory.
@@ -100,6 +116,7 @@ Default source locations:
 | --- | --- | --- |
 | Codex | shared Codex DB probe list | `SPIRACHA_CODEX_DB` |
 | Claude Code | `~/.claude/projects` | `SPIRACHA_CLAUDE_CODE_PROJECTS_DIR` |
+| Grok | `~/.grok/sessions` | `SPIRACHA_GROK_SESSIONS_DIR`, `SPIRACHA_GROK_HOME` |
 | Kiro | `~/Library/Application Support/Kiro/User/globalStorage/kiro.kiroagent/workspace-sessions` | `SPIRACHA_KIRO_WORKSPACE_SESSIONS_DIR` |
 | Qoder | `~/Library/Application Support/Qoder/User/globalStorage/state.vscdb` + `~/Library/Application Support/Qoder/User/workspaceStorage` | `SPIRACHA_QODER_GLOBAL_STATE_DB`, `SPIRACHA_QODER_WORKSPACE_STORAGE_DIR` |
 | Cursor | `~/Library/Application Support/Cursor/User` on macOS | `SPIRACHA_CURSOR_USER_DIR`, `SPIRACHA_CURSOR_PROJECTS_DIR` |
@@ -109,6 +126,8 @@ Default source locations:
 
 Codex analytics cache keys are based on Codex DB row metadata instead of statting every rollout file before cache hits. That keeps large histories responsive. The tradeoff is that manual JSONL edits outside Codex do not invalidate analytics unless DB row metadata changes or the temporary UI cache is cleared.
 
+The temporary UI cache is pruned opportunistically at read/write boundaries, with cleanup scans throttled to once per minute. Entries expire after 24 hours and the retained cache is capped at 256 MiB; recently accessed entries refresh their age so hot data survives eviction.
+
 Transcript detail pages expose the same display controls across sources: user messages, commentary, tool calls, extra events, and raw JSON. Claude Code assistant lead-ins are classified from `stop_reason`, Kiro assistant phases are classified per user turn from session and execution files, Qoder shows local prompt history plus checkpoint file operations, and OpenCode assistant phases are classified per assistant run after stripping MiniMax `<think>` blocks into commentary. OpenCode think-tag extraction preserves literal `<think>` examples inside Markdown code spans and fenced code blocks.
 
 ## Routes
@@ -125,6 +144,12 @@ Transcript detail pages expose the same display controls across sources: user me
   - Claude Code workspace session listing
 - `/claude-code-sessions/$sessionId`
   - Claude Code session detail and export
+- `/grok`
+  - Grok workspace inventory and search
+- `/grok/$workspaceKey`
+  - Grok workspace session listing
+- `/grok-sessions/$sessionId`
+  - Grok session detail, export, and delete
 - `/kiro`
   - Kiro workspace inventory and search
 - `/kiro/$workspaceKey`
@@ -160,11 +185,11 @@ Transcript detail pages expose the same display controls across sources: user me
 - `/$threadId`
   - shortcut redirect to the thread detail page for pasted Codex thread UUIDs
 - `/analytics`
-  - Codex token and tool-call analytics, with `project` as the route search param
+  - project-scoped Codex token, archive, tool, model, client-source, and reasoning-effort analytics, with `project` as the route search param
 
 ## Testing
 
 - UI component tests live under `src/**/*.vitest.tsx`.
 - Source-specific transcript event adapter tests live under `src/lib/*.vitest.ts`.
 - Route search parsing tests live in `src/lib/route-search.vitest.ts`.
-- The repo root wraps this Vitest suite from `src/ui-package.test.ts`, so `rtk bun test` at the root covers both the Bun tests and the UI tests.
+- The repo root wraps this Vitest suite from `src/ui-suite.test.ts`, so `rtk bun test` at the root covers both the Bun tests and the UI tests.

package/apps/ui/src/components/analytics-breakdowns.tsx

@@ -0,0 +1,106 @@
+import type {
+    CodexAnalytics,
+    DistributionItem,
+    ModelTokenSummary,
+    ToolUsageSummary,
+} from '@spiracha/lib/codex-browser-types';
+import { createColumnHelper } from '@tanstack/react-table';
+import { formatNumber, formatTokens } from '#/lib/formatters';
+import { DataTable } from './data-table';
+
+const toolUsageColumnHelper = createColumnHelper<ToolUsageSummary>();
+const toolUsageColumns = [
+    toolUsageColumnHelper.accessor('name', {
+        cell: (info) => <span className="font-mono text-sm">{info.getValue()}</span>,
+        header: 'Tool',
+    }),
+    toolUsageColumnHelper.accessor('count', {
+        cell: (info) => <span className="font-mono text-sm">{formatNumber(info.getValue())}</span>,
+        header: 'Calls',
+    }),
+] as const;
+
+const modelColumnHelper = createColumnHelper<ModelTokenSummary>();
+const modelColumns = [
+    modelColumnHelper.accessor('model', {
+        cell: (info) => <span className="font-mono text-sm">{info.getValue()}</span>,
+        header: 'Model',
+    }),
+    modelColumnHelper.accessor('threadCount', {
+        cell: (info) => <span className="font-mono text-sm">{formatNumber(info.getValue())}</span>,
+        header: 'Threads',
+    }),
+    modelColumnHelper.accessor('totalTokens', {
+        cell: (info) => <span className="font-mono text-sm">{formatTokens(info.getValue())}</span>,
+        header: 'Tokens',
+    }),
+] as const;
+
+const distributionColumnHelper = createColumnHelper<DistributionItem>();
+const distributionColumns = [
+    distributionColumnHelper.accessor('label', {
+        cell: (info) => <span className="font-mono text-sm">{info.getValue()}</span>,
+        header: 'Value',
+    }),
+    distributionColumnHelper.accessor('count', {
+        cell: (info) => <span className="font-mono text-sm">{formatNumber(info.getValue())}</span>,
+        header: 'Threads',
+    }),
+] as const;
+
+type AnalyticsBreakdownsProps = Pick<CodexAnalytics, 'modelsByTokens' | 'reasoningEfforts' | 'sources' | 'toolUsage'>;
+
+export const AnalyticsBreakdowns = ({
+    modelsByTokens,
+    reasoningEfforts,
+    sources,
+    toolUsage,
+}: AnalyticsBreakdownsProps) => {
+    return (
+        <div className="grid gap-6 xl:grid-cols-2">
+            <section className="space-y-4">
+                <div>
+                    <h3 className="font-semibold text-sm">Most frequent tool calls</h3>
+                    <p className="mt-1 text-[var(--muted-foreground)] text-sm">
+                        Useful for future prompt and tool optimization work.
+                    </p>
+                </div>
+                <DataTable columns={toolUsageColumns} data={toolUsage} emptyMessage="No tool calls recorded." />
+            </section>
+
+            <section className="space-y-4">
+                <div>
+                    <h3 className="font-semibold text-sm">Model token breakdown</h3>
+                    <p className="mt-1 text-[var(--muted-foreground)] text-sm">
+                        Compare model usage and token concentration within the current project scope.
+                    </p>
+                </div>
+                <DataTable columns={modelColumns} data={modelsByTokens} emptyMessage="No model usage recorded." />
+            </section>
+
+            <section className="space-y-4">
+                <div>
+                    <h3 className="font-semibold text-sm">Client source breakdown</h3>
+                    <p className="mt-1 text-[var(--muted-foreground)] text-sm">
+                        See which Codex clients created threads in the current scope.
+                    </p>
+                </div>
+                <DataTable columns={distributionColumns} data={sources} emptyMessage="No client sources recorded." />
+            </section>
+
+            <section className="space-y-4">
+                <div>
+                    <h3 className="font-semibold text-sm">Reasoning effort breakdown</h3>
+                    <p className="mt-1 text-[var(--muted-foreground)] text-sm">
+                        Compare configured reasoning effort across threads.
+                    </p>
+                </div>
+                <DataTable
+                    columns={distributionColumns}
+                    data={reasoningEfforts}
+                    emptyMessage="No reasoning effort recorded."
+                />
+            </section>
+        </div>
+    );
+};