Halo › Guides

How to know when Cursor's agent is done on a Mac

Cursor's agent can work for minutes at a time, and it's easy to lose track while you're in another window. Cursor has hooks, small commands it runs at moments like "the agent stopped", so your Mac can tell you. Here's the free way with a sound, and how to see every agent in the notch.

By Otabek Abdiraimov, who makes Halo. Updated 16 October 2026.

An AI agent waiting for you, shown in the MacBook notch by Halo — An agent waiting for you, in the notch. Cursor sessions show up here the same way as Claude Code and Codex.

How Cursor's hooks work

Cursor reads ~/.cursor/hooks.json for hooks that apply to every project (a project can also have its own .cursor/hooks.json). Each hook names an event and a command to run. The one you want is stop: Cursor runs it when the agent finishes, and tells it whether the run completed, was aborted or hit an error. A stop hook can't block or slow the agent.

Option 1: play a sound when the agent stops

Create the script ~/.cursor/hooks/done.sh with these two lines:
```
#!/bin/bash
afplay /System/Library/Sounds/Glass.aiff
```
Make it runnable: chmod +x ~/.cursor/hooks/done.sh

Create (or add to) ~/.cursor/hooks.json:

{
  "version": 1,
  "hooks": {
    "stop": [{ "command": "./hooks/done.sh" }]
  }
}

Restart Cursor if the hook doesn't fire on the next run.

User-level hook commands run from ~/.cursor/, which is why the path starts with ./hooks/. Swap Glass for any sound in /System/Library/Sounds.

The limit: a sound tells you something stopped, not which agent, or whether it's done or asking you something. With several agents running, you still go window to window.

Option 2: every agent in the notch, with Halo

Halo shows each Cursor agent in your Mac's notch, next to Claude Code and Codex: working (and what it's doing, like running a command or editing a file), has a question, or done with how long it took. Click one to jump back to Cursor's window for that project.

Open Halo's Settings › AI Agents.
Next to Cursor, click Connect. Halo adds its entries to ~/.cursor/hooks.json after any you already have, and backs the file up first.
Run an agent in Cursor and watch the notch. Disconnect removes only Halo's entries.

Halo only uses hooks that can't block the agent, so it never slows or stops Cursor. Everything stays on your Mac: Cursor's hook writes a line to a file, and Halo reads it. One honest note: Cursor doesn't report "waiting for an answer" directly, so Halo shows has a question when the agent's last reply ends with a question.

Which one to pick

One agent at a time: Option 1. A sound is enough.
Several agents, or Cursor next to Claude Code and Codex: Option 2, so you can see which one needs you without switching windows.

Questions

Does Cursor have a notification when the agent finishes?

Cursor can run a command when its agent stops, through a stop hook in ~/.cursor/hooks.json. Point it at a script that plays a sound, or connect Halo to see the agent's status in the notch.

Where is Cursor's hooks.json?

For every project: ~/.cursor/hooks.json, whose commands run from ~/.cursor/. A project can also have its own .cursor/hooks.json at its root.

Can a hook slow down or block Cursor's agent?

A stop hook can't. Hooks that run before a command or tool can, and a bad answer from one can block the action, which is why Halo never uses those.

Does it work with Cursor's background agents?

Hooks run where Cursor runs them. Halo shows the agents whose hooks run on your Mac.

Do I need Halo to get a sound?

No. The script in Option 1 is free and works on its own. Halo is for seeing which agent is working, waiting or done, without switching windows.

More guides: Know when Claude Code is done · Show notifications in the MacBook notch · All guides

Try Halo

Cursor, Claude Code and Codex in your notch, plus notifications, dictation and music. $9.99 one-time, no subscription.

Buy Halo

See everything Halo does ›