session-sidekick 0.1.0__py3-none-any.whl

session_sidekick-0.1.0.dist-info/METADATA

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: session-sidekick
+Version: 0.1.0
+Summary: Search your Claude Code sessions and get semantic recall hints as you type
+Project-URL: Homepage, https://github.com/AravindKurapati/session-sidekick
+Project-URL: Issues, https://github.com/AravindKurapati/session-sidekick/issues
+Author: Aravind Kurapati
+License: MIT
+License-File: LICENSE
+Keywords: anthropic,claude,claude-code,cli,hooks,recall,search,semantic,sessions
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: fastembed>=0.4
+Requires-Dist: platformdirs>=4.2
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: titler
+Requires-Dist: anthropic>=0.40; extra == 'titler'
+Description-Content-Type: text/markdown
+
+# session-sidekick
+
+> **Stop re-explaining context you've already worked through.**
+
+A local CLI + Claude Code hook that indexes all your past sessions and surfaces relevant ones as you type — before you accidentally redo work you've already done.
+
+---
+
+## The problem this solves
+
+Claude Code sessions are ephemeral. Every time you start a new one, Claude has no memory of the three hours you spent debugging the same Modal deployment last week, or the exact vLLM flag you figured out, or how you structured that RAG pipeline.
+
+You either:
+- Re-explain everything from scratch every session (slow)
+- Search through raw JSONL files manually (painful)
+- Forget you solved it and solve it again (expensive)
+
+Session-sidekick fixes this with two pieces:
+
+1. **A recall hook** — fires on every prompt via `UserPromptSubmit`. Runs semantic search against all your past sessions. If it finds a confident match, it prints a one-line hint before Claude sees your message: `💡 You did this before — session abc12345: add modal vllm endpoint`
+
+2. **A search CLI** — keyword + semantic + combined search across every session you've ever had. `sidekick search "modal deployment"` ranks results by relevance, not just recency.
+
+Everything is local. No API keys. No data leaves your machine.
+
+---
+
+## Install
+
+```bash
+pip install session-sidekick
+```
+
+Or from source:
+```bash
+git clone https://github.com/AravindKurapati/session-sidekick
+cd session-sidekick
+pip install -e .
+```
+
+**Requirements:** Python 3.11+ — no API keys needed.
+
+---
+
+## Quick start
+
+```bash
+# Index your Claude Code sessions (reads ~/.claude/projects/)
+sidekick reindex
+
+# Build semantic embeddings (one-time, ~1-2 min)
+sidekick embed
+
+# Check what got indexed
+sidekick stats
+
+# Search
+sidekick search "modal vllm"
+sidekick search "react state management" --mode fts
+sidekick list --project my-project
+sidekick show abc12345 --full
+```
+
+---
+
+## Live recall hook (the main feature)
+
+The recall hook injects a past-session hint into your terminal at the moment you submit a prompt to Claude Code — giving you context before Claude even sees your message.
+
+**Setup:**
+
+```bash
+# 1. Install the hooks into ~/.claude/settings.json
+sidekick install-hooks --apply
+
+# 2. Start the daemon (keeps the embedding model warm for fast recall)
+sidekick-daemon
+```
+
+The daemon needs to be running for recall to work. Add it to your shell startup to keep it always-on:
+
+```bash
+# ~/.zshrc or ~/.bashrc
+sidekick-daemon &>/dev/null &
+```
+
+**How it looks:**
+
+```
+You: fix the vllm timeout on modal
+
+💡 You may have done this before — session a3f2b1c8 (2026-04-28): debug modal vllm timeout
+   Set request_timeout=120 in the Modal endpoint config, not in the vLLM args.
+   Tags: modal,vllm,timeout
+   Resume with: claude --resume a3f2b1c8
+
+Claude: ...
+```
+
+The hint only appears when the confidence score exceeds the threshold (default 0.78). Silent otherwise — it never interrupts you.
+
+---
+
+## All commands
+
+| Command | What it does |
+|---------|-------------|
+| `reindex` | Incrementally scan `~/.claude/projects/*.jsonl` |
+| `embed` | Build/update semantic embeddings for unembedded turns |
+| `stats` | Sessions, turns, embeddings count + DB path |
+| `list` | Browse sessions (`--project`, `--status`, `--limit`) |
+| `search` | Keyword + semantic search (`--mode fts\|semantic\|combined`) |
+| `show` | Full session detail by id (`--full` for all turns) |
+| `install-hooks` | Print or apply hook config (`--apply` to patch settings.json) |
+| `stop-hook` | Run by Claude Code Stop event — reindex + embed |
+
+---
+
+## How it works
+
+```
+~/.claude/projects/**/*.jsonl
+        ↓  sidekick reindex
+   SQLite (WAL) + FTS5
+        ↓  sidekick embed
+   MiniLM embeddings (384d, ONNX, local)
+        ↓  sidekick-daemon
+   TCP socket server (Windows) / Unix socket (macOS/Linux)
+        ↓  UserPromptSubmit hook → sidekick-recall
+   Cosine similarity → hint printed if score > 0.78
+```
+
+- **Index:** `~/.session-sidekick/index.db` — SQLite with FTS5 full-text and raw float32 embeddings
+- **Model:** `sentence-transformers/all-MiniLM-L6-v2` via fastembed (ONNX, ~80MB, downloads once)
+- **Search:** FTS5 keyword, cosine similarity semantic, or RRF-fused combined
+- **Recall budget:** 300ms timeout — silent if daemon is slow or down, never blocks Claude Code
+
+---
+
+## Data & privacy
+
+- All data stays local at `~/.session-sidekick/`
+- Only reads `~/.claude/projects/` — never writes to it
+- No network calls (the optional titler uses Anthropic's API but is disabled by default)
+- The daemon runs on localhost only
+
+---
+
+## Optional: session titler
+
+If you want auto-generated titles for sessions (requires `ANTHROPIC_API_KEY`):
+
+```bash
+pip install "session-sidekick[titler]"
+ANTHROPIC_API_KEY=... sidekick-titler
+```
+
+Calls Claude Haiku (~$0.0005 per session). Titles are stored locally and shown in `sidekick list`.
+
+---
+
+## License
+
+MIT

session_sidekick-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+sidekick/__init__.py,sha256=QTYqXqSTHFRkM9TEgpDFcHvwLbvqHDqvqfQ9EiXkcAM,23
+sidekick/__main__.py,sha256=kiU1ZwEt06j4cTHQ6fnFHCuX5MZx4x8ni25PJVWOzOk,73
+sidekick/cli.py,sha256=IbW018nt36VtIXjVtibaISygiSoSlX8X3Z7XhbtJQMs,4644
+sidekick/daemon.py,sha256=ZvJA3j96l5gUrDSc-woEH2EyJFRuZtNlIUpkpTtib-k,4306
+sidekick/db.py,sha256=EL2HvJFABk4D3XkQwDK189TzExtXDFNqM_afkCnFNBE,1817
+sidekick/embeddings.py,sha256=cQz12jaYkCcpk-RioH_dyrSuFbnOtit80PTQUm-JfD0,1026
+sidekick/hooks.py,sha256=ZX5uCJ6aIsW1QwpBvSPkS2wAFUkc0vpKiXv_8grJdz0,1882
+sidekick/indexer.py,sha256=bSlPvEuMGGgKSmUMcenY8oxEbGmrDKxvrKnlsSjpwy4,4353
+sidekick/parser.py,sha256=obyZdFByKhg-bbP0SCwigAWvcjnn47SM-Fyk_Mhh3Zk,2717
+sidekick/paths.py,sha256=VVS5m3NipulNP1kNOCffIL4eQdYHgwG4Iv31NLw3Ndk,733
+sidekick/recall.py,sha256=6lZ8dwbIhSnhelAAz9deuJjTRFEbWQghvuTKuZmUHTM,2342
+sidekick/search.py,sha256=YjK6PQWAO9FEmF_PRGZwE4Xuq4kgN29RrjM84a_1OnM,3285
+sidekick/titler.py,sha256=CflcQk1eDOnRqwRvcKZppnfN_rfg9SwUCZ2JS-sxhZc,4138
+session_sidekick-0.1.0.dist-info/METADATA,sha256=M-Z2dlZXAhXM856UO2XuBJ4b3e4E-KqOewYS0esfO6k,5982
+session_sidekick-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+session_sidekick-0.1.0.dist-info/entry_points.txt,sha256=34eHFR53wHmm-lWpYUlIbYzmP03bxBg3ouFmzPTFuyQ,164
+session_sidekick-0.1.0.dist-info/licenses/LICENSE,sha256=1jQMZN1uCxe0u_XL7YZOqjvHMHGKwvESVQBlPuDQD80,1094
+session_sidekick-0.1.0.dist-info/RECORD,,

session_sidekick-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

session_sidekick-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+sidekick = sidekick.cli:main
+sidekick-daemon = sidekick.daemon:main
+sidekick-recall = sidekick.recall:main
+sidekick-titler = sidekick.titler:main

session_sidekick-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aravind Kurapati
+
+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:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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.

sidekick/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

sidekick/__main__.py

@@ -0,0 +1,4 @@
+from sidekick.cli import main
+
+if __name__ == "__main__":
+    main()

sidekick/cli.py

@@ -0,0 +1,119 @@
+"""Click CLI: composition root."""
+from __future__ import annotations
+import click
+from sidekick import db, indexer
+from sidekick import search as searchmod
+from sidekick.paths import db_path
+
+@click.group()
+def main() -> None:
+    """session-sidekick: search & recall your Claude Code sessions."""
+
+@main.command()
+def reindex() -> None:
+    """Incrementally index ~/.claude/projects/*.jsonl."""
+    n = indexer.run()
+    click.echo(f"indexed {n} new turn(s)")
+
+@main.command()
+def stats() -> None:
+    """Print database stats."""
+    conn = db.connect()
+    s = conn.execute("SELECT COUNT(*) FROM sessions").fetchone()[0]
+    t = conn.execute("SELECT COUNT(*) FROM turns").fetchone()[0]
+    e = conn.execute("SELECT COUNT(*) FROM embeddings").fetchone()[0]
+    titled = conn.execute(
+        "SELECT COUNT(*) FROM sessions WHERE titled_at IS NOT NULL"
+    ).fetchone()[0]
+    click.echo(f"db: {db_path()}")
+    click.echo(f"sessions: {s} (titled: {titled})")
+    click.echo(f"turns: {t}")
+    click.echo(f"embeddings: {e}")
+
+@main.command(name="list")
+@click.option("--project", default=None, help="Filter by project name (substring).")
+@click.option("--status", default=None, help="completed|abandoned|context_limit|unknown")
+@click.option("--limit", default=20, type=int)
+def list_sessions(project: str | None, status: str | None, limit: int) -> None:
+    """List indexed sessions, most recent first."""
+    conn = db.connect()
+    sql = "SELECT id, project, title, status, ended_at FROM sessions WHERE 1=1"
+    args: list = []
+    if project:
+        sql += " AND project LIKE ?"
+        args.append(f"%{project}%")
+    if status:
+        sql += " AND status=?"
+        args.append(status)
+    sql += " ORDER BY ended_at DESC LIMIT ?"
+    args.append(limit)
+    for sid, proj, title, st, ended in conn.execute(sql, args):
+        click.echo(f"{sid:<36}  {proj:<30}  {st or 'unknown':<12}  {title or '(untitled)'}")
+
+@main.command()
+def embed() -> None:
+    """Embed any turns that don't yet have an embedding."""
+    n = indexer.embed_pending()
+    click.echo(f"embedded {n} turn(s)")
+
+@main.command()
+@click.argument("query")
+@click.option("--project", default=None)
+@click.option("--limit", default=10, type=int)
+@click.option("--mode", type=click.Choice(["fts", "semantic", "combined"]), default="combined")
+def search(query: str, project: str | None, limit: int, mode: str) -> None:
+    """Search across all indexed sessions."""
+    if mode == "fts":
+        hits = searchmod.fts(query, limit=limit, project=project)
+    elif mode == "semantic":
+        hits = searchmod.semantic(query, limit=limit, project=project)
+    else:
+        hits = searchmod.combined(query, limit=limit, project=project)
+    if not hits:
+        click.echo("(no hits)")
+        return
+    for h in hits:
+        score = h.get("score", 0.0)
+        click.echo(f"{h['session_id']:<36}  turn {h['turn_idx']:>3}  score={score:.3f}  {h['project']:<25}  {h['snippet'][:120]}")
+
+@main.command()
+@click.argument("session_id")
+@click.option("--full", is_flag=True, help="Print every turn's text.")
+def show(session_id: str, full: bool) -> None:
+    """Show a session by id (partial id supported)."""
+    conn = db.connect()
+    row = conn.execute(
+        "SELECT id, project, title, summary, tags, status, ended_at FROM sessions WHERE id LIKE ?",
+        (f"{session_id}%",),
+    ).fetchone()
+    if not row:
+        click.echo(f"no session matching {session_id!r}")
+        return
+    click.echo(f"id:      {row[0]}")
+    click.echo(f"project: {row[1]}")
+    click.echo(f"title:   {row[2] or '(untitled)'}")
+    click.echo(f"summary: {row[3] or '-'}")
+    click.echo(f"tags:    {row[4] or '-'}")
+    click.echo(f"status:  {row[5]}")
+    click.echo(f"ended:   {row[6]}")
+    if full:
+        click.echo("---")
+        for tidx, role, text in conn.execute(
+            "SELECT turn_idx, role, text FROM turns WHERE session_id=? ORDER BY turn_idx", (row[0],)
+        ):
+            click.echo(f"[{tidx}] {role}: {text[:300]}")
+
+from sidekick import hooks as hooksmod
+
+@main.command(name="install-hooks")
+@click.option("--apply", is_flag=True, help="Patch ~/.claude/settings.json. Otherwise prints snippet.")
+def install_hooks(apply: bool) -> None:
+    """Print or install the Claude Code hook config."""
+    out = hooksmod.install(apply=apply)
+    click.echo(out)
+
+@main.command(name="stop-hook")
+def stop_hook() -> None:
+    """Run by Claude Code Stop event: incremental index + embed."""
+    indexer.run()
+    indexer.embed_pending(batch_size=64)

sidekick/daemon.py

@@ -0,0 +1,128 @@
+"""Local socket daemon. Unix domain socket on POSIX, TCP localhost on Windows."""
+from __future__ import annotations
+import json
+import os
+import socket
+import sys
+import threading
+from sidekick import db, search
+from sidekick.embeddings import Embedder
+from sidekick.paths import sidekick_dir
+
+CONFIDENCE_THRESHOLD = 0.78
+
+def _socket_address():
+    if sys.platform == "win32":
+        return ("127.0.0.1", 0)
+    return str(sidekick_dir() / "daemon.sock")
+
+class Server:
+    def __init__(self) -> None:
+        self._address = None
+        self._sock: socket.socket | None = None
+        self._thread: threading.Thread | None = None
+        self._stop = threading.Event()
+        self._embedder: Embedder | None = None
+
+    @property
+    def address(self):
+        return self._address
+
+    def start(self) -> None:
+        if sys.platform == "win32":
+            self._sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            self._sock.bind(("127.0.0.1", 0))
+            self._address = self._sock.getsockname()
+            (sidekick_dir() / "daemon.port").write_text(str(self._address[1]))
+        else:
+            path = _socket_address()
+            try:
+                os.unlink(path)
+            except FileNotFoundError:
+                pass
+            self._sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+            self._sock.bind(path)
+            self._address = path
+        self._sock.listen(8)
+        self._sock.settimeout(0.5)
+        self._thread = threading.Thread(target=self._run, daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        self._stop.set()
+        if self._sock:
+            self._sock.close()
+        if self._thread:
+            self._thread.join(timeout=2.0)
+
+    def _run(self) -> None:
+        while not self._stop.is_set():
+            try:
+                conn, _ = self._sock.accept()
+            except (socket.timeout, OSError):
+                continue
+            threading.Thread(target=self._handle, args=(conn,), daemon=True).start()
+
+    def _handle(self, conn: socket.socket) -> None:
+        try:
+            f = conn.makefile("rb")
+            line = f.readline()
+            req = json.loads(line)
+            resp = self._dispatch(req)
+            conn.sendall(json.dumps(resp).encode() + b"\n")
+        except Exception as e:
+            try:
+                conn.sendall(json.dumps({"ok": False, "error": str(e)}).encode() + b"\n")
+            except OSError:
+                pass
+        finally:
+            conn.close()
+
+    def _dispatch(self, req: dict) -> dict:
+        op = req.get("op")
+        if op == "ping":
+            return {"ok": True, "pong": True}
+        if op == "recall":
+            return self._recall(req.get("prompt", ""), req.get("project"))
+        return {"ok": False, "error": f"unknown op: {op}"}
+
+    def _recall(self, prompt: str, project: str | None) -> dict:
+        if not prompt.strip():
+            return {"ok": True, "hit": None}
+        if self._embedder is None:
+            self._embedder = Embedder()
+        hits = search.semantic(prompt, limit=5, project=project)
+        if not hits:
+            return {"ok": True, "hit": None}
+        top = hits[0]
+        if top["score"] < CONFIDENCE_THRESHOLD:
+            return {"ok": True, "hit": None}
+        conn = db.connect()
+        row = conn.execute(
+            "SELECT title, summary, tags, ended_at FROM sessions WHERE id=?",
+            (top["session_id"],),
+        ).fetchone()
+        conn.close()
+        title, summary, tags, ended = row if row else (None, None, None, None)
+        return {
+            "ok": True,
+            "hit": {
+                "session_id": top["session_id"],
+                "score": top["score"],
+                "title": title,
+                "summary": summary,
+                "tags": tags,
+                "ended_at": ended,
+            },
+        }
+
+def main() -> None:
+    """Entry point: `sidekick-daemon`. Runs forever."""
+    srv = Server()
+    srv.start()
+    addr = srv.address
+    print(f"sidekick-daemon listening on {addr}", flush=True)
+    try:
+        srv._thread.join()
+    except KeyboardInterrupt:
+        srv.stop()

sidekick/db.py

@@ -0,0 +1,66 @@
+"""SQLite connection + schema. Lives at ~/.session-sidekick/index.db."""
+from __future__ import annotations
+import sqlite3
+from sidekick.paths import db_path
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS sessions (
+    id TEXT PRIMARY KEY,
+    project TEXT,
+    cwd TEXT,
+    started_at TEXT,
+    ended_at TEXT,
+    title TEXT,
+    summary TEXT,
+    tags TEXT,
+    status TEXT,
+    titled_at TEXT,
+    last_seen_offset INTEGER DEFAULT 0
+);
+
+CREATE TABLE IF NOT EXISTS turns (
+    session_id TEXT NOT NULL,
+    turn_idx INTEGER NOT NULL,
+    role TEXT NOT NULL,
+    text TEXT NOT NULL,
+    timestamp TEXT,
+    input_tokens INTEGER DEFAULT 0,
+    output_tokens INTEGER DEFAULT 0,
+    PRIMARY KEY (session_id, turn_idx)
+);
+
+CREATE TABLE IF NOT EXISTS file_offsets (
+    file_path TEXT PRIMARY KEY,
+    mtime REAL NOT NULL,
+    byte_offset INTEGER NOT NULL,
+    indexed_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS embeddings (
+    session_id TEXT NOT NULL,
+    turn_idx INTEGER NOT NULL,
+    vec BLOB NOT NULL,
+    PRIMARY KEY (session_id, turn_idx)
+);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS turns_fts USING fts5(
+    text,
+    session_id UNINDEXED,
+    turn_idx UNINDEXED,
+    role UNINDEXED,
+    content='turns',
+    content_rowid='rowid'
+);
+
+CREATE INDEX IF NOT EXISTS idx_turns_session ON turns(session_id);
+CREATE INDEX IF NOT EXISTS idx_sessions_project ON sessions(project);
+CREATE INDEX IF NOT EXISTS idx_sessions_titled ON sessions(titled_at) WHERE titled_at IS NULL;
+"""
+
+def connect() -> sqlite3.Connection:
+    conn = sqlite3.connect(db_path(), isolation_level=None)
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("PRAGMA synchronous=NORMAL")
+    conn.execute("PRAGMA foreign_keys=ON")
+    conn.executescript(SCHEMA)
+    return conn

sidekick/embeddings.py

@@ -0,0 +1,30 @@
+"""Embeddings via fastembed (ONNX MiniLM). 384 dims, L2-normalized."""
+from __future__ import annotations
+import numpy as np
+from fastembed import TextEmbedding
+
+MODEL_NAME = "sentence-transformers/all-MiniLM-L6-v2"
+
+class Embedder:
+    def __init__(self) -> None:
+        self._model = TextEmbedding(model_name=MODEL_NAME)
+        self.dim = 384
+
+    def embed_one(self, text: str) -> np.ndarray:
+        v = next(iter(self._model.embed([text])))
+        v = v.astype(np.float32)
+        n = np.linalg.norm(v)
+        return v / n if n > 0 else v
+
+    def embed_many(self, texts: list[str]) -> np.ndarray:
+        out = list(self._model.embed(texts))
+        arr = np.stack([v.astype(np.float32) for v in out])
+        norms = np.linalg.norm(arr, axis=1, keepdims=True)
+        norms[norms == 0] = 1.0
+        return arr / norms
+
+def to_blob(v: np.ndarray) -> bytes:
+    return v.astype(np.float32).tobytes()
+
+def from_blob(b: bytes) -> np.ndarray:
+    return np.frombuffer(b, dtype=np.float32)

sidekick/hooks.py

@@ -0,0 +1,60 @@
+"""Build + install Claude Code hook config in ~/.claude/settings.json."""
+from __future__ import annotations
+import json
+from pathlib import Path
+from sidekick.paths import home
+
+def build_hook_config() -> dict:
+    return {
+        "Stop": [
+            {
+                "matcher": "*",
+                "hooks": [
+                    {"type": "command", "command": "sidekick stop-hook", "timeout": 5}
+                ],
+            }
+        ],
+        "UserPromptSubmit": [
+            {
+                "matcher": "*",
+                "hooks": [
+                    {"type": "command", "command": "sidekick-recall", "timeout": 1}
+                ],
+            }
+        ],
+    }
+
+def settings_path() -> Path:
+    return home() / ".claude" / "settings.json"
+
+def merge_into(existing: dict, new_hooks: dict) -> dict:
+    out = dict(existing)
+    out.setdefault("hooks", {})
+    for event, entries in new_hooks.items():
+        out["hooks"].setdefault(event, [])
+        out["hooks"][event] = [
+            e for e in out["hooks"][event]
+            if not any(
+                "sidekick" in (h.get("command", "") if isinstance(h, dict) else "")
+                for h in (e.get("hooks", []) if isinstance(e, dict) else [])
+            )
+        ]
+        out["hooks"][event].extend(entries)
+    return out
+
+def install(apply: bool = False) -> str:
+    cfg = build_hook_config()
+    snippet = json.dumps({"hooks": cfg}, indent=2)
+    if not apply:
+        return snippet
+    sp = settings_path()
+    sp.parent.mkdir(parents=True, exist_ok=True)
+    existing = {}
+    if sp.exists():
+        try:
+            existing = json.loads(sp.read_text())
+        except json.JSONDecodeError:
+            existing = {}
+    merged = merge_into(existing, cfg)
+    sp.write_text(json.dumps(merged, indent=2))
+    return f"wrote {sp}"

sidekick/indexer.py

@@ -0,0 +1,119 @@
+"""Incremental indexer. Walks ~/.claude/projects, parses new JSONL bytes, inserts."""
+from __future__ import annotations
+import datetime as dt
+from pathlib import Path
+from sidekick import db
+from sidekick.parser import parse_session_file, Turn
+from sidekick.paths import claude_projects_dir
+
+def _project_name(path: Path) -> str:
+    return path.parent.name
+
+def _upsert_session(conn, turn: Turn, project: str) -> None:
+    conn.execute(
+        """
+        INSERT INTO sessions (id, project, cwd, started_at, ended_at, status)
+        VALUES (?, ?, ?, ?, ?, 'unknown')
+        ON CONFLICT(id) DO UPDATE SET
+            cwd=COALESCE(sessions.cwd, excluded.cwd),
+            ended_at=excluded.ended_at,
+            project=COALESCE(sessions.project, excluded.project)
+        """,
+        (turn.session_id, project, turn.cwd, turn.timestamp, turn.timestamp),
+    )
+
+def _insert_turn(conn, turn: Turn) -> None:
+    conn.execute(
+        """
+        INSERT OR IGNORE INTO turns
+            (session_id, turn_idx, role, text, timestamp, input_tokens, output_tokens)
+        VALUES (?, ?, ?, ?, ?, ?, ?)
+        """,
+        (turn.session_id, turn.turn_idx, turn.role, turn.text,
+         turn.timestamp, turn.input_tokens, turn.output_tokens),
+    )
+    conn.execute(
+        """
+        INSERT OR REPLACE INTO turns_fts (rowid, text, session_id, turn_idx, role)
+        SELECT rowid, text, session_id, turn_idx, role FROM turns
+        WHERE session_id=? AND turn_idx=?
+        """,
+        (turn.session_id, turn.turn_idx),
+    )
+
+def _last_offset(conn, file_path: Path) -> tuple[float, int]:
+    row = conn.execute(
+        "SELECT mtime, byte_offset FROM file_offsets WHERE file_path=?",
+        (str(file_path),),
+    ).fetchone()
+    return (row[0], row[1]) if row else (0.0, 0)
+
+def _save_offset(conn, file_path: Path, mtime: float, offset: int) -> None:
+    conn.execute(
+        """
+        INSERT INTO file_offsets (file_path, mtime, byte_offset, indexed_at)
+        VALUES (?, ?, ?, ?)
+        ON CONFLICT(file_path) DO UPDATE SET
+            mtime=excluded.mtime,
+            byte_offset=excluded.byte_offset,
+            indexed_at=excluded.indexed_at
+        """,
+        (str(file_path), mtime, offset, dt.datetime.utcnow().isoformat()),
+    )
+
+def embed_pending(batch_size: int = 64) -> int:
+    """Embed turns that have no embedding yet. Returns count embedded."""
+    from sidekick.embeddings import Embedder, to_blob
+    conn = db.connect()
+    rows = conn.execute(
+        """
+        SELECT t.session_id, t.turn_idx, t.text
+        FROM turns t
+        LEFT JOIN embeddings e
+          ON e.session_id=t.session_id AND e.turn_idx=t.turn_idx
+        WHERE e.session_id IS NULL AND t.text != ''
+        """
+    ).fetchall()
+    if not rows:
+        return 0
+    embedder = Embedder()
+    total = 0
+    for i in range(0, len(rows), batch_size):
+        batch = rows[i : i + batch_size]
+        vecs = embedder.embed_many([r[2] for r in batch])
+        conn.executemany(
+            "INSERT OR REPLACE INTO embeddings (session_id, turn_idx, vec) VALUES (?, ?, ?)",
+            [(r[0], r[1], to_blob(v)) for r, v in zip(batch, vecs)],
+        )
+        total += len(batch)
+    conn.close()
+    return total
+
+def run(only_session: str | None = None) -> int:
+    """Index all new bytes; return number of new turns inserted."""
+    root = claude_projects_dir()
+    if not root.exists():
+        return 0
+    conn = db.connect()
+    new_turns = 0
+    files = sorted(root.rglob("*.jsonl"))
+    for f in files:
+        if only_session and only_session not in f.name:
+            continue
+        mtime = f.stat().st_mtime
+        last_mtime, last_offset = _last_offset(conn, f)
+        size = f.stat().st_size
+        if mtime <= last_mtime and size <= last_offset:
+            continue
+        project = _project_name(f)
+        max_offset = last_offset
+        for turn in parse_session_file(f):
+            if turn.byte_offset < last_offset:
+                continue
+            _upsert_session(conn, turn, project)
+            _insert_turn(conn, turn)
+            new_turns += 1
+            max_offset = max(max_offset, turn.byte_offset + 1)
+        _save_offset(conn, f, mtime, size)
+    conn.close()
+    return new_turns

sidekick/parser.py

@@ -0,0 +1,78 @@
+"""JSONL → Turn dataclasses. Pure parsing; no DB, no network."""
+from __future__ import annotations
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterator
+
+@dataclass(frozen=True)
+class Turn:
+    session_id: str
+    turn_idx: int
+    role: str
+    text: str
+    timestamp: str
+    cwd: str | None
+    input_tokens: int
+    output_tokens: int
+    byte_offset: int
+    raw_type: str
+    raw_subtype: str | None
+
+def _flatten_content(content) -> str:
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts = []
+        for item in content:
+            if not isinstance(item, dict):
+                continue
+            if item.get("type") == "text":
+                parts.append(item.get("text", ""))
+            elif item.get("type") == "tool_use":
+                parts.append(f"[tool_use:{item.get('name','?')}]")
+            elif item.get("type") == "tool_result":
+                tr = item.get("content", "")
+                if isinstance(tr, list):
+                    tr = " ".join(p.get("text", "") for p in tr if isinstance(p, dict))
+                parts.append(f"[tool_result:{tr[:500]}]")
+        return "\n".join(parts)
+    return ""
+
+def parse_session_file(path: Path) -> Iterator[Turn]:
+    """Yield Turn for each well-formed line. Skip malformed lines silently."""
+    if not path.exists():
+        return
+    turn_idx = 0
+    offset = 0
+    with open(path, "rb") as f:
+        for raw in f:
+            line_offset = offset
+            offset += len(raw)
+            try:
+                obj = json.loads(raw)
+            except json.JSONDecodeError:
+                continue
+            if not isinstance(obj, dict):
+                continue
+            session_id = obj.get("sessionId") or obj.get("session_id")
+            if not session_id:
+                continue
+            msg = obj.get("message") or {}
+            role = msg.get("role") or obj.get("type", "")
+            text = _flatten_content(msg.get("content", ""))
+            usage = msg.get("usage") or {}
+            yield Turn(
+                session_id=session_id,
+                turn_idx=turn_idx,
+                role=role,
+                text=text,
+                timestamp=obj.get("timestamp", ""),
+                cwd=obj.get("cwd"),
+                input_tokens=int(usage.get("input_tokens", 0) or 0),
+                output_tokens=int(usage.get("output_tokens", 0) or 0),
+                byte_offset=line_offset,
+                raw_type=obj.get("type", ""),
+                raw_subtype=obj.get("subtype"),
+            )
+            turn_idx += 1

sidekick/paths.py

@@ -0,0 +1,26 @@
+"""Centralized path resolution. All FS paths come from here."""
+from __future__ import annotations
+from pathlib import Path
+
+def home() -> Path:
+    return Path.home()
+
+def sidekick_dir() -> Path:
+    p = home() / ".session-sidekick"
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+def db_path() -> Path:
+    return sidekick_dir() / "index.db"
+
+def logs_dir() -> Path:
+    p = sidekick_dir() / "logs"
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+def claude_projects_dir() -> Path:
+    """Where Claude Code stores session JSONLs. Tries new path first."""
+    new = home() / ".config" / "claude" / "projects"
+    if new.exists():
+        return new
+    return home() / ".claude" / "projects"

sidekick/recall.py

@@ -0,0 +1,69 @@
+"""Recall client. Invoked by the UserPromptSubmit hook. Always returns 0."""
+from __future__ import annotations
+import json
+import socket
+import sys
+from sidekick.paths import sidekick_dir
+
+def _daemon_address():
+    if sys.platform == "win32":
+        port_file = sidekick_dir() / "daemon.port"
+        if not port_file.exists():
+            return None
+        try:
+            return ("127.0.0.1", int(port_file.read_text().strip()))
+        except ValueError:
+            return None
+    sock = sidekick_dir() / "daemon.sock"
+    return str(sock) if sock.exists() else None
+
+def _connect(addr, timeout: float) -> socket.socket | None:
+    try:
+        if isinstance(addr, tuple):
+            return socket.create_connection(addr, timeout=timeout)
+        s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        s.settimeout(timeout)
+        s.connect(addr)
+        return s
+    except OSError:
+        return None
+
+def _format_hit(hit: dict, prompt: str) -> str:
+    title = hit.get("title") or "(untitled session)"
+    summary = hit.get("summary") or ""
+    tags = hit.get("tags") or ""
+    sid = hit["session_id"]
+    ended = hit.get("ended_at", "")
+    return (
+        f"\U0001f4a1 You may have done this before — session `{sid[:8]}` ({ended[:10]}): {title}\n"
+        f"   {summary}\n"
+        f"   Tags: {tags}\n"
+        f"   Resume with: claude --resume {sid}\n"
+    )
+
+def run(prompt: str, project: str | None = None, timeout_ms: int = 300) -> int:
+    """Print hint to stdout if confident match; otherwise silent. Always exits 0."""
+    addr = _daemon_address()
+    if not addr:
+        return 0
+    timeout = timeout_ms / 1000.0
+    sock = _connect(addr, timeout)
+    if not sock:
+        return 0
+    try:
+        sock.sendall(json.dumps({"op": "recall", "prompt": prompt, "project": project}).encode() + b"\n")
+        f = sock.makefile("rb")
+        line = f.readline()
+        resp = json.loads(line)
+        if resp.get("ok") and resp.get("hit"):
+            print(_format_hit(resp["hit"], prompt))
+    except (OSError, json.JSONDecodeError):
+        pass
+    finally:
+        sock.close()
+    return 0
+
+def main() -> None:
+    """Entry: `sidekick-recall`. Reads the prompt from stdin."""
+    prompt = sys.stdin.read()
+    sys.exit(run(prompt))

sidekick/search.py

@@ -0,0 +1,85 @@
+"""Search functions. FTS5 first; semantic added in Task 8."""
+from __future__ import annotations
+from sidekick import db
+
+def fts(query: str, limit: int = 20, project: str | None = None) -> list[dict]:
+    """FTS5 keyword search. Returns ranked hits with snippet."""
+    conn = db.connect()
+    sql = """
+        SELECT t.session_id, t.turn_idx, t.role, s.project,
+               snippet(turns_fts, 0, '[[', ']]', '...', 12) AS snippet,
+               s.title
+        FROM turns_fts JOIN turns t ON t.rowid = turns_fts.rowid
+        JOIN sessions s ON s.id = t.session_id
+        WHERE turns_fts MATCH ?
+    """
+    args: list = [query]
+    if project:
+        sql += " AND s.project LIKE ?"
+        args.append(f"%{project}%")
+    sql += " ORDER BY rank LIMIT ?"
+    args.append(limit)
+    return [
+        {"session_id": r[0], "turn_idx": r[1], "role": r[2],
+         "project": r[3], "snippet": r[4], "title": r[5]}
+        for r in conn.execute(sql, args).fetchall()
+    ]
+
+import numpy as np
+from sidekick.embeddings import Embedder, from_blob
+
+_embedder: Embedder | None = None
+
+def _embedder_singleton() -> Embedder:
+    global _embedder
+    if _embedder is None:
+        _embedder = Embedder()
+    return _embedder
+
+def semantic(query: str, limit: int = 20, project: str | None = None) -> list[dict]:
+    """Cosine similarity over stored embeddings."""
+    conn = db.connect()
+    sql = """
+        SELECT e.session_id, e.turn_idx, e.vec, t.text, t.role, s.project, s.title
+        FROM embeddings e
+        JOIN turns t ON t.session_id=e.session_id AND t.turn_idx=e.turn_idx
+        JOIN sessions s ON s.id=e.session_id
+    """
+    args: list = []
+    if project:
+        sql += " WHERE s.project LIKE ?"
+        args.append(f"%{project}%")
+    rows = conn.execute(sql, args).fetchall()
+    if not rows:
+        return []
+    qv = _embedder_singleton().embed_one(query)
+    scored = []
+    for sid, tidx, blob, text, role, proj, title in rows:
+        v = from_blob(blob)
+        score = float(np.dot(qv, v))
+        scored.append({
+            "session_id": sid, "turn_idx": tidx, "role": role,
+            "project": proj, "title": title,
+            "snippet": text[:200], "score": score,
+        })
+    scored.sort(key=lambda h: h["score"], reverse=True)
+    return scored[:limit]
+
+def combined(query: str, limit: int = 20, project: str | None = None) -> list[dict]:
+    """RRF fusion of FTS and semantic."""
+    fts_hits = fts(query, limit=limit * 2, project=project)
+    sem_hits = semantic(query, limit=limit * 2, project=project)
+    k = 60.0
+    rrf: dict[tuple[str, int], dict] = {}
+    for rank, h in enumerate(fts_hits, start=1):
+        key = (h["session_id"], h["turn_idx"])
+        rrf.setdefault(key, {**h, "score": 0.0, "mode": "fts"})
+        rrf[key]["score"] += 1.0 / (k + rank)
+    for rank, h in enumerate(sem_hits, start=1):
+        key = (h["session_id"], h["turn_idx"])
+        rrf.setdefault(key, {**h, "score": 0.0, "mode": "semantic"})
+        rrf[key]["score"] += 1.0 / (k + rank)
+        if rrf[key].get("mode") != "semantic":
+            rrf[key]["mode"] = "hybrid"
+    out = sorted(rrf.values(), key=lambda h: h["score"], reverse=True)
+    return out[:limit]

sidekick/titler.py

@@ -0,0 +1,121 @@
+"""Haiku-powered titler + heuristic status detection."""
+from __future__ import annotations
+import datetime as dt
+import json
+import os
+from sidekick import db
+
+MODEL = "claude-haiku-4-5-20251001"
+
+PROMPT_TEMPLATE = """You are summarizing a developer's coding session with an AI assistant.
+
+Output STRICT JSON with this schema:
+{{
+  "title": "<5-word title in lowercase, no punctuation>",
+  "tags": ["<tag1>", "<tag2>", "<tag3>"],
+  "summary": "<one sentence describing what got done or what was attempted>"
+}}
+
+Only output JSON. No prose, no markdown fences.
+
+First user prompts:
+{first_user_prompts}
+
+Last assistant turns:
+{last_assistant_turns}
+"""
+
+def _client():
+    import anthropic
+    return anthropic.Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))
+
+def detect_status(session_id: str) -> str:
+    conn = db.connect()
+    rows = conn.execute(
+        "SELECT role, text, input_tokens FROM turns WHERE session_id=? ORDER BY turn_idx",
+        (session_id,),
+    ).fetchall()
+    if not rows:
+        return "unknown"
+    last_text = (rows[-1][1] or "").lower()
+    if "compact" in last_text or "context auto-compact" in last_text:
+        return "context_limit"
+    max_input = max((r[2] or 0) for r in rows)
+    if max_input > 180000:
+        return "context_limit"
+    last_user = [r for r in rows if r[0] == "user"][-3:]
+    short_corrections = sum(
+        1 for r in last_user
+        if len((r[1] or "").strip()) <= 12
+        and any(w in (r[1] or "").lower() for w in ("no", "stop", "forget", "nope", "cancel"))
+    )
+    if short_corrections >= 2:
+        return "abandoned"
+    return "completed"
+
+def _build_prompt(session_id: str) -> str:
+    conn = db.connect()
+    user_rows = conn.execute(
+        "SELECT text FROM turns WHERE session_id=? AND role='user' ORDER BY turn_idx LIMIT 5",
+        (session_id,),
+    ).fetchall()
+    asst_rows = conn.execute(
+        "SELECT text FROM turns WHERE session_id=? AND role='assistant' ORDER BY turn_idx DESC LIMIT 3",
+        (session_id,),
+    ).fetchall()
+    first_user = "\n---\n".join(r[0][:800] for r in user_rows)
+    last_asst = "\n---\n".join(r[0][:800] for r in reversed(asst_rows))
+    return PROMPT_TEMPLATE.format(
+        first_user_prompts=first_user or "(none)",
+        last_assistant_turns=last_asst or "(none)",
+    )
+
+def title_session(session_id: str) -> dict | None:
+    """Call Haiku, parse JSON, persist to sessions row. Returns the parsed dict or None."""
+    status = detect_status(session_id)
+    prompt = _build_prompt(session_id)
+    client = _client()
+    resp = client.messages.create(
+        model=MODEL,
+        max_tokens=200,
+        messages=[{"role": "user", "content": prompt}],
+    )
+    raw = resp.content[0].text if resp.content else ""
+    raw = raw.strip()
+    if raw.startswith("```"):
+        raw = raw.strip("`")
+        if raw.startswith("json"):
+            raw = raw[4:]
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError:
+        return None
+    title = (data.get("title") or "").strip().lower()[:80]
+    tags = ",".join((data.get("tags") or [])[:3])
+    summary = (data.get("summary") or "").strip()[:300]
+    conn = db.connect()
+    conn.execute(
+        """
+        UPDATE sessions
+        SET title=?, tags=?, summary=?, status=?, titled_at=?
+        WHERE id=?
+        """,
+        (title, tags, summary, status, dt.datetime.utcnow().isoformat(), session_id),
+    )
+    return {"title": title, "tags": tags, "summary": summary, "status": status}
+
+def main() -> None:
+    """Entry: `sidekick-titler <session_id>` — titles untitled sessions if no arg."""
+    import sys
+    if len(sys.argv) > 1:
+        title_session(sys.argv[1])
+        return
+    conn = db.connect()
+    ids = [r[0] for r in conn.execute(
+        "SELECT id FROM sessions WHERE titled_at IS NULL LIMIT 50"
+    ).fetchall()]
+    for sid in ids:
+        try:
+            title_session(sid)
+        except Exception as e:
+            print(f"titler error on {sid}: {e}", file=__import__("sys").stderr)