claudewheel v0.24.2 /claudewheel.app
Updated Edit
On this page

App class -- TUI event loop for claudewheel.

#claudewheel.app

#claudewheel.app

TUI event loop, keyboard dispatch, and segment interaction.

#KeyContext

Ephemeral snapshot of state relevant to key dispatch decisions.

#Binding

A single keybinding entry in the registry.

#App

TUI application managing the event loop, keyboard handling, and segment interaction.

#_refresh_orphan_findings

python
def _refresh_orphan_findings(self) -> None

Recompute orphan-token findings and the persistent status notice.

Read-only audit of the token store. A corrupt tokens.json (surfaced as a FAILED health check elsewhere) must not crash the TUI, so its :class:TokenStoreError is swallowed here into an empty finding set.

#run_tui

python
def run_tui(self) -> dict[str, str | None] | None

Enter the TUI loop. Returns selections on launch, None on quit.

#_select_client

python
def _select_client(self) -> bool

Run the Client selection step and drop claude-only segments.

Explicit --client wins and skips the picker (see :func:claudewheel.clients.resolve_client); otherwise the picker fans out the :data:~claudewheel.clients.CLIENT_ADAPTERS registry with the configured default pre-focused. Returns False when the user cancels the picker (Esc/Ctrl-C) so the caller quits cleanly; True otherwise.

When the resolved client is not claude, the version segment is removed from the bar: it selects a claudewheel-managed claude binary, so it is inapplicable to any other client and is skipped entirely.

#_promote_ephemeral

python
def _promote_ephemeral(self) -> None

Promote ephemeral selections to pinned on disk before launch.

#_run_slow_discovery_thread

python
def _run_slow_discovery_thread(self) -> None

Background thread: run slow discovery and store results.

#_apply_slow_discovery

python
def _apply_slow_discovery(self) -> None

Merge slow discovery results into the live segment bar.

Results for the focused segment are deferred to avoid disrupting the user's current interaction. Unfocused segments are updated immediately.

Known limitation: while results are buffered, evaluate_requires() uses the focused segment's pre-discovery options for cross-segment constraint checks. Constraint-based dimming may be briefly stale until defocus.

#_apply_pending_for_segment

python
def _apply_pending_for_segment(self, seg: Segment) -> None

Apply any deferred discovery results for seg and clear pending state.

#_defocus

python
def _defocus(self) -> None

Run deferred-apply housekeeping on the segment about to lose focus.

#_build_context

python
def _build_context(self) -> KeyContext

Build an ephemeral KeyContext from current app state.

#_compute_hints

python
def _compute_hints(self) -> list[str]

Compute visible hint labels from the binding registry for the current state.

#_handle_key

python
def _handle_key(self, key: str) -> str | None

Process a keypress via the binding registry.

#_h_main_left

python
def _h_main_left(self, key: str) -> str | None

Handle left arrow: defocus current segment and move focus left.

#_h_main_right

python
def _h_main_right(self, key: str) -> str | None

Handle right arrow: defocus current segment and move focus right.

#_h_main_up

python
def _h_main_up(self, key: str) -> str | None

Handle up arrow: clear search buffer and cycle selection up.

#_h_main_down

python
def _h_main_down(self, key: str) -> str | None

Handle down arrow: clear search buffer and cycle selection down.

#_h_main_enter

python
def _h_main_enter(self, key: str) -> str | None

Handle enter: launch if valid, or enter creation/install/auth flow.

#_h_main_tab

python
def _h_main_tab(self, key: str) -> str | None

Handle tab: accept search match or advance focus to next segment.

#_h_main_backspace

python
def _h_main_backspace(self, key: str) -> str | None

Handle backspace: enter freeform editing or trim search buffer.

#_h_main_esc

python
def _h_main_esc(self, key: str) -> str | None

Handle escape: clear search buffer and exit freeform editing.

#_h_main_ctrl_c

python
def _h_main_ctrl_c(self, key: str) -> str | None

Handle Ctrl-C: quit the TUI.

#_h_main_delete

python
def _h_main_delete(self, key: str) -> str | None

Handle delete key: initiate profile deletion flow if on profile segment.

#_h_main_question

python
def _h_main_question(self, key: str) -> str | None

Handle '?': toggle provenance overlay visibility.

#_h_main_inspect

python
def _h_main_inspect(self, key: str) -> str | None

Handle 'i': open the profile inspect page for the focused profile.

#_h_main_review

python
def _h_main_review(self, key: str) -> str | None

Handle 'T': open the stale token review page.

#_h_main_freeform_seed

python
def _h_main_freeform_seed(self, key: str) -> str | None

Handle first printable key on freeform segment: seed editing from current value.

#_h_main_search

python
def _h_main_search(self, key: str) -> str | None

Handle printable key on searchable segment: append to search buffer.

#_h_main_quit

python
def _h_main_quit(self, key: str) -> str | None

Handle 'q' on non-searchable segment: quit the TUI.

#_h_theme_switch

python
def _h_theme_switch(self, key: str) -> str | None

Handle Mode 2031 theme-change notification.

#_h_freeform_enter

python
def _h_freeform_enter(self, key: str) -> str | None

Handle enter in freeform mode: submit the typed text as a new value.

#_h_freeform_tab

python
def _h_freeform_tab(self, key: str) -> str | None

Handle tab in freeform mode: accept first matching option.

#_h_freeform_backspace

python
def _h_freeform_backspace(self, key: str) -> str | None

Handle backspace in freeform mode: remove last character from buffer.

#_h_freeform_left

python
def _h_freeform_left(self, key: str) -> str | None

Handle left arrow in freeform mode: cancel editing and move focus left.

#_h_freeform_right

python
def _h_freeform_right(self, key: str) -> str | None

Handle right arrow in freeform mode: cancel editing and move focus right.

#_h_freeform_esc

python
def _h_freeform_esc(self, key: str) -> str | None

Handle escape in freeform mode: cancel editing and clear buffer.

#_h_freeform_ctrl_c

python
def _h_freeform_ctrl_c(self, key: str) -> str | None

Handle Ctrl-C in freeform mode: cancel editing and quit.

#_h_freeform_printable

python
def _h_freeform_printable(self, key: str) -> str | None

Handle printable key in freeform mode: append to search buffer.

#_h_create_enter

python
def _h_create_enter(self, key: str) -> str | None

Handle enter in creating mode: confirm creation of the new option.

#_h_create_esc

python
def _h_create_esc(self, key: str) -> str | None

Handle escape in creating mode: cancel and clear the create buffer.

#_h_create_backspace

python
def _h_create_backspace(self, key: str) -> str | None

Handle backspace in creating mode: remove last character from create buffer.

#_h_create_ctrl_c

python
def _h_create_ctrl_c(self, key: str) -> str | None

Handle Ctrl-C in creating mode: cancel creation and quit.

#_h_create_printable

python
def _h_create_printable(self, key: str) -> str | None

Handle printable key in creating mode: append to create buffer.

#_run_install_flow

python
def _run_install_flow(self, seg: Segment, version: str) -> None

Confirm install via run_selection, download in cooked, show result page.

#_build_bindings

python
def _build_bindings(self) -> list[Binding]

Build the full binding registry from handler methods.

#_h_main_search_or_quit

python
def _h_main_search_or_quit(self, key: str) -> str | None

Handle printable key on searchable segment: search or quit.

#_intercept_unauth

python
def _intercept_unauth(self, seg: Segment) -> str

Prompt auth for an unauthenticated profile before launch.

The app's terminal stays raw: the auth forms render borrowed as pages in the existing alt screen, and the subprocess steps inside the auth flow open their own cooked windows. On "authenticated", "unverified" (a token was saved without validation), and "failed" (credentials may be partially written), re-runs profile discovery and updates auth status. Returns the auth flow outcome: "authenticated", "unverified", "skip", "cancel", or "failed".

#_show_profile_inspect

python
def _show_profile_inspect(self, seg: Segment) -> None

Show a fullscreen inspect page for the focused profile option.

The app's terminal stays raw: show_page renders borrowed in the existing alt screen and the main TUI repaints on return. If the profile has an auth shadow, the hint offers 'f' to fix it.

#_show_stale_token_review

python
def _show_stale_token_review(self) -> None

Review and remove stale token entries (keys with no profile dir).

Lists each orphan tokens.json entry and offers per-entry or bulk removal via a selection list. Each removal goes through remove_orphan_token_entry (which rewrites tokens.json atomically), then findings are refreshed so the persistent notice clears once none remain. Cancelling leaves the store untouched.

#_delete_profile_flow

python
def _delete_profile_flow(self, seg: Segment) -> None

Confirm and delete the focused profile from the TUI.

Profiles holding REAL data at shared-dir names are hard-blocked with a fullscreen page pointing at the CLI escape hatch -- the TUI offers no override. Otherwise an informed two-option confirm runs (Cancel default-focused). The running check stays CLI/TUI policy; the actual deletion goes through ProfileStore.delete (no force flags). Store refusals raise ValueError, surfaced as a flash.

#_refresh_profile_segment

python
def _refresh_profile_segment(self, seg: Segment) -> None

Re-run profile discovery and update the segment's auth status.

#_launch_profile_wizard

python
def _launch_profile_wizard(self, seg: Segment) -> str | None

Run the create-profile flow as one continuous alt-screen session.

The app's terminal stays raw throughout: the wizard form, the auth forms, and the creation summary page all render borrowed in the existing alt screen (subprocess steps open cooked windows inside the auth flow). The main TUI repaints on return.

#_confirm_create

python
def _confirm_create(self, seg: Segment) -> None

Confirm creation of a new option.

Search