Core Features & Architecture Design
The Pi-Local plugin is written in TypeScript, with a concise yet fully functional design. Its core architecture consists of several key modules:
Connection Management Module
The plugin provides the /local-login command to manage connection configurations for local LLM servers. Users can add new connections via an interactive interface, each containing a base URL and API key. The plugin supports multiple authentication methods:
- Direct Key: Plaintext API key, e.g.,
sk-1234567890abcdef
- Environment Variable Reference: Reference environment variables using formats like
$MY_API_KEY or ${MY_API_KEY}
- Command Execution: Dynamically retrieve keys using commands like
!security find-generic-password
- No Authentication Mode: Leave blank to indicate no authentication is needed
Secure Key Storage
For macOS users, the plugin specifically integrates the system Keychain feature. When users enter an API key, the plugin can automatically store it in the macOS Keychain instead of plaintext configuration files. This not only improves security but also makes key management more convenient. When a connection is deleted, the plugin also automatically cleans up the corresponding Keychain entry.
Intelligent Model Selector
The /local-model command is one of the plugin's core features. It automatically detects the connected server type (oMLX, LM Studio, or OpenAI-compatible interface) and retrieves the list of available models. The plugin supports the following features:
- Multi-server Type Adaptation: Automatically identify server type via API response characteristics
- Model Metadata Display: Show key information like model size, context window, and whether inference is supported
- Dynamic Loading/Unloading: For oMLX and LM Studio servers, support direct loading or unloading of models in the UI
- Intelligent Sorting & Formatting: Models are sorted by name, and displayed information is aligned for easy reading
Auto-Recovery Mechanism
The plugin automatically checks and restores the last used local model connection on startup. It reads Pi's settings file, finds the default local provider and model ID, and if the configuration is valid and the key can be resolved, it automatically registers with Pi's provider system. This means users do not need to reconfigure after each restart.
