claudewheel v0.20.1 /claudewheel.segment
Updated Edit
On this page

Segment model, SegmentBar, and option discovery logic.

#claudewheel.segment

#claudewheel.segment

Segment and SegmentBar dataclasses, option discovery, and cross-segment constraints.

#DiscoveryResult

Structured result from a discovery function.

#DiscoveryEntry

Registry entry mapping a discovery type to its function.

#_deduplicate

python
def _deduplicate(items: list[str]) -> list[str]

Remove duplicates preserving first occurrence order.

#SegmentState

Manages option collections with cache-invalidating mutation methods.

#options

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

#set_discovered

python
def set_discovered(self, vals: list[str], *, verify_fn: Callable | None=None) -> None

#add_pinned

python
def add_pinned(self, val: str) -> None

#remove_pinned

python
def remove_pinned(self, val: str) -> None

#set_defaults

python
def set_defaults(self, vals: list[str]) -> None

#add_ephemeral

python
def add_ephemeral(self, val: str) -> None

#set_installed

python
def set_installed(self, vals: set[str]) -> None

#has_installed

python
def has_installed(self) -> bool

#mark_installed

python
def mark_installed(self, val: str) -> None

#set_metadata

python
def set_metadata(self, meta: dict[str, dict]) -> None

#update_metadata

python
def update_metadata(self, partial: dict[str, dict]) -> None

#source_of

python
def source_of(self, val: str) -> str | None

#is_installed

python
def is_installed(self, val: str) -> bool

#set_authenticated

python
def set_authenticated(self, vals: set[str]) -> None

#has_auth_status

python
def has_auth_status(self) -> bool

#is_authenticated

python
def is_authenticated(self, val: str) -> bool

#Segment

A single segment in the TUI bar with options, selection state, and search.

#options

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

#display_options

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

Options visible in the UI: real options + virtual "+" for creatable segments.

#selected_idx

python
def selected_idx(self) -> int

Computed index of selected_value in display_options, or -1 if unselected.

#value

python
def value(self) -> str | None

#filtered_options

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

Return options filtered by search_buffer using fuzzy matching.

Filters against self.options (not display_options), so "+" is excluded from fuzzy search. This is intentional.

#cycle

python
def cycle(self, direction: int) -> None

Move selection up (+1) or down (-1) through display_options.

The ring has n+1 positions: [None, 0, 1, ..., n-1] where None is the blank/unselected state and n = len(display_options). With wrap=True, cycling continuously rotates through all positions including blank. With wrap=False, blank is reachable from EITHER end of the option list (UP from first OR DOWN from last), but going past blank in either direction stays at blank rather than continuing to the other end.

#is_on_plus

python
def is_on_plus(self) -> bool

True if the current selection is the '+' creation sentinel.

#select_value

python
def select_value(self, val: str) -> bool

Select an option by its string value. Returns True if found.

#SegmentBar

Ordered collection of segments with focus tracking and navigation.

#focused

python
def focused(self) -> Segment

#move_focus

python
def move_focus(self, direction: int) -> None

#get_selections

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

#version_sort_key

python
def version_sort_key(version: str) -> list[int]

Split a version string on '.' and convert parts to ints for numeric sorting.

#fetch_npm_versions

python
def fetch_npm_versions(state: dict, count: int=15) -> list[str]

Fetch recent Claude Code versions from npm, with 1-hour cache in state.

#_discover_directory_listing

python
def _discover_directory_listing(config: dict, state: dict) -> DiscoveryResult

Discover options from a directory of files (e.g., installed versions).

#_discover_npm_and_local

python
def _discover_npm_and_local(config: dict, state: dict) -> DiscoveryResult

Discover versions from npm registry + locally installed files.

#_discover_npm_and_local_cached

python
def _discover_npm_and_local_cached(config: dict, state: dict) -> DiscoveryResult

Fast path for npm_and_local: use cached npm versions only if warm.

#_discover_directory_scan

python
def _discover_directory_scan(config: dict, state: dict) -> DiscoveryResult

Discover directories by scanning parent directories.

Recent dirs from state are used as hints: validated (must exist on disk), emitted first in the result, and pruned back to state (stale entries removed). Static values from options.json are NOT included -- they are handled by SegmentState.defaults via the defaults collection.

#_discover_profiles

python
def _discover_profiles(config: dict, state: dict) -> DiscoveryResult

Discover Claude Code profiles via filesystem scan.

#_discover_gh_accounts

python
def _discover_gh_accounts(config: dict, state: dict) -> DiscoveryResult

Discover GitHub accounts from gh CLI auth status.

#_discover_state_field

python
def _discover_state_field(config: dict, state: dict) -> DiscoveryResult

Discover options by merging state-tracked values with static defaults.

#_parse_static_values

python
def _parse_static_values(config: dict) -> list[str]

Extract plain string values from an options_def entry, stripping requires dicts.

#_parse_requires

python
def _parse_requires(config: dict) -> dict[str, dict[str, str]]

Extract requires constraints from dict-style values in an options_def entry.

#run_slow_discovery_via_registry

python
def run_slow_discovery_via_registry(options_def: dict, state: dict) -> dict[str, DiscoveryResult]

Run only slow discovery types via the registry.

Mutates state (e.g. fetch_npm_versions writes npm_versions_cache). Callers running this in a background thread should pass a deep copy of the shared state dict and merge results back on the main thread.

#populate_segment_state

python
def populate_segment_state(seg: 'Segment', options_def_entry: dict, state: dict, *, skip_slow: bool=True) -> None

Populate a segment's state from discovery and static config.

Looks up the discovery config, calls the registry function (unless slow and skip_slow is True), and writes results to seg.state.

#_update_auth_from_metadata

python
def _update_auth_from_metadata(seg: 'Segment') -> None

Compute and set authenticated set from segment metadata.

A value is authenticated if its metadata has has_token=True or has_credentials=True. Auth tracking is only activated when at least one metadata entry carries these fields, keeping the feature invisible to segments that don't use it.

#build_segment_bar

python
def build_segment_bar(cfg: ConfigManager, *, skip_slow: bool=False) -> SegmentBar

Construct the segment bar from config, applying discovery and last-state restore.

#merge_slow_results

python
def merge_slow_results(bar: SegmentBar, results: dict[str, DiscoveryResult], state: dict, options_def: dict | None=None) -> None

Merge background discovery results into the live segment bar.

For each segment with new options in results, update its discovered list via SegmentState, update the installed set, and restore the previous selection (falling back to last_config from state).

When options_def is provided, staleness verify callbacks from the discovery registry are wired through so values that still exist on disk are not prematurely dropped.

#evaluate_requires

python
def evaluate_requires(bar: SegmentBar) -> None

Recompute unavailable sets based on cross-segment requirements.

#_satisfies_constraint

python
def _satisfies_constraint(value: str | None, constraint: str) -> bool

Check if a value satisfies a version constraint like '>=2.1.110'.