@skastr0/quasar-cli-linux-arm64 0.5.2 → 0.5.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +601 -31
  2. package/bin/quasar +0 -0
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,13 +1,40 @@
1
1
  # Quasar CLI
2
2
 
3
- The Quasar CLI discovers, parses, ingests, and queries local AI-agent session
4
- histories.
3
+ The Quasar CLI discovers, parses, normalizes, ingests, queries, and inspects local AI-agent session histories.
5
4
 
6
- The production control surface is the Effect local server with SQLite truth,
7
- durable worker queues, and SQLite FTS search. The npm package ships that
8
- production CLI as a prebuilt Bun standalone binary behind a small Node launcher.
5
+ Quasar interfaces with a local Effect server backed by SQLite as the single source of truth, durable worker queues, trigger-maintained SQLite FTS5 lexical search, and a resident f16 vector matrix scanned via SIMD (simsimd FFI) for semantic and hybrid fusion search. The npm package ships a Node launcher plus prebuilt Bun standalone binaries for macOS and Linux (arm64 and x64).
9
6
 
10
- ## Install
7
+ ---
8
+
9
+ ## Table of Contents
10
+
11
+ - [Installation](#installation)
12
+ - [Configuration & Server Routing](#configuration--server-routing)
13
+ - [Supported Providers (13 Providers)](#supported-providers-13-providers)
14
+ - [CLI Commands (All 24 Commands)](#cli-commands-all-24-commands)
15
+ - [Ingestion & Sync](#ingestion--sync)
16
+ - [Background Daemon (macOS launchd)](#background-daemon-macos-launchd)
17
+ - [Discovery & Status](#discovery--status)
18
+ - [Search & Query Interface](#search--query-interface)
19
+ - [Session & Message Inspection](#session--message-inspection)
20
+ - [Tool Call Forensics](#tool-call-forensics)
21
+ - [Trajectory Export](#trajectory-export)
22
+ - [Research Export](#research-export)
23
+ - [Session Enrichments](#session-enrichments)
24
+ - [Vector Maintenance & Queue Operations](#vector-maintenance--queue-operations)
25
+ - [Schema & Introspection](#schema--introspection)
26
+ - [Interactive Terminal UI (TUI)](#interactive-terminal-ui-tui)
27
+ - [Interactive Terminal UI (TUI) Keymap & Usage](#interactive-terminal-ui-tui-keymap--usage)
28
+ - [Query Spec, Filters & Projections](#query-spec-filters--projections)
29
+ - [JSON Output & Dual Envelope Model](#json-output--dual-envelope-model)
30
+ - [JSON Piping & Automation Recipes](#json-piping--automation-recipes)
31
+ - [Environment Variables Reference](#environment-variables-reference)
32
+
33
+ ---
34
+
35
+ ## Installation
36
+
37
+ Install globally via npm:
11
38
 
12
39
  ```bash
13
40
  npm install -g @skastr0/quasar-cli
@@ -15,32 +42,38 @@ quasar --version
15
42
  quasar --help
16
43
  ```
17
44
 
18
- Ephemeral runner examples:
45
+ Or run ephemerally with your package manager of choice:
19
46
 
20
47
  ```bash
48
+ # npx
21
49
  npx --package @skastr0/quasar-cli quasar --version
50
+
51
+ # bunx
22
52
  bunx -p @skastr0/quasar-cli quasar --version
53
+
54
+ # pnpm dlx
23
55
  pnpm --package @skastr0/quasar-cli dlx quasar --version
24
56
  ```
25
57
 
26
- The npm package ships a Node launcher plus prebuilt Bun standalone binaries for
27
- macOS and Linux on arm64/x64.
58
+ Prebuilt standalone binaries are distributed across native platform packages:
59
+ - `@skastr0/quasar-cli-darwin-arm64` (Apple Silicon)
60
+ - `@skastr0/quasar-cli-darwin-x64` (Intel macOS)
61
+ - `@skastr0/quasar-cli-linux-arm64` (Linux ARM64)
62
+ - `@skastr0/quasar-cli-linux-x64` (Linux x86_64)
28
63
 
29
- ## Connect to a Mac mini Quasar server
64
+ ---
30
65
 
31
- Use the Tailscale Service hostname assigned to `svc:quasar`:
66
+ ## Configuration & Server Routing
32
67
 
33
- ```bash
34
- export QUASAR_SERVER_URL=https://<quasar-service-tailnet-hostname>
35
- export QUASAR_INGEST_TOKEN=<same-token-configured-on-the-mac-mini-server>
68
+ Client commands route to an active Quasar Effect server (local or reached over Tailscale). Configuration is resolved in the following priority:
36
69
 
37
- quasar stats
38
- quasar search --mode fusion --query "quasar local server" --limit 3
39
- quasar ingest --provider all --summary
40
- quasar workers
41
- ```
70
+ 1. Command-line flags (`--server <url>`, `--ingest-token <token>`)
71
+ 2. Environment variables (`QUASAR_SERVER_URL`, `QUASAR_INGEST_TOKEN`)
72
+ 3. Configuration file (`~/.config/quasar/config.json` or path in `QUASAR_CONFIG`)
42
73
 
43
- Or configure the default server once:
74
+ ### Default Configuration File
75
+
76
+ Create `~/.config/quasar/config.json`:
44
77
 
45
78
  ```json
46
79
  {
@@ -51,18 +84,555 @@ Or configure the default server once:
51
84
  }
52
85
  ```
53
86
 
54
- `ingest` reads native local history folders on the machine running the CLI and
55
- POSTs mapped sessions to the configured server. The server owns idempotent SQLite
56
- writes, embedding cache lookup, and search-index queue draining.
57
- Remote ingest requires `ingestToken`, `QUASAR_INGEST_TOKEN`, or
58
- `--ingest-token <token>`; read and search commands do not.
87
+ > [!NOTE]
88
+ > `ingest` and `daemon run` read native local history files on the host running the CLI and stream normalized sessions to the configured server. Remote ingest requires `ingestToken`, `QUASAR_INGEST_TOKEN`, or `--ingest-token <token>`; read and search commands do not require authentication tokens.
89
+
90
+ ---
91
+
92
+ ## Supported Providers (13 Providers)
93
+
94
+ Quasar provides deterministic adapters for 13 AI agent and coding assistant session formats. Adapters normalize heterogeneous source structures into canonical `NormalizedSession` records with full transcript lineage, execution context, usage metrics, and tool calls.
95
+
96
+ | Provider | Adapter ID | Native Storage | Default Root Path | Environment Override |
97
+ |---|---|---|---|---|
98
+ | **Codex** | `codex-local-jsonl` | JSONL session files | `~/.codex` | `QUASAR_CODEX_ROOT` / `CODEX_HOME` |
99
+ | **Claude Code** | `claude-code-local` | JSON session files | `~/.claude` | `QUASAR_CLAUDE_ROOT` / `CLAUDE_HOME` |
100
+ | **OpenCode** | `opencode-local-jsonl` | JSONL sessions | `~/.local/share/opencode` | `QUASAR_OPENCODE_ROOT` / `OPENCODE_HOME` |
101
+ | **Grok** | `grok-local-jsonl` | JSONL sessions | `~/.grok` | `QUASAR_GROK_ROOT` / `GROK_HOME` |
102
+ | **Hermes** | `hermes-local-sqlite` | SQLite database | `~/.hermes` | `QUASAR_HERMES_ROOT` / `HERMES_HOME` |
103
+ | **Kimi** | `kimi-local-json` | JSON session state | `~/.kimi` | `QUASAR_KIMI_ROOT` / `KIMI_HOME` |
104
+ | **Antigravity** | `antigravity-local-json` | JSON artifacts / state | `~/.gemini/antigravity-cli` | `QUASAR_ANTIGRAVITY_ROOT` / `ANTIGRAVITY_HOME` |
105
+ | **OMP** | `omp-local-json` | JSON session tree | `~/.omp` | `QUASAR_OMP_ROOT` / `OMP_HOME` |
106
+ | **Pi** | `pi-local-jsonl` | Append-tree JSONL | `~/.pi` | `QUASAR_PI_ROOT` / `PI_HOME` |
107
+ | **Prime** | `prime-local-json` | JSON session files | `~/.prime` | `QUASAR_PRIME_ROOT` / `PRIME_HOME` |
108
+ | **Cursor** | `cursor-local-sqlite` | SQLite state DB | `~/Library/Application Support/Cursor` | `QUASAR_CURSOR_ROOT` / `CURSOR_HOME` |
109
+ | **Devin** | `devin-local-sqlite` | SQLite session DB | `~/.devin` | `QUASAR_DEVIN_ROOT` / `DEVIN_HOME` |
110
+ | **Amp** | `amp-local-json` | JSON session files | `~/.amp` | `QUASAR_AMP_ROOT` / `AMP_HOME` |
111
+
112
+ ---
113
+
114
+ ## CLI Commands (All 24 Commands)
115
+
116
+ Every command produces structured JSON on `stdout`. Subcommand help is accessible via `quasar <command> --help` or `quasar help <command>`.
117
+
118
+ ### Ingestion & Sync
119
+
120
+ #### 1. `ingest`
121
+ Scans local provider directories, normalizes new and updated sessions, and ingests them into the Quasar server. Utilizes a local stat-manifest (`~/.config/quasar/ingest-manifest.json`) for incremental delta uploads.
122
+
123
+ ```bash
124
+ quasar ingest [--provider <all|codex|claude|opencode|grok|kimi|hermes|antigravity|omp|pi|prime|cursor|devin|amp>] [--server <url>] [--ingest-token <token>] [--limit <n>] [--force] [--summary]
125
+ ```
126
+
127
+ - `--provider <name>`: Target a specific provider or `all` (default: `all`).
128
+ - `--limit <n>`: Maximum number of sessions to scan and process.
129
+ - `--force`: Bypass the stat-manifest and re-evaluate all discovered session files.
130
+ - `--summary`: Output a condensed summary report omitting per-session arrays.
131
+
132
+ #### 2. `ingest-runs`
133
+ Lists recent server ingestion runs, run statuses, processed session counts, and error summaries.
134
+
135
+ ```bash
136
+ quasar ingest-runs [--status <running|completed|failed>] [--limit <n>] [--offset <n>] [--server <url>]
137
+ ```
138
+
139
+ ---
140
+
141
+ ### Background Daemon (macOS launchd)
142
+
143
+ #### 3. `daemon`
144
+ Controls the background remote-ingest daemon via macOS `launchd`. The daemon regularly synchronizes modified local session histories with the Quasar server using non-overlapping file locks.
145
+
146
+ ```bash
147
+ # Install and bootstrap the LaunchAgent plist
148
+ quasar daemon install --server https://<quasar-host> --ingest-token <token> [--interval-seconds <n>] [--binary <path>] [--amp]
149
+
150
+ # Check daemon running state, loaded plist, and lock file status
151
+ quasar daemon status
152
+
153
+ # Remove LaunchAgent and unload from launchd
154
+ quasar daemon uninstall
155
+
156
+ # Execute a single scheduled sync tick (invoked by launchd)
157
+ quasar daemon run
158
+ ```
159
+
160
+ - `--interval-seconds <n>`: Synchronization interval in seconds (minimum: `10`, default: `15` or `60`).
161
+ - `--amp`: Also poll Amp threads from this machine. Off by default because Amp
162
+ threads live only on Amp's servers, so every list and export is a remote
163
+ call; enable it on exactly one machine. When enabled, the daemon walks the
164
+ full thread list once every 20 minutes and exports only threads whose
165
+ fingerprint changed. Nothing is skipped, only delayed by at most one
166
+ interval. The only local state is `amp-poll-state.json` beside the ingest
167
+ manifest: one timestamp. An explicit `quasar ingest --provider amp` ignores
168
+ the throttle and lists right away.
169
+ - `--binary <path>`: Absolute path to the Quasar binary to execute (defaults to current runtime binary).
170
+
171
+ ---
172
+
173
+ ### Discovery & Status
174
+
175
+ #### 4. `stats`
176
+ Fetches server status, active store metrics, total session/message/tool counts, index coverage, and queue depths.
177
+
178
+ ```bash
179
+ quasar stats [--server <url>]
180
+ ```
181
+
182
+ #### 5. `projects`
183
+ Lists distinct projects discovered and normalized across the ingested corpus.
184
+
185
+ ```bash
186
+ quasar projects [--limit <n>] [--offset <n>] [--server <url>]
187
+ ```
188
+
189
+ #### 6. `workers`
190
+ Displays the real-time status of server background workers (durable queue processing, FTS indexers, vector embeddings).
191
+
192
+ ```bash
193
+ quasar workers [--server <url>]
194
+ ```
195
+
196
+ #### 7. `doctor`
197
+ Runs diagnostic checks against the server database, vector matrix index, and provider adapters.
198
+
199
+ ```bash
200
+ quasar doctor [--server <url>]
201
+ ```
202
+
203
+ ---
204
+
205
+ ### Search & Query Interface
206
+
207
+ #### 8. `search`
208
+ Executes lexical (FTS5), semantic (SIMD vector cosine), or hybrid fusion search across indexed conversational messages.
209
+
210
+ ```bash
211
+ quasar search --query <text> [--mode <lexical|semantic|fusion>] [--project <key>] [--provider <name[,name]>] [--role <user|assistant|reasoning>] [--agent <name>] [--agent-role <role>] [--model <slug>] [--model-provider <name>] [--fields <a,b>] [--detail] [--cursor <token>] [--limit <n>] [--server <url>]
212
+ ```
213
+
214
+ - `-q`, `--query <text>`: Free-text search query.
215
+ - `--mode <lexical|semantic|fusion>`: Search retrieval mode (default: `lexical`).
216
+ - `--fields <field1,field2>`: Restrict response items to specific projected fields.
217
+ - `--detail`: Return full detail projection instead of summary projection.
218
+ - `--cursor <token>`: Opaque cursor for deterministic pagination (`page.nextCursor`).
219
+ - `--limit <n>`: Number of results to return (1 to 200, default: server configured).
220
+
221
+ #### 9. `query`
222
+ Executes an arbitrary `QuerySpec` JSON payload against the server query endpoint. Accepts inline JSON, `@filepath`, or `-` for stdin.
223
+
224
+ ```bash
225
+ # Inline JSON
226
+ quasar query '{"protocolVersion":"quasar.query/v1","kind":"search","text":"loss","mode":"fusion","projection":{"detail":"summary","fields":["sessionId","text","score"]},"page":{"limit":5}}'
227
+
228
+ # From file
229
+ quasar query @my-query.json
230
+
231
+ # Piped from stdin
232
+ cat query.json | quasar query -
233
+ ```
234
+
235
+ ---
236
+
237
+ ### Session & Message Inspection
238
+
239
+ #### 10. `sessions`
240
+ Queries and lists ingested session records with optional filtering by project, provider, agent, or model.
241
+
242
+ ```bash
243
+ quasar sessions [--project <key>] [--provider <name[,name]>] [--session <id>] [--agent <name>] [--agent-role <role>] [--model <slug>] [--model-provider <name>] [--fields <a,b>] [--detail] [--cursor <token>] [--limit <n>] [--server <url>]
244
+ ```
245
+
246
+ #### 11. `session`
247
+ Retrieves comprehensive details for a single session, including messages, tool calls, lifecycle events, execution contexts, usage metrics, and artifacts.
248
+
249
+ ```bash
250
+ quasar session --id <sessionId> [--message-limit <n>] [--tool-call-limit <n>] [--event-limit <n>] [--usage-limit <n>] [--edge-limit <n>] [--artifact-limit <n>] [--context-limit <n>] [--server <url>]
251
+ ```
252
+
253
+ - `--id <sessionId>`: Full canonical session identifier (e.g. `codex:uuid`).
254
+
255
+ #### 12. `messages`
256
+ Performs structured cursor-based message scans across the entire corpus or within specific session boundaries.
257
+
258
+ ```bash
259
+ quasar messages [--session <id>] [--project <key>] [--provider <name[,name]>] [--role <user|assistant|reasoning>] [--agent <name>] [--agent-role <role>] [--model <slug>] [--model-provider <name>] [--message-after <iso-ts>] [--message-before <iso-ts>] [--session-started-after <iso-ts>] [--session-started-before <iso-ts>] [--roots-only] [--lineage-root-session <id>] [--fields <a,b>] [--detail] [--cursor <token>] [--limit <n>] [--server <url>]
260
+ ```
261
+
262
+ - `--roots-only`: Return messages only from root sessions (omits child subagents).
263
+ - `--lineage-root-session <id>`: Filter for messages belonging to a root session and its recursive subagent tree.
264
+ - `--message-after` / `--message-before`: Time range bounds for message timestamps.
265
+ - `--session-started-after` / `--session-started-before`: Time range bounds for session creation.
266
+
267
+ ---
268
+
269
+ ### Tool Call Forensics
270
+
271
+ #### 13. `tool-calls`
272
+ Queries and lists tool call invocations across sessions without dumping full argument/result payloads in summary mode.
273
+
274
+ ```bash
275
+ quasar tool-calls [--session <id>] [--project <key>] [--provider <name[,name]>] [--tool <name>] [--agent <name>] [--agent-role <role>] [--model <slug>] [--model-provider <name>] [--fields <a,b>] [--detail] [--cursor <token>] [--limit <n>] [--server <url>]
276
+ ```
277
+
278
+ - `--tool`, `--tool-name <name>`: Filter by tool function name (e.g. `exec_command`, `read_file`).
279
+ - `--tool-call`, `--tool-call-id <id>`: Filter by specific tool call identifier.
280
+
281
+ #### 14. `tool-call`
282
+ Fetches complete, unabridged tool execution forensics (input JSON, output text/JSON, status, timestamps, and error payloads) for a specific tool call ID.
283
+
284
+ ```bash
285
+ quasar tool-call --id <toolCallId> [--fields <a,b>] [--server <url>]
286
+ ```
287
+
288
+ ---
289
+
290
+ ### Trajectory Export
291
+
292
+ #### 15. `trajectory`
293
+ Exports a session trajectory in canonical Quasar format, Letta v1 format, or Harbor ATIF v1.7 format with full loss and compatibility auditing.
294
+
295
+ ```bash
296
+ quasar trajectory --session <id> [--format <quasar|letta|atif>] [--exclude-reasoning] [--exclude-tool-results] [--tool-result-max-bytes <n>] [--server <url>]
297
+ ```
298
+
299
+ - `--session`, `--id <sessionId>`: Session identifier to project.
300
+ - `--format <quasar|letta|atif>`: Target export format (default: `quasar`).
301
+ - `--exclude-reasoning`: Omit thinking/reasoning blocks.
302
+ - `--exclude-tool-results`: Omit tool output content.
303
+ - `--tool-result-max-bytes <n>`: Truncate large tool result payloads to `<n>` bytes with explicit content hashing.
304
+
305
+ ---
306
+
307
+ ### Research Export
308
+
309
+ #### 16. `research-export`
310
+ Streams reproducible, snapshot-bound NDJSON research export frames (manifest, messages, session trajectories, and checksum receipts) to an artifact file.
311
+
312
+ ```bash
313
+ quasar research-export --out <path.ndjson> [--project <key>] [--provider <name[,name]>] [--session <id>] [--role <user|assistant|reasoning>] [--agent <name>] [--agent-role <role>] [--model <slug>] [--model-provider <name>] [--message-after <ts>] [--message-before <ts>] [--session-started-after <ts>] [--session-started-before <ts>] [--roots-only] [--lineage-root-session <id>] [--exclude-reasoning] [--exclude-tool-results] [--tool-result-max-bytes <n>] [--cursor <token>] [--limit <n>] [--server <url>]
314
+ ```
315
+
316
+ - `--out <path>`: Destination path for the generated NDJSON artifact. Fails closed if the file already exists.
317
+ - Generates reproducible dataset shards tied to an immutable database snapshot hash.
318
+
319
+ ---
320
+
321
+ ### Session Enrichments
322
+
323
+ #### 17. `enrichments`
324
+ Lists derived analysis records, summaries, classifications, or thread evaluations attached to sessions.
325
+
326
+ ```bash
327
+ quasar enrichments [--project <key>] [--session <id>] [--namespace <name>] [--producer <name>] [--input-hash <hash>] [--cursor <token>] [--limit <n>] [--server <url>]
328
+ ```
329
+
330
+ - `--namespace <name>`: Namespaced category (e.g. `quasar.analysis.thread-summary`).
331
+ - `--producer <name>`: Producer identifier and version string (e.g. `evaluator@1.0.0`).
332
+ - `--input-hash <hash>`: Source fingerprint the enrichment was derived from.
333
+
334
+ #### 18. `enrichment-write`
335
+ Writes a namespaced session enrichment record. Re-ingesting raw source sessions will never overwrite derived enrichment records.
336
+
337
+ ```bash
338
+ quasar enrichment-write <inline-json|@file|-> [--server <url>] [--ingest-token <token>]
339
+ ```
340
+
341
+ Example payload:
342
+
343
+ ```json
344
+ {
345
+ "protocolVersion": "quasar.session-enrichment/v1",
346
+ "sessionId": "codex:01950e93-9c87-7359-bb43-d9d150247656",
347
+ "namespace": "quasar.analysis.eval",
348
+ "schemaVersion": 1,
349
+ "producer": "agent-evaluator@1.2.0",
350
+ "inputHash": "sha256:7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd200126d9069",
351
+ "payload": {
352
+ "score": 0.95,
353
+ "verdict": "completed_task",
354
+ "notes": "Resolved compilation issue without regressions"
355
+ },
356
+ "updatedAt": "2026-08-17T20:00:00.000Z"
357
+ }
358
+ ```
359
+
360
+ ---
361
+
362
+ ### Vector Maintenance & Queue Operations
363
+
364
+ #### 19. `materialize-embedding-vectors`
365
+ Triggers or drives vector embedding computation for un-embedded messages into SQLite vector tables.
366
+
367
+ ```bash
368
+ quasar materialize-embedding-vectors [--limit <n>] [--until-empty] [--max-batches <n>] [--require-provider <local|synthetic>] [--out <receipt.json>] [--server <url>]
369
+ ```
370
+
371
+ - `--until-empty`: Loop continuously until all vectorless messages are materialized.
372
+ - `--max-batches <n>`: Safety limit on total batches executed.
373
+ - `--require-provider <local|synthetic>`: Gate execution requiring a specific embedding provider (e.g. local ONNX).
374
+ - `--out <path>`: Write a durable closure receipt containing execution timestamps, batches, and total tokens.
375
+
376
+ #### 20. `replay-embedding-cache`
377
+ Replays pre-computed embedding cache rows into active message vector tables.
378
+
379
+ ```bash
380
+ quasar replay-embedding-cache [--limit <n>] [--server <url>]
381
+ ```
382
+
383
+ #### 21. `prune-dead-letters`
384
+ Prunes resolved or obsolete dead-letter queue jobs whose underlying tasks succeeded or were superseded.
385
+
386
+ ```bash
387
+ quasar prune-dead-letters [--server <url>]
388
+ ```
389
+
390
+ ---
391
+
392
+ ### Schema & Introspection
393
+
394
+ #### 22. `schema`
395
+ Emits the strict JSON Schema definition for any Quasar protocol contract (runs locally with zero network dependencies).
396
+
397
+ ```bash
398
+ quasar schema [normalized-session|mapped-session|trajectory|letta-trajectory|harbor-atif|atif-trajectory|research-export|query|response|session-enrichment]
399
+ ```
400
+
401
+ #### 23. `examples`
402
+ Emits valid example JSON payloads for protocol contracts (runs locally).
403
+
404
+ ```bash
405
+ quasar examples [schema-id|example-name]
406
+ ```
407
+
408
+ #### 24. `version`
409
+ Outputs version and package metadata.
410
+
411
+ ```bash
412
+ quasar version
413
+ ```
414
+
415
+ ---
416
+
417
+ ## Interactive Terminal UI (TUI)
418
+
419
+ Launching `quasar` in an interactive terminal with no arguments (or running `quasar tui`) launches the high-performance OpenTUI interface.
420
+
421
+ ```bash
422
+ quasar tui [--server <url>] [--smoke] [--smoke-query <query>]
423
+ ```
424
+
425
+ ```
426
+ ┌ quasar fusion 42 matches project:quasar #codex ────────────────┐
427
+ │ › project:quasar #codex model assignment█ │
428
+ ├──────────────────────────────────────────────────────────────────────────────────────┤
429
+ │ codex 2026-08-17 quasar Fix model provider resolution in turn context │
430
+ │ ...ensures that model assignment is preserved across subagent handoffs... │
431
+ │ │
432
+ │ codex 2026-08-16 quasar Refactor vector embeddings batch pipeline │
433
+ │ ...replaces synthetic fallback with resident ONNX SIMD vector matrix... │
434
+ └──────────────────────────────────────────────────────────────────────────────────────┘
435
+ ```
436
+
437
+ ### Omnibox Filter Syntax
438
+
439
+ Compose real-time search filters directly within the query string:
440
+
441
+ - `@<project>` or `project:<key>`: Filter by project (e.g. `@quasar` or `project:prism`)
442
+ - `#<provider>` or `provider:<name>`: Filter by provider (e.g. `#codex` or `provider:claude`)
443
+ - `role:<user|assistant|reasoning>`: Filter by message role (e.g. `role:user`)
444
+ - Free text: Search terms evaluated by the active search engine mode.
445
+
446
+ ### TUI Keymap Reference
447
+
448
+ The TUI operates with three primary focus modes without modal mode traps:
449
+
450
+ #### 1. Search Focus (Omnibox)
451
+ | Key | Action |
452
+ |---|---|
453
+ | `Any printable` | Type search text |
454
+ | `Down` / `Ctrl-N` / `Ctrl-J` | Move selection down in results list |
455
+ | `Up` / `Ctrl-P` / `Ctrl-K` | Move selection up in results list |
456
+ | `Enter` | Open transcript reader for selected session |
457
+ | `Tab` | Switch focus to results list |
458
+ | `Backspace` | Delete character |
459
+ | `Ctrl-W` | Delete preceding word |
460
+ | `Ctrl-U` | Clear omnibox query |
461
+ | `Escape` | Clear query if text present; quit if query is empty |
462
+
463
+ #### 2. List Focus (Results Browser)
464
+ | Key | Action |
465
+ |---|---|
466
+ | `j` / `Down` | Move selection down |
467
+ | `k` / `Up` | Move selection up |
468
+ | `g` | Jump to first result |
469
+ | `G` / `Shift-G` | Jump to last result |
470
+ | `1` - `9` | Jump directly to result index 1–9 |
471
+ | `Enter` / `l` / `s` | Open transcript reader for selected session |
472
+ | `t` | Toggle tool-call forensics view for session |
473
+ | `m` | Cycle search mode (`lexical` → `semantic` → `fusion`) |
474
+ | `e` | Open transcript in external `$EDITOR` |
475
+ | `y` | Yank session ID to system clipboard |
476
+ | `Y` / `Shift-Y` | Yank result snippet text to clipboard |
477
+ | `/` or `Escape` | Return focus to search omnibox |
478
+ | `?` | Toggle help overlay |
479
+ | `q` / `Ctrl-C` | Quit TUI |
480
+
481
+ #### 3. Reader Focus (Transcript & Tool Inspector)
482
+ | Key | Action |
483
+ |---|---|
484
+ | `j` / `Down` | Scroll down 1 line |
485
+ | `k` / `Up` | Scroll up 1 line |
486
+ | `Space` / `Ctrl-D` | Scroll down 12 lines (page down) |
487
+ | `b` / `Ctrl-U` | Scroll up 12 lines (page up) |
488
+ | `g` | Jump to top of transcript |
489
+ | `G` / `Shift-G` | Jump to bottom of transcript |
490
+ | `n` / `]` | Jump to next search match occurrence |
491
+ | `N` / `[` | Jump to previous search match occurrence |
492
+ | `t` | Toggle between transcript messages and tool-call view |
493
+ | `i` / `Enter` | Drill into full input/output payload for selected tool call |
494
+ | `e` | Open current transcript view in external `$EDITOR` |
495
+ | `y` | Yank session or tool call ID to clipboard |
496
+ | `Y` / `Shift-Y` | Yank visible message text to clipboard |
497
+ | `Escape` | Return to results list / omnibox |
498
+ | `q` / `Ctrl-C` | Quit TUI |
499
+
500
+ ---
501
+
502
+ ## Query Spec, Filters & Projections
503
+
504
+ All query-backed CLI commands (`search`, `sessions`, `messages`, `tool-calls`, `tool-call`) share the strict `quasar.query/v1` protocol specification.
505
+
506
+ ### Summary vs. Detail Projections
507
+
508
+ - **Summary (`--fields ...`)**: Lightweight rows tailored for scannability and fast network transfer. Tool payloads (`input`, `output`, `error`) and raw execution contexts are omitted.
509
+ - **Detail (`--detail`)**: Full message records, complete tool arguments and outputs, execution context references, and byte size indicators.
510
+
511
+ ### Pagination Contract
512
+
513
+ Query-backed commands use opaque cursor pagination:
514
+ - Pass the returned `page.nextCursor` from a response as `--cursor <token>` in the subsequent command.
515
+ - `--offset` is deliberately rejected on query-backed commands to enforce deterministic pagination across mutating datasets.
516
+
517
+ ---
518
+
519
+ ## JSON Output & Dual Envelope Model
520
+
521
+ The Quasar CLI adheres to a strict dual-envelope JSON output model:
522
+
523
+ ### 1. Operations & Resource Commands
524
+ Commands such as `ingest`, `stats`, `session`, `projects`, `daemon`, and `materialize-embedding-vectors` return the standard envelope:
525
+
526
+ ```json
527
+ {
528
+ "ok": true,
529
+ "command": "stats",
530
+ "data": { ... }
531
+ }
532
+ ```
533
+
534
+ On failure:
59
535
 
60
- Override provider roots when needed:
536
+ ```json
537
+ {
538
+ "ok": false,
539
+ "command": "ingest",
540
+ "error": {
541
+ "type": "ConfigurationError",
542
+ "message": "quasar ingest requires a configured local server URL",
543
+ "details": { ... }
544
+ }
545
+ }
546
+ ```
547
+
548
+ ### 2. Query Protocol Commands
549
+ Commands adhering directly to `quasar.query/v1` (`search`, `sessions`, `messages`, `tool-calls`, `tool-call`, `query`) emit top-level protocol responses:
550
+
551
+ ```json
552
+ {
553
+ "protocolVersion": "quasar.query/v1",
554
+ "kind": "search",
555
+ "projection": {
556
+ "detail": "summary",
557
+ "fields": ["sessionId", "provider", "text", "score"]
558
+ },
559
+ "page": {
560
+ "returned": 1,
561
+ "nextCursor": "eyJ2ZXJzaW9uIjoxLCJraW5kIjoic2VhcmNoIiwiYWZ0ZXIiOjEwfQ"
562
+ },
563
+ "items": [
564
+ {
565
+ "sessionId": "codex:01950e93-9c87-7359-bb43-d9d150247656",
566
+ "provider": "codex",
567
+ "text": "Model selection is preserved in turn context.",
568
+ "score": 0.94
569
+ }
570
+ ]
571
+ }
572
+ ```
573
+
574
+ ---
61
575
 
576
+ ## JSON Piping & Automation Recipes
577
+
578
+ ### Search and extract top session IDs:
62
579
  ```bash
63
- export QUASAR_CODEX_ROOT="$HOME/.codex"
64
- export QUASAR_CLAUDE_ROOT="$HOME/.claude"
65
- export QUASAR_OPENCODE_ROOT="$HOME/.local/share/opencode"
66
- export QUASAR_GROK_ROOT="$HOME/.grok"
67
- export QUASAR_HERMES_ROOT="$HOME/.hermes"
580
+ quasar search --query "sqlite lock issue" --mode fusion --limit 5 | jq -r '.items[].sessionId'
68
581
  ```
582
+
583
+ ### Export an entire session transcript to Markdown:
584
+ ```bash
585
+ quasar session --id "codex:01950e93-9c87-7359-bb43-d9d150247656" | jq -r '
586
+ .data.messages[] | "### \(.role | ascii_upcase) (\(.sequence))\n\n\(.text)\n"
587
+ ' > transcript.md
588
+ ```
589
+
590
+ ### Inspect failed tool calls across the corpus:
591
+ ```bash
592
+ quasar tool-calls --detail --limit 50 | jq '
593
+ .items[] | select(.status == "failed" or .error != null) | {toolCallId, sessionId, toolName, error}
594
+ '
595
+ ```
596
+
597
+ ### Stream research export shards into compressed archives:
598
+ ```bash
599
+ quasar research-export --out dataset-shard-1.ndjson --project quasar --roots-only
600
+ gzip -9 dataset-shard-1.ndjson
601
+ ```
602
+
603
+ ### Drive vector embedding materialization to completion:
604
+ ```bash
605
+ quasar materialize-embedding-vectors --until-empty --require-provider local --out ./materialize-receipt.json
606
+ cat materialize-receipt.json | jq '.data.closure'
607
+ ```
608
+
609
+ ---
610
+
611
+ ## Environment Variables Reference
612
+
613
+ | Environment Variable | Description | Default |
614
+ |---|---|---|
615
+ | `QUASAR_SERVER_URL` | URL of the running Quasar Effect server | From `config.json` |
616
+ | `QUASAR_INGEST_TOKEN` | Secret token required for remote ingest and daemon writes | From `config.json` |
617
+ | `QUASAR_CONFIG` | Custom file path for client configuration JSON | `~/.config/quasar/config.json` |
618
+ | `QUASAR_HTTP_TIMEOUT_MS` | Client HTTP timeout in milliseconds | `60000` (60s) |
619
+ | `QUASAR_LOCAL_HOME` | Server storage root override | `~/.config/quasar/server` |
620
+ | `QUASAR_LOCAL_SQLITE` | Direct SQLite file path override | `~/.config/quasar/server/quasar.sqlite` |
621
+ | `QUASAR_DAEMON_HOME` | Root configuration and logs directory for daemon | `~/.config/quasar` |
622
+ | `QUASAR_DAEMON_BINARY` | Path to executable used for background daemon ticks | System binary |
623
+ | `QUASAR_DAEMON_INTERVAL_SECONDS` | Daemon execution frequency in seconds | `15` |
624
+ | `QUASAR_DAEMON_STALE_LOCK_SECONDS` | Duration before broken daemon locks are reclaimed | `3600` (1 hour) |
625
+ | `QUASAR_AMP_INGEST` | `on` includes Amp in `ingest --provider all`; written by `daemon install --amp` | unset (off) |
626
+ | `QUASAR_CODEX_ROOT` | Codex history directory override | `~/.codex` |
627
+ | `QUASAR_CLAUDE_ROOT` | Claude Code history directory override | `~/.claude` |
628
+ | `QUASAR_OPENCODE_ROOT` | OpenCode history directory override | `~/.local/share/opencode` |
629
+ | `QUASAR_GROK_ROOT` | Grok history directory override | `~/.grok` |
630
+ | `QUASAR_HERMES_ROOT` | Hermes history directory override | `~/.hermes` |
631
+ | `QUASAR_KIMI_ROOT` | Kimi history directory override | `~/.kimi` |
632
+ | `QUASAR_ANTIGRAVITY_ROOT` | Antigravity history directory override | `~/.gemini/antigravity-cli` |
633
+ | `QUASAR_OMP_ROOT` | OMP history directory override | `~/.omp` |
634
+ | `QUASAR_PI_ROOT` | Pi history directory override | `~/.pi` |
635
+ | `QUASAR_PRIME_ROOT` | Prime history directory override | `~/.prime` |
636
+ | `QUASAR_CURSOR_ROOT` | Cursor history directory override | `~/Library/Application Support/Cursor` |
637
+ | `QUASAR_DEVIN_ROOT` | Devin history directory override | `~/.devin` |
638
+ | `QUASAR_AMP_ROOT` | Amp history directory override | `~/.amp` |
package/bin/quasar CHANGED
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@skastr0/quasar-cli-linux-arm64",
3
- "version": "0.5.2",
3
+ "version": "0.5.4",
4
4
  "description": "Command line importer and client for Quasar AI agent sessions. (linux-arm64 binary).",
5
5
  "license": "MIT",
6
6
  "type": "module",