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 the tuistory backend in terminal-use -- it's faster and more deterministic.
Platform support
| Platform | Status | Driver | Read |
|---|---|---|---|
| Linux / Wayland | Implemented | cage + wtype + any Wayland terminal | platforms/linux.md |
| macOS (QEMU) | Implemented | QEMU monitor sendkey to a macOS VM | platforms/macos.md |
| Windows (KVM) | Implemented | virsh send-key to a KVM/QEMU VM | platforms/windows.md |
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
| Concern | tuistory | true-input |
|---|---|---|
| Snapshot source | Virtual screen buffer | Scrubbed PTY log (Linux) or screenshot (VM platforms) |
| Wait mechanism | Event-driven (screen redraws) | Log polling (Linux) or sleep-based (VMs) |
| Recording | Must wrap launch (--record) | Can start/stop any time |
| Keyboard encoding | Synthetic (bypasses terminal) | Real terminal encoding path |
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 viawf-recorder(Wayland screen capture), not asciinema. Usetctl --recordortctl record start/stop. Callingasciinema recdirectly has no access to the compositor and produces nothing useful.