claude-session-skill 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ITeachYouAI
+
+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.

package/README.md

@@ -0,0 +1,173 @@
+# claude-session-skill
+
+A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) skill for searching, browsing, and naming past sessions. Indexes all session history and generates AI summaries so you can find any session by keyword, project, or name.
+
+## Requirements
+
+- [Bun](https://bun.sh) runtime
+- Claude Code CLI
+- `ANTHROPIC_API_KEY` environment variable
+
+## Installation
+
+```bash
+git clone https://github.com/ITeachYouAI/claude-session-skill.git ~/.claude/skills/session
+bun run ~/.claude/skills/session/session.ts rebuild
+```
+
+Claude Code discovers the skill automatically via `SKILL.md` triggers. Open any session and type `/session list`.
+
+## Usage
+
+```
+/session list                    # Show 20 most recent sessions
+/session list --all              # Show all sessions
+/session show <id>               # Show full session details (partial IDs work)
+/session name <name>             # Name the most recent session
+/session name <id> <name>        # Name a specific session by ID
+/session unname [<id>]           # Clear a session's name
+/session search <query>          # Search by keyword
+/session <query>                 # Shorthand for search
+/session rebuild                 # Rebuild the index
+/session stats                   # Stats by project
+```
+
+## Naming sessions
+
+Session naming is handled via natural language — you never type or see session IDs directly. Claude resolves which session you mean.
+
+| Input | Behavior |
+|---|---|
+| "Name this session `<name>`" | Names the most recent session |
+| "Name the session where I did `<thing>`" | Claude searches, finds it, names it |
+| After `/session list`: "name the second one `<name>`" | Claude uses the ID from the list output |
+| "Unname the `<name>` session" | Claude searches, finds it, clears the name |
+
+Names are 1–50 characters. Named sessions rank highest in search results. Clearing a name with `unname` preserves the AI summary.
+
+## How it works
+
+### Index build
+
+1. Parse `~/.claude/history.jsonl` for session IDs, timestamps, and project paths
+2. Scan `~/.claude/projects/*/` session files for conversation content, working directory, and git branch
+3. Generate summaries via Claude Haiku (5 bullet points per session, 10 concurrent requests)
+
+### Caching
+
+- Index cache invalidates when `history.jsonl` changes or any session file is modified
+- Summary cache persists across rebuilds — each session is summarized once
+- Cached lookups: ~30ms
+
+### Search scoring
+
+| Signal | Weight |
+|---|---|
+| Name match | 15 |
+| Summary match | 12 |
+| First message match | 10 |
+| Last message match | 5 |
+| Project/path match | 3 |
+| All messages match | 2 |
+| Quoted phrase | 2× multiplier |
+| Within 24 hours | 1.5× recency boost |
+| Within 7 days | 1.2× recency boost |
+
+## MCP Server
+
+`claude-session-skill` ships a Model Context Protocol (MCP) server so any MCP-compatible client (Claude Desktop, Cursor, etc.) can search sessions without using the CLI skill.
+
+### Install (via npm)
+
+```bash
+npm install -g claude-session-skill
+# or run without installing:
+bunx claude-session-mcp
+```
+
+### Claude Desktop config
+
+```json
+{
+  "mcpServers": {
+    "claude-session": {
+      "command": "bunx",
+      "args": ["claude-session-mcp"],
+      "env": {
+        "ANTHROPIC_API_KEY": "<your-key>"
+      }
+    }
+  }
+}
+```
+
+Or with the global install:
+
+```json
+{
+  "mcpServers": {
+    "claude-session": {
+      "command": "claude-session-mcp"
+    }
+  }
+}
+```
+
+### Available tools
+
+| Tool | Parameters | Description |
+|------|-----------|-------------|
+| `list_sessions` | `limit?: number` | List recent sessions with AI summaries |
+| `search_sessions` | `query: string` | Search by keyword or quoted phrase |
+| `show_session` | `id: string` | Detailed view of a specific session |
+| `name_session` | `id?: string, name: string` | Assign a memorable name to a session |
+| `unname_session` | `id?: string` | Remove a session's name |
+| `session_stats` | — | Statistics broken down by project |
+
+### Verify with MCP Inspector
+
+```bash
+bunx @modelcontextprotocol/inspector bun mcp-server.ts
+```
+
+## File structure
+
+```
+session.ts              # CLI entry point
+mcp-server.ts           # MCP server entry point (6 tools)
+lib/
+  indexer.ts            # Index builder, summarizer, name persistence
+  search.ts             # Weighted keyword search
+  format.ts             # Terminal output formatting
+  __tests__/            # Unit tests (bun:test)
+dist/                   # Built Node-compatible bundles (gitignored)
+SKILL.md                # Skill manifest and Claude instructions
+data/                   # Auto-generated, gitignored
+  index.json            # Cached session index
+  summaries.json        # Persistent AI summaries
+  names.json            # User-assigned session names
+```
+
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `ANTHROPIC_API_KEY` | required | Used for session summarization |
+| `SESSION_SUMMARY_MODEL` | `claude-haiku-4-5-20251001` | Model used for summarization |
+| `SESSION_DEBUG` | unset | Enable debug logging to stderr |
+
+## Development
+
+```bash
+git clone https://github.com/ITeachYouAI/claude-session-skill.git
+cd claude-session-skill
+bun install
+bun test
+bun x tsc --noEmit
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: session
+description: Search and browse past Claude Code sessions. Indexes all session history already stored by Claude Code and makes it searchable by keyword, project, or date. Can also name sessions for easy recall.
+triggers:
+  - session
+  - find session
+  - session search
+  - search sessions
+  - past session
+  - name session
+  - session name
+  - name this session
+  - call this session
+  - unname session
+  - clear session name
+---
+
+# Session Tracker Skill
+
+## Usage
+
+```
+/session <query>                 # Search sessions by keyword
+/session list                    # Show 20 most recent sessions
+/session list --all              # Show all sessions
+/session show <id>               # Full details (supports partial IDs)
+/session name <name>             # Name the most recent session (by last activity)
+/session name <id> <name>        # Name a specific session by ID
+/session unname [<id>]           # Clear a session's name
+/session rebuild                 # Force rebuild the index
+/session stats                   # Index statistics by project
+```
+
+## How It Works
+
+Claude Code already saves every user message to `~/.claude/history.jsonl` with session IDs, timestamps, and project paths. Session transcripts live as individual JSONL files under `~/.claude/projects/*/`. This skill indexes all of that and makes it searchable.
+
+### Implementation
+
+Entry point: `bun run ~/.claude/skills/session/session.ts <command> [args]`
+
+**CRITICAL OUTPUT RULES — read before running anything:**
+1. **Print the FULL command output verbatim.** Do NOT summarize, paraphrase, truncate, or reformat it. The skill handles all formatting. Your job is to relay what it prints, nothing more.
+2. **Do NOT add commentary** after the output. No "What do you need?", no "Here are your sessions:", no interpretation. Just the raw output.
+3. **Do NOT ask follow-up questions** after `list` or `search`. The output is self-contained.
+4. **If the user references an already-shown list** (e.g., "the most recent", "the third one", "that one") — use the IDs already printed in the previous output. Do NOT re-run `list` or `show` unnecessarily.
+
+### Naming Sessions
+
+Users name sessions in natural language. They will NEVER type IDs. Your job is to resolve which session they mean.
+
+**How to handle naming requests:**
+
+1. **"Name this session X"** / **"Call this session X"** — Name the most recent session (by last activity). Run: `session.ts name "<name>"`
+2. **"Name the session where I worked on the clinic bot"** — First search (`session.ts search "clinic bot"`), identify the right session from results, then name it by ID (`session.ts name <id> "<name>"`). The user never sees or types the ID — you resolve it.
+3. **"Name my last session X"** — Run: `session.ts name "<name>"` (defaults to most recent by last activity)
+4. **After `/session list`**, user says **"name the third one X"** — You already have the list output with IDs. Use the ID from the third entry.
+5. **"Clear the name from X"** / **"Unname the clinic bot session"** — Search to find it, then run: `session.ts unname <id>`. Or `session.ts unname` to clear the most recent.
+
+**Key rules:**
+- The user NEVER types or sees session IDs. You handle all ID resolution behind the scenes.
+- Names are 1-50 characters. If the user gives something longer, ask them to shorten it.
+- Named sessions show as `Name — summary` in list view and `Name: X` in detail view.
+- Names are searchable — `/session search "Vault Reorg"` finds named sessions with highest relevance.
+- Names can be cleared with `unname` — this removes the name but preserves the AI summary.