Onboarding Guide: Waggle OS

Scannable quick-start. The authoritative deep contract is CLAUDE.md at repo root — read that before writing code. This guide is the 2-minute orientation layer on top.

Overview

Waggle OS is a workspace-native AI agent platform with persistent memory. It ships as a Tauri 2 desktop binary (Win/macOS) wrapping a Vite/React 19 web UI and a Node.js Fastify sidecar. Strategically it's the demand-gen funnel for KVARK (Egzakta's sovereign enterprise AI).

Tech Stack (verified 2026-05-28)

Layer	Technology
Language	TypeScript 5.8, Node ≥20
Frontend	React 19.1 + Vite + Tailwind 4 + @base-ui/react
Desktop	Tauri 2.10 (Rust shell, `app/src-tauri/`)
Backend	Fastify sidecar (Node), runs via `tsx`
LLM routing	LiteLLM (`litellm-config.yaml`)
DB / Memory	SQLite (better-sqlite3) + sqlite-vec; mind substrate in `packages/core/src/mind/`
Billing	Stripe 21
Tests	Vitest (unit) + Playwright (E2E/visual)
Pkg manager	npm workspaces (`apps/`, `packages/`)

Architecture

Monorepo, full-stack. Frontend (apps/web) talks to a local sidecar (packages/server) over HTTP/WS at 127.0.0.1:3333. The sidecar owns the SQLite "mind" per workspace. Tauri wraps both for desktop; the same web UI also runs standalone in a browser against the sidecar.

Browser / Tauri WebView
   └─ apps/web (React)  ── lib/adapter.ts (RPC) ──▶ Fastify sidecar :3333
                                                      packages/server/src/local/
                                                        index.ts  (registers routes + decorators)
                                                        routes/*.ts
                                                          └─▶ @waggle/core mind substrate
                                                                FrameStore / SessionStore /
                                                                KnowledgeGraph / HybridSearch
                                                        chat.ts ──▶ @waggle/agent agent-loop ──▶ LiteLLM

Key Entry Points

Sidecar bootstrap: packages/server/src/local/start.ts → index.ts (route registration ~line 1916+, server decorators: multiMind, workspaceManager, agentState, vault, scheduler)
Frontend root: apps/web/src/pages/Index.tsx → components/os/Desktop.tsx (the desktop-OS shell + Dock)
RPC layer: apps/web/src/lib/adapter.ts (every backend call goes through here)
Agent loop: packages/agent/src/agent-loop.ts
Memory substrate: packages/core/src/mind/ (db, frames, search, knowledge, sessions)
Config: litellm-config.yaml (LLM routing), packages/shared/src/tiers.ts (5-tier system)

Directory Map

apps/web/        MAIN UI — desktop-OS metaphor (Dock, AppWindow, 25 apps, overlays)
apps/www/        Marketing landing page (waggle-os.ai)
apps/browser-ext/ Chrome MV3 companion extension (FR-1, 2026-05-28)
app/             Tauri desktop shell (Rust + minimal React cockpit)
packages/        27 workspaces (see below)
sidecar/         Node bundle target for Tauri packaging
docs/            Architecture, plans, audits, this guide
external/        meta-agents-research-environments (GAIA2 benchmark harness)
benchmarks/      Harness + benchmark runners

packages/ (27): 15 core — agent (94+ files, agent-loop/personas/evolution), core (mind+harvest), server (Fastify sidecar), shared (types/tiers/mcp-catalog), sdk, cli, worker, marketplace, optimizer, weaver, waggle-dance, wiki-compiler, launcher, admin-web, memory-mcp — plus 12 hive-mind-* OSS-split packages (core, cli, shim-core, mcp-server, wiki-compiler + 7 hooks: claude-code, claude-desktop, codex, codex-desktop, cursor, hermes, openclaw). (No packages/ui — it has no package.json.)

Request Lifecycle (a chat message)

User types in ChatApp.tsx → adapter.sendMessage() POSTs to /api/chat
routes/chat.ts resolves workspace mind DB via server.agentState.getWorkspaceMindDb()
Recall: HybridSearch (FTS5 + vec0 fused via RRF) pulls relevant frames
agent-loop.ts builds the system prompt (orchestrator.ts buildSystemPrompt), runs the LLM via LiteLLM, executes tools (tool-filter gates per persona)
Response streams back over SSE/WS; new memory written via FrameStore.createIFrame(); TraceRecorder logs the turn

Conventions

Files: kebab-case (sample-workspaces.ts); React components PascalCase (LoginBriefing.tsx)
Routes: export async function xxxRoutes(server: FastifyInstance), then await server.register(xxxRoutes) in index.ts. Reuse existing endpoints before adding new ones (see docs/addictiveness-audit-2026-05-28/REDUNDANCY-AUDIT.md for why).
Secrets: server.vault.get(key) / .set() — never hardcode (CLAUDE.md §7)
SQL: parameterized only (better-sqlite3 ? params)
Errors: try/catch → reply.status(n).send({ error })
Tests: unit = *.test.ts (Vitest, co-located/per-package); E2E+visual = *.spec.ts under tests/ (Playwright)
Commits: Conventional (feat(scope): …, fix:, refactor:, docs:, revert:). No AI attribution (disabled globally).

Common Tasks

Dev UI: npm run dev (Vite, apps/web)
Run sidecar standalone: npx tsx packages/server/src/local/start.ts --skip-litellm (serves built dist/ at :3333)
Build web: npm run build (→ dist/)
Build packages: npm run build:packages (order: shared → core → agent → server)
Unit tests: npm test (Vitest)
E2E: npm run test:e2e · Visual: npm run test:visual
Lint: npm run lint

Verification before claiming done

⚠️ npm run build typechecks only apps/web. The sidecar runs via tsx (transpile-only). Server-side type errors slip through unless you run the server tsconfig explicitly. CLAUDE.md §2's verification block omits this — add it:

npx tsc --noEmit --project packages/server/tsconfig.json   # ← the missing one
npx tsc --noEmit --project packages/agent/tsconfig.json
npx tsc --noEmit --project app/tsconfig.json
npm run test -- --run
npm run lint

Where to Look

I want to...	Look at...
Add a backend endpoint	`packages/server/src/local/routes/` + register in `index.ts`
Add/edit a desktop app	`apps/web/src/components/os/apps/`
Add an overlay/dialog	`apps/web/src/components/os/overlays/`
Change memory behavior	`packages/core/src/mind/`
Change agent reasoning	`packages/agent/src/` (agent-loop, orchestrator, personas)
Add a persona	`packages/agent/src/persona-data.ts`
Add a workspace template	`packages/server/src/local/routes/workspace-templates.ts` (`BUILT_IN_TEMPLATES`)
Change LLM routing	`litellm-config.yaml`
Change tiers/pricing	`packages/shared/src/tiers.ts`
Browse MCP/skills catalog	`packages/shared/src/mcp-catalog.ts` + `MarketplaceApp.tsx`

Flags for maintainers (found during onboarding recon)

CLAUDE.md §2 says "16 workspace packages" — actual count is 27. The 11 hive-mind-* packages (OSS split, synced to marolinik/hive-mind per §7.5) were added since the April verification. Worth a CLAUDE.md refresh.
Verification block in CLAUDE.md omits packages/server tsc (see above) — server routes can ship type errors undetected.

7.3 KiB Raw Blame History