Clear commands no longer trigger terminal screen clear

[gregpriday]

Summary

Terminal clear commands (/clear, /new, /reset, clear, cls) no longer clear the terminal screen. This is a regression caused by the InputTracker service being disconnected during architecture migration.

Current Behavior

When typing clear commands like /clear or clear in terminals (including Claude Code agent terminals):

• The command is entered and executed
• Terminal screen does not clear visually
• The InputTracker class exists in src/services/clearCommandDetection.ts but is unused
• Current TerminalPane uses naive commandBufferRef that only tracks last command for display

Expected Behavior

Clear commands should:

• Be detected before execution
• Trigger visual terminal clearing using VT100 escape sequences
• Clear both viewport and scrollback buffer
• Work consistently across all terminal types (interactive, Claude, Gemini, Codex)

Root Cause

The InputTracker class in src/services/clearCommandDetection.ts contains proper logic for:

• Detecting clear commands from the CLEAR_COMMANDS set
• Handling backspace, escape sequences, and bracketed paste
• Processing character-by-character input

However, TerminalPane.tsx (lines 162-193) implements a simplified buffer that:

• Only accumulates characters for last command display
• Does not check against CLEAR_COMMANDS
• Does not trigger terminal clearing action

Evidence

Affected Files:

• src/services/clearCommandDetection.ts - Unused InputTracker service
• src/components/Terminal/TerminalPane.tsx - Current naive input handler

Current Implementation (TerminalPane.tsx:164-193):

const handleInput = useCallback(
  (data: string) => {
    let buffer = commandBufferRef.current;

    for (let i = 0; i < data.length; i++) {
      const ch = data[i];

      if (ch === "\r" || ch === "\n") {
        const trimmed = buffer.trim();
        if (trimmed) {
          updateLastCommand(id, trimmed);
        }
        buffer = "";
        continue;
      }

      if (ch === "\x7f" || ch === "\b") {
        buffer = buffer.slice(0, -1);
        continue;
      }

      if (ch >= " " && ch !== "\x7f") {
        buffer += ch;
      }
    }

    commandBufferRef.current = buffer;
  },
  [id, updateLastCommand]
);

Deliverables

Code Changes

1. Enhance InputTracker API (src/services/clearCommandDetection.ts)

• Modify process() to return an InputResult object instead of boolean
• Add interface with isClear and command properties
• Support both clear detection and command tracking in one service
• Add reset() method for terminal restart cleanup

2. Wire InputTracker into TerminalPane (src/components/Terminal/TerminalPane.tsx)

• Replace commandBufferRef with InputTracker instance (line 162)
• Update handleInput to use tracker and handle clear commands
• When clear detected, call terminalInstanceService.get(id).terminal.clear()
• Update last command from tracker result
• Call tracker reset on terminal restart (in handleRestart)

Tests

• Verify /clear, clear, cls trigger screen clear
• Test backspace handling doesn't break clear detection
• Verify paste and escape sequences work correctly
• Test last command display still functions

Documentation

• No documentation changes needed (internal fix)

Technical Specifications

Footprint: Terminal input handling layer

• src/services/clearCommandDetection.ts - Enhance return type
• src/components/Terminal/TerminalPane.tsx - Wire up tracker

Dependencies: Existing xterm.js terminal.clear() API

Dependencies

None - standalone fix

Tasks

• Update InputTracker.process() to return InputResult object with isClear and command properties
• Add InputResult interface to export in clearCommandDetection.ts
• Add reset() method to InputTracker for cleanup
• Import InputTracker in TerminalPane.tsx
• Replace commandBufferRef with inputTrackerRef using InputTracker instance (line 162)
• Update handleInput to process with tracker and handle clear commands
• Call terminal.clear() via terminalInstanceService when clear detected
• Update updateLastCommand from tracker result
• Call inputTrackerRef.current?.reset() in handleRestart
• Test clear commands work in all terminal types
• Verify last command display still functions

Acceptance Criteria

• Typing /clear in Claude Code terminal clears screen
• Standard clear and cls commands work in interactive terminals
• Clear detection handles backspace/editing correctly
• Last command pill still displays user commands
• No regressions in terminal input handling
• Clear works consistently across terminal restart

Edge Cases & Risks

• Bracketed paste: InputTracker already handles ESC[200~/ESC[201~ sequences
• Arrow keys/navigation: Tracker resets buffer on escape sequences to avoid false positives
• Control characters: Ctrl+C, Ctrl+D properly reset buffer
• Terminal restart: Ensure tracker state is cleaned up
• Scrollback clearing: Verify VT100_FULL_CLEAR sequences are still available if needed beyond basic .clear()

[gregpriday]

Implementation Guide

This guide provides detailed code changes to reconnect the InputTracker service and restore clear command functionality.

Step 1: Enhance InputTracker API

Update src/services/clearCommandDetection.ts to return full command state:

// Commands that trigger visual terminal clear (AI agents + standard shell)
export const CLEAR_COMMANDS = new Set(["/clear", "/new", "/reset", "clear", "cls"]);

// VT100 escape sequences for terminal clearing (optimized order for compatibility)
export const VT100_CLEAR_SCROLLBACK = "\x1b[3J"; // Clear scrollback buffer first
export const VT100_CURSOR_HOME = "\x1b[H"; // Move cursor to (1,1)
export const VT100_CLEAR_SCREEN = "\x1b[2J"; // Clear entire screen
export const VT100_FULL_CLEAR = `${VT100_CLEAR_SCROLLBACK}${VT100_CURSOR_HOME}${VT100_CLEAR_SCREEN}`;

export interface InputResult {
  isClear: boolean;
  command: string | null;
}

/**
 * Tracks user input keystrokes to detect clear commands before Enter.
 * Handles multi-char chunks (paste), backspace, control characters, and escape sequences.
 */
export class InputTracker {
  private buffer = "";
  private inBracketedPaste = false;

  /**
   * Process input data chunk.
   * Returns result object if Enter was pressed, otherwise null.
   */
  process(data: string): InputResult | null {
    let result: InputResult | null = null;

    for (let i = 0; i < data.length; i++) {
      const char = data[i];
      const code = char.charCodeAt(0);

      // Handle bracketed paste start: ESC[200~
      if (char === "\x1b" && data.substring(i, i + 6) === "\x1b[200~") {
        this.inBracketedPaste = true;
        i += 5;
        continue;
      }

      // Handle bracketed paste end: ESC[201~
      if (char === "\x1b" && data.substring(i, i + 6) === "\x1b[201~") {
        this.inBracketedPaste = false;
        i += 5;
        continue;
      }

      // Handle Enter (CR or LF) - processing point
      if (char === "\r" || char === "\n") {
        const cmd = this.buffer.trim();
        this.buffer = "";
        this.inBracketedPaste = false;
        
        result = {
          isClear: CLEAR_COMMANDS.has(cmd),
          command: cmd || null
        };
        continue;
      }

      // Handle Backspace (DEL - 0x7f)
      if (char === "\x7f" || char === "\b") {
        this.buffer = this.buffer.slice(0, -1);
        continue;
      }

      // Handle escape sequences (arrows, home/end) -> Reset buffer
      // We don't try to parse these complex edits, just reset to avoid false positives
      if (char === "\x1b" && !this.inBracketedPaste) {
        this.buffer = "";
        continue;
      }

      // Handle other control characters (Ctrl+C, Ctrl+D, etc) -> Reset buffer
      if (code < 32) {
        this.buffer = "";
        continue;
      }

      // Accumulate printable characters
      this.buffer += char;
    }

    return result;
  }

  reset(): void {
    this.buffer = "";
    this.inBracketedPaste = false;
  }
}

Key changes:

• Return InputResult | null instead of boolean
• Return object on Enter with isClear flag and command string
• Add reset() method for cleanup
• Handle backspace as both \x7f and \b for compatibility

Step 2: Wire InputTracker into TerminalPane

Update the import section to include InputTracker:

import { terminalInstanceService } from "@/services/TerminalInstanceService";
import { InputTracker } from "@/services/clearCommandDetection";

Replace the commandBufferRef and handleInput implementation (around line 162):

// Replace this:
const commandBufferRef = useRef<string>("");

const handleInput = useCallback(
  (data: string) => {
    let buffer = commandBufferRef.current;
    // ... old logic
  },
  [id, updateLastCommand]
);

// With this:
const inputTrackerRef = useRef<InputTracker | null>(null);

if (!inputTrackerRef.current) {
  inputTrackerRef.current = new InputTracker();
}

const handleInput = useCallback(
  (data: string) => {
    const tracker = inputTrackerRef.current;
    if (!tracker) return;

    const result = tracker.process(data);

    if (result) {
      // Handle Clear Command
      if (result.isClear) {
        const managed = terminalInstanceService.get(id);
        if (managed?.terminal) {
          managed.terminal.clear();
          // Optionally clear scrollback via addon or internal API if needed
          // but .clear() handles the viewport which is usually sufficient
        }
      }

      // Handle Last Command Update
      if (result.command) {
        updateLastCommand(id, result.command);
      }
    }
  },
  [id, updateLastCommand]
);

Update handleRestart to clean up tracker state (around line 235):

const handleRestart = useCallback(() => {
  restartTerminal(id);
  inputTrackerRef.current?.reset();
}, [restartTerminal, id]);

Implementation Notes

Why this approach:

• Reuses existing robust InputTracker logic that handles edge cases
• Unifies command detection and last-command tracking in one place
• Maintains separation of concerns (service handles parsing, component handles actions)
• No changes needed to xterm.js layer or IPC

Testing strategy:

1. Test basic clear commands: /clear, clear, cls in different terminal types
2. Test with backspace/editing: type clea, backspace, type clear - should work
3. Test paste: paste clear command - should work
4. Test false positives: type clearance - should NOT clear
5. Test escape sequences: use arrow keys while typing - should reset gracefully
6. Test terminal restart: verify no stale state

Alternative: Full VT100 clear
If basic .clear() doesn't clear scrollback as desired, you can inject VT100 sequences:

if (result.isClear) {
  const managed = terminalInstanceService.get(id);
  if (managed?.terminal) {
    // Clear scrollback + screen
    managed.terminal.write(VT100_FULL_CLEAR);
  }
}

The VT100 constants are already defined in clearCommandDetection.ts for this purpose.

[gregpriday]

Fixed via manual merge of PR #919