Repository navigation
Fix terminal flickering — raw ANSI escape codes bypass Ink render system #254
Description
Problem
Users report terminal flickering when using Copilot CLI + Squad (Discussion #170). After audit, this is a Squad code issue, not a Copilot CLI platform problem.
Squad writes raw ANSI escape codes directly to process.stdout while Ink (React-based terminal UI) expects exclusive terminal access. This corrupts Ink's internal screen state and forces costly re-renders.
Findings
Critical (direct flicker causes)
| Location | Code | Impact |
|---|---|---|
shell/index.ts:1142 |
\x1b[2J\x1b[3J\x1b[H |
Full screen + scrollback clear BEFORE Ink renders = visible blackout on every squad shell start |
shell/index.ts:1131 |
\x1b[2J\x1b[3J\x1b[H |
Same clear on /resume while Ink is actively rendering |
commands/rc.ts:290 |
\r... rapid writes |
Carriage returns bypass Ink's render buffer |
Compounding factors
| Location | Issue |
|---|---|
useAnimation.ts:33 |
67ms typewriter interval (15fps) + multiple independent setInterval() timers = 60-120 uncoordinated re-renders/sec |
commands.ts:110 |
/clear writes ANSI directly, bypassing Ink |
Multiple *.tsx components |
Independent animation timers not synchronized with each other or Ink's render cycle |
Fix Approach
- Remove direct ANSI writes — replace
process.stdout.write('\x1b[...')with Ink-native clearing (clearOutput()or state reset) - Coordinate animation timers — consolidate intervals, use Ink's
useInput/useStdouthooks instead of rawsetInterval - Reduce typewriter FPS — 67ms (15fps) is aggressive. 200ms (5fps) would reduce render pressure significantly
- Gate screen clears — only clear when Ink is NOT actively rendering, or use Ink's built-in clear
References
- Discussion: Terminal Flickering #170 (Terminal Flickering)
- Reporters: @Gareth064, @diberry
Activity
github-actions commentedon Mar 7, 2026
📋 Assigned to Fenster (Core Dev)
Issue: #254 — Fix terminal flickering — raw ANSI escape codes bypass Ink render system
Fenster will pick this up in the next Copilot session.
bradygaster commentedon Mar 7, 2026
✅ Fix in progress on branch squad/254-fix-terminal-flicker.
Root cause: raw ANSI escape codes (\x1b[2J\x1b[3J\x1b[H) written directly to process.stdout while Ink expected exclusive terminal access, causing render state corruption.
What was fixed:
Tests: 26 regression tests in test/flicker-fix.test.ts (22 passing, 4 skipped pending integration). Validates FRAME_MS throttling, ANSI removal, NO_COLOR handling.
Community reporters @Gareth064 and @diberry — thank you for surfacing this (Discussion #170). Your feedback drove the fix.
— Fenster 🔧 & Hockney 🧪
feat: add OTel foundation — provider init, telemetry bridge, deps (gi…
docs(ai-team): Merge OTel observability Phase 1 logs and decisions
feat: Ink shell, runtime stubs, OTel Phases 1-3 (github#254-264)
Merge pull request #405 from bradygaster/squad/254-flicker-fix-to-dev