Mushi Mushi Setup

Overview

Mushi Mushi is a TDD/PDCA engine for web apps: it captures bugs, maps user stories from your live app, auto-generates Playwright tests, and continuously improves them via PDCA loops.

Console URLs

Resolution order: env → saved consoleUrl in ~/.config/mushi/config.json → localhost probe → monorepo heuristic → hosted.

Command matrix

Do not mint SDK keys under Settings → BYOK. Use Setup → Verify → Generate API key (report:write).

Quick Start (5 steps)

1. Get your project credentials

Open the Mushi admin console (local: http://localhost:6464).

1. Setup → Steps or Projects → New project — create a project.
2. Copy Project ID (UUID) from the success panel immediately after Create.
3. Setup → Verify — Generate API key (report:write). Shown once.

Or run npx mushi-mushi — the wizard opens /onboarding?tab=steps&setup=cli, verifies via whoami, then installs.

You need:

• MUSHI_PROJECT_ID — UUID from success panel or Projects chip
• MUSHI_API_KEY — mushi_… from Verify tab

2. Install the SDK

# Recommended — wizard handles framework + env
npx mushi-mushi

# From an agent terminal (no TTY): no prompts; prints a sign-in URL + code
# and waits for the user to approve it in the browser
npx mushi-mushi --yes

# Or manual
npm install @mushi-mushi/web

The key the wizard writes to .env.local is ingest-only (report:write): it ships in the app bundle, so it can submit reports but never read them. The CLI's own key (with mcp:read) stays in the CLI config.

3. Initialize in your app

import { Mushi } from '@mushi-mushi/web'

Mushi.init({
  projectId: process.env.MUSHI_PROJECT_ID!,
  apiKey: process.env.MUSHI_API_KEY!,
  capture: {
    discoverInventory: {
      enabled: true,
      routeTemplates: ['/items/[id]', '/users/[userId]/profile'],
    },
  },
})

4. Map user stories from live app (no SDK required)

npm install -g @mushi-mushi/cli

mushi login   # browser sign-in; never paste a key on an agent's command line
# CI only: mushi login --api-key <key> --project-id <uuid>
# endpoint defaults to Mushi Cloud when omitted after login

mushi stories map --url https://your-app.vercel.app --wait

Review proposals: Inventory → Discovery → Past proposals.

5. Generate TDD tests from stories

mushi tdd pending
mushi tdd gen <story-id> --mode review
mushi tdd approve <qa-story-id>

CLI prerequisite step (init wizard)

If no saved config and no --project-id / --api-key flags:

1. No — open console → opens ?setup=cli
2. Yes — paste credentials
3. Use mushi login first → exit and re-run init

Second project

Use /onboarding?tab=steps&setup=cli or Projects → New project so the create form stays visible when you already have projects.

BYOK Key Pool (quota-aware failover)

mushi keys list
MUSHI_BYOK_KEY=sk-ant-... mushi keys add --provider anthropic --label "Backup account"

Console: Settings → API Key Pool (not the same as SDK ingest keys on Verify).

MCP Integration (Cursor / Claude)

After mushi login:

mushi setup                    # merges into .cursor/mcp.json
mushi setup --ide claude       # merges into .mcp.json at the repo root (Claude Code)
# or full wiring:
mushi connect --project-id <uuid> --endpoint <url> --write-env --wire-ide --wait

Manual MCP block:

{
  "mcpServers": {
    "mushi": {
      "command": "npx",
      "args": ["@mushi-mushi/mcp"],
      "env": {
        "MUSHI_API_KEY": "mushi_...",
        "MUSHI_API_ENDPOINT": "https://dxptnwrhwsqckaftyymj.supabase.co/functions/v1/api",
        "MUSHI_PROJECT_ID": "<uuid>"
      }
    }
  }
}

Connect Slack (1-click)

Integrations → Slack → Add to Slack

mushi slack status
mushi slack test

Verify Setup

mushi doctor --server --qa-stories
pnpm smoke:cli-setup   # monorepo: Playwright smoke for create → copy ID (skips if unsigned)

Common flags:

• ✗ Firecrawl → Integrations → BYOK Keys
• ✗ QA target URL → QA Coverage → Edit story
• ✗ Slack → Integrations → Add to Slack

Docs

• CLI ↔ console loop
• Admin onboarding