Terminal viewport bounces during Claude Code sessions with selection locked

[gregpriday]

Summary

During long-running Claude Code sessions in Canopy terminals (particularly with Codex MCP active), the terminal viewport intermittently bounces between the bottom and mid-buffer positions, with text selection locked during the bouncing phase. The behavior occurs in both Canopy and VS Code's integrated terminal, indicating it's triggered by Claude's escape sequences interacting with xterm.js rather than Canopy-specific scroll logic.

Current Behavior

Viewport bouncing:

• Terminal scrolls to bottom where new output appears
• Immediately jumps upward to a fixed position in the middle of chat history
• Continues bouncing between bottom and mid-buffer region as new content arrives

Selection lock:

• Text selection is disabled or severely impaired during bouncing
• Mouse-based selection behaves as if terminal is in mouse-tracking mode
• Dragging over text doesn't select as expected

Spontaneous recovery:

• After additional output (often when MCP call finishes), bouncing stops
• Selection functionality returns to normal
• Subsequent output scrolls to bottom and stays there

When it occurs:

• Most visible during active Claude Code work (e.g., /codex:plan with Codex MCP)
• Requires long chat history in terminal
• Typically starts mid-session, not from beginning
• Reproducibility: Intermittent during intensive Claude sessions

Expected Behavior

When terminal is at bottom and user hasn't scrolled up:

• Viewport should track new output and remain pinned to bottom
• No jumps to earlier lines in the buffer

When user has scrolled up:

• Respect user's scroll position
• Don't forcibly re-scroll unless explicitly requested

Text selection:

• Should always be possible when dragging with mouse
• No alternative mode should prevent selection without explicit user choice

Steps to Reproduce

1. Open Canopy terminal and launch Claude Code CLI
2. Start a conversation that generates significant history
3. Execute /codex:plan or other intensive MCP operations
4. Observe viewport behavior as Codex processes the request
5. Attempt to select text during active processing

Reproducibility: Intermittent during Claude Code sessions with long history and active MCP calls

Environment

• OS: macOS 14.2+ (likely affects all platforms)
• App: Canopy Command Center (Electron-based)
• Terminal stack:
  • node-pty (Electron main/utility processes)
  • xterm.js (renderer)
  • SAB-based frame buffering in TerminalInstanceService
• Agent: Claude Code CLI with Codex MCP
• Version: Post-PR Fix: Restore clear command detection in terminals #919 ("fix(terminal): restore clear command detection")

Evidence

Affected Files:

• src/services/TerminalInstanceService.ts - SAB/frame buffering, scroll management
• src/components/Terminal/TerminalPane.tsx - Terminal rendering and user interaction
• electron/services/AgentStateMachine.ts - Agent state tracking

Observations:

• Also observed in VS Code's integrated terminal with Claude Code (not Canopy-specific)
• Does not affect plain shell sessions (bash/zsh) or other agents the same way
• Persists after PR Fix: Restore clear command detection in terminals #919 scroll/buffer refactor, ruling out our scroll logic as root cause

Related context:
PR #919 changes:

• Removed agent-driven scroll snapping
• Simplified setAgentState to no-op for scrolling
• Added frame-aware SAB buffering for TUI detection
• setFocused no longer calls scrollToBottom on focus changes
• Resizes don't auto-scroll

Root Cause

Hypothesized: Claude Code CLI emits ANSI escape sequences that xterm.js interprets as viewport repositioning commands:

1. Cursor movement to earlier lines

   • CSI <row>;<col>H / CSI <row>;<col>f (absolute cursor position)
   • CSI nA / CSI nB (cursor up/down)
   • ESC 7 / ESC 8 (save/restore cursor)
   • When cursor moves off-screen above viewport, xterm auto-adjusts to keep cursor visible

2. Mouse tracking enables (selection lock)

   • CSI ?1000h, CSI ?1002h, CSI ?1006h (mouse reporting modes)
   • Routes mouse events to application instead of using for selection
   • Disabled with corresponding ...l sequences when bouncing stops

3. Scroll-region manipulation

   • CSI <top>;<bottom> r (set scrolling region)
   • Combined with cursor movement causes viewport repositioning

Supporting evidence:

• Bouncing only occurs during intensive Claude work (Codex MCP calls)
• Stops when additional output produced (mode exits)
• Selection locked during bounce, returns after
• Same behavior in VS Code terminal (CLI-driven, not app-specific)

Most plausible: Claude Code enters TUI-like mode for progress/status rendering, using cursor movement and mouse tracking for in-place updates. Xterm follows these sequences, causing visible bouncing and selection hijacking.

Deliverables

Code Changes

Diagnostic phase:

• Add escape sequence logging to TerminalInstanceService for agent terminals
• Capture raw PTY output to identify exact sequences causing bouncing

Mitigation (escape sequence filtering):

• Create ANSI sequence sanitizer layer for agent terminals in "follow mode"
• Strip problematic sequences before xterm receives them:
  • Mouse tracking enables (?1000h, ?1002h, ?1006h)
  • Off-screen cursor positioning when user is at bottom
  • Optional: scroll-region changes

Scope: Apply only when:

• Terminal type is agent/Claude terminal
• User is at bottom (not manually scrolled up)
• Terminal is not focused

Tests

• Integration test: capture known problematic sequences, verify filtering
• Unit test: ANSI parser correctly identifies mouse tracking and cursor positioning
• Regression test: ensure basic ANSI features (colors, bold) preserved
• Manual test: long Claude Code session with Codex MCP shows no bouncing

Documentation

• Add comment in TerminalInstanceService explaining sequence filtering rationale
• Document configuration option for stabilization (if feature-flagged)

Technical Specifications

Footprint:

• src/services/TerminalInstanceService.ts - Add sequence filtering layer
• New utility: ANSI sequence parser/filter
• Possible config flag: "Stabilize agent terminal scrolling"

Performance:

• Minimal overhead: regex-based sequence detection in data pipeline
• Only active for agent terminals in follow mode
• No impact on plain shell terminals or when user has scrolled up

Dependencies

Blocking:

• Need to capture raw session with script command to confirm exact sequences:

  script -q -f /tmp/claude-bounce.log -c "claude <codex command>"

Informational:

• Related to PR Fix: Restore clear command detection in terminals #919 scroll refactor (provides foundation for mitigation)
• xterm.js behavior with cursor positioning and mouse tracking modes

Tasks

• Record bouncing Claude session with script command to capture raw PTY output
• Extract and analyze escape sequences from captured session
• Identify exact sequences correlated with bounce start/stop and selection lock
• Design ANSI sequence filter for agent terminals (regex-based parser)
• Implement filtering layer in TerminalInstanceService.ts
• Add detection for "agent terminal in follow mode" state
• Strip mouse-tracking sequences (?1000h, ?1002h, ?1006h)
• Strip or neutralize off-screen cursor moves when user at bottom
• Add optional debug logging for filtered sequences
• Create integration test with known problematic sequences
• Test with long Claude Code + Codex MCP session
• Verify no regression in basic ANSI features (colors, bold, etc.)
• Consider feature flag for opt-in/out during testing phase
• Document filtering logic and rationale in code

Acceptance Criteria

• Viewport remains stable at bottom during Claude Code sessions with Codex MCP
• Text selection works normally throughout agent sessions
• No bouncing during intensive MCP operations
• Basic ANSI features (colors, bold, progress bars) still render correctly
• Plain shell terminals unaffected by changes
• User-initiated scroll-up still respected (filtering only applies in follow mode)
• Tests verify filtering behavior and prevent regression

Edge Cases & Risks

Edge cases:

• Ensure filtering doesn't break Claude's legitimate progress indicators
• Handle terminals where user explicitly wants TUI mode (e.g., htop, vim)
• Respect user scroll position: disable filtering when manually scrolled up
• Focused terminals: consider whether to apply filtering or trust user intent

Risks:

• Over-aggressive filtering may break useful Claude UI feedback
• Need precise sequence detection to avoid false positives
• Performance impact if filtering is applied to all output (mitigation: scope to agent terminals only)

Mitigation strategies:

• Feature flag for testing before wide rollout
• Scope filtering to specific terminal types and states
• Optional "plain mode" for users who prefer unfiltered output
• Logging/diagnostics to debug future sequence interactions

Additional Context

Alternative mitigation approaches considered:

1. Pinned-bottom re-scroll - Allow sequences through but force scroll-to-bottom after detection

   • Pro: Preserves Claude's logic
   • Con: May cause flicker, fights the application

2. Plain-mode option - User toggle for no-TUI mode

   • Pro: Opt-in workaround
   • Con: Requires CLI support or external sanitizer

3. Observability only - Add diagnostics without changing behavior

   • Pro: Non-invasive
   • Con: Doesn't solve the problem

Recommended approach: Escape sequence sanitization (option 1 in proposal) scoped to agent terminals in follow mode, with feature flag for testing.

Diagnostic script for sequence extraction:

import re
data = open("/tmp/claude-bounce.log", "rb").read()
for m in re.finditer(b"\x1b[^\x1b]*", data):
    seq = m.group()
    print(repr(seq))

Next steps after issue creation:

1. Capture bouncing session with script command
2. Run diagnostic script to extract sequences
3. Correlate sequences with bounce timing
4. Implement minimal filter targeting confirmed problematic sequences

[gregpriday]

Implementation Guide

This comment provides detailed implementation guidance and technical context for addressing the viewport bouncing issue.

---

Diagnostic Process

Step 1: Capture the problematic session

Record a Claude Code session where bouncing occurs:

script -q -f /tmp/claude-bounce.log -c "claude <command that triggers Codex MCP>"

Reproduce the bouncing behavior during this session, then exit.

Step 2: Extract escape sequences

Use this Python script to extract all ESC sequences from the captured log:

import re

data = open("/tmp/claude-bounce.log", "rb").read()
sequences = []

for m in re.finditer(b"\x1b[^\x1b]*", data):
    seq = m.group()
    sequences.append(seq)
    print(repr(seq))

print(f"\nTotal sequences: {len(sequences)}")

Step 3: Identify problematic patterns

Look for these sequence types and correlate with bouncing timing:

Mouse tracking modes:

• b'\x1b[?1000h' - Enable X10 mouse reporting
• b'\x1b[?1002h' - Enable cell motion mouse tracking
• b'\x1b[?1006h' - Enable SGR extended mouse mode
• Corresponding ...l sequences to disable

Cursor positioning:

• b'\x1b[<row>;<col>H' or b'\x1b[<row>;<col>f' - Absolute position
• b'\x1b[<n>A' - Cursor up n lines
• b'\x1b[<n>B' - Cursor down n lines
• b'\x1b7' / b'\x1b8' or b'\x1b[s' / b'\x1b[u' - Save/restore cursor

Scroll regions:

• b'\x1b[<top>;<bottom>r' - Set scrolling region

Alternate screen:

• b'\x1b[?1049h' / b'\x1b[?1049l' - Enter/exit alternate screen

---

Implementation Strategy

Filtering Layer Architecture

Add an ANSI sequence filter between the SAB pipeline and xterm in TerminalInstanceService:

PTY output → SAB buffer → Frame detection → [ANSI Filter] → xterm.js
                                                ↑
                                    Only for agent terminals
                                    in "follow mode"

Filter activation conditions:

function shouldFilterSequences(terminalId: string): boolean {
  const managed = managedTerminals.get(terminalId);
  if (!managed) return false;
  
  // Only filter agent/Claude terminals
  if (managed.type !== 'claude' && managed.type !== 'agent') {
    return false;
  }
  
  // Don't filter if user has manually scrolled up
  const buffer = managed.terminal.buffer.active;
  const isAtBottom = buffer.viewportY + managed.terminal.rows >= buffer.baseY + buffer.cursorY;
  if (!isAtBottom) return false;
  
  // Optional: don't filter focused terminals
  if (managed.isFocused) return false;
  
  return true;
}

Filter implementation (pseudocode):

function filterProblematicSequences(data: string, terminalId: string): string {
  if (!shouldFilterSequences(terminalId)) {
    return data; // Pass through unchanged
  }
  
  // Strip mouse tracking enables
  let filtered = data.replace(/\x1b\[\?1000h/g, '');
  filtered = filtered.replace(/\x1b\[\?1002h/g, '');
  filtered = filtered.replace(/\x1b\[\?1006h/g, '');
  
  // Strip off-screen cursor positioning
  // This is more complex - need to track current viewport position
  // Consider: only strip moves that would position cursor far above viewport
  
  // Optional: strip scroll region changes
  filtered = filtered.replace(/\x1b\[\d+;\d+r/g, '');
  
  return filtered;
}

Integration point in TerminalInstanceService:

In the SAB data processing pipeline, after frame detection but before writing to xterm:

private flushBuffer(id: string, force = false) {
  const managed = managedTerminals.get(id);
  if (!managed?.terminal) return;
  
  const data = /* ... accumulated buffer data ... */;
  
  // NEW: Filter problematic sequences for agent terminals
  const processedData = filterProblematicSequences(data, id);
  
  managed.terminal.write(processedData);
}

---

Alternative Approach: Pinned-Bottom Override

If filtering proves too invasive, consider a lighter-touch approach:

// Track viewport position before write
const viewportBefore = managed.terminal.buffer.active.viewportY;
const wasAtBottom = /* ... check if at bottom ... */;

managed.terminal.write(data);

// If we were at bottom and viewport jumped up, snap back
const viewportAfter = managed.terminal.buffer.active.viewportY;
if (wasAtBottom && viewportAfter < viewportBefore - 10) {
  // Significant upward jump detected
  requestAnimationFrame(() => {
    managed.terminal.scrollToBottom();
  });
}

Pros:

• Less invasive than filtering
• Preserves all sequence information

Cons:

• May cause visible flicker
• Fights the application's intent
• Doesn't solve selection lock (mouse tracking still enabled)

---

Testing Strategy

Unit tests:

describe('ANSI sequence filtering', () => {
  it('strips mouse tracking enables', () => {
    const input = 'Hello\x1b[?1000hWorld';
    const output = filterProblematicSequences(input, 'agent-terminal-id');
    expect(output).toBe('HelloWorld');
  });
  
  it('preserves color sequences', () => {
    const input = '\x1b[31mRed text\x1b[0m';
    const output = filterProblematicSequences(input, 'agent-terminal-id');
    expect(output).toBe(input); // Unchanged
  });
  
  it('passes through shell terminal data unchanged', () => {
    const input = 'Any\x1b[?1000hData';
    const output = filterProblematicSequences(input, 'shell-terminal-id');
    expect(output).toBe(input); // No filtering for shell terminals
  });
});

Integration tests:

it('prevents viewport bounce with problematic sequences', async () => {
  const terminal = await createAgentTerminal();
  
  // Simulate being at bottom
  terminal.scrollToBottom();
  const viewportBefore = terminal.buffer.active.viewportY;
  
  // Write sequence that would normally cause bounce
  await terminal.write('\x1b[?1000h\x1b[20;1H'); // Mouse mode + cursor up
  
  const viewportAfter = terminal.buffer.active.viewportY;
  expect(viewportAfter).toBe(viewportBefore); // No jump
});

Manual testing checklist:

• Long Claude Code session with multiple Codex MCP calls
• Verify viewport stays at bottom during intensive operations
• Text selection works throughout session
• Progress bars and status updates still render
• Color output preserved
• Plain shell terminal behavior unchanged
• Manually scrolling up disables filter (sequences pass through)

---

Configuration & Feature Flags

Consider adding a config option for users who want different behavior:

interface TerminalConfig {
  // ...
  stabilizeAgentScrolling?: boolean; // Default: true
  agentScrollingMode?: 'filter' | 'pin-bottom' | 'none'; // Default: 'filter'
}

This allows:

• Users experiencing issues to disable mitigation
• Testing different approaches without code changes
• Future expansion (e.g., per-agent filtering rules)

---

Observability & Debugging

Add optional debug logging for escape sequence filtering:

if (process.env.DEBUG_TERMINAL_SEQUENCES) {
  console.log(`[Terminal ${id}] Filtered sequences:`, {
    original: data,
    filtered: processedData,
    removed: extractRemovedSequences(data, processedData)
  });
}

Consider a diagnostic overlay in the UI:

// Show when mouse tracking is active
if (detectedMouseTracking) {
  showTemporaryIndicator('Mouse tracking detected');
}

// Show when cursor moves off-screen
if (cursorMovedOffScreen) {
  showTemporaryIndicator(`Cursor moved to line ${row} (off-screen)`);
}

---

Performance Considerations

Regex performance:

• Sequence filtering uses regex on every data chunk
• For agent terminals only (~10% of terminals in typical use)
• Only when at bottom (most common case, but skip when scrolled up)
• Data chunks typically small (few KB)

Benchmark target:

• Filtering should add < 1ms per chunk on average hardware
• If exceeds 5ms, consider optimizing (compiled regex, state machine parser)

Optimization if needed:

• Pre-compile all regex patterns
• Use state machine instead of regex for sequence detection
• Cache "should filter" decision per terminal

---

Migration & Rollout

Phase 1: Diagnostic (current issue)

• Capture sessions
• Identify exact sequences
• Document findings

Phase 2: Prototype

• Implement filtering behind feature flag
• Test with small group
• Gather feedback

Phase 3: Refinement

• Adjust filtering rules based on findings
• Optimize performance if needed
• Add configurability

Phase 4: Default enable

• Enable by default for new users
• Existing users opt-in via settings
• Monitor for issues

Phase 5: Always-on

• Remove feature flag
• Keep config option for edge cases

---

Related xterm.js Behavior

Understanding xterm viewport management:

When xterm receives cursor positioning sequences:

• If cursor moves to off-screen row, viewport auto-adjusts to make cursor visible
• This is correct behavior for full-screen apps (vim, less, etc.)
• But causes "bouncing" when Claude moves cursor for in-place updates while user expects scroll-to-bottom

Mouse tracking modes:

• ?1000h = Click tracking only
• ?1002h = Click + drag tracking
• ?1006h = SGR extended coordinates (supports large terminals)
• When active, xterm sends mouse events to program via stdin
• Selection is disabled because mouse events go to app, not terminal

Our approach:

• Don't change xterm behavior (it's correct per spec)
• Change what sequences reach xterm for agent terminals
• Preserve normal behavior for everything else

---

Success Metrics

After implementation, verify:

Functional:

• ✅ No viewport bouncing in 10 consecutive Claude + Codex sessions
• ✅ Text selection works throughout all sessions
• ✅ No user reports of broken progress indicators

Performance:

• ✅ Filtering adds < 1ms per chunk (p95)
• ✅ No measurable impact on shell terminal latency

Compatibility:

• ✅ All existing tests pass
• ✅ Plain shell terminals unaffected
• ✅ User-initiated scroll preserved

---

This guide should provide a clear path from diagnosis through implementation and testing. Adjust the filtering approach based on the actual sequences discovered in the diagnostic phase.

[gregpriday]

This was also an effort to fix the problem: #920

[gregpriday]

Renderer-side experimental mitigations (Canopy app)

I did a round of theoretical fixes on the renderer side (in the Canopy app) to better understand and potentially reduce the Claude Code terminal bouncing. This work lives on the branch bug/925-claude-code-intermittent in the Canopy UI repo and is not intended as a final solution yet.

What we tried

1. Claude-only escape sequence filtering in TerminalInstanceService (renderer)

   • Scoped to terminals with type === "claude".
   • Only applies when the terminal buffer is at the bottom ("follow mode").
   • Initial filter removed:
     • Mouse tracking enables: ESC[?1000h, ESC[?1002h, ESC[?1006h.
     • Scroll region changes: ESC[<top>;<bottom>r.
     • Alt-screen toggles: ESC[?1049h / ESC[?1049l.
   • Goal: reduce selection lock and prevent xterm from being driven into TUI-style modes for background Claude terminals, without touching normal shells.

2. Pinned-bottom viewport stabilization for Claude terminals

   • In the renderer write path, we capture viewportY before the write and whether the buffer was at bottom.
   • After writing, if a Claude terminal was at bottom and the viewport suddenly jumps up by more than ~10 lines, we call scrollToBottom() to snap it back.
   • This reduced the frequency of the obvious "jump to top and stay there" behavior but didn’t eliminate it, because xterm is still reacting to certain full-screen redraw sequences.

3. Debug instrumentation to inspect incoming escape sequences

   • Added a debug flag:
     • Enable: localStorage.setItem("canopyDebugTerminalSequences", "1") in the renderer devtools, then reload.
     • Disable: localStorage.removeItem("canopyDebugTerminalSequences").
   • When enabled, the renderer logs:
     • The sequences that were filtered out for Claude terminals.
     • The sequences present in any write that caused a significant viewport jump (from bottom up).

What we observed

From a real Claude Code session that still produced bouncing, the logged sequences for a viewport jump looked like:

• ESC[2J (clear entire screen)
• ESC[3J (clear scrollback)
• ESC[H (cursor home to row 1, col 1) followed by \r\n
• A sequence of colored drawing codes that render the Claude header/banner and status line.

In one case we saw:

• viewportBefore: 75
• viewportAfter: 0

which is exactly xterm doing the right thing per spec: Claude clears the entire screen, moves the cursor to the top, and redraws its UI; xterm then moves the viewport so that row 1 is visible, which looks like a jump to the top of the scrollback when there’s a lot of history.

This confirms that, beyond mouse tracking and scroll regions, a big part of the remaining bounce is Claude’s full-screen clear + home redraw pattern.

Aggressive experiment that we backed away from

To see how far we could push renderer-side mitigation, we tried an even more aggressive filter for Claude terminals at bottom:

• Stripped ESC[2J, ESC[3J, ESC[H, and ESC[1;1H in addition to the mouse/scroll-region/alt-screen sequences.
• This effectively prevented xterm from seeing the clear+home combo and did stop the jump-to-top behavior.
• However, it had nasty side effects:
  • The Claude UI header would redraw in odd places (e.g., re-rendering after resizes instead of behaving as a proper full-screen TUI).
  • The overall experience became glitchy and obviously incorrect for the Claude terminal.

Conclusion: stripping full-screen clear/home at the renderer is too invasive; it breaks legitimate TUI behavior, even when scoped to the Claude terminal type.

Where this leaves us

• The debug work strongly supports the original hypothesis:
  • Claude Code’s TUI emits a combination of:
    • Mouse tracking (?1000h, ?1002h, ?1006h).
    • Scroll-region changes (ESC[<top>;<bottom>r).
    • Alt-screen toggles (ESC[?1049h/l).
    • Full-screen clears and cursor-home (ESC[2J, ESC[3J, ESC[H).
  • xterm reacts correctly to these, but in the context of long scrollback + agent terminals this manifests as bouncing and selection lock.
• The mouse/scroll-region/alt-screen filtering for Claude terminals in follow mode, plus the pinned-bottom correction, does reduce the frequency and severity of bounces, but:
  • It cannot fully eliminate them as long as Claude is doing full-screen redraws.
  • Over-aggressive filtering of clear/home breaks Claude’s own UI.
• The behavior still occurs in VS Code, so anything we do in Canopy is intentionally trying to go beyond what VS Code’s integrated terminal currently does.

Potential future directions

• Keep the Claude-only filtering and pinned-bottom stabilization as an optional, experimental mode (behind a config flag) rather than always-on behavior.
• If Claude CLI ever exposes a "plain output" or "no full-screen TUI" mode, we should prefer that over renderer-side interception.
• Alternatively, coordinate with the Claude Code team so that their TUI is less reliant on full-screen clears / scroll-region gymnastics in long-running sessions.

For now, this branch documents what we tried and what we observed. It should be a useful reference if we revisit this issue or if upstream changes in Claude Code make a lighter-weight mitigation viable.

[gregpriday]

Update: escape sequences observed during bouncing

Quick note from recent debugging sessions to capture what we actually see on the wire when the terminal "bounces" during Claude Code sessions.

What we did

• Captured the PTY output feeding the terminal during a Claude Code + Codex MCP session where viewport bouncing was clearly visible.
• Logged the ANSI escape sequences present in the chunks that immediately preceded a jump from the bottom of the viewport to near the top of the scrollback.

What we saw

For a representative bounce event, the terminal state changed roughly like this:

• viewportBefore: 75
• viewportAfter: 0

and the associated escape sequences included (among many color/formatting codes):

• ESC[2J — clear entire screen
• ESC[3J — clear scrollback
• ESC[H — cursor home to row 1, column 1 (often followed by \r\n)
• A series of colored drawing sequences that render the Claude Code header/banner and status line

This is exactly the pattern of a full-screen redraw from the top: clear everything, move the cursor to the top-left, and repaint the UI.

Interpretation

• xterm.js is behaving correctly according to these sequences:
  • When it sees ESC[2J/ESC[3J plus ESC[H, it treats that as a request to clear and redraw from the top.
  • To keep the cursor and new content visible, it adjusts the viewport so row 1 is in view, which appears as a jump to the very top when the scrollback is large.
• This matches the observed behavior:
  • The terminal jumps up to what looks like the top of the session.
  • If you scroll back down to the bottom while these redraws are happening, the viewport tends to get yanked back up again because the app keeps clearing and homing.

Current understanding

• The remaining "bounce" is driven primarily by Claude Code’s full-screen clear + cursor-home redraw pattern, not by Canopy-specific scroll logic.
• Mouse tracking and scroll-region changes are also involved (they explain selection lock and some other quirks), but the big, sudden jumps correlate strongly with:
  • ESC[2J, ESC[3J, ESC[H/ESC[1;1H + header redraw.
• The same behavior is still visible in VS Code’s integrated terminal with Claude Code, which supports the idea that this is about the interaction between Claude’s TUI escape sequences and xterm.js, rather than anything unique to Canopy.

This comment is mainly a breadcrumb for future work: if we revisit this, we should treat these full-screen clear + home sequences as the primary driver of viewport jumps during long Claude Code sessions.

[gregpriday]

We made an attempt at fixing this issue with 4360bd6

[gregpriday]

Update: Resize Events as a Primary Trigger

After further testing, we've identified additional patterns that correlate strongly with viewport bouncing. The issue is less frequent in normal operation but becomes pronounced under specific conditions.

Key Findings

1. Resize Operations Trigger Bouncing

The most significant new observation: resizing terminals appears to be a primary trigger for the bouncing behavior. Specifically:

• With 4+ Claude Code terminals running stable (no bouncing), adding a 5th terminal triggers the grid layout resize
• This resize event propagates to all existing terminals via the ResizeObserver → handleResizeEntry → terminalInstanceService.resize() chain
• After the resize, multiple Claude terminals begin exhibiting aggressive viewport jumping
• When the 5th terminal is closed and the grid returns to the original layout, the bouncing subsides

This suggests that the resize operation—combined with Claude Code's TUI escape sequences—creates a pathological interaction where xterm.js re-evaluates cursor position relative to the new viewport dimensions, triggering the jump-to-top behavior.

2. Multi-Terminal Parallel MCP Operations

The bouncing is most pronounced when running parallel Codex MCP operations across multiple Claude terminals:

• Running 2+ Codex MCP reviews simultaneously fills the visible viewport with MCP status output
• Claude Code renders a progress spinner/indicator that updates in-place using cursor movement
• When the indicator updates but is scrolled out of the visible viewport (because another terminal's output pushed it up), Claude's cursor repositioning sequences cause xterm to "chase" the cursor
• This creates a feedback loop where multiple terminals are fighting for viewport attention

3. Occasional Terminal Stalls

During intensive Codex MCP sessions, terminals occasionally stop responding. This may be a separate issue, but it occurs in the same contexts where bouncing is most severe:

• Terminal output stops mid-operation
• No clear error in logs
• Unknown whether related to the escape sequence handling or a flow control issue

This requires further investigation but is noted here as it appears correlated with heavy MCP usage.

Technical Analysis

Looking at the current implementation in TerminalInstanceService.ts:

// Lines 1076-1156: resize() method
resize(id: string, width: number, height: number, options: { immediate?: boolean } = {}) {
  // ...
  // Capture scroll state before resize
  const buffer = managed.terminal.buffer.active;
  const wasAtBottom = buffer.baseY - buffer.viewportY < 1;
  // ...
}

The resize logic already attempts to preserve scroll position, but the problem may occur at a lower level:

1. terminal.resize(cols, rows) triggers xterm's internal layout recalculation
2. If Claude has set a scroll region or cursor position, xterm may interpret the resize in unexpected ways
3. The resetFrameBuffersForTerminal() call clears pending frames, but buffered escape sequences may have already been partially processed

The parser handlers we added (lines 909-996) block mouse tracking and some cursor movements, but they may not cover all the sequences Claude emits during its TUI updates—particularly sequences that are valid in the context of a resize event.

Hypotheses

1. Resize + Pending Escape Sequences: When a resize occurs while Claude is mid-TUI-update, the pending escape sequences (cursor position, clear screen) are interpreted relative to the new dimensions, causing unexpected viewport jumps.

2. Frame Buffer Race Condition: The resetFrameBuffersForTerminal() call during resize may race with incoming data from the SAB polling loop, causing stale cursor-positioning sequences to be flushed at the wrong moment.

3. Codex MCP Output Volume: The sheer volume of output during parallel MCP operations may overwhelm the frame coalescing logic, causing more frequent flushes and more opportunities for escape sequence misinterpretation.

Potential Investigation Paths

1. Resize-Aware Sequence Filtering: Extend the parser handlers to be more aggressive during/after resize events—perhaps blocking all cursor repositioning for a brief settling period after a resize.

2. xterm.js Configuration: Investigate whether xterm.js exposes options to control viewport behavior during resize events. Relevant options might include:

   • scrollOnResize (if available)
   • Custom viewport management via the buffer API
   • Disabling cursor tracking temporarily

3. Deferred Resize for Agent Terminals: For Claude/agent terminals specifically, consider deferring the actual terminal.resize() call until a TUI quiet period is detected (no cursor movement sequences in the last N ms).

4. SAB Flush Coordination: Ensure the SAB polling loop respects resize boundaries—perhaps by inserting a "resize boundary" marker that causes pending frames to be discarded rather than flushed.

Current State

The issue is:

• Less frequent than before the parser handler mitigations
• More predictable in its triggers (resize events, parallel MCP operations)
• Still intermittent and difficult to reproduce reliably
• Present in VS Code as well, confirming this is Claude CLI + xterm.js interaction, not Canopy-specific

The multi-terminal scenario (6 terminals, 2 running parallel Codex MCPs) is currently the most reliable reproduction path.

Next Steps

1. Add instrumentation to log resize events alongside escape sequence detection to correlate timing
2. Investigate xterm.js viewport/buffer API for more direct control during resize
3. Consider a "resize settling" mode for agent terminals that temporarily suppresses TUI escape sequences
4. Profile the SAB polling loop under heavy MCP load to identify any bottlenecks or race conditions

[gregpriday]

This appears to be the most promising solution: #965

[gregpriday]

Resolved by #966