1. the SSH transport reads bytes;
2. the app updates session state and logs;
3. Swift posts the output to the UI;
4. WebKit IPC delivers it to the terminal renderer;
5. the renderer parses escape sequences and paints.

If every small read immediately triggers that entire path, a fast server can create hundreds of main-thread updates per second. CPU usage rises, scrolling becomes uneven, and input latency gets worse precisely when output is busiest.

Here is the design that worked for the terminal pipeline in Nexus Shell.

Drain the transport, but keep control responsive

With libssh2, socket readability does not mean its internal decrypted buffer is empty. The read loop should continue until EAGAIN, otherwise already-buffered output can be left behind while the thread goes back to sleep.

At the same time, an unlimited drain loop can starve input, resize, cancellation, and keepalive work. I cap each turn at 64 reads of 64 KiB, then return to the command inbox before continuing:

var batch = 0

while batch < 64 {
    let count = libssh2_channel_read_ex(channel, 0, buffer, 65_536)

    if count > 0 {
        batch += 1
        consume(Data(bytes: buffer, count: count))
    } else if count == LIBSSH2_ERROR_EAGAIN {
        break
    } else {
        handleEOFOrError(count)
        break
    }
}

if batch >= 64 {
    processPendingCommands()
}

The exact limit is not universal. The useful principle is to drain enough data to avoid unnecessary sleeps while preserving a bounded opportunity for control messages.

Coalesce output at the UI boundary

The next bottleneck is not the SSH read itself. It is the repeated work caused by each chunk: state changes, notifications, WebKit calls, terminal parsing, and rendering.

Instead of forwarding every chunk independently, append output per session and flush at roughly one display frame:

@MainActor
func enqueue(_ chunk: String, sessionID: UUID) {
    pending[sessionID, default: ""].append(chunk)

    guard !flushScheduled else { return }

    let elapsed = CACurrentMediaTime() - lastFlush
    if elapsed >= 0.016 {
        flush()
    } else {
        flushScheduled = true
        scheduleFlush(after: 0.016 - elapsed)
    }
}

This changes the cost model from “one UI transaction per transport callback” to “at most about one transaction per frame per active session.” Large bursts become much cheaper without dropping data.

Preserve zero-latency echo for sparse output

Always waiting 16 ms makes benchmarks look tidy but makes typing feel slightly soft. The compromise is a leading-edge flush:

• if enough time has passed since the previous flush, send the first chunk immediately;
• only coalesce subsequent chunks that arrive within the same frame window.

Interactive echo stays immediate, while cat-style output is batched.

Keep binary protocols out of the text decoder

Terminal output is usually UTF-8 text, but in-terminal transfer protocols such as ZMODEM contain arbitrary bytes. Decoding those bytes into String can replace invalid sequences and corrupt checksums.

The transport therefore has two mutually exclusive paths:

• normal terminal mode emits decoded text;
• raw transfer mode emits Data unchanged.

Switching to raw mode only after the transfer detector has matched preserves terminal behavior without treating a binary stream as text.

Buffer output before the UI handler is attached

One subtle race happens at startup: the SSH owner thread may receive the server banner or first shell prompt before the terminal view installs its output handler. Dropping that output makes a connection appear blank or incomplete.

I keep a small bounded pending buffer next to the handler. Installing the handler atomically drains the pending text. The bound matters because a view that never attaches should not create unbounded memory growth.

What to measure

Throughput alone is not enough. A useful test matrix includes:

• time until the first character is visible;
• typing latency during a large output burst;
• CPU usage in both the app and WebKit process;
• resize and cancellation responsiveness;
• exact preservation of multilingual UTF-8 output;
• binary transfer integrity;
• the initial banner and prompt before the view fully mounts.

The broader lesson is that terminal performance is a scheduling problem across boundaries. Drain the transport correctly, batch expensive UI work, keep sparse interaction immediate, and never mix binary and text paths.

This article comes from work on Nexus Shell, the native macOS SSH client I develop. The product link is included for context; the architecture above is useful for any terminal UI that bridges a native transport and a web-based renderer.

Suggested tags: macos, swift, ssh, performance