Skip to content

Models (overview)

Ripple supports two classes of planner model: on-device MLX models that run entirely on your Mac, and remote OpenAI-compatible models that call an external API. Both are selected through the same interface and can be swapped at any time without restarting.

On-device MLX models

MLX models run locally on Apple Silicon using the MLX inference stack. No data leaves the machine and there is no per-token cost. The trade-off is that a large-enough model can consume significant RAM and the first-token latency is higher than a remote call on a fast connection.

Model ids use the Hugging Face <provider>/<name> form, for example:

LiquidAI/LFM2.5-1.2B-Instruct-MLX-bf16

Models are downloaded from Hugging Face on demand and cached at ~/.cache/huggingface/hub/. Ripple never downloads a model silently - it always prompts before starting a transfer (or requires --yes). See Local MLX models for the full download workflow and the ripple model sub-commands.

MLX inference requires Apple Silicon and macOS 26+. On Intel Macs the MLX adapter is unavailable and you must use a remote model.

Remote models

Remote models are any service that speaks the OpenAI Chat Completions API, including OpenAI itself, Azure OpenAI, Anthropic (via its OpenAI-compatible proxy), and Amazon Bedrock. They are defined as named entries in settings.json and are available to all projects that share that config.

Because the call goes over the network, keys and costs live outside your machine, but you get access to the largest models and the highest context windows. See Remote models for the full config schema and provider-specific notes.

How a planner is selected

Ripple resolves the active planner model in this order:

  1. --model <id> flag - highest priority, overrides everything for that session.
  2. /model picker - the in-session overlay; persists the choice to selectedModel in settings.json.
  3. selectedModel in settings.json - the last model you picked with /model.
  4. A built-in default (the smallest available local model, or the first remote entry).

The --model value can be either a Hugging Face id for a local MLX model or the name field of a registered remote entry.

The /model picker

Type /model at the prompt to open the model overlay. It has three tabs:

Presents all available planners - both downloaded local models and registered remote models - as a single list, each local one labelled with what it is for, its weight format, size and context window. Selecting one makes it active for the session and writes selectedModel to settings.json so the choice persists across restarts. You can also set the idle timeout here.

This tab is also where you turn vision on. Vision is off by default: the vision subagent is a second model to download, load and keep resident, and most sessions never delegate a screenshot to it. Pick a VLM here to enable it (written to settings.json as visionModel); until you do, the banner reports vision none and no VLM is fetched.

Browse the on-device MLX catalog: model families first, split into LLM and Embedding, then that family's models under a heading per role (Text / Vision / Text + Vision). Each model row shows its download status, weight format, size, context window and per-turn output budget; type to filter. You can trigger a download without leaving the chat. See Local MLX models.

Browse OpenRouter's free catalog, in the same two levels as the Local tab: providers, then that provider's models under a role heading, carrying the same context-window and output columns. Add or remove models from your remote registry. See Remote models.

When to use local vs remote

Consideration Local MLX Remote
Data privacy Data never leaves the device Data sent to provider's API
Cost Free (electricity / RAM) Per-token billing
Context window Each model's documented window: 32k for most LFM2.5, 128k for 8B-A1B and Gemma 4, 131k for LFM2.5 2.6B, 262k for Ornith and Qwen3.6 Up to 200k+
First-token latency Higher (model loaded in RAM) Lower on fast connections
Availability Works offline Requires network and valid key
Vision Model-dependent Provider-dependent
Apple Silicon required Yes No

For tasks that handle sensitive code or documents, local models are the natural choice. For long multi-file refactors, research tasks, or when you need a frontier reasoning model, a remote model is more practical.

Tip

You can switch models mid-session with /model without losing your history or session state. The new model picks up exactly where the previous one left off.