@threadbase-sh/scanner 0.17.7 → 0.18.0

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.
package/README.md CHANGED
@@ -20,7 +20,7 @@ Combines the best parts of four independent scanner implementations (VS Code, El
20
20
  - **Filtering** — by project, account, time range, conversation type (conversations/subagents/teammates)
21
21
  - **5 sort modes** — recent, oldest, messages-desc, messages-asc, alphabetical
22
22
  - **Pagination** — limit/offset on all operations
23
- - **Multi-provider** — index Threadbase/Claude history and local OpenAI Codex CLI sessions through one normalized pipeline (Codex is opt-in; in-memory path only — see below)
23
+ - **Multi-provider** — index Threadbase/Claude history, local OpenAI Codex CLI sessions, and Cursor agent-transcripts through one normalized pipeline (Codex and Cursor are opt-in)
24
24
  - **Multi-profile** — scan multiple Claude config directories
25
25
  - **LRU caching** — metadata and conversation caches for fast repeated access
26
26
  - **Git branch detection** — reads `.git/HEAD` with parent directory walking
@@ -113,37 +113,46 @@ scanner.close()
113
113
 
114
114
  ### Scanning Codex CLI history (providers)
115
115
 
116
- The scanner can index local **OpenAI Codex CLI** rollout sessions alongside the
117
- default Threadbase/Claude history, normalizing both into the same
118
- `ConversationMeta` model. Codex support is **opt-in**: pass `providers` and the
119
- explicit `codexRoots` to discover under (no home directory is scanned by
120
- default).
116
+ The scanner can index local **OpenAI Codex CLI** rollout sessions and **Cursor**
117
+ agent-transcripts (`~/.cursor/projects/<slug>/agent-transcripts/`) alongside the
118
+ default Threadbase/Claude history, normalizing all of them into the same
119
+ `ConversationMeta` model. Extra providers are **opt-in**: pass `providers` and
120
+ the matching `*Roots` (no home directory is scanned by default). Cursor Composer
121
+ (`state.vscdb`) is a different store and is not indexed.
121
122
 
122
123
  ```typescript
124
+ import { homedir } from 'node:os'
125
+ import { join } from 'node:path'
126
+
123
127
  const scanner = new ConversationScanner()
124
128
 
125
129
  const result = await scanner.scan({
126
- providers: ['claude-code', 'codex-cli'],
127
- codexRoots: ['~/.codex/sessions'], // expand ~ yourself, or pass an absolute path
130
+ providers: ['claude-code', 'codex-cli', 'cursor'],
131
+ codexRoots: [join(homedir(), '.codex/sessions')],
132
+ cursorRoots: [join(homedir(), '.cursor/projects')],
128
133
  })
129
134
 
130
135
  // Each meta carries its source provider
131
136
  for (const c of result.conversations) {
132
- console.log(c.provider) // 'claude-code' | 'codex-cli'
137
+ console.log(c.provider) // 'claude-code' | 'codex-cli' | 'cursor'
133
138
  }
134
139
 
135
- // Search across both, or filter to one provider
136
- const codexHits = await scanner.search('refactor', { provider: 'codex-cli' })
140
+ // Search across all, or filter to one provider
141
+ const cursorHits = await scanner.search('refactor', { provider: 'cursor' })
137
142
  ```
138
143
 
139
- `codexRoots` entries must be absolute paths — expand `~` before passing them
140
- (e.g. ``join(homedir(), '.codex/sessions')``). Codex metas also set `kind`
141
- (`'conversation'` | `'task'`) and `externalSessionId` (the Codex-native session
142
- id) when available.
144
+ `codexRoots` / `cursorRoots` entries must be absolute paths — expand `~` before
145
+ passing them (e.g. ``join(homedir(), '.cursor/projects')``). Codex and Cursor
146
+ metas also set `kind` (`'conversation'` | `'task'`) and `externalSessionId`
147
+ when available.
143
148
 
144
- Codex rows are indexed into the same SQLite database as Claude history. Their
145
- `sessionId` is the rollout's `session_meta` id, which is the uuid at the end of
146
- the `rollout-<ts>-<uuid>.jsonl` filename.
149
+ Codex and Cursor rows are indexed into the same SQLite database as Claude
150
+ history. A Codex `sessionId` is the rollout's `session_meta` id (the uuid at
151
+ the end of `rollout-<ts>-<uuid>.jsonl`). A Cursor `sessionId` is the transcript
152
+ filename stem (`<runId>.jsonl`). The wire name is **`cursor`**. The live PTY
153
+ name `cursor-cli` is still accepted as an alias. Not `cursor-agent`. Cursor copies of another provider
154
+ set `isImportedFromClaude` or `isImportedFromCodex`; `isImportedFromCursor` is
155
+ reserved for Claude/Codex providers.
147
156
 
148
157
  #### Resolving an id to its transcript file
149
158
 
@@ -154,7 +163,7 @@ process:
154
163
  ```typescript
155
164
  const scanner = new ConversationScanner() // opens the existing index.db
156
165
  const [meta] = scanner.getConversationsBySessionId(uuid) // newest first; [] if unknown
157
- meta?.filePath // absolute path to the .jsonl, for Claude and Codex alike
166
+ meta?.filePath // absolute path to the .jsonl (Claude, Codex, and Cursor)
158
167
  const page = await scanner.getConversationPage(uuid, { limit: 50 })
159
168
  ```
160
169
 
@@ -340,9 +349,12 @@ Every scanned conversation produces a `ConversationMeta` with the full superset
340
349
  | `isTeammate` | boolean | VS Code |
341
350
  | `teamName` | string \| null | VS Code |
342
351
  | `toolNames` | string[] | CLI |
343
- | `provider` | `'claude-code' \| 'codex-cli'` | Provider that produced the meta |
344
- | `kind` | `'conversation' \| 'task'` | Codex (optional) |
345
- | `externalSessionId` | string | Codex-native session id (optional) |
352
+ | `provider` | `'claude-code' \| 'codex-cli' \| 'cursor'` | Provider that produced the meta |
353
+ | `kind` | `'conversation' \| 'task'` | Codex / Cursor (optional) |
354
+ | `externalSessionId` | string | Provider-native session id (optional) |
355
+ | `isImportedFromClaude` | boolean | Cursor copy of a Claude session (optional; omit when false) |
356
+ | `isImportedFromCodex` | boolean | Cursor copy of a Codex session (optional; omit when false) |
357
+ | `isImportedFromCursor` | boolean | Reserved for Claude/Codex copies of Cursor (optional; omit when false) |
346
358
 
347
359
  ## Development
348
360