Cursor Hooks

File-based agent loop hooks via `.cursor/hooks.json` — pre/post commands, governance gates. Use when enforcing policy without modifying agent prompts.

HKTITAN 368f547 4 files · 2.8 KB Updated

File contents

cursor-hooks

Hooks are file-based, not programmatic. The SDK does not expose JS callbacks for the agent loop — use .cursor/hooks.json and rely on local.settingSources to load them.

When to use

  • Lint / type-check gates before agent commits
  • Audit logging or compliance commands after each turn
  • Fail-fast policies that must run regardless of prompt

Concepts

  • [[references/file-format]] — .cursor/hooks.json shape
  • [[references/loading]] — settingSources and project vs user vs team scope
  • [[references/programmatic-alternatives]] — what to use when you need JS callbacks (onDelta, onStep)

Cross-links

  • local.settingSources → [[../cursor-sdk/references/local-options]]
  • Stream-side observation → [[../cursor-runs/references/interaction-updates]]
  • Sibling .cursor/ features → [[../cursor-rules/SKILL]] · [[../cursor-skills-system/SKILL]]

HKTITAN/cursor-sdk/tree/main/skills/cursor-hooks commit 368f5470c0

Frequently asked questions

npx skillmds@latest add hktitan/cursor-hooks