# Waggle OS

Workspace-native AI agent platform with persistent memory, model-agnostic orchestration, and skill-extensible capabilities. It ships as a Tauri 2.0 desktop binary (Windows/macOS) with a Vite-bundled web app and a Node.js sidecar.

## Architecture

```
waggle-os/
├── apps/
│   ├── web/            # Main web app UI (React 19 + Vite + Tailwind 4 + base-ui/react)
│   ├── www/            # Marketing site (Next.js)
│   └── browser-ext/    # Browser extension (unpacked; not an npm workspace)
├── packages/           # 28 workspace packages (see "Packages" below)
├── app/                # Tauri 2.0 desktop shell (Rust) — loads the apps/web build
├── sidecar/            # Node.js sidecar bundled into the Tauri desktop binary
└── docs/               # Architecture, contributing, threat model, and guides
```

### Packages

The monorepo has **28 packages** under `packages/`. They split into two groups.

**Product packages (15, MIT):**

| Package | Purpose |
|---|---|
| `agent` | Agent loop, orchestrator, tools, personas, workflows, and the evolution subsystem |
| `core` | Config, the encrypted vault, cron store, file store, telemetry, and compliance/audit |
| `server` | Fastify sidecar — local (solo) and team routes, SSE streaming, Stripe, KVARK client |
| `shared` | Shared types, Zod schemas, the tier system, and the MCP catalog |
| `marketplace` | Package catalog with the `SecurityGate` installer |
| `optimizer` | GEPA prompt optimization |
| `weaver` | Memory consolidation daemon |
| `waggle-dance` | Multi-agent coordination protocol |
| `worker` | Background job processor (BullMQ, team mode) |
| `sdk` | Plugin / skill SDK |
| `cli` | Command-line REPL |
| `launcher` | AI-tool launcher / dock backend |
| `admin-web` | Admin dashboard for team deployments |
| `wiki-compiler` | Knowledge / wiki compiler |
| `memory-mcp` | MCP server exposing the memory substrate to external agents |

**Memory substrate — `hive-mind-*` (13, Apache-2.0):** the persistent-memory core, mirrored to the public OSS repo [`marolinik/hive-mind`](https://github.com/marolinik/hive-mind).

| Package | Purpose |
|---|---|
| `hive-mind-core` | The memory substrate: `FrameStore`, `HybridSearch`, `KnowledgeGraph`, `IdentityLayer`, `AwarenessLayer`, plus Harvest ingestion (`src/mind` + `src/harvest`) |
| `hive-mind-cli` | CLI for the substrate |
| `hive-mind-mcp-server` | MCP server for the substrate |
| `hive-mind-shim-core` | Signal-emitter shim library |
| `hive-mind-wiki-compiler` | Wiki compiler (OSS) |
| `hive-mind-hooks-core` | Shared hook library |
| `hive-mind-hooks-*` | Per-tool capture hooks: `claude-code`, `claude-desktop`, `codex`, `codex-desktop`, `cursor`, `hermes`, `openclaw` |

> The memory substrate is developed **here** and mirrored out — never the reverse.
> See the "Memory Substrate Sync" section of [`CLAUDE.md`](./CLAUDE.md) before touching `packages/hive-mind-core`.

## Quick Start

### Self-host in one line (Linux / macOS)

```bash
curl -fsSL https://raw.githubusercontent.com/marolinik/waggle-os/main/install.sh | bash
```

Best for a VPS or homelab — this runs a headless Waggle server (no desktop shell):

- **Checks prerequisites, clones, builds, and starts** the Node.js sidecar, then prints the URL (`http://127.0.0.1:3333`). A 5-question wizard — install dir, port, data dir, build web UI, start now — is all Enter-defaulted; pass `--yes` to accept every default non-interactively.
- **Boots with zero API keys** in echo mode so the UI works immediately. Add a provider key later under **Settings → API Keys**, where it is stored in the encrypted vault — keys are never passed on the command line.
- **No sudo, ever.** A missing prerequisite prints the exact per-OS install command and exits; the installer never installs system packages for you.

Manage the running server with the installed wrapper: `scripts/waggle-server.sh status | logs | stop | start`. Re-running the one-liner against an existing install prints an upgrade hint instead of reinstalling.

### Run from source (development)

```bash
# Prerequisites: Node.js >= 20, npm
npm install

# (Optional) copy the env template. Provider API keys are normally set in-app
# (Settings → API Keys), which stores them in the encrypted vault — so you do
# NOT need to put keys in .env for a basic local run.
cp .env.example .env

# Terminal 1 — backend sidecar (http://localhost:3333)
npm run dev:server

# Terminal 2 — web app (http://localhost:8080)
npm run dev:web

# Open http://localhost:8080
```

`npm run dev:server` runs the Fastify sidecar via `tsx` (equivalent to
`cd packages/server && npx tsx src/local/start.ts`). `npm run dev:web` runs the
Vite dev server for `apps/web`.

**Embeddings.** By default `EMBEDDING_PROVIDER=auto` downloads a small in-process
model (~23 MB, cached under `~/.waggle/models/`) and works fully offline. For
better recall — and to reproduce any hive-mind benchmark — install
[Ollama](https://ollama.com), run `ollama pull nomic-embed-text`, and set
`EMBEDDING_PROVIDER=ollama`.

> **Windows:** if the sidecar fails to start with an esbuild platform error, see
> [Troubleshooting](docs/CONTRIBUTING.md#troubleshooting) in the contributing guide.

## Environment Variables

Provider keys are stored in the encrypted vault (set via **Settings → API Keys**)
and hydrated into the process at boot, so most of these are optional for a local
run. See [`.env.example`](./.env.example) for the full contract.

| Variable | Required | Description |
|----------|----------|-------------|
| `ANTHROPIC_API_KEY` | Recommended | Claude API key. Optional in `.env` — can be set in-app instead (vault). |
| `OPENAI_API_KEY` | No | Enables OpenAI models and optional OpenAI embeddings. |
| `EMBEDDING_PROVIDER` | No | `auto` (default) · `inprocess` · `ollama` · `voyage` · `openai` · `mock`. `auto` tries in-process → Ollama → API → mock. |
| `LITELLM_BASE_URL` | No | LiteLLM proxy URL for multi-model routing (default `http://localhost:4000`). |
| `DATABASE_URL` | Team only | PostgreSQL connection string. |
| `REDIS_URL` | Team only | Redis for the background job queue. |

## Documentation

- [Getting Started](docs/GETTING-STARTED.md) — first-run walkthrough
- [Architecture](docs/ARCHITECTURE.md) — package structure, data flow, extension points
- [Contributing](docs/CONTRIBUTING.md) — setup, tests, PR process, troubleshooting
- [Threat Model](THREAT_MODEL.md) — trust boundary and security controls
- [Security Policy](SECURITY.md) — how to report a vulnerability
- [Code of Conduct](CODE_OF_CONDUCT.md)

## License

This repository is licensed under the [MIT License](./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. See [Packages](#packages) for the split.