AgentNotify

Development status: Pre-release v0.0.4-alpha.2 — AgentNotify is under active development and has not reached the mature v1.0.0 release. Builds are for testing and evaluation; expect incomplete features, breaking changes, and unsigned binaries.

The local human-attention and notification broker for coding agents.
Documentation · GitHub · Installation · API · ARC · Contributing

AgentNotify is a local human-attention broker for autonomous coding agents. Agents send a small authenticated request; AgentNotify displays a dedicated non-activating WPF toast, preserves the event in local history, and makes unresolved requests visible from the system tray.

It is designed for people running several agents across terminals, repositories, windows, and virtual desktops who need a reliable answer to: “Which agents are waiting for me?”

Platform support

The graphical application is Windows-only today. macOS and Linux run the same broker, CLI and API, but headlessly — there is no tray icon, no notification center and no Settings window on those platforms, so everything configured through the Settings UI on Windows (outbound channels, custom types, sounds, toast placement) has to be edited in config.json or left at its defaults.

	Windows 11 x64	macOS	Linux
Installer	AgentNotifySetup.exe	install.sh archive	install.sh archive
CLI (agentnotify)	yes	yes	yes
Loopback REST API	yes	yes	yes
SQLite history, dedup keys, retention	yes	yes	yes
Outbound channels (19 adapters)	yes	yes, config file only	yes, config file only
Desktop notification	custom AgentNotify toast	Notification Center via terminal-notifier/osascript	notify-send
Tray icon and notification center	yes	no	no
Settings window	yes	no	no
Verified on real hardware	yes	Intel yes (2026-09-04), Apple Silicon no	yes

Native macOS and Linux clients are a roadmap goal, not a shipped feature; the portable broker exists so that they can be built on top of it. See Cross-platform plan.

What you get

Everywhere:

• A loopback-only, bearer-authenticated REST API at 127.0.0.1:47821.
• A self-contained agentnotify CLI, including an agentnotify.exe for Windows and WSL agents.
• SQLite history, deduplication keys, configurable retention, and local logs.
• Nineteen opt-in outbound channel adapters with encrypted credentials, including AgentNotify Relay — a self-hostable transport from your computers to your phone.
• Single-instance behavior and a desktop notification on each supported platform.

On Windows, additionally:

• Custom Windows 11 toast windows owned by AgentNotify, not browser notifications.
• Sticky input_required, permission_required, and blocked toasts that stay until dismissed or resolved.
• Auto-expiring informational, warning, success, and completion notifications.
• Centralized multi-toast stacking on the monitor where the user is working.
• A compact notification center with “Needs attention” and recent history.
• A system tray icon that keeps the broker alive when windows close.
• A Settings window for channels, custom types, sounds, toast placement, and pause/DND.
• Per-user startup registration.
• Tray actions to copy or save the distributable SKILL.md.
• One self-contained installer executable with an offline getting-started page.

Install

Windows

The distributable is AgentNotifySetup.exe. Copy that one file to a Windows 11 machine and run it; no separate .NET runtime is required.

Setup installs per user by default under %LOCALAPPDATA%\Programs\AgentNotify, then:

1. installs AgentNotify.Tray.exe and agentnotify.exe;
2. adds the CLI directory to the user PATH;
3. creates Start menu shortcuts;
4. registers AgentNotify to start at sign-in, unless unchecked;
5. registers a Windows “Installed apps” uninstall entry;
6. starts the tray application; and
7. opens the offline getting-started HTML page in the default browser when setup closes.

The installer displays the MIT License and the explicit “as is, no warranty” notice before installation. This build contains publisher metadata for Kabani Tech Private Limited, but it is not Authenticode-signed. Windows may therefore show an unknown-publisher/SmartScreen prompt until a code-signing certificate is used.

After installation, open a new PowerShell, Command Prompt, or WSL shell so the updated Windows user PATH is visible.

macOS and Linux

curl -fsSL https://raw.githubusercontent.com/Akash97p/agent-notify/main/scripts/install.sh | sh

This installs the agentnotify CLI and the agentnotifyd broker into ~/.local/bin after verifying the published SHA-256 checksum. Start the broker with agentnotifyd, then use the same CLI and the same /v1 API as on Windows.

There is no graphical application on macOS or Linux. No tray icon, no notification center and no Settings window: agentnotifyd is a headless daemon you run under systemd or launchd, and every setting is edited in config.json by hand. Desktop notifications go to notify-send on Linux, Notification Center on macOS, or standard output when no desktop session is available.

The macOS build ran on real Intel hardware for the first time on 2026-09-04, and the osascript notification backend was seen displaying a banner. The binaries are adhoc-signed rather than notarized, so a fresh download is quarantined until you run xattr -dr com.apple.quarantine <dir> — no sudo needed. Apple Silicon has still never executed one.

See Installing on macOS and Linux.

Send your first notification

agentnotify.exe send `
  --agent codex `
  --project AgentNotify `
  --type input_required `
  --priority high `
  --key AgentNotify-decision `
  --title "Need your decision" `
  --message "Should I use option A or option B?"

From Bash or WSL:

agentnotify.exe send \
  --agent codex \
  --project AgentNotify \
  --type input_required \
  --priority high \
  --key AgentNotify-decision \
  --title "Need your decision" \
  --message "Should I use option A or option B?"

The CLI prints the created notification, including its id. Clear a resolved request with:

agentnotify.exe resolve NOTIFICATION_ID

Useful commands:

agentnotify.exe health
agentnotify.exe list --unresolved
agentnotify.exe get NOTIFICATION_ID
agentnotify.exe dismiss NOTIFICATION_ID
agentnotify.exe "Build complete" "All tests passed" --type completed

Both underscore and hyphen spellings are accepted by the CLI, such as input_required and input-required.

User-defined types can be created under Tray → Settings… → Custom types. Each definition has a stable ID, display name, accent color, default priority, lifetime (0 is sticky), and enabled state. Agents can then pass the ID through --type, for example --type deployment_waiting. Deleting or disabling a definition never corrupts history: existing/new events keep the ID and use safe generic presentation defaults.

AgentNotify ships with four built-in tones — Chime, Ping, Alert, and Knock — that are embedded in the application and seeded into the managed sound directory on first run, so sound works offline with no setup. Under Settings… → Sounds & channels, users can pick a built-in tone or import their own global WAV/MP3 tone, assign per-type overrides, preview sounds, choose volume, and control critical playback during Do Not Disturb. Imported files are validated, content-addressed, and copied into AgentNotify’s managed per-user sound directory; configuration never depends on the original upload path.

Give the skill to a coding agent

Right-click the tray icon and choose Install agent skill…. The Install tab lists every agent AgentNotify knows a folder for, shows where the file will go, and says whether it is already there. Anything else installs to a folder you pick.

The same install from the CLI—offline, with no npm or Python dependency:

agentnotify install-skill codex
agentnotify install-skill claude
agentnotify install-skill opencode

The default personal locations are:

Codex:       ~/.agents/skills/agentnotify/SKILL.md
Claude Code: ~/.claude/skills/agentnotify/SKILL.md
OpenCode:    ~/.config/opencode/skill/agentnotify/SKILL.md

Use --scope project, --dry-run, or --path DIRECTORY when needed. Changed existing files are protected unless --force is explicit. The tray's Copy/Download actions remain available.

The source skill is at distribution/agentnotify/SKILL.md. It tells an agent when to notify, how to avoid notification spam, how to use stable deduplication keys, and how to resolve an attention request.

See Agent setup and skills for Agent Skills-compatible tools and a portable instruction snippet for agents that use project rules or system prompts instead.

Attention Request Contract

AgentNotify defines ARC 0.1, an open transport-neutral contract for creating, updating, and resolving bounded requests for human attention. ARC producers post request.created, request.updated, and request.resolved events to the authenticated loopback /v1/events endpoint. Sender identity, session and project context, immutable event identity, unresolved conditions, and deduplication survive projection into local history.

See the Attention Request Contract for the lifecycle, field rules, published JSON Schema, security boundary, and future stdout/ACP/A2A adapter direction.

Notification model

Types:

Type	Default toast behavior	Intended use
input_required	Sticky	A user decision or answer blocks progress
permission_required	Sticky	Explicit authorization is required
blocked	Sticky	A prerequisite or external dependency prevents progress
error	15 seconds	A significant operation failed
warning	12 seconds	Attention is advisable but work can continue
info	7 seconds	A meaningful non-actionable milestone
success	5 seconds	An important operation succeeded
completed	5 seconds	The requested work finished

Toast lifetime and “needs attention” are separate ideas. input_required, permission_required, blocked, and error are all attention types, so an active one is listed under Needs attention in the notification center. Only the first three have a sticky toast; an error toast auto-dismisses after its lifetime while the entry stays active in the center. Every lifetime above is the default and is configurable per type.

Priorities are low, normal, high, and critical. Status values are active, dismissed, and resolved.

An optional key identifies one logical unresolved condition. A new active notification with the same key updates the existing row and toast instead of producing duplicates. Keyed creation is serialized inside the broker so concurrent agents cannot create duplicate active rows.

Tray behavior

The tray menu provides:

• Notification Center
• Settings…
• Getting started
• Copy agent SKILL.md
• Download agent SKILL.md…
• Pause notifications
• Start with Windows
• Open log folder
• Exit

Closing the notification center only hides it. AgentNotify exits only from the tray menu. A second launch signals the existing process to show the center instead of opening another API listener.

Architecture

Coding agent / CLI
        |
        | HTTP + local bearer token
        v
ASP.NET Core Minimal API (127.0.0.1 only)
        |
        v
NotificationService ---- SQLite repository
        |
        +---- ToastStackManager ---- WPF toast windows
        |
        +---- Notification Center
        |
        +---- WinForms NotifyIcon tray

Project layout:

src/AgentNotify.Protocol    native API contracts and the ARC model/schema
src/AgentNotify.Core        cross-platform domain rules, config, persistence, logging
src/AgentNotify.Api         authenticated loopback Minimal API
src/AgentNotify.App         WPF tray app, toasts, center, startup/single instance
src/AgentNotify.Cli         self-contained command-line client
src/AgentNotify.Desktop     portable macOS/Linux notification backends
src/AgentNotify.Host        cross-platform headless broker
src/AgentNotify.Setup       self-contained per-user WPF installer
tests/AgentNotify.Tests     xUnit domain, persistence, API, auth, and CLI tests
distribution/agentnotify   validated agent skill
assets                     offline getting-started HTML template
docs                       detailed reference and verification notes

See docs/ARCHITECTURE.md for lifecycle and trust-boundary details.

Local data and configuration

Runtime state stays under %LOCALAPPDATA%\AgentNotify:

config.json                 port, random bearer token, UI/runtime options
agentnotify.db              SQLite notification history
logs/agentnotify-YYYYMMDD.log
sounds/                     built-in tones plus user-imported WAV/MP3 files
resources/SKILL.md
resources/GettingStarted.html

Selected config.json defaults:

JSON key	Default
port	47821
toastLocation	BottomRight
maxVisibleToasts	5
historyRetentionDays	30
pauseNotifications	false
soundsEnabled	false
soundVolume	0.8
maxRequestBodyBytes	65536
rateLimitPerSecond	30

authToken is generated with 256 bits of randomness on first launch. The CLI reads it automatically. AGENTNOTIFY_PORT and AGENTNOTIFY_TOKEN can override discovery for debugging, but agents should not print or transmit the token.

The SQLite database also contains versioned delivery tables for provider profiles, routing rules, durable outbox items, and bounded attempt history. Provider credentials and sensitive destinations are serialized only into versioned Windows DPAPI current-user envelopes; profile summaries expose secret field names but never values or ciphertext. The Channels tab can create, test, enable, and delete hardened generic webhook, authenticated TLS SMTP, Telegram Bot, Discord, Slack, Teams Workflows, Zoho Cliq, Google Chat, Mattermost, Matrix, ntfy, Gotify, Pushover, Pushbullet, paid Twilio SMS, direct WhatsApp Cloud API, Twilio WhatsApp, MQTT 5, or AgentNotify Relay profiles and filtered routes, and shows redacted queue diagnostics. Outbound delivery remains disabled until both a provider and matching route are explicitly enabled. See Outbound channels.

Connect to AgentNotify Relay

In Tray icon → Settings → Channels, create an AgentNotify Relay provider:

1. Enter the self-hosted Relay base URL and press Connect.
2. Confirm the short code on the approval page opened in your browser.
3. When Settings shows the verified connection, press Save provider.

Connecting pairs this computer as a sender; it does not create a recipient. Pair at least one phone before using Send test. If no active phone is present, AgentNotify reports that state locally and does not send a placeholder envelope that Relay would reject.

The one-time installation credential is never displayed. It moves directly from the pairing poll into AgentNotify's protected provider secret store when you save. Headless Windows, macOS, and Linux hosts can use agentnotify relay pair --url https://relay.example.com; run agentnotify relay status to verify saved connections. Relay Go remains unavailable, and the self-hosted opaque envelope transport remains experimental rather than a claim of end-to-end encryption.

Uninstall removes application binaries, shortcuts, startup registration, and the CLI PATH entry. It intentionally preserves %LOCALAPPDATA%\AgentNotify history/config so an upgrade or reinstall does not destroy user data.

Security and privacy

• Kestrel binds only to 127.0.0.1, never 0.0.0.0.
• Every /v1/* route requires the per-user bearer token.
• Token comparison uses SHA-256 and fixed-time byte comparison.
• Request bodies, fields, metadata size, and create rate are bounded.
• Notification content, database rows, and logs remain local; there is no telemetry or cloud service.
• API-to-UI callbacks are isolated so a rendering failure cannot make a persisted API request fail.
• The unauthenticated /health endpoint exposes only {"status":"ok"}.

Read SECURITY.md before proposing network transports or external delivery channels.

Build it yourself

Prerequisites

• Windows 11 x64.
• Windows .NET SDK 10.0.302 or a compatible .NET 10 SDK with the Windows Desktop workload.
• Git.
• WSL is recommended for the supplied Bash scripts, but it is not required for ordinary dotnet builds.

Clone the repository when it is published:

git clone https://github.com/Akash97p/agent-notify.git
cd agent-notify

Build and test directly from PowerShell:

dotnet restore AgentNotify.slnx
dotnet build AgentNotify.slnx --configuration Release
dotnet test tests/AgentNotify.Tests/AgentNotify.Tests.csproj --configuration Release

WPF must be built with a Windows .NET SDK, not Linux dotnet. From WSL, point the scripts at the Windows dotnet.exe if it is not installed at the repository default:

cd /path/to/agent-notify
./scripts/build.sh
./scripts/test.sh

Override the SDK path when necessary:

AGENTNOTIFY_DOTNET_EXE=/path/to/windows/dotnet.exe ./scripts/build.sh

The current v0.0.3-alpha.1 build completes with zero warnings. The test suite has 720 passing tests.

Build the single-file installer

./scripts/package.sh

This publishes self-contained single-file Windows binaries for the tray app and CLI, embeds both in a self-contained WPF setup executable, validates the skill, and creates:

artifacts/AgentNotifySetup.exe

The artifact is intentionally ignored by Git. See docs/INSTALLATION.md for packaging internals, signing guidance, and release checks.

The current v0.0.3-alpha.1 GitHub prerelease includes the installer, checksum, and distributable skill. Future exact v-prefixed tags publish through the release workflow; hyphenated prerelease tags are marked as prereleases automatically. Building locally does not require GitHub access. See Releases and GitHub Pages.

API

The versioned API is documented in docs/API.md. The primary create route is:

POST http://127.0.0.1:47821/v1/notifications
Authorization: Bearer LOCAL_TOKEN
Content-Type: application/json

{
  "agent": "codex",
  "agentInstance": "agent-3",
  "project": "payments",
  "type": "input_required",
  "priority": "high",
  "key": "payments-schema-decision",
  "title": "Need schema decision",
  "message": "Choose normalized or denormalized storage.",
  "cwd": "D:\\dev\\payments"
}

Current limitations

• The Windows tray application, notification center, Settings UI, and installer are x64 Windows only.
• macOS and Linux run the broker headlessly through agentnotifyd; there is no tray or Settings UI there yet.
• The macOS Intel build and its osascript notification backend have now run on real hardware; Apple Silicon, terminal-notifier, the launchd unit and the Relay channel on macOS have not. Linux's notify-send backend has never been seen displaying anything. See docs/VERIFICATION.md.
• The installer is not yet Authenticode-signed.
• “Open Agent” cannot reliably focus a specific Windows Terminal tab or cross virtual desktops yet.
• Nineteen outbound adapters are configurable: generic HTTPS webhook, authenticated TLS SMTP email, Telegram Bot, Discord, Slack, Teams Workflows, Zoho Cliq, Google Chat, Mattermost, unencrypted Matrix rooms, ntfy, Gotify, Pushover, Pushbullet, paid Twilio SMS, Meta WhatsApp Cloud templates, Twilio WhatsApp Content templates, MQTT 5 over TLS/mTLS, and the experimental self-hosted AgentNotify Relay transport.
• Real-provider interoperability is not claimed by automated tests. Configure and test each provider with your own account, destination, consent, quotas, and compliance controls.
• AWS SNS, Signal, provider email APIs, additional SMS/mobile-push services, quiet hours/escalation, agent callbacks, and SDK/MCP work remain backlog items; AWS SNS is currently paused and has no implementation in this branch.

Roadmap

The transport design keeps the local broker as the source of truth. Completed delivery adapters are listed in docs/CHANNELS.md; remaining directions include:

• Provider email APIs where SMTP is unavailable or insufficient.
• Delivery-status webhooks and durable spend budgets for paid SMS/WhatsApp transports.
• Additional SMS and mobile push through explicitly configured providers.
• Quiet hours, schedules, snooze, escalation, grouping, and per-project rules.
• Response buttons and acknowledgements back to the waiting agent.
• Agent heartbeat/status, richer SDKs, and an optional MCP server.
• Safer terminal/tab activation and virtual-desktop awareness.
• ARM64 packages, signed releases, automatic updates, and migration tooling.
• Native macOS menu-bar and Linux tray clients on top of the portable broker that now exists.

External channels are disabled by default and must add provider-specific secret storage, consent, redaction, retry, cost-control, and rate-limit policies. See docs/ROADMAP.md and docs/FEATURE_BACKLOG.md. No new outbound adapter branch is active; current work is cross-platform support and documentation.

Contributing and license

Read CONTRIBUTING.md before submitting changes. AgentNotify is available under the permissive MIT License. Bundled dependency licenses and attribution are recorded in THIRD_PARTY_NOTICES.md.

Publisher: Kabani Tech Private Limited Author: Akash P — github.com/Akash97p

The software is provided “as is”, without warranty of any kind, as stated in the license.