spiracha 1.5.0 → 2.1.0

package/README.md

@@ -4,331 +4,156 @@
   <img src="apps/ui/public/icon.svg" alt="Spiracha icon" width="96" height="100">
 </p>
 
-[![npm version](https://img.shields.io/npm/v/spiracha?label=npm)](https://www.npmjs.com/package/spiracha)
-[![downloads](https://img.shields.io/npm/dm/spiracha?label=downloads)](https://www.npmjs.com/package/spiracha)
 [![license](https://img.shields.io/npm/l/spiracha)](LICENSE.md)
 [![runtime](https://img.shields.io/badge/runtime-Bun-000000?logo=bun)](https://bun.sh)
-[![wakatime](https://wakatime.com/badge/user/a0b906ce-b8e7-4463-8bce-383238df6d4b/project/f035d5e2-fa44-4383-913b-53c2c326d8a7.svg)](https://wakatime.com/badge/user/a0b906ce-b8e7-4463-8bce-383238df6d4b/project/f035d5e2-fa44-4383-913b-53c2c326d8a7)
 
-Export local Codex, Claude Code, and Cursor transcripts to Markdown or plain text, and inspect or export Codex, Claude Code, Kiro, Cursor, Antigravity, and OpenCode history through a browser UI.
+Spiracha is a local TanStack Start app 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.
 
 ## Quick Start
 
-For repo-local development:
+To run the packaged app:
 
 ```bash
-rtk bun start
-rtk bun run ui:dev
+bunx spiracha
 ```
 
-Published package usage, once the package is available on npm:
-
-```bash
-rtk bunx spiracha
-rtk bunx spiracha ui
-rtk bunx spiracha claude /path/to/session-export.jsonl --output-format txt
-rtk bunx spiracha cursor list
-```
+Spiracha asks Vite for port 3000 and automatically uses the next available port when 3000 is occupied.
 
-## Features
-
-- Export Codex session transcripts from local `.codex` history
-- Export Cursor Agent/Composer threads from local Cursor storage
-- Browse Codex, Claude Code, Kiro, Cursor, Antigravity, and OpenCode history in a TanStack Start UI
-- Inspect Codex thread timelines, tool calls, thread metadata, and raw event context
-- Inspect Claude Code project workspaces, dedicated session detail pages, reasoning/tool calls, token metadata, and export sessions directly from local `~/.claude/projects` JSONL files
-- Inspect Kiro workspace inventories, dedicated session detail pages, image attachments, prompt logs, execution-derived tool calls, and export sessions
-- Inspect Cursor workspace inventories, dedicated thread detail pages, recover split storage buckets, and export or delete workspace threads
-- Inspect Antigravity workspaces, dedicated conversation detail pages, unlock transcript export through macOS Keychain, and export conversation transcripts or generated artifacts
-- Inspect OpenCode project workspaces, dedicated session detail pages, reasoning/tool parts, MiniMax `<think>` blocks, token metadata, and export sessions
-- Delete threads or derived projects from the Codex SQLite database after confirmation
-- Download thread exports directly from the UI as Markdown, plain text, or optional zip archives, with optional metadata, commentary, and tool-call inclusion
-- Keep source-specific assistant commentary hidden by default while still showing final answers, with matching export filtering for Claude Code, Kiro, and OpenCode
-- View dashboard and analytics summaries, including token totals and tool-call frequency
-- Filter Codex exports by:
-  - exact `cwd`
-  - project basename via `--project`
-  - specific thread deeplinks like `codex://threads/<id>`
-- Include command logs with `--tools`
-- Write Markdown or real plain-text output with `--output-format md|txt`
-- Export Claude Code transcript `.jsonl` files or export directories
-- Export, recover, and prune Cursor chat history from the CLI
-- Run the same export flows through an MCP server and a local Codex plugin
-
-## Install
+For repository development:
 
 ```bash
 rtk bun install
+rtk bun start
 ```
 
-For package use after publish, no local install is required:
+Open the local URL printed by Vite.
 
-```bash
-rtk bunx spiracha --help
-rtk bunx spiracha ui --help
-```
+## What It Does
 
-## Usage
+- 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.
+- 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.
 
-### Codex exports
+## Stable Data API
 
-Package entrypoint:
+The API is served by the local UI server under `/api/v1`.
 
 ```bash
-rtk bunx spiracha [options] [codex://threads/<id> ...]
-rtk bunx spiracha codex [options] [codex://threads/<id> ...]
+bunx spiracha
 ```
 
-With no arguments, `spiracha` starts in interactive mode and asks what you want to export.
-
-Examples:
+Common read endpoints:
 
-```bash
-rtk bunx spiracha
-rtk bunx spiracha --interactive
-rtk bunx spiracha --project summer
-rtk bunx spiracha --tools --project summer
-rtk bunx spiracha codex://threads/019da28f-ee5b-7881-afe0-68b3d3bd2c77
-rtk bunx spiracha codex://threads/019da28f-ee5b-7881-afe0-68b3d3bd2c77 --output-format txt
-rtk bunx spiracha --cwd ~/workspace/reversed/summer --flat
-rtk bunx spiracha codex://threads/<thread-id> --no-metadata
+```text
+GET  /api/v1/sources
+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>
 ```
 
-Important flags:
-- no args: start interactive mode
-- `--interactive`: force the interactive prompt flow
-- `--project <name>`: matches the final `cwd` path segment for both POSIX and Windows-style paths
-- `--cwd <path>`: exact cwd match
-- `--tools`: include `exec_command` call logs and summaries
-- `--no-metadata`: omit the metadata section from the top of each export
-- `--flat`: write files into a single output folder
-- `--output-format md|txt`: output as Markdown or plain text
+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.
 
-### Browser UI
+Example:
 
 ```bash
-rtk bunx spiracha ui
+curl 'http://localhost:3000/api/v1/conversations?cwd=/Users/me/workspace/fgh&include_messages=true'
 ```
 
-This launches the packaged production UI server, opens your browser by default, and keeps running in the foreground.
-Large download bundles are written to a Spiracha-managed directory under your OS temp folder and served directly by the UI server, so packaged `rtk bunx spiracha ui` exports do not depend on your current working directory.
+Response envelope:
 
-Useful flags:
-- `--port <port>`: bind a specific port, default `3000`
-- `--host <host>`: bind a specific host, default `127.0.0.1`
-- `--db <path>`: override the Codex SQLite path used by the UI
-- `--no-open`: do not open the browser automatically
+```json
+{
+  "data": [
+    {
+      "source": "codex",
+      "id": "019ecbfc-8a84-7421-ab3b-35653feb7896",
+      "title": "Review thread",
+      "workspacePath": "/Users/me/workspace/fgh",
+      "messages": [
+        {
+          "role": "assistant",
+          "phase": "final_answer",
+          "text": "Final review result..."
+        }
+      ],
+      "deepLinks": {
+        "ui": "/threads/019ecbfc-8a84-7421-ab3b-35653feb7896",
+        "native": "codex://threads/019ecbfc-8a84-7421-ab3b-35653feb7896",
+        "spiracha": "spiracha://conversation/codex/019ecbfc-8a84-7421-ab3b-35653feb7896"
+      }
+    }
+  ],
+  "meta": {
+    "hasNext": false,
+    "next_cursor": null
+  }
+}
+```
 
-The UI currently includes:
-- a Codex inventory and derived-project detail flow
-- a Claude Code workspace inventory, workspace-session listing, and standalone session detail flow
-- a Kiro workspace inventory, workspace-session listing, and standalone session detail flow
-- a Cursor workspace inventory, workspace-thread listing, and standalone thread detail flow
-- an Antigravity workspace inventory, conversation listing, and standalone conversation detail flow
-- an OpenCode workspace inventory, session listing, and standalone session detail flow
-- a Codex dashboard, Codex thread detail view, and Codex analytics page
+For serverless access from Bun, use the public client export:
 
-Transcript detail pages use the same compact controls across sources: show or hide user messages, commentary, tool calls, extra events, and raw JSON. Claude Code uses `stop_reason` to distinguish tool-use lead-ins from final answers. Kiro uses execution traces for assistant commentary/tool calls and keeps the final assistant response for each user turn visible. OpenCode strips MiniMax `<think>` blocks into commentary, preserves literal `<think>` examples inside Markdown code, and uses the final visible assistant text in each assistant run as the final answer.
+```ts
+import { createConversationClient } from "spiracha/client";
+
+const client = createConversationClient({ mode: "local" });
+const page = await client.listConversations({
+  cwd: process.cwd(),
+  includeMessages: true,
+  messageSelector: "last_final_answer",
+});
+```
 
-Default browser UI data locations:
+## 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` |
 | 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` |
+| Antigravity | `~/.gemini/antigravity-ide` and `~/.gemini/antigravity` | `SPIRACHA_ANTIGRAVITY_DIRS`, `SPIRACHA_ANTIGRAVITY_DIR` |
 | OpenCode | `${XDG_DATA_HOME:-~/.local/share}/opencode/opencode.db` | `SPIRACHA_OPENCODE_DB` |
-| Export downloads | OS temp directory under `spiracha-ui-exports` | `SPIRACHA_UI_EXPORT_DIR` |
-
-Codex inventory search and analytics project filters are stored in route search params, so filtered views can be bookmarked or reloaded. `/projects` and `/projects/$project` use `q`, and `/analytics` uses `project`.
-
-Analytics cache keys are derived from Codex DB row metadata instead of statting every rollout file. This avoids large per-rollout stat storms on big histories and lets cached analytics resolve without touching transcript files. The hard tradeoff is that manual JSONL edits outside Codex do not invalidate analytics unless the corresponding DB row metadata changes or the temp UI cache is cleared. Transcript analytics parsing uses a bounded worker pool; tune it with `SPIRACHA_ANALYTICS_TRANSCRIPT_CONCURRENCY` when benchmarking large datasets.
-
-The thread detail page also supports a direct UUID shortcut route. Pasting `http://localhost:3000/<thread-id>` redirects to `/threads/<thread-id>`.
-
-Notable UI routes:
-- `/projects` and `/projects/$project` for Codex inventory and project threads
-- `/threads/$threadId` for Codex thread detail
-- `/claude-code` and `/claude-code/$workspaceKey` for Claude Code workspace inventory and session lists
-- `/claude-code-sessions/$sessionId` for Claude Code session detail
-- `/kiro` and `/kiro/$workspaceKey` for Kiro workspace inventory and session lists
-- `/kiro-sessions/$sessionId` for Kiro session detail
-- `/cursor` and `/cursor/$workspaceKey` for Cursor workspace inventory and thread lists
-- `/cursor-threads/$composerId` for Cursor thread detail
-- `/antigravity` and `/antigravity/$workspaceKey` for Antigravity workspace inventory and conversation lists
-- `/antigravity-conversations/$conversationId` for Antigravity conversation detail
-- `/opencode` and `/opencode/$workspaceKey` for OpenCode workspace inventory and session lists
-- `/opencode-sessions/$sessionId` for OpenCode session detail
+| UI exports | OS temp directory under `spiracha-ui-exports` | `SPIRACHA_UI_EXPORT_DIR` |
 
-Examples:
+## UI Routes
 
-```bash
-rtk bunx spiracha ui
-rtk bunx spiracha ui --port 43123 --no-open
-rtk bunx spiracha ui --db ~/.codex/state_5.sqlite
-```
-
-Stop the UI with `Ctrl+C`.
-
-### Claude exports
-
-```bash
-rtk bunx spiracha claude <input-path> [options]
-```
-
-Examples:
-
-```bash
-rtk bunx spiracha claude /path/to/session.jsonl
-rtk bunx spiracha claude /path/to/export-dir --tools
-rtk bunx spiracha claude /path/to/export-dir --output-format txt
-```
-
-Repo-local equivalents remain available during development:
-
-```bash
-rtk bun start
-rtk bun start --interactive
-rtk bun start ...
-rtk bun run export:claude -- ...
-```
-
-Legacy aliases remain available for compatibility:
-
-```bash
-rtk bunx codex-chats
-rtk bunx codex-chats-claude
-```
-
-### Cursor exports
-
-```bash
-rtk bunx spiracha cursor <subcommand> [options]
-```
-
-Examples:
-
-```bash
-rtk bunx spiracha cursor list
-rtk bunx spiracha cursor list --query summer
-rtk bunx spiracha cursor export --workspace summer --output-dir ./cursor-exports
-rtk bunx spiracha cursor export --thread <composer-id> --output-format txt
-rtk bunx spiracha cursor recover --workspace summer --apply
-rtk bunx spiracha cursor prune --workspace summer --apply
-```
-
-Repo-local equivalent during development:
-
-```bash
-rtk bun run ./src/export-cursor.ts --help
-```
-
-Claude Code direct-history browsing, Kiro browsing/export, Antigravity, and OpenCode conversation browsing/export currently live in the browser UI rather than standalone CLI subcommands.
-
-## MCP server
-
-Run the MCP server with:
-
-```bash
-rtk bun run mcp
-```
-
-Exposed tools:
-- `export_codex_chats`
-- `export_claude_transcript`
-
-The local plugin lives in [plugins/codex-chats-export](plugins/codex-chats-export) and is registered through [plugins/codex-chats-export/.mcp.json](plugins/codex-chats-export/.mcp.json).
+- `/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.
 
 ## Development
 
-Useful commands:
-
 ```bash
 rtk bun test
 rtk bun run lint
 rtk bun run typecheck
 rtk bun run build
 rtk bun run coverage
-rtk bun run ui:dev
-rtk bun run --cwd apps/ui test
-rtk bun run test:perf
 rtk bun start
-rtk bun start --interactive
-rtk bun start -- --help
-rtk bun run export:claude -- --help
-rtk bun run mcp
-```
-
-Packed-tarball smoke test before publishing:
-
-```bash
-rtk bun pm pack
-package_tgz="$PWD/spiracha-<version>.tgz"
-tmp_dir=$(mktemp -d)
-cd "$tmp_dir"
-printf '{"name":"codex-chats-smoke","private":true}\n' > package.json
-rtk bun add "$package_tgz"
-rtk bunx --package "$package_tgz" spiracha --help
-rtk bunx --package "$package_tgz" spiracha ui --help
-rtk bunx --package "$package_tgz" spiracha claude --help
-rtk bunx --package "$package_tgz" codex-chats --help
-rtk bunx --package "$package_tgz" codex-chats-claude --help
+rtk bun run --cwd apps/ui test
 ```
 
-For the exact packaged UI launch path, run:
-
-```bash
-rtk bun run smoke:package-ui
-```
+The UI package runs Vite through `bun --bun` because server functions import Bun-only modules such as `bun:sqlite`.
 
-This builds the app, packs a fresh tarball in a clean temp directory, launches `rtk bunx --package <tgz> spiracha ui --no-open`, probes the running UI for real SSR HTML, rejects Bun fallback responses, and shuts it down. The same packaged-path smoke is also covered by `src/package-ui-smoke.test.ts`.
-
-## Project Layout
-
-- `apps/ui/`: TanStack Start browser app for Codex, Claude Code, Kiro, Cursor, Antigravity, and OpenCode browsing plus export and delete flows
-- `src/export-chats.ts`: Codex CLI wrapper
-- `src/export-claude.ts`: Claude CLI wrapper
-- `src/export-cursor.ts`: Cursor CLI wrapper
-- `src/mcp-server.ts`: MCP server entrypoint
-- `src/lib/antigravity-*.ts`: Antigravity workspace discovery, transcript rendering, and Keychain helpers
-- `src/lib/codex-exporter-*.ts`: Codex exporter modules
-- `src/lib/codex-browser-*.ts`: shared browser/UI data, analytics, and export helpers
-- `src/lib/codex-thread-*.ts`: structured transcript parsing and caching helpers
-- `src/lib/concurrency.ts`: shared bounded-concurrency helper for large transcript and DB workloads
-- `src/lib/claude-code-*.ts`: Claude Code local project/session discovery, assistant phase classification, and transcript rendering helpers
-- `src/lib/kiro-*.ts`: Kiro workspace/session discovery, execution-trace enrichment, assistant phase classification, and transcript rendering helpers
-- `src/lib/claude-exporter.ts`: Claude exporter implementation
-- `src/lib/cursor-*.ts`: Cursor discovery, transcript rendering, recovery, and CLI helpers
-- `src/lib/opencode-*.ts`: OpenCode project/session discovery, MiniMax think-tag handling, assistant phase classification, and transcript rendering helpers
-- `src/lib/ui-export-archive.ts` and `src/lib/ui-export-files.ts`: browser download filename, MIME type, zip archive, temp file, and URL helpers
-- `plugins/codex-chats-export/`: local Codex plugin bundle
-
-## Testing
-
-The test suite includes:
-- Codex exporter end-to-end coverage
-- Claude exporter end-to-end coverage
-- Claude Code direct-history discovery and export coverage
-- Kiro workspace session discovery and export coverage
-- source-specific assistant commentary/final-answer classification and export filtering coverage
-- Cursor exporter and recovery coverage
-- Antigravity discovery and export coverage
-- OpenCode discovery and export coverage
-- OpenCode MiniMax `<think>` extraction coverage, including literal tags in Markdown code
-- Codex CLI helper tests
-- transcript rendering helper tests
-- route search parsing and bounded concurrency tests
-- MCP stdio protocol round-trip tests
-- local packaging should be smoke-tested with a packed tarball before publishing
-- packaged source manifests are checked for UI server helper files used at runtime
-
-Coverage enforcement:
-- `rtk bun run coverage:root` checks the root Bun unit-test surface at a minimum of 90% line coverage.
-- `rtk bun run coverage:ui` checks the UI unit-test surface at a minimum of 90% line coverage.
-- `rtk bun run coverage` runs both checks.
-
-Run:
+## Breaking Consequences
 
-```bash
-rtk bun test
-```
+- The only published `bin` entry is `spiracha`, and it only launches the local UI server.
+- No `codex-chats`, `codex-chats-claude`, or legacy export command remains.
+- No repo-local CLI export flow remains.
+- No standalone Claude or Cursor export CLI remains.
+- No MCP server or local Codex plugin remains.
+- Programmatic consumers should call the stable local HTTP API or import `spiracha/client` from Bun.

package/apps/ui/AGENTS.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-This package is the local browser UI for Spiracha. It reads Codex, Claude Code, Kiro, Cursor, Antigravity, and OpenCode local data through TanStack Start server functions and shared root-package helpers.
+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.
 
 ## Commands
 
@@ -17,22 +17,24 @@ rtk bun run coverage
 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`.
-- Keep TanStack/React runtime dependency versions aligned with the root package when both manifests list the same package. Version drift can break packaged server-function manifests in production.
+- 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.
 
 ## Routing
 
 - This package uses TanStack Start with file-based routes in `src/routes/`.
 - `src/routeTree.gen.ts` is generated. Do not edit it manually.
 - If route typing behaves strangely, delete `src/routeTree.gen.ts` and rebuild with `rtk bun run build` to regenerate it cleanly.
+- Stable API routes live in `src/routes/api.v1.*.ts` and should stay thin wrappers around `@spiracha/lib/conversation-api`.
 - The UI supports both `/threads/$threadId` and a root shortcut route `/$threadId` that redirects straight to the thread detail page.
-- Codex project inventory and project-thread search use route search params. `/projects` and `/projects/$project` use `q`.
+- 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`.
 - 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, 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, 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
 
@@ -49,6 +51,9 @@ The UI depends on root-package helpers via `@spiracha/*` path aliases:
 - `@spiracha/lib/kiro-db`
 - `@spiracha/lib/kiro-transcript-phase`
 - `@spiracha/lib/kiro-transcript`
+- `@spiracha/lib/qoder-db`
+- `@spiracha/lib/qoder-transcript-phase`
+- `@spiracha/lib/qoder-transcript`
 - `@spiracha/lib/cursor-db`
 - `@spiracha/lib/cursor-recovery`
 - `@spiracha/lib/cursor-transcript`
@@ -58,6 +63,8 @@ The UI depends on root-package helpers via `@spiracha/*` path aliases:
 - `@spiracha/lib/opencode-transcript-phase`
 - `@spiracha/lib/opencode-think-tags`
 - `@spiracha/lib/opencode-transcript`
+- `@spiracha/lib/conversation-api`
+- `@spiracha/lib/conversation-data`
 
 Keep server-only imports inside server functions or route loaders. Do not import Bun-only modules into purely client-side components.
 The `*-transcript-phase` helpers are intentionally browser-safe and may be imported by client adapters.
@@ -66,15 +73,18 @@ 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/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/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/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/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, CLI, and packaged launcher.
+  - Extend these when the behavior should stay shared between the UI and the stable data API.
   - Use the shared source-specific phase helpers for assistant commentary/final-answer rules instead of duplicating that logic in UI adapters.
   - Keep OpenCode think-tag handling in `@spiracha/lib/opencode-think-tags` so UI display and exports strip MiniMax reasoning tags consistently.
+- Stable API route handlers in `src/routes/api.v1.*.ts`
+  - Use route-level `server.handlers`.
+  - Delegate to `@spiracha/lib/conversation-api` instead of duplicating parsing or response-envelope logic.
 - `src/lib/source-session-export-server.ts`
   - Use for single-session source exports that may return either inline content or a temporary zip download URL.
 - `settings-store.tsx`

package/apps/ui/README.md

@@ -1,6 +1,6 @@
 # Spiracha UI
 
-The browser UI for browsing local Codex, Claude Code, Kiro, 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
 
@@ -18,11 +18,15 @@ The browser UI for browsing local Codex, Claude Code, Kiro, Cursor, Antigravity,
 - 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, Cursor, and OpenCode sessions or threads as Markdown, plain text, or optional zip archives with optional metadata, commentary, and tool-call inclusion
+- 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
 - 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
+- shows dedicated Qoder session detail pages with prompts, checkpoint file operations, metadata, and export actions
 - lists Cursor workspaces and workspace threads with the same table-based index/detail flow as Codex
 - shows dedicated Cursor thread detail pages with breadcrumbs back to the workspace and source
 - recovers split Cursor storage buckets, exports Cursor threads, and deletes Cursor workspaces or threads
@@ -33,7 +37,7 @@ The browser UI for browsing local Codex, Claude Code, Kiro, Cursor, Antigravity,
 - 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
 - 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, and OpenCode
+- keeps source-specific commentary hidden by default while preserving final answers, with matching export filtering for Claude Code, Kiro, Qoder, and OpenCode
 
 ## Commands
 
@@ -65,17 +69,41 @@ 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_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.
+- `SPIRACHA_QODER_GLOBAL_STATE_DB`
+  - Optional absolute path to Qoder's global `state.vscdb`.
+  - If unset, Spiracha reads `${SPIRACHA_QODER_USER_DIR:-~/Library/Application Support/Qoder/User}/globalStorage/state.vscdb`. `SPIRACHA_QODER_DATA_DIR` and `SPIRACHA_QODER_DIR` are also accepted aliases for the Qoder user directory.
+- `SPIRACHA_QODER_WORKSPACE_STORAGE_DIR`
+  - Optional absolute path to Qoder's `workspaceStorage` directory.
+  - If unset, Spiracha reads `${SPIRACHA_QODER_USER_DIR:-~/Library/Application Support/Qoder/User}/workspaceStorage`.
 - `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.
-
-Export artifacts are served through the UI as attachment downloads from `/__exports/*`. The packaged `spiracha ui` launcher and the local dev server both use the same export-directory contract.
+- `SPIRACHA_OPENCODE_DB_CONCURRENCY`
+  - Optional positive integer for concurrent OpenCode database reads.
+  - Defaults to `2`.
+- `SPIRACHA_CURSOR_USER_DIR`
+  - Optional absolute path to Cursor's `User` directory.
+  - If unset, Spiracha reads the platform default Cursor user-data directory.
+- `SPIRACHA_CURSOR_PROJECTS_DIR`
+  - Optional absolute path to Cursor's project transcript directory.
+  - If unset, Spiracha infers `.cursor/projects` from the Cursor user directory when possible.
+- `SPIRACHA_ANTIGRAVITY_DIRS`
+  - Optional path-list of Antigravity roots.
+  - If unset, Spiracha reads `~/.gemini/antigravity-ide` and `~/.gemini/antigravity`. `SPIRACHA_ANTIGRAVITY_DIR` is accepted as a single-root alias.
+
+Export artifacts are served through the UI as attachment downloads from `/__exports/*`. The local dev and preview servers use the same export-directory contract.
 
 Default source locations:
 
@@ -83,21 +111,25 @@ 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` |
+| Antigravity | `~/.gemini/antigravity-ide` + `~/.gemini/antigravity` | `SPIRACHA_ANTIGRAVITY_DIRS`, `SPIRACHA_ANTIGRAVITY_DIR` |
 | OpenCode | `${XDG_DATA_HOME:-~/.local/share}/opencode/opencode.db` | `SPIRACHA_OPENCODE_DB` |
 | Export downloads | OS temp directory under `spiracha-ui-exports` | `SPIRACHA_UI_EXPORT_DIR` |
 
 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.
 
-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, 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.
+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
 
 - `/`
   - dashboard
-- `/projects`
+- `/codex`
   - Codex inventory and search, with `q` as the route search param
-- `/projects/$project`
+- `/codex/$project`
   - Codex project thread listing, with `q` as the route search param
 - `/claude-code`
   - Claude Code workspace inventory and search
@@ -105,12 +137,24 @@ 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`
   - Kiro workspace session listing
 - `/kiro-sessions/$sessionId`
   - Kiro session detail and export
+- `/qoder`
+  - Qoder workspace inventory and search
+- `/qoder/$workspaceKey`
+  - Qoder workspace session listing
+- `/qoder-sessions/$sessionId`
+  - Qoder session detail and export
 - `/cursor`
   - Cursor workspace inventory and search
 - `/cursor/$workspaceKey`