About input-handling
A skill for developers implementing input in terminal UIs, covering keyboard, mouse, paste, and focus handling. It emphasizes reliable raw-mode recovery, deliberate keybinding design, and treating pasted content as data rather than commands.
Key features
- 01Interactive and non-interactive input rules
- 02Raw-mode recovery requirements
- 03Keybinding design guidance
- 04Focus management requirements
- 05Safe paste and mouse event handling
Use cases
- 01Design discoverable shortcuts for a terminal UI
- 02Restore terminal state when an app exits
- 03Treat pasted text as data instead of keystrokes
- 04Validate mouse positions after a resize
Install
Copy the command and run it in a terminal.
npx skills add https:/After installing, type/input-handlingin Claude Code to confirm it loaded.
Bundled filesreferences/input-protocols.mdreferences/keybinding-design.md
Details
From the project READMETUI Input Handling, Raw Mode, Keyboard, Mouse, Paste, and Focus
Use this skill when a TUI reads keys, handles shortcuts, supports mouse, edits text, manages focus, or needs safe paste behavior.
Input contract
- Only enter raw or cbreak mode for interactive TTY sessions.
- Provide non-interactive alternatives for scripts, pipes, and CI.
- Keep input decoding separate from application actions.
- Make every action reachable by keyboard.
- Treat mouse support as optional progressive enhancement.
- Preserve expected terminal shortcuts unless the user can rebind them.
Raw mode rules
Raw mode disables line discipline and changes signal behavior. Centralize it and restore it reliably. Verify behavior for Ctrl-C, Ctrl-Z/suspend where supported, EOF, resize, terminal close, and fatal exceptions. Passwords and tokens must not echo.
Keybinding design
Good keybindings are discoverable, consistent, and conflict-aware.
- Always provide visible help for common actions.
- Use
q, Esc, or Ctrl-C for quit/cancel only when consistent with workflow risk. - Confirm destructive actions; require stronger confirmation for irreversible work.
- Avoid stealing common terminal, shell, editor, and multiplexer shortcuts unless configurable.
- Support both mnemonic shortcuts and navigational keys where possible.
- Distinguish global shortcuts from focused-widget shortcuts.
Focus model
Every interactive element needs:
- A stable identity.
- Focus eligibility rules.
- A visible focus indicator that does not rely on color alone.
- Tab/Shift-Tab or arrow navigation when appropriate.
- Clear behavior for disabled, hidden, modal, and nested controls.
- Mouse click behavior that updates focus before activating actions.
Paste and mouse safety
Enable bracketed paste for shells, editors, command palettes, and multiline inputs. Parse paste start/end markers and treat pasted text as data, not a sequence of commands. For mouse input, validate coordinates against the current layout and ignore stale events after resize.
Failure modes
| Symptom | Likely cause | Fix |
|---|---|---|
| Esc feels delayed | parser waiting to distinguish Alt prefix | tune timeout or use framework protocol support |
| Ctrl-C does not exit | raw mode swallowed signal | map Ctrl-C explicitly and restore terminal |
| Paste triggers actions | no bracketed paste or paste treated as keystrokes | enable paste protocol and route as text |
| Mouse clicks wrong row | stale layout after resize or scroll | validate coordinates against current viewport |
| Focus disappears | no focused fallback after removing widget | compute next eligible focus target |
Reference files
references/input-protocols.md- Keyboard, mouse, paste, focus, and resize event details.references/keybinding-design.md- Shortcut design, conflict avoidance, and forms/editors.