# Concepts and safety

## What Mugi is

Mugi is a Mac app with a built-in AI assistant. It runs a local backend on your Mac; the SwiftUI front end talks to it over localhost. You do not need Terminal for normal use.

Models run on your Mac. Choose the chat engine in **Settings → LLMs**:

- **MLX (mlx-vlm)** — default on Apple Silicon; fully managed local server on port **8000**.
- **Exo (connect)** — point Mugi at a running [Exo](https://github.com/exo-explore/exo) OpenAI-compatible API (default `http://127.0.0.1:52415/v1`). Mugi does not install or manage Exo.
- **External API** — any OpenAI-compatible endpoint (LM Studio, Ollama, vLLM, cloud APIs).

Embeddings and the utility model continue to use the MLX environment regardless of which engine powers chat.

The app watches your chats, **Vault** notes, and **Knowledge** corpora in the background. When it infers something about you or spots work worth doing, it puts that in places you can review:

- **Settings → Profile** — name, pronouns, timezone, tone, assistant personality.
- **Settings → You** — learned facts and **proposals** (accept, edit, or reject; diffs shown).
- **Kanban** — when a job needs more than one step, Mugi puts **cards** on a task board you open from the toolbar. See [How Kanban works](08-right-panels.md#kanban-overlay) (background jobs, **Coordinating workers…** banner, what you can stop).
- **Dashboard** — **⇧⌥D** or **View → Dashboard** opens a floating panel with vitals, calendar, weather, markets, news, and a chat composer. See [Dashboard panel](08-right-panels.md#dashboard-panel).
- **Activity** / **On my mind** — timeline and quick queue of background events.

Assistant identity files in your workspace (e.g. `PERSONA.md`) are protected from silent overwrites after onboarding.

Data lives under `~/.mugi` and your workspace folder. Optional chat encryption uses a Keychain key. **Your personal data stays on your Mac** — chats, memory, Vault, Knowledge, and **You**. In day-to-day use, the only way personal information can leave your machine is when the agent searches the web in connection with your conversations; those lookups go through a local **SearXNG** instance ([Settings → Network](10-settings-compendium.md#network)) and are not tied to any user account.

## Privacy and permissions

Default posture: private and local.

- **Allowed directories** (**Settings → Access**) — file tools stay inside folders you list, plus built-in workspace paths.
- **macOS prompts** — Screen Recording, Accessibility, Calendar, etc. appear when a feature first needs them.
- **Mesh** — LAN peer discovery only; off unless you use it.
- **Webhooks** — off until you enable them in **Settings → Advanced** and create tokens.

**Chat encryption** (optional) encrypts `~/.mugi/chats.db`. Export the key from the **File** menu if you need a backup. Lose the key, lose the history.

Background runs propose changes; they do not silently rewrite Profile, personality files, or your personal model. If something looks wrong, check **You**, **Activity**, and **Kanban**.

### When work moves to the Kanban board

Multi-step jobs do not always finish inside one chat reply. Mugi may create **cards** on the **Kanban** board (**toolbar → Kanban** or **View → Kanban Board**). Each card is one job running in the background while you keep chatting.

You may also see **Coordinating workers…** at the top of a thread — that means this conversation is waiting on several board jobs; the chat agent will summarize when they finish.

**Read next:** [How Kanban works](08-right-panels.md#kanban-overlay) — what the cards mean, what runs automatically, and how to cancel or pause a job.

### Further reading

- [Security overview](harness_threat_model.md)
- [Browser capture](THREAT_MODEL.md) — optional Chrome extension only

## Glossary

| Term | Meaning |
|------|---------|
| **Profile** | **Settings → Profile** — everyday identity and assistant personality fields. |
| **You** | **Settings → You** — learned context, proposals, checkpoints. |
| **Vault** | Notes and captures (mode rail → Vault, ⌃⌘2). **Discuss this** injects a note into chat. |
| **Knowledge** | Folders or repos digested into a corpus; read in the **Knowledge Library** (books icon on the mode rail). Manage under **Settings → Knowledge**. |
| **Kanban** | Task board overlay — one card per background job. [How it works →](08-right-panels.md#kanban-overlay) |
| **Dispatcher** | Mugi's automatic task runner (starts jobs from ready cards). You do not launch it. [Details →](08-right-panels.md#kanban-overlay) |
| **Worker** | The background run behind one **in progress** card. |
| **Coordinator mode** | Chat banner **Coordinating workers…** while several cards from this thread finish. [Details →](08-right-panels.md#kanban-overlay) |
| **Activity** | Right-pane feed of runs, trust events, diagnostics. |
| **On my mind** | Toolbar popover for short proactive items. |
| **Proposal** | Suggested personal fact or link; reviewed in **You**. |
| **Heartbeat** | Scheduled background pass (intervals in **Settings → Heartbeats**). |
| **Council mode** | Optional multi-step review on hard questions (**Settings → General**); or **`/council <question>`** in chat. |
| **Results** | Durable deliverables workspace (mode rail → Results, ⌃⌘4) — HTML, Markdown, reports, charts. [Details →](15-results-workspace.md) |
| **Grounding** | Optional background fact-checking of Mugi's own claims (**Settings → General → Grounding / fact-checking**). |
| **Slash command** | Typed shortcut in chat starting with `/`; **`/help`** lists all. [Full table →](07-chat-search-and-confirmations.md#slash-commands) |

Examples: [14-workflows-and-examples.md](14-workflows-and-examples.md).