What is syncfu?

syncfu is a free, open-source desktop notification overlay that lets AI agents, scripts, and automation tools push rich notifications to your screen.

Definition

syncfu is a standalone notification system that runs as a system tray application on macOS, Windows, and Linux. It exposes an HTTP API on port 9868 and a CLI (syncfu send) that any process can use to display native overlay notifications on the developer's screen.

Unlike operating system notifications that disappear in a few seconds and carry no interactive elements, syncfu notifications persist on screen with up to three action buttons, live progress bars, custom icons, and 27 configurable style properties. The --wait flag blocks the calling process until the user responds, enabling human-in-the-loop workflows for AI agents.

How it works

Your Script ──HTTP POST──▸ syncfu server ──▸ Desktop Overlay
CLI         ──HTTP POST──▸ syncfu server ──▸ Desktop Overlay
CLI (--wait) ────────────▸ SSE stream ◂──── wait for action/dismiss

syncfu runs two components: an invisible overlay window (always on top, click-through) and a system tray icon. When a notification arrives via HTTP, it slides in from the top-right corner with action buttons and an auto-dismiss countdown. Clicks pass through to your apps underneath — only the notification cards are interactive.

Key features

  • Always-on-top overlay. NSPanel on macOS — non-activating, click-through, joins all Spaces, follows your mouse cursor across monitors.
  • Action buttons with callbacks. Up to 3 buttons per notification. Buttons return exit codes to the calling script and optionally POST to a webhook URL.
  • --wait flag. The CLI blocks until the user clicks an action button or dismisses the notification. stdout prints the action ID. Exit codes: 0 = action, 1 = dismissed, 2 = timeout.
  • Live progress bars. Update notifications in place with a progress value (0–1.0). Bar and ring styles available.
  • 27 style properties. Override colors, fonts, border radii, and more per notification. Dark and light themes auto-follow the system.
  • 1400+ Lucide icons. Any Lucide icon name can be used per notification. Google Fonts loaded on demand.
  • Agent-agnostic. Works with Claude Code, Cursor, Copilot, CrewAI, LangGraph, custom Python scripts, shell scripts, CI pipelines, and anything that can make an HTTP request.

Quick start

# Install (macOS / Linux)
curl -fsSL https://raw.githubusercontent.com/Zackriya-Solutions/syncfu/main/install.sh | sh

# Send your first notification
syncfu send "Hello from syncfu!"

# With title, priority, and icon
syncfu send -t "Build Complete" -p high -i circle-check "All 142 tests passing"

# Block until user responds
syncfu send -t "Deploy?" -a "yes:Yes" -a "no:No:danger" --wait "Ship to production?"

Technology

Built with Tauri v2 (Rust) for the backend and system integration, React (TypeScript) with Zustand for the overlay UI, and axum for the HTTP server. The binary is 9 MB — compared to 300+ MB for an equivalent Electron app. Ships on macOS, Windows, and Linux.

Who it is for

  • Developers running AI coding agents (Claude Code, Cursor, Copilot) who need to know when tasks complete
  • DevOps engineers who want CI/CD build results on their screen with action buttons
  • ML engineers tracking training progress across long runs
  • Anyone running background tasks who needs push-based notifications that actually reach them

Frequently asked questions

What is syncfu?

syncfu is an open-source desktop notification overlay for developers. It runs as a lightweight system tray daemon (9 MB, built with Tauri and Rust) and shows rich desktop overlay notifications when AI agents, scripts, CI pipelines, or any HTTP client sends a request to its local API on port 9868. Notifications appear as native floating panels with action buttons, progress bars, and custom styling.

How do AI agents communicate with humans through syncfu?

Any AI agent that can run a shell command or make an HTTP request can send notifications through syncfu. The agent calls syncfu send with a message, or POSTs JSON to http://localhost:9868/notify. The notification appears as a persistent desktop overlay. With the --wait flag, the agent can pause and wait for the human to click an action button before continuing.

What is the best desktop notification tool for developers?

For developers who need rich, interactive notifications with action buttons and progress bars, syncfu is purpose-built. Unlike OS notifications that disappear in seconds, syncfu overlays persist on screen, support custom styling, and can block scripts until the user responds. For mobile push notifications, ntfy or Pushover are better choices. Many developers use both.

Is syncfu free?

Yes. syncfu is free, open-source software under the MIT license. There is no account, no cloud dependency, and no telemetry. It runs entirely on your local machine. The full source code is available on GitHub.

How to send notifications from a bash script?

Install syncfu with one command (curl -fsSL install script), then run: syncfu send -t 'Title' 'Body text'. For action buttons, add --action 'id:Label:style'. For blocking until the user responds, add --wait. You can also POST JSON to http://localhost:9868/notify using curl.

Try syncfu now

One install command, one notification on your screen. Free, open source, no account needed.

Get started →