Ripple

An on-device coding agent for macOS, a Claude Code-style terminal CLI that runs LFM2.5 models locally on Apple Silicon via MLX, with an interactive REPL, a headless mode, and a scenario harness. Built on DeepAgents.

---

Commands

ripple                     interactive deep-agent REPL (no subcommand needed)
ripple -p "..."            one-shot, non-interactive run (machine-readable output)
ripple run <scenarios>     headless TOML/JSON scenario harness
ripple mcp                 manage MCP servers
ripple model               download / manage local models
ripple --version           print the ripple and DeepAgents-swift versions
ripple --help              full usage and project links

Just run ripple to start the interactive REPL - no subcommand needed (ripple chat is the explicit equivalent). Pipe text on stdin (echo "..." | ripple) for a one-shot run.

Lazy tools (experimental). Prefilling forty tool schemas on every query is most of a cold first response. In /config → Lazy Tools you mark each toolset (and each MCP server) core or auxiliary: core schemas stay in the prompt, auxiliary ones are found on demand with search_tools and then called normally, costing nothing until they are needed. Matching is lexical by default, or semantic via an on-device ColBERT encoder (ripple model pull mlx-community/LFM2.5-ColBERT-350M-8bit). See Lazy tools.

Pick a model without leaving the chat. /model → Local lists the on-device catalog by model family, split into LLM and Embedding; open one for its models under a Text / Vision / Text + Vision heading, each row showing its download state, weight format, size, context window and per-turn output budget in aligned columns. Type to filter, enter to download, ctrl-x to remove. The Remote tab browses OpenRouter's free catalog the same way, with the same columns. See Local MLX models.

Requirements

• macOS 26+ (Tahoe), Apple Silicon (arm64)
• Xcode 26+ only if you build from source (the prebuilt brew install dsaad68/tap/ripple needs no Xcode)
• Apple's container tool only for the shell sandbox (/config → Sandbox). It is not part of macOS; without it failover runs commands in the local shell and container-only refuses to run them.

Install

With Homebrew (prebuilt binary, no Xcode needed):

brew install dsaad68/tap/ripple

Or build from source from a clone (needs Xcode 26+, which is the only build system that co-locates MLX's default.metallib beside the binary):

brew install --HEAD ./Formula/ripple.rb

Upgrade later with brew upgrade ripple.

Models come from your local Hugging Face cache; pre-fetch a planner first, e.g.:

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

Docs

• Ripple: ripple.verybad.engineer
• DeepAgents: deepagents-swift.verybad.engineer

License

MIT. See LICENSE.