session-sidekick 0.1.0__tar.gz

session_sidekick-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+build/
+.venv/

session_sidekick-0.1.0/CLAUDE.md

@@ -0,0 +1,27 @@
+# CLAUDE.md — session-sidekick
+
+Project-local instructions. Inherits from `D:\Aru\NYU\CLAUDE.md` and `~/.claude/CLAUDE.md`.
+
+## What this project is
+
+A local CLI + hook bundle for Claude Code that auto-titles sessions on close and surfaces per-prompt semantic matches against past sessions via a `UserPromptSubmit` hook. See `FEATURE_session_sidekick.md` for the full spec, `state.md` for current phase.
+
+## Project conventions
+
+- **Source of truth:** `FEATURE_session_sidekick.md`. Update it before changing behavior.
+- **State tracking:** Update `state.md` whenever phase changes (design → planning → implementing → shipped).
+- **Language:** Python is the V1 default (per spec § Open questions). Revisit if 300ms recall budget is missed.
+- **Data location:** `~/.session-sidekick/index.db` (SQLite, WAL mode). Never write inside `~/.claude/projects/` — that's Claude Code's data, read-only to us.
+- **Hooks:** Stop hook (titler + indexer) and UserPromptSubmit hook (recall). Both must fail silent — never block Claude Code.
+
+## Don't
+
+- Don't duplicate ccusage's job — no cost dashboards.
+- Don't add a TUI / web UI in V1.
+- Don't auto-patch `~/.claude/settings.json` without explicit `--apply` flag from the user.
+- Don't make the recall hook chatty — silent on miss is the default.
+
+## Testing notes
+
+- Real corpus for testing: Aru's `~/.claude/projects/` (~15 project dirs as of 2026-05-05).
+- Use a tmp copy for destructive tests: `cp -r ~/.claude/projects /tmp/sidekick-fixture`.

session_sidekick-0.1.0/FEATURE_session_sidekick.md

@@ -0,0 +1,163 @@
+# FEATURE: session-sidekick
+
+**Date:** 2026-05-05
+**Status:** Design — not yet approved for implementation
+**Author:** Aru
+
+## One-line goal
+
+A local Claude Code companion that (1) auto-titles every session on close so they're findable later, and (2) when you start typing a new prompt, semantically searches your past sessions and surfaces a tight pointer if you've already solved this exact thing.
+
+## Problem
+
+Aru runs Claude Code across 15+ project directories under `~/.claude/projects/`. Sessions get closed without renaming (sleepy-close problem) — so even existing search tools (ccrider, ClaudeHistoryMCP, cc-sessions) struggle to surface them, because the only metadata is "first user message" which is rarely the gist of the session. Result: same problems get re-derived from scratch in new sessions, burning tokens and time.
+
+Two underlying causes:
+
+1. **Sessions aren't titled meaningfully** — search tools index content, but recall is poor when you can't remember a keyword from a 4-week-old conversation.
+2. **Existing recall tools are either broad-and-eager (ClaudeHistoryMCP injects project-wide context at session start, often irrelevant) or reactive (Claude must decide to call a search tool, which it often doesn't).** Nothing fires at `UserPromptSubmit` with a precise per-prompt semantic match.
+
+## Non-goals
+
+- **Cost dashboards.** ccusage owns this. We do not duplicate.
+- **TUI / web UI.** Out of scope. CLI only for V1.
+- **Multi-machine sync.** Local only.
+- **Real-time token-waste prevention** (PreToolUse hooks for redundant Reads/Bash). Considered and dropped from V1 — risk of false-positive annoyance is high. Revisit in V2.
+- **Auto-skill compiler / CLAUDE.md generator.** V2.
+- **Replacing `claude --resume`.** We surface session IDs; the user runs `--resume` themselves.
+
+## Comparison to existing tools
+
+| Tool | What it does well | Gap we fill |
+|---|---|---|
+| ccusage | Cost/token tracking | (we don't compete) |
+| ccrider, cc-sessions | CLI search, resume | No LLM titles → poor recall on unrenamed sessions; no per-prompt auto-injection |
+| ClaudeHistoryMCP | SessionStart hook injects project context | Broad dump, fires once, often irrelevant — no per-prompt precision match |
+| session-seek, conversation-search | MCP search tools | Reactive — Claude must invoke; doesn't fire automatically per prompt |
+| kmizzi/claude-code-sessions | Web UI, embeddings | UI-heavy; no hooks; no LLM titles |
+
+**Our wedge:** LLM-generated titles + tags on every session at close, plus a `UserPromptSubmit` hook that does a precision semantic match per prompt and only injects a hit when confidence is high (silent otherwise). Two small, focused mechanisms; nobody currently combines them.
+
+## Architecture
+
+```
+Claude Code
+   │
+   ├─ Stop hook ───────────► sidekick titler ───► SQLite (titles + tags + summary)
+   │                            (1 Haiku call per closed session)
+   │
+   ├─ Stop hook ───────────► sidekick indexer ──► SQLite FTS5 + embeddings
+   │                            (incremental, line-level)
+   │
+   └─ UserPromptSubmit hook ─► sidekick recall ──► (semantic search past sessions)
+                                  │                  │
+                                  │                  ├─ confidence ≥ threshold → inject 1-paragraph hit
+                                  │                  └─ below threshold → silent (no injection)
+                                  ▼
+                              CLI: sidekick search / list / show / why-stopped
+```
+
+### Components
+
+**1. Indexer (`sidekick index`)**
+- Scans `~/.claude/projects/**/*.jsonl`.
+- Parses each JSONL turn (user prompts, assistant responses, tool calls).
+- Stores in SQLite at `~/.session-sidekick/index.db`:
+  - `sessions(id, project, cwd, started_at, ended_at, title, summary, tags, status)`
+  - `turns(session_id, turn_idx, role, content, tools_used, timestamp)`
+  - FTS5 virtual table on `turns.content` and `sessions.title|summary|tags`.
+  - Embedding column on `turns` (sqlite-vec or LanceDB; decision deferred to writing-plans).
+- Incremental: tracks `(file_mtime, byte_offset)` per JSONL; only processes new bytes.
+- Idempotent: safe to run repeatedly.
+
+**2. Titler (`sidekick title <session_id>`)**
+- Triggered by Stop hook.
+- Reads first ~5 user turns + last ~3 assistant turns of the session.
+- Single Haiku call (~$0.0001) producing strict JSON: `{title, tags[3], summary, status}` where `status ∈ {completed, abandoned, context_limit, in_progress}`.
+- Status detection:
+  - `context_limit` if last turn shows compaction marker or context-full error.
+  - `abandoned` if last 3 user turns are short corrections / "no" / "stop" without resolution.
+  - `completed` otherwise.
+- Persisted to `sessions` row.
+
+**3. Recall (`sidekick recall <prompt>`)**
+- Triggered by `UserPromptSubmit` hook with the user's pending prompt.
+- Embeds the prompt; semantic-searches `turns` (filter: same project preferred, then global).
+- Reranks top-K by recency × project-match × content-type weight.
+- **Confidence gate:** only inject if top hit's similarity ≥ 0.78 AND the hit is from a different session AND not from the last 24h (avoid telling the user about a session they're already in the middle of).
+- On hit, writes a small markdown block to stdout (consumed by Claude Code as `additionalContext`):
+  ```
+  💡 You may have done this before — session `<id>` (<date>): <title>
+     <one-line summary>. Tags: <tag1, tag2, tag3>
+     Resume with: claude --resume <id>
+  ```
+- Silent on miss. **No false-positive nags.**
+- Hard timeout: 300ms. If recall hasn't returned, hook exits silent.
+
+**4. CLI**
+- `sidekick search <query>` — full-text + semantic, ranked.
+- `sidekick list [--project X] [--status abandoned|completed|...] [--since 7d]`
+- `sidekick show <id>` — title, summary, tags, turn count, full transcript on `--full`.
+- `sidekick reindex [--full]` — rebuild index.
+- `sidekick stats` — basic db stats (sessions, turns, db size, last index time).
+
+## Data flow
+
+1. User finishes a session in Claude Code → Stop hook fires.
+2. Hook calls `sidekick index --session <id>` (incremental, ~50ms) and `sidekick title <id>` (Haiku call, ~1s, async — does not block Claude Code exit).
+3. Next session: user types a prompt → `UserPromptSubmit` hook calls `sidekick recall <prompt>` with 300ms budget.
+4. If confident match: a one-paragraph hint is injected as additional context. Otherwise: nothing happens.
+
+## Token / cost budget
+
+| Operation | Cost per event | Notes |
+|---|---|---|
+| Titler (per closed session) | ~$0.0001 (Haiku, ~2K input + 100 output) | One-time per session |
+| Recall (per user prompt) | $0 (local embeddings) | Local model only |
+| Injected context (on hit) | ~50–80 tokens of *your* context window | Only when injected |
+| Indexing | $0 | Local |
+
+Worst case: 50 sessions/week × $0.0001 = $0.005/week for titles. Negligible.
+
+## Failure modes & handling
+
+- **Hook timeout** → silent, log to `~/.session-sidekick/logs/recall.log`.
+- **Malformed JSONL** → skip line, count, surface in `stats`.
+- **DB locked** (concurrent index + recall) → recall reads from snapshot; index uses WAL.
+- **Haiku titler fails** (network, quota) → leave title null, retry on next `sidekick reindex`.
+- **Embedding model not yet downloaded** → recall returns silent; titler still works; indexer queues for later embedding.
+- **Hot loop / repeat injection** — same hint injected twice in one session: dedupe by session-id within current sidekick run; don't re-suggest the same prior session twice.
+
+## Privacy
+
+- 100% local. No data leaves the machine.
+- Haiku titler is the only network call — sends ~2KB of session content to Anthropic per closed session. Opt-out flag: `--no-titler` (falls back to first-user-message heuristic).
+- Honors CLAUDE.md rule: never reads `.env` files; sidekick parses only `*.jsonl` under `~/.claude/projects/`.
+
+## Open questions (resolve in writing-plans phase)
+
+1. **Embedding model:** all-MiniLM-L6-v2 (384d, fast, what session-seek and kmizzi use) vs. bge-small-en-v1.5 (better recall, slightly heavier). Default: MiniLM unless we hit recall problems.
+2. **Vector store:** sqlite-vec (single-file, simple) vs. LanceDB (faster at scale). Default: sqlite-vec; revisit if turn count > 500K.
+3. **Confidence threshold (0.78):** placeholder — needs empirical tuning on Aru's actual session corpus during implementation.
+4. **Language:** Python (matches Aru's stack, easy hooking) vs. Go (single binary, ccrider's choice). Default: Python — fewer build steps, faster iteration; revisit if startup latency hurts the 300ms budget.
+5. **Hook installation UX:** should `sidekick install-hooks` patch `~/.claude/settings.json` automatically, or print the snippet for the user to paste? Default: print + `--apply` flag for auto-patch. Reversible.
+
+## Success criteria
+
+- Aru can ask `sidekick search "modal vllm"` and find every relevant past session, even ones closed without rename.
+- At least one `UserPromptSubmit` hit per week that prevents a re-derivation (measured: count of injections in `recall.log`, anecdotal "this was useful").
+- Indexing 1500 sessions in <30s on first run.
+- Recall p95 < 200ms.
+- Zero false-positive nags in normal use (subjective; track injection-dismissal rate if we add a thumbs-down).
+
+## Out of scope (V2 candidates)
+
+- PreToolUse token-waste warnings (#3 from brainstorming — dropped from V1).
+- Auto-skill / CLAUDE.md compiler from recurring corrections.
+- Session DAG / lineage tracking.
+- Multi-machine sync.
+- TUI / web UI.
+
+## Database impact
+
+New SQLite database at `~/.session-sidekick/index.db`. Does not touch any existing project database. No SCHEMA.md update needed for any existing project — this is a standalone tool.

session_sidekick-0.1.0/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.

session_sidekick-0.1.0/PKG-INFO

@@ -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