True Input

True-Input Driver

The orchestrator routed you here. Use these mechanics to execute your plan.

Drive a real terminal emulator, injecting keystrokes through the platform's native HID input path. This proves exactly what bytes the terminal emits -- no synthetic injection, no PTY distortion.

When to use

• Proving that a terminal really sends the sequence you expect (e.g., Ghostty's Shift+Enter)
• Recording demos that reflect actual terminal rendering
• Validating that Droid handles a keystroke correctly end-to-end in a specific terminal

If you don't need real terminal proof, use tuistory -- it's faster and more deterministic.

Platform support

Read the platform file for your target OS. Each contains prerequisites, core pattern, command reference, encoding reference, recording, troubleshooting, and recovery -- specific to that platform.

Key differences from tuistory

Known dead ends

• Xvfb + xdotool: bypasses real keyboard processing entirely
• uinput + Xvfb: Xvfb does not consume kernel input devices
• SSH for TUI testing: PTY layer distorts input encoding; use SSH only for deployment
• Raw `asciinema rec`: true-input records via wf-recorder (Wayland screen capture), not asciinema. Use tctl --record or tctl record start/stop. Calling asciinema rec directly has no access to the compositor and produces nothing useful.

True-Input: Linux / Wayland

Prerequisites

sudo apt-get install -y cage wtype          # required
sudo apt-get install -y grim wf-recorder    # optional: screenshots / video
ls /dev/dri/                                # must be non-empty

At least one Wayland terminal: ghostty, kitty, or alacritty.

Architecture

tctl launches a headless Wayland compositor (cage) with an isolated per-session runtime directory, opens a real terminal emulator inside it, injects keystrokes via wtype, and monitors the PTY log stream via script. All socket/runtime management is handled by tctl.

Core pattern

TCTL=${DROID_PLUGIN_ROOT}/bin/tctl

$TCTL launch "droid-dev" -s proof --backend true-input --cols 120 --rows 36
$TCTL -s proof wait ">" --timeout 15000
$TCTL -s proof type "hello"
$TCTL -s proof press shift enter
$TCTL -s proof snapshot --trim
$TCTL -s proof screenshot -o /tmp/proof.png
$TCTL -s proof close

Auto-detection order: ghostty > kitty > alacritty. Force a specific terminal:

$TCTL launch "droid-dev" -s proof --backend ghostty

Command reference (via tctl)

Recording

Recording can start and stop independently of the session:

$TCTL -s proof record start /tmp/proof.mp4
# ... interact ...
$TCTL -s proof record stop

Or record from launch via --record:

$TCTL launch "droid-dev" -s proof --backend true-input --record /tmp/proof.mp4

Terminal encoding reference

Ghostty

Falls back to xterm modifyOtherKeys (Kitty keyboard protocol disabled due to arrow-key issues):

Kitty

CSI-u protocol by default:

VS Code / Cursor / Windsurf

Integrated terminals need explicit keybinding setup. Droid's helper writes workbench.action.terminal.sendSequence bindings that emit \\\r\n for Shift+Enter.

tmux

tmux may rewrite sequences when relaying. With extended keys enabled, Shift+Enter typically appears as \x1b[27;2;13~ regardless of the inner terminal's native encoding.

Recovery

$TCTL -s proof press esc
$TCTL -s proof snapshot --trim
$TCTL -s proof close

True-Input: macOS via QEMU Monitor

Drive a macOS VM's terminal through QEMU HMP sendkey -- keystrokes enter the VM's virtual USB keyboard, hitting macOS's HID subsystem the same way a physical keyboard would. No host compositor leakage, no SSH PTY distortion.

Architecture

mac-ctl.sh type / press
        |
        v
  socat → QEMU monitor socket → sendkey → QEMU virtual USB keyboard (HID)
        |
        v
  macOS HID subsystem → Terminal.app / iTerm2 / Ghostty

Prerequisites

Host packages: qemu-system-x86_64 (or aarch64), socat, ffmpeg or ImageMagick (for PNG conversion). VM: QEMU macOS guest with UEFI, user-mode networking with SSH port forward. The VM must be started with MONITOR_SOCKET env var pointing to a unix socket so mac-ctl.sh can connect.

Required env vars:

export DROID_MAC_MONITOR="<path-to-qemu-monitor-socket>"  # QEMU monitor unix socket
export DROID_MAC_SSH_HOST="<ssh-config-host-alias>"        # SSH config host alias

Optional env vars:

export DROID_MAC_BOOT_SCRIPT="<path-to-qemu-boot-script>"  # for `up` command
export DROID_MAC_SHOT_DIR="/tmp"

Core pattern

MACCTL=${DROID_PLUGIN_ROOT}/scripts/macos/mac-ctl.sh

$MACCTL up                                       # start VM (needs DROID_MAC_BOOT_SCRIPT)
$MACCTL wait-boot 120                            # poll SSH until ready
$MACCTL terminal                                 # open Terminal.app via Spotlight
sleep 3
$MACCTL type "echo hello world"
$MACCTL press enter
sleep 2
$MACCTL shot /tmp/result.png                     # screendump via QEMU monitor → PNG

Command reference (via mac-ctl.sh)

macOS-specific keys

cmd / command maps to meta_l (the macOS Command key). Chords work as expected:

$MACCTL press cmd c           # Copy
$MACCTL press cmd shift 3     # Screenshot (macOS native)
$MACCTL press cmd space       # Spotlight
$MACCTL press cmd q           # Quit foreground app

Key differences from other platforms

Recording

Poll-based recording via screendump:

MACREC=${DROID_PLUGIN_ROOT}/scripts/macos/mac-record.sh

$MACREC start /tmp/demo.mp4 5    # 5 fps
# ... interact with mac-ctl.sh ...
$MACREC stop                      # encodes PPM frames to MP4

Troubleshooting

Recovery

MACCTL=${DROID_PLUGIN_ROOT}/scripts/macos/mac-ctl.sh
$MACCTL press esc
$MACCTL shot /tmp/state.png
$MACCTL kill                     # hard-kill QEMU process
$MACCTL up                       # cold restart

Future: native macOS (no VM)

For bare-metal Macs (not VMs), the QEMU monitor approach isn't available. Potential paths:

• Wawona (native macOS Wayland compositor) + wtype + waypipe -- would reuse Linux plumbing
• AppleScript / Accessibility API injection into Terminal.app / iTerm2
• cliclick for mouse/keyboard automation

These are not yet implemented. Use this QEMU approach for VM-based macOS testing.

True-Input: Windows via KVM/QEMU

Drive a Windows VM's console through virsh send-key -- keystrokes enter the VM's virtual HID device, hitting the Windows Console Subsystem the same way a physical keyboard would. No host compositor leakage, no SSH PTY distortion.

Architecture

vm-ctl.sh type / press
        |
        v
  virsh send-key ──> QEMU virtual keyboard (HID)
        |
        v
  Windows Console Subsystem ──> PowerShell / TUI app

Prerequisites

Host packages: qemu-full, libvirt, virt-manager, swtpm, dnsmasq. VM: KVM/QEMU with UEFI + TPM 2.0, SPICE display, NAT networking, SSH enabled.

Required env vars:

export DROID_VM_NAME="<libvirt-domain-name>"        # libvirt domain name
export DROID_VM_SSH_KEY="<path-to-ssh-private-key>"  # SSH key for deployment
export DROID_VM_SSH_USER="<ssh-username>"             # SSH user in the VM

Core pattern

VMCTL=${DROID_PLUGIN_ROOT}/scripts/windows/vm-ctl.sh

$VMCTL up                                    # start the VM
sleep 15                                     # wait for boot
$VMCTL login                                 # dismiss lock screen
sleep 5
$VMCTL pwsh                                  # open PowerShell via Start menu
sleep 4
$VMCTL type "Get-Process | Select-Object -First 5"
$VMCTL press enter
sleep 2
$VMCTL shot /tmp/result.png                  # screenshot via virsh

Command reference (via vm-ctl.sh)

Key differences from Linux true-input

Recording

Poll-based recording via virsh screenshot:

VMREC=${DROID_PLUGIN_ROOT}/scripts/windows/vm-record.sh

$VMREC start /tmp/demo.mp4 5    # 5 fps
# ... interact with vm-ctl.sh ...
$VMREC stop                      # encodes to MP4

Terminal encoding reference

VT mode (ENABLE_VIRTUAL_TERMINAL_INPUT)

Modifier codes: 2=Shift, 3=Alt, 5=Ctrl, 6=Shift+Ctrl

Win32 console API (ReadKey / ReadConsoleInput)

Lossless. Preserves VirtualKeyCode + exact modifier state (left/right Ctrl/Alt/Shift). Shift+Enter is VKey=13 + ShiftPressed (distinct from plain Enter). Use win-key-dumper.ps1 for this level of detail.

Troubleshooting

Recovery

VMCTL=${DROID_PLUGIN_ROOT}/scripts/windows/vm-ctl.sh
$VMCTL press esc
$VMCTL shot /tmp/state.png
$VMCTL restore <snapshot>    # hard reset to known state