Bark Notify

Overview

Use this skill to send Bark notifications from an agent. The bundled script is scripts/bark-notify.py, resolved relative to this SKILL.md.

Safety

• Never print, commit, or quote BARK_KEY.
• Do not put Bark keys in repository files.
• Prefer local private config at ~/.config/bark-notify.env.
• Do not put a real key after --key in a shell command: it can be retained in shell history or exposed to local process inspection. Use the private config file or --key-stdin for setup.
• Use --agent <name> for agent-originated pushes so group/icon metadata can come from config.
• Only pass --server, --key, --group, or --icon when the user explicitly asks to override defaults.
• If command output could include sensitive config, summarize it instead of pasting raw output.

Send

Run the bundled script from this skill directory:

python3 scripts/bark-notify.py "Title" "Body"
python3 scripts/bark-notify.py Title Body words without quoting the body
python3 scripts/bark-notify.py --agent codex --level active "Build finished" "Codex completed the requested task"
python3 scripts/bark-notify.py --agent codex --level active "Milestone reached" "The first migration finished"

Use explicit overrides only when requested:

python3 scripts/bark-notify.py --agent codex --group Custom --icon "https://example.com/custom.png" "Title" "Body"

To send WorkBuddy notifications, add a workbuddy entry to the local agent configuration with group WorkBuddy and the server-hosted icon URL from the example configuration.

Decide Whether to Send

A progress-update instruction grants permission to send useful notifications; it does not make every agent update notification-worthy.

Send a Bark notification when at least one of these is true:

• The user explicitly asked for a Bark notification or reminder.
• A long-running task reached a meaningful milestone or completed while the user may be away.
• The agent is blocked, a long-running task failed, or the user needs to act.

Skip Bark for routine tool activity, short tasks, tests merely starting or continuing, partial findings, and updates already visible in the active conversation. If an update is too minor for a normal visible notification, usually do not send it. Use passive only when the user explicitly asks for a quiet, passive, background, or Notification Center-only delivery.

Notification Level

After deciding to send, choose the level from this table. Use active when the user did not specify a level and the situation does not require timeSensitive or critical:

Situation	Level
Meaningful progress, requested task completed, or ordinary user-requested notification	active
Agent is blocked and needs user input soon	timeSensitive
Deployment failed, service is unavailable, long task crashed	timeSensitive
User explicitly requested an emergency/critical alert	critical
User explicitly requested quiet/background delivery	passive

Rules:

• Default to active whenever a notification is worth sending, including meaningful progress and task completion.
• Do not use passive as a low-stakes default or a fallback for routine progress. Skip the push instead.
• Use passive only when the user explicitly requests quiet/background delivery.
• Use timeSensitive only when the user should notice promptly.
• Use critical only when explicitly requested or clearly safety/incident critical; do not use it for routine task failures.
• If the user specifies a level, obey the user.

Configure

Create ~/.config/bark-notify.env manually when possible. It is private local configuration and the script saves it with mode 0600:

mkdir -p ~/.config
chmod 700 ~/.config

To initialize it without putting the key in shell history, pass the key through standard input:

read -rs BARK_KEY; printf '\n'
printf '%s\n' "$BARK_KEY" | python3 scripts/bark-notify.py --save-config --key-stdin
unset BARK_KEY

Agent metadata is optional and lives outside the repository at ~/.config/bark-notify-agents.json:

{
  "codex": {
    "group": "Codex",
    "icon": "https://example.com/icons/codex.png"
  }
}

Bark icons must be URLs reachable by the receiving device. Local .app, .icns, or filesystem paths are not valid notification icon values. If no --icon or agent icon is configured, use the built-in Agent Bark icon hosted from assets/agent-bark.png through jsDelivr. Resolution order is explicit --icon, agent environment/config, then the built-in default.

Check

python3 scripts/bark-notify.py --help
python3 scripts/bark-notify.py --ping
python3 scripts/bark-notify.py --doctor
python3 scripts/bark-notify.py --dry-run --agent codex --level active "Done" "Ready"

--doctor reports the selected server, config-file permissions, agent/group/icon resolution, and ping result without printing the key. --dry-run prints the final request payload with device_key masked and never sends a notification.

If sending fails, first check --doctor; then inspect the reported server/network status. Preserve HTTP status and short messages without exposing credentials.