# Minima

> A recommendation engine for LLM model routing. Cuts token spend without losing quality — plus the minima harness, a cost-aware terminal coding agent.

## Docs

- [SDK architecture](/sdk/architecture): Minima ships two official SDKs over the same `/v1/*` HTTP contract:
- [Python Client SDK](/sdk/client-sdk): The `minima_client` package is the official thin, typed Python client for the hosted Minima API, plus an optional zero-code intake helper.
- [Concepts](/sdk/concepts): LLM workflows overspend by sending every call to a top-tier model when a cheaper model would do a portion of the work just as well. Token cost is the lever; **model choice is the cheapest knob to turn**. Minima turns that knob, per task, based on what models have actually done on similar tasks before.
- [Examples](/sdk/examples): Copy-paste recipes against the hosted API, from a single `curl` to a production routing wrapper. Every snippet is self-contained.
- [Getting Started](/sdk/getting-started): Minima is a hosted API. There is nothing to install or run — you call the service with an API key, get a model recommendation, run that model in **your own** stack, and report the outcome so the next pick gets sharper — or run your own instance instead: see [Self-hosting](/sdk/self-hosting). This walks you from a key to a closed feedback loop.
- [How Minima uses Mubit](/sdk/mubit): Minima's recommender is **non-parametric**: it doesn't train a model on your traffic, it *remembers* your traffic. [Mubit](https://mubit.ai) is the memory substrate that makes that work — and it is the **only external dependency** of the core recommender. Every capability below is hosted; you operate none of it.
- [Self-hosting](/sdk/self-hosting): The hosted service at `api.minima.sh` needs nothing installed — but Minima is also a small FastAPI service you can run yourself. The core recommender's only external dependency is a [Mubit](https://docs.mubit.ai) memory backend. This page condenses the repo's operator docs; the deep versions are [`docs/getting-started.md`](https://github.com/mubit-ai/minima/blob/main/docs/getting-started.md), [`docs/configuration.md`](https://github.com/mubit-ai/minima/blob/main/docs/configuration.md), and [`docs/seeding.md`](https://github.com/mubit-ai/minima/blob/main/docs/seeding.md).
- [TypeScript SDK](/sdk/typescript): [`@mubit-ai/minima-sdk`](https://www.npmjs.com/package/@mubit-ai/minima-sdk) is the official TypeScript client for the Minima API: pure `fetch`, **zero runtime dependencies**, typed against the same `/v1/*` wire contract as the [Python SDK](/sdk/client-sdk). It works in Node, Bun, Deno, and edge runtimes.
- [Using Minima correctly](/sdk/usage-guide): Minima is **recommend-only**. Everything about using it well follows from that one fact: it tells you which model to run, *you* run the model, and you tell it what actually happened. This page is the whole proper-use flow in one place.
- [Under the hood](/harness/architecture): This page explains how the `minima` agent actually works internally — what happens between you pressing <kbd>Enter</kbd> and the next recommendation getting sharper. You don't need any of it to use the CLI, but it's the mental model behind the slash commands, the confidence badges, and the cost figures you see.
- [CLI usage](/harness/cli): Besides the interactive TUI, `minima` runs in two non-interactive modes and exposes two subcommands.
- [Configuration](/harness/configuration): The harness is configured through environment variables — supplied via a per-user credential store, project `.env` files, or your shell. `minima config` manages the per-user store.
- [Installation](/harness/installation): The `minima` harness is distributed as a self-contained native binary through the [`mubit-ai/homebrew-minima`](https://github.com/mubit-ai/homebrew-minima) Homebrew tap. Install it, authenticate, and start.
- [Interactive TUI](/harness/interactive): Running `minima` with no prompt opens the interactive terminal UI: a scrolling conversation view, an input prompt, and a status bar. Type a message and press <kbd>Enter</kbd> to send it; the harness routes it, runs the chosen model, streams the reply, and executes any tool calls (asking permission where required).
- [Minima CLI](/harness/overview): `minima` is a terminal coding agent. It reads and edits your code, runs commands, and answers questions about a repo — like any agentic CLI — but every prompt is first sent to the [Minima recommender](/sdk/getting-started) to pick the cheapest model that will actually do the job. It then **runs that model itself** (calling the provider API directly), grades the outcome, and reports feedback so the next pick is sharper.
- [Model routing](/harness/routing): Every turn follows the Minima loop:
- [Sessions](/harness/sessions): Every conversation is persisted as an **append-only session** — a JSONL log of turns stored under `~/.minima-harness/sessions/<session-id>.jsonl`. Because entries are only ever appended, you can branch from any point in the history rather than losing it.
- [Tools & permissions](/harness/tools): The agent gets things done by calling **tools**. Each tool call passes through a permission gate before it runs, so nothing touches your files or shell without approval (or a standing grant).
- [Troubleshooting](/harness/troubleshooting): If routing calls fail or hang:
- [Usage flows](/harness/usage-flows): Everything the harness does hangs off one idea: **honest outcomes make the next turn better**. Each flow below either earns an honest outcome (plans, gates, the judge), acts on one (recovery, memory, routing), or keeps you in control while it happens (budgets, checkpoints, permission modes). This page walks the major flows — what each does, how to drive it, and what you get out of it. For the one-line reference of every command and key, see [Interactive TUI](/harness/interactive).
- [API Reference](/api-reference/endpoints): Base URL: `https://api.minima.sh`. Base path: `/v1`. All request and response bodies are JSON. Interactive OpenAPI docs are served at [`https://api.minima.sh/docs`](https://api.minima.sh/docs).