chat-logbook 0.3.1 → 0.4.1

package/README.md

@@ -2,48 +2,71 @@
 
 > _Where your AI conversations live._
 
-chat-logbook is a local-first library for your AI conversations. It reads the
-files AI assistants write on your machine — starting with Claude Code, with
-more tools planned — and presents them as a single browsable, searchable,
-organizable history.
+A local-first library for the conversations you've had with your AI tools.
+Read by chat-logbook, kept on your machine, browsable and searchable in one
+place — even after your AI tool has deleted the original.
 
-> **Status:** Early release (v0.3.0). Browsing, rendering, and
-> soft-delete with Trash are working today. Search, tags, and
-> annotations are on the way. See [Roadmap](#roadmap).
+> **Status.** A personal side project, moving at side-project pace —
+> development and responses happen as time allows. Early release:
+> browsing, rendering, soft-delete, and a local archive that survives
+> vendor cleanup all work today. Search and tags are next. See
+> [Roadmap](#roadmap).
 
-## About
+## What chat-logbook is
 
-You open chat-logbook from the command line, and a browser window opens onto
-your conversation history. You can browse it, find anything in it, tag what
+You open it from the command line, and a browser window opens onto your
+conversation history. You can browse it, find anything in it, tag what
 matters, and pick up where you left off.
 
+It reads the files your AI tools already write to your machine — Claude Code
+today, with more tools planned. From there it keeps its own copy in a
+private archive on your machine, so the history is yours even when the
+source tool quietly cleans up after itself (Claude Code defaults to deleting
+conversations older than 30 days).
+
 Nothing leaves your machine. There is no account to create. The original
-files written by your AI tools are never modified.
+files your AI tools wrote are never modified.
+
+We built this because the right place for your AI conversations to live
+isn't inside the next vendor change.
 
-Design principles:
+## What it gives you
 
-- **Read-only access to source directories.** Original conversation files are
-  never modified. Today that means `~/.claude/`; the same rule applies to
-  every agent we add.
+- **Read-only access to source directories.** Original conversation files
+  are never modified. Today that means `~/.claude/`; the same rule applies
+  to every agent we add.
 - **Local-only.** No telemetry, no analytics, no third-party calls.
 - **Zero configuration.** Install and run.
 - **Drive everything from the keyboard.** A `/` or `⌘K` overlay finds any
   past conversation in seconds. The mouse still works, but every primary
   action has a binding.
+- **Your archive is yours.** It's a single SQLite file at
+  `~/.chat-logbook/archive.db`. Copy it to back up. Open it with any tool
+  that reads SQLite. If chat-logbook disappears tomorrow, the archive
+  doesn't.
 
 The full problem statement, user stories, and direction live in the
 [PRD](docs/PRD.md).
 
 ## What works today
 
-- **Three-column layout** — Resizable panels for filters, session list, and conversation content
-- **Rich conversation rendering** — Markdown, syntax-highlighted code blocks, collapsible tool calls with one-line summaries, and collapsible thinking blocks
-- **Virtual scrolling** — Handles long conversations smoothly with virtualized rendering
-- **Solarized Dark theme** — Easy on the eyes, consistent with Claude Code's terminal aesthetic
+- **Three-column layout.** Resizable panels for filters, session list,
+  and conversation content.
+- **Rich conversation rendering.** Markdown, syntax-highlighted code
+  blocks, collapsible tool calls with one-line summaries, and collapsible
+  thinking blocks.
+- **Virtual scrolling.** Long conversations scroll smoothly.
+- **Solarized Dark theme.** Easy on the eyes, consistent with Claude
+  Code's terminal look.
+- **Soft delete with Trash.** Hide sessions you don't want to see; restore
+  them anytime.
+- **Local archive.** Every conversation chat-logbook reads is copied into
+  `~/.chat-logbook/archive.db`. The UI reads from the archive, so a
+  session stays visible even after the source JSONL is gone.
 
 ## Quick start
 
-Requirements: Node.js 20+.
+Requirements: Node.js 20 or later.
 
 Install globally for a shorter command:
 
@@ -64,129 +87,114 @@ You should see:
 chat-logbook is running at http://localhost:3100
 ```
 
-Your browser will open automatically, showing a list of your Claude Code sessions on the left and conversation content on the right.
+A browser window opens automatically, showing a list of your Claude Code
+sessions on the left and conversation content on the right.
 
 ### Troubleshooting
 
-**"No conversations found"**
-Make sure you have Claude Code conversation history at `~/.claude/`. chat-logbook reads from this directory automatically.
-
-**Port already in use**
-By default, chat-logbook runs on port 3100. Use `PORT=8080 chat-log` to specify a different port.
-
-**Updating to the latest version**
-Run `npm install -g chat-logbook@latest` to update. If you use npx, the `@latest` tag ensures you always run the newest version.
-
-## Architecture
+**"No conversations found."**
+You need to have Claude Code conversation history at `~/.claude/`.
+chat-logbook reads from this directory automatically.
 
-Monorepo with two workspaces, published as a single npm package:
+**"Port already in use."**
+chat-logbook runs on port 3100 by default. Use `PORT=8080 chat-log` to
+pick a different port.
 
-| Directory | Role                                                                      | Stack                                   |
-| --------- | ------------------------------------------------------------------------- | --------------------------------------- |
-| `api/`    | Backend — reads `~/.claude/` JSONL files, serves session and message data | Hono + @hono/node-server                |
-| `web/`    | Frontend — three-column SPA with conversation rendering                   | React + Vite + Tailwind CSS + shadcn/ui |
+**Updating to the latest version.**
+Run `npm install -g chat-logbook@latest`. If you use npx, the `@latest`
+tag ensures you always run the newest version.
 
-In production, Hono serves both the API endpoints and the static frontend
-assets from a single Node.js process. During development, Vite proxies `/api`
-requests to the Hono dev server.
-
-### How it reads conversations
-
-chat-logbook reads conversation data directly from the JSONL files that Claude
-Code stores in `~/.claude/`. It **never modifies** these files — your original
-conversation data is always left untouched.
+## FAQ
 
-Only conversations that are written to `~/.claude/` are visible. Ephemeral
-interactions that Claude Code does not persist (such as `/btw` side questions)
-cannot be displayed.
+### Does chat-logbook work with Claude Code on the web?
 
-## Development
+No. chat-logbook reads from local `~/.claude/` files, which are only
+created by the Claude Code CLI on your machine. Conversations run via
+Claude Code on the web (cloud VMs) are not stored locally and aren't
+visible to chat-logbook.
 
-Requirements: Node.js 20+ and pnpm 10+.
+### Why can't I see my `/btw` conversations?
 
-```bash
-git clone https://github.com/evaaaaawu/chat-logbook.git
-cd chat-logbook
-pnpm install
-pnpm dev
-```
+`/btw` is designed to be ephemeral — questions and answers appear in a
+temporary overlay and are never written to conversation history files.
+For a conversation to be preserved and visible in chat-logbook, send a
+regular message instead.
 
-### Scripts
+### Will chat-logbook lose my history if Claude Code deletes its files?
 
-| Command          | What it does                                        |
-| ---------------- | --------------------------------------------------- |
-| `pnpm dev`       | Start dev servers for both workspaces (Vite + Hono) |
-| `pnpm build`     | Build frontend and backend for production           |
-| `pnpm test`      | Run all tests (Vitest)                              |
-| `pnpm typecheck` | Type-check all workspaces                           |
+Once chat-logbook has read a conversation into its archive, vendor
+cleanup of the original file no longer removes it from chat-logbook.
+The archive's contract: never delete in response to source deletion.
+Only an explicit user action (Hard Delete / Purge) removes archived
+conversations.
 
-A Husky `pre-commit` hook runs Prettier on staged files, type-checks, and runs
-the test suite on every commit.
+### Where is my data stored?
 
-## FAQ
+Three places, all on your machine:
 
-### Does chat-logbook work with Claude Code on the web?
+- `~/.claude/` (and equivalents for other tools) — read-only source.
+- `~/.chat-logbook/archive.db` — chat-logbook's copy of the
+  conversations it has read.
+- `~/.chat-logbook/data.db` — your tags, titles, annotations, and
+  soft-delete flags.
 
-No. chat-logbook reads from local `~/.claude/` files, which are only created by the Claude Code CLI running on your machine. Conversations run via Claude Code on the web (cloud VMs) are not stored locally and are not accessible to chat-logbook.
+Back up the two `~/.chat-logbook/` files together; they are the
+complete chat-logbook state.
 
-### Why can't I see my `/btw` conversations?
+### Is this affiliated with Anthropic / OpenAI?
 
-`/btw` is designed to be ephemeral — questions and answers appear in a temporary overlay and are never written to conversation history files. If you want a conversation to be preserved and visible in chat-logbook, use a regular message instead of `/btw`.
+No. chat-logbook reads files those tools write on your machine. It
+doesn't talk to their servers and isn't endorsed by them.
 
 ## Roadmap
 
-The headline feature on the way is **Spotlight Search** — a `⌘K` / `/` overlay
-that searches across sessions, messages, tags, and projects with full keyboard
-navigation, full-text matching (SQLite FTS5 trigram), and message-level jump +
-highlight. It is tracked as the [Spotlight Search epic (#5)](https://github.com/evaaaaawu/chat-logbook/issues/5).
+Two phases of work are in flight, in this order.
 
-Work is grouped into release milestones:
+**Custom titles and tags.** Rename a session to something you'll
+recognize, attach tags with custom colors, and filter the list by tag or
+by project. This is the path from "I have a lot of conversations" to
+"I can find the one I need."
 
-### [v0.3.0 — Spotlight Alpha](https://github.com/evaaaaawu/chat-logbook/milestone/1)
+**Spotlight search.** A keyboard-driven overlay (`⌘K` or `/`) that
+searches across sessions, messages, tags, and projects from one input.
+A match lands you on the exact message with the term highlighted, and
+you can jump between every match without leaving the overlay.
 
-- **Spotlight overlay skeleton** — `⌘K` / `/` opens an overlay; sessions picker; `Enter` opens, `Esc` closes
-- **SQLite + soft delete & restore** — hide sessions you don't need; recover them anytime
-- **Full keyboard contract** — Browse + Spotlight bindings unified
+Beyond these three, several smaller things are on the list without firm
+timing — live updates while an AI tool is writing, annotations and
+highlights for marking what matters, editing your own past messages,
+CLI commands for working with conversations from a terminal. Some will
+ship; some are still being weighed.
 
-### [v0.4.0 — Spotlight v1](https://github.com/evaaaaawu/chat-logbook/milestone/2)
+Explicit non-goals: semantic / vector search, cloud sync inside the OSS
+core, modification of source directories like `~/.claude/`, and bulk
+export to bespoke formats (the archive itself is the export). See the
+[PRD](docs/PRD.md) for the full out-of-scope list.
 
-- **FTS5 full-text messages search** — fast keyword search across all conversations, including CJK and file paths mentioned in tool calls
-- **Incremental reindex** — newly-arrived messages are searchable within seconds
-- **Message-level jump** — Spotlight matches scroll to the exact message and highlight the matched term, with a `n / m matches  ↑↓ Esc` navigator bar
-- **Tags & Projects pickers** — `Tab`-cycle picker scopes; tag/project selection applies the same filter pipeline as the navigation panel
-- **Tag system + tag filtering** — color-coded tags, multi-tag AND filtering
-- **Project filtering** — focus on conversations within a specific project
-- **Title editing** — customize session titles for easier identification
+This project is **not affiliated with Anthropic, OpenAI, or any other AI
+provider.** It reads files those tools write on your machine; it does
+not talk to their servers and is not endorsed by them.
 
-### [v0.5.0 — Cross-vendor foundation](https://github.com/evaaaaawu/chat-logbook/milestones)
+## Changelog
 
-- **Parser plugin architecture** — one plugin per agent, behind a stable
-  interface, so adding a new tool is a contained change
-- **First additional agents** — Codex CLI and Aider plugins, alongside the
-  existing Claude Code reader
-- **`SyncProvider` interface stub** — a no-op default in the OSS core, leaving
-  the integration point open for an opt-in cloud product later
+See [CHANGELOG.md](CHANGELOG.md) for release notes.
 
-### Later
+## Contributing
 
-- **Real-time streaming** — watch active conversations update live via SSE
-- **Annotations** — add notes next to any message in a conversation
-- **Highlights** — mark important text within conversations
-- **`#tag` / `@project` prefix syntax** in Spotlight (fast-follow)
-- **Recent-sessions empty state + onboarding hint** in Spotlight (fast-follow)
+Chat Logbook is in very early development. To keep focus on the current
+goals, we're not taking contributions right now.
 
-Explicit non-goals: semantic / vector search, cloud sync inside the OSS core,
-and any modification of source directories like `~/.claude/`. See the
-[PRD](docs/PRD.md) for the full out-of-scope list.
-
-This project is **not affiliated with Anthropic, OpenAI, or any other AI
-provider.** It reads files those tools write on your machine; it does not
-talk to their servers and is not endorsed by them.
+If there's something you really need — or you'd genuinely like to help —
+reach out directly and we can talk through it.
 
 ## License
 
-This project is licensed under the [GNU Affero General Public License v3.0](LICENSE) (AGPL-3.0-only).
+This project is licensed under the
+[GNU Affero General Public License v3.0](LICENSE) (AGPL-3.0-only).
 
-You are free to use, modify, and distribute this software under the terms of the AGPL-3.0. If you modify the program and make it available over a network, you must release your modified source code under the same license.
+You are free to use, modify, and distribute this software under the
+terms of the AGPL-3.0. If you modify the program and make it available
+over a network, you must release your modified source code under the
+same license.
 
-For commercial licensing inquiries, please contact the author.
+For commercial licensing inquiries, contact the author.

package/api/dist/drizzle/0001_rekey_sessions_meta.sql

@@ -0,0 +1,18 @@
+PRAGMA foreign_keys=OFF;
+--> statement-breakpoint
+CREATE TABLE `__new_sessions_meta` (
+	`id` text PRIMARY KEY NOT NULL,
+	`is_deleted` integer DEFAULT false NOT NULL,
+	`custom_title` text,
+	`created_at` integer NOT NULL,
+	`updated_at` integer NOT NULL
+);
+--> statement-breakpoint
+INSERT INTO `__new_sessions_meta`("id", "is_deleted", "created_at", "updated_at")
+SELECT `session_id`, `is_deleted`, `created_at`, `updated_at` FROM `sessions_meta`;
+--> statement-breakpoint
+DROP TABLE `sessions_meta`;
+--> statement-breakpoint
+ALTER TABLE `__new_sessions_meta` RENAME TO `sessions_meta`;
+--> statement-breakpoint
+PRAGMA foreign_keys=ON;

package/api/dist/drizzle/archive/0000_first_gateway.sql

@@ -0,0 +1,5 @@
+CREATE TABLE `archive_meta` (
+	`id` integer PRIMARY KEY NOT NULL,
+	`archive_uuid` text NOT NULL,
+	`created_at` integer NOT NULL
+);

package/api/dist/drizzle/archive/0001_gigantic_dracula.sql

@@ -0,0 +1,4 @@
+CREATE TABLE `schema_version` (
+	`version` integer PRIMARY KEY NOT NULL,
+	`applied_at` integer NOT NULL
+);

package/api/dist/drizzle/archive/0002_fast_cloak.sql

@@ -0,0 +1,46 @@
+CREATE TABLE `ingestion_events` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`agent` text NOT NULL,
+	`session_id` text NOT NULL,
+	`source_path` text NOT NULL,
+	`event_type` text NOT NULL,
+	`detail` text NOT NULL,
+	`observed_at` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE `messages` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`agent` text NOT NULL,
+	`session_id` text NOT NULL,
+	`message_id` text NOT NULL,
+	`role` text NOT NULL,
+	`ts` integer NOT NULL,
+	`text` text NOT NULL,
+	`blocks` text NOT NULL,
+	`raw_id` integer NOT NULL,
+	FOREIGN KEY (`raw_id`) REFERENCES `raw_messages`(`id`) ON UPDATE no action ON DELETE no action
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `messages_canonical_idx` ON `messages` (`agent`,`session_id`,`message_id`);--> statement-breakpoint
+CREATE TABLE `raw_messages` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`agent` text NOT NULL,
+	`session_id` text NOT NULL,
+	`source_path` text NOT NULL,
+	`source_locator` text NOT NULL,
+	`raw_payload` text NOT NULL,
+	`payload_hash` text NOT NULL,
+	`ingested_at` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `raw_messages_idem_idx` ON `raw_messages` (`agent`,`session_id`,`payload_hash`);--> statement-breakpoint
+CREATE TABLE `sessions` (
+	`id` text PRIMARY KEY NOT NULL,
+	`short_code` text NOT NULL,
+	`agent` text NOT NULL,
+	`source_session_id` text NOT NULL,
+	`first_seen_at` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `sessions_short_code_unique` ON `sessions` (`short_code`);--> statement-breakpoint
+CREATE UNIQUE INDEX `sessions_agent_source_idx` ON `sessions` (`agent`,`source_session_id`);

package/api/dist/drizzle/archive/0003_ordinary_blackheart.sql

@@ -0,0 +1,11 @@
+CREATE TABLE `session_scan_state` (
+	`id` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`agent` text NOT NULL,
+	`session_id` text NOT NULL,
+	`source_path` text NOT NULL,
+	`last_mtime_ms` integer NOT NULL,
+	`last_size_bytes` integer NOT NULL,
+	`last_scanned_at` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `session_scan_state_idx` ON `session_scan_state` (`agent`,`session_id`);

package/api/dist/drizzle/archive/0004_worried_mojo.sql

@@ -0,0 +1 @@
+ALTER TABLE `sessions` ADD `project` text;

package/api/dist/drizzle/archive/meta/0000_snapshot.json

@@ -0,0 +1,49 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "d3a95e23-e94b-48eb-b47f-93125fb0c649",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "tables": {
+    "archive_meta": {
+      "name": "archive_meta",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "archive_uuid": {
+          "name": "archive_uuid",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}

package/api/dist/drizzle/archive/meta/0001_snapshot.json

@@ -0,0 +1,73 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "037731f6-9a27-4a72-b757-9ac3c4cedf65",
+  "prevId": "d3a95e23-e94b-48eb-b47f-93125fb0c649",
+  "tables": {
+    "archive_meta": {
+      "name": "archive_meta",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "archive_uuid": {
+          "name": "archive_uuid",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "schema_version": {
+      "name": "schema_version",
+      "columns": {
+        "version": {
+          "name": "version",
+          "type": "integer",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "applied_at": {
+          "name": "applied_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}