Do I have to set up any hooks myself?

No. Agent HUD adds them when it starts. The one step left to you is Codex's: it runs a new hook only after you trust it in /hooks.

Will Agent HUD change the hooks I already have?

No. It adds its own entry beside them and removes only its own. A settings file it cannot read is left untouched.

What do I lose if I turn client hooks off?

Answering permission requests on the island, completion reminders from the clients that only report them through a hook, Claude Code's waiting-for-approval state and Pi's running status. Usage, quota and sessions are unaffected.

Does a hook send my code or prompts anywhere?

No. What a hook carries is read on your Mac to draw the request or record the finished turn, and the answer goes straight back to the client that asked. Nothing leaves the machine.

Agent HUD · Guides

What Agent HUD adds to your AI tools' settings

Most of what Agent HUD shows it reads from records your clients already keep. A few things are only known at the moment they happen, and for those the client has to call out.

Why a hook at all

Two things never reach a record in time: that a client is about to ask whether a tool may run, and, for some clients, that a turn has just finished. A client can run a command it was told about in its own settings when either happens. That command is a hook, and Agent HUD is the command.

Agent HUD adds its handlers by itself each time it starts, only for the clients installed on this Mac. Every other hook in those files is left as it was, and a settings file it cannot read is not rewritten.

What is added, client by client

Client	What its hook is for
Claude Code	Answering permission requests on the island; saying a session is waiting for approval
Qoder, Qoder CN, QoderWork	Answering permission requests
Codex Desktop / CLI	Answering permission requests
CodeBuddy	Answering permission requests; reporting finished turns
WorkBuddy, ZCode	Answering permission requests
Qwen Code	Answering permission requests; reporting finished turns
Antigravity, Cursor, GitHub Copilot CLI	Reporting finished turns
Pi	An extension rather than a hook: reporting running and finished turns

The steps a client asks of you

Codex runs a new or changed hook only after you review and trust it in /hooks. Agent HUD never marks it trusted for you, so until you do, Codex asks in its own window as it always has.

ZCode runs no hooks at all until its hooks switch is on. Agent HUD turns it on when it has never been set, and leaves it off if you turned it off yourself.

A request nobody answers

A permission request waits on the island for ten minutes — Settings → General → Wait for an answer changes that — and then goes back to the client, which asks in its own window. Nothing is answered for you.

Quitting Agent HUD hands every waiting request back at once, and a client that asks while Agent HUD is not running goes straight to its own prompt.

Turning them off

Settings → General → Client hooks. Before it switches off it names what stops working, and when you confirm, Agent HUD takes its handlers out of every client's settings at once and does not add them back when it starts.

Permission requests are no longer answered on the island; each client asks in its own window.
Antigravity, Cursor, GitHub Copilot CLI, CodeBuddy and Qwen Code no longer report finished turns, so their completion reminders stop.
Claude Code sessions no longer show that they are waiting for approval.
Pi shows no running status and no completions.
Usage, quota, token counts and session history stay exactly as they were.

Before you delete the app

Switch Client hooks off first. Deleting the app alone leaves its handlers in the clients' settings, pointing at a program that is no longer there.

A handler added by another copy of Agent HUD — Agent HUD Open beside Agent HUD, say — belongs to that copy, and only that copy takes it out.

Common questions

Do I have to set up any hooks myself?: No. Agent HUD adds them when it starts. The one step left to you is Codex's: it runs a new hook only after you trust it in /hooks.
Will Agent HUD change the hooks I already have?: No. It adds its own entry beside them and removes only its own. A settings file it cannot read is left untouched.
What do I lose if I turn client hooks off?: Answering permission requests on the island, completion reminders from the clients that only report them through a hook, Claude Code's waiting-for-approval state and Pi's running status. Usage, quota and sessions are unaffected.
Does a hook send my code or prompts anywhere?: No. What a hook carries is read on your Mac to draw the request or record the finished turn, and the answer goes straight back to the client that asked. Nothing leaves the machine.

Guides

Free on Mac

Agent activity and turn progress
Quota, resets and token usage
Turn completion, quota warnings and reset reminders

Get for free

Last updated: 2026-09-22 · The behaviour described here is documented in full, with the code it comes from, in Agent HUD Open. github.com/jazzenchen/agent-hud-open