Auto-Capture
Surchin automatically captures significant agent activity via Claude Code hooks. Edits, test runs, builds, git operations, migrations, and errors are recorded as lightweight session events — no configuration needed.
How It Works
The auto-capture pipeline flows through three hooks that fire at different points in a Claude Code session:
- PostToolUse — After each tool call,
auto-capture.jsclassifies the event and sends it toPOST /api/v1/auto-capture. Events are stored insession_events(not insights). - Stop — When Claude finishes responding,
turn-summary.jscallsPOST /api/v1/sessions/turn-summaryto generate per-turn metadata from accumulated events. - SessionEnd — When the session ends,
session-end.jscallsPOST /api/v1/sessions/finalizeto aggregate turns, identify high-signal events, and promote them to draft insights.
Event Types
Not every tool call is captured. Read-only tools (Read, Glob, Grep, Agent, etc.) are skipped. The following event types are recorded:
| Event Type | Trigger | Example |
|---|---|---|
edit | Edit tool | Edited src/auth/validator.ts (120→145 chars) |
write | Write tool | Created/wrote src/new-file.ts (890 chars) |
test | Bash with vitest, jest, pytest, etc. | Tests PASSED: pnpm vitest run |
build | Bash with build, compile, tsc, webpack, etc. | Build succeeded: turbo build |
git | Bash with git commit, merge, rebase, cherry-pick | Git: git commit -m "fix auth flow" |
migration | Bash with migrate, supabase db, prisma, knex | Migration: supabase db push |
error | Tool execution that produces errors | Build FAILED: tsc --noEmit |
Turn Summaries
Each time Claude finishes responding (a “turn”), the Stop hook fires and generates a heuristic summary from the events captured during that turn. Turn summaries include metadata such as files modified, tests run, and pass/fail counts. They provide a compact record of what happened at each step of the session.
Session Finalization
When a Claude Code session ends, the SessionEnd hook triggers finalization. This aggregates all turn summaries into a session-level summary and runs promotion heuristics against the captured events.
Promotion Heuristics
During finalization, Surchin identifies high-signal event patterns and automatically promotes them to draft insights. Up to 5 insights can be promoted per session. Three heuristics are applied:
- iterative_edits — A file edited 3+ times in a single session suggests iterative work on a tricky area. Promoted as a
PATTERNinsight with all edit summaries. - test_fix — A test failure followed by edits followed by a passing test indicates a bug fix. Promoted as a
SOLUTIONinsight with the failure context and fix description. - recurring_error — The same error hit 2+ times in a session signals a non-obvious pitfall. Promoted as a
PITFALLinsight with the error summary and occurrence count.
Promotion thresholds are configurable per organization via the capture tuning settings.
Deduplication
Every event includes a content_hash computed from the session ID, tool name, and event summary. If the same hash already exists within a session, the event is deduplicated and the existing event ID is returned. A database-level UNIQUE(session_id, content_hash) constraint prevents duplicates even under concurrent writes.
Zero Configuration
Auto-capture works out of the box when the Surchin Claude Code plugin is installed. The hooks are registered automatically and fire silently in the background. They never block the agent — all capture operations fail silently so errors in the capture pipeline cannot disrupt your workflow.