helm copilot-instructions.md

gamepad-cli-hub — Copilot Instructions

Project Purpose

DIY Xbox controller → CLI session manager. Control multiple AI coding CLIs (Claude Code, Copilot CLI, etc.) from a single game controller. Embedded terminals via node-pty + xterm.js — no external windows. Built as an Electron 41 desktop app on Windows.

---

System Overview

graph TB
    subgraph Hardware
        XC[Xbox Controller<br/>USB/Bluetooth]
    end

    subgraph "Electron App"
        subgraph "Renderer Process"
            UI[UI: Sessions / Settings]
            BGA[Browser Gamepad API]
            TM[TerminalManager<br/>Tab bar + switching]
            TV[TerminalView<br/>xterm.js]
        end

        subgraph "Main Process"
            IPC[IPC Handlers<br/>10 handler groups]
            SM[SessionManager<br/>EventEmitter]
            SP[SessionPersistence<br/>YAML save/load]
            PS[ProcessSpawner]
            PTY[PtyManager<br/>node-pty spawn/write/resize]
            SD[StateDetector<br/>AIAGENT-* keywords]
            PQ[PipelineQueue<br/>Auto-handoff]
            IP[InitialPrompt<br/>Sequence → PTY]
            CL[ConfigLoader<br/>Profile YAML]
        end

        UI <-->|contextBridge| IPC
        BGA -->|button events| UI
        TM --> TV
        TV <-->|pty:data / pty:write| PTY
    end

    XC --> BGA
    IPC --> SM
    IPC --> SP
    IPC --> PS
    IPC --> PTY
    IPC --> CL
    SM --> SP
    PS --> PTY
    PTY --> SD
    SD --> PQ
    PTY --> IP

Data Flow Pipeline

flowchart LR
    A[Xbox Controller] --> B[Browser Gamepad API<br/>renderer polling]
    B --> C[250ms debounce + repeat engine]
    C --> D{Binding Resolution}
    D -->|per-CLI type| E[Execute Action]
    E --> F[keyboard → SequenceParser → PTY stdin<br/>voice → OS-default robotjs, PTY when target: 'terminal'<br/>spawn → PtyManager<br/>switch → SessionManager → TerminalManager<br/>scroll → terminal buffer scroll<br/>context-menu → overlay modal]

Detailed flow:

1. Browser Gamepad API polls at 16ms in the renderer process
2. Button presses debounced at 250ms; D-pad and sticks auto-repeat when held (400ms initial delay, 120ms rate for D-pad; displacement-proportional for sticks)
3. Emits button events to subscribers; analog sticks emit virtual button events
4. Binding resolution: check CLI-specific bindings
5. Execute resolved action (keyboard sequence → PTY stdin, voice → OS-default robotjs or PTY when target: 'terminal', spawn → PTY, session-switch, scroll, etc.)
6. Voice bindings: default to OS (robotjs). If active terminal exists and target === 'terminal' → convert key to escape sequence via keyToPtyEscape() → ptyWrite(). Otherwise → robotjs. Hold mode sends escape sequence once (PTY has no key-up).
7. Analog sticks: explicit binding found → execute action; no binding → fall back to stick mode (left=cursor arrows via PTY, right=configurable per-CLI bindings, default: scroll)
8. D-pad / left stick navigates sessions and auto-selects the terminal
9. Keyboard input always routes to the active terminal (PTY stdin)
10. Ctrl+V paste: document-level interceptor reads clipboard text → writes to active PTY via ptyWrite() regardless of DOM focus