LM Studio Tray Manager

Load app version from the VERSION file. Args: base_dir (str): Directory path containing the VERSION file. Returns: str: Version string read from the VERSION file, or DEFAULT_APP_VERSION if the file is missing or empty.

Get the default script directory. Returns the directory containing the currently executing script, or the current working directory if the script path cannot be determined. Returns: str: Absolute path to the script directory.

Parse command-line arguments from sys.argv. This function reads all arguments and flags provided on the command line via sys.argv and returns them as a structured namespace object. Command-line Arguments: model (str): Model name to monitor; positional, optional. script_dir (str): Script directory for logs; positional, optional. --debug, -d (bool): Flag to enable debug logging. --auto-start-daemon, -a (bool): Start daemon on launch. --gui, -g (bool): Start LM Studio GUI on launch. --version, -v (bool): Print version and exit. --help (bool): Print help message and exit. Returns: argparse.Namespace: Parsed arguments as an object with attributes matching argument names (e.g., namespace.model, namespace.debug). Raises: SystemExit: If --help or --version flags are used, or if the argument parser encounters invalid arguments (handled by argparse.ArgumentParser).

Synchronize test mocks with _AppState and module-level variables. This public helper function allows tests to update both _AppState (private class) and module-level variables in a coordinated way, avoiding direct access to _AppState. Args: gtk_mod (ModuleType, optional): GTK module to set. glib_mod (ModuleType, optional): GLib module to set. app_mod (ModuleType, optional): AppIndicator3 module to set. gdk_pixbuf_mod (ModuleType, optional): GdkPixbuf module to set. script_dir_val (str, optional): script_dir value to set. app_version_val (str, optional): APP_VERSION value to set. auto_start_val (bool, optional): AUTO_START_DAEMON value to set. gui_mode_val (bool, optional): GUI_MODE value to set. api_host_val (str, optional): API host value to set. api_port_val (int, optional): API port value to set. Returns: None.

Load app version from VERSION file in script directory. Reads the app version from the VERSION file located in the script directory. Falls back to DEFAULT_APP_VERSION if the file is missing or unreadable. Returns: str: Version string read from the VERSION file, or DEFAULT_APP_VERSION if loading fails.

Initialize module globals from CLI args and run the tray application. Parses command-line arguments (from sys.argv) via parse_args(), loads GTK dependencies, configures logging, and starts the GTK main loop. Exits immediately when the --version flag is provided, without loading GTK. Raises: SystemExit: When --version flag is provided (via sys.exit(0)).

Locate asset file handling both PyInstaller and normal execution. Searches in this order: 1. sys._MEIPASS/assets/... (PyInstaller bundle) 2. script_dir/assets/... (Release package or source dir) 3. Current working directory/assets/... Args: *path_components: Path components relative to assets/ directory. Example: get_asset_path("img", "lm-studio-tray-manager.svg") Returns: str | None: Full path to the asset file if found, None otherwise.

Return the user config file path in the home config directory.

Normalize and validate the API port value.

Load config values for the LM Studio API endpoint. Updates _AppState.API_HOST and _AppState.API_PORT when valid values are present in the config file.

Persist config values for the LM Studio API endpoint.

Validate that URL uses only permitted schemes (http/https). Args: url: URL string to validate. Raises: ValueError: If URL scheme is not http or https.

Return the base URL for the LM Studio API endpoint. Constructs the URL using the configured API_HOST and API_PORT from _AppState. Returns: str: Base API URL in format http://host:port Raises: ValueError: If the API host or port configuration is invalid.

Return the full URL for the LM Studio API models endpoint.

Load authors from AUTHORS file in script directory. Reads the AUTHORS file located in _AppState.script_dir and parses author names from markdown list format. If the file cannot be read or contains no valid authors, a fallback list containing APP_MAINTAINER is returned instead. Returns: list: List of author name strings extracted from the AUTHORS file. If the file cannot be read or contains no valid authors, returns a list containing APP_MAINTAINER as a fallback.

Parse a version string into a comparable tuple of integers.

Return True when latest is newer than current.

Validate update URL to prevent unsafe schemes or hosts. Args: url: URL string to validate. Returns: bool: True when the URL uses HTTPS and GitHub API host.

Fetch the latest GitHub release tag name.

Return the LM Studio CLI path if executable or resolve it from PATH.

Return llmster executable path from PATH or LM Studio install dir.

Return the absolute pkill path from PATH if available.

Return the absolute notify-send path from PATH if available.

Return the absolute ps path from PATH if available.

Return the absolute pgrep path from PATH if available.

Return the absolute dpkg path from PATH if available.

Check if any models are loaded via LM Studio API. Queries the configured API endpoint to check if models are loaded. This is a fallback when 'lms ps' fails (e.g., desktop app running without daemon). Returns: bool: True if at least one model is loaded, False otherwise.

Run a pre-validated command list via subprocess. The caller MUST ensure that ``command`` only contains trusted, absolute-path executables resolved through helper functions. Args: command: List of strings forming the command. Returns: CompletedProcess: The completed process result. Raises: ValueError: If command format is invalid or executable is not an absolute path.

Return True when a llmster process is currently running.

Return PIDs of LM Studio desktop app root processes.

Terminate other running instances of this script.

Apply parsed command-line arguments to app state. Args: args (argparse.Namespace): Parsed command-line arguments. Expected fields: model, script_dir, debug, gui, auto_start_daemon. Returns: None.

Store imported GTK-related module references on the class. Args: gtk_module (ModuleType): The Gtk module to store as cls.Gtk. glib_module (ModuleType): The GLib module to store as cls.GLib. app_indicator_module (ModuleType): The AppIndicator3 module to store as cls.AppIndicator3. gdk_pixbuf_module (ModuleType): The GdkPixbuf module to store as cls.GdkPixbuf. Returns: None.

Initialize tray indicator, menu, and periodic status checks.

Start llmster daemon on launch when enabled.

Start LM Studio GUI on launch when enabled.

Prevent rapid double-triggering of tray actions.

Schedule a delayed menu refresh when GLib is available. Args: delay_seconds (int): Number of seconds to delay before refreshing the menu. Defaults to 2 seconds.

Build or rebuild the context menu with current status and options.

Check if llmster headless daemon is running. Returns: str: "running" if daemon process is active, "stopped" if llmster is installed but daemon not running, "not_found" if llmster is not installed.

Check if LM Studio desktop app is running. The desktop app is started via lmstudio_autostart.sh --gui or directly, and runs WITHOUT the --run-as-service flag. This is different from the headless daemon (--run-as-service). Returns: str: "running" if desktop app process is active, "stopped" if installed but not running, "not_found" if not installed.

Convert status string to emoji indicator. Args: status: "running", "stopped", or "not_found" Returns: str: Emoji indicator (🟢 running, 🟡 stopped, 🔴 not_found)

Run a pre-validated command list via subprocess. The caller MUST ensure that ``command`` only contains trusted, absolute-path executables resolved through ``get_lms_cmd``, ``get_llmster_cmd`` or equivalent helpers. Args: command: List of strings forming the command. Returns: CompletedProcess: The completed process result. Raises: ValueError: If command format is invalid or executable is not absolute path.

Run daemon command attempts until a condition is met. Args: attempts: Ordered list of command argument lists. stop_when: Callable that receives the subprocess result and returns True when no further attempts are needed. Returns: CompletedProcess | None: Last command result, or None if no command was executed.

Build ordered daemon CLI attempts for one action. Args: action: Either "start" or "stop". Returns: list[list[str]]: Commands to try in order.

Force-stop llmster and wait briefly for process exit.

Stop llmster with graceful attempts and force-stop fallback. Returns: tuple[bool, CompletedProcess | None]: Tuple containing: - True when llmster is no longer running. - Last command result used during stop attempts.

Stop LM Studio desktop processes using TERM, then KILL. Returns: bool: True when the desktop app is no longer running.

Start the headless daemon. Stops the desktop app first if needed, then tries daemon start variants and notifies on success/failure. Args: _widget: Widget that triggered the action (unused).

Stop the headless daemon. Tries graceful stop variants first and falls back to force-stop. Args: _widget: Widget that triggered the action (unused).

Start the LM Studio desktop app. Stops the daemon first if needed, locates the app (.deb or AppImage), and launches it with user notification. Args: _widget: Widget that triggered the action (unused).

Stop the LM Studio desktop app process. Useful when the window closes to tray but the process remains active. Args: _widget: Widget that triggered the action (unused).

Handle the tray quit action by logging and exiting the Gtk main loop.

Show a GTK message dialog containing the LM Studio CLI status output. Runs `lms ps` to retrieve status information. If daemon is not running, falls back to querying the LM Studio API directly. Formats a friendly message on success or error, and displays it in an informational dialog. Errors are caught and shown to the user instead of raising.

Show application information in a GTK dialog.

Show configuration dialog for LM Studio API endpoint.

Return version text with update status for the About dialog. Returns: str: Version text in the format '<APP_VERSION> (<status>)'.

Run the update check for scheduled timers.

Run a single update check shortly after startup.

Build the update check notification message.

Run update check on demand and notify about the result.

Check GitHub for a newer release and notify the user. Returns: bool: True if a notification was sent.

Check LM Studio runtime/model status and update tray icon. Updates the tray icon using this schema: - FAIL: neither daemon nor desktop app is installed - WARN: neither daemon nor desktop app is running - INFO: daemon or desktop app is running, but no model loaded - OK: a model is loaded Sends desktop notifications when status changes from a previous non-None state, and logs status changes and errors. Returns: bool: True to indicate the check completed (used for scheduled callbacks).

Get a writable directory for logs. If base_script_dir is writable, returns base_script_dir/.logs. Otherwise (e.g., in AppImage), returns a writable location in the user's home directory. Args: base_script_dir (str): The script directory to check. Returns: str: Absolute path to a writable logs directory.

Set GSETTINGS_SCHEMA_DIR if not already set and schemas exist. This prevents GSettings crashes when running PyInstaller binaries on systems where GTK tries to load missing schema keys. Returns: None.

Open *url* in the default web browser. Historically this helper copied the link to the clipboard; the behaviour was updated to perform an indirect open instead. It remains easily monkey-patchable for unit tests.

Open a link from GTK dialogs and report success. Args: url (str): URL from the activate-link signal. Returns: bool: True when the URL open was attempted successfully.

Return a GitHub URL for a release. Args: tag (str, optional): A release tag name (e.g. "v1.2.3"). If provided the URL will point directly to that tag. If omitted the generic ``/releases/latest`` URL is returned, which GitHub redirects to the newest release. Returns: str: Absolute URL to the desired release page.

Return True if ``lms ps`` output indicates a loaded model. Some releases of the CLI print *all* available models even when none are actually loaded. Other releases explicitly say "No models are currently loaded.". We treat such outputs as *not* containing a loaded model; a debug log entry is emitted so the behavior is traceable.

Return model names that are explicitly marked as loaded. LM Studio API responses may include *available* models that are not currently loaded. To avoid false positives, we only treat a model as loaded when there is explicit evidence in the model object. Args: models: Parsed ``data`` list from the API response. Returns: list[str]: Names/ids for models explicitly marked as loaded.

Mutable application state shared across the module.

Manage the GTK tray icon for LM Studio runtime monitoring. The tray displays runtime status, provides daemon/app controls, and sends desktop notifications on status transitions.