1.. _desktop_notifications:
2
3
4Desktop notifications
5=======================
6
7|kitty| implements an extensible escape code (OSC 99) to show desktop
8notifications. It is easy to use from shell scripts and fully extensible to
9show title and body.  Clicking on the notification can optionally focus the
10window it came from, and/or send an escape code back to the application running
11in that window.
12
13The design of the escape code is partially based on the discussion in
14the defunct
15`terminal-wg <https://gitlab.freedesktop.org/terminal-wg/specifications/-/issues/13>`_
16
17The escape code has the form::
18
19    <OSC> 99 ; metadata ; payload <terminator>
20
21Here ``<OSC>`` is :code:`<ESC>]` and ``<terminator>`` is
22:code:`<ESC><backslash>`.  The metadata is a section of colon separated
23:code:`key=value` pairs. Every key must be a single character from the set
24:code:`a-zA-Z` and every value must be a word consisting of characters from
25the set :code:`a-zA-Z0-9-_/\+.,(){}[]*&^%$#@!`~`. The payload must be
26interpreted based on the metadata section. The two semi-colons *must* always be
27present even when no metadata is present.
28
29Before going into details, lets see how one can display a simple, single line
30notification from a shell script::
31
32    printf '\x1b]99;;Hello world\x1b\\'
33
34To show a message with a title and a body::
35
36    printf '\x1b]99;i=1:d=0;Hello world\x1b\\'
37    printf '\x1b]99;i=1:d=1:p=body;This is cool\x1b\\'
38
39The most important key in the metadata is the ``p`` key, it controls how the
40payload is interpreted. A value of ``title`` means the payload is setting the
41title for the notification. A value of ``body`` means it is setting the body,
42and so on, see the table below for full details.
43
44The design of the escape code is fundamentally chunked, this is because
45different terminal emulators have different limits on how large a single escape
46code can be. Chunking is accomplished by the ``i`` and ``d`` keys. The ``i``
47key is the *notification id* which can be any string containing the characters
48``[a-zA-Z0-9_-+.]``. The ``d`` key stands for *done* and
49can only take the values ``0`` and ``1``. A value of ``0`` means the
50notification is not yet done and the terminal emulator should hold off
51displaying it. A value of ``1`` means the notification is done, and should be
52displayed. You can specify the title or body multiple times and the terminal
53emulator will concatenate them, thereby allowing arbitrarily long text
54(terminal emulators are free to impose a sensible limit to avoid
55Denial-of-Service attacks).
56
57Both the ``title`` and ``body`` payloads must be either UTF-8 encoded plain
58text with no embedded escape codes, or UTF-8 text that is base64 encoded, in
59which case there must be an ``e=1`` key in the metadata to indicate the payload
60is base64 encoded.
61
62When the user clicks the notification, a couple of things can happen, the
63terminal emulator can focus the window from which the notification came, and/or
64it can send back an escape code to the application indicating the notification
65was activated. This is controlled by the ``a`` key which takes a comma
66separated set of values, ``report`` and ``focus``. The value ``focus`` means
67focus the window from which the notification was issued and is the default.
68``report`` means send an escape code back to the application. The format of the
69returned escape code is::
70
71    <OSC> 99 ; i=identifier ; <terminator>
72
73The value of ``identifier`` comes from the ``i`` key in the escape code sent by
74the application. If the application sends no identifier, then the terminal
75*must* use ``i=0``. Actions can be preceded by a negative sign to turn them
76off, so for example if you do not want any action, turn off the default
77``focus`` action with::
78
79    a=-focus
80
81Complete specification of all the metadata keys is in the table below. If a
82terminal emulator encounters a key in the metadata it does not understand,
83the key *must* be ignored, to allow for future extensibility of this escape
84code. Similarly if values for known keys are unknown, the terminal emulator
85*should* either ignore the entire escape code or perform a best guess effort
86to display it based on what it does understand.
87
88.. note::
89   It is possible to extend this escape code to allow specifying an icon for
90   the notification, however, given that some platforms, such as macOS, dont
91   allow displaying custom icons on a notification, at all, it was decided to
92   leave it out of the spec for the time being.
93
94   Similarly, features such as scheduled notifications could be added in future
95   revisions.
96
97
98=======  ====================  =========  =================
99Key      Value                 Default    Description
100=======  ====================  =========  =================
101``a``    Comma separated list  ``focus``  What action to perform when the
102         of ``report``,                   notification is clicked
103         ``focus``, with
104         optional leading
105         ``-``
106
107``d``    ``0`` or ``1``        ``1``      Indicates if the notification is
108                                          complete or not.
109
110``e``    ``0`` or ``1``        ``0``      If set to ``1`` means the payload is base64 encoded UTF-8,
111                                          otherwise it is plain UTF-8 text with no C0 control codes in it
112
113``i``    ``[a-zA-Z0-9-_+.]``   ``0``      Identifier for the notification
114
115``p``    One of ``title`` or   ``title``  Whether the payload is the notification title or body. If a
116         ``body``.                        notification has no title, the body will be used as title.
117=======  ====================  =========  =================
118
119
120.. note::
121   |kitty| also supports the legacy OSC 9 protocol developed by iTerm2 for
122   desktop notifications.
123