feat(tui): implement TUI settings screen with configuration panels #9317

Open
opened 2026-04-14 14:43:25 +00:00 by HAL9000 · 1 comment
Owner

Metadata

  • Branch: feat/tui-settings-screen
  • Commit message: feat(tui): implement TUI settings screen with configuration panels
  • Milestone: v3.7.0

Background and Context

The CleverAgents TUI (built on Textual >= 1.0, per ADR-044) requires a dedicated settings screen to allow users to configure the application without leaving the terminal interface. Currently, all configuration must be done by manually editing the YAML config file, which is error-prone and inaccessible to non-technical users.

The settings screen is a core component of the v3.7.0 TUI milestone (M8: TUI Implementation), explicitly listed in the milestone scope as "Settings screen, session management screen." It provides a full-screen overlay with four configuration panels — General, Appearance, Providers, and Shortcuts — that map directly to the underlying config file structure. Changes are persisted immediately to disk, ensuring the TUI always reflects the current configuration state.

This feature is accessible via the /settings slash command (using the existing / command input mode) or the Ctrl+, keyboard shortcut, consistent with common IDE conventions. The overlay is dismissed with Escape, returning the user to their previous context without disrupting active sessions.


Expected Behavior

  • Pressing Ctrl+, or typing /settings opens a full-screen settings overlay on top of the current TUI screen.
  • The overlay displays four tabbed or sectioned panels: General, Appearance, Providers, and Shortcuts.
  • General panel exposes:
    • default_format — dropdown (e.g., markdown, plain, json)
    • default_namespace — text input
    • auto_save_interval — numeric spinner (seconds)
  • Appearance panel exposes:
    • theme — dropdown (default: dracula; options include all bundled Textual themes)
    • font_size — numeric spinner
    • sidebar_width — numeric spinner (columns)
  • Providers panel exposes:
    • Per-provider API key fields (masked with *, reveal-on-focus toggle)
    • Per-provider model selection dropdown
  • Shortcuts panel exposes:
    • A table of action → key binding pairs, each editable inline
  • All changes are written immediately to the config file on field change (no explicit "Save" button required).
  • Pressing Escape dismisses the overlay and returns focus to the underlying screen.
  • The settings screen respects the active Dracula theme and all Textual CSS styling conventions.

Acceptance Criteria

  • Ctrl+, keyboard binding opens the settings overlay from any screen state (MainScreen, session active, sidebar open/closed).
  • /settings slash command opens the same settings overlay via the command input system.
  • The overlay is full-screen and renders above all other widgets without disrupting underlying session state.
  • General panel renders and correctly reads/writes default_format, default_namespace, and auto_save_interval from/to the config file.
  • Appearance panel renders and correctly reads/writes theme, font_size, and sidebar_width; changing theme applies the new theme immediately without requiring a restart.
  • Providers panel renders API key fields masked by default; keys are revealed only when the field has focus or a reveal toggle is activated; model selection dropdowns are populated from the provider's available models.
  • Shortcuts panel renders all configurable key bindings in an editable table; changes are validated for conflicts before being written.
  • All field changes are persisted to the config file immediately (no explicit save action required).
  • Pressing Escape dismisses the overlay; the underlying screen state (cursor position, active session, sidebar state) is fully restored.
  • The settings screen is styled consistently with the Dracula theme and passes Textual snapshot tests.
  • Unit tests cover config read/write for all four panels with >= 97% coverage.
  • Widget tests cover overlay open/close, field interaction, and immediate persistence.
  • No regressions in existing TUI tests (nox -s tests).

Subtasks

  • Design & scaffold — Create src/cleveragents/tui/screens/settings.py with SettingsScreen as a Textual Screen subclass; register it in app.py.
  • Keyboard binding — Add Ctrl+, binding in MainScreen (and any other top-level screens) that calls self.push_screen(SettingsScreen()).
  • Slash command integration — Register /settings in the command registry so the / input mode dispatches to SettingsScreen.
  • Config adapter layer — Implement SettingsAdapter in src/cleveragents/tui/settings_adapter.py that reads from and writes to the YAML config file; wrap with debounce to avoid excessive disk writes.
  • General panel widget — Implement GeneralPanel widget with default_format dropdown, default_namespace text input, and auto_save_interval spinner; wire to SettingsAdapter.
  • Appearance panel widget — Implement AppearancePanel widget with theme dropdown (populated from textual.themes), font_size spinner, and sidebar_width spinner; apply theme change reactively via app.theme.
  • Providers panel widget — Implement ProvidersPanel widget with masked API key inputs (per-provider), reveal toggle, and model selection dropdowns populated from provider metadata; wire to SettingsAdapter.
  • Shortcuts panel widget — Implement ShortcutsPanel widget with an editable DataTable of action → key binding pairs; validate for conflicts on edit; wire to SettingsAdapter.
  • Escape dismissal — Implement on_key handler for Escape that calls self.app.pop_screen() and restores underlying screen focus.
  • Textual CSS — Write settings.tcss with Dracula-themed styles for the overlay, panel tabs, form fields, and masked inputs.
  • Snapshot tests — Add Textual snapshot tests for the settings overlay in all four panel states.
  • Unit tests — Add unit tests for SettingsAdapter covering read, write, debounce, and conflict validation logic.
  • Integration tests — Add integration tests verifying that config file changes are reflected in the TUI after settings are modified.

Definition of Done

The issue is closed when:

  1. SettingsScreen is implemented and accessible via both Ctrl+, and /settings.
  2. All four configuration panels (General, Appearance, Providers, Shortcuts) are functional and persist changes immediately to the config file.
  3. The Escape key correctly dismisses the overlay without disrupting underlying session state.
  4. All acceptance criteria checkboxes above are checked.
  5. nox -s tests passes with >= 97% test coverage including the new settings screen tests.
  6. A Textual snapshot test exists for each panel state and passes in CI.
  7. The PR has been reviewed and merged to the feat/tui-settings-screen branch target.

Automated by CleverAgents Bot
Agent: new-issue-creator

## Metadata - **Branch**: `feat/tui-settings-screen` - **Commit message**: `feat(tui): implement TUI settings screen with configuration panels` - **Milestone**: v3.7.0 --- ## Background and Context The CleverAgents TUI (built on Textual >= 1.0, per ADR-044) requires a dedicated settings screen to allow users to configure the application without leaving the terminal interface. Currently, all configuration must be done by manually editing the YAML config file, which is error-prone and inaccessible to non-technical users. The settings screen is a core component of the v3.7.0 TUI milestone (M8: TUI Implementation), explicitly listed in the milestone scope as "Settings screen, session management screen." It provides a full-screen overlay with four configuration panels — General, Appearance, Providers, and Shortcuts — that map directly to the underlying config file structure. Changes are persisted immediately to disk, ensuring the TUI always reflects the current configuration state. This feature is accessible via the `/settings` slash command (using the existing `/` command input mode) or the `Ctrl+,` keyboard shortcut, consistent with common IDE conventions. The overlay is dismissed with `Escape`, returning the user to their previous context without disrupting active sessions. --- ## Expected Behavior - Pressing `Ctrl+,` or typing `/settings` opens a full-screen settings overlay on top of the current TUI screen. - The overlay displays four tabbed or sectioned panels: **General**, **Appearance**, **Providers**, and **Shortcuts**. - **General panel** exposes: - `default_format` — dropdown (e.g., `markdown`, `plain`, `json`) - `default_namespace` — text input - `auto_save_interval` — numeric spinner (seconds) - **Appearance panel** exposes: - `theme` — dropdown (default: `dracula`; options include all bundled Textual themes) - `font_size` — numeric spinner - `sidebar_width` — numeric spinner (columns) - **Providers panel** exposes: - Per-provider API key fields (masked with `*`, reveal-on-focus toggle) - Per-provider model selection dropdown - **Shortcuts panel** exposes: - A table of action → key binding pairs, each editable inline - All changes are written immediately to the config file on field change (no explicit "Save" button required). - Pressing `Escape` dismisses the overlay and returns focus to the underlying screen. - The settings screen respects the active Dracula theme and all Textual CSS styling conventions. --- ## Acceptance Criteria - [ ] `Ctrl+,` keyboard binding opens the settings overlay from any screen state (MainScreen, session active, sidebar open/closed). - [ ] `/settings` slash command opens the same settings overlay via the command input system. - [ ] The overlay is full-screen and renders above all other widgets without disrupting underlying session state. - [ ] **General panel** renders and correctly reads/writes `default_format`, `default_namespace`, and `auto_save_interval` from/to the config file. - [ ] **Appearance panel** renders and correctly reads/writes `theme`, `font_size`, and `sidebar_width`; changing `theme` applies the new theme immediately without requiring a restart. - [ ] **Providers panel** renders API key fields masked by default; keys are revealed only when the field has focus or a reveal toggle is activated; model selection dropdowns are populated from the provider's available models. - [ ] **Shortcuts panel** renders all configurable key bindings in an editable table; changes are validated for conflicts before being written. - [ ] All field changes are persisted to the config file immediately (no explicit save action required). - [ ] Pressing `Escape` dismisses the overlay; the underlying screen state (cursor position, active session, sidebar state) is fully restored. - [ ] The settings screen is styled consistently with the Dracula theme and passes Textual snapshot tests. - [ ] Unit tests cover config read/write for all four panels with >= 97% coverage. - [ ] Widget tests cover overlay open/close, field interaction, and immediate persistence. - [ ] No regressions in existing TUI tests (`nox -s tests`). --- ## Subtasks - [ ] **Design & scaffold** — Create `src/cleveragents/tui/screens/settings.py` with `SettingsScreen` as a Textual `Screen` subclass; register it in `app.py`. - [ ] **Keyboard binding** — Add `Ctrl+,` binding in `MainScreen` (and any other top-level screens) that calls `self.push_screen(SettingsScreen())`. - [ ] **Slash command integration** — Register `/settings` in the command registry so the `/` input mode dispatches to `SettingsScreen`. - [ ] **Config adapter layer** — Implement `SettingsAdapter` in `src/cleveragents/tui/settings_adapter.py` that reads from and writes to the YAML config file; wrap with debounce to avoid excessive disk writes. - [ ] **General panel widget** — Implement `GeneralPanel` widget with `default_format` dropdown, `default_namespace` text input, and `auto_save_interval` spinner; wire to `SettingsAdapter`. - [ ] **Appearance panel widget** — Implement `AppearancePanel` widget with `theme` dropdown (populated from `textual.themes`), `font_size` spinner, and `sidebar_width` spinner; apply theme change reactively via `app.theme`. - [ ] **Providers panel widget** — Implement `ProvidersPanel` widget with masked API key inputs (per-provider), reveal toggle, and model selection dropdowns populated from provider metadata; wire to `SettingsAdapter`. - [ ] **Shortcuts panel widget** — Implement `ShortcutsPanel` widget with an editable `DataTable` of action → key binding pairs; validate for conflicts on edit; wire to `SettingsAdapter`. - [ ] **Escape dismissal** — Implement `on_key` handler for `Escape` that calls `self.app.pop_screen()` and restores underlying screen focus. - [ ] **Textual CSS** — Write `settings.tcss` with Dracula-themed styles for the overlay, panel tabs, form fields, and masked inputs. - [ ] **Snapshot tests** — Add Textual snapshot tests for the settings overlay in all four panel states. - [ ] **Unit tests** — Add unit tests for `SettingsAdapter` covering read, write, debounce, and conflict validation logic. - [ ] **Integration tests** — Add integration tests verifying that config file changes are reflected in the TUI after settings are modified. --- ## Definition of Done The issue is closed when: 1. `SettingsScreen` is implemented and accessible via both `Ctrl+,` and `/settings`. 2. All four configuration panels (General, Appearance, Providers, Shortcuts) are functional and persist changes immediately to the config file. 3. The Escape key correctly dismisses the overlay without disrupting underlying session state. 4. All acceptance criteria checkboxes above are checked. 5. `nox -s tests` passes with >= 97% test coverage including the new settings screen tests. 6. A Textual snapshot test exists for each panel state and passes in CI. 7. The PR has been reviewed and merged to the `feat/tui-settings-screen` branch target. --- **Automated by CleverAgents Bot** Agent: new-issue-creator
HAL9000 added this to the v3.7.0 milestone 2026-04-14 14:45:09 +00:00
Author
Owner

Triage: Verified [AUTO-OWNR-1]

Valid feature: The TUI settings screen is explicitly listed in the v3.7.0 milestone scope: "Settings screen, session management screen." This issue provides a comprehensive specification for the SettingsScreen with four configuration panels (General, Appearance, Providers, Shortcuts), keyboard binding (Ctrl+,), slash command integration (/settings), and immediate config persistence.

Assigning to v3.7.0 (TUI Implementation) as this is explicitly in the milestone scope. Priority High — core TUI deliverable.

MoSCoW: Must Have — the settings screen is explicitly required by the v3.7.0 milestone scope.


Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner-pool-supervisor

✅ **Triage: Verified** [AUTO-OWNR-1] Valid feature: The TUI settings screen is explicitly listed in the v3.7.0 milestone scope: "Settings screen, session management screen." This issue provides a comprehensive specification for the `SettingsScreen` with four configuration panels (General, Appearance, Providers, Shortcuts), keyboard binding (`Ctrl+,`), slash command integration (`/settings`), and immediate config persistence. Assigning to **v3.7.0** (TUI Implementation) as this is explicitly in the milestone scope. Priority **High** — core TUI deliverable. MoSCoW: **Must Have** — the settings screen is explicitly required by the v3.7.0 milestone scope. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
cleveragents/cleveragents-core#9317
No description provided.