Skip to main content

​
Runtime overview

Beacon supports Cursor through native hook payloads sent to beacon-hooks, with local session-store sync for historical backfill. For provider-managed Cursor cloud sessions, see Cursor Cloud Agents.

​
Prerequisites

Before enabling Cursor hooks, make sure:
  • Cursor is installed for the user or the ~/.cursor directory exists.
  • beacon endpoint install has run so shared endpoint config and runtime log paths exist.
  • Beacon hooks are installed with beacon endpoint hooks install --harness cursor.
  • For project-level collection, install hooks from the target project with --level project.
  • Cursor is restarted after hook install or removal so new sessions load the updated hook configuration.

​
Collection path

Cursor invokes Beacon’s hook adapter from Cursor hook configuration. The adapter writes normalized endpoint events to the configured runtime JSONL log. Beacon can also read Cursor’s committed local session stores:
Sync Cursor local sessions
The sync path reads Cursor Composer conversations from the global VS Code storage database and agent transcripts under ~/.cursor/projects. It is local and offline, emits events with harness.collection_method=poll, and is useful for historical sessions or sessions that ran before Beacon hooks were installed. Use --print to inspect mapped events without writing the runtime log or advancing the cursor.

​
Discovery and status

Beacon detects Cursor through the Cursor binary or ~/.cursor, then checks Beacon hook configuration. Use beacon endpoint hooks status --harness cursor to inspect Cursor hook status. Use beacon endpoint cursor status to inspect local session stores and how much Beacon has synced.

​
Install or configuration support

beacon endpoint install prepares shared endpoint config and runtime log paths. Install Cursor hooks separately:
Install runtime hooks
For project-level hooks, run:
Install project-level hooks

​
Telemetry coverage

​
Session-store sync

beacon endpoint cursor sync reads Cursor records after Cursor has committed them. It can recover committed prompts, assistant text, tool and command activity, file activity where the stored record names a path, and session metadata present in Cursor’s local stores. It cannot hold or deny tool calls, and it does not imply that Beacon observed the event at runtime. Run beacon endpoint cursor sync --watch, or schedule one-shot sweeps, if you want the poll path to stay current.

​
Deployment notes

Restart Cursor after installing or removing hooks so the updated hook configuration is picked up by new sessions. Hook events include metadata such as file path, operation, language, diff hash, and diff byte count. Raw diffs and reasoning text are subject to Beacon’s redaction, sanitization, truncation, and event-size limits before writing.

Supported agent harnesses

Return to the runtime support overview.

Hooks

Install, inspect, and uninstall runtime hook integrations.

Cursor Cloud Agents

Capture Cursor cloud agent telemetry with sandbox-local hooks and direct GCS or S3 upload.