chat-logbook 0.2.0 → 0.3.0

package/LICENSE

@@ -1,21 +1,16 @@
-MIT License
+Copyright (C) 2026 Eva Wu
 
-Copyright (c) 2026 Eva Wu
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published by
+the Free Software Foundation, version 3 of the License.
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+The full text of the GNU Affero General Public License version 3
+can be found at: https://www.gnu.org/licenses/agpl-3.0.txt

package/README.md

@@ -1,28 +1,49 @@
 # chat-logbook
 
-A local-first conversation manager for Claude Code.
+> _Where your AI conversations live._
 
-Browse, tag, annotate, and organize your Claude Code conversation history — all from your browser.
+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.
 
-## Features
+> **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).
 
-- **Conversation browser** — Three-column interface (filters | session list | conversation content) for navigating all your Claude Code sessions
-- **Full-text search** — Find conversations by keywords across all projects
-- **Project filtering** — Focus on conversations within a specific project, or view everything at once
-- **Real-time streaming** — Watch active Claude Code conversations update live in your browser via SSE
-- **Collapsible tool calls** — Tool calls are collapsed by default with a one-line summary (e.g., "Read: src/index.ts")
-- **Collapsible thinking blocks** — Thinking blocks are collapsed by default, expandable when you want to inspect Claude's reasoning
-- **Soft delete & restore** — Hide sessions you don't need; restore them anytime
-- **Keyboard shortcuts** — `↑↓` to switch sessions, `/` to search, `Esc` to go back
-- **Dark theme** — Easy on the eyes, consistent with Claude Code's terminal aesthetic
+## About
 
-## Quick Start
+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
+matters, and pick up where you left off.
 
-### Prerequisites
+Nothing leaves your machine. There is no account to create. The original
+files written by your AI tools are never modified.
 
-- Node.js >= 20
+Design principles:
 
-### Usage
+- **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.
+
+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
+
+## Quick start
+
+Requirements: Node.js 20+.
 
 Install globally for a shorter command:
 
@@ -56,19 +77,53 @@ By default, chat-logbook runs on port 3100. Use `PORT=8080 chat-log` to specify
 **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.
 
-## How It Works
+## Architecture
 
-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.
+Monorepo with two workspaces, published as a single npm package:
 
-User-created data (custom titles, tags, annotations, highlights) is stored in a separate SQLite database at `~/.chat-logbook/data.db`, using the session ID as the link between the two data sources.
+| 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 |
 
-Because chat-logbook relies on what Claude Code persists to disk, **only conversations that are written to `~/.claude/` are visible**. Ephemeral interactions that Claude Code does not persist (such as `/btw` side questions) are not captured by Claude Code's storage and therefore cannot be displayed.
+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.
 
-## FAQ
+### 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.
+
+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.
+
+## Development
+
+Requirements: Node.js 20+ and pnpm 10+.
+
+```bash
+git clone https://github.com/evaaaaawu/chat-logbook.git
+cd chat-logbook
+pnpm install
+pnpm dev
+```
+
+### Scripts
+
+| 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                           |
 
-### Is my data safe?
+A Husky `pre-commit` hook runs Prettier on staged files, type-checks, and runs
+the test suite on every commit.
 
-Yes. chat-logbook is fully local — no data ever leaves your machine. It only **reads** from `~/.claude/` and never modifies your original conversation files. The SQLite database it creates for your tags, annotations, and other metadata is stored separately at `~/.chat-logbook/`.
+## FAQ
 
 ### Does chat-logbook work with Claude Code on the web?
 
@@ -76,17 +131,62 @@ No. chat-logbook reads from local `~/.claude/` files, which are only created by
 
 ### Why can't I see my `/btw` conversations?
 
-The `/btw` feature in Claude Code is designed to be ephemeral — questions and answers appear in a temporary overlay and are never written to conversation history files. Since chat-logbook reads from these files, `/btw` exchanges are not available.
-
-This is by design: `/btw` is intended for quick, throwaway questions. If you want a conversation to be preserved and visible in chat-logbook, use a regular message instead of `/btw`.
+`/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`.
 
 ## Roadmap
 
-- **Title editing** — Customize session titles for easier identification
-- **Tag system** — Add color-coded tags to sessions, filter by multiple tags (AND logic)
-- **Annotations** — Add notes next to any message in a conversation
-- **Highlights** — Mark important text within conversations
+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).
+
+Work is grouped into release milestones:
+
+### [v0.3.0 — Spotlight Alpha](https://github.com/evaaaaawu/chat-logbook/milestone/1)
+
+- **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
+
+### [v0.4.0 — Spotlight v1](https://github.com/evaaaaawu/chat-logbook/milestone/2)
+
+- **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
+
+### [v0.5.0 — Cross-vendor foundation](https://github.com/evaaaaawu/chat-logbook/milestones)
+
+- **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
+
+### Later
+
+- **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)
+
+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.
 
 ## License
 
-[MIT](LICENSE)
+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.
+
+For commercial licensing inquiries, please contact the author.

package/api/dist/drizzle/0000_safe_slapstick.sql

@@ -0,0 +1,6 @@
+CREATE TABLE `sessions_meta` (
+	`session_id` text PRIMARY KEY NOT NULL,
+	`is_deleted` integer DEFAULT false NOT NULL,
+	`created_at` integer NOT NULL,
+	`updated_at` integer NOT NULL
+);

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

@@ -0,0 +1,57 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "bc9f920f-c5a0-4f4f-b813-9ea2c69e0f7e",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "tables": {
+    "sessions_meta": {
+      "name": "sessions_meta",
+      "columns": {
+        "session_id": {
+          "name": "session_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "is_deleted": {
+          "name": "is_deleted",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false,
+          "default": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_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/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "sqlite",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "6",
+      "when": 1777980160883,
+      "tag": "0000_safe_slapstick",
+      "breakpoints": true
+    }
+  ]
+}