mushi-mushi 🐛

Ship a shake-to-report button. Get AI-classified, deduped, ready-to-fix bug reports.

One npx command. Works with React, Next.js, Vue, Nuxt, Svelte, SvelteKit, Angular, React Native, Expo, Capacitor, and vanilla JS.

↑ a real user report, fully classified and ready to dispatch as a GitHub PR · open the live demo

What does it actually do? (60 seconds, no jargon)

Your users open your app, something feels broken — a button that doesn't react, a page that takes forever, a layout that folds in half on their phone — and they leave. Your error tracker stays silent because nothing technically crashed.

Mushi adds a small "shake your phone (or click the bug)" button. The user taps it, scribbles a note, and Mushi captures everything around the moment: a screenshot, the page they were on, what they were trying to do, and the last few seconds of network and console activity. An AI then reads that report, tags it with severity and category in plain English, groups it with similar reports so you see one row per actual bug, and (optionally) hands it off to another AI that opens a draft pull request with a proposed fix. A human always reviews and merges — the loop never bypasses you.

Founders, PMs, designers: see the 60-second tour in the GitHub README.

Install in one line

npx mushi-mushi

The wizard detects your framework, installs the right SDK, writes env vars to .env.local (with the right prefix — NEXT_PUBLIC_, NUXT_PUBLIC_, or VITE_), and prints the snippet to paste into your app. Non-destructive: never overwrites existing env vars, never edits your source.

// After the wizard runs (React example):
import { MushiProvider } from '@mushi-mushi/react';

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

That's it. Your users now have a shake-to-report button (or a floating widget). Reports land in your admin console, classified by an LLM within seconds.

What you get

• Shake-to-report widget — Shadow-DOM, zero CSS conflicts. Ships with screenshot, console ring, network ring, route + intent capture, and an offline queue.
• AI-classified reports — 2-stage pipeline (Haiku fast-filter → Sonnet deep + vision + RAG) tags each report with category, severity, confidence, and the component path. Stage 2 streams partial results to the admin UI as tokens arrive.
• Dedup by meaning, not by string — pgvector knowledge graph collapses duplicate reports across users, routes, and deploys so your queue isn't a noise storm.
• Bidirectional inventory (v2) — opt in to capture: { discoverInventory: true } and the SDK quietly observes routes, data-testids, and outbound API paths in production. Claude drafts an inventory.yaml of user stories + pages + actions for you to accept — most teams will never hand-author one.
• Five pre-release gates (v2) — mushi-mushi/no-dead-handler, mushi-mushi/no-mock-leak, inventory drift, agentic-failure detection, synthetic walk health. One composite GitHub status check via the Mushi Mushi CI Gate Action.
• Spec-traced fixes (v2.10) — every dispatched fix carries the inventory Action it's meant to repair, the expected_outcome contract is rendered into the LLM prompt, a deterministic validateAgainstSpec gate fires before the PR opens, and a targeted synthetic probe runs the moment the PR lands.
• One-click "Dispatch fix" — agentic orchestrator opens a GitHub PR with a screenshot diff and a Playwright replay. Sandbox-pluggable (e2b, modal, cloudflare, or your own).
• Standards-first integrator — W3C traceparent end-to-end, Standard Webhooks signing on every outbound delivery, RFC-draft Idempotency-Key middleware, OAuth 2.0 Dynamic Client Registration, OTLP/HTTP+JSON BYOK exporter. You bring your own observability stack — Mushi never marks up tokens.
• Agent-native via MCP + A2A — MCP Streamable HTTP at /functions/v1/mcp, A2A v1.0.0 tasks at /v1/a2a/tasks (pull SSE and push notifications), Agent Card discovery, OpenAPI 3.1 spec. Cursor, Claude Code, Copilot, OpenAI Agents SDK, LangGraph, CrewAI all see the same surface.

Who it's for

| You are… | …and this helps because | | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | A solo dev / small team shipping a consumer app | You already have Sentry for crashes — but users drop off over friction, not exceptions. Mushi captures "this button doesn't do anything". | | A PM or designer living in the admin | Triage, severity, component ownership, and PR status — all in one dark-mode console. No reading stack traces. | | An AI-native team already using Cursor / Claude | MCP tools expose the whole loop to your agent. get_recent_reports, classify, dispatch_fix — the same primitives your teammates use. | | An enterprise needing SOC 2 + residency | Region-pinned data (US / EU / JP / SELF), SAML SSO, audit-log ingest, DSAR workflow, HMAC-signed plugin webhooks. |

Mushi vs your existing stack

Mushi is a companion to Sentry/Datadog, not a replacement. It sees the bugs your crash tracker can't.

| Scenario | Sentry / Datadog | Mushi Mushi | | --------------------------------------- | :--------------: | :-------------: | | Unhandled JS exception | ✅ | ✅ | | Button that looks clickable but isn't | — | ✅ | | 12-second page load, no error thrown | — | ✅ | | User can't find the settings panel | — | ✅ | | Layout broken on iPad Safari only | — | ✅ | | Form submits but data doesn't save | ~ | ✅ | | Feature silently regressed last deploy | ~ | ✅ | | LLM-classified + deduped queue | — | ✅ | | One-click AI fix → draft GitHub PR | — | ✅ |

Already have Sentry? Mushi writes breadcrumbs into your existing Sentry session so you can jump from a crash to the user's own words in one click.

Integrates with

13 outbound plugins — Mushi sends signals to whatever your team already lives in:

11 inbound adapters — Mushi receives alerts from your existing monitoring and turns them into the same triaged report rows as user-felt bugs:

Sentry · Datadog · Bugsnag · Rollbar · Firebase Crashlytics · New Relic · Honeycomb · Grafana Loki · AWS CloudWatch · Opsgenie · Firebase Analytics

All of them ship in @mushi-mushi/adapters — drop them into any Node webhook server (Express / Fastify / Hono / serverless function).

Framework support

| Framework | Install after wizard (automatic) | | ------------------------------- | ------------------------------------------------- | | React | @mushi-mushi/react | | Next.js | @mushi-mushi/react | | Vue 3 / Nuxt | @mushi-mushi/vue + @mushi-mushi/web | | Svelte / SvelteKit | @mushi-mushi/svelte + @mushi-mushi/web | | Angular 17+ | @mushi-mushi/angular + @mushi-mushi/web | | React Native / Expo | @mushi-mushi/react-native | | Capacitor / Ionic | @mushi-mushi/capacitor | | Flutter / Dart | pub add mushi_mushi | | iOS native (Swift) | Swift Package Manager — early dev | | Android native (Kotlin/Java) | Gradle dev.mushimushi:mushi-android — early dev | | Node (Express / Fastify / Hono) | @mushi-mushi/node (server-side error capture) | | Vanilla JS | @mushi-mushi/web |

Prefer to skip the wizard? npm i @mushi-mushi/react (or your framework's package) and wire it up by hand.

How the pipeline works

User hits widget ──▶ screenshot + console + network + intent
        │
        ▼
  Fast-filter (Haiku)  ──▶  drops spam, keeps signal
        │
        ▼
  Deep classify (Sonnet + vision + RAG)  ──▶  category, severity, component
        │
        ▼
  Dedup (pgvector)  ──▶  groups repeat reports by meaning
        │
        ▼
  Judge (weekly)  ──▶  scores classifier, retrains prompts
        │
        ▼
  "Dispatch fix"  ──▶  agent opens a GitHub PR with Playwright replay + visual diff

See the full architecture in the root README.

30-second quick start

# 1. Drop the wizard in (or one of the equivalents below)
npx mushi-mushi

# equivalents:
npm create mushi-mushi
npx @mushi-mushi/cli init

npx mushi-mushi --framework next               # skip framework detection
npx mushi-mushi --project-id proj_xxx --api-key mushi_xxx
npx mushi-mushi --skip-install                 # print the install command, don't run it
npx mushi-mushi --skip-test-report             # don't offer to send a test report
npx mushi-mushi --cwd apps/web                 # run inside a monorepo sub-package
npx mushi-mushi --endpoint https://mushi.your-company.com   # self-hosted
npx mushi-mushi -y                             # accept the detected framework
npx mushi-mushi -v                             # print version
npx mushi-mushi --help

• Wrong framework detected? Pass --framework <id>. Valid values: next, react, vue, nuxt, svelte, sveltekit, angular, expo, react-native, capacitor, vanilla.
• Monorepo? cd into the package first, or pass --cwd apps/web.
• Stale npx cache? npm cache clean --force or npx mushi-mushi@latest.
• Non-interactive terminal (CI)? Pass --yes --project-id proj_xxx --api-key mushi_xxx. The wizard exits with a clear error instead of hanging.
• Node version too old? Requires Node ≥ 18. Upgrade at nodejs.org.
• Full stack traces on error? DEBUG=mushi npx mushi-mushi.

• Credentials passed via --api-key are visible to other users on the same machine via ps -ef. Use the interactive prompt on shared hosts.
• ~/.config/mushi/config.json (the credentials cache) is written with mode 0o600 on Unix; legacy ~/.mushirc auto-migrates on first load.
• The wizard rejects pasted secrets containing CR/LF/NUL to prevent .env injection.
• All prompts validate format: proj_[A-Za-z0-9_-]{10,} and mushi_[A-Za-z0-9_-]{10,}.
• This release ships with npm provenance — verify with npm audit signatures.

Mushi is a CLI launcher — it spawns one npm install and writes one .env.local line. Here's what each scanner shows and why:

| Scanner | What it shows | What it actually means | | ------------------ | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | npm provenance | ✅ Signed by kensaurus/mushi-mushi @ master | Cryptographic Sigstore attestation — npm audit signatures will verify this build came from this exact commit on this exact CI workflow. | | Socket.dev | Score + a few low-signal alerts | Alerts are expected and benign: child_process.spawn (used to invoke npm install), process.env (read DEBUG, npm_config_*), URL strings (printed in help text). All visible in src/index.ts — ~150 LOC, easy to audit. | | Bundlephobia | ❌ EntryPointError | Expected. This is a CLI (bin only — no main/module/exports), so there is no importable bundle to measure. Bundlephobia only works for libraries you import. | | Snyk Advisor | Health score (lower right after publish) | Snyk's crawler often lags by 1–2 weeks for new public packages — score corrects itself once it picks up the actual package.json (CONTRIBUTING.md, funding, downloads, repo activity). |

If something looks off to you, open an issue — the source is 100% public and the CI build is reproducible.

Power-user CLI

mushi-mushi is just the setup wizard. For day-to-day triage install the full CLI:

npm i -g @mushi-mushi/cli
mushi reports list
mushi reports show <id>
mushi reports triage <id> --status acknowledged --severity high
mushi deploy check          # post-deploy smoke check
mushi status                # live pipeline health

For the v2 inventory + gates loop the actionable surface is the GitHub Action — drop one job into your repo and it runs Claude's proposer / the gate suite / the discovery digest on every PR:

# .github/workflows/mushi-gates.yml
- uses: kensaurus/mushi-mushi/packages/mcp-ci@master
  with:
    api-key: ${{ secrets.MUSHI_API_KEY }}
    project-id: ${{ secrets.MUSHI_PROJECT_ID }}
    command: gates # also: propose · discover-api · discovery-status · auth-bootstrap

The same commands are exposed as MCP tools through @mushi-mushi/mcp, so Cursor / Claude Code / Copilot can drive the v2 loop without you ever opening a terminal.

Or skip the CLI entirely and drive it from your AI agent via @mushi-mushi/mcp:

{ "mcpServers": { "mushi": { "command": "npx", "args": ["-y", "@mushi-mushi/mcp"] } } }

Links

• 🌐 Live admin demo — click around a real dataset
• 📦 GitHub — source, architecture, self-hosting
• 📚 Docs — quickstart, concepts, API reference
• 🐛 Report a bug — eat your own dogfood

License

MIT © Kenji Sakuramoto. Backend packages (@mushi-mushi/server, agents, verify) are BSL 1.1 — converts to Apache 2.0 on April 15, 2029.

Monorepo scale (June 2026): 47 edge functions · 256 SQL migrations · 13 outbound plugins · 11 inbound adapters · 18 pipeline agents. Canonical counts: docs/stats.md · pnpm docs-stats