{
  "markdown": "# claude-sqlite-plugin\n\nhttps://github.com/user-attachments/assets/cb254f18-082b-4fe6-99d9-763d7dcd185f\n\n\nEmbedded conversation viewer **and MCP search server** for Claude Code. Never lose a conversation, never lose context, even when your network drops mid-session or anthropic suddenly goes bankrupt after IPO😅.\n\n> **Renamed in v0.2.1.** The project was originally `claude-postgres-plugin` (PostgreSQL-backed). v0.2 swapped the database for embedded SQLite (WAL + FTS5) — no daemon, no `createdb`, no separate database service — and v0.2.1 renamed everything user-visible to match: plugin id `claude-sqlite-plugin`, MCP server `claude-sqlite`, slash commands `/csp-*`. If you installed v0.2.0 under the old name, run `/plugin uninstall claude-postgres-plugin@songtonyli-plugins` then reinstall under the new name. The old GitHub URL still redirects.\n\n## The problem this solves\nYou want to copy some conversations from Claude Code to other AI agent to resume the work. \n\nYou SSH into a remote dev box and kick off a long Claude Code \"vibe coding\" session. Two hours in, your home Wi-Fi flakes for 30 seconds. The SSH connection dies. You reconnect, run:\n\n```bash\nclaude --resume\n```\n\n…and Claude immediately **autocompacts** because the conversation grew large. Half the context — the careful back-and-forth where you nailed down the architecture, the failing test runs, the prompt that finally worked — gets squashed into a one-paragraph summary. The detail is gone.\n\nSame story with: laptop sleep dropping the SSH tunnel, a `tmux` session that didn't survive a reboot, an `iTerm` crash, a cellular hotspot blip on the train.\n\nYou can take a look at the JSONL file where Claude Code writes to `~/.claude/projects/`, and you will be surprised that not every conversation, tool result, or assistant answers are saved! But by default, you have no good way to search it, browse it, or hand the relevant slice back to a fresh Claude session — so `--resume` and its autocompact are your only options.\n\nThis plugin fixes that:\n\n- **A real-time watcher** ingests every message into a local SQLite database the moment Claude Code writes it to disk. ACID-safe via WAL + `synchronous = FULL` + foreign keys. No transaction is ever lost, even if the parent terminal dies.\n- **A web dashboard** at `http://localhost:3456` lets you browse, search, and export every past session — text, tool calls, thinking blocks, **and image / document attachments** rendered exactly as they appeared.\n- **An MCP server** ships with the plugin so Claude itself can search your conversation history during a new session: *\"what did we try for the rate-limiter bug last week?\"* → Claude calls the `search_messages` tool → answers with real evidence from your past work.\n\n## How it works\n\n```\nYou use claude normally           This plugin runs in background\n        |                                    |\n        v                                    v\n  claude-code writes                  fs.watch detects\n  ~/.claude/projects/*.jsonl    -->   every changes in CLI\n                                             |\n                                             v\n                                    Parser extracts messages,\n                                    tool calls, thinking, images\n                                             |\n                                             v\n                                    SQLite stores everything\n                                    (WAL + FTS5, ACID safe)\n                                             |\n                              +-----------------------------+\n                              |                             |\n                              v                             v\n                  Web dashboard at :3456           MCP tools for Claude\n                  (humans browse visually)         (Claude searches via\n                                                    search_messages, etc.)\n```\n\n## Two ways to install\n\n### Option A — As a Claude Code plugin (recommended)\n\nThis bundles the MCP server, the slash commands, and the watcher all in one install.\n\n```text\n/plugin marketplace add SongTonyLi/claude-sqlite-plugin\n/plugin install claude-sqlite-plugin@songtonyli-plugins\n```\n\n**Prerequisites**: Bun installed (`curl -fsSL https://bun.sh/install | bash`). That's it — **no Postgres, no `createdb`, no database service to manage**. The DB is a single SQLite file under `~/.claude-sqlite-plugin/csp.sqlite` (or `${CLAUDE_PLUGIN_DATA}` if Claude Code provides one).\n\n**Dependencies are installed automatically** on the first MCP server start — no manual `bun install` required. If you also want the web dashboard, build the frontend once:\n\n```bash\n# Replace the path below with whatever /plugin install reported, typically:\ncd ~/.claude/plugins/cache/songtonyli-plugins/claude-sqlite-plugin/0.2.3\n\n(cd web && bun install && bun --bun vite build)      # frontend bundle (only needed if you'll use the dashboard)\n```\n\nThat's it. From any Claude Code session you now have:\n\n**MCP tools** Claude can call autonomously (no slash command needed — Claude picks them up from the `claude-sqlite` MCP server when relevant):\n\n| Tool | What it does |\n|---|---|\n| `list_recent_sessions` | List the user's most recent sessions |\n| `search_messages` | Fuzzy or regex search across all conversation messages |\n| `get_session` | Fetch a session's metadata by id |\n| `get_session_messages` | Fetch the message transcript |\n| `get_session_tool_calls` | List all tool calls made in a session |\n\n**Slash commands** for direct invocation:\n\n| Command | What it does |\n|---|---|\n| `/csp-search <phrase>` | Fuzzy-search past sessions and show top matches with session IDs |\n| `/csp-recent [count]` | List the most recent N sessions (default 10) |\n| `/csp-session <id> [N]` | Show metadata + last N messages for a session |\n| `/csp-resume [phrase]` | Resume from any point in any past conversation — picks up full context that autocompact destroyed |\n| `/csp-start` | Start the watcher + web dashboard in the background |\n| `/csp-status` | Health check — verify plugin is connected, show DB stats |\n\n### Option B — Standalone (no Claude Code plugin)\n\nUse this if you want only the dashboard and don't need MCP integration.\n\n**Prerequisite**: Bun. That's literally it. (No Postgres. No `createdb`. No service to start.)\n\n**Setup**\n\n```bash\ngit clone https://github.com/SongTonyLi/claude-sqlite-plugin.git\ncd claude-sqlite-plugin\nbun install\n(cd web && bun install && bun --bun vite build)\nbun run src/index.ts import        # import existing sessions (creates the SQLite file on first run)\nbun run src/index.ts start         # watch + serve dashboard\n```\n\nOpen **http://localhost:3456**.\n\nThe SQLite file is created automatically at `~/.claude-sqlite-plugin/csp.sqlite` on first run. Override the location with `CSP_DB_PATH` or `CSP_DATA_DIR`.\n\n## Quick examples\n\n```bash\n# Start watcher + dashboard (plugin)\n/csp-start\n\n# Start watcher + dashboard (standalone)\nbun run src/index.ts start       # then open http://localhost:3456\n\n# Search past conversations from inside Claude Code\n/csp-search rate limiter bug\n\n# List recent sessions\n/csp-recent 20\n\n# Inspect a specific session\n/csp-session a745301c\n\n# Resume with interactive picker (shows numbered selector)\n/csp-resume\n\n# Search \"homework\" → pick one or more sessions → load full context into current conversation\n/csp-resume homework\n\n# Unlike `claude --resume`, this loads the FULL transcript (no autocompact),\n# works cross-project, and lets you combine context from multiple sessions.\n\n# Health check — verify everything is connected\n/csp-status\n\n# Traditional resume (subject to autocompact on large sessions)\nclaude --resume a745301c-fe8a-4f20-97bf-4fda1f1f2ad2\n\n# Ask Claude to search for you (no slash command needed — Claude uses the MCP tools)\n> \"What did we try for the auth middleware rewrite last week?\"\n```\n\n## `/csp-resume` vs `claude --resume`\n\n| | `claude --resume` | `/csp-resume` |\n|---|---|---|\n| **Context** | Autocompacts large sessions into a summary | Loads the **full unabridged transcript** from SQLite |\n| **Scope** | Current project directory only | Any project, any session, cross-directory |\n| **Entry point** | Continues from the end | Load from the beginning, the middle, or any range |\n| **Multi-session** | One session at a time | Select multiple sessions, combine their context |\n| **Images** | Lost after autocompact | Preserved in DB, reloaded as attachments |\n| **Search** | No search (pick from recent list) | Fuzzy search across all message content |\n\n**Example workflow:**\n\n```\n> /csp-resume homework\n\n[1]  Homework: ch5 linear algebra — math301 — yesterday — 34 messages\n[2]  Homework: ch4 eigenvalues — math301 — 3 days ago — 28 messages\n[3]  Homework: ch3 vector spaces — math301 — last week — 41 messages\n\n> 1 2 3\n\n━━━ Loaded 3 sessions (103 messages) ━━━\nCombined context: chapters 3–5 of math301, covering vector spaces,\neigenvalues, and linear algebra. Key results: ...\n\nContext loaded. You can now:\n  (a) Continue this work right here — I have the full context above.\n```\n\nYou now have the full history of all three homework sessions in one conversation — something `claude --resume` simply cannot do.\n\n## Usage\n\n### Real-time browsing\n\nStart the watcher, use Claude Code normally, open `http://localhost:3456`. Messages appear in the dashboard as Claude writes them.\n\n### Search (Cmd+K)\n\n`Cmd+K` / `Ctrl+K` in the dashboard fuzzy-searches every past conversation (FTS5 prefix matching, LIKE fallback). From Claude Code, just ask — Claude calls `search_messages` automatically.\n\n### Images and documents\n\nPasted images, screenshots, PDFs — all extracted from the JSONL and stored in SQLite. Viewable in the dashboard even after autocompact destroys the original context. Click thumbnails for full-size originals.\n\n### Export to XML\n\n**Select** → check messages → **Export XML**. Useful for handing context to a fresh session, archiving, or feeding to other tools.\n\n### Hide sessions\n\nHover a session in the sidebar → click the eye icon. Hidden from the list, still in the DB and searchable.\n\n### CLI commands\n\n```bash\nbun run src/index.ts start   # Watch + dashboard\nbun run src/index.ts web     # Dashboard only (no watcher)\nbun run src/index.ts import  # One-time import of existing sessions\nbun run src/index.ts mcp     # Run as stdio MCP server\nbun test                     # Run tests\n```\n\n### Configuration\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `CSP_DB_PATH` | (see `CSP_DATA_DIR`) | Full path to the SQLite database file. Use `:memory:` for an ephemeral in-process DB (used by tests). |\n| `CSP_DATA_DIR` | `${CLAUDE_PLUGIN_DATA}` if set, else `~/.claude-sqlite-plugin/` | Directory containing `csp.sqlite`. |\n| `CSP_PORT` | `3456` | Dashboard port |\n| `CSP_WEB_DIST` | (auto-resolved) | Override the location of the built web frontend. Auto-discovered relative to the binary or source. |\n\nWhen running as a Claude Code plugin, set these in your shell or `.env` before launching `claude`. The MCP server inherits them.\n\n## Architecture\n\n**Backend**: Bun + TypeScript, embedded SQLite via `bun:sqlite` (zero install), Hono HTTP server, native `fs.watch`\n**MCP server**: bare stdio JSON-RPC, no extra dependencies, reuses the same `ConversationStore`\n**Frontend**: React 19 + Tailwind CSS v4 + Vite, Open WebUI-inspired layout\n**Database**: 4 tables (`sessions`, `messages`, `tool_calls`, `raw_events`) plus a `messages_fts` FTS5 virtual table. WAL journal mode + `synchronous = FULL` + `foreign_keys = ON` for full ACID + multi-process safety (one writer, many readers, snapshot isolation across processes)\n**Distribution**: standard `bun run` for v0.2; single-binary `bun build --compile` opt-in (`bun run build` produces `bin/csp`); v0.3 will ship per-platform binaries via GitHub Releases\n\n## Current Status\n\n- [x] **v0.2.1: rename to `claude-sqlite-plugin`** — plugin id, MCP server, slash commands, env vars, default DB path all renamed away from `cpg`/`claude-postgres` to match the SQLite reality\n- [x] **v0.2: SQLite swap** — dropped PostgreSQL dep entirely, embedded WAL + FTS5\n- [x] Schema + migrations (ACID via WAL + `synchronous = FULL` + foreign keys)\n- [x] Session file watcher (real-time detection)\n- [x] Ingest pipeline (race-condition safe, deduplication)\n- [x] REST API + SSE real-time streaming\n- [x] Web dashboard (Open WebUI style — sidebar + chat view)\n- [x] Inline tool call and tool result rendering\n- [x] Image / document attachment preservation and serving\n- [x] Global search with FTS5 prefix matching + LIKE fallback (Cmd+K)\n- [x] XML export of selected messages\n- [x] Session hiding\n- [x] Message selection with checkboxes\n- [x] MCP server with 5 search/inspect tools\n- [x] Slash commands: `/csp-search`, `/csp-recent`, `/csp-session`, `/csp-resume`, `/csp-start`, `/csp-status`\n- [x] Single-plugin marketplace catalog\n- [x] `bun build --compile` produces a working single binary (96 MB, platform-specific)\n- [x] 25 tests passing against `:memory:` SQLite\n\n## Next Steps\n\n1. **v0.3 — pre-built per-platform binaries via GitHub Releases** — drops the Bun runtime requirement entirely; truly zero-dep `/plugin install`\n2. **Live session streaming** — real-time message appearance in dashboard via SSE during active sessions\n3. **Session metadata panel** — model, token usage, duration, tool stats\n4. **Conversation branching** — visualize sidechain/forked conversations\n5. **Unhide UI** — settings page to manage hidden sessions\n6. ~~**Auto-resume helper** — slash command that builds a context bundle from a past session for resuming without autocompact loss~~ ✅ Shipped as `/csp-resume`\n",
  "bytes": 13678,
  "sha": "cf3fc62bc41672274bd0e203f07a6b36f55145db6e9f156c09d7f15ba2936a9d",
  "repo_slug": "songtonyli/claude-sqlite-plugin",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_songtonyli_claude_sqlite_plugin_claude_s_2c984a56/readme"
}