Sessions & Events

Overview

A session represents a single Claude Code conversation. When the Surchin plugin is active, each session is automatically tracked with:

• A unique session ID tied to the Claude Code process
• Start and end timestamps
• Counters for events captured, queries made, and insights deposited
• A generated summary after finalization
• The repository context where the session occurred

Event Timeline

The session detail page at /dashboard/sessions/[id] displays a chronological timeline of every event captured during the session. Each event shows:

• Event type — edit, write, test, build, git, migration, or error
• Tool name — the Claude Code tool that triggered the event
• File paths — which files were involved
• Summary — a concise description of what happened
• Timestamp — when the event occurred
• Promotion status — whether the event has been promoted to an insight

Turn Summaries

Each turn (a complete Claude response cycle) generates a summary with per-turn metadata. Turn summaries are ordered by turn number and include:

• A heuristic summary of what happened during that turn
• Count of events in the turn
• Files modified
• Whether tests were run, and pass/fail counts

Turn summaries provide a compact, structured view of session progression without needing to read every individual event.

Session Finalization

When a session ends, the finalization process aggregates all turn summaries into a session-level summary, records the session duration, and runs promotion heuristics to automatically surface high-signal events as draft insights. The finalized session includes activity counts (events captured, queries made, deposits created) and links to any auto-promoted insights.

Promote to Insight

Any session event can be manually promoted to a full insight from the dashboard. When promoting, you supply:

• Content — edited text describing the knowledge (pre-populated from the event summary)
• Kind — SOLUTION, PATTERN, PITFALL, CONTEXT, WORKFLOW, or DEPENDENCY
• File patterns — optional file path anchors
• Tags — optional topic tags
• Error signature — optional error text for fingerprinting

Promotion runs the event through the full deposit pipeline — embedding generation, deduplication check, and strength scoring. The event is then linked to the resulting insight via a promoted_to reference. Events that have already been promoted cannot be promoted again.

API Endpoints