Mushi Mushi README

Mushi Mushi

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

A user says your app is broken. Mushi Mushi tells you why in plain English and hands the fix to Cursor, Claude Code or Lovable. No Sentry or monitoring needed.

TerminalCopy

npx mushi-mushi

See a sample diagnosis → No signup, nothing to install.

_{Built for the vibe coder who ships fast with Cursor, Claude Code, Lovable or Bolt. No terminal? Add it to Lovable or Bolt with one prompt.}

Quick start · How it works · Docs · Sample diagnosis · Why not Sentry? · Self-host · Vision

_{↑ reports in the Mushi Mushi console, each with a plain-English summary. Click for one full sample diagnosis you can read without signing up.}

How it works

_{↑ Short videos that show every click: a user reporting a bug, the diagnosis, connecting your editor, and the fix shipping. Watch them on How it works.}

flowchart LR
    U["Your users<br/>tap the bug widget"] --> M
    S["Your monitoring<br/>Sentry, Crashlytics… (optional)"] -.-> M
    M["Mushi Mushi<br/>one queue · diagnosis · fix"] --> E["Your editor or agent<br/>Cursor, Claude Code (MCP)"]
    E --> P["Draft PR<br/>you review it"]
    P --> R["Release<br/>report closes, user is told"]

1. Capture. A user taps the widget. Mushi Mushi records a screenshot, the route, their note, and the last console and network events.
2. Diagnose. Mushi Mushi writes the root cause in plain English with a fix prompt. Twenty reports of the same broken button become one row.
3. Fix. Your editor reads the diagnosis over MCP and makes the fix with its own model. If you prefer, an agent opens a draft PR that you review like any other. On hosted Mushi Mushi the built-in fixer needs no key of your own; Cursor's agents need your Cursor key; or run fixes on your own computer with the Mushi Mushi worker. With your own Anthropic or OpenAI key, a second AI (Claude Opus, or GPT on an OpenAI key) reviews each agent PR first. Mushi Mushi will not merge a PR it says to hold unless you override it in the console and give a reason.

It catches the bugs that never throw an error: the pay button hidden under the keyboard, the Save button tapped twice because nothing happened, the dashboard that takes 12 seconds.

Quick start

npx mushi-mushi                      # detects your framework, installs the SDK, writes env vars, sends a test report

Then connect your editor so it can read diagnoses: one click on the Connect page, or npx mushi-mushi setup --ide cursor (or --ide claude). Ask it: "Get the latest Mushi Mushi report and fix it."

Building in Lovable or Bolt, with no terminal? Paste one script tag through your prompt instead: Mushi Mushi in Lovable or Bolt.

The SDK needs two env vars (VITE_MUSHI_PROJECT_ID / VITE_MUSHI_API_KEY, or NEXT_PUBLIC_MUSHI_*; see examples/sdk.env.example). No Sentry, no LLM key, no monitoring stack. The hosted free plan covers one app and 100 diagnoses a month, with no card and no AI key of your own (pricing). Or you can self-host.

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

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

import { MushiPlugin } from '@mushi-mushi/vue';        // Vue 3 / Nuxt: app.use(MushiPlugin, { projectId, apiKey })
import { initMushi } from '@mushi-mushi/svelte';       // Svelte / SvelteKit: initMushi({ projectId, apiKey })
import { provideMushi } from '@mushi-mushi/angular';   // Angular 17+: providers: [provideMushi({ projectId, apiKey })]
import { MushiProvider } from '@mushi-mushi/react-native';
import { Mushi } from '@mushi-mushi/web';              // any framework: Mushi.init({ projectId, apiKey })

Who it's for

• You build apps with AI, mostly on your own. You use Lovable, Bolt, Cursor or Claude Code, your app has real users, and you didn't write most of the code by hand. When someone says "it's broken", Mushi Mushi tells you the likely cause in plain English and gives your editor a fix prompt.
• You're a developer and you own your code. You read the diffs and may already run Sentry. User reports and Sentry errors land in one list with duplicates merged, and an agent's fix gets a second AI review before it can merge.
• You run a team. Reports arrive from the app, Sentry, store reviews and Slack, and nobody sees all of them. Here they share one list, each with a diagnosis, and they can go on to Linear, Jira or GitHub Issues.

The pains each group has, and where each should start: who it's for.

What's inside

Full list and maturity: SDK reference. Architecture: how the pipeline fits together.

What else it does

Most bugs never get reported. People just leave. So beyond the reports people send, Mushi Mushi can look for bugs itself and check the fixes. Each of these is off until you switch it on, and several need your own key.

A "fix first" review can go back to the agent with its findings, at most twice per PR. That is off by default and uses your organization's Cursor key (agent PR review, CI runners). Every feature, with what it solves: what else it does.

Why not just Sentry?

Sentry is built around what the code threw, with a User Feedback widget and replay alongside. Mushi Mushi starts from what the user reported, ingests Sentry's errors too, explains each one in plain English, and hands your agent a fix prompt to start from. One queue, with or without Sentry.

It works with what you already run. Point a Sentry alert webhook at /v1/webhooks/sentry?projectId=<id> and errors land in the same queue. Merging a Mushi Mushi fix resolves the Sentry issue, and the reverse. Adapters also bring in Datadog, Bugsnag, Rollbar, Crashlytics and others. Plugins keep Linear, Jira, GitHub Issues, Slack, Discord, Teams and PagerDuty in sync. Nothing gets ripped out. Details: Sentry vs Mushi Mushi.

Self-host

cd deploy && cp .env.example .env   # add ANTHROPIC_API_KEY and your Supabase credentials
docker compose up -d

Walkthroughs: SELF_HOSTED.md and Docker Compose guide. Self-hosting is bring-your-own-key: you pay your LLM vendor at list price. The hosted service needs no key; it bills per diagnosis with a spend cap (pricing). Teams wiring Mushi Mushi into an existing stack (SSO, retention, region routing, Kubernetes) start at docs/operators/. Only the public api function should face the internet: see internal caller authentication.

Where it stops

_{Repo at a glance (run pnpm docs-stats): ~620K TS lines · ~2,700 source files · 45 workspace / 37 npm packages · 77 edge functions · 547 SQL migrations · 19 pipeline agents. Full tour: docs/SCREENSHOTS.md.}

Community and contributing

Questions and show-and-tell: GitHub Discussions. Bugs: Issues (first reply within 24 hours on weekdays). Security: SECURITY.md. Anything else private: kensaurus@gmail.com.

git clone https://github.com/kensaurus/mushi-mushi.git && cd mushi-mushi
pnpm install && pnpm dev   # Node ≥ 22, pnpm ≥ 10

See CONTRIBUTING.md and docs/stats.md.

License

Open core. Each package directory's own LICENSE governs that package; the root LICENSE states the split.

Self-hosting is free and complete: the repo has every feature and working default prompts. Mushi Mushi Cloud runs the same code and keeps its own tuning data (prompt wording, evaluation sets and scoring weights tuned on live traffic) as configuration. Contributions come in under a CLA. Why it is set up this way: ADR 0036. Third-party notices: NOTICE.

More apps from the same maker

	App	What it is
	glot.it	Learn Thai — bite-size lessons, smart flashcards, and an AI tutor
	yen-yen	Where did the money go? Now you'll know. A kakeibo for households
	the wanting mind	How the Battle Between Extraction and Generation Is Reshaping Our World — a 147,000-word interactive webbook with 268 concepts, 242 citations, and original illustrations
	help her take photo	Pair phones, direct the pose, nail the photo
	lets-talk	Practice hard conversations before you have them
	一人社長 Solo Boss	Bookkeeping and tax-filing co-pilot for one-person companies in Japan — Free tools
	Tsumagoi Work&Camp	A 24-hour mountain lounge at 1,444 m; guests sleep in their own car or tent — Book a stay · Instagram · Facebook · Maps
	kenji skills	Agent skills and slash commands for Claude Code, Cursor, Codex, and Gemini — Getting started
	kensaur.us	All apps from the same maker

The list comes from https://kensaur.us/apps.json (kensaurus/kensaur.us src/data/family.json).