ember

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="assets/brand/hero-dark.svg">
  <img src="assets/brand/hero-light.svg" alt="ember — Ember hugs its glowing tummy. Give your agent a gut feeling." width="1200">
</picture>

<!-- mcp-name: io.github.shapeandshare/ember -->

**A local gut feeling for coding agents.** ember runs a decision model — Cloudflare's
Clef-Flash, from its [public Hugging Face repo](https://huggingface.co/Cloudflare/clef-flash)
— on your Apple Silicon Mac and gives agents one MCP tool, `advise`: describe a situation,
ask typed questions, and get back a calibrated feeling about every option. It's a little
buddy for judgment calls — it advises; the agent decides.

**Website:** [shapeandshare.github.io/ember](https://shapeandshare.github.io/ember/)

## How it works

A decision model is not a chat model: it takes a `state` plus a schema of typed
questions and returns one probability per option, with no text generation. So ember
plugs into agents as a **tool**, while their reasoning stays on their normal LLM:

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="assets/diagrams/call-path-dark.svg">
  <img src="assets/diagrams/call-path-light.svg" width="760" alt="ember call path: a coding agent calls the advise tool over MCP into ember-mcp (stdio, starts instantly), which starts the ember model server on the first call; the server stays warm and runs Cloudflare's Clef-Flash on MPS in fp16.">
</picture>

- The **model server** (`ember/serving/server.py`) loads the model once and stays warm across
  agent sessions.
- The **MCP server** (`ember/mcp/mcp_server.py`) never loads the model; it starts the model
  server on the first tool call, so the MCP handshake stays instant.

### Names

| Thing | Name |
| --- | --- |
| Product, Python import, repository | `ember` |
| Distribution (`uv tool install`, PyPI) | `ember-advise`, because `ember` is taken on PyPI and `gut` is held by an empty project |
| CLI | `ember` (short alias: `gut`; `ember-advise` too, so `uvx ember-advise mcp` works) |
| MCP server / command | `ember` / `ember-mcp` |
| Tool | `advise` — opencode: `ember_advise`; Claude Code: `mcp__ember__advise` (plugin: `mcp__plugin_ember_ember__advise`); Kilo Code: `ember_advise` |
| Playbook skill / MCP resource | `ember-advise` / `ember://guide` |
| Environment variables | `EMBER_*` |

"Clef" always refers to Cloudflare's upstream model, never to this product. Select a model
with `ember model pull <name>` / `EMBER_MODEL=<name>`; run `ember model list` to see every
registered entry (`flash`, `full`).

A hosted deployment (e.g. [Outerbounds](https://outerbounds.com)) that supplies the model's
S3 location directly at start time doesn't use this registry at all — see "Hosted deployment:
a model location supplied at start time" below.

## Verified

On a MacBook Pro **M4 Max / 128 GB**, torch 2.14.1, transformers 5.18.0, mcp 2.3:

| Step | Result |
| --- | --- |
| Model load | ~5 s |
| Warm request | **~0.9–1.3 s** for ~220–360 input tokens |
| opencode end to end | ✅ the agent reads the instructions, lists the skill, and calls the tool unprompted |

## Install (Apple Silicon)

### Requirements

- **Apple Silicon Mac** (M-series) on macOS for local use (MPS). Intel Macs remain out of
  scope. For a hosted deployment on NVIDIA/CUDA compute (e.g. Outerbounds), see "Hosted
  deployment" below and `deployment/README.md`.
- **Unified memory** above the model's size: 32 GB or more for `flash` (9B), 64 GB or more
  for `full` (27B). Only 128 GB has been verified.
- **Disk**: about 18 GiB for `flash` or 55 GiB for `full`, in Hugging Face's shared cache
  (`~/.cache/huggingface`). Config, state, and logs live in
  `~/Library/Application Support/ember`.
- **Python 3.12**, managed by uv.

```bash
uv tool install --python 3.12 ember-advise

ember model pull                   # ~18 GB, resumable, disk-space checked
ember doctor                       # platform, dependencies, model, server, and agent registration
ember init --opencode --global     # register with opencode for every repo on this machine
```

Keep `--python 3.12`: uv otherwise picks your newest interpreter, which the pinned
torch/transformers stack is not tested on.

This installs the latest released wheel from PyPI.

To pin a specific release tag from GitHub instead (no PyPI required):

```bash
uv tool install --python 3.12 "ember-advise @ git+https://github.com/shapeandshare/ember@v0.8.1"
```

The repository is public, so the git install needs no credentials. To use SSH instead,
install from `git+ssh://git@github.com/shapeandshare/ember@v0.8.1`.

Installed ember before the rename, as `gut`? Run `uv tool uninstall gut` first: both
distributions provide the same commands.

Restart opencode and every repo on this machine gains `ember_advise`. The model server
stays **lazy** — it starts on the first tool call (or with `ember start`).

**Per-project skill and policy** (run once in each repo you want ember-aware agents):

```bash
cd /path/to/your/repo
ember agents install --agent opencode  # installs the ember-advise playbook skill
ember agents show snippet >> AGENTS.md # then edit the project policy block at the end
```

The skill teaches the agent *when* to consult ember and *how* to ask; the AGENTS.md snippet
adds a project-specific policy you customize (e.g. "check change risk before every push").
See [Agent onboarding](#agent-onboarding) below for all harnesses and options.

`flash` targets the commit verified on MPS (`17f0b0a`) and `full` its release commit
(`2f3de3d`, not yet verified locally) as a download convenience, and torch/torchvision are
pinned to the tested minor series — but ember does not restrict itself to a hand-maintained
allowlist of individually verified weights; it runs any model that fits its loader contract
(constitution Article V, "Model Loading"). Set `EMBER_MODEL_DIR` to run another weights
directory.

### Cloud

ember is Apple-Silicon-first locally, and supports NVIDIA GPUs for hosted deployment
(constitution Article VI, "Apple Silicon and CUDA") — three devices total: run it on an
Apple Silicon host with the memory above (MPS), on an NVIDIA GPU host (`EMBER_DEVICE=cuda`,
float16 — see "Hosted deployment: a model location supplied at start time" and
`deployment/README.md` for a full Outerbounds example), or on any host with the CPU fallback
(`EMBER_DEVICE=cpu` — float32, roughly twice the memory, much slower). The HTTP server binds
to loopback by default; to serve other machines set `EMBER_HOST` and set
`EMBER_SERVER_AUTH_TOKEN` to require `Authorization: Bearer <token>` (or any header name via
`EMBER_AUTH_HEADER`, e.g. `x-api-key`, on the client side). Ember does not terminate TLS —
front a remote-serving
deployment with a proxy. Clients point at it with `EMBER_SERVER_URL`. See
[COMPATIBILITY.md](COMPATIBILITY.md) and [SECURITY.md](SECURITY.md).

## Agent onboarding

Installing the tool is half the job; the other half is making agents **want** to consult it
at the right moments and read its answers sensibly. `ember/agent_kit/` ships that
guidance through every channel each agent actually reads:

| Channel | opencode | Kilo Code | Claude Code | Codex CLI | How you get it |
| --- | --- | --- | --- | --- | --- |
| MCP server instructions (when to consult, how to ask, how to read answers) | ✅ in the system prompt | ✅ in the system prompt | ✅ (2 KB cap) | — | built in, nothing to do |
| `ember://guide` resource (full playbook) | ✅ via `read_mcp_resource` | ✅ via `read_mcp_resource` | ✅ | — | built in |
| `ember-advise` skill (playbook, loaded on demand) | ✅ | ✅ | ✅ | ✅ | `ember agents install --agent <agent>` |
| AGENTS.md / CLAUDE.md policy block | ✅ | ✅ | ✅ (CLAUDE.md) | ✅ | `ember agents show snippet >> AGENTS.md` |

```bash
ember init --opencode                  # opencode: config entry, plugin, and skill
ember init --kilocode                  # Kilo Code: kilo.json entry and skill
ember init --codex                     # Codex CLI: .codex/config.toml entry and skill
ember agents install --agent claude    # .claude/skills/ember-advise/SKILL.md
ember agents install --agent codex     # .agents/skills/... (opencode reads this too)
ember agents show snippet >> AGENTS.md # then edit the project policy at the end
```

The skill is a playbook, not a reference card: the decision points worth consulting
ember about, copy-paste question sets for intent and readiness, failure triage, change
risk, routing, and effort, and starting confidence thresholds calibrated from observed model
output (re-measured whenever the pinned model revision changes). The snippet ends with a
**project policy** — edit it to wire ember into your own workflow, e.g. "check change
risk before every push".

Agent-specific notes:

- opencode reads skills from `.opencode/skills`, `.claude/skills`, and `.agents/skills`, so
  install one copy per project to avoid duplicate listings.
- Kilo Code: `ember init --kilocode` writes the `mcp.ember` entry to `kilo.json` (same
  config shape as opencode) and installs the skill to `.kilo/skills/ember-advise/SKILL.md`;
  the tool appears as `ember_advise`. Kilo Code also reads `AGENTS.md` automatically.
- Claude Code: register the server with `claude mcp add --scope user ember -- ember-mcp`
  (every project; drop `--scope user` to register it for the current project only); the
  tool appears as `mcp__ember__advise`. Or install the **ember plugin**, which bundles the
  MCP entry and the `ember-advise` skill (so skip `ember agents install --agent claude`):

  ```bash
  claude plugin marketplace add shapeandshare/ember
  claude plugin install ember@ember
  ```

  The plugin still runs the `ember-mcp` you installed with `uv tool install`, and its tool
  appears as `mcp__plugin_ember_ember__advise`. Use one route, not both, or the tool is
  listed twice.
- Codex CLI: `ember init --codex` writes `[mcp_servers.ember]` to `.codex/config.toml`
  (`--global`: `~/.codex/config.toml`, or `$CODEX_HOME/config.toml`)