Cursor Commands vs Hooks: What Runs When
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
| Command | Hook | |
|---|---|---|
| Trigger | You type /name | An agent event (for example before a shell command or after a file edit) |
| Determinism | Low. The model reads the prompt and may vary | High. Same script, same input, same result |
| Written in | Markdown | Any executable, registered in .cursor/hooks.json |
| Can it stop the agent? | No, it only asks | A hook can refuse an action (check the builder for the current output contract) |
| Example | /ship: run the checks, then commit | Run Prettier on every edited file |
Event names and the hook input/output format are Cursor's and may change; the 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, 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 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.
Related pages
Frequently asked questions
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.
Build a hooks.json without hand-writing it
Pick the event and the command, download the file, drop it into .cursor/hooks.json.