Files
waggle-os/README.md
shumeiko.it 5f088698dd chore: remove internal documents and service directories (P2.2 part 1)
The commercial repository carries the product's internal history: audits,
screenshots, briefs, decisions, pricing, publication drafts, personal data
and research runs. None of it belongs in the community edition.

- delete judging/, "UAT 3/", benchmarks/ (including LoCoMo data under
  CC BY-NC), preflight-results/, gepa-phase-5/, notes/, decisions/,
  .understand-anything/, .agents/, .lovable/, the legacy sidecar/ package
  and waggle-cowork/ (an analysis of Claude Code sources)
- delete docs/ except docs/oss, the user guides (without the team-mode
  guide), the reference, methodology, architecture, getting-started and
  contributing pages, which P2.4 rewrites
- delete render.yaml, .parity-allowlist, the retired mind-parity and
  sync-mind workflows and 29 one-off scripts nothing references
- delete tests that only checked removed files (sidecar package, Render
  blueprint, UAT capture, benchmark harness isolation, internal audit and
  signing docs); drop sidecar/ and benchmarks/ from the hive-mind subtree
  split guard; prune ignore, attribute, lint and test globs
- replace the commercial README with an interim one for this edition

Source comments still point at some deleted docs; P2.2 part 2 cleans them
together with names and paths.
2026-10-20 01:02:18 +02:00

3.7 KiB

Waggle OS Community Edition

Waggle is a local-first AI workspace: an agent with persistent memory, personas, skills, connectors and scheduled automations. It runs as a Node.js sidecar with a React web UI, and can be wrapped in a Tauri desktop shell. You bring your own model: a local model through Ollama or a provider API key.

Status: work in progress. This branch is being converted from the commercial Waggle OS codebase into an open-source community edition. Billing, KVARK, compliance reporting and self-learning are already removed; memory is moving to a local mem0 store, and installers for Windows, macOS and Linux are not ready yet. The rules for this conversion are in AGENTS.md and the decision records in docs/oss/adr/.

Repository layout

waggle-os/
├── apps/web/           # Web UI (React 19, Vite, Tailwind 4)
├── app/                # Tauri 2 desktop shell (Rust); loads the apps/web build
├── packages/           # npm workspaces: agent, server, core, shared, marketplace,
│                       # memory-contract, memory-mem0, cli, launcher, sdk, weaver, ...
└── docs/               # Guides, reference, and docs/oss for the community edition

AGENTS.md lists the status of every package in this edition.

Run from source

Prerequisites: Node.js ^20.19.0 or >=22.12.0, and npm.

npm install
npm run build:packages   # workspace packages export dist/; the sidecar needs it
npm run build            # builds the web UI into dist/
npm run dev:server       # the sidecar on http://localhost:3333, serving the UI

Open http://localhost:3333. Rebuild the UI and restart the sidecar to see UI changes: the Vite dev server (npm run dev:web) cannot authenticate against the sidecar yet (UF-003 in docs/oss/upstream-fixes.md).

Provider keys are entered in the app under Settings → API Keys and stored in the encrypted vault, so a basic local run needs no .env file. .env.example lists the optional variables.

Embeddings. By default EMBEDDING_PROVIDER=auto downloads a small in-process model (about 23 MB, cached under ~/.waggle/models/) and works offline. To use Ollama instead, install Ollama, run ollama pull nomic-embed-text, and set EMBEDDING_PROVIDER=ollama.

Variable Description
ANTHROPIC_API_KEY Claude API key; can be set in the app instead.
OPENAI_API_KEY Enables OpenAI models and optional OpenAI embeddings.
EMBEDDING_PROVIDER auto (default), inprocess, ollama, voyage, openai or mock.
LITELLM_BASE_URL Optional external LiteLLM-compatible proxy.

Checks

npm run build:packages   # build all workspace packages
npm run typecheck:web    # type-check the web UI
npm run lint             # lint the packages
npm run check:deps       # every import is a declared dependency
npm test                 # unit tests

Known failures and the numbers to compare against are in docs/oss/baseline.md.

Documentation

The guides predate the community edition and still describe some removed features; they are rewritten before the first release.

License

This repository is licensed under the MIT License, except the hive-mind-* packages under packages/, which are licensed under Apache-2.0. Each hive-mind-* package carries its own LICENSE file, which governs that package.