# AI-OS Architecture Exploration — WaggleDance Evolution + Unified Memory Launcher

**Date:** 2026-05-19 · **Mode:** exploration / pre-spec · **Code:** none yet.
**Mandate:** "Explore first, don't code yet. ULTRATHINK."

---

## 0. Executive summary (read this first)

1. **WaggleDance today is small and well-scoped:** ~120-LOC dispatcher + 10-subtype protocol, team-scoped, used for *internal* multi-agent coordination. Underused. The UI surface (`WaggleDanceApp.tsx`) renders signals as a feed but nothing outside the team workspace feeds it.

2. **The "OS for AI" substrate is already ~70% built — this is the headline finding.** The monorepo now contains **7 dedicated hook-installer packages** (`claude-code`, `claude-desktop`, `cursor`, `codex`, `codex-desktop`, `hermes`, `openclaw`), a `hive-mind-shim-core` foundation layer, a canonical `hive-mind-mcp-server`, a `hive-mind-cli`, and `hive-mind-wiki-compiler` — wired through `hive-mind-core` (the extracted `mind/`+`harvest/` substrate). The integration ethics are production-grade: byte-identical uninstall, fail-open hooks, SHA-256-verified round-trips.

3. **The remaining 30% is UI + connective tissue,** not new substrate. To deliver the "real OS feel" we need (a) a launcher / dock that detects installed AI tools and offers one-click hook install + workspace-scoped launch, (b) WaggleDance promoted from internal-team-bus to **cross-tool live nervous system** (every captured event becomes a signal), (c) cross-tool task dispatch from the Waggle UI. We **do not** need to embed Cursor/VS Code; that's the wrong shape.

The thesis we can ship: **"Waggle is the OS for AI work. Every tool you already use — Claude Code, Cursor, Codex, Claude Desktop, Hermes — silently feeds one unified memory, and Waggle's launcher + activity bus is how you see and steer it."**

---

## 1. WaggleDance — what it actually does today

**Code surface (verified):**
- `packages/waggle-dance/src/protocol.ts` — type/subtype combo validation. Three types × ten subtypes total. ~17 LOC.
- `packages/waggle-dance/src/dispatcher.ts` — `WaggleDanceDispatcher` class. Routes 4 of 10 subtypes today: `task_delegation`, `knowledge_check`, `skill_request`, `skill_share`. Takes 3 deps: `searchMemory`, `resolveCapability`, `spawnWorker`. ~120 LOC.
- `packages/waggle-dance/src/hive-query.ts` — pure types for hive queries. ~25 LOC.

**Message shape (`packages/shared/src/types.ts:92-102`):**
```ts
interface WaggleMessage {
  id: string;
  teamId: string;          // currently team-scoped only
  senderId: string;
  type: MessageType;       // 'broadcast' | 'request' | 'response'
  subtype: MessageSubtype; // 10 distinct subtypes
  content: Record<string, unknown>;
  referenceId: string | null;
  routing: Array<{userId: string; reason: string}> | null;
  createdAt: Date;
}
```

**Currently wired:**
- `packages/worker/src/handlers/waggle-handler.ts` routes protocol messages through the dispatcher; legacy non-protocol calls fall back to a topic-based hive query.
- `packages/server/src/services/message-service.ts` + `routes/messages.ts` — server-side persistence + REST surface.
- `apps/web/src/components/os/apps/WaggleDanceApp.tsx` — UI activity feed with filters: discovery / handoff / insight / alert / coordination. Pulls from `useWaggleDance()` hook.
- WebSocket inbound: `{type: 'send_message', ...}` and `{type: 'waggle_message', message}` types are in the WS protocol.

**What's underused:**
- `model_recommendation`, `knowledge_match`, `task_claim`, `discovery`, `routed_share`, `model_recipe` — defined in the type union, no dispatcher branches yet. The protocol over-commits to coordination primitives the runtime doesn't yet exercise.
- `resolveCapability` is stubbed in `waggle-handler.ts` (returns canned response — comment says "full capability router wiring needs agent package context").
- `spawnWorker` is a stub that returns a string ("Worker spawned for..."). Real BullMQ enqueue is commented out as TODO.
- TEAMS-tier feature today; no path to per-user signal volume.

**Honest assessment:** WaggleDance is a *protocol-shaped scaffold* with a small live core (3 working subtypes against stubbed deps) and a UI that consumes whatever signals exist. It is **not yet** the "live nervous system" the name evokes.

---

## 2. WaggleDance — evolution options (no code, just shape)

### 2a. Status quo — keep as team-internal
Finish wiring `resolveCapability` + `spawnWorker` to real implementations. Add dispatcher branches for the remaining 6 subtypes. Leaves WaggleDance as a TEAMS feature only. **Verdict:** correct, but doesn't unlock new value.

### 2b. Promote to **cross-tool nervous system** ★ recommended
The hook packages already capture conversation episodes from every external tool. Today they write frames directly. Add a new emission path: every interesting hook event (significant `Stop` summary, `compact_memory` event, sign-gated frame, learning loop fire from D1) **also emits a WaggleMessage** to a per-user `personal` team (not just real Teams). The Waggle Dance app becomes the unified live activity feed for ALL your AI work across ALL tools.

Concretely:
- Drop the `teamId NOT NULL` constraint, or introduce a synthetic `personal::<userId>` team. Personal users get WaggleDance for free; the TEAMS tier upgrade adds shared-team visibility on top.
- Hook packages gain a `--emit-signal` flag that POSTs a `broadcast/discovery` message when a `Stop` summary exceeds an importance threshold.
- D1's mechanically-closed learning loop emits a `broadcast/skill_share` when a new skill is distilled — and other tools can recall it via MCP.
- The `WaggleDanceApp` filter list (`discovery|handoff|insight|alert|coordination`) already matches this perfectly.

### 2c. Add provenance + trust
Extend `WaggleMessage` with optional `provenance: { tool, sessionId, workspaceId, frameId }` and `trust: number ∈ [0,1]`. Lets the UI render "Cursor saw this in workspace X with trust 0.82" — and lets downstream consumers (KVARK governance, EU AI Act audit) filter on origin/confidence.

### 2d. Topology-aware routing (deferred)
`routing: Array<{userId, reason}>` is already in the message shape. Hop-limited fan-out for big teams; not needed pre-launch but the field is reserved.

**Recommendation:** ship 2b + 2c together as **"WaggleDance v2 — cross-tool activity bus"** roughly 1 to 1.5 weeks of work. Skip 2d until TEAMS scale demands it.

---

## 3. "OS for AI" — the **surprise finding**

The user's ask reads like greenfield architecture. It is not. The substrate is mostly here.

### 3a. What's already in `packages/` (verified by `find`)

| Package | Role |
|---|---|
| `hive-mind-core` | The extracted `mind/`+`harvest/` substrate — single source of memory truth, shared with the open-source release at `marolinik/hive-mind`. |
| `hive-mind-shim-core` | Foundation layer used by every tool hook. Exposes: `cli-bridge`, `frame-encoder`, `hook-event-types`, `importance-classifier`, `prompt-summarizer`, `retry-bridge`, `workspace-resolver`, `logger`. |
| `hive-mind-mcp-server` | Canonical MCP server. Any MCP-aware tool can read/write hive-mind via stdio. |
| `hive-mind-cli` | Programmatic + interactive CLI surface; the bridge hooks shell out to it. |
| `hive-mind-wiki-compiler` | Compiles harvested frames into navigable wiki pages. |
| `hive-mind-hooks-claude-code` | SessionStart / UserPromptSubmit / Stop / PreCompact hooks for Claude Code, with reversible byte-identical install. |
| `hive-mind-hooks-claude-desktop` | Same pattern for Anthropic Claude Desktop. |
| `hive-mind-hooks-cursor` | Same pattern for Cursor. |
| `hive-mind-hooks-codex` | Same for OpenAI Codex CLI. |
| `hive-mind-hooks-codex-desktop` | Same for the Codex Desktop variant. |
| `hive-mind-hooks-hermes` | Same for Hermes agent. |
| `hive-mind-hooks-openclaw` | Same for OpenClaw. |

### 3b. The integration pattern — already production-grade

From `hive-mind-hooks-claude-code/README.md`:

| Hook | Semantic effect |
|---|---|
| `SessionStart` | Resolve workspace → switch context → recall top-N frames → inject as additional context. |
| `UserPromptSubmit` | Save prompt as `temporary` frame, session-scoped. |
| `Stop` | Deterministically summarize the completed turn → save as `important` frame parented to the prompt. |
| `PreCompact` | Run `compact_memory` so superseded P/B frames merge before the tool truncates context. |

**Ethics that are already enforced:** byte-identical uninstall via SHA-256 round-trip, fail-open on any error (tool never sees a hook failure), workspace-pinned via small pointer file. This is the trust posture you need for "install Waggle and let it observe everything."

### 3c. What this means

The "unified memory across all your AI tools" promise is **already deliverable today** via a documented install path (`npx @hive-mind/<tool>-hooks install`). It just isn't packaged as an OS-shaped product surface yet. The remaining work is **product**, not **research** — which is the cheaper kind.

---

## 4. Gap analysis — what's missing for "real OS feel"

These are the deltas between "the substrate exists" and "Waggle feels like an OS for AI."

### Tier 0 — must-have for the OS metaphor to land

| Gap | What | Effort |
|---|---|---|
| **G1. Tool launcher / dock** | Detect installed AI tools on the user's machine; show them in a Waggle dock; one-click "Open in workspace X". Spawn the native binary (Tauri `Command::new` or web-app deep-link). | M |
| **G2. Hook auto-installer** | "I see Cursor 0.42 installed and uninstrumented. Want to wire it to hive-mind? [Install][Skip]." Wraps the `npx @hive-mind/<tool>-hooks install` flow in a Tauri-side action with consent UI. | S |
| **G3. WaggleDance v2 — cross-tool bus** | (See §2b/§2c.) Every captured event from any tool becomes a WD signal. Single live activity feed. | M |
| **G4. Cross-tool workspace context** | When the user launches Claude Code "in workspace KVARK," the hook chain picks up that workspace at SessionStart. Today `workspace-resolver.ts` exists; we need the launcher side to set the env/marker the resolver reads. | S |

### Tier 1 — strongly increases OS feel

| Gap | What | Effort |
|---|---|---|
| **G5. Tool inventory + status** | Mission Control / Dashboard tile: "5 tools installed, 3 instrumented, 2 running, last capture 14s ago." | S |
| **G6. Cross-tool task dispatch** | "Spawn agent in Claude Code with this prompt + workspace context" from inside Waggle. Uses the existing process-spawn + MCP-config-injection path. | M |
| **G7. Provenance UI on memory** | Every frame already records source. Surface it: "This came from Cursor (workspace KVARK, 2 hours ago)." Memory app gets a `source-of-truth` column. | S |
| **G8. Skill diffusion loop** | D1's mechanically-closed learning loop (shipped last session) emits skills locally. Promote skills via WD `skill_share` broadcast so other tools (via MCP) can adopt them. | M |

### Tier 2 — nice-to-have, not launch-blocking

| Gap | What | Effort |
|---|---|---|
| **G9. Embedded shell panes** | Tauri webview-embeds a terminal running `claude-code` or `cursor` *inside* the Waggle window. Maximal OS feel but legal/effort cost is high. | L+ |
| **G10. Cross-tool replay** | "Show me the chain: Cursor question → Claude Code edit → Codex test → Hermes review." Already possible from frame data; needs UI. | M |
| **G11. Tool-aware governance hooks** | EU AI Act audit + KVARK governance — filter on tool/provenance. Already permitted by hive-mind schema; needs UI + reports. | M |

---

## 5. Three architectural paths

### Path A — "Memory bus only"
Waggle is just the memory + UI substrate. Other tools run independently; users install hooks themselves via CLI. No launcher, no dock, no signal bus.
- **Pros:** lowest friction; we're already 95% here.
- **Cons:** doesn't deliver the "OS for AI" feel the user is asking for.
- **Verdict:** under-shoots the ask.

### Path B — "Hub launcher"
Waggle detects + launches external tools; injects workspace context + ensures hooks are installed. Tools run in their own windows; Waggle is the launcher + memory cockpit.
- **Pros:** Real OS feel without taking on embedding risk. Native window management means the user keeps muscle memory.
- **Cons:** Process management complexity; cross-platform installer detection; Tauri permissions/capabilities work.
- **Verdict:** the realistic landing zone.

### Path C — "Embedded shells"
Tauri embeds Cursor/VS Code/terminals as webview panels inside the Waggle window.
- **Pros:** Maximum OS feel.
- **Cons:** Cursor isn't designed to embed; VS Code remote requires the Server extension; legal questions on Cursor; massive effort. The user's existing UI muscle memory in Cursor would break.
- **Verdict:** wrong shape for the value delivered. Skip.

### **Path D — recommended: B + WaggleDance v2 as the unifying bus**
Path B for processes + UI launcher; promote WaggleDance from team-internal to cross-tool live activity bus (§2b/§2c). The "OS feel" comes from four converging primitives:

1. **Unified memory** (already there — hive-mind-core + 7 hook packages).
2. **One-click launcher with workspace context injection** (G1 + G4).
3. **Live unified activity feed across all tools** (G3 = WaggleDance v2).
4. **Cross-tool task dispatch** (G6).

This is the smallest set of new code that delivers the maximum amount of "OS for AI." No embedding. No greenfield substrate. Mostly product surface + bus rewiring + Tauri spawn wiring.

---

## 6. Suggested phasing (no code yet — for ratification)

**Phase 0 — Tool detection PoC** (~3 days)
- Single Tauri command: scan known install paths for Claude Code, Cursor, Codex CLI, Claude Desktop, Hermes on win32/darwin/linux.
- Returns `{tool, installedPath, version, hooksInstalled}`.
- Foundation for G1 + G2 + G5.

**Phase 1 — WaggleDance v2 cross-tool bus** (~5 days)
- Schema migration: allow `personal::<userId>` synthetic team.
- Hook packages gain optional signal-emit path on `Stop` when importance > threshold.
- Drop dispatcher fall-throughs to fully wire the 6 unwired subtypes (even as stubs).
- `WaggleDanceApp` filter expanded to include `tool` column.
- Locks: end-to-end test that a Claude Code stop emits a `discovery` signal visible in `WaggleDanceApp`.

**Phase 2 — Launcher dock + hook-installer UX** (~5 days)
- Dock surface in Tauri shell + on `apps/web/src/components/os/`.
- Per-tool: "Launch in workspace X" + "Install hooks" + "Verify" + "Uninstall."
- Workspace context injection via env or pointer file picked up by `workspace-resolver.ts`.
- Locks: spawn-test for each of the 7 tool integrations.

**Phase 3 — Cross-tool task dispatch + skill diffusion** (~7 days)
- "Spawn agent in Claude Code with prompt P" from Waggle UI → spawns + injects context.
- D1's distilled skills broadcast via WD `skill_share`; MCP-consuming tools can recall.
- Locks: round-trip test (Waggle UI → spawn Claude Code → execute → memory frame visible in Waggle within N seconds).

**Phase 4 — Polish / governance / launch comms** (~5 days)
- Provenance UI in Memory app (G7).
- Mission Control tile (G5).
- Cross-tool replay (G10) if time permits.
- Pre-launch comms: this is the OS-for-AI story.

Total: ~25 working days, all incremental on existing substrate, zero new research dependencies.

---

## 7. Open questions for you (PM-level decisions)

1. **Scope: which tools first?** Claude Code + Cursor + Claude Desktop are the highest-frequency for your persona. Codex/Hermes/OpenClaw fill out the catalog but their hook packages already exist. Recommend all 7 by Phase 4 because the cost-per-additional-tool is small.
2. **Personal-tier vs TEAMS-only for WaggleDance v2?** Recommend personal-tier (free) for visibility-only; TEAMS keeps the shared/collaborative-team value. The free version drives the lock-in moat (Memory + Harvest is free forever per `feedback_silent_recommendations_dont_ask` lineage).
3. **Embedded shells: revisit later or never?** I'd argue *never for Cursor/VS Code* (effort/legal), *yes for `claude-code` CLI* (terminal embed via xterm.js is straightforward and ships big OS feel for the CLI users). Defer to Phase 5+.
4. **Naming.** "Waggle is the OS for AI" is a positioning claim, not a feature name. The dock probably wants a name — `Hive Dock`? `The Launcher`? `Studio`? Worth a separate brainstorm.
5. **Pre-launch sequencing.** Polish-sprint backlog (CLAUDE.md §10) has PersonaSwitcher, Stripe, light-mode finish still open. AI-OS work is additive, not blocking — but it's a bigger story than any single polish item. Do we slip launch to lead with the AI-OS narrative, or ship current scope and lead the post-launch arc with AI-OS?

---

## 8. Risks / non-goals

- **Non-goal:** rewriting any external AI tool's UI. We respect their surfaces; we observe + coordinate + remember.
- **Non-goal:** building proprietary hooks for tools that don't already have one. The 7-tool catalog is the catalog.
- **Risk:** cross-platform process spawning is fiddly. Tauri 2's `Command` API helps but each tool has its own quirks (especially Windows CLI shims — already burnt time on `hive-mind-cli` `.cmd` shim, hence the `--cli-path` flag in claude-code hook README).
- **Risk:** capturing-everything posture demands the trust posture is airtight. The existing reversible-install ethics (byte-identical uninstall, fail-open) is the right baseline; do not regress it.
- **Risk:** signal volume on WaggleDance bus. Importance-classifier already exists (`hive-mind-shim-core/src/importance-classifier.ts`); thresholds need product tuning.

---

## 9. What I'd ratify before any code

| # | Decision | My recommendation |
|---|---|---|
| D1 | Path D over A/B/C | **Path D.** B alone undersells the activity-bus value. |
| D2 | WaggleDance v2 personal-tier eligibility | **Yes** — drives moat. TEAMS keeps team-shared visibility. |
| D3 | Tool launch-list for Phase 1 | **Claude Code + Cursor + Claude Desktop** first; rest by Phase 4. |
| D4 | Embedded shells | **Never for IDEs; consider xterm.js for `claude-code` CLI** in a later phase. |
| D5 | Phasing | **Phase 0→4 as above (~25 days)**; or compressed to ~15 days if we cut governance polish to v1.5. |
| D6 | Launch sequencing | **Open.** Two viable paths: (a) launch current scope, then lead the post-launch story with AI-OS; (b) compress remaining polish, fold AI-OS Phase 1+2 into the launch story. Recommend (a). |

---

## 10. Appendix — surface map (verified file inventory)

```
packages/
├── waggle-dance/                              # protocol + dispatcher (120 LOC core)
├── hive-mind-core/                            # extracted mind/+harvest/
│   └── src/{mind,harvest}/                    # the substrate
├── hive-mind-shim-core/                       # foundation for all hooks
│   └── src/{cli-bridge,frame-encoder,
│            hook-event-types,importance-
│            classifier,prompt-summarizer,
│            retry-bridge,workspace-resolver,
│            logger}.ts
├── hive-mind-cli/                             # programmatic CLI
├── hive-mind-mcp-server/                      # canonical MCP surface
├── hive-mind-wiki-compiler/                   # frame→wiki pages
├── hive-mind-hooks-claude-code/               # ★ shipped, reversible install
├── hive-mind-hooks-claude-desktop/            # ★
├── hive-mind-hooks-cursor/                    # ★
├── hive-mind-hooks-codex/                     # ★
├── hive-mind-hooks-codex-desktop/             # ★
├── hive-mind-hooks-hermes/                    # ★
├── hive-mind-hooks-openclaw/                  # ★
├── launcher/                                  # currently: `npx waggle` CLI launcher only
└── memory-mcp/                                # standalone MCP server (predecessor; check overlap with hive-mind-mcp-server)
```

```
apps/web/src/components/os/apps/
├── WaggleDanceApp.tsx                        # ready to consume cross-tool signals
├── AgentsApp.tsx                              # local agents UI
├── ConnectorsApp.tsx                          # external services (30 connectors)
└── ...                                        # 21 OS-app surfaces total
```

```
app/src-tauri/
└── src/commands/agent.rs                      # process-spawn pattern already proven for
                                               # in-process agent loop streaming
                                               # — extend to external tool spawn
```

---

**END.** Awaiting decisions D1–D6 in §9 before any code.