# Cursor Hooks

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

- Skill: `hktitan/cursor-hooks` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add hktitan/cursor-hooks`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hktitan/cursor-hooks/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: HKTITAN (https://skillmd.com/u/hktitan)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/hktitan/cursor-hooks

---


# 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]]