Set up Cursor hooks

Build a hooks.json file in Tokenize and roll it out so Cursor reports agent sessions to the desktop app on every machine.

Cursor reads a hooks.json file to know when to call the Tokenize desktop app's transcript shipper. The Cursor hooks page builds that file for you, so you can roll it out to your team instead of editing ~/.cursor/hooks.json on every machine.

Who can do this: Admins. The page is at Settings → Cursor hooks.

Hooks only work on computers that have the desktop app installed. Install it first. See Install on your computer or Deploy with MDM.

Build the file

  1. Go to Settings → Cursor hooks.
  2. Pick the platform: macOS, Windows, or Linux. The install path and data directory change to match.
  3. Copy the hooks.json shown on the page with the copy button.

To see what each hook does, open the Cursor Dashboard tab under Install and click View hooks.

What the hooks record

By default the file has nine hooks:

  • Session events: sessionStart, sessionEnd, beforeSubmitPrompt, stop, subagentStart, subagentStop. These mark when sessions, prompt turns, and subagents start and end.
  • Tool events: beforeShellExecution, beforeMCPExecution, afterFileEdit. These record shell commands, MCP tool calls, and file edits.

The shell and MCP hooks always answer "allow", so they observe and never block anyone's work in Cursor.

Advanced options

Click Advanced options to change:

  • Shipper install location: the path to transcript-shipper on each device. Change this if you installed the desktop app somewhere other than the default.
  • Data directory: passed to each hook as --data-dir.
  • Record shell and MCP tool calls: on by default. Needs Cursor 3.12.10 or later. Turn it off to leave out the three tool hooks.
  • Send command text to the shipper: on by default. Turn it off if your desktop app is configured with ShipPromptText=false. See What data Tokenize collects.

The default Windows install path includes PalindromeLabs, the product's former name. That is expected.

Roll it out

Under Install, pick how you want to roll the file out.

Cursor Dashboard

If you have Cursor Enterprise, paste the hooks in the Cursor Dashboard. Click Open Cursor to go to the hooks page. Cursor syncs them to signed-in users. You can set a different file for each OS.

MDM

Push the JSON file with Jamf, Kandji, Intune, or a similar tool. Write it to:

PlatformPath
macOS/Library/Application Support/Cursor/hooks.json
WindowsC:\ProgramData\Cursor\hooks.json
Linux/etc/cursor/hooks.json

Git

Add the file to a repository as .cursor/hooks.json. Anyone who works in that repo gets these hooks. It only applies to that repo.