UAT: TUI missing 14 spec-required keyboard shortcuts — only 3 of 17 global hotkeys implemented in `BINDINGS` #3663

New issue

Open

opened 2026-04-05 21:14:15 +00:00 by freemo · 0 comments

freemo commented

2026-04-05 21:14:15 +00:00

Owner

Metadata

Branch: bugfix/tui-missing-keyboard-shortcuts
Commit Message: fix(tui): implement all 17 spec-required global hotkey bindings in CleverAgentsTuiApp
Milestone: (none — backlog)
Parent Epic: #868

Backlog note: This issue was discovered during autonomous operation
on milestone v3.7.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

Background and Context

The CleverAgents TUI is built on Textual and is required to be a keyboard-first interface. The spec (Hotkey Reference section) defines 17 global hotkeys that must be registered in CleverAgentsTuiApp.BINDINGS. Currently only 3 are implemented, and one of those (ctrl+t for "Cycle Preset") is not in the spec at all — the spec requires ctrl+tab for that action.

Current Behavior

CleverAgentsTuiApp.BINDINGS in src/cleveragents/tui/app.py (lines 92–95) defines only 3 bindings:

BINDINGS = [
    ("ctrl+q", "quit", "Quit"),
    ("f1", "help", "Help"),
    ("ctrl+t", "cycle_preset", "Cycle Preset"),
]

ctrl+t is used for "Cycle Preset" but the spec requires ctrl+tab for this action; ctrl+t is not in the spec.
14 spec-required hotkeys are entirely absent.

Expected Behavior

Per the spec Hotkey Reference, the following global hotkeys must be registered and functional:

Hotkey	Action
`ctrl+q`	Quit TUI (saves session state)
`ctrl+c`	Interrupt actor / double-tap to quit (5 s window)
`F1`	Toggle help panel
`F2` / `ctrl+,`	Open settings
`ctrl+s`	Open Sessions screen
`ctrl+n`	Create new session tab
`ctrl+w`	Close current session tab
`ctrl+[`	Switch to previous session tab
`ctrl+]`	Switch to next session tab
`shift+tab`	Cycle sidebar: hidden → visible → fullscreen
`escape`	Close current overlay/modal/sidebar toward main screen
`tab`	Cycle persona (MainScreen prompt)
`ctrl+tab`	Cycle preset (MainScreen prompt)
`shift+enter`	Multi-line mode (MainScreen prompt)
`alt+up` / `alt+down`	Block cursor navigation (MainScreen prompt)
`ctrl+b`	Focus sidebar
`ctrl+r`	Resume saved session
`1`–`9`	Jump to session tab by number

Impact

Users cannot use keyboard shortcuts to navigate sessions, toggle the sidebar, interrupt actors, open the sessions screen, or navigate conversation blocks. The TUI is not keyboard-first as required by the spec.

Code Location

src/cleveragents/tui/app.py, CleverAgentsTuiApp.BINDINGS class variable (lines 92–95).

Subtasks

Write failing Behave scenarios covering each of the 17 spec-required hotkeys (TDD — Type/Testing issue first per CONTRIBUTING.md)
Remove non-spec binding ctrl+t → cycle_preset
Add ctrl+tab → cycle_preset (replaces ctrl+t)
Add ctrl+c → interrupt_or_quit with double-tap / 5 s window logic
Add F2 / ctrl+, → open_settings
Add ctrl+s → open_sessions
Add ctrl+n → new_session_tab
Add ctrl+w → close_session_tab
Add ctrl+[ → prev_session_tab
Add ctrl+] → next_session_tab
Add shift+tab → cycle_sidebar
Add escape → close_overlay
Add tab → cycle_persona (scoped to MainScreen prompt)
Add shift+enter → multiline_mode (scoped to MainScreen prompt)
Add alt+up / alt+down → block_cursor_up / block_cursor_down
Add ctrl+b → focus_sidebar
Add ctrl+r → resume_session
Add 1–9 → jump_to_tab (dynamic bindings)
Verify all new bindings appear in the F1 help panel
Run nox (all default sessions), fix any errors
Verify coverage >=97% via nox -s coverage_report

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
All nox stages pass.
Coverage >= 97%.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-uat-tester

## Metadata - **Branch**: `bugfix/tui-missing-keyboard-shortcuts` - **Commit Message**: `fix(tui): implement all 17 spec-required global hotkey bindings in CleverAgentsTuiApp` - **Milestone**: *(none — backlog)* - **Parent Epic**: #868 > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.7.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. ## Background and Context The CleverAgents TUI is built on Textual and is required to be a keyboard-first interface. The spec (Hotkey Reference section) defines 17 global hotkeys that must be registered in `CleverAgentsTuiApp.BINDINGS`. Currently only 3 are implemented, and one of those (`ctrl+t` for "Cycle Preset") is not in the spec at all — the spec requires `ctrl+tab` for that action. ## Current Behavior `CleverAgentsTuiApp.BINDINGS` in `src/cleveragents/tui/app.py` (lines 92–95) defines only 3 bindings: ```python BINDINGS = [ ("ctrl+q", "quit", "Quit"), ("f1", "help", "Help"), ("ctrl+t", "cycle_preset", "Cycle Preset"), ] ``` - `ctrl+t` is used for "Cycle Preset" but the spec requires `ctrl+tab` for this action; `ctrl+t` is not in the spec. - 14 spec-required hotkeys are entirely absent. ## Expected Behavior Per the spec Hotkey Reference, the following global hotkeys must be registered and functional: | Hotkey | Action | |---|---| | `ctrl+q` | Quit TUI (saves session state) | | `ctrl+c` | Interrupt actor / double-tap to quit (5 s window) | | `F1` | Toggle help panel | | `F2` / `ctrl+,` | Open settings | | `ctrl+s` | Open Sessions screen | | `ctrl+n` | Create new session tab | | `ctrl+w` | Close current session tab | | `ctrl+[` | Switch to previous session tab | | `ctrl+]` | Switch to next session tab | | `shift+tab` | Cycle sidebar: hidden → visible → fullscreen | | `escape` | Close current overlay/modal/sidebar toward main screen | | `tab` | Cycle persona (MainScreen prompt) | | `ctrl+tab` | Cycle preset (MainScreen prompt) | | `shift+enter` | Multi-line mode (MainScreen prompt) | | `alt+up` / `alt+down` | Block cursor navigation (MainScreen prompt) | | `ctrl+b` | Focus sidebar | | `ctrl+r` | Resume saved session | | `1`–`9` | Jump to session tab by number | ## Impact Users cannot use keyboard shortcuts to navigate sessions, toggle the sidebar, interrupt actors, open the sessions screen, or navigate conversation blocks. The TUI is not keyboard-first as required by the spec. ## Code Location `src/cleveragents/tui/app.py`, `CleverAgentsTuiApp.BINDINGS` class variable (lines 92–95). ## Subtasks - [ ] Write failing Behave scenarios covering each of the 17 spec-required hotkeys (TDD — `Type/Testing` issue first per CONTRIBUTING.md) - [ ] Remove non-spec binding `ctrl+t` → `cycle_preset` - [ ] Add `ctrl+tab` → `cycle_preset` (replaces `ctrl+t`) - [ ] Add `ctrl+c` → `interrupt_or_quit` with double-tap / 5 s window logic - [ ] Add `F2` / `ctrl+,` → `open_settings` - [ ] Add `ctrl+s` → `open_sessions` - [ ] Add `ctrl+n` → `new_session_tab` - [ ] Add `ctrl+w` → `close_session_tab` - [ ] Add `ctrl+[` → `prev_session_tab` - [ ] Add `ctrl+]` → `next_session_tab` - [ ] Add `shift+tab` → `cycle_sidebar` - [ ] Add `escape` → `close_overlay` - [ ] Add `tab` → `cycle_persona` (scoped to MainScreen prompt) - [ ] Add `shift+enter` → `multiline_mode` (scoped to MainScreen prompt) - [ ] Add `alt+up` / `alt+down` → `block_cursor_up` / `block_cursor_down` - [ ] Add `ctrl+b` → `focus_sidebar` - [ ] Add `ctrl+r` → `resume_session` - [ ] Add `1`–`9` → `jump_to_tab` (dynamic bindings) - [ ] Verify all new bindings appear in the F1 help panel - [ ] Run `nox` (all default sessions), fix any errors - [ ] Verify coverage >=97% via `nox -s coverage_report` ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. - All nox stages pass. - Coverage >= 97%. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester

freemo added a new dependency

2026-04-05 21:14:22 +00:00

#868 Epic: TUI Interface, Modals and Persona System

freemo added this to the v3.7.0 milestone

2026-04-05 21:19:01 +00:00

freemo referenced this issue

2026-04-05 21:19:12 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3572

freemo referenced this issue

2026-04-05 21:23:18 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377

freemo referenced this issue