agentd

agentd is a Windows-first local notification agent for terminals, scripts, and local automation tools. It runs as a CLI plus a lightweight background daemon and is published primarily as the npm package agentdc.

The installed command stays:

agentd

What agentd does

agentd gives local tools and scripts a simple way to trigger desktop notifications on Windows without forcing every caller to implement its own notification lifecycle.

It is designed for:

• CLI tools that need desktop notifications after long-running work
• local coding agents and automation scripts
• developer workflows that need a background notification daemon
• Windows users who want a simple notify command

Core features

• Global CLI command: agentd
• Background daemon with local-only HTTP API
• Fast 202 Accepted event handling
• Automatic daemon startup on first notify
• Windows logon autostart via agentd install
• npm-first distribution through agentdc
• Optional GitHub Release binaries for non-npm installation

Install agentd

Install from npm

agentd is primarily distributed through npm under the package name agentdc.

Requirements:

• Windows
• Node.js 22 or newer
• npm

Install:

npm install -g agentdc

Enable daemon autostart for your Windows user:

agentd install

Verify the installation:

agentd daemon status
agentd notify "agentd is installed"

Install from GitHub Releases

If you prefer binaries, GitHub Releases also provide:

• agentd.exe
• agentd-setup-x64.exe
• agentd-release.zip

Quick examples

Send a simple notification:

agentd notify "Build finished"

Send a titled notification:

agentd notify "Tests passed" "All test suites finished successfully"

Start the daemon manually:

agentd daemon start

Stop the daemon:

agentd daemon stop

Remove the Windows autostart task:

agentd uninstall

CLI reference

agentd notify "text"
agentd notify "title" "text"
agentd daemon run
agentd daemon start
agentd daemon stop
agentd daemon status
agentd install
agentd uninstall

How agentd works

agentd has two roles:

1. A CLI that users and scripts invoke
2. A local daemon that listens for events on 127.0.0.1

The CLI ensures the daemon is running, posts an event, and returns. The daemon validates the event, responds quickly, and then dispatches the notification asynchronously.

Current HTTP endpoints:

• GET /health
• POST /event
• POST /shutdown

The daemon is localhost-only by default.

Configuration

Environment variables:

| Variable | Default | Description | | --- | --- | --- | | AGENTD_HOST | 127.0.0.1 | Bind host | | AGENTD_PORT | 1738 | Bind port | | AGENTD_STARTUP_TIMEOUT_MS | 5000 | CLI wait time for daemon startup | | AGENTD_REQUEST_BODY_LIMIT | 16kb | Maximum JSON body size | | AGENTD_REQUEST_TIMEOUT_MS | 10000 | HTTP request timeout | | AGENTD_KEEP_ALIVE_TIMEOUT_MS | 5000 | Keep-alive timeout |

Repository structure

• cli/ contains the user-facing command entrypoint
• daemon/ contains the HTTP server, runtime, handlers, and daemon lifecycle
• shared/ contains shared contracts and types
• scripts/ contains build, packaging, and release scripts
• docs/ contains operational and release documentation
• installer/ contains the optional Windows installer definition

Development

Install dependencies and run verification:

npm install
npm run build
npm run smoke

Create the publishable npm tarball:

npm run pack:npm

Optional Windows binary artifacts:

npm run build:exe
npm run release:stage

Releases and npm publishing

Releases are tag-driven.

Pushing a tag like v0.1.1 triggers GitHub Actions to:

1. publish the npm package agentdc
2. build the optional Windows binaries
3. create the GitHub Release

See docs/RELEASING.md for the exact release flow and required secrets.

Why the npm package is called agentdc

The package name on npm is agentdc because npm package names must be globally unique. The installed command remains agentd, so the user-facing CLI stays short and consistent.

Troubleshooting

If agentd is not found after installation:

1. Open a new terminal.
2. Verify your global npm bin directory is on PATH.

If notifications do not appear:

1. Run agentd daemon status
2. Run agentd notify "test"
3. Check Windows notification permissions

If you previously used the .exe installer version:

1. Remove the scheduled task with agentd uninstall or schtasks /Delete /F /TN agentd
2. Remove old installer files if they still exist under C:\Program Files\agentd

Documentation

• Operations guide
• Release guide
• Contributing guide
• Security policy

License

MIT. See LICENSE.