oleg.m/waggle-os

Fork 0

Files

Oleg Maslov 0c3e2ead3b

Installer Smoke / installer-smoke (push) Has been cancelled

Details

moving

2026-09-02 10:10:29 +02:00

20 KiB

Raw Blame History

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)

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.
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.
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):

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:

Unified memory (already there — hive-mind-core + 7 hook packages).
One-click launcher with workspace context injection (G1 + G4).
Live unified activity feed across all tools (G3 = WaggleDance v2).
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)

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.
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).
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+.
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.
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.

20 KiB Raw Blame History Unescape Escape