Skip to the content

Get told when an agent is denied or asks

Follow each denial, approval ask and alert as it happens: in a terminal, as desktop notifications, or through your own Linux notifier.

Built, not yet claimed preview: this guide describes a package that has not passed its release gate.

Follow AgentGarm's notices as they happen: one line for each denial, approval ask and alert, in a terminal, as macOS notifications from the menu bar, as Windows tray balloons or through your own Linux notifier, with the details one click away in the dashboard.

1. Follow notices in a terminal

agentgarm notices follows agentgarmd from now on and prints one line per notice, the title and then the body; nothing from before it started arrives as news. When the connection drops it reconnects, waiting 1, 2, 5, 10 and then 30 seconds between tries, and resumes where it stopped. It runs until its output closes, so stop it with Ctrl-C. --json prints each notice as an object with kind, title and body, for a program of your own.

agentgarm notices
agentgarm notices --json

2. Read what each notice means

There are three kinds. A deny is titled “AgentGarm denied an action” and an ask “AgentGarm asks for your approval”; the body names the kind of action (a command, a file access, a network connection, a tool call, an MCP call or a model call), the agent and the rule that decided it, or “the default action” when no rule did. An ask waits for you in the agent's own prompt or, with a presence key enrolled, in agentgarm presence watch; on a root Linux install with no key enrolled, agentgarm presence watch --method polkit answers it with your polkit password instead (rated C, not presence).

An alert is titled with what happened: “A bypass attempt was detected”, “Enforcement is degraded”, “Sensitive data was found”, “Policies conflict”, “A task could not be attributed”, “A budget threshold was reached”, “An agent's configuration needs attention”, “A credential was refused” or “Tampering was blocked”; its body says to open the dashboard for details. An allow is never a notice, nor is a checkpoint, and in audit mode what the rules would deny or ask is let through, so it raises none.

A task being suspended, or the machine being locked down by a kill order, raises no notice of its own yet: you see it when a governed agent stops or will not start, and agentgarm status says why (Find out why your agent stopped).

A notice never contains the command, a path or any text the agent sent, because a notification centre keeps what it is shown.

See also

Approve risky actions with Touch ID

Enrol a Touch ID key on your Mac and approve each command your policy asks about with your fingerprint, for that one call only.

3. See notices in the macOS menu bar

AgentGarm's presence menu (agentgarm-presence menubar) follows the notices while it runs, starting the follower again 5 seconds after it ends. It lists the five newest under Recent, with the body as each item's tooltip, and posts each as a system notification when the menu runs from an app bundle; run as a bare executable, the Recent list is the only place they show. Its Open Dashboard item (⌘D) opens the dashboard, and Quit AgentGarm Presence Menu stops the follower with the menu.

AgentGarm's item in the macOS menu bar, its menu open: the key's state, Open Dashboard, the recent notices, Refresh and Quit

4. See notices in the Windows tray

The tray has not yet been built and run on a Windows 11 machine, so this is how it is designed to work. agentgarm-agent tray is to add an AgentGarm icon to the notification area, with Open dashboard and Quit, and show each notice as a balloon. Each balloon is to replace the one before it, so at most one would show every 6 seconds, and a backlog of more than three would become one “N new AgentGarm notices” balloon. To start it at logon, put a shortcut to agentgarm-agent tray in your Startup folder.

5. Send notices to your Linux desktop

Linux has no AgentGarm tray icon. Feed the notices to your own notifier instead, such as notify-send, from a terminal or a user service of your own: each line becomes one desktop notification.

agentgarm notices | while IFS= read -r line; do notify-send AgentGarm "$line"; done

6. Open the dashboard for the details

A notice is a pointer, and the details are in the dashboard: agentgarm ui --open asks the session for a fresh launch code and opens the dashboard in your browser, which is what the menu's and the tray's item does too. Its Overview shows the newest alerts, grouped where the same alert repeats, and, under “Denied or asked”, each refusal or question with its rule id and reason; the Alerts screen lists them all.

agentgarm ui --open
The dashboard's Overview: a status line, four tiles, then what was denied and the newest alerts beside the tasks running now and their assurance level

See also

Trace what one agent task did

Find an agent's task in the dashboard, read every decision its policy made with the rule behind it, and follow the run from first decision to last.