🌐 WhyBuddy

WhyBuddy — an AI agent crew that questions your product idea and rehearses it before you build.
Edge execution · Cloud orchestration · One sentence in, full spec out

English · 简体中文

🚀 Quick Start (1 minute · 2 commands)

cp .env.example .env       # then fill in LLM_API_KEY (see "MUST FILL" section)
docker compose up

Open http://localhost:3000 and you're in. The WhyBuddy server (3001 internally) is published on host port 3000 so you can navigate directly without remembering port numbers.

Three ways to run — pick whichever matches your environment:

1. Online demo — https://opencroc.github.io/whybuddy/ (browser-only mode, no install).
2. Docker compose — the snippet above; one MySQL + one WhyBuddy container.
3. Local dev — pnpm install && pnpm run dev:all (full stack, hot reload, see Local Dev below).

🔑 MUST FILL — without these you'll get template-only output

The server starts even when these are blank, but every autopilot bridge silently
falls back to deterministic templates and you'll see the same canned answers
regardless of input. Fill these two and you'll get real LLM-driven generation:

LLM_BASE_URL and LLM_MODEL should match the provider you picked
(default values target api.openai.com + gpt-5.4). Everything else in
.env.example ships with safe defaults — leave them alone unless you have
a reason.

💡 What it does (in 30 seconds)

You type one sentence. The system rehearses the entire product for you:

    💬 "AI comic platform"
        │
        ▼
    ① 🔍 Smart Clarification    Goals · Constraints · Personas · Success criteria
        │
        ▼
    ② 🗺️ Route Planning         Main route + Alternatives + Risk + Cost
        │
        ▼
    ③ 🌳 SPEC Tree              Modular spec node decomposition
        │
        ▼
    ④ 📄 Spec Documents         Requirements / Design / Tasks (streaming)
        │
        ▼
    ⑤ 🎨 Effect Preview         Architecture + Prompts + Next steps
        │
        ▼
    📦 Export → Markdown / ZIP / Online

💡 The entire process is observable in real time: a 3D office scene shows
the agent fleet collaborating, while the right-rail workbench streams
generation progress with stage indicators.

🤖 The FSD Fleet

Seven specialized AI roles collaborate on every rehearsal:

Each role has access to 50+ AIGC capability nodes, Docker sandbox, MCP
tools, Skills, and domain knowledge injection.

✨ Key Features

🛠️ Local Dev

git clone https://github.com/opencroc/whybuddy.git && cd whybuddy
pnpm install
pnpm run dev:all          # Full stack: frontend + server + executor

pnpm run dev:frontend     # Opens at localhost:5173

Or visit the Live Demo directly on GitHub Pages.

• Node.js 22+
• pnpm
• Docker (optional, only required for full sandbox executor mode; WhyBuddy
  falls back to a native runner when Docker is unavailable)

• The compose file boots two containers: whybuddy-app (the server +
  bundled frontend) and whybuddy-mysql (MySQL 8 with the
  whybuddy schema kept for backward compat — the data shape is
  unchanged, only the project brand changed).
• The Lobster Executor sandbox is not in the compose file by default.
  Docker-in-Docker introduces extra surface area and isn't required for
  the spec generation loop. Opt in by setting
  LOBSTER_EXECUTION_MODE=real and pointing the host's Docker daemon at
  the executor service yourself.
• All BLUEPRINT_*_ENABLED flags default to safe values matched to a
  fresh dev environment; the AUTOPILOT_REAL_RUNTIME master switch is
  on by default — bridges that find their dependencies will run real,
  bridges that don't will fall back gracefully.

🖼️ Screenshots

📝 Rehearsal Examples

Every rehearsal is a shareable piece of content. 50 rehearsals = 50
distribution opportunities.

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│  🌐 ENTRY          Browser · Feishu Relay · Destination Input   │
├─────────────────────────────────────────────────────────────────┤
│  🖥️ FRONTEND       3D Scene · Task Cockpit · Route View        │
│                    Drive State · Takeover Panel · Replay         │
├─────────────────────────────────────────────────────────────────┤
│  🧠 CUBE BRAIN     10-Stage Workflow · Mission Runtime          │
│                    Dynamic Roles · Cost Governance · Review      │
├─────────────────────────────────────────────────────────────────┤
│  🔮 PROJECTION     Mission→Destination · Workflow→Route         │
│                    State→DriveState · Decision→Takeover          │
├─────────────────────────────────────────────────────────────────┤
│  💡 INTELLIGENCE   3-Level Memory · Knowledge Graph · RAG       │
│                    Self-Evolution · LLM Multi-Provider           │
├─────────────────────────────────────────────────────────────────┤
│  🛡️ TRUST          Hash-Chain Audit · Lineage DAG · Evidence    │
├─────────────────────────────────────────────────────────────────┤
│  ⚙️ EXECUTION      Docker Containers · HMAC · Sandbox · Terminal│
├─────────────────────────────────────────────────────────────────┤
│  🔗 INTEROP        A2A Protocol · Swarm · Guest Agent Market    │
└─────────────────────────────────────────────────────────────────┘

🛠️ Tech Stack

📊 Project Scale

⚔️ Comparison

🤝 Contributing

1. Fork & clone → pnpm install
2. pnpm run dev:frontend (UI) or pnpm run dev:all (full stack)
3. Before PR: node --run check && pnpm run test

See CONTRIBUTING.md for details.

🪪 About the name

WhyBuddy is two characters: 端 (edge / endpoint) and 云 (cloud).
Together they describe the model the project converges on — workloads execute
at the edge when they can (browser runtime, native sandbox, your laptop's
Docker), and fall back to the cloud when they need shared coordination
(LLM, MCP servers, the Lobster Executor service). The codebase still carries
the legacy package name whybuddy in some internal modules; that is
intentional and tracked under
whybuddy-internal-rename for a future sweep, not the entry
point you read first.

The domain whybuddy.com is reserved for the hosted edition.

⭐ Star History

Every rehearsal is content that helps others discover possibilities. Star
this repo to help more people find it.