Skip to content

feat(cursor): add automatic transcript sync hook - #314

Draft
lesbass wants to merge 2 commits into
melagiri:masterfrom
lesbass:feat/cursor-hook
Draft

feat(cursor): add automatic transcript sync hook#314
lesbass wants to merge 2 commits into
melagiri:masterfrom
lesbass:feat/cursor-hook

Conversation

@lesbass

@lesbass lesbass commented Aug 11, 2026

Copy link
Copy Markdown

What

Add a Cursor-native stop hook installer for automatic transcript sync:

code-insights install-hook --cursor
code-insights uninstall-hook --cursor

Fixes #313.

Stacked PR: depends on #312, which adds the modern Cursor Agent JSONL parser used by this hook. Review the final hook commit (5c75e3e) independently; the parser commit will disappear from this diff once #312 lands.

Why

code-insights install-hook currently supports only Claude Code. Cursor users can sync sessions manually, but Cursor now exposes native lifecycle hooks and supplies the current transcript path in its stop payload.

Cursor's stop event is the safest trigger for ingestion because it runs after a completed Agent turn while the shell execution host is still available. Its sessionEnd event is not an equivalent trigger: it fires when a composer/tab is closed and currently has a known command-execution failure during window_close.

Automatic analysis is intentionally not run on every Cursor stop; doing so would repeatedly spend LLM credits as the same multi-turn session grows.

How

cli/src/commands/install-hook.ts

  • Add --cursor dispatch while preserving Claude Code as the default behavior.
  • Read/write the user-level ~/.cursor/hooks.json native schema.
  • Preserve unrelated top-level settings and hook events.
  • Install one idempotent stop command and remove only Code Insights entries on uninstall.

cli/src/commands/cursor-stop.ts

  • Add a small non-blocking hook entry point.
  • Accept Cursor's conversation_id, transcript_path, status, and hook_event_name payload.
  • Sync only completed stop events using syncSingleFile(..., sourceTool: 'cursor').
  • Ignore malformed, incomplete, aborted, or unrelated events without blocking Cursor.

cli/src/index.ts

  • Register install-hook --cursor, uninstall-hook --cursor, and the internal cursor-stop command.

Tests and documentation

  • Cover install, uninstall, preservation, idempotency, payload validation, event/status filtering, sync routing, and failure isolation.
  • Document the Cursor workflow and remove stale references to unsupported --sync-only / --analysis-only flags.

Behavior and limitations

  • The hook performs sync only; Cursor analysis remains explicit.
  • Cursor sessions with two or fewer messages retain the existing trivial-session filtering behavior.
  • The configuration is user-level and applies across Cursor workspaces.
  • The hook requires a Cursor version that supports the native stop event and transcript_path payload.

Schema Impact

  • SQLite schema changed: no
  • Types changed: additive internal hook config types only
  • Server API changed: no
  • Existing Claude hook behavior changed: no
  • Backward compatible: yes

Testing

  • Full CLI suite passes: 593/593 tests across 29 test files.
  • pnpm --filter @code-insights/cli build passes.
  • Real CLI smoke test in an isolated temporary home confirms:
    • install-hook --cursor writes the expected native ~/.cursor/hooks.json structure.
    • uninstall-hook --cursor removes only the managed stop hook.
    • No real user Cursor or Claude configuration was touched.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add a Cursor stop hook for automatic transcript sync

1 participant