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

CommandHook
TriggerYou type /nameAn agent event (for example before a shell command or after a file edit)
DeterminismLow. The model reads the prompt and may varyHigh. Same script, same input, same result
Written inMarkdownAny executable, registered in .cursor/hooks.json
Can it stop the agent?No, it only asksA hook can refuse an action (check the builder for the current output contract)
Example/ship: run the checks, then commitRun 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.