1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105# history-context
File-based history search for Claude Code. Find which sessions edited specific files and retrieve conversation context.
## Why This Plugin?
Unlike semantic search (episodic-memory), this plugin uses Claude Code's native **file-history tracking** to know exactly which sessions edited which files. No git commits needed, works immediately.
## Features
- **File-to-session mapping**: Find all sessions that edited a specific file
- **Instant results**: Uses a cached index of file-history, not full-text search on every query
- **Full context retrieval**: Read conversation content with key decisions
- **Session IDs**: Returns complete UUIDs for reference
## Installation
### From GitHub
```bash
# Add the marketplace
/plugins marketplace add gentritbiba/history-context
# Install the plugin
/plugins install history-context
```
### That's It!
On first session start, the plugin automatically:
1. Copies the CLI tool to `~/.claude/commands/`
2. Builds the file-history index
To manually rebuild the index later:
```bash
~/.claude/commands/claude-history.py index --rebuild
```
## Usage
### Via Skill (Automatic)
The `file-history` skill triggers automatically when you:
- Ask about past work on a specific file
- Want to understand why code was written
- Reference "what we did before" on a feature
### Via Slash Command
```
/file-history src/components/AuthForm.tsx
```
### Via Agent
```
Use Task tool with subagent_type="history-context"
Prompt: "Find context for [file/feature]"
```
### Via CLI
```bash
# Find sessions that edited a file
~/.claude/commands/claude-history.py file "AuthForm.tsx"
# Search conversations for a topic
~/.claude/commands/claude-history.py search "authentication"
# Get session details
~/.claude/commands/claude-history.py session <id> --read
# Rebuild index
~/.claude/commands/claude-history.py index --rebuild --stats
```
## How It Works
1. **Indexes file-history**: Scans `~/.claude/file-history/` to build file→session mapping (cached for speed)
2. **Maps sessions to projects**: Cross-references with `~/.claude/projects/`
3. **Reads conversations**: Extracts messages from session `.jsonl` files
4. **Returns structured context**: Summary, decisions, session IDs, paths
### Why "Instant Results"?
- **First run/rebuild**: Scans all file-history and builds an index at `~/.claude/file-session-index.json`
- **Subsequent queries**: Reads from cached index (~5ms) instead of scanning all files (~500ms+)
- **Auto-refresh**: Cache rebuilds if older than 1 hour
## vs episodic-memory
| Aspect | history-context | episodic-memory |
|--------|-----------------|-----------------|
| Query type | File-specific | Semantic/conceptual |
| Accuracy | Exact (file tracking) | Fuzzy (embedding search) |
| Speed | Indexed | Full search |
| Best for | "What sessions touched this file?" | "How did we handle auth patterns?" |
**Use history-context** when you have a specific file or feature in mind.
**Use episodic-memory** for broad conceptual searches across all projects.
## License
MIT