ModelSelectorScreen

Key bindings for model navigation, selection, defaulting, and cancel.

Arrows move the cursor, Page Up/Down jump by a visual page, Tab copies the highlighted spec into the filter input, Enter selects, Ctrl+S toggles the screen's stored default (which preference that is comes from its DefaultModelScope; inert when the screen has none), Ctrl+R toggles between showing all installed models and the hand-curated "recommended" subset, Ctrl+N toggles rows between friendly display names and raw provider:model specs (the analog of the /theme picker's n key), and Esc dismisses. All bindings use priority=True so they take precedence over the embedded Input; vim-style j/k bindings — and a bare n mirroring the /theme picker — are deliberately omitted because they would prevent typing those letters into the always-focused filter input, which is why the names toggle is bound to ctrl+n instead.

Styling for the modal shell, filter input, provider-grouped list, detail footer, and help text.

Compose the screen layout.

Set up the screen on mount.

Loads model data in a background thread so the screen frame renders immediately, then populates the model list.

Refit the model list when terminal dimensions change.

Filter models as user types.

Handle Enter key when filter input is focused.

Handle click on a model option.

Move selection up.

Move selection down.

Replace search text with the currently selected model spec.

Move selection up by one visible page.

Move selection down by one visible page.

Select the current model.

Return whether model_spec is the preference stored by this screen.

Toggle the highlighted model as the screen's stored default.

If the highlighted model is already stored, clears it. Otherwise stores it. Which preference is written — and how the footer names it — comes from the screen's DefaultModelScope, so the /auto classifier picker cannot silently retarget the main agent model. A screen constructed with default_scope=None has nothing to write and returns early.

Rows whose provider integration is missing are refused rather than persisted: unlike the session-only Enter path (which offers to install the package), a stored spec that can never build would degrade every future launch with no prompt at the moment of the keypress. The refusal applies only to storing — when the highlighted row is already the stored spec, Ctrl+S must still clear it, since the clear path is the only in-app way to drop a persisted value whose provider integration was later removed.

Write failures leave their notice in place instead of scheduling a restore timer, and (when the screen is running) raise a toast naming the remedy — a 3-second footer flash is not enough to read, let alone act on. The install refusal is a different class: the user fixes it by moving the cursor to an installed row, so it restores on the usual timer rather than pinning the footer for the life of the modal.

Toggle between the full model list and the recommended subset.

Disabled while in _curated (onboarding) mode — that screen is already constrained to the recommended subset and the user should finish or skip onboarding rather than browse the full list. Preserves the highlighted model when it survives the toggle and falls back to the current/default/first model otherwise.

Toggle rows between friendly display names and raw model specs.

Mirrors the /theme picker's label/key toggle: pressing Ctrl+N flips every visible row between its human-readable name (e.g. Claude Sonnet 5) and the canonical provider:model spec (e.g. anthropic:claude-sonnet-5) so the user can read or copy the exact id without leaving the picker. Relabels the mounted rows in place — the toggle changes neither ordering nor selection, so a full rebuild is unnecessary — and stays available in curated/onboarding mode since it only affects presentation.

In standard mode the footer hint is rewritten so it advertises the mode the next press switches to; curated mode omits the hint entirely, so the refresh is a no-op there.

The refresh is skipped while a Ctrl+S error notice is on the footer, since that notice is the only signal a save failed and the user may not have read it yet. Successful Ctrl+S messages are clobbered freely, and their pending restore timer is stopped rather than left to fire: the refresh already rendered the hint this timer would render, and an untracked timer is one _fail could not cancel.

Cancel the selection.