desktop-notify-kitty

Pi extension that sends desktop notifications via kitten notify (kitty) or notify-send when a kitty terminal session needs attention.

Package details

← Back

extension

Install desktop-notify-kitty from npm and Pi will load the resources declared by the package manifest.

npm repo home report

$ pi install npm:desktop-notify-kitty

Package: desktop-notify-kitty
Version: 0.2.0
Published: Apr 29, 2026
Downloads: 282/mo · 282/wk
Author: cjrh
License: MIT
Types: extension
Size: 11 KB
Dependencies: 0 dependencies · 1 peer

Pi manifest JSON

{
  "extensions": [
    "./extensions"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

desktop-notify-kitty

A pi extension that sends a Linux desktop notification when pi finishes an agent run and the kitty terminal window running pi is not focused.

It uses:

kitten notify for desktop notifications in kitty (clicking the notification jumps back to the originating window)
notify-send as a fallback for non-kitty terminals
kitty @ ls --self + KITTY_WINDOW_ID for kitty-specific focus detection
xterm focus reporting as a fallback for non-kitty terminals

Install

From npm:

pi install npm:desktop-notify-kitty

Or from GitHub:

pi install git:github.com/cjrh/desktop-notify-kitty

Reload any already-running pi session:

/reload

Test

Inside pi:

/desktop-notify-test

Behavior

The extension listens for pi's agent_end lifecycle event. When pi completes a response, it sends a notification only if the current terminal does not appear focused.

The notification includes the current project directory name and a short, truncated excerpt from the last assistant answer. Thinking/reasoning blocks, tool calls, images, and unknown content blocks are ignored.

Requirements

Linux desktop notification service
kitty terminal: kitten notify is used automatically (kitty ≥ 0.36.0)
Non-kitty terminals: notify-send on PATH (fallback)
kitty remote control must be available for kitty @ ls (focus detection)

If kitty focus detection is unavailable, the extension falls back to generic terminal focus reporting.

Notes

This detects whether the terminal is focused, not whether it is merely visible on screen. On Wayland, reliable cross-compositor window visibility detection is generally not available to terminal applications.

If you already have a local copy of this extension in ~/.pi/agent/extensions/, remove or disable that copy before installing this package to avoid duplicate notifications.