Skip to content

feat: Add event-bus integration for cross-session insights #59

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
evansenter merged 1 commit into from
Jan 8, 2026
Merged

feat: Add event-bus integration for cross-session insights #59

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ Parses your Claude Code session logs (`~/.claude/projects/**/*.jsonl`) and provi
- **Permission gaps** - Commands that should be added to settings.json
- **Token usage** - Usage breakdown by day, session, or model
- **Session timeline** - Events across conversations with filtering
- **Cross-session insights** - Gotchas, patterns, and learnings from [event-bus](https://github.com/evansenter/claude-event-bus)

Data is stored persistently in SQLite and auto-refreshes when stale (>5 min old).

Expand Down Expand Up @@ -76,6 +77,9 @@ session-analytics-cli git-ingest # Import git commit history
session-analytics-cli git-correlate # Link commits to sessions
session-analytics-cli session-commits # Show commits per session

# Event-Bus Integration
session-analytics-cli bus-events # Query cross-session events (gotchas, patterns)

# Pattern Inspection
session-analytics-cli sample-sequences # Sample instances of a pattern with context
```
Expand All @@ -87,7 +91,7 @@ All commands support:

## MCP Tools

28 tools available when running as an MCP server:
30 tools available when running as an MCP server:

| Category | Tools |
|----------|-------|
Expand All @@ -100,6 +104,7 @@ All commands support:
| **Messages** | `get_session_messages`, `search_messages` |
| **Relationships** | `detect_parallel_sessions`, `find_related_sessions` |
| **Git** | `ingest_git_history`, `correlate_git_with_sessions`, `get_session_commits` |
| **Event-Bus** | `ingest_bus_events`, `get_bus_events` |

For detailed usage, read the MCP resource `session-analytics://guide` or see [guide.md](src/session_analytics/guide.md).

Expand All @@ -123,6 +128,7 @@ make check

- **Database**: `~/.claude/contrib/analytics/data.db`
- **Logs parsed from**: `~/.claude/projects/**/*.jsonl`
- **Event-bus source**: `~/.claude/contrib/event-bus/data.db` (if [claude-event-bus](https://github.com/evansenter/claude-event-bus) is installed)

## How It Works

Expand Down
216 changes: 216 additions & 0 deletions docs/event-bus-integration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,216 @@
# Event-Bus Integration

Session Analytics can ingest events from [claude-event-bus](https://github.com/evansenter/claude-event-bus) for queryable cross-session insights.

## Overview

The event-bus enables Claude Code sessions to communicate asynchronously. By ingesting these events, you can:

- Track gotchas and patterns discovered across sessions
- See help requests and responses between sessions
- Correlate task progress across parallel work
- Surface cross-session learnings in `/improve-workflow`

## Prerequisites

Install [claude-event-bus](https://github.com/evansenter/claude-event-bus). The integration is optional—session-analytics works without it.

## Data Flow

```
┌─────────────────────────────────────────────────────────────────┐
│ Event-Bus Database │
│ ~/.claude/contrib/event-bus/data.db │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ events table: id, event_type, channel, session_id, payload ││
│ └─────────────────────────────────────────────────────────────┘│
└───────────────────────────┬─────────────────────────────────────┘
│ Read-only connection
▼
┌─────────────────────────────────────────────────────────────────┐
│ ingest_bus_events() │
│ - Incremental: tracks last ingested event_id │
│ - Extracts repo from channel (e.g., "repo:dotfiles" → "dotfiles")
│ - Stores raw payload unchanged │
└───────────────────────────┬─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Session Analytics Database │
│ ~/.claude/contrib/analytics/data.db │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ bus_events table: event_id, timestamp, event_type, channel,││
│ │ session_id, repo, payload ││
│ └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘
```

## Event Types

Common event types from event-bus:

| Event Type | Description |
|------------|-------------|
| `gotcha_discovered` | Non-obvious issues found during work |
| `pattern_found` | Useful patterns identified |
| `help_needed` | Request for assistance from other sessions |
| `help_response` | Response to a help request |
| `task_started` | Work begun on an issue/PR |
| `task_completed` | Work finished (merged, closed) |
| `ci_completed` | CI run finished (pass/fail) |
| `wip_checkpoint` | Work-in-progress snapshot |

## API Reference

### CLI

```bash
# Ingest and query events
session-analytics-cli bus-events --days 7

# Filter by event type
session-analytics-cli bus-events --event-type gotcha_discovered

# Filter by repository
session-analytics-cli bus-events --repo dotfiles

# Limit results
session-analytics-cli bus-events --limit 20

# JSON output
session-analytics-cli bus-events --json
```

### MCP Tools

#### `ingest_bus_events(days?)`

Ingest events from event-bus database. Performs incremental ingestion by tracking the last ingested event ID.

**Parameters:**
- `days` (int, default: 7): Days to look back on first run

**Returns:**
```json
{
"status": "ok",
"events_ingested": 42,
"last_event_id": 1438,
"oldest_event": "2025-01-01T10:00:00",
"newest_event": "2025-01-08T01:30:00"
}
```

If event-bus is not installed:
```json
{
"status": "skipped",
"reason": "event-bus database not found",
"path": "~/.claude/contrib/event-bus/data.db"
}
```

#### `get_bus_events(days?, event_type?, session_id?, repo?, limit?)`

Query ingested event-bus events.

**Parameters:**
- `days` (int, default: 7): Time range to query
- `event_type` (str, optional): Filter by event type
- `session_id` (str, optional): Filter by source session
- `repo` (str, optional): Filter by repository name
- `limit` (int, default: 100): Maximum events to return

**Returns:**
```json
{
"events": [
{
"event_id": 1438,
"timestamp": "2025-01-08T01:30:47",
"event_type": "task_completed",
"channel": "repo:dotfiles",
"session_id": "6cd931c1-929b-4c9c-beb6-507e43e7feec",
"repo": "dotfiles",
"payload": "Merged PR #182 - Add named sessions to /parallel-work"
}
],
"type_breakdown": {
"task_completed": 15,
"gotcha_discovered": 8,
"ci_completed": 42
},
"total_events": 65
}
```

## Integration with Insights

When event-bus data is available, `get_insights()` includes cross-session activity:

```json
{
"cross_session_activity": {
"gotcha_discovered": 8,
"pattern_found": 3,
"help_needed": 2,
"task_completed": 15
},
"summary": {
"has_bus_events": true
}
}
```

This enables `/improve-workflow` to surface cross-session learnings.

## Design Principles

This integration follows the project's design philosophy:

1. **Raw signals over interpretation**: Payloads are stored unchanged. The `repo` field is extracted for filtering, but no semantic analysis is performed. The consuming LLM interprets meaning.

2. **Guaranteed drill-down**: `get_bus_events()` returns raw events with full payloads. You can filter by `event_type`, `session_id`, or `repo` to focus on specific signals.

3. **API conformance**: Follows existing patterns:
- `ingest_bus_events(days)` matches `ingest_logs`, `ingest_git_history`
- `get_bus_events(...)` matches `get_session_events`, `get_agent_activity`

## Schema

The `bus_events` table (migration v6):

```sql
CREATE TABLE bus_events (
id INTEGER PRIMARY KEY,
event_id INTEGER UNIQUE NOT NULL, -- Original ID from event-bus
timestamp TIMESTAMP NOT NULL,
event_type TEXT NOT NULL,
channel TEXT,
session_id TEXT,
repo TEXT, -- Extracted from channel
payload TEXT, -- Raw payload unchanged
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Indexes for common queries
CREATE INDEX idx_bus_events_timestamp ON bus_events(timestamp);
CREATE INDEX idx_bus_events_type ON bus_events(event_type);
CREATE INDEX idx_bus_events_session ON bus_events(session_id);
CREATE INDEX idx_bus_events_repo ON bus_events(repo);
```

## Troubleshooting

### "event-bus database not found"

Install [claude-event-bus](https://github.com/evansenter/claude-event-bus) and ensure at least one session has registered.

### Events not appearing

1. Check ingestion status: `session-analytics-cli bus-events --json | jq .total_events`
2. Force re-ingest: Events are ingested incrementally; if the event-bus database was recreated, you may need to clear the analytics `bus_events` table.

### Stale data

Data auto-refreshes when queries detect stale data (>5 min). You can also manually trigger ingestion via the MCP tool `ingest_bus_events()`.
Loading