@clauderecallhq/cli 0.0.1 → 0.12.0

package/README.public.md

@@ -0,0 +1,523 @@
+<div align="center">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="marketing/logos/wordmark-dark.svg">
+  <source media="(prefers-color-scheme: light)" srcset="marketing/logos/wordmark-light.svg">
+  <img src="marketing/logos/wordmark-dark.svg" alt="Claude Recall" width="400">
+</picture>
+
+<br />
+<br />
+
+**Stop re-explaining your project to Claude every morning.**
+
+Claude Recall indexes every Claude Code session you've ever run, surfaces what matters,<br />and pipes the right context back in with one command.
+
+<br />
+
+[![npm](https://img.shields.io/npm/v/@clauderecallhq/cli?style=flat-square&color=f97316&label=npm)](https://www.npmjs.com/package/@clauderecallhq/cli)
+[![Node](https://img.shields.io/badge/node-%E2%89%A522-43853d?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/typescript-strict-3178c6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Local-first](https://img.shields.io/badge/local--first-127.0.0.1%20only-0b0c0f?style=flat-square)](#privacy--security)
+[![License](https://img.shields.io/badge/license-proprietary-1a1a2e?style=flat-square)](#license)
+[![Site](https://img.shields.io/badge/clauderecall.com-f97316?style=flat-square&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IndoaXRlIiBzdHJva2Utd2lkdGg9IjIiPjxjaXJjbGUgY3g9IjEyIiBjeT0iMTIiIHI9IjEwIi8+PGxpbmUgeDE9IjIiIHkxPSIxMiIgeDI9IjIyIiB5Mj0iMTIiLz48cGF0aCBkPSJNMTIgMmExNS4zIDE1LjMgMCAwIDEgNCAxMCAxNS4zIDE1LjMgMCAwIDEtNCA4IDEwIi8+PC9zdmc+)](https://clauderecall.com)
+
+<br />
+
+<sub>100% local. No cloud. No account. No telemetry. Your conversations never leave your machine.</sub>
+
+</div>
+
+<br />
+
+---
+
+<br />
+
+## The Problem
+
+Claude Code is incredible until the conversation ends. Then you hit three walls:
+
+<table>
+<tr>
+<td width="33%" valign="top">
+
+### Context Amnesia
+
+Every new `claude` invocation starts from zero. You re-explain the architecture, re-paste the key files, re-describe the bug you already fixed yesterday.
+
+You built that context pyramid once. Now you're building it again.
+
+</td>
+<td width="33%" valign="top">
+
+### Cost Blindness
+
+Claude Code tells you nothing about spend after a session ends. Which session burned through tokens? Which project is quietly eating half your Anthropic bill?
+
+You're guessing.
+
+</td>
+<td width="33%" valign="top">
+
+### Session Sprawl
+
+Claude Code scatters conversations into `~/.claude/projects/**/*.jsonl`. No titles. No search. No way to find the session where you finally got the auth flow right.
+
+Dozens of projects. Hundreds of sessions. Zero discoverability.
+
+</td>
+</tr>
+</table>
+
+<br />
+
+## The Fix
+
+```bash
+npm install -g @clauderecallhq/cli
+recall start
+recall open
+```
+
+That's it. Recall indexes every past and future Claude Code session into a searchable local database, gives you a beautiful web UI to explore them, and lets you pipe any session back into a new conversation:
+
+```bash
+# The moat: past session -> new conversation
+recall context abc12345 | claude
+```
+
+Claude picks up where you left off instead of asking you to explain it again.
+
+<br />
+
+---
+
+<br />
+
+## Features
+
+<table>
+<tr>
+<td width="50%" valign="top">
+
+### Search Everything
+Full-text search across 100,000+ messages in milliseconds. BM25 ranking, highlighted snippets, inline `#tag` filters.
+
+```bash
+recall search "zod schema"
+recall search "auth #auth-fix"
+```
+
+</td>
+<td width="50%" valign="top">
+
+### Context Re-injection
+The core feature. Pipe any past session into a new Claude Code conversation as condensed markdown. Runs locally, never touches the network.
+
+```bash
+recall context <id> | claude
+recall context <id> --prelude "continue this" | claude
+```
+
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top">
+
+### Cost Analytics
+Per-session and per-project token + dollar totals. Daily sparkline. Top-10 heaviest sessions. Know exactly where your Anthropic bill is going.
+
+```bash
+recall stats <id>
+recall stats --project Tools
+recall stats --days 7
+```
+
+</td>
+<td width="50%" valign="top">
+
+### Git Correlation
+Every session links to commits authored in its working directory during its time window. Reverse-map any commit back to the session that produced it.
+
+```bash
+recall correlate
+recall blame <sha>
+```
+
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top">
+
+### Semantic Search
+Conceptual search powered by your local `claude` CLI. Find "the session where I debugged the worker memory leak" without remembering exact words.
+
+```bash
+recall semantic on
+recall semantic backfill
+```
+
+</td>
+<td width="50%" valign="top">
+
+### MCP Server
+Expose Recall to Claude Desktop, Claude Code, or any MCP client as native tools. Read-only by default, opt-in write tools with rate limiting and audit logging.
+
+```bash
+recall mcp
+recall mcp --allow-writes
+```
+
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top">
+
+### Collections & Tags
+Hand-curated hierarchical groupings of sessions that cut across projects. Human-readable aliases. Auto-tagging via your Anthropic API key or Claude CLI (zero extra cost).
+
+</td>
+<td width="50%" valign="top">
+
+### Web UI
+Beautiful dark-mode three-pane layout. Virtualized transcript rendering (10,000-message sessions open instantly). `Cmd+K` command palette. Multi-select. Export to markdown, HTML, or PDF.
+
+</td>
+</tr>
+</table>
+
+<br />
+
+<details>
+<summary><strong>More: VS Code extension, cross-session diff, onboarding, keyboard shortcuts...</strong></summary>
+
+<br />
+
+- **VS Code / Cursor / Windsurf extension** -- auto-names sessions using terminal tab names via process-tree matching
+- **Cross-session diff** -- split view of two transcripts with shareable `cmp=` URL
+- **First-run onboarding** -- a 3-step tour that demos the moat in the first 60 seconds
+- **Multi-select sessions** -- `Cmd+Click` to toggle, `Shift+Click` for range, right-click to copy IDs
+- **Export** -- condensed markdown, full markdown, self-contained dark-mode HTML, print-ready PDF
+- **Cmd+K command palette** -- jump to any session, action, or setting in one keystroke
+
+#### Keyboard Shortcuts
+
+| Key | Action |
+|---|---|
+| `/` | Focus search |
+| `?` | Open Command Center |
+| `Cmd+K` / `Ctrl+K` | Command palette |
+| `Esc` | Close / clear / dismiss |
+| `n` / `p` | Next / previous search match |
+| `c` | New collection |
+| `Cmd+Shift+A` | Add session to collection |
+| `Cmd+Enter` | Save note |
+
+</details>
+
+<br />
+
+---
+
+<br />
+
+## Quick Start
+
+### Install
+
+```bash
+npm install -g @clauderecallhq/cli
+```
+
+### Start
+
+```bash
+# Start the background daemon (file watcher + local HTTP server)
+recall start
+
+# Open the web UI
+recall open
+```
+
+The daemon watches `~/.claude/projects/` for new and changed session files, indexes them into a local SQLite database at `~/.recall/db.sqlite`, and serves the web UI on a random `127.0.0.1` port.
+
+### Explore
+
+```bash
+recall projects           # list projects with session counts
+recall list               # 30 most-recent sessions
+recall list -p Tools      # filter by project
+recall show <id>          # pretty-printed transcript
+recall search "auth bug"  # full-text search
+```
+
+### The Moat
+
+```bash
+# Pipe a past session into a new Claude Code conversation
+recall context abc12345 | claude
+
+# With a custom instruction
+recall context abc12345 --prelude "continue where we left off" | claude
+
+# Just the last 2 hours
+recall context abc12345 --since 2h | claude
+```
+
+### MCP Server
+
+Point any MCP client at Recall and the model calls it as native tools:
+
+```json
+{
+  "mcpServers": {
+    "recall": {
+      "command": "claude-recall-mcp"
+    }
+  }
+}
+```
+
+<details>
+<summary><strong>Available MCP tools</strong></summary>
+
+<br />
+
+**Read-only (always available):**
+
+| Tool | Purpose |
+|---|---|
+| `list_projects` | Every indexed project |
+| `list_sessions` | Recent sessions, filterable by project / tag / date |
+| `list_tags` | Tag cloud with counts |
+| `search` | Full-text search with `#tag` support |
+| `get_session` | Full transcript (accepts 8+ char id prefix) |
+| `context_for_session` | Condensed markdown export |
+
+**Write tools (opt-in via `--allow-writes`):**
+
+| Tool | Purpose |
+|---|---|
+| `add_tag` / `remove_tag` | Organize sessions from inside Claude |
+| `set_alias` | Rename a session |
+| `append_note` | Add to a session's markdown note |
+| `create_collection` | Create a new collection |
+| `add_session_to_collection` | Curate memberships |
+
+All writes are rate-limited, zod-validated, and audited.
+
+</details>
+
+<br />
+
+---
+
+<br />
+
+## How It Works
+
+```
+~/.claude/projects/**/*.jsonl   <-- Claude Code's session files (read-only)
+        |
+        v  chokidar file watcher
+~/.recall/db.sqlite             <-- indexed database (FTS5 full-text search)
+        |
+  +-----+-----+
+  |           |
+  CLI         HTTP server (Hono, 127.0.0.1 only)
+  |           |
+  recall ...  Web UI (React + Tailwind SPA)
+```
+
+### Data stays local
+
+| Path | What |
+|---|---|
+| `~/.recall/db.sqlite` | Indexed database (projects, sessions, messages, FTS5, aliases, notes, tags, collections, semantic summaries, commit links, usage rollups, audit logs) |
+| `~/.recall/aliases.json` | Plain-text mirror of every alias with full edit history |
+| `~/.recall/notes/<session>.md` | One markdown file per session note |
+| `~/.recall/tags.json` | Current tag state + append-only event log |
+| `~/.recall/collections.json` | Current tree state + append-only event log |
+
+<br />
+
+---
+
+<br />
+
+## Privacy & Security
+
+Claude Recall is **local-first by design**, not as an afterthought.
+
+- The daemon binds to **`127.0.0.1` only**. Never `0.0.0.0`, never a public interface.
+- **No telemetry.** No analytics. No outbound network calls. The only exception is a one-time license check when you activate a Pro key.
+- **No cloud. No account.** Your data lives at `~/.recall/` and nowhere else.
+- **Source sessions are never modified.** Claude Code's JSONL files at `~/.claude/projects/` are strictly read-only to Recall.
+- **Never-delete-data invariant.** Every write enforces three independent durability layers: SQLite with history columns, plain-text mirror on disk, and source JSONLs untouched. Renaming, clearing, or removing anything is always additive -- the prior value is archived, never destroyed.
+
+<br />
+
+---
+
+<br />
+
+## Full CLI Reference
+
+<details>
+<summary><strong>Click to expand</strong></summary>
+
+<br />
+
+```bash
+# Lifecycle
+recall start              # start daemon (watcher + local HTTP)
+recall stop               # stop daemon
+recall open               # open web UI (starts daemon if needed)
+recall status             # db + daemon health
+
+# Indexing
+recall index              # scan for new/changed session files
+recall index --force      # reindex everything
+
+# Explore
+recall projects           # list projects with session counts
+recall list               # 30 most-recent sessions
+recall list -p Tools      # filter by project substring
+recall list -n 100        # higher limit
+
+# Read
+recall show <id>          # pretty transcript, auto-paged
+recall show <id> --raw    # raw JSONL
+recall show <id> --no-pager
+
+# Search
+recall search "zod schema"
+recall search "auth" -p Pest-Control
+recall search bug -n 50
+
+# Context re-injection
+recall context <id>                              # condensed markdown
+recall context <id> | pbcopy                     # to clipboard (macOS)
+recall context <id> | claude                     # into new Claude session
+recall context <id> --full                       # full transcript
+recall context <id> --since 2h                   # last 2 hours only
+recall context <id> --prelude "continue this"    # prepend instruction
+recall context <id> --subagents                  # include subagent messages
+
+# Stats
+recall stats <id>              # tokens + dollars for one session
+recall stats --project Tools   # per-project rollup
+recall stats --days 7          # 7-day overview
+recall stats --backfill        # one-shot usage backfill
+
+# Git correlation
+recall correlate               # link sessions to commits
+recall blame <sha>             # commit -> session reverse lookup
+
+# Semantic search
+recall semantic on             # enable conceptual search
+recall semantic status         # backfill progress
+recall semantic backfill       # run now
+
+# MCP server
+recall mcp                     # stdio, read-only
+recall mcp --allow-writes      # opt-in write tools
+```
+
+</details>
+
+<br />
+
+---
+
+<br />
+
+## Tech Stack
+
+| Layer | Technology |
+|---|---|
+| CLI + daemon | TypeScript 5 (strict), Node 22+, ESM |
+| HTTP server | Hono + @hono/node-server |
+| Database | better-sqlite3 with FTS5 full-text search |
+| File watcher | chokidar |
+| CLI parsing | commander |
+| MCP server | @modelcontextprotocol/sdk (stdio) |
+| Validation | zod |
+| Web UI | Vite 8 + React 19 + Tailwind CSS |
+| Data fetching | @tanstack/react-query |
+| Virtualization | @tanstack/react-virtual |
+| Markdown | marked + highlight.js + DOMPurify |
+
+<br />
+
+---
+
+<br />
+
+## Pricing
+
+| | Free | Pro |
+|---|---|---|
+| **Search** | Unlimited | Unlimited |
+| **Context re-injection** | Unlimited | Unlimited |
+| **Sessions indexed** | Unlimited | Unlimited |
+| **Cost analytics** | Unlimited | Unlimited |
+| **Git correlation** | Unlimited | Unlimited |
+| **MCP server** | Read-only | Read + Write |
+| **Semantic search** | -- | Included |
+| **Auto-tagging** | -- | Included |
+| **Price** | $0 | **$29.69 one-time** |
+
+No subscriptions. No recurring fees. Pay once, own it forever.
+
+<br />
+
+---
+
+<br />
+
+## Roadmap
+
+- [x] CLI, daemon, web UI, full-text search
+- [x] Context re-injection (the moat)
+- [x] Aliases, notes, tags, pins
+- [x] Cross-session diff
+- [x] VS Code / Cursor / Windsurf extension
+- [x] MCP server (read-only)
+- [x] Collections (hierarchical, cross-project)
+- [x] Auto-tagging
+- [x] Cost / token analytics
+- [x] Git correlation
+- [x] Semantic search
+- [x] Cmd+K command palette
+- [x] Bidirectional MCP write tools
+- [x] First-run onboarding
+- [ ] Public launch at clauderecall.com
+- [ ] Team features
+
+<br />
+
+---
+
+<br />
+
+<div align="center">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="marketing/logos/mark-scrollback-dark.svg">
+  <img src="marketing/logos/mark-scrollback-dark.svg" alt="Claude Recall" width="48">
+</picture>
+
+<br />
+<br />
+
+**Claude Recall** -- the memory layer for the agent you're steering.
+
+[Website](https://clauderecall.com) &nbsp;&middot;&nbsp; [Install](https://www.npmjs.com/package/@clauderecallhq/cli) &nbsp;&middot;&nbsp; [Issues](https://github.com/citizencapet/claude-recall/issues)
+
+<br />
+
+<sub>Built by <a href="https://github.com/citizencapet">@citizencapet</a></sub>
+
+</div>