Mushi Mushi 虫虫

The user-friction intelligence layer that complements Sentry.

Sentry sees what your code throws. Mushi sees what your users feel.

Quick start · Live admin demo · Docs · Self-hosting · Architecture

_{↑ a logged-in 4-stop walk through the Plan → Do → Check loop · static deep-dive hero below · click to open the live admin}

_{↑ a real bug, end-to-end · the admin is dark-only by design}

The gap Mushi Mushi closes

Your existing monitoring is excellent at one thing: what your code threw. It cannot see:

• A button that looks clickable but does nothing
• A checkout flow that confuses every new user
• A page that takes 12 seconds to load but never errors
• A layout that breaks on one specific Android phone
• A feature that silently regressed two deploys ago

These are user-felt bugs. They never trigger an alert. Users just leave.

Mushi Mushi is the missing layer. Drop a small SDK into your app — users press shake-to-report (or click a widget) and Mushi auto-captures screenshot, console, network, device, route, and intent. An LLM-native pipeline (Haiku fast-filter → Sonnet vision + RAG → judge → optional agentic auto-fix) classifies, deduplicates, and turns the friction into actionable bug intelligence — wired into Sentry, Slack, Jira, Linear, and PagerDuty.

Designed as a companion to your existing monitoring, not a replacement. Reports stream through to Sentry breadcrumbs and link back to the offending session.

Tour

A walk through the rooms inside. Click any panel to land on it in the live demo.

Quickstart mode · 3 pages, verb-led labels, no PDCA jargon. The default for first-time visitors — pill-toggle up to Beginner (9 pages) or Advanced (all pages) anytime.	First-run tour · custom 5-stop spotlight tour, no react-joyride dep so it inherits dark theme tokens. Stops that need real data silently skip until the first report lands.
Plug-n-play onboarding · opens with a Plan→Do→Check→Act storyboard so you see the loop before the checklist. Required steps drive the green progress bar; optional steps stay tagged.	Sticky run receipts · every Run / Generate / Dispatch button leaves a persistent ResultChip next to it, so the user never has to wonder "did it actually work?" after the toast fades.
Dashboard (Advanced) · one living number per stage, bottleneck ring, Next-Best-Action strip, 14d severity-stacked histogram, LLM tokens & calls sparklines, Repo link right under Fixes.	Reports · triage queue + Btn parity — 4 px severity stripe, 14d severity KPIs with sparklines, blast-radius dedup, Save view preset, single primary action per row.
Fixes · pipeline + stagger — per-attempt PDCA cards, 30d KPI sparklines, Langfuse trace per run, real PR links, retry-failed CTA. Cards cascade-fade in via useStaggeredAppear.	Judge · Decide/Act/Verify hero over the charts. Live KPIs, 12w score trend, distribution histogram, prompt leaderboard, one-click re-run with a sticky ResultChip.
Repo · one branch per auto-fix attempt, grouped by CI status. Live event stream via Supabase Realtime on fix_events, inline mini-graph per card, refreshes itself so you can leave it open on a second monitor.	Intelligence · the 3-tile hero pattern in action — Decide surfaces the one-liner that matters, Act collapses to "All clear" when there's nothing to do, Verify deeplinks to the evidence. Every advanced page follows this shape.
Health · real cost_usd per call, per-function / per-model breakdown, p50/p95 latency, fallback rate, cron triggers, Langfuse deeplinks, Decide/Act/Verify hero over the raw numbers.	Prompt Lab · replaces Fine-Tuning. A/B traffic split between active and candidate prompts per stage, eval dataset preview, synthetic report generator, fine-tuning jobs queue.
Knowledge graph · auto-switches to Sankey storyboard under 12 nodes; full React Flow canvas above. Apache AGE backed when installed, falls back to plain SQL adjacency otherwise.	Compliance · SOC 2 control evidence pack with PASS / WARN pills and inline JSON, region pinning per project, print-styled Export PDF, DSAR workflow tracking.
Marketplace · toggleable extension layer for the loop. Each plugin declares the events it subscribes to and ships with HMAC-signed webhooks; deliveries are logged with HTTP status + first 512 chars of the response.	Action inbox · open actions across the PDCA loop, grouped by stage with one yellow CTA per group (Open critical queue → / Open failed fixes → / Run judge batch →). Empty groups skip — the page only renders what's actually waiting on you.
Anti-gaming · per-device fingerprint tracker that throttles bad-faith reporters and surfaces multi-account abuse (4 reporter tokens from same device). Operator gets Details / Unflag per row; every enforcement action lands in the audit trail.	Processing queue (DLQ) · worker_jobs viewer with 14d throughput histogram, per-stage backlog bar, and per-job Retry action. Top-right batch ops — Retry page (25) / Flush queued / Recover stranded — operate on the visible filter so you never accidentally retry the whole table.
Ask Your Data · ad-hoc natural-language SQL over the bug data — read-only Postgres, pre-canned chip prompts (Top 5 components by report count this month, Reports with screenshots but no console logs in the last 7 days), Saved queries + History sidebar, every successful answer logged to the audit trail.	Research · pin QA + product findings here so the next loop iteration starts smarter. Pre-seeded chip topics (pgvector cosine distance vs inner product accuracy, vite 8 esbuild externalization regression) hint at the kind of low-noise long-form notes the loop benefits from.
MCP — Model Context Protocol · per-project .cursor/mcp.json snippet pre-filled with the active MUSHI_PROJECT_ID, 13-tool catalog mirror (apps/admin/src/lib/mcpCatalog.ts, kept in sync with packages/mcp/src/catalog.ts by the check-catalog-sync pre-commit guard), 60s 3-step agent bootstrap.	Integrations · Sentry / Langfuse / GitHub health-checked probes with last-probe latency + HTTP code + sparkline, codebase indexing status (401 files swept 3h ago, fed back into the RAG context the auto-fix agent reads), routing-destination CRUD (Jira / PagerDuty / Linear).
Reporter notifications · outbound messages sent to the people who reported each bug (e.g. classified — report:5b0027a1... paired with tok:e7bafe2b...). Show payload reveals the exact JSON the SDK delivered. Keeps the loop transparent — every reporter knows what happened to their bug.	Workspace settings · 5 tabs (General · BYOK · Firecrawl · Health & test · Dev tools) covering Slack webhook, Sentry DSN, Stage-2 model picker, Stage-1 confidence threshold, dedup similarity threshold — every knob the LLM pipeline reads at runtime, with a No changes button that arms only when something diffs.
SSO config · SAML 2.0 + OIDC form, calls the Supabase Auth Admin API on submit, surfaces the resulting ACS URL + Entity ID below for you to paste into your IdP. JIT provisioning on first login is the default. OIDC intentionally returns 501 — see Honest status.	Audit log · append-only history of every mutation, filterable by actor / action / resource / time. Each row pairs a settings.updated / compliance.dsar.created action with an actor UUID and resource handle so you can trace any change to a tenant. Export CSV for the next SOC 2 review.
BYO storage · per-project bucket form (Supabase / S3 / R2), region pinning, presigned-URL TTL editor, vault-ref'd access keys (never plaintext). Per-project usage table at the top so you spot a project burning through storage before the bill arrives.	Multi-project workspace · per-project cards with active-key count, reports count, member count, plus inline CTAs to mint a fresh key, send a test report, or open project-scoped Integrations / Settings. The active project drives the project filter on every other page.
Billing · plan comparison (Hobby Free / Starter $19 / Pro $99 / Enterprise), per-plan reports/month + overage cents/report + retention days + admin seats, Stripe-metered LLM $ per day below the fold, Need help? form wired to /v1/support/contact (rate-limited to 5 tickets/hour/user) so paying customers jump the queue.	Report detail · 4-stamp PDCA receipt + live Branch & PR timeline — every step of the dispatch lifecycle from llm_invocations, fix_attempts, fix_events, and classification_evaluations in a single round-trip so it never N+1s.

Seven capabilities, one platform

1. User-side capture — Shadow-DOM widget, screenshot, console + network rings, route + intent, offline queue, rage-click / error-spike / slow-page proactive triggers.
2. LLM-native classification — 2-stage pipeline (Haiku fast-filter → Sonnet deep + vision), structured outputs via response_format, prompt-cached system instructions, deterministic JSON.
3. Knowledge graph + dedup — Bug ↔ component ↔ page ↔ version edges in Postgres + pgvector. Auto-grouping kills duplicate noise.
4. LLM-as-Judge self-improvement — Weekly Sonnet judge scores classifier outputs; low-scoring runs feed a fine-tuning queue. OpenAI fallback when Anthropic is degraded.
5. Agent-agnostic auto-fix — Orchestrator with validateResult gating + GitHub PR creation. Sandbox provider abstraction (local-noop for tests, e2b / modal / cloudflare for prod, all four wired through resolveSandboxProvider). True MCP client adapter (JSON-RPC 2.0 + SEP-1686 Tasks) so Claude Code, Codex, Cursor, or any future agent plugs in.
6. Multi-repo coordinated PRs — A bug spanning frontend + backend opens linked PRs (fix_coordinations table) so reviewers see the full surface.
7. Enterprise scaffolding — SSO config CRUD, audit log ingest, plugin marketplace with HMAC, region-pinned data residency, retention policies, DSAR workflow, Stripe metered billing.

Quick start

npx mushi-mushi

The wizard auto-detects your framework (Next.js / Nuxt / SvelteKit / Angular / Expo / Capacitor / plain React, Vue, Svelte / vanilla JS), installs the right SDK with your package manager, writes MUSHI_PROJECT_ID and MUSHI_API_KEY to .env.local (with the right framework prefix), and prints the snippet to paste in. Equivalent commands:

npm create mushi-mushi              # via the npm-create convention
npx @mushi-mushi/cli init           # if you prefer the scoped name

Skip the wizard and install directly if you already know which SDK you want:

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

That's it. Users now have a shake-to-report widget. Reports land in your admin console, classified within seconds.

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

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

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

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

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

import { MushiProvider } from '@mushi-mushi/react-native'
<MushiProvider projectId="proj_xxx" apiKey="mushi_xxx">
  <App />
</MushiProvider>

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

.package(url: "https://github.com/kensaurus/mushi-mushi.git", from: "0.1.0")

import Mushi
Mushi.configure(projectId: "proj_xxx", apiKey: "mushi_xxx")

dependencies {
  implementation("dev.mushimushi:mushi-android:0.1.0")
}

Mushi.init(context = this, config = MushiConfig(projectId = "proj_xxx", apiKey = "mushi_xxx"))

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

Where the project is today

Published: SDKs at 0.2.x (all seven frameworks + node + adapters + capacitor), CLI + launcher at 0.4.x, MCP + MCP-CI at 0.1.x, admin at kensaur.us/mushi-mushi/ (auto-deployed to S3 + CloudFront on every push to master).

Dogfood: end-to-end loop validated on a real production webapp. Report → LLM triage → "Dispatch fix" → draft GitHub PR → live in /fixes → live branch graph in /repo with per-event Supabase Realtime stream. Sentry, Langfuse, and GitHub all probe Healthy from the Integrations page, with a nightly Playwright dogfood against the production stack catching regressions before they reach users.

This month's highlights 🐛

• Decide / Act / Verify page hero — every Advanced PDCA page now opens with a 3-tile hero strip (Decide = one headline metric, Act = the current next-best-action with a single CTA, Verify = deeplink to the evidence). Charts moved below the fold. Beginner mode collapses it to a one-line summary. Source: apps/admin/src/components/PageHero.tsx.
• Live /repo page — one node per branch the auto-fix agent has opened, grouped by CI status (open / passing / failing / merged / stuck), with a live event stream on the right via Supabase Realtime on the new fix_events table. Each branch shows its own mini PDCA graph (Plan → Dispatch → Branch → Commit → PR → CI → Merge) so you can see the loop progress without leaving the page.
• Dynamic tab titles + favicon badges — useDocumentTitle keeps document.title in sync with the active page via the shared pageContext registry (Reports · 60 reports · 2 critical — Mushi Mushi) and useFaviconBadge paints a red dot on the favicon whenever criticalCount > 0, so operators see urgency from any other browser tab. Both are data-layer driven — zero per-page wiring.
• Nightly prod PDCA — .github/workflows/nightly-prod-pdca.yml runs the full Playwright dogfood suite against the production Supabase stack every night (07:00 UTC) and auto-opens a GitHub issue if the pipeline regresses. Catches stale env keys, expired tokens, cron disables, and LLM provider outages that the local-stack PR e2e can't see. Flip ENABLE_NIGHTLY_PROD_PDCA to true to enable.
• Global command palette — press ⌘K (macOS) or Ctrl+K (Linux/Windows) anywhere to jump to any page, filtered view, or real report / fix by name. cmdk-backed, keyword aliases (bugs → Reports, pr → Fixes, spam → Anti-Gaming), debounced live API search, recents persist per browser (page actions excluded from the recents list so navigation recents don't get evicted).
• PDCA as a live React Flow canvas — the dashboard loop is a diamond of Plan / Do / Check / Act nodes with gradient bezier edges and a marching-ants animation on the current bottleneck. Narrow viewports keep the stacked cockpit fallback; onboarding ships the same flow as an explainer.
• Quickstart mode — the default 3-page admin (Setup → Bugs to fix → Fixes ready) for humans who'd rather not know what PDCA stands for. Pill-toggle up to Beginner (9 pages) or Advanced (full console) anytime. Advanced mode groups pages under the four PDCA stages with staleness badges and per-page "next best action" strips.
• First-run tour — a 5-stop spotlight that auto-launches once, skips stops that need real data, and resumes when the first report lands. No react-joyride dep, inherits dark theme tokens.
• Responsive tables — ResponsiveTable primitive with edge-fade scroll shadows, opt-in sticky first column, and a global comfy / compact density toggle that persists per browser. Reports, Judge leaderboards, and Compliance evidence / DSAR tables already use it.
• Themed dialogs — native window.confirm/prompt retired in favour of focus-trapped <ConfirmDialog> / <PromptDialog> with proper tone="danger" for destructive actions.
• Resilient embeddings sweep — the RAG repo indexer no longer aborts the whole sweep on a single embedding failure. Per-chunk try/catch keeps the loop going, counts failed chunks, and only surfaces to Sentry when zero chunks succeed. Empty-response errors now include upstream host, model, and the raw 200-OK body so BYOK + OpenRouter mis-configurations are diagnosed in one pass.
• N+1 slayed — apiFetch dedups in-flight requests + keeps a 200 ms micro-cache. The old 24× storm on /v1/admin/setup is now 1 request.
• Sentry telemetry — every non-2xx API response leaves a breadcrumb; 5xx captures a message; rotated DSNs self-disable after 3 consecutive 401/403 so your devtools stay clean. logLlmInvocation now swallows its own promise-rejection so void callers on the hot request path can't crash the isolate.
• Slack quick-fix — Block Kit messages with Triage + Dispatch fix buttons wired to a signed slack-interactions Edge Function. The loop starts and ends in Slack.
• Pre-commit lint guards — pnpm install auto-installs a .git/hooks/pre-commit that chains zero-dependency guards: check-no-secrets.mjs (AWS / Stripe / Slack / GitHub / OpenAI / Anthropic / JWT leak scanner), check-design-tokens.mjs (retired-Tailwind-aliases that render transparently), check-mcp-catalog-sync.mjs (MCP catalog ↔ admin mirror parity), check-dead-buttons.mjs (<button disabled> without aria-label / tooltip), check-publish-readiness.mjs, and check-license-headers.mjs. Bypass once with git commit --no-verify, skip install with MUSHI_SKIP_GIT_HOOKS=1.

Honest status — what works, what's still partial

The orchestrator refuses to run local-noop in production unless you explicitly set MUSHI_ALLOW_LOCAL_SANDBOX=1. Pick e2b (or implement the SandboxProvider interface yourself) before exposing autofix to production traffic.

Architecture

flowchart LR
    subgraph App["Your app"]
        SDK["@mushi-mushi/{react,vue,svelte,angular,react-native,web}<br/>Shadow-DOM widget · screenshot · console · network · offline queue"]
    end

    subgraph Edge["Supabase Edge Functions (Deno + Hono)"]
        API["api"]
        FF["fast-filter<br/>Haiku"]
        CR["classify-report<br/>Sonnet + vision + RAG"]
        JB["judge-batch<br/>Sonnet (OpenAI fallback)"]
        IR["intelligence-report"]
        ORCH["fix-dispatch<br/>SSE"]
    end

    subgraph DB["Postgres + pgvector"]
        REP["reports"]
        KG["knowledge graph"]
        EVAL["judge_evals"]
        FIX["fix_attempts<br/>+ coordinations"]
    end

    subgraph Agents["@mushi-mushi/agents"]
        MO["MCP client (JSON-RPC 2.0)"]
        SBX["Sandbox: local-noop / e2b"]
        GH["GitHub PR creator"]
    end

    SDK -->|HTTPS| API
    API --> FF --> CR
    CR --> KG
    CR --> REP
    KG --> IR
    REP --> JB --> EVAL
    REP --> ORCH --> Agents
    Agents --> GH

See apps/docs/content/concepts/architecture.mdx for the full pipeline.

Packages

Most developers only install one SDK package — npx mushi-mushi picks the right one for you and pulls in core and web automatically.

Connecting to a backend

A. Hosted (zero-config)

1. Sign up at kensaur.us/mushi-mushi
2. Create a project → copy your projectId and apiKey
3. Drop the SDK into your app

B. Self-hosted

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

Or via Supabase CLI directly — see SELF_HOSTED.md. A Helm chart lives at deploy/helm/ (incomplete — missing migrations ConfigMap).

Internal edge functions (fast-filter, classify-report, fix-worker, judge-batch, intelligence-report, usage-aggregator, soc2-evidence, generate-synthetic) authenticate via the shared requireServiceRoleAuth middleware, which accepts either MUSHI_INTERNAL_CALLER_SECRET (used by pg_cron → pg_net, mirrored into public.mushi_runtime_config.service_role_key) or the auto-injected SUPABASE_SERVICE_ROLE_KEY (used for function-to-function calls). Never expose them with --no-verify-jwt in production. Only the public api function should face the internet. See packages/server/README.md.

Monitoring & privacy (this repo's deployment)

The hosted instance reports to two Sentry projects under the sakuramoto org:

Privacy & safety:

• sendDefaultPii: false on both — no IPs, cookies, or request bodies attached automatically.
• Token-like query params scrubbed in beforeSend. Authorization, Cookie, *-api-key headers redacted server-side.
• Sourcemaps uploaded by @sentry/vite-plugin during pnpm build and deleted from dist/ before the S3 sync — the public bucket never serves them.
• Sentry data scrubbing strips token prefixes (mushi_*, sntryu_*, JWTs starting with eyJ, ghp_*, npm_*) on top of SDK-side redaction.

For SDK consumers and forks: the published packages do not initialize Sentry. The bridge at packages/web/src/sentry.ts only reads context from your existing Sentry instance — it never sends data on its own. Self-hosted forks can leave the DSNs unset and the SDKs no-op cleanly.

Payment & support operations

The hosted product wires three feedback loops so the operator hears from paying customers fast:

How each piece works:

• Operator push (packages/server/supabase/functions/_shared/operator-notify.ts): a single helper that knows how to render Slack Block Kit and Discord rich embeds. Severity drives colour; urgent pings @here on Discord. Failures are captured to Sentry but never block the webhook from 200-ing back to Stripe.
• In-app support form (/v1/support/contact): JWT-gated, rate-limited to 5 tickets/hour/user, captures plan tier at submit time so paid tickets jump the queue. Customer sees status updates inline on /billing. PII (passwords, API keys) explicitly called out as off-limits in the form copy.
• Centralised support address (SUPPORT_EMAIL env var, defaults to [email protected]): used in the Checkout custom_text, the BillingPage "Need help?" mailto, and the rate-limit error message.

To enable the operator push for a self-hosted instance:

# 1. Create a Slack incoming webhook (api.slack.com/messaging/webhooks)
#    OR a Discord channel webhook (server settings → integrations → webhooks).
# 2. Push the secret to Supabase:
supabase secrets set OPERATOR_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
# or
supabase secrets set OPERATOR_DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
# 3. Optionally override the support address (defaults to [email protected]):
supabase secrets set [email protected]
# 4. Redeploy the api + stripe-webhooks functions:
supabase functions deploy api stripe-webhooks

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

cd apps/admin
pnpm dev    # → http://localhost:6464 — auto-connects to Mushi Cloud

cp .env.example .env   # Supabase + LLM provider keys
cd packages/server/supabase
npx supabase db push
npx supabase functions deploy api --no-verify-jwt

packages/
  core, web, react, vue, svelte, angular,                 # Web / framework SDKs (MIT)
  react-native, capacitor, node, adapters
  ios, android, flutter                                   # Native SDKs (early dev)
  cli, mcp, mcp-ci, launcher, create-mushi-mushi          # Tooling + CI gate
  server, agents, verify                                  # Backend (BSL 1.1)
  plugin-sdk, plugin-jira, plugin-slack-app,              # Plugin marketplace
  plugin-linear, plugin-pagerduty, plugin-zapier, plugin-sentry
  wasm-classifier                                         # On-device pre-classifier (ONNX)
apps/
  admin    # React 19 + Tailwind 4 + Vite 8 (dark-only by design, 24 pages)
  docs     # Nextra v4 documentation site
  cloud    # Next.js 15 marketing landing + Stripe billing
examples/
  react-demo, e2e-dogfood
deploy/    # Docker Compose + Helm chart
tooling/   # Shared ESLint + TypeScript configs
scripts/   # Zero-dependency pre-commit + CI guards (secrets / tokens / dead-buttons / changelog aggregate / …)

Contributing

Issues and PRs welcome. To get started: pnpm install && pnpm dev. See individual package READMEs for package-specific setup, and the latest handovers (newest first) under docs/ — HANDOVER-2026-04-21-console-elevate.md is the current state of play; Wave S (Decide/Act/Verify hero, /repo page, dynamic titles, favicon badge, nightly prod PDCA) lands on top of it via subsequent PRs.

License

• SDK packages (core, web, react, vue, svelte, angular, react-native, cli, mcp): MIT
• Server, agents, verify: BSL 1.1 — converts to Apache 2.0 on April 15, 2029