-Search your Claude Code sessions, Codex CLI history, Gemini CLI chats, GitHub stars, Twitter bookmarks, and YouTube likes — locally, instantly.
+Search your Claude Code sessions, Codex CLI history, and Gemini CLI chats — locally, instantly.
> **Early stage.** Spool is under active development — expect rough edges. Feedback, bug reports, and ideas are very welcome via [Issues](https://github.com/spool-lab/spool/issues) or [Discord](https://discord.gg/aqeDxQUs5E).
@@ -26,14 +26,15 @@ pnpm build
## What it does
-Spool indexes your AI conversations and bookmarks into a single local search box.
+Spool indexes your AI conversations into a single local search box.
- **AI sessions** — watches Claude/Codex/Gemini session dirs in real time, including profile-based paths like `~/.claude-profiles/*/projects`, `~/.codex-profiles/*/sessions`, and Gemini’s project temp dirs under `~/.gemini/tmp/*/chats`
-- **Connectors** — sync bookmarks and stars from platforms like Twitter/X, GitHub, and more via installable connector plugins
- **Agent search** — a `/spool` skill inside Claude Code feeds matching fragments back into your conversation
Everything stays on your machine. Nothing leaves.
+> Looking for connectors (Twitter / GitHub / Reddit / etc.)? They now live in **[Spool Daemon](https://spool.pro/daemon)**, a sibling app focused on syncing platform data.
+
## Architecture
```
@@ -74,10 +75,6 @@ until CI finishes; artifacts appear on the release page when it returns.
To test a local build without cutting a release, use `pnpm --filter @spool/app build:mac`.
-## Acknowledgements
-
-- **[fieldtheory-cli](https://github.com/afar1/fieldtheory-cli)** — Twitter/X bookmark sync implementation adapted from this project
-
## License
MIT
diff --git a/docs/connector-developer-guide.md b/docs/connector-developer-guide.md
deleted file mode 100644
index bc5e1fa..0000000
--- a/docs/connector-developer-guide.md
+++ /dev/null
@@ -1,607 +0,0 @@
-# Connector Developer Guide
-
-> Everything you need to build, test, and publish a Spool connector.
-
----
-
-## What is a Connector?
-
-A connector is a small npm package that teaches Spool how to fetch data from one platform source. You implement two methods — `checkAuth()` and `fetchPage()` — and the framework handles everything else: scheduling, state persistence, error retries, progress UI, and search indexing.
-
-A connector does NOT:
-- Know when it will be called (the scheduler decides)
-- Track pagination state (the sync engine manages cursors)
-- Write to the database (the engine handles upserts)
-- Handle retries or backoff (the scheduler handles this)
-
-Your job is simple: **given a `FetchContext`, return one page of items.** Most connectors only need the `cursor` field — `sinceItemId` and `phase` are optional hints.
-
----
-
-## Anatomy of a Connector
-
-### The Interface
-
-```typescript
-interface Connector {
- readonly id: string // Unique ID: 'twitter-bookmarks', 'github-stars'
- readonly platform: string // Platform grouping: 'twitter', 'github'
- readonly label: string // Display name: 'X Bookmarks', 'GitHub Stars'
- readonly description: string // One-liner for picker UI
- readonly color: string // Hex color for badges: '#1DA1F2'
- readonly ephemeral: boolean // true = cache (full-replace), false = user data (incremental)
-
- checkAuth(opts?: Record
+
+ )
+}
+
diff --git a/packages/core/README.md b/packages/core/README.md
index 95bcee0..1f99dff 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -1,8 +1,8 @@
# @spool-lab/core
-The engine behind [Spool](https://spool.pro) — a local search engine for your AI sessions and connected sources.
+The engine behind [Spool](https://spool.pro) — a local search engine for your AI sessions.
-This package provides the core runtime: session parsing, full-text search, the connector sync engine, and the SQLite database layer. It powers both the Spool desktop app and the `@spool-lab/cli`.
+This package provides the core runtime: session parsing, full-text search, and the SQLite database layer. It powers both the Spool desktop app and the `@spool-lab/cli`.
## Usage
@@ -26,9 +26,8 @@ syncer.syncAll()
- **Session parsers** — reads Claude Code, Codex, and Gemini CLI session files
- **Full-text search** — FTS5 with unicode + trigram indexes for CJK support
-- **Sync engine** — paginated connector sync with cursor-based state, backfill, and error recovery
-- **Connector loader** — discovers and loads connector plugins from `~/.spool/connectors/`
-- **Connector registry** — in-memory registry of available connectors
+- **Watcher** — incremental indexing as new session files arrive
+- **Stars** — pin sessions for quick recall
## Native dependency
diff --git a/packages/core/src/db/db.ts b/packages/core/src/db/db.ts
index b12ef45..c9dd87d 100644
--- a/packages/core/src/db/db.ts
+++ b/packages/core/src/db/db.ts
@@ -1,25 +1,39 @@
import Database from 'better-sqlite3'
import { homedir } from 'node:os'
import { join } from 'node:path'
-import { mkdirSync, statSync } from 'node:fs'
+import { existsSync, mkdirSync, statSync } from 'node:fs'
export const SPOOL_DIR = process.env['SPOOL_DATA_DIR'] ?? join(homedir(), '.spool')
export const DB_PATH = join(SPOOL_DIR, 'spool.db')
let _db: Database.Database | null = null
+let _wasNewDb = false
+let _initialUserVersion: number | null = null
export function getDB(_readonly = false): Database.Database {
if (_db) return _db
mkdirSync(SPOOL_DIR, { recursive: true })
+ // Capture pre-open state before better-sqlite3 creates the file. These two
+ // signals together let callers tell apart "fresh install" from "upgrade":
+ // - wasNewDb=true → DB file did not exist; this is a first-time install
+ // - wasNewDb=false → upgrade path, and initialUserVersion tells you from where
+ _wasNewDb = !existsSync(DB_PATH)
const db = new Database(DB_PATH)
db.pragma('journal_mode = WAL')
db.pragma('foreign_keys = ON')
db.pragma('busy_timeout = 5000')
+ _initialUserVersion = (db.pragma('user_version') as Array<{ user_version: number }>)[0]?.user_version ?? 0
runMigrations(db)
_db = db
return db
}
+/** True if the DB file did not exist before this process opened it. */
+export function wasNewDb(): boolean { return _wasNewDb }
+
+/** user_version of the DB before any migrations ran this process. Null if getDB() hasn't been called. */
+export function getInitialUserVersion(): number | null { return _initialUserVersion }
+
export function getDBSize(): number {
try {
return statSync(DB_PATH).size
diff --git a/packages/core/src/db/migration-v5.test.ts b/packages/core/src/db/migration-v5.test.ts
index e599a08..ea098e0 100644
--- a/packages/core/src/db/migration-v5.test.ts
+++ b/packages/core/src/db/migration-v5.test.ts
@@ -144,6 +144,10 @@ describe('migration v5 (connector subsystem removal)', () => {
const dbModule = await import('./db.js')
const db = dbModule.getDB()
+ // Upgrade-path detection: DB pre-existed and was on v4
+ expect(dbModule.wasNewDb()).toBe(false)
+ expect(dbModule.getInitialUserVersion()).toBe(4)
+
// user_version bumped to 5
expect((db.pragma('user_version') as Array<{ user_version: number }>)[0]?.user_version).toBe(5)
@@ -181,6 +185,10 @@ describe('migration v5 (connector subsystem removal)', () => {
const dbModule = await import('./db.js')
const db = dbModule.getDB()
+ // Upgrade-path detection: DB file did not exist before this run
+ expect(dbModule.wasNewDb()).toBe(true)
+ expect(dbModule.getInitialUserVersion()).toBe(0)
+
expect((db.pragma('user_version') as Array<{ user_version: number }>)[0]?.user_version).toBe(5)
// Stars exists with narrow CHECK
+
+
+
+
+
+
+
+ + Connectors moved to Spool Daemon +
++ Spool now focuses on AI sessions. Twitter, GitHub, Reddit, Hacker News and other + platform connectors live in{' '} + + Spool Daemon + + , a sibling app. Synced platform data has been removed from Spool — install Daemon + to keep using connectors. +
+
+
+
+
+