Skip to content

Commit 4c0c60d

Browse files
evansenterclaude
evansenter
and
claude
committed
Expand MCP usage guide with Phase 2-9 documentation
- Add tool tables for failure analysis, session classification, trend analysis, user workflow, and git integration - Add usage examples for each new feature category - Include session category definitions with thresholds - Expand from 68 to 297 lines for comprehensive coverage 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 7968220 commit 4c0c60d

1 file changed

Lines changed: 259 additions & 30 deletions

File tree

‎src/session_analytics/guide.md‎

Lines changed: 259 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,68 +1,297 @@
11
# Session Analytics Usage Guide
22

3-
This MCP server provides queryable analytics on Claude Code session logs.
3+
## What is this?
44

5-
## Quick Start
5+
Session Analytics provides queryable analytics on Claude Code session logs. It parses
6+
the JSONL files from `~/.claude/projects/` and stores them in SQLite for fast querying.
7+
Use it to understand your Claude Code usage patterns, find workflow improvements, and
8+
identify permission gaps.
69

7-
The server auto-refreshes data when queries detect stale data (>5 min old).
8-
You can also manually trigger ingestion:
10+
## Available Tools
911

10-
```
11-
ingest_logs(days=7) # Process last 7 days of logs
12-
```
12+
### Status & Ingestion
1313

14-
## Available Tools
14+
| Tool | Purpose |
15+
|------|---------|
16+
| `get_status()` | Database stats, last ingestion time |
17+
| `ingest_logs(days?, project?, force?)` | Refresh data from JSONL files |
1518

16-
### Ingestion
19+
### Core Queries
20+
21+
| Tool | Purpose |
22+
|------|---------|
23+
| `query_tool_frequency(days?, project?)` | Tool usage counts (Read, Edit, Bash, etc.) |
24+
| `query_commands(days?, prefix?, project?)` | Bash command breakdown |
25+
| `query_sessions(days?, project?)` | Session metadata and token totals |
26+
| `query_tokens(days?, by?, project?)` | Token usage by day, session, or model |
27+
| `query_timeline(hours?, tool?, session_id?)` | Recent events with filtering |
28+
29+
### Pattern Analysis
30+
31+
| Tool | Purpose |
32+
|------|---------|
33+
| `query_sequences(days?, min_count?, length?)` | Common tool chains (e.g., Read → Edit → Bash) |
34+
| `query_permission_gaps(days?, threshold?)` | Commands that should be in settings.json |
35+
| `get_insights(days?, refresh?)` | Pre-computed patterns for /improve-workflow |
36+
37+
### Failure Analysis
38+
39+
| Tool | Purpose |
40+
|------|---------|
41+
| `query_failure_correlation(days?, project?)` | Correlate tool failures with commands |
42+
| `query_common_failures(days?, min_count?)` | Aggregate failure patterns |
43+
44+
### Session Classification
45+
46+
| Tool | Purpose |
47+
|------|---------|
48+
| `classify_sessions(days?, project?)` | Categorize sessions (debugging, development, research, maintenance) |
49+
| `query_session_progression(session_id)` | Track session stage transitions |
50+
51+
### Trend Analysis
1752

1853
| Tool | Purpose |
1954
|------|---------|
20-
| `ingest_logs` | Refresh data from JSONL files |
21-
| `get_status` | Ingestion status + DB stats |
55+
| `analyze_trends(days?, compare_to?)` | Token/event trends with growth rates |
56+
| `compare_periods(days?, metric?)` | Period-over-period comparisons |
2257

23-
### Queries
58+
### User Workflow
2459

2560
| Tool | Purpose |
2661
|------|---------|
27-
| `query_timeline` | Events in time window |
28-
| `query_tool_frequency` | Tool usage counts |
29-
| `query_commands` | Bash command breakdown |
30-
| `query_sequences` | Common tool patterns |
31-
| `query_permission_gaps` | Commands needing settings.json |
32-
| `query_sessions` | Session metadata |
33-
| `query_tokens` | Token usage analysis |
34-
| `get_insights` | Pre-computed patterns |
62+
| `get_user_journey(days?, project?)` | Session summaries with tool chains |
63+
| `find_related_sessions(session_id)` | Find sessions with similar patterns |
64+
65+
### Git Integration
66+
67+
| Tool | Purpose |
68+
|------|---------|
69+
| `ingest_git_history(days?, repo_path?)` | Parse and store git commits |
70+
| `correlate_git_with_sessions(days?)` | Link commits to sessions by timing |
71+
| `query_session_commits(session_id)` | Get commits associated with a session |
72+
73+
## Quick Start
74+
75+
### 1. Check status
76+
```
77+
get_status()
78+
→ {last_ingestion: "2025-01-15T10:30:00", event_count: 5432, db_size_mb: 2.1}
79+
```
80+
81+
### 2. Ingest recent logs
82+
```
83+
ingest_logs(days=7)
84+
→ {files_processed: 12, entries_added: 847, entries_skipped: 23}
85+
```
86+
Data auto-refreshes when queries detect stale data (>5 min old).
87+
88+
### 3. Query your usage
89+
```
90+
query_tool_frequency(days=30)
91+
→ {tools: [{name: "Read", count: 1234}, {name: "Edit", count: 567}, ...]}
92+
```
3593

3694
## Common Patterns
3795

3896
### Understanding tool usage
3997

4098
```
99+
# What tools do I use most?
41100
query_tool_frequency(days=30)
101+
102+
# What bash commands do I run?
103+
query_commands(days=30, prefix="git") # Just git commands
104+
query_commands(days=30) # All commands
105+
```
106+
107+
### Finding workflow sequences
108+
109+
```
110+
# What 2-tool patterns are common?
111+
query_sequences(length=2, min_count=10)
112+
→ [{pattern: "Read → Edit", count: 234}, {pattern: "Grep → Read", count: 156}, ...]
113+
114+
# What 3-tool patterns?
115+
query_sequences(length=3, min_count=5)
116+
→ [{pattern: "Read → Edit → Bash", count: 45}, ...]
117+
```
118+
119+
### Identifying permission gaps
120+
121+
```
122+
# Commands I use frequently but haven't added to settings.json
123+
query_permission_gaps(threshold=5)
124+
→ [{command: "npm test", count: 23, suggestion: "Bash(npm test:*)"}, ...]
125+
```
126+
127+
Add these to your `~/.claude/settings.json` under `permissions.allow`.
128+
129+
### Token usage analysis
130+
131+
```
132+
# Usage by day
133+
query_tokens(days=30, by="day")
134+
135+
# Usage by model
136+
query_tokens(days=30, by="model")
137+
138+
# Usage by session
139+
query_tokens(days=7, by="session")
140+
```
141+
142+
### Timeline exploration
143+
144+
```
145+
# Recent events
146+
query_timeline(hours=24)
147+
148+
# Filter by tool
149+
query_timeline(hours=24, tool="Bash")
150+
151+
# Filter by session
152+
query_timeline(session_id="abc123")
153+
```
154+
155+
### Session classification
156+
157+
```
158+
# Categorize recent sessions by activity type
159+
classify_sessions(days=30)
160+
→ {
161+
sessions: [
162+
{session_id: "abc", category: "development", confidence: 0.85},
163+
{session_id: "def", category: "debugging", confidence: 0.72},
164+
...
165+
],
166+
summary: {debugging: 5, development: 12, research: 3, maintenance: 2}
167+
}
42168
```
43169

44-
### Finding permission gaps
170+
Categories:
171+
- **debugging**: High error rate (>15%) or 5+ errors
172+
- **development**: Heavy editing (>30% edits or 3+ writes)
173+
- **maintenance**: Git/build focus without much editing
174+
- **research**: Mostly reading/searching codebase
175+
- **mixed**: No dominant pattern
176+
177+
### Failure analysis
45178

46179
```
47-
query_permission_gaps(threshold=5) # Commands used 5+ times that need permission
180+
# What commands tend to fail?
181+
query_common_failures(days=30, min_count=3)
182+
→ [{tool: "Bash", command: "cargo test", count: 12}, ...]
183+
184+
# Correlate failures with context
185+
query_failure_correlation(days=30)
186+
→ {correlations: [{tool: "Bash", command: "npm install", failure_rate: 0.15}, ...]}
48187
```
49188

50-
### Analyzing workflows
189+
### Git integration
51190

52191
```
53-
query_sequences(min_count=3, length=3) # Common 3-tool sequences
192+
# Ingest git history from current repo
193+
ingest_git_history(days=30)
194+
→ {commits_found: 45, commits_added: 42, skipped_malformed: 0}
195+
196+
# Link commits to sessions (within 5-min buffer of session)
197+
correlate_git_with_sessions(days=30)
198+
→ {sessions_analyzed: 20, commits_correlated: 38}
199+
200+
# See what commits were made during a session
201+
query_session_commits(session_id="abc123")
202+
→ [{sha: "abc...", message: "Fix auth bug", timestamp: "..."}]
203+
```
204+
205+
### Trend analysis
206+
207+
```
208+
# Compare this week to last week
209+
analyze_trends(days=7, compare_to="previous")
210+
→ {
211+
metrics: {
212+
events: {current: 500, previous: 400, change_pct: 25, direction: "up"},
213+
tokens: {current: 50000, previous: 45000, change_pct: 11, direction: "up"}
214+
}
215+
}
216+
217+
# Compare to same week last month
218+
analyze_trends(days=7, compare_to="same_last_month")
54219
```
55220

56221
## Integration with /improve-workflow
57222

58-
The `get_insights` tool returns pre-computed patterns specifically for
59-
the `/improve-workflow` command:
223+
The `get_insights` tool returns pre-computed patterns specifically formatted
224+
for the `/improve-workflow` command:
60225

61226
```
62-
get_insights(refresh=True) # Force fresh analysis
227+
get_insights(days=30, refresh=True)
228+
→ {
229+
tool_frequency: [...],
230+
command_frequency: [...],
231+
sequences: [...],
232+
permission_gaps: [...],
233+
summary: {has_gaps: true, top_tools: ["Read", "Edit", "Bash"]}
234+
}
63235
```
64236

65-
## Data Location
237+
This powers data-driven workflow improvement suggestions.
238+
239+
## Best Practices
240+
241+
### Ingestion
242+
243+
1. **Let auto-refresh work** - Queries auto-ingest when data is stale (>5 min)
244+
2. **Use project filter** - `ingest_logs(project="my-repo")` for faster, focused ingestion
245+
3. **Force refresh sparingly** - `force=True` re-parses everything, slower but thorough
246+
247+
### Querying
248+
249+
4. **Start with frequency** - `query_tool_frequency` gives quick overview
250+
5. **Use day filters** - `days=7` for recent trends, `days=30` for patterns
251+
6. **Project filter** - Most queries accept `project` to focus on one repo
252+
253+
### Permission Gaps
254+
255+
7. **Check weekly** - Run `query_permission_gaps(threshold=3)` to catch new patterns
256+
8. **Higher threshold = less noise** - Start with `threshold=10` if overwhelmed
257+
9. **Review before adding** - Some commands shouldn't be auto-approved
258+
259+
### Workflow Improvement
260+
261+
10. **Use /improve-workflow** - It consumes `get_insights` and generates suggestions
262+
11. **Look for sequences** - Repeated patterns might benefit from automation
263+
12. **Track over time** - Compare `days=7` vs `days=30` to see trend changes
264+
265+
## Data Details
266+
267+
### Storage Location
268+
269+
| Item | Path |
270+
|------|------|
271+
| Database | `~/.claude/contrib/analytics/data.db` |
272+
| Source logs | `~/.claude/projects/**/*.jsonl` |
273+
274+
### What's Tracked
275+
276+
Each event includes:
277+
- Timestamp and session ID
278+
- Tool name and entry type
279+
- For Bash: command prefix (e.g., "git", "npm")
280+
- For file ops: file path
281+
- Token counts (input/output)
282+
- Error status
283+
284+
### Incremental Ingestion
285+
286+
The server tracks file mtimes and sizes. Only changed files are re-parsed
287+
on subsequent ingestions, making `ingest_logs` fast for daily use.
288+
289+
## Tips
66290

67-
- Database: `~/.claude/contrib/analytics/data.db`
68-
- Logs parsed from: `~/.claude/projects/**/*.jsonl`
291+
- Data auto-refreshes on query if stale (>5 min since last ingestion)
292+
- Use `get_status()` to check when data was last refreshed
293+
- The `project` filter uses LIKE matching - partial names work
294+
- `query_sequences` with `length=3` finds more complex patterns but needs more data
295+
- Permission gaps compare your usage against `~/.claude/settings.json`
296+
- Token queries help track API usage costs over time
297+
- The CLI (`session-analytics-cli`) mirrors all MCP tools for terminal use

0 commit comments

Comments
 (0)