Cursor

Quick install

If this machine is already paired, one command configures Cursor:

birdybeep agent install cursor

Ready after installation

Cursor loads the hooks as soon as they are written. The app shows the integration as installed, and the next Cursor session appears after its first event.

What gets written

Install merges BirdyBeep-managed entries into ~/.cursor/hooks.json. Your existing hooks are preserved, the original file is backed up once to hooks.json.birdybeep-backup, and re-running install changes nothing:

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      { "command": "birdybeep hook cursor", "timeout": 30 }
    ],
    "beforeShellExecution": [
      { "command": "birdybeep hook cursor", "timeout": 30 }
    ]
  }
}

The same entry is registered under every documented Cursor hook — sessionStart, sessionEnd, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, beforeShellExecution, stop, afterAgentResponse, subagentStart and subagentStop — so you're covered whichever events your Cursor version fires.

Cursor passes each event to the command as JSON on stdin. The command reads your machine token from the secure store at event time and does not write it here.

A slow or offline backend never holds up Cursor: the send itself has a hard ~3s timeout, and anything that doesn't make it goes to the local 24h queue to be retried on a later event. The 30 in the hook entry is Cursor's own kill deadline — a backstop, not the thing that keeps the hook fast.

Events you'll get

With Private Mode on (free for everyone), the push drops repo, branch, path, and command.

cursor-agent (headless)

Headless cursor-agent -p fires only sessionStart and sessionEnd today — it never fires stop. That's why a completed sessionEnd maps to agent_completed: on the CLI it is your finished beep. In the Cursor IDE you additionally get the tool, approval and stop events above.

Test it

Send a real test beep to confirm the integration end to end:

birdybeep test
# → beep sent. check your phone.

If the test beep does not arrive, run birdybeep doctor. It checks pairing, the hooks file, and delivery.

Security note