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 Updated 46 repo stars

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 commit 368f5470c0

Frequently asked questions

npx get-skill add hktitan/cursor-hooks