Terminal notifications¶

A program in a terminal can ask for your attention while you are working somewhere else: a build script rings the bell when it is done, a prompt rings it when it waits for input, a coding agent on a server asks for a notification when it needs your answer, and in a shell set up for shell integration a long command tells korTTY when it has finished. KorTTY marks the tab such a request comes from, so you see it in the tab bar, and can also show a desktop notification. It never plays a sound.

You can also ask korTTY to watch a tab for you: to tell you when output appears in a quiet tab, or when a tab that was printing falls silent; see Watching a tab for activity or silence.

A keyword highlighting rule of your own can do the same for a word or pattern: it marks the tab and notifies when the pattern appears in new output; see Notifications for matching output.

A program can also ask to put text on your clipboard, or to read it. KorTTY allows that only when you switch it on, asks you before every read, and the status bar tells you each time; see Programs copying to the clipboard and Programs reading the clipboard.

When you are looking at a tab¶

KorTTY only asks for your attention in tabs you are not looking at. A tab counts as seen while it is the selected tab of the window in front, that is the window that has the keyboard focus and is not minimised. Which pane of a tab with split panes has the focus does not matter: the tab is seen as a whole. A tab that is not selected, the tabs of a korTTY window behind another one, and every tab while another application is in front are not seen.

The terminal bell¶

Programs ring the terminal bell with the BEL control character (Ctrl+G): bash and zsh ring it when a Tab completion finds nothing, less and vim when you try to move past the end of a file, and a script can ring it with printf '\a' when a long job ends. The bell works in local shells and SSH sessions alike, in every terminal emulation korTTY offers, and needs no setup on the server.

Bell mark on the tab¶

When the bell rings in a tab you are not looking at, the tab shows 🔔 in its title, after the coding-agent glyph and before the [group] prefix, for example ⚡ 🔔 [Ops] web-01. Pointing at the tab shows The bell rang while you were not looking at this tab. in its tooltip, so the mark is also explained in words.

The mark goes away as soon as you look at the tab: select it, or bring its window to the front. A bell in the tab you are looking at leaves no mark. The mark is always on and makes no sound, so it has no setting of its own. Many bells in quick succession, for example from cat on a binary file, count as one.

Desktop notification for the bell¶

With Desktop notification when the bell rings in a tab you are not looking at switched on in Settings → Messaging (see Messaging settings), a bell in a tab you are not looking at also shows a desktop notification through the operating system's notification service: Notification Center on macOS, a tray balloon on Windows and the desktop's notification server on Linux. Clicking it brings you to the pane, see Clicking a notification.

• The notification's title is korTTY · and the name of the tab, its text says that a program rang the bell. It never contains terminal output. A name the shell set for the tab is cleaned of control and bidi characters first.
• A pane shows at most one bell notification every 10 seconds; further bells in that time only keep the mark on the tab. Each pane of a split tab counts on its own, but the panes that take part in multi-exec count as one, whichever tabs they are in. A bell that rings in a pane within 2 seconds of keys you typed in another pane reaching it through broadcast mode or multi-exec, such as a failed Tab completion on every server at once, answers those keys: it neither marks the tab nor notifies.
• The setting is off by default, because shells ring the bell on every failed Tab completion. A change applies to the open tabs as soon as you save.
• A pane in which korTTY detected a coding agent gets no bell notification while Desktop notification when a coding agent needs a decision or finishes while you are not looking at its pane is on: agents ring the bell when they wait for you, and their own notification already says so, with more detail. The tab still gets its mark.
• Clicking the notification brings the window to the front, selects the tab and focuses the pane the bell rang in, as for every desktop notification of korTTY (see Clicking a notification). The 🔔 in the tab bar stays until you look at the tab.

Long-running commands¶

In a shell set up for shell integration, the shell marks when each command starts and when it finishes, with its exit status. When a command that ran at least the minimum runtime, 30 seconds by default, finishes in a tab you are not looking at, korTTY marks that tab with 🔔 and shows a desktop notification, for example korTTY · web-01 with the text Command failed (exit 1) after 2 min 14 sec. Start a build or an upgrade, switch to another tab or application, and you hear from korTTY when it is done.

• The runtime counts from the moment you pressed Enter to the moment the command finished, without the time you spent typing it. A command that ends with exit status 0 says Command finished, any other status says Command failed, and a shell that reports no status gets Command finished after … without one.
• The notification never contains the command itself, nor anything it printed: command lines can contain passwords and tokens, and a notification can appear on the lock screen. Pointing at the marked tab shows the same text in its tooltip.
• A command that finishes in the tab you are looking at leads to nothing, and so does a command shorter than the minimum runtime. The tab gets its mark even with the notification switched off.
• A tab shows at most one such notification every 10 seconds. When broadcast typed the same command into several panes of a tab and they finish close together, you get one notification, and the tab stays marked until you look at it. With multi-exec, a command you type once runs in every pane that takes part, in whichever tab or window: you get one notification for it however far apart the panes finish, each of their tabs keeps its mark, and those panes together show at most one such notification every 10 seconds.
• Commands that korTTY's AI Agent runs in a pane neither mark the tab nor notify: the agent's run reports its own commands in its activity panel.
• A coding agent such as Claude Code is itself a command to the shell, so when it exits in a tab you are not looking at, that is reported like any other command.
• Without shell integration nothing changes: korTTY does not guess from pauses in the output when a command has finished. Shells without the marks, tmux, screen and mosh connections get no long-command notifications; see the limits of shell integration.

Settings → Messaging has Desktop notification when a long-running command finishes in a tab you are not looking at, on by default, and Minimum command runtime:, from 1 to 3,600 seconds. Both are greyed out while shell integration is switched off, and a change applies to the open tabs as soon as you save. See Messaging settings.

Notifications from programs¶

A program can ask the terminal for a desktop notification with an escape sequence: OSC 9 (the iTerm2 form, ESC ] 9 ; text BEL) or OSC 777 (the urxvt and foot form, ESC ] 777 ; notify ; title ; body BEL). Coding agents such as Claude Code or Codex running on a server can use it to say that they wait for your answer or have finished, and so can your own scripts. Many agents and tools have a setting that sends their notifications this way, often called the iTerm2 style; korTTY understands both forms in local shells and SSH sessions alike, with nothing to install on the server. To try it, run this and switch to another tab within five seconds:

sleep 5; printf '\e]777;notify;%s;%s\a' 'Backup' 'Finished without errors'

When such a request comes from a tab you are not looking at, korTTY marks the tab with 🔔, and pointing at the tab shows A program in this tab sent a notification: with the text in its tooltip. A desktop notification titled korTTY · and the name of the tab shows the text below that title, for example Backup: Finished without errors, so it always says which tab it came from and never passes for a message of another application.

• The program chooses every character of the text, so korTTY cleans it first: control characters, line breaks and the invisible characters that change the reading direction are removed, the title is cut to 80 characters and the text to 200. The terminal never shows the sequence itself.
• A pane shows at most one such notification every 5 seconds; what a program asks for in that time only keeps the mark on the tab and is dropped, so a program that prints notifications in a loop cannot flood your desktop.
• A request in the tab you are looking at leads to nothing.
• A pane in which korTTY detected a coding agent gets no notification of this kind while Desktop notification when a coding agent needs a decision or finishes while you are not looking at its pane is on, because the agent's own notification already says it. korTTY detects agents in local shell tabs only, so an agent on a server always notifies through its own request.
• OSC 9 with a number first, such as the ESC ] 9 ; 4 ; 1 ; 50 BEL progress report of ConEmu and Windows Terminal, is no notification and is ignored. Other OSC 777 commands are no notifications either and are left alone.
• It needs no shell integration, and switching shell integration off does not stop it.
• Inside tmux or screen the requests usually do not arrive: the multiplexer does not pass them on, and korTTY does not unwrap tmux's passthrough sequences. Mosh connections never carry them.
• korTTY's own log never records the text; the tab's tooltip and the notification are the only places korTTY shows it. A terminal log or session journal of the pane leaves escape sequences out, so the text does not reach them either, except when a program uses the rare 8-bit form of the sequence.

Settings → Messaging has Desktop notification when a program in a tab you are not looking at asks for one (OSC 9, OSC 777), on by default. Switched off, a request only marks the tab. A change applies to the open tabs as soon as you save. See Messaging settings.

AI agent and AI Swarm runs¶

korTTY's own AI Agent and AI Swarm runs tell you when they need you or are done while you look elsewhere. When a run in a tab you are not looking at waits for your approval of a command, waits for a password, finishes, or stops without finishing (an error, or the agent gave up blocked), a desktop notification titled korTTY · and the name of the tab says so. Without it, an approval asked for in a window behind another one would hold the run until you happened to look.

• The text is one fixed sentence, such as The AI run in this tab is waiting for your approval. It never contains your prompt, the command waiting for approval, the password request's wording or any output, because a notification can appear on the lock screen.
• A tab shows at most one notification of the same kind every 10 seconds, so a swarm whose agents ask for approvals one after another does not flood your desktop; the run's end still notifies right after an approval.
• A terminal tab whose agent run asks for you is also marked with 🔔, and the tooltip repeats the sentence. An AI Swarm tab keeps its own blinking indicator instead.
• Nothing happens in the tab you are looking at, and nothing when you cancel or restart the run yourself.

Settings → Messaging has Desktop notification when an AI agent or AI swarm run in a tab you are not looking at finishes or waits for you, on by default. Switched off, a terminal tab is still marked. See Messaging settings.

Watching a tab for activity or silence¶

Right-click a terminal tab and choose Monitor for Activity or Monitor for Silence to have korTTY watch it while you work elsewhere. Both are also commands of the command palette for the tab you are in, with a check mark while they are on. They work in local shells and SSH sessions alike, need no shell integration and nothing on the server.

• Monitor for Activity reports output that appears in the tab after at least 10 seconds without any while you are not looking at it, such as a new line in a quiet tail -f log, a message in a chat program or a prompt that finally asks for input. The tab gets 🔔, pointing at it shows New output arrived while you were not looking at this tab., and a desktop notification titled korTTY · and the name of the tab says New output in this tab after at least 10 seconds of quiet. It reports once: further output only reports again after you have looked at the tab, so a log that keeps scrolling in the background notifies you once and not on every line.
• Monitor for Silence reports a pane of the tab that printed something and then stays without output for the time set at Monitor for Silence reports after: in Settings → Messaging, 30 seconds by default and from 5 to 3,600 seconds. The tab gets 🔔 and a desktop notification such as No output in this tab for 30 sec. It is meant for a build, a copy or an upgrade that prints while it works, also in a shell without shell integration, where korTTY cannot tell when a command has finished. It reports once, and again only after the pane printed something new. Switch it on while the command is still printing, or right after it stopped: output from within the threshold before still counts, while a pane that has been quiet for longer reports nothing until it prints again.

Both switches belong to the tab and are off until you switch them on. A tab keeps them while it is open, also when you move it to another window, but they are never saved: a project does not store them, and they end when the tab closes or korTTY quits. Choosing the entry again switches it off. In a tab with split panes every pane is watched on its own, and the notification names the tab.

The same rules as for the bell apply. Nothing happens in the tab you are looking at, and the mark goes away when you look at the tab. A pane shows at most one notification of each kind every 10 seconds, and the panes that take part in multi-exec count as one, whichever tabs they are in. The notification never contains terminal output. Activity and silence have no notification setting of their own: switching the watch on is the request for the notification, so switch it off, or turn off korTTY's notifications in the operating system, to stop them.

What counts as output is everything the pane receives from its session: the echo of what you type there, a prompt the shell redraws, and while korTTY's AI Agent runs in an SSH pane, the prompt the shell prints for the blank line the agent sends now and then to keep the connection alive. Output that arrives within about 3 seconds of keys you typed in another pane reaching the pane through broadcast mode or multi-exec is the shell's answer to those keys, typically their echo: it is no activity and starts no silence count, so typing into a dozen watched panes at once makes none of them notify. Output after a new quiet spell counts again.

Clicking a notification¶

Clicking any of the desktop notifications on this page — the bell, a finished command, a program's request, an AI run, activity or silence — brings the window that holds the tab to the front, selects the tab and focuses the pane the notification came from; an AI Swarm notification selects the swarm's tab. The tab is looked up when you click, so a tab you have moved to another window in the meantime is still found, and a tab that has been closed makes the click do nothing. On macOS this works in the installed korTTY.app, whose notifications are korTTY's own, and with ./gradlew run through the native korTTY Notifications helper; on Windows it works for the latest notification; on Linux it works when the desktop's notification server supports actions, as GNOME and KDE Plasma do. The details per platform are in the table under Coding agents.

Programs copying to the clipboard (OSC 52)¶

Programs such as vim, Neovim and tmux can copy text into the clipboard of the terminal they run in with the OSC 52 escape sequence (ESC ] 52 ; c ; <base64 text> BEL). Over SSH this is the only way for them to reach the clipboard of the computer in front of you: you copy in vim on the server, and the text is on your clipboard. KorTTY allows it only when you switch on Let programs in the terminal copy text to the clipboard (OSC 52) in Settings → Terminal; it is off by default. To try it, switch it on and run:

printf '\e]52;c;%s\a' "$(printf 'copied from the server' | base64)"

• Each time a program copies, the status bar of its window says so and names the tab, for example A program in the tab “web-01” copied 22 characters to the clipboard (OSC 52). While the setting is off, the status bar says that a program tried, and the clipboard stays as it was.
• With OSC 52 programs can only write the clipboard, never read it: korTTY never answers the OSC 52 query, so nothing you copied elsewhere reaches a program in the terminal. A program's own paste command that reads the clipboard this way, such as Neovim's OSC 52 paste, therefore gets nothing; paste with korTTY's paste shortcut instead, which goes through paste protection. Programs that speak kitty's clipboard protocol can ask to read it, see Programs reading the clipboard.
• One write can carry up to 256 KiB of text. A write that is larger, that is not valid base64 or whose text is not UTF-8 changes nothing, and the status bar says so. Line breaks in the base64, as base64 without -w0 writes it, are fine.
• Every selection a program names (c, p, q, s, the cut buffers 0 to 7, or none) goes to the same clipboard; on Linux that is the clipboard, not the primary selection. When a program copies several times in quick succession, the clipboard ends up with the last text.
• With the enterprise policy's internal clipboard mode, what programs copy lands in korTTY's internal clipboard and never reaches the operating system's clipboard.
• Your organization can forbid it with allow-osc52-clipboard-write = false in its enterprise policy: the setting is then off and locked with the "Managed by your organization" hint, and the status bar says that a program tried.
• It needs no shell integration and works in local shells and SSH sessions alike. Inside tmux, set -g set-clipboard on in ~/.tmux.conf passes the copies of tmux and of the programs in it on to korTTY. Mosh connections may not carry the sequence.
• Apart from the status bar, nothing tells you that the clipboard changed. Text a program put there and you paste into korTTY still goes through paste protection, which asks about line breaks and control characters, but other applications paste it as it is. Leave the setting off while you work on servers whose programs you do not trust.
• korTTY's own log records only how many bytes a program copied, never the text. A terminal log or session journal of the pane leaves escape sequences out, so the copied text does not reach them either, except when a program uses the rare 8-bit form of the sequence: then the file holds the text base64-encoded.

The setting is read on every write, so a change applies to open tabs as soon as you save. See Terminal settings.

Programs reading the clipboard (OSC 5522)¶

kitty's clipboard protocol, OSC 5522, lets programs read the clipboard as well as write it, and lets them ask whether the terminal supports it (CSI ? 5522 $ p). Editors such as Neovim and the kitten clipboard tool use it, also on a server over SSH. KorTTY speaks it under the same rules as OSC 52, and reading needs a second switch and your answer each time.

• Writing follows Let programs in the terminal copy text to the clipboard (OSC 52) and allow-osc52-clipboard-write: with it off, a program's write is refused and the status bar says that a program tried. With it on, the text goes on the clipboard, at most 256 KiB, and the status bar names the tab, for example A program in the tab “web-01” copied 22 characters to the clipboard (OSC 5522).
• Reading needs Let programs in the terminal ask to read the clipboard (OSC 5522) in Settings → Terminal, which is off by default. With it on, every read opens a prompt that names the tab, the name the program gives itself and the types it asks for. Deny is the default button, and closing the prompt denies too. Allow Once hands out the text this one time.
• Allow for This Program appears only when the program sends a name and a password with its request. KorTTY then hands the text to later requests with the same name and password in the same tab without asking, until the tab is closed. Nothing of it is saved.
• After you deny a read, the tab refuses further reads without asking for 10 seconds, so a program cannot bury you in prompts.
• Paste events: a program can ask for your pastes to reach it as an event instead of as typed text (CSI ? 5522 h). When you then paste into it with korTTY's paste shortcut, the program reads the clipboard itself, without a prompt, because the paste is your consent. KorTTY only does this while reading is switched on; otherwise the paste goes the usual way, through paste protection. A program reading through a paste event gets the text as it is, so korTTY's paste warning does not see it. When your organization sets a paste-warning floor, every paste goes the usual way.
• KorTTY exchanges text only (text/plain). A write without text is refused, and a read gets the text and nothing else. Listing what is on the clipboard needs no permission and reports text/plain or nothing. The primary selection of Linux is not available to programs.
• With the enterprise policy's internal clipboard mode, writes land in korTTY's internal clipboard and reads get the internal clipboard, never the operating system's.
• Your organization can forbid reading with allow-osc5522-clipboard-read = false in its enterprise policy: the switch is then off and locked, no prompt opens, and paste events are off.
• The strict terminal mode drops OSC 5522, the paste-event mode and the support query, so a program in such a session sees a terminal without the protocol.
• KorTTY's log records how many bytes a program wrote or read, never the text.

To try it, switch both settings on and run kitten clipboard --get-clipboard on a computer with kitty's tools installed, or ask whether the terminal supports the protocol:

printf '\e[?5522$p'; read -rs -t 1 -d y reply; printf '%q\n' "$reply"

A reply ending in 5522;2$ means that korTTY supports it and paste events are off.