helm: Instructions file for Claude Code

Helm

Mission

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.

Scope of this file: orientation and the invariants that constrain code anywhere in the repo. It is deliberately NOT a feature catalogue — per-feature behaviour lives in docs/. When you add a feature, document it there and link it from the table; do not grow this file.

System Overview

graph TB
    XC[Gamepad<br/>Xbox USB/BT · Generic/DirectInput]

    subgraph "Electron App"
        subgraph "Renderer Process"
            UI[UI: Sessions / Settings<br/>Vue 3 + Pinia]
            BGA[Browser Gamepad API]
            TV[TerminalManager → xterm.js]
        end

        subgraph "Main Process"
            IPC[IPC Handlers<br/>domain files + orchestrator]
            SM[SessionManager<br/>EventEmitter]
            PTY[PtyManager<br/>node-pty]
            SD[StateDetector<br/>activity + AIAGENT-* keywords]
            CL[ConfigLoader<br/>Profile YAML]
            FEAT[Feature managers<br/>Plans · Drafts · Artifacts · …]
        end

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

    XC --> BGA
    IPC --> SM & PTY & CL & FEAT
    PTY --> SD

Every feature manager follows the same shape: an EventEmitter class in src/session/, an injected persist sink writing YAML/JSON under the user config dir, IPC channels exposed through the preload bridge, and a renderer composable owning the reactive mirror. Match that shape when adding one.

Data Flow

Gamepad → Browser Gamepad API (renderer polling, 16ms)
  → IPC gamepad:event → debounce (250ms)
    → Resolve binding (the CLI type's binding profile)
      → Execute action (keyboard/voice/spawn/switch/context-menu)

D-pad / left stick navigates sessions and auto-selects the terminal.
Keyboard input routes to the active terminal (PTY stdin), blocked while a
selection-mode modal overlay is visible.