Mushi Mushi

The bug your monitoring can't see, in your queue with a draft fix.

Sentry catches what your code throws. Datadog catches what your infrastructure does. Firebase catches what your users click. Mushi catches what your users feel — the dead button, the 12-second screen, the layout that breaks on one Android.

Mushi is the synthesis layer: the one signal none of your existing tools capture, with inbound adapters for 11 monitoring sources (Sentry, Datadog, Bugsnag, Rollbar, Crashlytics, New Relic, Honeycomb, Grafana Loki, AWS CloudWatch, Opsgenie, Firebase Analytics) and 12 outbound plugins (Sentry, Slack, Jira, Linear, PagerDuty, Discord, Microsoft Teams, GitHub Issues, Bugsnag, Rollbar, Crashlytics, Zapier) so every tool in your stack stays in the loop.

Quick start · Live admin demo · Docs · Marketing landing · Self-hosting · Rewards program · Full screenshot tour

_{↑ a logged-in 4-stop walk through the Plan → Do → Check → Act loop}

_{↑ the v2 admin · click to open the live demo · the image swaps with your system theme}

Read this first if you're not a developer

A 60-second tour for product managers, designers, founders, and anyone who's ever heard "we'll fix it next sprint" three sprints in a row.

• What it is — A small "shake your phone to report a bug" button that drops into any web or mobile app in one line of code. It captures a screenshot, what the user was trying to do, and what their device looked like.
• Why it's different — Sentry, Datadog, and Firebase tell you when code crashes. They go quiet when a button looks clickable but isn't, when a page takes 12 seconds to load with no error, or when the layout looks broken on one phone model. Mushi catches those — the bugs your users feel but your monitoring can't see.
• What happens to a report — An AI reads it within seconds, tags severity ("blocker", "minor"), groups duplicates ("the same broken button collapsed across 47 users"), and (optionally) hands the report to another AI that opens a draft pull request with the proposed code change. A human always reviews and merges.
• Where your data lives — Your own cloud (self-hosted), or ours. The free tier covers 1,000 reports a month with no credit card.
• What it costs to run — Mushi is the plumbing. You bring your own API keys for Anthropic / OpenAI / Sentry / Slack / etc., and you pay those vendors directly. We don't mark up LLM tokens or hold your data hostage. Most teams run the whole loop for under $20/month.
• Who it's for — Founders shipping a consumer product, PMs who live in support tickets, designers tired of "works on my machine", on-call engineers who want fewer 3 AM Slack pings.
• Two-line install — npx mushi-mushi. The wizard does the rest.

If you're a developer skip ahead to Try it. If you're an operator or platform engineer, jump to Operator-grade plumbing for the production checklist.

What's new in v2 — bidirectional inventory + agentic-failure gates

Mushi v1 was the negative side: catch what your users felt break and triage it. v2 adds the positive side: a declarative inventory.yaml of user stories, pages, and actions — with five pre-release gates that fail the build when the agent's drafts diverge from the contract, and a synthetic monitor that re-walks the same surface against staging on a schedule.

• 🌱 Sketch your app, not just its bugs. A User stories · Inventory page (sidebar → User stories) groups every user-facing action under the story it serves and shows verified / unwired / regressed counts at a glance.
• 🤖 The SDK proposes the inventory. Turn on capture.discoverInventory and the SDK quietly observes routes, data-testids, and outbound API paths in production — Claude drafts an inventory.yaml from the stream, you accept or edit. Most teams will never hand-author one.
• 🚦 Five gates, one composite GitHub check. mushi-mushi/no-dead-handler (empty onClicks), mushi-mushi/no-mock-leak (faker / "John Doe" arrays in non-test paths), inventory drift (added / removed / renamed actions), agentic-failure detection (handler regressions across deploys), and synthetic walk health.
• 🛰️ Synthetic monitor runs the inventory's expected_outcome checks against your staging URL on a cron — fail-closed by default, with explicit synthetic_monitor_allow_mutations opt-in for write paths.
• 🕸️ Graph gets a Surface mode — the same Bug graph toggles to a Surface view that overlays the positive inventory on the live knowledge graph so you can see the dead corners.
• 🧭 Spec traceability is end-to-end (2026-05-09 release). expected_outcome is a real schema field — its assertions ride along with every fix dispatch, get rendered into the LLM prompt, gate the PR through validateAgainstSpec, and trigger a targeted synthetic probe against the originating Action the moment the PR opens. Every fix_attempt row records the inventory Action it was meant to repair (inventory_action_node_id), so the admin "Where this fix came from" drawer can show the same spec the agent saw. See How spec traceability works below for the full chain.
• 🔌 First-class orchestrator interop. Plug Mushi into Cursor, Claude Code, OpenAI Agents SDK, LangGraph, CrewAI, A2A v1.0.0 agents, or anything else: MCP Streamable HTTP at /functions/v1/mcp (2025-03-26 spec), A2A tasks endpoints at /v1/a2a/tasks (create / get / cancel / SSE subscribe), OpenAPI 3.1 at /openapi.json, AG-UI v0.4 SSE accepts API keys (mcp:read), SandboxProvider is an open contract with a third-party registry, and JSON Schemas for FixContext / FixResult / SandboxProvider / ExpectedOutcome are served at /v1/schemas/*. See Connecting your orchestrator for per-orchestrator recipes.
• 🧩 Headless SDK widget. MushiTrigger and MushiAttach let you attach the feedback reporter to any button, icon, or menu item in your existing design system — no floating stamp, no fixed position, just your UI opening Mushi on click. Works in React (polymorphic as prop) and React Native (cloneElement injection). See Headless integration.
• 🌐 Multi-platform console. Reports from iOS, Android, Web, and React Native are now filterable by platform and SDK package in the Reports list. Each report's detail drawer shows the "Device & Build" section with sdk_version and app_version. The Dashboard shows a Platform Health tile with 24h report volume per SDK.
• 🤖 QA Coverage Suite. Define automated user-story tests as natural-language prompts or Playwright scripts, schedule them on cron, and run them via Firecrawl Actions (default, no setup), Browserbase (BYOK, cloud Chromium), or local Playwright (CLI). Pass/fail history appears on a dedicated /qa-coverage page and a dashboard tile. When you generate a Playwright test from a report, Mushi automatically creates a QA story so it runs on a weekly schedule as a regression guard. See QA Coverage Suite.

Get started in any project that already has Mushi installed:

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

Inside your IDE the same commands are exposed as MCP tools via @mushi-mushi/mcp, so Cursor / Claude Code / Copilot can run them on your behalf. From the admin UI you click Run gates / Run crawler directly on each row of the User stories page.

Full schema in @mushi-mushi/inventory-schema, ESLint rules in eslint-plugin-mushi-mushi, the auth-bootstrap helper in @mushi-mushi/inventory-auth-runner.

How spec traceability works

The most-asked v2 question is "how do you keep agent work tied back to the original spec once implementation starts?" Honest answer: until the 2026-05-09 release the read side was tight and the write side was a U-turn — the worker dropped the inventory pointer the moment dispatch started. That's now closed end-to-end.

report ──► classify-report writes graph_edge (reports_against)
              │
              ▼
        inventory Action node ◄────────── inventory.yaml (expected_outcome)
              │
              ▼
       POST /v1/admin/fixes/dispatch  (or /v1/a2a/tasks, MCP dispatch_fix)
              │  body may carry { inventoryActionNodeId } — else worker walks the edge
              ▼
        fix_dispatch_jobs.inventory_action_node_id  ──► persisted
              │
              ▼
        fix-worker assembles FixContext
              + inventoryAction.expectedOutcome  ──► Markdown spec block in the LLM prompt
              ▼
        validateAgainstSpec  (deterministic pre-PR gate)
              │  HARD ERROR if the diff removes a json_path field the contract asserts on
              │  WARN to fix_attempts.spec_validation_warnings if no file references the contract's table / route
              ▼
        GitHub PR + fix_attempts row stamped with inventory_action_node_id
              │
              ▼
        synthetic_runs queued (status='skipped', error_message='queued_post_pr', action_node_id=…)
              │
              ▼
        synthetic-monitor cron drains the queue with priority on the next tick,
        runs an HTTP probe, evaluates expected_outcome (status_in + JSONPath assertions),
        records a real synthetic_runs row.
              │
              ▼
        Status reconciler picks it up → admin UI flips the Action to verified / regressed.

Every link in that chain has a real column / migration / test:

What the agent sees in its prompt today (rendered by renderSpecContext):

## Inventory Spec Context (whitepaper §2.10 spec-traceability)

This fix was dispatched against a tracked Action in the project's `inventory.yaml`.
The agent and the reviewer MUST keep the diff scoped to making the action work as
specified — do NOT refactor unrelated code or break sibling actions on the same page.

- Action: `signup-form: submit`
- Description: Submit the signup form and create a new user
- Page: `/signup` (id=`signup`)
- User story: New user signup (`signup`)

### Expected outcome contract (success criteria after fix)

- Summary: POST /signup returns 200 and creates a user row
- HTTP status MUST be one of: 200, 201
- Response body assertions:
  - `$.user.id` exists
- Database: `public.users` MUST row_exists
- UI MUST show text containing: "Welcome"
- UI MUST navigate to: `/dashboard`

After the PR merges, the synthetic monitor will probe the action against this
contract. A draft fix that the synthetic monitor will then immediately mark
`regressed` is worse than no fix at all.

The same anchor flows out to every external surface — Cursor / Claude Code / OpenAI Agents SDK / LangGraph / CrewAI / A2A all get the inventory Action and its expected_outcome via the MCP get_fix_context tool, the A2A Task metadata.inventoryActionNodeId field, or the dispatch row's column directly.

When this matters to you

Your existing monitoring is excellent at one thing: telling you what your code threw. It can't tell you any of these:

• 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 started using the competitor's tab in the meantime.
• A layout that looks fine on your laptop folds in half on the one Android model used by 18% of your traffic.
• A feature regressed two deploys ago. Three users emailed support; two just churned.

These never trigger an alert. Your users just leave. Mushi gives them a way to tell you while the moment is still fresh — so the bug your monitoring missed lands in your triage queue, classified, deduped, and (optionally) with a draft PR already open.

Try it

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, writes MUSHI_PROJECT_ID and MUSHI_API_KEY to .env.local, and prints the snippet to paste in. Equivalent commands:

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

Or 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',
        // v2.1 — opt in to passive inventory discovery (off by default).
        // Routes, testids, and outbound API paths flow into the proposer
        // so Claude can draft an inventory.yaml for you to accept.
        capture: { discoverInventory: true },
      }}
    >
      <YourApp />
    </MushiProvider>
  );
}

Your users now have a shake-to-report widget. Reports land in your admin console, classified within seconds — and (with discoverInventory) your inventory drafts itself from the same stream.

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

import { initMushi } from '@mushi-mushi/svelte';
initMushi({ 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.4.0")
import Mushi
Mushi.configure(projectId: "proj_xxx", apiKey: "mushi_xxx")

dependencies {
  implementation("dev.mushimushi:mushi-android:0.4.0")
}
Mushi.init(context = this, config = MushiConfig(projectId = "proj_xxx", apiKey = "mushi_xxx"))

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.

Tour the rooms

A quick look at where you'll spend your time. Every panel is a click-through to the live demo.

Dashboard · the PDCA cockpit — PLAN / DO / CHECK / ACT in one row, the next action explained in plain English, and the setup checklist that moves itself off-screen once you finish	User stories · Inventory · the new v2 positive surface — every user-facing action grouped under its story, with verified / unwired / regressed counts and one-click Run gates / Run crawler from the row
Knowledge graph · component / page / release adjacency weighted by bug incidence — toggle Surface to overlay the positive inventory and see the dead corners	Graph · Surface mode · v2 — the same canvas, but every Page / Element / Action from inventory.yaml overlaid on the live knowledge graph so the dead corners light up

For the full screenshot tour (28 surfaces, every page in the console) see docs/SCREENSHOTS.md.

How the loop runs

When a user shakes their phone, four things happen in roughly the order you'd expect a careful colleague to 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. Everything they were doing, plus everything that broke.
2. Classify. A two-stage LLM pipeline (Haiku fast-filter → Sonnet deep + vision) tags severity, category, and root-cause hint in plain English. A nightly Sonnet judge scores the classifier's own work and feeds a prompt-A/B loop, so the labels you see come from prompts that have earned their place.
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. You click Dispatch fix (or wire the same action from Slack — the bot posts a threaded status reply once the PR is open), MCP, or 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 — and merge, change, or close it.

The architecture, sequence diagram, and component-by-component spec live in apps/docs/content/concepts/architecture.mdx. A condensed wire diagram:

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 Functions"]
        API["api"]
        FF["fast-filter"]
        CR["classify-report<br/>+ vision + RAG"]
        ORCH["fix-dispatch"]
    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

What you get on day one

• You see one report per actual bug, not twenty. Dedup runs against the knowledge graph, so the same broken button collapses across users and devices.
• Your queue is already triaged. Severity, category, and a one-line root-cause hint are there before you click in.
• Your users get a way to tell you. A 14 KB shake-to-report widget that doesn't pretend to be a chat bot and doesn't ask them to write a ticket.
• Your auto-fix is opt-in and reviewable. The agent opens a draft PR. You merge it, edit it, or close it — the loop never bypasses you.
• Your existing tools keep working. Mushi sits next to Sentry; it does not replace it. Sentry breadcrumbs flow into Mushi's classifier, and Mushi reports flow back as Sentry User Feedback if you want them to.

Launcher modes

The SDK ships four ways to surface the bug reporter — choose the one that fits your app's layout:

Banner quick start

Mushi.init({
  apiKey: 'mushi_…',
  widget: {
    trigger: 'banner',
    bannerConfig: {
      variant: 'brand',   // 'neon' | 'brand' | 'subtle'
      position: 'top',    // 'top' | 'bottom'
      bugCta: '🐛 Report a bug',
      featureCta: true,
    },
  },
})

Configure the launcher and preview the snippet live in the admin console under SDK Install → Launcher.

Headless SDK integration

By default the SDK injects a floating 🐛 stamp button. For the attach or manual modes, use the headless primitives:

React — MushiTrigger

import { MushiTrigger } from '@mushi-mushi/react'

// Any element: button, anchor, div, custom component
<MushiTrigger as="button" category="bug" className="my-feedback-btn">
  Report a bug
</MushiTrigger>

// With Radix / shadcn
<MushiTrigger as={Button} variant="ghost" size="sm">
  Feedback
</MushiTrigger>

All native props are forwarded. The onClick chain is preserved — if the host button calls e.preventDefault() Mushi will not open.

React — MushiAttach

Attach the reporter to an element you can't wrap (third-party widget, portal):

import { MushiAttach } from '@mushi-mushi/react'

// Renders nothing — just wires the click listener
<MushiAttach selector="#help-button" category="bug" />

React Native — MushiTrigger

import { MushiTrigger } from '@mushi-mushi/react-native'

<MushiTrigger>
  <Pressable style={styles.btn}>
    <Text>Report a bug</Text>
  </Pressable>
</MushiTrigger>

SDK Install Card

The admin console's SDK Install page (Get started → Configure & install the SDK) has a five-option Trigger mode chooser: Header banner (recommended), Attach to my button, Floating stamp, Edge tab, and Headless (manual). The snippet preview updates in real time to show the correct import and usage pattern.

QA Coverage Suite

Define user-story tests as prompts or Playwright scripts and schedule them to run automatically.

Quick start

1. Go to Check → QA Coverage in the sidebar.
2. Click + New story and describe the test in natural language.
3. Pick a provider (Firecrawl by default — no API key needed).
4. The story runs hourly and results appear on the page and the Dashboard tile.

Providers

Connecting to user stories

When you click Generate test from report on a report, Mushi writes a Playwright script, opens a GitHub PR, and automatically creates a QA story for it — scheduled weekly as a regression guard.

BYOK (Bring Your Own Key)

Story runners use your own API keys stored in mushi_runtime_config. No key → story is skipped with a clear reason. Key resolution order: project-level override → org-level override → Mushi platform default (Firecrawl only).

Dashboard integration

The QA Coverage tile on /dashboard shows: total stories, % passing (≥80% pass rate), and the top failing story. Click "View all →" to open the full /qa-coverage page.

A2A failure notifications

If a story fails and your project has an A2A endpoint configured, qa-story-runner pushes a structured failure notification to connected agents (Cursor, Claude Code, etc.) via the A2A protocol.

Multi-platform console

Filtering reports by platform / SDK

The Reports list (/reports) has Platform and SDK filter dropdowns. Options: iOS, Android, Web, macOS, Windows (platform); Web, React, React Native, Capacitor (SDK package). Selecting a value appends ?platform=ios (or ?sdk_package=@mushi-mushi/react-native) to the URL for shareability.

Device & Build panel

Each report detail page shows a Device & Build section with:

• platform — iOS / Android / Web / …
• sdk_package — @mushi-mushi/react, @mushi-mushi/react-native, etc.
• sdk_version — the SDK version that filed the report
• app_version — the app's own version string (if provided)

Platform Health dashboard tile

The Platform Health · 24h tile on /dashboard shows report volume, error counts, and SDK version list per platform, sourced from the qa_platform_rollup_24h materialized view (refreshed hourly). Click any row to drill into /reports?platform=<platform>.

Operator-grade plumbing

Mushi is the intermediary. We deliberately avoid replicating Sentry / Datadog / Firebase — instead we ship the boring-but-essential standards that let those tools talk to each other through one console, with one audit trail, and one consistent agent-facing API.

BYOK throughout. Mushi never holds your Anthropic / OpenAI / Sentry / Slack / Jira keys for billing leverage. Bring your own; rotate them in your own dashboard. The Integration Health Probe tells us (and you) the moment something rotated out from under us.

Where it stops

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

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

Where Mushi fits

Every team we talk to already runs three kinds of monitoring. Mushi is the fourth layer none of them cover.

Mushi is the synthesis layer, not a replacement. It adds the one signal that's missing, and ingests the others so a single classified bug row can carry everything at once: the stack trace from Crashlytics, the latency spike from Datadog, the funnel drop from Firebase, AND the user's screenshot and note.

Compared to each tool you already have

Mushi is already wired to send signals back to the tools you run — 12 outbound plugins covering Sentry, Slack, Jira, Linear, PagerDuty, Discord, Microsoft Teams, GitHub Issues, Bugsnag, Rollbar, Crashlytics, and Zapier — and to receive alerts from 11 inbound sources (Sentry, Datadog, Bugsnag, Rollbar, Crashlytics, New Relic, Honeycomb, Grafana Loki, AWS CloudWatch, Opsgenie, Firebase Analytics) via @mushi-mushi/adapters. You don't replace anything; you add the layer that completes the picture.

The marketing landing at kensaur.us/mushi-mushi/ walks the full integration story.

Run it

Hosted (zero-config). Sign up at kensaur.us/mushi-mushi/, click Start free, no card, create a project, and copy your projectId + apiKey. The free tier covers 1,000 reports a month.

Self-hosted. 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 is the long-form guide. A production-ready Helm chart lives at deploy/helm/ — pre-install Job applies all 138 SQL migrations from a bundled ConfigMap (pnpm sync:helm-migrations keeps it fresh; CI guards drift). One helm install on any cluster.

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. Never expose them with --no-verify-jwt in production. Only the public api function should face the internet — see packages/server/README.md.

Cursor & Claude Skills

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

# Install all three Mushi skills at once
npx skills add kensaurus/mushi-mushi

# Or individually
npx skills add kensaurus/mushi-mushi/mushi-setup   # Setup guide
npx skills add kensaurus/mushi-mushi/mushi-debug   # Debug & fix issues
npx skills add kensaurus/mushi-mushi/mushi-test    # TDD test workflow

Then in Cursor/Claude:

• /mushi-setup — guided setup walkthrough
• /mushi-debug — diagnose and fix issues
• /mushi-test — run the full TDD loop

Packages

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

Contributing

Issues and PRs welcome. To get started:

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 for setup, docs/ for handover notes (newest first), and docs/SCREENSHOTS.md for the full admin tour.

License & branding

This repository is dual-licensed because the code is open source but the brand is not. The split is what lets us welcome forks while making it hard for bad actors to ship a malicious copy under our name.

If you're a security researcher, see SECURITY.md for the threat model, PII commitments, coordinated-disclosure timeline, and safe-harbor terms.