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:

Terminal

Copy

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

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

Terminal

Copy

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 — the single source of truth for positioning, the north-star sentence, and who this is for.}

_{Node ≥22 · CI · SDK MIT · enterprise · Smithery}

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

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

60-second proof

Using Cursor, Claude Code, or another AI editor? Paste this prompt and your agent does the whole setup — install, wiring, and a verified test report:

Install the Mushi skills from github.com/kensaurus/mushi-mushi (npx skills add kensaurus/mushi-mushi), then run the mushi-setup skill to wire the Mushi SDK and MCP server into this app and send a test report to verify the connection.

Or run the wizard yourself:

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

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.

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.

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 Helm chart lives at deploy/helm/ — one helm install on any cluster.

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

Why not just Sentry?

The question every team asks, answered once:

Sentry tells you what threw. Mushi ingests that — plus the bugs that never throw — explains each one in plain English, and closes the loop with a fix your agent can ship. One queue, one audit trail, with or without Sentry.

Mushi works standalone. If you already run Sentry, point a Sentry issue-alert webhook at /v1/webhooks/sentry?projectId=<your-project> and errors land in the same queue as user reports — deduped per Sentry issue, triaged in plain English, fix-dispatchable from the console, Slack, or your editor. The loop closes both ways: merging a Mushi fix resolves the linked Sentry issue, and resolving in Sentry resolves the linked report. A repeat alert on a fixed report reopens it as a regression instead of filing a duplicate.

Beyond Sentry, inbound adapters translate Datadog, Bugsnag, Rollbar, Crashlytics, New Relic, Honeycomb, Grafana Loki, CloudWatch, Opsgenie, and Firebase alerts into the same queue; outbound plugins keep Linear, Jira, GitHub Issues, Slack, Discord, Teams, and PagerDuty in sync. Nothing gets ripped out — Mushi is the mediator between what you already run. Operator-depth (SSO, retention, region routing): docs/operators/.