← Return to the archive
Essay № 003 · Electron

Taming 12 Terminals: How I Stopped the UI from Freezing

Running 12 AI coding sessions at once means 12 terminals generating output simultaneously. Here is how I kept the UI responsive.

Omniscribe runs up to 12 AI coding sessions simultaneously. Each session gets its own terminal — xterm.js on the frontend, node-pty on the backend. When one AI agent is dumping a 500-line file diff while three others are running test suites, that’s four terminals blasting output at the same time.

The naive version froze the UI within seconds.

The firehose problem

Each node-pty instance fires an onData callback for every chunk the PTY produces. During heavy output — think npm install or a large git diff — a single terminal can fire dozens of events per second. Multiply by 12, and the renderer was drowning in xterm.write() calls. I measured roughly 250 writes per second across all terminals during peak bursts.

Every write() triggers xterm.js’s parser, which updates the buffer, which triggers a render. At 250/sec, the browser’s main thread had no breathing room for anything else — no mouse events, no tab switching, no scrolling. The app looked frozen even though every terminal was technically working.

Backend: throttle at the source

The first layer of defense lives in TerminalService, the NestJS service managing all PTY processes. Instead of forwarding every onData event immediately, output accumulates in a per-session buffer and flushes on a 32ms timer (~30fps):

const OUTPUT_THROTTLE_MS = 32;
const OUTPUT_BATCH_SIZE = 65_536;  // 64KB
const MAX_OUTPUT_BUFFER_SIZE = 524_288;  // 512KB

ptyProcess.onData((data: string) => {
  session.outputBuffer += data;

  if (session.outputBuffer.length > MAX_OUTPUT_BUFFER_SIZE) {
    session.outputBuffer = session.outputBuffer.slice(-MAX_OUTPUT_BUFFER_SIZE);
  }

  if (!session.flushTimer) {
    session.flushTimer = setTimeout(() => {
      this.flushOutput(sessionId);
    }, OUTPUT_THROTTLE_MS);
  }
});

The flush logic is chunk-aware. If the buffer exceeds 64KB, it sends the first 64KB and reschedules itself for the remainder. This prevents a single massive burst from monopolizing the socket:

private flushOutput(sessionId: number): void {
  const session = this.sessions.get(sessionId);
  if (!session || session.paused) { session.flushTimer = null; return; }

  if (session.outputBuffer.length > OUTPUT_BATCH_SIZE) {
    const chunk = session.outputBuffer.slice(0, OUTPUT_BATCH_SIZE);
    session.outputBuffer = session.outputBuffer.slice(OUTPUT_BATCH_SIZE);
    this.eventEmitter.emit(InternalTerminalEvents.OUTPUT, { sessionId, data: chunk });
    session.flushTimer = setTimeout(() => this.flushOutput(sessionId), OUTPUT_THROTTLE_MS);
    return;
  }

  this.eventEmitter.emit(InternalTerminalEvents.OUTPUT, { sessionId, data: session.outputBuffer });
  session.outputBuffer = '';
  session.flushTimer = null;
}

The 512KB cap on outputBuffer is a safety valve. If output arrives faster than the flush loop can drain it (backpressure scenario), only the most recent 512KB is kept rather than letting memory grow unbounded. Data is lost, but the alternative is the process running out of heap.

Frontend: one write per frame

Even with backend throttling, socket events still arrive in bursts. The frontend adds a second coalescing layer using requestAnimationFrame:

const MAX_HIDDEN_BUFFER_SIZE = 1_048_576;  // 1MB

const handleOutput = useCallback((data: string) => {
  if (isDisposedRef.current) return;
  writeBufferRef.current += data;

  if (!isActiveRef.current && writeBufferRef.current.length > MAX_HIDDEN_BUFFER_SIZE) {
    const trimmed = writeBufferRef.current.slice(-MAX_HIDDEN_BUFFER_SIZE);
    const firstNewline = trimmed.indexOf('\n');
    writeBufferRef.current = firstNewline > 0 ? trimmed.slice(firstNewline) : trimmed;
  }

  if (isActiveRef.current && rafIdRef.current === null) {
    rafIdRef.current = requestAnimationFrame(flushWriteBuffer);
  }
}, [isDisposedRef, isActiveRef, flushWriteBuffer]);

Multiple socket events between frames get concatenated into writeBufferRef, then written as a single xterm.write() call on the next animation frame. That dropped the rate from ~250 writes/sec to ~60 — one per frame per terminal.

The real win is hidden terminals. When a terminal tab is not visible, isActiveRef is false, and RAF scheduling stops entirely. Data still accumulates in the buffer (capped at 1MB), but zero CPU goes to parsing or rendering it. When the user switches back, flushBuffer() fires a single RAF to write everything at once.

The newline trick

That buffer trimming deserves a closer look. Slicing to the last 1MB of output can cut in the middle of an ANSI escape sequence like \x1b[38;2;255;128;0m. Writing a partial escape to xterm.js corrupts the parser state — you get garbled colors that persist for the rest of the session. Trimming to the next newline boundary avoids this because escape sequences don’t span lines.

Backpressure: when output wins

Sometimes output genuinely overwhelms the pipe. An AI session running cat on a 10MB log, or a test suite with verbose logging, can produce data faster than the throttle-and-batch pipeline can drain it.

The backend supports explicit PTY pause/resume. When the frontend detects backpressure (buffer hitting capacity), it signals the backend, which calls session.pty.pause(). This triggers kernel-level flow control — the child process’s writes to stdout will block until the session is resumed. No data is lost, but the AI session effectively stalls until the pipe drains.

pause(sessionId: number): void {
  const session = this.sessions.get(sessionId);
  if (!session || session.paused) return;
  session.pty.pause();
  session.paused = true;
}

resume(sessionId: number): void {
  const session = this.sessions.get(sessionId);
  if (!session || !session.paused) return;
  session.pty.resume();
  session.paused = false;

  if (session.outputBuffer.length > 0 && !session.flushTimer) {
    session.flushTimer = setTimeout(() => this.flushOutput(sessionId), OUTPUT_THROTTLE_MS);
  }
}

The user sees a “Buffering output…” overlay — but only after 500ms of sustained backpressure. Transient spikes (< 500ms) never show the overlay, which avoids a distracting flicker during normal operation:

useEffect(() => {
  if (!isBackpressured) { setVisible(false); return; }
  const timer = setTimeout(() => setVisible(true), DEBOUNCE_MS);
  return () => clearTimeout(timer);
}, [isBackpressured]);

The overlay also has a “Cancel output” button that kills the session. Sometimes the right answer is to stop the process, not wait for it.

Terminal initialization: patience required

With 12 terminals mounting simultaneously in a grid layout, container dimensions are not immediately available. CSS grid calculates sizes across frames, and a terminal opened with 0x0 dimensions produces garbage layout.

The init hook defers xterm.open() until the container has non-zero dimensions, then runs a fit-retry loop — up to 20 attempts, each scheduled via requestAnimationFrame:

const performInitialFit = (retriesLeft: number) => {
  if (isDisposedRef.current || !terminal || !fitAddon) return;

  const result = safeFit(fitAddon, terminal, container);
  if (result) {
    isReadyRef.current = true;
    resizeTerminal(sessionId, result.cols, result.rows);
    connectAndJoin(sessionId);
  } else if (retriesLeft > 0) {
    initRetryTimeout = setTimeout(() => {
      requestAnimationFrame(() => performInitialFit(retriesLeft - 1));
    }, 50);
  } else {
    logger.warn('Fit retries exhausted, connecting anyway');
    isReadyRef.current = true;
    connectAndJoin(sessionId);
  }
};

requestAnimationFrame(() => performInitialFit(20));

If all 20 retries fail, it connects anyway and schedules deferred fits at 100ms, 250ms, 500ms, and 1000ms. This handles the case where a panel animation or DnD reorder delays the final layout. The terminal might render at a wrong size for a fraction of a second, but it self-corrects.

Write serialization

One more subtlety: user input writes. When the user types in a terminal while an AI is also feeding commands into it, you can get interleaved writes. Each session has a promise chain that serializes writes:

write(sessionId: number, data: string): void {
  const session = this.sessions.get(sessionId);
  if (!session) return;

  session.writeChain = session.writeChain
    .then(() => this.performWrite(session, data))
    .catch(err => this.logger.error(`[write] Failed for session ${sessionId}:`, err));
}

Large writes (> 1000 chars) are chunked into 100-char pieces with setImmediate yields between them, so a paste of 50KB of text doesn’t block the event loop for the other 11 sessions.

The numbers

Layer Mechanism Key numbers
Backend output Timer-based throttle 32ms interval (~30fps)
Backend output Chunk batching 64KB per flush
Backend output Buffer cap 512KB per terminal
Frontend output RAF coalescing ~250 writes/sec to ~60 writes/sec
Frontend hidden RAF paused + buffer 1MB cap, newline-boundary trim
Backpressure UI Debounced overlay 500ms threshold
Init Fit retry loop 20 retries via RAF + 50ms timeouts
Writes Serialized queue 100-char chunks with setImmediate yield

Total memory budget per terminal in the worst case: 512KB backend buffer + 500KB scrollback + 1MB frontend hidden buffer = ~2MB. For 12 terminals, that’s 24MB. Acceptable.

What I learned

Throttle at the source. The temptation is to fix everything in the renderer. But if you’re already sending 250 socket events/sec, no amount of frontend optimization makes that cheap. The 32ms timer on the backend cut the event count before it ever hit the IPC bridge.

Hidden work is wasted work. Pausing RAF for background terminals was the single biggest win. Before that change, 12 terminals at 60fps meant 720 xterm.write() calls per second even if the user could only see one. After: 60.

Backpressure is a feature, not a failure. The instinct is to buffer everything and never lose data. But unbounded buffers just convert a performance problem into a memory problem. Cap the buffer, pause the source, tell the user what’s happening.

Retry, don’t assume. Container dimensions in a grid layout are non-deterministic during mount. Waiting for “ready” events is fragile. A retry loop with exponential backoff is ugly but reliable. The 20-retry RAF loop handles every edge case I’ve thrown at it — panel resizes, drag-and-drop reorders, animation delays.