# Cursor Commands vs Hooks

> Commands are prompts you type with /. Hooks are scripts that run on agent events. A decision table plus three setups: format on edit, block dangerous commands, audit log.

Canonical: https://www.agentickit.co/compare/cursor-commands-vs-hooks
Last updated: 2026-11-18

A command is a markdown prompt that runs only when you type it, and the model interprets it. A hook is a script wired to an agent event in .cursor/hooks.json, and it runs every time that event fires, whether or not the model remembers. Use commands for judgment, hooks for things that must always happen.



## Verdict
If you would be annoyed when it is skipped, it is a hook. If you want to decide each time, it is a command. A command asks the model to do a job; a hook does not ask anyone. That is why “always run the formatter” belongs in a hook while “review this PR” belongs in a command.

## Commands vs hooks at a glance
<table><thead><tr><th></th><th>Command</th><th>Hook</th></tr></thead><tbody><tr><td>**Trigger**</td><td>You type `/name`</td><td>An agent event (for example before a shell command or after a file edit)</td></tr><tr><td>**Determinism**</td><td>Low. The model reads the prompt and may vary</td><td>High. Same script, same input, same result</td></tr><tr><td>**Written in**</td><td>Markdown</td><td>Any executable, registered in `.cursor/hooks.json`</td></tr><tr><td>**Can it stop the agent?**</td><td>No, it only asks</td><td>A hook can refuse an action (check the builder for the current output contract)</td></tr><tr><td>**Example**</td><td>[/ship](https://www.agentickit.co/commands/ship): run the checks, then commit</td><td>Run Prettier on every edited file</td></tr></tbody></table>Event names and the hook input/output format are Cursor's and may change; [the Hooks Builder](https://www.agentickit.co/tools/hooks-builder) is the quickest way to see the current options.

## When to use each
**Command when** the job needs reading code, weighing trade-offs or writing prose: a review, an SEO audit, a launch checklist. You are the trigger on purpose, because you know when the moment is right.
**Hook when** the rule is mechanical and the cost of forgetting is real: formatting, secrets, destructive shell commands, logging. A line in a rule saying “never run `rm -rf`” is a request. A hook that refuses the command is a guarantee.
Many things need both. The command does the thinking; the hook guards the edges.

## Three setups that combine them
**1. Format on edit.** A hook on the after-file-edit event runs your formatter on the changed file. Your `/ship` command then never has to spend tokens on “fix the lint noise”, because the files are already clean.
**2. Block dangerous commands.** A hook on the before-shell-command event reads the proposed command and refuses patterns you never want the agent to run, such as `rm -rf`, `git push --force` or `DROP TABLE`. Keep the pattern list short, in a script you can read in ten seconds. A command cannot do this job: it runs when you ask, not before the agent acts.
**3. Audit log.** A hook appends a line (time, event, command or file) to a local file such as `.cursor/audit.log`. Then a command, say `/weekly-review`, reads that log and summarizes what the agent actually touched. The hook collects the facts; the command interprets them.

## Build one with the Hooks Builder
Open [/tools/hooks-builder](https://www.agentickit.co/tools/hooks-builder), pick the format or protect preset, adjust the command, and download `hooks.json`. Put it at `.cursor/hooks.json`. Test it with a harmless input first: a hook that wrongly blocks every shell command will stall the agent, and a hook that errors silently gives false confidence.

## What not to do
- Do not put judgment in a hook. A script that decides whether code is “good enough” will be brittle; give that to a command or the [code-reviewer](https://www.agentickit.co/agents/code-reviewer) agent.
- Do not rely on a command or rule alone for a hard ban. Prompts can be ignored; a hook cannot.
- Do not make hooks slow. They sit in the agent's path, so a ten-second hook costs ten seconds every time.
For rules and skills in the same picture, see [Rules vs Skills vs Commands](https://www.agentickit.co/compare/cursor-rules-vs-skills).



## FAQ

### What is the difference between Cursor commands and hooks?
Commands are markdown prompts you run by typing / in the agent. Hooks are scripts registered in .cursor/hooks.json that run automatically when an agent event fires. Commands rely on the model; hooks do not.

### Can a hook call a command?
Not directly. A hook runs a script, and commands are prompts for the agent. The usual pattern is the reverse: the hook records or enforces something, and a command reads the result later.

### Where does hooks.json go?
In .cursor/hooks.json in your project. The Hooks Builder on this site generates the file for you.

### Should I use a rule or a hook to stop the agent running dangerous commands?
Use a hook if the action must never happen. A rule is guidance the model can miss; a hook that refuses the command is enforced.

## Related
- [Hooks JSON Builder](https://www.agentickit.co/tools/hooks-builder)
- [Cursor Commands](https://www.agentickit.co/commands)
- [Rules vs Skills vs Commands](https://www.agentickit.co/compare/cursor-rules-vs-skills)
- [Skills vs Commands](https://www.agentickit.co/compare/cursor-skills-vs-commands)
- [Cursor Commands vs Rules Files](https://www.agentickit.co/compare/cursor-commands-vs-rules)
