---
url: https://docs.mochiexec.io/guides/ai.md
description: >-
  Use AI in Mochi to describe, explain, and diagnose executables, get insights
  from run history, and chat with tool access to your workspaces, using your own
  key, a local model, or Mochi's gateway.
---

# AI

Mochi's AI works on the things it already knows about: your executables, their scripts,
and their run history. It is **optional**, and you choose where the requests go.

* **Describe and document**: write the missing one-line descriptions across a workspace.
* **Explain**: say in plain English what an unfamiliar executable does, and what to watch
  out for before running it.
* **Diagnose**: read a failed run's output with the executable that produced it, and report
  the likely cause, the evidence, and what to try.
* **Insights**: turn success rates and durations into prioritized recommendations.
* **Chat**: ask questions and let the model look things up (and, with your approval, run
  them) through Mochi's own tools.

## Where requests go

```mermaid
flowchart LR
  cmd["mochi ai …<br/>or the desktop app"] --> cfg{"Active provider"}
  cfg -- "mochi-gateway" --> gw["Mochi gateway<br/>license-gated, metered"]
  cfg -- "openai · anthropic · gemini" --> byok["Your provider<br/>your API key"]
  cfg -- "ollama" --> local["Local model<br/>nothing leaves the machine"]
  cfg -- "custom" --> custom["Any compatible endpoint"]
```

API keys are stored in a vault, not in a plain config file.

## Choose a provider

```sh
# Your own key: asks for it at a masked prompt (or pass --api-key-file)
mochi ai config set provider anthropic --model <model-name>

# A local model through Ollama
mochi ai config set provider ollama --model <model-name>

# Mochi's managed gateway (uses your license)
mochi ai config set provider mochi-gateway

# Check it works
mochi ai config test
```

See [AI Providers](/reference/ai-providers) for every provider and option.

## Commands

| Command | Does |
|---|---|
| `mochi ai describe <verb> <id>` | One-line description for an executable |
| `mochi ai document [workspace]` | Descriptions for every undescribed executable. `--write` saves them into the flow files. |
| `mochi ai explain <verb> <id>` | Plain-English walkthrough of an executable |
| `mochi ai diagnose <run-id>` | Likely cause and fixes for a failed run |
| `mochi ai insights [workspace]` | Recommendations from run statistics |
| `mochi ai chat [prompt]` | Ask a question with tool access to your workspaces |
| `mochi ai usage` | Gateway usage for your license; `usage local` for your own providers |

## What chat is allowed to do

`mochi ai chat` gives the model a **tool tier**, and you choose the highest one it gets:

| Tier | Adds |
|---|---|
| `read-only` | Lookups only |
| `caution` | Non-destructive state changes |
| `edit` | Writing flow and workspace files |
| `full` | Running commands |

```sh
mochi ai config set tools --tier edit
```

Writing files and running commands always ask for confirmation first, whatever the tier.

## Usage and credits

With the Mochi gateway, AI requests draw on your license's credit balance.
`mochi ai usage` shows requests, tokens and credits remaining, and so does **Settings →
AI & Integrations → Usage** in the desktop app.

When the credits run out, AI features stop with **AI credits used up** until your balance
is topped up. Switching to your own provider key keeps them working in the meantime.
Sending many requests in a short time can return **Too many AI requests**; wait a moment
and try again.

Requests through your own keys or a local model aren't metered by Mochi.
`mochi ai usage local` shows what they used, by provider and model, and
`mochi ai config set usage` sets how long that log is kept.