Question 1

What is syncfu?

Accepted Answer

syncfu is an open-source universal notification overlay for AI agents. It runs as a lightweight system tray daemon (built with Tauri/Rust) and shows rich desktop overlay notifications when AI agents like Claude Code, Cursor, or custom agents need to communicate with the developer. It features action buttons, progress bars, custom themes, and a --wait flag for human-in-the-loop decision gates.

Question 2

How do I get notifications from Claude Code?

Accepted Answer

Install syncfu with one command (curl -fsSL https://syncfu.dev/install | sh), then use Claude Code hooks or the syncfu CLI to send notifications. When Claude finishes a task, syncfu shows a rich desktop overlay with the result. You can also use the --wait flag to block until you click an action button, making it perfect for approval gates.

Question 3

How does the --wait flag work?

Accepted Answer

The --wait flag makes the syncfu CLI block until the user interacts with the notification. It opens an SSE stream to the local server. When the user clicks an action button, the action ID is printed to stdout with exit code 0. If dismissed, exit code 1. If timed out, exit code 2. This makes it perfect for scripting human-in-the-loop decision gates in CI/CD pipelines and AI agent workflows.

Question 4

Is syncfu free and open source?

Accepted Answer

Yes. syncfu is fully open source under the MIT license. The core notification overlay, CLI, HTTP API, and all features are free. No account required, no telemetry, fully local. Built with Tauri v2 and Rust for a lightweight ~9MB binary.

Question 5

What platforms does syncfu support?

Accepted Answer

syncfu supports macOS, Windows, and Linux. On macOS it uses NSPanel for a native non-activating overlay that joins all Spaces. On Windows it uses always-on-top WebviewWindow. On Linux it supports X11 with Wayland support planned.

Question 6

How is syncfu different from ntfy or Pushover?

Accepted Answer

Unlike ntfy and Pushover which are phone-focused push notification tools, syncfu is a native desktop overlay designed for developers at their computer. It features rich notifications with action buttons, progress bars, 27 style properties, a --wait flag for decision gates, and is agent-agnostic — working with Claude Code, Cursor, Copilot, and any AI agent or script. It's also fully open source and runs entirely locally.

Feature	Details
Core overlay + system tray	Always-on-top overlay window with slide-in/out animations. System tray with pause, clear all, and quit.
NSPanel on macOS	Non-activating native panel that joins all Spaces. Does not steal focus from your current application.
Liquid Glass design	9-layer reflex shadows, backdrop blur, grain texture, priority-tinted icons, SF Mono typography.
HTTP REST API (port 9868)	Full CRUD: send, update, dismiss, wait (SSE), health check, list active notifications.
CLI with --wait flag	`syncfu send/update/dismiss/list/health`.`--wait` blocks until user responds via SSE.
Action buttons + webhooks	Up to 3 buttons per notification. Per-button icon, color, and border customization. Webhook callback on click.
Live progress bars	Bar and ring styles. Update in-place via POST. Custom label text. Animated transitions.
27 style properties	Per-notification color, font size, border radius, icon styling, button styling, progress colors.
Lucide icons (1400+)	Any Lucide icon name as a string. Priority-tinted icon backgrounds.
Google Fonts	Load any Google Font on demand per notification.
Light/dark theme	Auto-follows system theme. Per-notification override with `theme` field.
Auto-dismiss with countdown	Visual countdown bar. Pauses on hover. Priority-based default timeouts.
Critical pulsing glow	Siri-style pulsing border animation for critical-priority notifications.
Multi-monitor support	Notifications follow your mouse cursor across displays.
Click-through overlay	Only notification cards are interactive. Clicks pass through to apps underneath.
One-command install	`curl \| sh` for macOS/Linux, PowerShell for Windows. SHA-256 checksum verification.
181 tests	72 frontend + 70 Rust server + 29 CLI unit + 10 CLI integration tests.

Feature	Status	Details
Markdown body rendering	~ Planned	Render markdown in notification body text — bold, italic, code, links, lists.
Sound playback	~ Planned	Play a sound when notification arrives. Sound field is accepted today but playback is not yet implemented.
Notification grouping UI	~ Planned	Group related notifications visually. The `group` field is tracked today; grouped rendering is planned.
Persistent history (SQLite)	~ Planned	Store notification history in a local SQLite database. Search, filter, and replay past notifications.
Linux Wayland support	~ Planned	Always-on-top overlay on Wayland compositors (currently X11 only on Linux).
Configuration file	~ Planned	Optional config file for default styles, port, and behavior. Everything remains API-driven per notification.
Encrypted transport (mTLS / API keys)	~ Planned	Secure the HTTP API for remote access with mutual TLS or API key authentication.
Remote notifications (tunnel / cloud relay)	~ Planned	Built-in tunnel or cloud relay so CI/CD and remote servers can reach syncfu without manual tunnel setup.

Component	Stack
Backend	Rust — axum HTTP server, SSE streams, tokio broadcast channels
Frontend	React — Zustand store, CSS animations, Lucide icons, Google Fonts
Overlay	NSPanel (macOS) — non-activating, follows mouse cursor across monitors
CLI	Rust — fire-and-forget by default, --wait opens SSE stream
System tray	Tauri tray API — pause, clear, quit with confirmation

Roadmap

Shipped

Planned

Architecture

Contributing

Try syncfu today