Quick Start

1. Install syncfu

The installer places the syncfu binary in your PATH and starts the background daemon. Pick the command for your platform:

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/Zackriya-Solutions/syncfu/main/install.sh | sh

Windows (PowerShell)

irm https://raw.githubusercontent.com/Zackriya-Solutions/syncfu/main/install.ps1 | iex

After installation, verify the daemon is running with syncfu status. You should see daemon: running in the output.

2. Send your first notification

Open a new terminal and run this command. A native desktop notification will appear within a second:

syncfu send -t "Hello" "It works!"

The -t flag sets the title. The positional argument is the notification body. That's all you need for a basic notification.

3. Claude Code integration

Claude Code supports lifecycle hooks that fire shell commands at key points during a session. Add a PostToolUse hook to your ~/.claude/settings.json to get notified after every tool call:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "syncfu send -t \"Claude Code\" \"Tool use complete\""
          }
        ]
      }
    ]
  }
}

Set matcher to an empty string to match all tools, or supply a tool name like "Bash" to notify only for shell commands. Restart Claude Code after saving the file.

4. Cursor integration

Cursor exposes terminal access inside the AI context. The simplest approach is to append a syncfu send call to any long-running command you ask Cursor to run:

npm run build && syncfu send -t "Cursor" "Build finished"

For persistent notifications across all Cursor sessions, add the syncfu call to your shell PROMPT_COMMAND (bash) or precmd hook (zsh) so it fires whenever a command completes. This works for any agent that drives a terminal — Cursor, GitHub Copilot Workspace, Codeium, and others.

5. HTTP API

syncfu runs a local HTTP server on port 9868. Any process that can make an HTTP request can trigger a notification — useful for CI scripts, Python agents, or server-side code running on localhost:

curl -s -X POST http://localhost:9868/notify \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Deploy complete",
    "body": "Production updated to v1.4.2",
    "actions": [
      { "label": "View logs", "url": "https://your-app.com/logs" }
    ]
  }'

The actions array is optional. Each action renders as a clickable button on the notification. Buttons can open URLs or return exit codes to a waiting caller (see the --wait section below).

6. Decision gates with --wait

Pass --wait to block your script until the user responds. The exit code tells your script which button was pressed: 0 for the primary action, 1 for dismiss/cancel. This lets you build human-in-the-loop approval steps inside automation:

#!/usr/bin/env bash
set -euo pipefail

syncfu send --wait \
  -t "Ready to deploy?" \
  "Push v1.4.2 to production?" \
  --action "Deploy" \
  --action "Cancel"

# syncfu exits 0 if "Deploy" was clicked, 1 if "Cancel" or dismissed
if [ $? -eq 0 ]; then
  echo "Deploying..."
  ./scripts/deploy.sh production
else
  echo "Deploy cancelled."
  exit 0
fi

Tip: combine --wait with Claude Code's PreToolUse hook to require explicit approval before Claude runs destructive commands like rm or git reset.

What else can syncfu do?

The features below are all available today — see the GitHub repo for the full reference.

FAQ