OSC 7501 Program Status Notifications in NeoServer for iOS and macOS

A remote build finishes while you are checking another server. A coding agent pauses for approval in a different terminal. NeoServer now supports OSC 7501 program status notifications on iOS and macOS, so a task can tell you when it finishes, fails, or needs approval without you repeatedly checking its terminal.

Tap a notification to return to the existing terminal session. On macOS, NeoServer can also locate the session’s split pane.

What is OSC 7501?

OSC 7501 is a terminal escape sequence that a running program uses to report its state. It can describe work in progress, a completed task, a failure, or a pause that needs user input. The program sends structured status information through terminal output; the terminal decides how to present it. See the Program Status Protocol specification for the wire format.

The running program must emit OSC 7501 reports. Turning on notifications does not make every shell command report its status. A compatible command-line tool can send reports itself, and your own scripts can send them with printf.

Which states produce a notification?

NeoServer uses these rules on both iOS and macOS:

Report	System notification
state=done	Task completed
state=error	Task failed
state=blocked:kind=permission	Approval required
state=idle or state=working	No notification
state=blocked:kind=question or kind=auth	No notification

NeoServer suppresses notifications for a terminal you are already viewing while the app is active. Reports from other sessions can notify you. When the app is not active, notifications can appear as long as NeoServer is still receiving terminal output.

Repeated message or progress updates do not create repeated alerts. NeoServer combines rapid changes, spaces notifications from the same session at least five seconds apart, and replaces that session’s previous notification with the latest one.

Enable program status notifications

1. Open NeoServer’s settings and find Terminal Settings.
2. Find Program Status Notifications at the bottom of the terminal settings page. It is enabled by default on iOS and macOS.
3. Run a program that sends OSC 7501 reports. NeoServer requests system notification permission after receiving its first non-empty status report, rather than when you open a terminal or toggle the setting.
4. Allow notifications in the system permission dialog. If permission was previously denied, enable notifications for NeoServer in the operating system’s notification settings.

For an initial test, stay in the terminal until you have answered the permission dialog. Then run the delayed example below and switch to another terminal in NeoServer.

Try a completion notification over SSH

Connect to a server using an ordinary SSH terminal and paste:

printf '\033]7501;state=working:id=demo:app=demo\033\\'
sleep 10
printf '\033]7501;state=done:id=demo:app=demo\033\\'

During the ten-second delay, switch to a different terminal session in NeoServer. Keeping NeoServer open makes this a straightforward test of the status notification flow. A completion notification should arrive after the final report is processed, subject to system notification settings.

To test failure or approval notifications, run either example and switch to another session during the delay:

# Report a failed task.
sleep 10
printf '\033]7501;state=error:id=demo:app=demo\033\\'

# Report a task waiting for approval.
sleep 10
printf '\033]7501;state=blocked:id=demo:kind=permission:app=demo\033\\'
sleep 10

The final delay in the approval example keeps the blocked report in place before the shell returns to its prompt. Leave time for the notification to arrive before returning to the source terminal. Clearing or replacing a report immediately can cancel a pending alert.

These commands only report a status. The approval example does not run an operation or grant permission. Tapping its notification opens the terminal, where you can review the actual program’s request.

Add status reports to your own scripts

Wrap a command so its exit result becomes an explicit completion or failure report:

#!/bin/sh

printf '\033]7501;state=working:id=job:app=script\033\\'

# Replace this command with your build or other task.
if sh -c 'sleep 10'; then
    result=0
    state=done
else
    result=$?
    state=error
fi

printf '\033]7501;state=%s:id=job:app=script\033\\' "$state"
exit "$result"

Run the script in the connected terminal so NeoServer receives its output. This example preserves the command’s exit code. For custom notification text, the protocol’s title and msg fields take Base64-encoded, single-line UTF-8 text; app is a short program identifier.

iOS background behavior and missing alerts

These are local system notifications generated from received terminal output. NeoServer must remain able to receive and parse that output. If iOS suspends or terminates the app, it cannot generate new notifications from remote status changes. A remote job may continue running without a new alert reaching your iPhone.

If an alert does not appear, check these points:

• Start with direct SSH. If the examples work there but fail inside tmux or screen, check whether that layer forwards the OSC sequence to NeoServer.
• Switch away from the source terminal. An active, visible terminal intentionally stays quiet.
• Check both permission and the app toggle. System notification settings and Focus settings can affect whether a banner appears.
• Keep the report alive long enough. Rapidly clearing a report or changing its state can cancel or replace the pending notification.
• Check the reported state. A question or authentication pause does not trigger the approval notification; it requires blocked with kind=permission.

Tapping a notification selects an existing session. If that session has already closed, NeoServer tells you; it does not reconnect or execute commands automatically. If the app is locked, navigation waits until you unlock it.

For connection setup, read the NeoServer quick start. For the rest of the terminal preferences, see Terminal Settings.