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

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

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

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 · licensing.

_{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.}

Vision · Quick start · Connect your editor · Self-host · Already on Sentry? · Packages · Docs · Live demo · Operators / platform · Roadmap

<!-- TODO(loop-video): embed the 20–30s incident-loop gif when recut (docs/screenshots/incident-loop.gif). Until then the static diagnosis screenshot above shows error → diagnosis → fix. Script + target metric (time-to-first-diagnosis < 2 min) in docs/marketing/STOREFRONTS.md. -->

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

_{↑ the diagnosis: plain-English root cause + a paste-ready fix prompt · click to open the live demo}

</div>

60-second proof

npx mushi-mushi

The wizard auto-detects your framework, installs the right SDK, writes MUSHI_PROJECT_ID + MUSHI_API_KEY to .env.local, and prints the snippet to paste. 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 ready-to-apply fix.
3. You pull it straight into your editor over MCP and paste the fix:

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

• Built for the solo, AI-first builder — the _vibe coder_. You ship fast with Cursor, Claude Code, Lovable, or Bolt to real users, then lose afternoons when something breaks in code you didn't fully write. (Small teams and agencies feel the same pain — it works for them too.)
• The comprehension layer for AI-built apps. AI lets you ship in an afternoon. But when it breaks, you're alone with a stack trace for code you didn't really write. Mushi makes understanding the bug as fast as creating the feature that caused it.
• It pays the momentum tax for you. A two-hour incident shouldn't eat your whole day — the real cost is the flow state you lose. Mushi turns "something broke" into "here's exactly why, and here's the fix" so a bug costs you five minutes, not your afternoon.
• It lives in your editor. Plain-English diagnosis + a paste-ready fix arrive over MCP inside Cursor / Claude Code — no dashboard to go read, no second LLM key for MCP.

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. The answer comes to your editor.
• Not an enterprise monitoring stack. No Sentry/Datadog/Firebase required to get value — standalone first.
• Not something you configure for an afternoon. One command in, diagnosis out.

The diagnosis loop

When a user shakes their phone (or clicks the reporter), four things happen in the order a careful colleague would do them:

1. Capture. The widget grabs the screenshot, the route, the user's note, the last few console + network events, and the device context.
2. Classify. A two-stage LLM pipeline 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, so a malicious screenshot can't inject one. A nightly judge scores the classifier's own work 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._ Click _Dispatch fix_ (or from Slack / MCP / CI) and an agent in a sandbox tries the change, runs your tests, and opens a draft PR. You review it like any other PR — merge, edit, or close.

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.

Self-host in under 5 minutes

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

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

SELF_HOSTED.md and the Self-host in minutes guide are the long-form walkthroughs. A production-ready Helm chart lives at deploy/helm/ — one helm install on any cluster.

Hosted (zero-config). Prefer we run it? Sign up at 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.

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.

Already on Sentry?

You don't need it — Mushi works standalone — but if you already run it, 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/ — it's the upgrade path, never the front door.

Framework coverage

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

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

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>

// Vue 3 / Nuxt
import { MushiPlugin } from '@mushi-mushi/vue';
app.use(MushiPlugin, { projectId: 'proj_xxx', apiKey: 'mushi_xxx' });

// Svelte / SvelteKit
import { initMushi } from '@mushi-mushi/svelte';
initMushi({ projectId: 'proj_xxx', apiKey: 'mushi_xxx' });

// Angular 17+
import { provideMushi } from '@mushi-mushi/angular';
bootstrapApplication(AppComponent, { providers: [provideMushi({ projectId: 'proj_xxx', apiKey: 'mushi_xxx' })] });

// React Native / Expo
import { MushiProvider } from '@mushi-mushi/react-native';

// Vanilla JS / any framework
import { Mushi } from '@mushi-mushi/web';
Mushi.init({ projectId: 'proj_xxx', apiKey: 'mushi_xxx' });

iOS (Swift PM, v0.4.0): .package(url: "https://github.com/kensaurus/mushi-mushi.git", from: "0.4.0") · Android (Gradle): dev.mushimushi:mushi-android:0.4.0 · Flutter: pub add mushi_mushi.

</details>

Want a runnable example? examples/react-demo is a minimal Vite + React app with test buttons for dead clicks, thrown errors, failed API calls, and console errors.

<details> <summary><b>All packages</b> — SDKs, plugins, adapters, and backend</summary>

Backend packages — @mushi-mushi/server, @mushi-mushi/agents, @mushi-mushi/verify (AGPLv3) — power the classification pipeline, knowledge graph, fix dispatch, and Playwright verification. Plugins: Jira, Slack, Linear, PagerDuty, Zapier, Sentry, Discord, MS Teams, GitHub Issues, Bugsnag, Rollbar, Crashlytics, Cursor Cloud. Inventory tooling: inventory-schema, inventory-auth-runner, eslint-plugin-mushi-mushi, mcp-ci.

</details>

Where it stops

Mushi is honest about what's still partial. Skim before you commit:

Running this for a team?

The platform depth — inbound adapters, outbound plugins, A2A / AG-UI / MCP interop, the inventory.yaml QA-gate system, the synthetic monitor, SSO / audit / retention / region pinning, and open-standards plumbing — lives in [`docs/operators/`](./docs/operators/) so the front door stays on the wedge. Start there if you're wiring Mushi into an existing stack or evaluating it as a platform.

Cursor & Claude Skills

Install Mushi skills in your Cursor or Claude Code project for one-command setup, usage, and debugging:

npx skills add kensaurus/mushi-mushi

Then: /mushi-setup (guided SDK install + MCP wiring), /mushi-debug (diagnose ingest / MCP / pipeline failures), /mushi-health (pass/fail check across CLI, API, edge functions, BYOK keys). The admin Connect & Update page (/connect) mirrors the same flows with one-click Add to Cursor deeplinks.

_{Repo at a glance (run pnpm docs-stats): ~339K TS lines · 1,610 source files · 44 workspace / 36 npm packages · 51 edge functions · 298 SQL migrations · 19 pipeline agents. Full tour: docs/SCREENSHOTS.md.}

Contributing

Issues and PRs welcome:

git clone https://github.com/kensaurus/mushi-mushi.git
cd mushi-mushi
pnpm install
pnpm dev

Requires Node.js ≥ 22 and pnpm ≥ 10. See individual package READMEs, docs/stats.md for canonical counts, and CONTRIBUTING.md.

License & branding

This repository is open-core — the Supabase / Grafana model. The SDK packages are MIT — use them in any product, open or closed. The server (the part you self-host or we run for you) is AGPLv3 — true OSI open source: self-host it, fork it, modify it for your own org. If you offer a modified server as a hosted service to third parties, publish your changes or see COMMERCIAL-LICENSE.md. A small Enterprise Edition boundary (packages/server/ee/) is source-available but commercial for production use — that's operator/enterprise plumbing only, never the wedge.

Security researchers: see SECURITY.md for the threat model, PII commitments, and safe-harbor terms.

Also by @kensaurus

Other free apps and tools from the same Tokyo studio:

<div align="center"> _{If Mushi-chan helped, drop a ⭐ — next devs find the repo faster that way. <a href="https://github.com/kensaurus/mushi-mushi/stargazers">Star the repo</a> · <a href="https://github.com/kensaurus/mushi-mushi/issues/new/choose">Open an issue</a> · <a href="https://bsky.app/profile/mushimushi.dev">Follow on Bluesky</a>} </div>