mushi-mushi

<div align="center">

# Mushi Mushi

**Your AI wrote it. Mushi tells you why it broke.**

Plain-English diagnosis + a paste-ready fix, right inside Cursor and Claude Code. No log-reading. No second LLM API key for MCP.

**Fastest path — drop Mushi into your AI editor:**

```bash
npx mushi-mushi setup --ide cursor   # or: --ide claude
```

Already shipping an app? One command installs the SDK + env vars + an optional test report:

```bash
npx mushi-mushi
```

**Open source, self-hostable, MIT JS core** — bring your own LLM key, no second key for MCP, no lock-in. [Self-host in minutes](./SELF_HOSTED.md) · [licensing](https://kensaur.us/mushi-mushi/docs/concepts/open-source).

<sub>What is Mushi, exactly? Read the one-page constitution: **[VISION.md](./VISION.md)** — the single source of truth for positioning, the north-star sentence, and who this is for.</sub>

[![Add to Cursor](https://img.shields.io/badge/Add%20to-Cursor-0098FF)](https://kensaur.us/mushi-mushi/docs/connect)
[![Try the demo — no signup](https://img.shields.io/badge/Try%20the%20demo-no%20signup-E34234)](https://kensaur.us/mushi-mushi/docs/connect)
[![npm](https://img.shields.io/npm/v/@mushi-mushi/react?label=%40mushi-mushi%2Freact&color=cb3837)](https://www.npmjs.com/package/@mushi-mushi/react)
[![Server](https://img.shields.io/badge/server-AGPL--3.0-brightgreen.svg)](./packages/server/LICENSE)

<sub>Node ≥22 · [CI](https://github.com/kensaurus/mushi-mushi/actions/workflows/ci.yml) · SDK MIT · [enterprise](./packages/server/ee/README.md) · [Smithery](https://smithery.ai/servers/kensaurus/mushi-mushi)</sub>

[Vision](./VISION.md) · [Quick start](#60-second-proof) · [Connect your editor](https://kensaur.us/mushi-mushi/docs/connect) · [Self-host](#self-host-in-under-5-minutes) · [Sentry enrichment](#sentry-enrichment) · [Packages](#framework-coverage) · [Docs](https://kensaur.us/mushi-mushi/docs/) · [Live demo](https://kensaur.us/mushi-mushi/admin/) · [Operators / platform](./docs/operators/) · [Roadmap](https://kensaur.us/mushi-mushi/docs/roadmap)

<a href="https://kensaur.us/mushi-mushi/admin/reports" title="Open a classified report in the live demo">
  <img alt="Report detail — plain-English root cause, confidence chip, paste-ready Cursor fix prompt, and PDCA receipt strip." src="./docs/screenshots/report-detail-dark.png" width="100%" />
</a>

<sub>↑ the diagnosis: plain-English root cause + a paste-ready fix prompt · click to open the live demo</sub>

</div>

---

## 60-second proof

```bash
npx mushi-mushi
```

The wizard auto-detects your framework, installs the right SDK, writes framework-prefixed env vars (e.g. `VITE_MUSHI_PROJECT_ID` / `VITE_MUSHI_API_KEY`, or `NEXT_PUBLIC_MUSHI_*`) to `.env.local`, and prints the snippet to paste. Those two vars are **all the SDK needs** — no Supabase, no LLM key (see [`examples/sdk.env.example`](./examples/sdk.env.example); the root `.env.example` is for self-hosting the backend only). Then, the moment something breaks:

1. The bug lands in your queue — screenshot, the user's note, the route, the last console + network events, device context.
2. Mushi produces **the diagnosis**: a plain-English root cause + a fix you can paste.
3. You pull it into your editor over MCP:

```bash
npx mushi-mushi setup --ide cursor    # then ask Cursor: "what's broken in prod?"
```

**No Sentry, no account, no monitoring stack required to see value.** Self-host the whole thing in under five minutes, or use the free hosted tier (no card).

---

## What this is

For the solo AI-first builder (the _vibe coder_): you ship fast with Cursor, Claude Code, Lovable, or Bolt, then lose afternoons when something breaks in code you didn't fully write. Mushi is the **comprehension layer** — plain-English diagnosis in your editor over MCP, so a bug costs five minutes instead of your afternoon. (Small teams and agencies hit the same pain.)

These are the bugs your monitoring can't see, and the ones you didn't write:

- A user added a coupon and the pay button slipped under their keyboard.
- A new signup tapped _Save_ twice because nothing visibly happened the first time.
- A Pro customer's dashboard takes 12 seconds to load — and they've opened the competitor's tab.
- A layout that looks fine on your laptop folds in half on the one Android model used by 18% of your traffic.

## What it is not

Not another dashboard you have to go read, and not an enterprise monitoring stack — standalone first, no Sentry/Datadog/Firebase required. Full positioning: [`VISION.md`](./VISION.md).

---

## The diagnosis loop

When a user shakes their phone (or clicks the reporter):

1. **Capture** — screenshot, route, user note, recent console + network events, device context.
2. **Classify** — two-stage LLM tags severity, category, and a plain-English root-cause hint. The screenshot goes through an air-gapped vision pass that can't see the text prompt. A nightly judge scores the classifier and feeds a prompt-A/B loop.
3. **Connect** — the report embeds into a knowledge graph (Postgres + pgvector). The same broken button reported twenty times shows up as **one** row, not twenty.
4. **Fix** _(optional)_ — _Dispatch fix_ (or Slack / MCP / CI) runs an agent in a sandbox, runs your tests, and opens a **draft** PR. You review it like any other PR.

```mermaid
flowchart LR
    subgraph App["Your app"]
        SDK["mushi-mushi/{react, vue, svelte, angular, …}<br/>shadow-DOM widget · screenshot · console · network"]
    end
    subgraph Edge["Supabase Edge (Hono gateway + ~50 functions)"]
        API["api"]
        FF["fast-filter"]
        CR["classify-report<br/>+ vision + RAG"]
        ORCH["fix-worker"]
    end
    subgraph DB["Postgres + pgvector"]
        REP["reports"]
        KG["knowledge graph"]
        FIX["fix_attempts"]
    end
    subgraph Agents["mushi-mushi/agents"]
        SBX["sandbox: e2b / modal / cloudflare"]
        GH["GitHub PR"]
    end
    SDK -->|HTTPS| API
    API --> FF --> CR
    CR --> KG
    CR --> REP
    REP --> ORCH --> Agents
    Agents --> GH
```

The architecture, sequence diagram, and component-by-component spec live in [`apps/docs/content/concepts/architecture.mdx`](./apps/docs/content/concepts/architecture.mdx).

---

## Self-host in under 5 minutes

A single Docker Compose file gets you a working stack against your own Supabase project:

```bash
cd deploy
cp .env.example .env   # ANTHROPIC_API_KEY, Supabase creds
docker compose up -d
```

[`SELF_HOSTED.md`](./SELF_HOSTED.md) and the [Self-host in minutes](https://kensaur.us/mushi-mushi/docs/self-hosting/docker-compose) guide are the long-form walkthroughs. A **Helm chart** lives at [`deploy/helm/`](./deploy/helm/README.md) — one `helm install` on any cluster.

**Hosted:** sign up at [`kensaur.us/mushi-mushi/`](https://kensaur.us/mushi-mushi/), click _Start free, no card_, create a project, and copy your `projectId` + `apiKey`. The free tier covers 50 diagnoses a month (no card required).

> **One BYOK rule, both ways.** Self-host and you bring your own Anthropic / OpenAI key — you pay the vendor at list rate, we never mark up a token. On hosted you bring no key at all: we meter by **diagnosis** (the plain-English root cause + fix), never by tokens, with a per-project **spend cap** and **50 / 80 / 100% alerts** so the bill can't surprise you. Full numbers: [pricing](https://kensaur.us/mushi-mushi/docs/pricing).

> **Internal edge functions** (`fast-filter`, `classify-report`, `fix-worker`, `judge-batch`, `intelligence-report`, `usage-aggregator`, `generate-synthetic`) authenticate via `requireServiceRoleAuth`. Never expose them with `--no-verify-jwt`. Only the public `api` function should face the internet — see [`packages/server/README.md`](./packages/server/README.md#internal-caller-authentication-sec-1).

---

## Sentry enrichment

Mushi works standalone. If you already run Sentry, Mushi enriches it: Sentry owns "errors your code throws"; Mushi owns the bugs that *don't* throw (dead buttons, 12-second screens, layouts that break on one phone) and the **plain-English diagnosis + fix** Sentry's $80/mo Seer tier reserves for bigger teams.

Inbound adapters forward Sentry (and Datadog, Bugsnag, Rollbar, Crashlytics, New Relic, Honeycomb, Grafana Loki, CloudWatch, Opsgenie, Firebase) alerts into Mushi for deeper fix context; outbound plugins send Mushi's verdicts back so a Sentry issue auto-resolves the moment Mushi merges its fix. The full enrichment / synthesis story lives in [`docs/operators/`](./docs/operators/#where-mushi-fits) — it's the upgrade path, never the front door.

| | Mushi | Sentry | Langfuse |
| --- | --- | --- | --- |
| Catches | Thrown errors **and** silent UX bugs (dead clicks, slow screens, layout breaks) | Thrown errors, performance traces | LLM call traces, prompt evals |
| Output | Plain-English root cause + paste-ready fix, in your editor | Stack trace + breadcrumbs, in a dashboard | Trace tree + scores, in a dashboard |
| Auto-fix | Optional: sandbox agent opens a draft PR | Seer add-on (paid) | Not in scope |
| Second LLM key for MCP | No — reuses your app's key | N/A | N/A |
| Setup | One command, no account required to try | SDK + DSN + dashboard | SDK + project + dashboard |

Different jobs: Sentry watches what your code throws, Langfuse watches what your LLM calls do, Mushi watches what your *user* experiences — including the bugs that never throw.

---

## Framework coverage

Most developers install **one** SDK — `npx mushi-mushi` picks it for you. React/Next.js quick start:

```bash
npm install @mushi-mushi/react      # also covers Next.js
```

```tsx
import { MushiProvider } from '@mushi-mushi/react';

function App() {
  return (
    <MushiProvider config={{ projectId: 'proj_xxx', apiKey: 'mushi_xxx' }}>
      <YourApp />
    </MushiProvider>
  );
}
```

<details>
<summary><b>Other frameworks</b> — Vue, Svelte, Angular, React Native, Vanilla JS, iOS, Android, Flutter</summary>

```ts
// Vue 3 / Nuxt
import { MushiPlugin } from '@mushi-mushi/vue'