Home

A local-first, provider-agnostic agentic coding companion

One Rust core · three faces — a terminal UI, a web UI, and a phone app.

🌸  rose → lavender → violet → cyan — the Living Rose palette that runs through every surface  🩵

---

What is blumi?

blumi is a local-first, provider-agnostic agentic coding companion built as a single Rust binary. One UI-agnostic Rust core emits one typed event stream, so three faces — a terminal UI (TUI), an embedded web UI, and blugo, a Flutter phone app — all show the same live session. blumi is bring-your-own-key (BYOK): you connect Anthropic, OpenAI (or any OpenAI-compatible endpoint), Gemini, Azure Foundry, or a fully local model, and several machines sharing one secret can run as a single fleet (the grid).

This is the blumi wiki — everything you need to install, configure, and run blumi across your terminal, browser, phone, and a whole fleet of machines.

TL;DR: Install blumi with one command, run blumi login to add a provider key, then launch blumi for the terminal UI, blumi web for the browser, or blumi run "…" for a one-shot. It is Apache-2.0 licensed, runs on macOS, Linux, and Android, and keeps all secrets in ~/.blumi/settings.json (never in git).

Key facts

• blumi is a single Rust binary with a UI-agnostic core that emits one typed event stream.
• Three faces, one session: a terminal UI (TUI), an embedded React web UI, and blugo, a Flutter phone app.
• Provider-agnostic (BYOK): Anthropic, OpenAI (and OpenAI-compatible endpoints), Gemini, Azure Foundry, or a fully local model — switchable per-invocation.
• Local-first: semantic memory (RAG) and a code index work fully offline via a bundled embedder.
• The grid: several machines sharing one grid.secret form a fleet that auto-discovers peers and hands off tasks.
• Current version is 0.5.0, licensed Apache-2.0, running on macOS, Linux, and Android.

⭐ Enjoying blumi? Star it on GitHub — it genuinely helps others find the project.

🚀 How do I get started? (~60 seconds)

You start blumi in three steps: install the binary, add a provider key with blumi login, then run blumi. The same install works for the terminal UI, the web UI, and one-shot runs.

# 1. Install (builds the single binary; also sets up the Node + uv helpers)
curl -fsSL https://raw.githubusercontent.com/ankurCES/blumi-cli/main/install.sh | sh

# 2. Pick a provider + paste a key (or point at a local model)
blumi login

# 3. Go — the terminal UI
blumi                 # or:  blumi web   (browser UI)   ·   blumi run "…"  (one-shot)

New here? Installation → Configuration → CLI Usage is the happy path.

🧭 Find your way

	Guide	What's inside
📦	Installation	One-line install, prerequisites, building from source
⚙️	Configuration	The complete settings.json reference — every section, field & default
⌨️	CLI Usage	Commands, the TUI, slash-commands, the autonomous loop
🌐	Gateway	blumi serve + the messaging-bot gateway as always-on services
📱	Mobile App	Connect the blugo phone app over your Wi-Fi
🕸️	Grid (distributed) · Demo	Run many machines as one fleet that hands off tasks
🧠	Memory & Knowledge	Semantic memory (RAG) + a code knowledge base
🎙️	Voice	Speak to / hear blumi (STT + TTS)
✨	Self-Management	Self-edited config/skills, routing, hooks, notifications, self-healing
⚖️	RPL-Judgement	Adversarial, regret-minimizing pre-execution review (Raskolnikov's Loop)
🛠️	Development	Architecture + hacking on blumi
🩹	Troubleshooting	When something's off
❓	FAQ	Why blumi & how it works — for decision-makers and developers

💡 What can blumi do?

blumi runs agentic coding sessions across a terminal, a browser, and a phone, with any model you bring, and can spread work across a fleet of machines. Its core capabilities are:

• 🖥️ Three faces, one session — a crush-inspired terminal UI, an embedded React web UI, and blugo, a Flutter phone app that mirrors the TUI (and folds gracefully on foldables).
• 🔌 Bring your own model — Anthropic, OpenAI (and any OpenAI-compatible endpoint), Gemini, Azure Foundry, or a fully local server. Switch per-invocation.
• 💸 Cost-aware routing — auto-route simple turns to a cheap model and hard ones to the flagship; watch the $ saved.
• 🧠 Memory & code knowledge — semantic long-term memory with RAG recall + a local code index, fully offline via a bundled embedder.
• 🕸️ The grid — several machines sharing one secret form a fleet; your phone drives work that runs across all of them.
• 🤖 Always-on & autonomous — an always-on gateway, an autonomous task loop, proactive discovery, and completion notifications (desktop / bot / phone / browser).
• ✨ Self-managing — it can author its own skills, edit its own (validated) config, reload in place, and self-heal failed steps into learned fixes.

🧩 What are the common ways to run blumi?

blumi has three common setups: a single local machine, a gateway plus phone, or a multi-machine grid. Pick the one that matches how many machines and surfaces you want.

1. Local (one machine). Install, blumi login, run blumi (TUI) or blumi web. Nothing else needed. → Installation · CLI Usage
2. Gateway + phone. Run blumi serve as an always-on service; connect blugo over Wi-Fi (it auto-discovers the gateway on your network). → Gateway · Mobile App
3. Grid (many machines). Install on several machines, give them the same grid.secret; they auto-discover and hand off tasks. Any node — or your phone — drives the fleet. → Grid

📎 Conventions used here

• Config lives in ~/.blumi/settings.json (global) + a per-project .blumi/ overlay.
• Services are com.blumi.serve / com.blumi.gateway (launchd, macOS) or blumi-serve / blumi-gateway (systemd user, Linux).
• Secrets — API keys, the grid secret, the gateway password hash — stay in settings.json (mode 0600), never in git.

❓ Frequently asked questions

What is blumi?

blumi is a local-first, provider-agnostic agentic coding companion, shipped as a single Rust binary. Its UI-agnostic core emits one typed event stream so a terminal UI, a web UI, and the blugo phone app all show the same live session.

How do I install blumi?

Run the one-line installer: curl -fsSL https://raw.githubusercontent.com/ankurCES/blumi-cli/main/install.sh | sh. It builds the single binary and sets up the Node and uv helpers. Then run blumi login to add a provider and key. See Installation.

Which AI models and providers does blumi support?

blumi is bring-your-own-key (BYOK) and works with Anthropic, OpenAI (and any OpenAI-compatible endpoint), Gemini, Azure Foundry, or a fully local model server. You can switch the model per-invocation, and cost-aware routing can send simple turns to a cheap model and hard ones to the flagship.

Is blumi local-first and offline-capable?

Yes. blumi is local-first: its semantic long-term memory (RAG, retrieval-augmented generation) and local code index run fully offline through a bundled embedder, and all secrets stay on disk in ~/.blumi/settings.json rather than in git.

What is the blumi grid?

The grid is a fleet of several machines that share the same grid.secret; they auto-discover each other and hand off tasks. Any node — or your phone via blugo — can drive work that runs across the whole fleet. See Grid and the Grid Demo.

What platforms and license does blumi use?

blumi runs on macOS, Linux, and Android (via the blugo app), is currently at version 0.5.0, and is licensed under Apache-2.0.

Install · Configure · CLI · Gateway · Mobile · Grid · Memory · Voice · Self-Management · FAQ

_{Made with 🌸 — Apache-2.0 · github.com/ankurCES/blumi-cli}