ember

A gut feeling for coding agents. AI coding assistants like Claude Code, Codex, opencode, and Kilo Code constantly have to decide: start now or ask a question first? Is this test failure real? Is this change safe to push? ember is a small add-on that gives them a quick second opinion at those moments, as a number ("93% likely this needs review"), so they stop interrupting you needlessly and stop making risky changes without asking. You don't call it yourself; your assistant does. It's free and open source, and you choose where the model runs: on your Apple Silicon Mac (32 GB of memory or more, a one-time ~18 GB download), on a server you host, or on one your team already runs. ember advises; the agent decides.

Under the hood, ember runs Cloudflare's Clef-Flash decision model, from its public Hugging Face repo, and exposes it as one MCP tool, advise, that returns a calibrated probability for every option.

Website: shapeandshare.github.io/ember

Ways to run ember

All three are supported equally; ember init asks which one you want.

Nothing is ever sent to a server you didn't configure. Without a terminal to ask (a script, CI), ember init sets up local inference; --local or --server-url answer the question up front.

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:

• 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

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

A hosted deployment (e.g. Outerbounds) 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

Tested versions and hardware are in COMPATIBILITY.md. Current accuracy and latency, from the latest tracked benchmark run, are on the benchmark report.

Install (Apple Silicon)

Requirements

To use a server someone else runs, you need only Python 3.12 (managed by uv) and the server's address; skip ember model pull. To run the model yourself:

• 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), 96 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.

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):

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

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.16.0.

If you manage Python with conda, mamba, or pixi, install the same tool from the interim joshburt channel on Anaconda.org (it moves to conda-forge once that feedstock lands):

conda install -c joshburt -c conda-forge ember-advise   # mamba and pixi take the same flags

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):

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 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 (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 and 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:

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):

  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) and installs the skill to .agents/skills/ember-advise/SKILL.md. Codex loads a project .codex/config.toml o