Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

perf(chat): skip the screen poll while the window is unfocused, re-read on focus

Brandon Bridgesad943e4dcbf0
diff --git a/CLAUDE.md b/CLAUDE.md
index 995fcd3c4..99b3716bb 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4190,8 +4190,9 @@ command-bearing opens; this does not add a human-confirm dialog or change mobile
A send therefore goes through `pty.sendChatPrompt`, where core captures the pane first and
refuses (`ChatPromptBlocked`, nothing written, the draft kept) when the bottom of the screen is a
dialog footer or has no input box; an empty or unreadable capture is NOT evidence and sends as
- before. A LOCAL pane is also polled every 2 s while the view is visible, to disable the composer
- and show the dialog's lines; SSH and relay panes are not polled (a round trip per read) and rely
+ before. A LOCAL pane is also polled every 2 s while the view is visible AND the window focused
+ (an unfocused window skips ticks — ~30 tmux spawns a minute per view otherwise — and `focus`
+ re-reads at once; unknown focus polls), to disable the composer and show the dialog's lines; SSH and relay panes are not polled (a round trip per read) and rely
on the send-time check. Another CLI's layout would read as a permanent dialog, so an agent joins
the list only with its own measured reader.
**Live progress (2026-09).** While the agent works, a `role=status` row closes the thread (the ONE
diff --git a/src/renderer/lib/chatLive.test.ts b/src/renderer/lib/chatLive.test.ts
index f1eb5cd83..6bd047f35 100644
--- a/src/renderer/lib/chatLive.test.ts
+++ b/src/renderer/lib/chatLive.test.ts
@@ -4,8 +4,10 @@ import {
CHAT_OPTIMISTIC_WORKING_MS,
chatActivity,
planLiveReload,
+ screenPollTickAllowed,
shouldPollScreen,
- turnEndReloadCarries
+ turnEndReloadCarries,
+ windowFocusHint
} from './chatLive'
describe('chatActivity — the status row at the end of the ⌘M thread', () => {
@@ -98,3 +100,41 @@ describe('shouldPollScreen — reading the pane for the agent\'s own dialogs', (
}
})
})
+
+describe('screenPollTickAllowed — one tick of the screen poll (audit main-6)', () => {
+ it('runs while the window is visible and focused', () => {
+ expect(screenPollTickAllowed({ hidden: false, focused: true })).toBe(true)
+ })
+
+ it('skips while the window is unfocused: ~30 tmux spawns a minute per chat view nobody can type into', () => {
+ expect(screenPollTickAllowed({ hidden: false, focused: false })).toBe(false)
+ })
+
+ it('skips while the page is hidden, focused or not (the original gate)', () => {
+ expect(screenPollTickAllowed({ hidden: true, focused: true })).toBe(false)
+ expect(screenPollTickAllowed({ hidden: true, focused: null })).toBe(false)
+ })
+
+ it('unknown focus polls: the hint fails toward the old behaviour', () => {
+ expect(screenPollTickAllowed({ hidden: false, focused: null })).toBe(true)
+ })
+})
+
+describe('windowFocusHint — reading focus without guessing', () => {
+ it('reports what the document says', () => {
+ expect(windowFocusHint({ hasFocus: () => true })).toBe(true)
+ expect(windowFocusHint({ hasFocus: () => false })).toBe(false)
+ })
+
+ it('is unknown, never false, when the document cannot answer', () => {
+ expect(windowFocusHint(undefined)).toBeNull()
+ expect(windowFocusHint({})).toBeNull()
+ expect(
+ windowFocusHint({
+ hasFocus: () => {
+ throw new Error('no window')
+ }
+ })
+ ).toBeNull()
+ })
+})
diff --git a/src/renderer/lib/chatLive.ts b/src/renderer/lib/chatLive.ts
index 810ab9c9e..6abc7a152 100644
--- a/src/renderer/lib/chatLive.ts
+++ b/src/renderer/lib/chatLive.ts
@@ -66,6 +66,35 @@ export function shouldPollScreen(s: {
return s.readable && !s.readOnly && !s.remote && (s.refusal === null || s.refusal === 'working')
}
+/**
+ * Does THIS tick of the screen poll run? Not while the page is hidden (the original gate), and not
+ * while the window is unfocused: a nodeterm window left visible on a second monitor is not hidden
+ * by Chromium's definition, so the hidden gate alone kept every chat view spawning a `tmux
+ * capture-pane` every 2 s — ~30 spawns a minute per open chat view — for a composer nobody could
+ * type into (perf audit 2026-10, main-6 / roadmap #21). The panel re-ticks on `focus`, so the
+ * screen is re-read the moment someone can act on it, and a send re-checks the screen in core
+ * (`pty.sendChatPrompt`) regardless, so skipping a tick never weakens dialog safety.
+ *
+ * `focused: null` is "could not tell" and polls: a hint must fail toward the old behaviour.
+ */
+export function screenPollTickAllowed(s: { hidden: boolean; focused: boolean | null }): boolean {
+ if (s.hidden) return false
+ return s.focused !== false
+}
+
+/**
+ * Window focus as a hint for `screenPollTickAllowed`: `null` when the document cannot answer (no
+ * `hasFocus` — a test DOM, an exotic embedder — or it throws), never a guessed `false`.
+ */
+export function windowFocusHint(doc: { hasFocus?: () => boolean } | undefined): boolean | null {
+ if (doc === undefined || typeof doc.hasFocus !== 'function') return null
+ try {
+ return doc.hasFocus()
+ } catch {
+ return null
+ }
+}
+
/** What the row at the end of the thread says; `null` = no row. */
export type ChatActivity = 'working' | 'dialog' | null
diff --git a/src/renderer/nodes/ChatPanel.screenDialog.test.tsx b/src/renderer/nodes/ChatPanel.screenDialog.test.tsx
index 80e84e6f5..f01325c74 100644
--- a/src/renderer/nodes/ChatPanel.screenDialog.test.tsx
+++ b/src/renderer/nodes/ChatPanel.screenDialog.test.tsx
@@ -70,8 +70,14 @@ async function typeAndEnter(text: string): Promise<void> {
})
}
+// jsdom's `hasFocus()` is false (nothing focused the test window), and the poll skips unfocused
+// windows (audit main-6) — so every test starts with a focused window, and the focus tests flip it.
+let focused = true
+
beforeEach(() => {
vi.useFakeTimers()
+ focused = true
+ vi.spyOn(document, 'hasFocus').mockImplementation(() => focused)
screen.now = IDLE
capture.mockClear()
sendChatPrompt.mockReset()
@@ -90,6 +96,7 @@ afterEach(async () => {
return { byId }
})
vi.useRealTimers()
+ vi.restoreAllMocks()
})
describe('ChatPanel — the agent\'s own dialog on screen', () => {
@@ -178,4 +185,38 @@ describe('ChatPanel — the agent\'s own dialog on screen', () => {
expect(sendChatPrompt).toHaveBeenCalledWith(NODE, 'hello', 'claude')
})
+
+ it('skips ticks while the window is unfocused, and re-reads the moment it is focused', async () => {
+ focused = false
+ screen.now = TRUST
+ await mount()
+ await tick()
+ await tick()
+
+ // ~30 tmux spawns a minute per chat view while nobody can type into it — none now.
+ expect(capture).not.toHaveBeenCalled()
+ expect(notice()).toBeNull()
+
+ focused = true
+ await act(async () => {
+ window.dispatchEvent(new Event('focus'))
+ })
+
+ // No waiting for the next interval: the dialog is on screen before anyone types.
+ expect(capture).toHaveBeenCalledTimes(1)
+ expect(textarea().disabled).toBe(true)
+ expect(notice()?.textContent).toContain('No, exit')
+ })
+
+ it('polls when the window cannot say whether it is focused (the hint fails toward polling)', async () => {
+ vi.spyOn(document, 'hasFocus').mockImplementation(() => {
+ throw new Error('no focus source')
+ })
+ screen.now = TRUST
+ await mount()
+ await tick()
+
+ expect(capture).toHaveBeenCalled()
+ expect(textarea().disabled).toBe(true)
+ })
})
diff --git a/src/renderer/nodes/ChatPanel.tsx b/src/renderer/nodes/ChatPanel.tsx
index 1164862d4..c3354a1dc 100644
--- a/src/renderer/nodes/ChatPanel.tsx
+++ b/src/renderer/nodes/ChatPanel.tsx
@@ -39,8 +39,10 @@ import {
TURN_END_RELOAD_DELAYS_MS,
chatActivity,
planLiveReload,
+ screenPollTickAllowed,
shouldPollScreen,
- turnEndReloadCarries
+ turnEndReloadCarries,
+ windowFocusHint
} from '../lib/chatLive'
import { sentCommand } from '@shared/chat-command'
import { isInteractiveBuiltin } from '@shared/chat-catalog'
@@ -683,20 +685,29 @@ export function ChatPanel({
// Re-read the pane's screen while the view is visible (see `screenBlock`). A read that fails or
// finds a blank screen changes nothing: unknown is not evidence either way.
+ // Ticks are skipped while the window is unfocused (`screenPollTickAllowed`: ~30 tmux spawns a
+ // minute per chat view otherwise, audit main-6), and coming back — `focus`, or the page turning
+ // visible — re-reads at once, so a dialog that opened meanwhile is on screen before anyone types.
useEffect(() => {
if (!pollScreen) {
setScreenBlock((b) => (b?.live === true ? null : b))
return
}
let cancelled = false
+ // A focus re-tick can land while the interval's read is still out; one read at a time.
+ let inFlight = false
const tick = async (): Promise<void> => {
const el = msgsRef.current
- if (el === null || el.clientHeight === 0 || document.hidden) return
+ if (el === null || el.clientHeight === 0 || inFlight) return
+ if (!screenPollTickAllowed({ hidden: document.hidden, focused: windowFocusHint(document) })) return
let screen: string
+ inFlight = true
try {
screen = await api.pty.capture(nodeId)
} catch {
return
+ } finally {
+ inFlight = false
}
if (cancelled) return
const read = readClaudeScreen(screen)
@@ -707,9 +718,14 @@ export function ChatPanel({
}
void tick()
const t = setInterval(() => void tick(), CHAT_SCREEN_POLL_MS)
+ const onReturn = (): void => void tick()
+ window.addEventListener('focus', onReturn)
+ document.addEventListener('visibilitychange', onReturn)
return () => {
cancelled = true
clearInterval(t)
+ window.removeEventListener('focus', onReturn)
+ document.removeEventListener('visibilitychange', onReturn)
}
}, [pollScreen, api, nodeId])