feat: configurable key bindings with webtty key command#23
Merged
Conversation
added 10 commits
March 29, 2026 09:35
- Deleted ADR 019: Config — Keyboard sequence compatibility in nested terminal chains, and created a new ADR 019 with updated content. - Updated references in client and config specifications to point to the new ADR 019. - Revised keyboard specification to reflect the changes in recommended sequences for Shift+Enter, emphasizing the use of legacy encoding. - Introduced ADR 018: Client — Configurable keyboard bindings, detailing the new keyboard binding system and its configuration. - Adjusted compatibility matrix and decision sections to clarify the implications of using KKP versus legacy encoding in nested terminal environments.
- Removed ADR 019: Config — Keyboard sequence compatibility in nested terminal chains and replaced it with ADR 019: Config — Keyboard sequence compatibility in nested terminal chains. - Updated references in the documentation to reflect the new ADR structure. - Introduced a new ADR 018: Client — Configurable keyboard bindings to define a flexible key binding system for TUI applications. - Added support for configurable keyboard bindings in the client, allowing users to define custom key-to-sequence mappings. - Enhanced the `bytesToDisplay` function to provide a clearer representation of received byte sequences. - Updated the `webtty chars` command to display both the received byte representation and the corresponding `chars` value. - Adjusted the configuration documentation to recommend legacy encoding for Shift+Enter and similar key combinations in nested terminal setups.
…mand - Introduced `keyboardBindings` in `~/.config/webtty/config.json` to allow users to define custom key mappings for terminal applications. - Added support for legacy encoding and Kitty Keyboard Protocol (KKP) for key sequences. - Implemented `webtty key` command to capture key combos and display their corresponding `chars` values in JSON format. - Updated documentation to reflect the new key binding features and usage examples. - Added ADRs 018, 019, and 020 to detail the design decisions and compatibility considerations for key bindings.
…n for Shift+Enter
Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
There was a problem hiding this comment.
Pull request overview
Adds end-user support and documentation for configurable keyboard bindings, including a new CLI helper to capture and format key sequences as JSON chars values suitable for keyboardBindings.
Changes:
- Add
webtty keyCLI command and supporting byte-formatting utilities. - Add unit tests for the new formatter helpers and the non-TTY error path.
- Add/adjust specs + ADRs for key bindings (schema, encoding guidance, and the new CLI command) and update related docs.
Reviewed changes
Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| src/cli/index.ts | Wires the new key subcommand into CLI help + dispatch. |
| src/cli/commands.ts | Implements cmdKey() and exports bytesToDisplay/bytesToChars helpers. |
| src/cli/commands.test.ts | Adds tests for display/JSON formatting and non-TTY behavior. |
| docs/specs/webtty.md | Removes Author metadata line. |
| docs/specs/key-bindings.md | New spec describing keyboardBindings, encodings, and webtty key. |
| docs/specs/config.md | Updates config spec to reference key-bindings spec; updates examples. |
| docs/specs/client.md | Updates client spec references to key-bindings spec / ADR. |
| docs/specs/cli.md | Removes Author metadata line. |
| docs/skills/create-live-spec/assets/spec-template.md | Removes Author field from spec template. |
| docs/awesome-web.md | Adds multiplexer section and updates Zellij entry. |
| docs/adrs/020.cli.key.md | New ADR for the webtty key command. |
| docs/adrs/019.key-bindings.sequence-compat.md | New ADR on legacy vs KKP in nested terminal chains. |
| docs/adrs/018.key-bindings.config-support.md | Updates ADR 018 framing + recommendation to legacy encoding. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 14 out of 14 changed files in this pull request and generated 3 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
…stry pollution Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
…er tests Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
…terminal cleanup on exit/signals, defensive return after process.exit Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
keyboardBindingsconfig support — capture-phasekeydownhandler intercepts modifier+key combos and sends configuredcharsto PTY (ADR 018)webtty keyCLI command — raw mode capture tool that prints the JSONcharsvalue for any key combo pressed, ready to copy-paste into config (ADR 020)What's included
Implementation
keyboardBindingsarray in~/.config/webtty/config.jsonwithkey,mods,charsfieldswebtty keycommand:bytesToDisplay+bytesToCharspure functions, 50ms idle timeout for multi-byte sequences,qto quit, ANSI styled outputbytesToDisplay,bytesToChars, non-TTY error path)Docs
docs/specs/key-bindings.md— new standalone spec: binding schema, legacy vs KKP encoding, porting from Alacritty/Ghostty/VS Code/Windows Terminal/iTerm2, binding examples table with use casesdocs/adrs/018.key-bindings.config-support.md— config schema, design rationale, terminal ecosystem surveydocs/adrs/019.key-bindings.sequence-compat.md— terminal chain architecture problem, why KKP fails in nested terminals, legacy encoding recommendationdocs/adrs/020.cli.key.md—webtty keycommand decisiondocs/awesome-web.md— new Multiplexer section (vim, Zellij, tmux, psmux, GNU Screen); updated Zellij entry for v0.44.0 Windows + web support