chs

Files (9)

• SKILL.md
• chs_config.example.json
• command-reference.md · references/
• configuration.md · references/
• examples.md · references/
• _edit_data.json · scripts/
• _edit_helper.py · scripts/
• _runner.py · scripts/
• chs_cli.py · scripts/

SKILL.md (first lines)

# Chat History Search (/chs)

## Purpose

Dedicated search for Claude Code chat history with advanced features: summarization modes, workspace aliases, tool filtering, context preview, session statistics, and branch filtering.

**Why /chs instead of /find?**
- `/find` = Unified search across all sources (chat + knowledge + code + docs)
- `/chs` = Chat-specific workflows with dedicated features for conversation analysis

## Project Context

### Technical Architecture
- **Primary CLI**: `P://packages/.claude-marketplace/plugins/search-research/skills/chs/scripts/chs_cli.py`
- **CHS Backend**: Reuses existing CHS infrastructure from `/find`
- **Two-Stage Search**: Lightweight index → Deep content scan (on-demand)
- **Storage**: SQLite metrics database at `P://packages/.claude-marketplace/plugins/search-research/data/chs_metrics.db`
- **FTS5 bootstrap**: `python -m core.chs.scripts.reindex_from_jsonl --db-path "P://__csf/data/chat_history.db" --history-path "~/.claude/history.jsonl"`
- **Bootstrap rule**: If `chat_history.db` exists but schema/FTS tables are missing, reindex from `history.jsonl` before trusting search results

### Session Resolution (Registry-Only)

**Source of truth:** `P:/.claude/.artifacts/session_registry.jsonl` — append-only JSONL written by `PreCompact` hook.

**How it works:**
1. **Find current session:** Query registry by `terminal_id` (WT_SESSION env var) → get most recent `session_id`
2. **Build full chain:** Query registry by `session_id` → aggregate all entries across terminals → extract unique `transcript_path` values in chronological order
3. **Result:** Complete `transcript_chain` array spanning all compactions and terminal switches

**Why registry instead of identity.json:**
- Registry is the source of truth (written by PreCompact)
- Identity.json was just a cache (written by SessionStart, deleted at compaction)
- Registry contains cross-terminal session history (identity.json is single-terminal only)
- Registry always works (identity.json doesn't exist for fresh sessions)

**Data structure:**
```json
{"ts": "2026-05-27T12:00:00", "terminal_id": "console_abc", "session_id": "uuid-123", "transcript_path": "C:\\Users\\...\\uuid-123.jsonl", ...}
```

Each `session_id` appears multiple times (once per terminal/compaction). Aggregating by `session_id` reconstructs the full chain.

### Consolidation History
- Previously part of `/find` (consolidated old `/chs`, `/recent`, `/find-more`)
- Now re-extracted as dedicated chat history skill with advanced features
- `/find` handles unified queries; `/chs` handles chat-specific workflows

## Your Workflow

1. **Parse query** - Extract filters (workspace, tool, branch, date, mode)
2. **Stage 1 search** - Lightweight index-only search (firstPrompt, summary fields)
3. **Check results** - If insufficient, trigger Stage 2
4. **Stage 2 search** - Deep JSONL content scan (only when needed)
5. **Apply filters** - Tool, branch, workspace, date filters
6. **Generate output** - Summary, context preview, or full details
7. **Optional summarization** - Apply selected summarization mode

## Quick Start: Searching Previous Sessions

When you have a session_id from handoff context or need to find content from a previous conversation:

### With session_id (from handoff)

```bash
# View the session with surrounding context
/chs show {session_id} --context 20

# Search within a specific session for unique phrases
/chs "CRITICAL: You MUST call Skill" --session {session_id}

# Use two-stage search for deep exploration
/chs "Option A Option B Option C" --session {session_id} --stage auto
```

### Without session_id (search across all sessions)

```bash
# Search for unique phrases from the conversation
/chs "unique phrase from discussion"

# Filter by workspace or time
/chs "authentication" --workspace tiny-vacation --since "7 days ago"

# Use context preview to see surrounding messages
/chs show {found_session_id} --context 10
```

### Why /chs instead of generic search tools

| Feature | /chs | Generic (grep/Read) |
|---------|-----|---------------------|
| **Speed** | ~10ms index, ~500ms deep | Full file scan every time |
| **Context** | Session-aware, filters | Raw content only |
| **Precision** | Two-stage search | Manual pattern refinement |
| **Output** | Structured with context | Raw grep results |

### Search Tips from Failure Analysis

**DO:**
- Use unique phrases from the conversation ("CRITICAL: You MUST call Skill")
- Combine multiple unique terms for better matching
- Search the handoff session file first
- Use `--context` flag to see surrounding messages

**DON'T:**
- Use generic terms ("Option A") that match unrelated content
- Search current session when handoff points to previous session
- Use grep/python when /chs exists and has the session
- Load full conversations unnecessarily (use two-stage search)

## Seven Key Features

### 1. Summarization Modes

Transform raw chat history into structured documentation.

| Mode | Description | Use Case |
|------|-------------|----------|
| `documentation` | Full technical doc: problem, changes, patterns, lessons | Deep dive into complex sessions |
| `short-memory` | MEMORY.md-ready bullets (500-2000 chars) | Quick knowledge capture |

From EndUser123/search-research, MIT.

More from EndUser123/search-research