notifications.md

title	Desktop Notifications
description	Get notified when Nanocoder needs your attention
sidebar_order	14

Desktop Notifications

When Nanocoder is running a long task in the background, you might switch to another window and miss when it needs your input. Desktop notifications let you know when attention is required.

Quick Start

Open /settings and select Notifications to enable them. Toggle which events you want to be notified about:

• Tool Confirmation — a tool call needs your approval
• Question Prompt — the AI has asked you a question
• Generation Complete — the AI has finished responding and is ready for your next message
• Triggered Run Complete — a daemon-triggered skill run has finished

You can also enable notification sound, and a Terminal Bell that writes a BEL character to stdout. The bell is rendered by the terminal emulator itself, so it still reaches you over SSH or inside tmux, where the desktop notifiers cannot land.

The bell rides along with the desktop notification, so it needs the master Notifications toggle on as well - Terminal Bell on its own does nothing. If you are inside tmux and hear nothing, tmux swallows the bell unless it is configured to pass it through:

set -g monitor-bell on
set -g bell-action any

How It Works

Nanocoder uses native OS notification APIs — no bundled binaries or external dependencies.

Platform	Method	Icon Support
macOS	terminal-notifier (if installed)	Yes
macOS	osascript (fallback)	No
Linux	notify-send	Yes
Windows	PowerShell (system tray balloon notification)	No

macOS — Getting the Best Experience

By default, Nanocoder falls back to osascript which shows basic notifications without the Nanocoder icon. For the full experience with icon support and proper click-to-focus behaviour, install terminal-notifier via Homebrew:

brew install terminal-notifier

Nanocoder will automatically detect and use it. You may need to allow notifications for terminal-notifier in System Settings > Notifications the first time.

Linux

Notifications use notify-send, which is included with most desktop environments (GNOME, KDE, etc.). The Nanocoder icon ships with the package and is included automatically.

Configuration

Notification preferences are stored in nanocoder-preferences.json under the top-level notifications key. You can configure them via /settings or by editing the file directly:

{
  "notifications": {
    "enabled": true,
    "sound": true,
    "bell": true,
    "events": {
      "toolConfirmation": true,
      "questionPrompt": true,
      "generationComplete": false
    },
    "customMessages": {
      "toolConfirmation": {
        "title": "Action Required",
        "message": "Nanocoder needs your approval"
      }
    }
  }
}

Option	Type	Default	Description
enabled	boolean	false	Master toggle for all notifications
sound	boolean	false	Play a sound with each notification (macOS only; Linux and Windows use the system's default notification behaviour)
bell	boolean	false	Also write a terminal bell (BEL) to stdout — skipped when stdout is not a TTY
events.toolConfirmation	boolean	true	Notify when a tool needs approval
events.questionPrompt	boolean	true	Notify when the AI asks a question
events.generationComplete	boolean	true	Notify when a response is ready
events.triggeredRunComplete	boolean	true	Notify when a daemon-triggered skill run (file-watch, cron, CI watch) finishes
events.ciFailureDetected	boolean	true	Notify as soon as CI watch detects a failing run, before investigation starts
events.ciInvestigationComplete	boolean	true	Notify when the automated CI-failure investigation finishes
customMessages.<event>	object	—	Override the default title and message for an event

The last three fire only from the per-project daemon (nanocoder daemon start) — see Scheduler and CI Watch configuration in Preferences.

Events you leave out of events keep their default of true, so {"notifications": {"enabled": true}} is enough to turn every event on.

Notification titles include the current project directory name, e.g. "Tool Confirmation Required in my-project".