Merge P2.4: README and documentation for the community edition

This commit is contained in:
shumeiko.it
2026-11-01 02:20:13 +01:00
17 changed files with 1520 additions and 1529 deletions

92
CHANGELOG.md Normal file
View File

@@ -0,0 +1,92 @@
# Changelog
All notable changes to the Waggle community edition are listed here. The format follows
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
## Unreleased: first community edition
The first open-source release of Waggle, made from the commercial Waggle OS product. This entry
lists what changed for users compared with that product. The reasons are recorded in the
[decision records](docs/oss/adr/README.md).
### Removed
- **Billing and plans.** Trial, Solo, Teams and Enterprise plans, Stripe checkout, license
checks, trial banners and upgrade prompts. Everything a plan used to unlock is available
(ADR-0001).
- **KVARK** enterprise retrieval, its agent tools, and the enterprise capability packs.
- **Compliance reports** and the compliance subsystem.
- **Self-learning** (ADR-0004): behavior evolution and prompt optimization (the `optimizer`
package), learning from corrections, the Evolution screen (Memory → Improvements), the
nightly prompt-optimization and monthly-assessment jobs, and the idle-session reviewer.
Thumbs up and down are still stored, and corrections you make are saved as ordinary memories.
- **Team mode** (ADR-0003): connecting to a team server, team workspaces and shared memory,
WaggleDance, the team screens, and S3 file storage for workspaces. The code stays in the
repository but is not built or shipped.
- **Features of the old memory engine** (ADR-0002): the knowledge graph, the wiki, importing chat
history from ChatGPT and Claude exports, memory consolidation, the memory server for
external tools (MCP), and the memory hooks for Claude Code, Codex and other coding agents.
- **`install.sh`** and `scripts/waggle-server.sh`, replaced by the server installer.
- The automatic start of a LiteLLM proxy, which needed Python. It is now opt-in (see Changed).
### Changed
- **Memory runs on local mem0** behind a memory contract (ADR-0002, ADR-0007). Memories are kept
in `~/.waggle/memory/`, embedded by a model that runs on your computer, and searched with
mem0's combined vector and keyword search. Nothing goes to a cloud memory service. Memories
from the old `.mind` files are not carried over. See [docs/memory.md](docs/memory.md).
- **Waggle's own data** (automations, notifications, cost tracking, your profile card and task
list) moved to a separate `waggle.db`, apart from memory.
- **Analytics are opt-in** (ADR-0006). Waggle asks once; nothing is sent until you choose
**Allow**, and Settings → General → Privacy & Telemetry turns it off again. When allowed,
Waggle sends one event at the end of setup with the template, persona and model you chose.
- **WhatsApp uses `whatsapp-web.js`** instead of Baileys (ADR-0005). Pair your phone again with
the QR code. The session is kept in the data directory as a browser profile, protected by file
permissions rather than the vault. If no Chrome, Edge or Chromium is installed, Waggle
downloads Chrome for Testing (about 170 MB) the first time you start WhatsApp. The channel
handles text messages only.
- **`npx @waggle-ai/waggle` installs a prebuilt server** (ADR-0009) instead of running the server
from npm. It adds the `waggle-server` command with `run`, `doctor`, `update` and `uninstall`,
and the installed server serves the web UI. The package and command names are temporary.
- **Desktop app and server archives carry their own Node.js** (22.23.2) with matching native
modules, so no Python or compiler is needed to install (ADR-0008).
- **Model calls go through the built-in provider proxy** by default. LiteLLM runs only when
`config.json` contains `"litellm": { "enabled": true }`, on your own Python.
- **The Waggle-managed Ollama runtime works on Linux**, and installs no longer download CUDA
libraries.
- **The recall reranker is off by default**; `WAGGLE_RERANKER=1` turns it on.
- **The license is MIT** for the whole repository. Notices for shipped third-party components are
in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
- UI text no longer uses decorative emoji or em dashes, and generic AI icons were replaced.
### Added
- **Background fact extraction.** While you chat, Waggle can save facts about you to personal
memory, every six messages or after a two-minute pause, with the model you chat with. Turn it
off in Settings → General → Memory.
- **Memory capabilities.** The UI hides memory features the store does not support.
- **The server installer** (`packages/launcher`): `install`, `run`, `doctor`, `update` and
`uninstall`, with SHA-256 checks of the downloaded archive.
- **A license check** for shipped npm packages and Rust crates.
- **A new design**, off by default, switched on with "New design" at the bottom of the sidebar.
- **A bottom navigation bar on phones**, instead of the sidebar rail.
### Fixed
Fixes made while preparing this edition. Each is recorded in
[docs/oss/upstream-fixes.md](docs/oss/upstream-fixes.md).
- The packaged macOS app could not find its bundled server and stayed on "Starting Waggle…"
(UF-004).
- On macOS and Linux the desktop app stopped its server without letting it shut down (UF-046).
- Local model downloads were cancelled after five minutes (UF-008).
- A working API key showed as not responding, and other internal model calls failed (UF-044).
- A memory saved to an unknown workspace landed in personal memory (UF-039).
- Memory searches from Timeline and the chat recall toast used the wrong scope (UF-035), and the
command palette searched the wrong workspace (UF-033).
- The web client showed "important" and "temporary" memories as normal (UF-036).
- Generating a persona from a description failed (UF-045).
- The onboarding Industry dropdown opened under the dialog (UF-007), and startup text was
invisible in the light theme (UF-017).
- Brand fonts did not load under the content security policy.
- Smaller interface fixes: UF-042, UF-043, UF-047 to UF-057.

View File

@@ -66,6 +66,10 @@ and fairly.
All community leaders are obligated to respect the privacy and security of the
reporter of any incident.
Security vulnerabilities are not conduct issues. Report them privately as
described in [SECURITY.md](SECURITY.md): through GitHub private vulnerability
reporting, or to **hello@egzakta.com** if you cannot use GitHub.
## Enforcement Guidelines
Community leaders will follow these Community Impact Guidelines in determining

131
CONTRIBUTING.md Normal file
View File

@@ -0,0 +1,131 @@
# Contributing to Waggle
Thank you for helping. This page covers the setup, the checks and how to propose a change.
**Read [AGENTS.md](AGENTS.md) before you change code.** It is the operating contract for this
repository, for people and coding agents alike: what is in scope, the rules that must not be
broken, and the commands that verify a change. The decisions behind it are in
[docs/oss/adr/](docs/oss/adr/README.md). [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) explains
how the parts fit together.
## Prerequisites
- Node.js `^20.19.0` or `>=22.12.0`, and npm. Node 22 is recommended; the release builds bundle
22.23.2.
- Git.
- For the desktop app only: a current Rust toolchain, plus the platform's Tauri prerequisites
(on Windows, Visual Studio Build Tools with the C++ workload; see
[docs/oss/build-windows.md](docs/oss/build-windows.md)).
Python, Docker and a database server are not needed.
## Setup
Clone the repository, then in its root:
```bash
npm ci
npm run build # type-checks the web UI and builds it into dist/
npm run dev:server # the sidecar on http://localhost:3333, serving dist/
```
Open http://localhost:3333 and add a model in Settings → Models.
- Workspace packages export their TypeScript source under the `source` condition, which tsx,
Vitest, Vite and the sidecar build resolve. You do not need `npm run build:packages` before
running or testing; it type-checks the packages and builds their `dist/` for publishing.
- The sidecar registers the files in `dist/` when it starts. After `npm run build`, restart it,
or new assets return 404.
- `npm run dev:web` (Vite) cannot authenticate against the sidecar yet. Use the UI the sidecar
serves.
- Run one sidecar at a time. To keep test data apart from your own, start it with another data
directory: `WAGGLE_DATA_DIR=/tmp/waggle-dev npm run dev:server`.
Other entry points:
```bash
npm run dev -w @waggle/cli # terminal REPL on the same memory and waggle.db
(cd app && npm ci && npm run tauri:build:mac:arm64) # desktop app; see AGENTS.md section 4
```
## Checks
Run the checks that cover your change before you open a pull request. CI runs them too.
```bash
npm run build:packages # tsc -b over every in-scope package
npm run typecheck:web # the web UI
npx tsc --noEmit --project app/tsconfig.json
npm run typecheck:tests # test suites; advisory until existing errors are fixed
npm run lint # root config; ignores apps/web
(cd apps/web && npx eslint .) # web config
npm run check:deps # every imported package is declared in its package.json
npm run check:licenses # shipped dependencies allow MIT distribution
npm test # root Vitest: packages, tests/, scripts/
(cd apps/web && npx vitest run) # web UI tests
```
Some checks fail before your change: [docs/oss/baseline.md](docs/oss/baseline.md) records the
known failures and counts. A check that passes there must not start failing.
End-to-end tests use Playwright (`npm run test:e2e`). They reuse a server already listening on
:3333 and its data directory. For an isolated run set `WAGGLE_E2E_REUSE_EXISTING_SERVER=0` and a
free `WAGGLE_E2E_PORT`. The e2e web server step runs `npm run build:all`, which rewrites `dist/`.
Tests live in each package's `tests/` directory, in `apps/web/src` next to the code, and in the
root `tests/`. New behavior needs a test; a bug fix needs a test that fails without the fix.
## Rules that reviews check first
The full list is in [AGENTS.md](AGENTS.md), section 3. In short:
- No monetization: no tiers, trials, payments, license checks or upsell.
- Memory goes through `MemoryStore` from `@waggle/memory-contract`. No SQL against a memory
database, and no knowledge graph in this release.
- Team mode (`packages/team-server`, `waggle-dance`, `worker`) is frozen, and self-learning is
out of scope.
- Every new dependency must allow MIT distribution: no GPL or AGPL code in shipped artifacts.
Name its license in the commit message.
- Analytics stay opt-in. Never commit a PostHog key or any other secret.
- Platform-specific code needs Windows, macOS and Linux paths. End users must not need Python,
Docker, a compiler or a developer Node.js install.
- Security constraints (secrets in the vault, the injection scanner on external input, no
`eval`, an explicit Tauri IPC allowlist, parameterized SQL) are in AGENTS.md, section 8.
## Code style
- TypeScript in strict mode, ES modules, `.js` extensions in relative imports, and
`import type` for types.
- File names in `kebab-case.ts`; React components in `PascalCase.tsx`.
- Match the style of the file you change. Do not reformat code you do not otherwise touch.
- Search before you add a file: [AGENTS.md](AGENTS.md), section 9, lists modules that already
exist.
- Code, comments, commit messages and documentation are in English. Write plainly.
## Commits and pull requests
- One focused change per pull request. Describe what changed, why, and how you tested it.
- Commit messages: `type(scope): summary` in the imperative, for example
`fix(server): close the memory recall step when nothing is found`. Types: `feat`, `fix`,
`refactor`, `test`, `docs`, `build`, `chore`, `perf`.
- Keep commits small enough to review. Do not mix a refactor with a behavior change.
- Never commit secrets, `.env` files or personal data.
## Reporting bugs and security issues
Open an issue for bugs and feature proposals. Report security vulnerabilities privately as
described in [SECURITY.md](SECURITY.md), not in a public issue.
## Troubleshooting
**Windows: the sidecar fails to start with an esbuild error** such as
`Cannot find module @esbuild/win32-x64`. npm skipped esbuild's platform binary. Install the
binary that matches the esbuild version named in the error, without changing `package.json`:
```bash
npm i @esbuild/win32-x64@<version> --no-save
```
**Assets return 404 after a build.** Restart the sidecar; see Setup.
More user-facing problems are in [docs/guides/troubleshooting.md](docs/guides/troubleshooting.md).

138
README.md
View File

@@ -1,89 +1,113 @@
# Waggle OS Community Edition
# Waggle 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.
Waggle is an AI agent workspace that runs on your own computer. You organize work into
workspaces; in each one an agent chats with you, uses tools (files, web search, documents,
connected services), runs scheduled automations, and remembers facts and decisions between
chats. Memory, settings and keys stay on your computer.
> **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`](AGENTS.md) and the decision records in
> [`docs/oss/adr/`](docs/oss/adr/README.md).
The agent needs a model: a local model that Waggle downloads and runs for you, or your own key
for a provider such as Anthropic, OpenAI or Google.
## Repository layout
This is the open-source community edition (MIT). It has no paid tiers, no license checks and no
team features. Analytics are off unless you allow them.
```
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
## Install
Two ways, on Windows x64, macOS (Apple silicon and Intel) and Linux x64:
- **Desktop app.** Download the installer for your system (`.exe` or `.msi`, `.dmg`, `.deb` or
`.AppImage`) and run it. The first release is unsigned, so Windows and macOS show a warning
the first time; [the install guide](docs/install.md) shows how to get past it.
- **Server installer.** Install the server and use Waggle in your browser:
```bash
npx @waggle-ai/waggle install --from <archive path or URL>
waggle-server # starts Waggle at http://localhost:3333
```
`AGENTS.md` lists the status of every package in this edition.
Node.js 20 or newer is needed only for the `npx` call. The package and command names are
temporary, and there is no default download location yet, which is why `--from` is needed
for now.
Neither way needs Python, Docker or a compiler. Details, updates and uninstalling:
[docs/install.md](docs/install.md).
## What is in this edition
- Workspaces with chat sessions, files and a choice of personas
- Memory on your computer: facts, search and a profile of what Waggle learned about you, through
a memory contract backed by a local [mem0](https://github.com/mem0ai/mem0) store
([docs/memory.md](docs/memory.md))
- Models: the Waggle-managed Ollama runtime, an Ollama you run, or your own provider keys
- Skills, plugins, MCP servers and a marketplace with a security scan before install
- Connectors (GitHub, Slack, Jira, Notion, Google Workspace and Microsoft apps among others) and
messaging channels (Telegram, Discord, Slack, WhatsApp)
- Automations, approvals for sensitive actions, cost tracking and budgets
- An encrypted vault for keys and credentials
Not in this edition: billing and tiers, KVARK, compliance reports, self-learning, team mode, the
knowledge graph, chat-history import, the wiki, memory hooks for external coding agents (Claude
Code, Codex) and the memory server for external tools (MCP).
[CHANGELOG.md](CHANGELOG.md) lists what changed from the commercial product.
## Run from source
Prerequisites: Node.js `^20.19.0` or `>=22.12.0`, and npm.
Prerequisites: Node.js `^20.19.0` or `>=22.12.0` (22 recommended) and npm.
```bash
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
npm ci
npm run build # type-checks the web UI and builds it into dist/
npm run dev:server # the sidecar on http://localhost:3333, serving dist/
```
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`](docs/oss/upstream-fixes.md)).
Open http://localhost:3333. After changing the UI, run `npm run build` again and restart the
sidecar: it registers the files in `dist/` when it starts. The Vite dev server
(`npm run dev:web`) cannot sign in to the sidecar yet.
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.
Workspace packages are resolved from their TypeScript source, so no package build is needed
before running or testing. Data goes to `~/.waggle` unless you set `WAGGLE_DATA_DIR`.
**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](https://ollama.com), run `ollama pull nomic-embed-text`, and set
`EMBEDDING_PROVIDER=ollama`.
Add a model in the app (Settings → Models). `.env.example` lists optional environment
variables; a basic local run needs none of them.
| 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. |
The desktop app and release archives are built per system:
see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#how-a-release-is-built).
## Checks
```bash
npm run build:packages # build all workspace packages
npm run build:packages # type-check every package
npm run typecheck:web # type-check the web UI
npm run lint # lint the packages
(cd apps/web && npx eslint .) # lint the web UI
npm run check:deps # every import is a declared dependency
npm test # unit tests
npm run check:licenses # shipped dependencies allow MIT distribution
npm test # unit tests (packages, tests/, scripts/)
(cd apps/web && npx vitest run) # web UI unit tests
```
Known failures and the numbers to compare against are in
[`docs/oss/baseline.md`](docs/oss/baseline.md).
[CONTRIBUTING.md](CONTRIBUTING.md) has the full list, and
[docs/oss/baseline.md](docs/oss/baseline.md) records the known failures to compare against.
## Documentation
- [Getting Started](docs/GETTING-STARTED.md)
- [Install](docs/install.md)
- [Getting started](docs/guides/getting-started.md)
- [Workspaces](docs/guides/workspaces.md)
- [Skills, plugins and the marketplace](docs/guides/capabilities.md)
- [Connectors and channels](docs/guides/connectors.md)
- [Troubleshooting](docs/guides/troubleshooting.md)
- [Memory](docs/memory.md)
- [Architecture](docs/ARCHITECTURE.md)
- [Contributing](docs/CONTRIBUTING.md)
- [Threat Model](THREAT_MODEL.md)
- [Security Policy](SECURITY.md)
- [Code of Conduct](CODE_OF_CONDUCT.md)
The guides predate the community edition and still describe some removed features; they
are rewritten before the first release.
- Reference: [slash commands](docs/reference/commands.md), [local API](docs/reference/api.md)
- [Decision records](docs/oss/adr/README.md)
- [Contributing](CONTRIBUTING.md), [Security policy](SECURITY.md),
[Threat model](THREAT_MODEL.md), [Code of conduct](CODE_OF_CONDUCT.md)
- [Changelog](CHANGELOG.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.
The code in this repository is licensed under the [MIT License](LICENSE).
Waggle uses third-party packages under their own licenses. The notices for the components that
ship with Waggle are in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

View File

@@ -1,63 +1,72 @@
# Security Policy
Waggle OS runs on a user's own machine and touches sensitive material — API
keys, connector credentials, the local filesystem, and imported conversation
history. We take reports seriously and appreciate responsible disclosure.
Waggle runs on the user's own computer and handles sensitive material: provider API keys,
connector credentials, the local file system, chats and memories. We take reports seriously
and appreciate responsible disclosure.
For the trust boundary, the controls that enforce it, and the currently known
gaps, read [`THREAT_MODEL.md`](./THREAT_MODEL.md). It is the authoritative
description of what Waggle defends against and what it does not.
[`THREAT_MODEL.md`](./THREAT_MODEL.md) describes the trust boundary, the controls that enforce
it and the known gaps.
## Reporting a Vulnerability
## Supported versions
**Please do not open a public GitHub issue for security vulnerabilities.**
| Version | Supported |
|---|---|
| The latest community edition release | Yes |
| Earlier community edition releases | No. Update to the latest release. |
| Unreleased code on the default branch | Best effort |
Report privately through either channel:
The commercial Waggle OS product is not covered by this policy.
1. **GitHub Security Advisories (preferred).** On the repository, go to the
**Security** tab → **Report a vulnerability**. This opens a private advisory
visible only to the maintainers.
2. **Email.** Send details to **marko@egzakta.com** with `SECURITY` in the
## Reporting a vulnerability
**Do not open a public issue for a security vulnerability.**
1. **GitHub private vulnerability reporting (preferred).** On the repository, open the
**Security** tab and choose **Report a vulnerability**. The report is visible only to the
maintainers.
2. **Email, if you cannot use GitHub.** Write to **hello@egzakta.com** with `SECURITY` in the
subject line.
Please include:
- A description of the issue and the impact you believe it has.
- Step-by-step reproduction instructions (or a proof of concept).
- The affected component/package and version or commit SHA.
- Your environment (OS, Node version, desktop build vs. web).
- what the issue is and the impact you expect;
- steps to reproduce it, or a proof of concept;
- the affected component and the version or commit;
- your environment: operating system, desktop app or server installer, and the model provider
if it matters.
## What to Expect
## What to expect
- **Acknowledgement** within 5 business days.
- An initial assessment and severity classification shortly after.
- Coordinated disclosure: we will agree on a timeline with you and credit you in
the release notes unless you prefer to remain anonymous.
- An acknowledgement within 5 business days.
- An assessment and a severity rating after that.
- Coordinated disclosure: we agree on a timeline with you and credit you in the release notes
unless you prefer to stay anonymous.
Please give us a reasonable window to release a fix before any public
disclosure.
Please give us reasonable time to release a fix before you disclose the issue publicly.
## Scope
In scope:
- The desktop app (Tauri shell + bundled sidecar), the web app, and the
workspace packages under `packages/` and `apps/`.
- Memory (`packages/memory-contract`, `packages/memory-mem0`).
- Prompt-injection paths, secret handling (the vault), the filesystem boundary,
and the capability/approval gates — see `THREAT_MODEL.md` for the details.
- the desktop app (the Tauri shell and its bundled server);
- the server installer (`packages/launcher`) and the server archives it installs;
- the web UI (`apps/web`) and the shipped packages under `packages/`;
- memory (`packages/memory-contract`, `packages/memory-mem0`);
- prompt-injection paths, secret handling in the vault, the file-system boundary, the local
API's authentication, and the approval gates.
Out of scope (documented, not vulnerabilities):
Out of scope:
- The known gaps enumerated in `THREAT_MODEL.md` (e.g. the pattern-based
injection scanner and the absence of an OS-level shell sandbox). If you can
demonstrate impact meaningfully beyond what is already documented there, we
still want to hear about it.
- Findings that require a compromised operator account or physical access to the
user's machine — the operator is trusted by design.
- the known gaps listed in `THREAT_MODEL.md`, such as the pattern-based injection scanner and
the absence of an operating-system sandbox for shell commands. If you can show impact beyond
what is documented there, we still want to hear about it;
- findings that need control of the user's account or physical access to the computer: the user
is trusted by design;
- team mode packages (`packages/team-server`, `packages/waggle-dance`, `packages/worker`), which
are not built or shipped in this edition;
- third-party services that Waggle connects to.
## Secrets
If a report involves an exposed secret (an API key, token, or credential), note
it explicitly so we can rotate it immediately. Never include live secrets in a
public issue or PR.
If a report involves an exposed secret (an API key, a token or a credential), say so clearly so
it can be rotated at once. Never put live secrets in a public issue or pull request.

View File

@@ -1,263 +1,218 @@
# Architecture
Waggle is a monorepo with **28 packages** under `packages/` organized around a layered architecture: the memory substrate, agent intelligence, server API, and UI presentation. This document covers the package structure, data flow, and extension points.
How the community edition of Waggle is put together: the parts, how a chat turn flows through
them, where data lives and how a release is built. The decisions behind it are in
[`docs/oss/adr/`](oss/adr/README.md); [`AGENTS.md`](../AGENTS.md) lists the status of every
package.
> **Note:** memory goes through `@waggle/memory-contract`, implemented on local
> mem0 by `@waggle/memory-mem0` (ADR-0007). The React UI is **not** a package — it
> lives in `apps/web/src`. There is no `@waggle/ui` package. This document predates
> the community edition and is rewritten in P2.4.
## Package Overview
## Overview
```
waggle-os/
apps/
web/ # Main web app UI (React 19 + Vite + Tailwind 4 + base-ui/react)
browser-ext/ # Browser extension (unpacked; not an npm workspace)
packages/
# Product packages (MIT)
agent/ # Agent loop, tools, sub-agents, workflows, trust, hooks, personas, evolution
core/ # Config, vault (secrets), cron, file store, telemetry, compliance/audit
server/ # Fastify API server, local + team routes, daemons, KVARK client, scheduler
shared/ # Shared types, Zod schemas, tiers, MCP catalog
marketplace/ # Marketplace catalog, installer, security gate, sync
optimizer/ # Prompt optimization (GEPA engine)
weaver/ # Memory consolidation daemon
waggle-dance/ # Swarm orchestration protocol
worker/ # Background task processing (BullMQ)
sdk/ # Plugin/skill SDK, capability packs, starter skills
cli/ # Command-line REPL
launcher/ # AI-tool launcher / dock backend
memory-contract/ # MemoryStore interface, record model, capability map
memory-mem0/ # MemoryStore on local mem0
sidecar/ # Node.js sidecar for Tauri desktop app
app/ # Tauri 2.0 desktop shell (Rust + WebView2) — loads the apps/web build
Browser tab or Tauri window
┌──────────────────────────┐
│ Web UI (apps/web, React) │
└────────────┬─────────────┘
│ HTTP + Server-Sent Events, bearer session token
▼
┌─────────────────────────────────────────────────────────────┐
│ Sidecar: Fastify on Node.js, 127.0.0.1:3333 │
│ (packages/server/src/local) │
│ │
│ agent runtime ─────── built-in provider proxy ──► provider │
│ (packages/agent) (/v1/chat/completions) APIs or │
│ Ollama │
│ MemoryStore ──► @waggle/memory-mem0 ──► <data>/memory/ │
│ WaggleDB ─────► <data>/waggle.db │
│ vault ────────► <data>/vault.json │
│ connectors, channels, scheduler, marketplace, skills │
└─────────────────────────────────────────────────────────────┘
```
## Package Details
Everything runs on the user's computer. The only outside calls are the ones the user sets up:
model providers, connectors, messaging channels, marketplace sources, downloads of local
models and the embedding model, and analytics if the user allows them.
### @waggle/memory-contract and @waggle/memory-mem0
## Parts
`MemoryStore` (remember, search, list, get, update, forget, history) with its record
model and capability map, and its implementation on the open-source mem0 library,
running locally in the sidecar (ADR-0007).
### Web UI (`apps/web`)
### @waggle/core
React 19, TypeScript, Vite 6, Tailwind CSS 3.4 and Radix UI primitives. It is an application,
not a package. `npm run build` builds it into the root `dist/`, which the sidecar serves; the
desktop build uses `apps/web/dist`.
The foundation layer for the desktop/server runtime. Zero network dependencies.
The UI talks to the sidecar over HTTP, with Server-Sent Events for chat streaming and
notifications. Every `/api/*` request carries a bearer session token. A page served by the
sidecar gets the token from `GET /api/auth/session-token`, which answers same-origin requests
only; the desktop window gets it through a per-launch credential from the Tauri shell.
- **WaggleConfig**: Configuration management (`~/.waggle/config.json`). Provider keys, default model, team server config.
- **Vault**: AES-256-GCM encrypted secret storage. Stores API keys, connector credentials, and sensitive metadata.
- **MultiMind**: Manages personal + workspace minds simultaneously — routes searches to both and merges results.
- **FileStore**: Workspace filesystem access with a segment-boundary + symlink-aware containment guard and a secret deny-list (see the [threat model](../THREAT_MODEL.md)).
- **CronStore**: Schedule management for the cron service. CRUD on cron expressions with last/next run tracking.
- **ImportParser** (`memory-import.ts`): parses ChatGPT and Claude export files into importable knowledge items.
- **Telemetry / Compliance**: telemetry pipeline and compliance reporting (`compliance/`).
Product analytics (PostHog) start only after the user allows them, and only in builds that carry
a key in `VITE_POSTHOG_KEY` (ADR-0006).
### @waggle/agent
### Sidecar (`packages/server/src/local`)
The intelligence layer. Orchestrates tool execution, sub-agents, and workflows.
A Fastify server on Node.js. In development it runs from TypeScript source with tsx; for
release it is bundled into one `service.js` with esbuild. It listens on `127.0.0.1` port 3333
by default (`WAGGLE_PORT`, `WAGGLE_HOST`), rejects requests whose `Host` header is not local,
and serves the web UI from `WAGGLE_FRONTEND_DIR` or the root `dist/`.
- **AgentLoop**: Core loop that sends messages to the LLM, parses tool calls, executes tools, and streams results. Supports up to 200 turns per conversation.
- **Tools (97+)**: Organized across 12 categories:
- System tools: `bash`, `read_file`, `write_file`, `edit_file`, `search_files`, `search_content`, `list_directory`
- Memory tools: `search_memory`, `save_memory`, `forget_memory`
- Web tools: `web_search`, `web_fetch`
- Git tools: `git_status`, `git_diff`, `git_log`, `git_commit`
- Plan tools: `create_plan`, `add_plan_step`, `execute_step`, `show_plan`
- Document tools: `generate_docx`
- Sub-agent tools: `spawn_agent`, `coordinate_agents`
- Skill tools: dynamically generated from installed skills
- KVARK tools: `kvark_search`, `kvark_ask_document`, `kvark_feedback`, `kvark_action`
- Team tools: `request_team_capability`, `assign_task`, `update_task`
- Audit tools: `audit_trail`, `trust_assessment`
- Connector tools: dynamically generated from connected services
- **CapabilityRouter**: Routes user intents to the appropriate tool or workflow based on context.
- **WorkflowComposer**: Dynamically composes multi-step workflows from templates.
- **Workflow Templates**: `research-team` (parallel research), `review-pair` (draft + review), `plan-execute` (plan + execute steps).
- **SubagentOrchestrator**: Manages sub-agent lifecycle -- spawning, monitoring, result collection.
- **CommandRegistry**: Slash command registration and execution (14 commands).
- **HookRegistry**: Event-driven hooks (before/after tool calls, session start/end, etc.).
- **Personas**: 8 predefined agent configurations with system prompts and tool presets.
- **TrustModel**: Assesses capability risk level, trust source, and approval class.
- **SkillRecommender**: Context-aware skill suggestions based on conversation content.
It holds:
### @waggle/server
- the HTTP routes (`routes/`) for chat, workspaces, sessions, memory, settings, vault, skills,
plugins, connectors, marketplace, automations and the rest;
- the **built-in provider proxy** (`routes/anthropic-proxy.ts`): an OpenAI-compatible
`/v1/chat/completions` endpoint that translates Claude requests to Anthropic's Messages API
and forwards requests for other providers to their OpenAI-compatible APIs. The agent loop and
memory extraction call cloud models through it (or through LiteLLM when the user runs it);
- the **managed Ollama runtime** (`managed-ollama-runtime.ts`): downloads the official Ollama
build, checks its SHA-256 and size, and runs it on `127.0.0.1:11434` with models in
`<data>/models/ollama`;
- the scheduler for automations (`cron.ts`), notifications, held actions and approvals;
- messaging channels (`channels/`): Telegram, Discord, Slack, and WhatsApp through
`whatsapp-web.js` (ADR-0005);
- the memory store and background fact extraction (`memory-runtime.ts`,
`memory-extraction.ts`).
The API layer. Fastify server exposing 29 route modules.
An optional LiteLLM proxy runs only when `config.json` contains `"litellm": { "enabled": true }`,
on the user's own Python. Nothing else needs Python.
- **Local Server** (`src/local/`): Solo mode on localhost:3333. Routes for chat, workspaces, sessions, memory, settings, vault, skills, plugins, connectors, marketplace, cron, fleet, etc.
- **InstallAuditStore** (`src/local/install-audit.ts`): append-only capability-install trail (proposed / approved / installed / rejected / uninstalled) in `waggle.db`, shown in the Audit and Activity tabs.
- **Team Server** (`src/routes/`): Multi-user mode with PostgreSQL (Drizzle ORM), Redis, Clerk auth, and WebSocket presence.
- **SSE Streaming**: Chat responses stream via Server-Sent Events.
- **Anthropic Proxy**: Built-in `/v1/chat/completions` endpoint that translates OpenAI format to Anthropic API.
- **KVARK Client** (`src/kvark/`): HTTP facade for enterprise retrieval. User-level Bearer tokens.
- **Daemons**: Background processes (memory consolidation, proactive checks).
- **Scheduler** (`src/scheduler/`): LocalScheduler that ticks cron schedules and dispatches jobs.
- **ConnectorRegistry**: Registers and manages 29 native connectors. Generates agent tools from connected services.
- **Session Manager**: Manages parallel workspace sessions for Mission Control.
- **Notification System**: Event bus + SSE stream for real-time notifications (cron, approval, task, agent events).
### Agent runtime (`packages/agent`)
### apps/web (UI)
The agent loop (`agent-loop.ts`), the orchestrator that builds the system prompt and recalls
memory (`orchestrator.ts`), personas (`persona-data.ts`, `personas.ts`), tools, slash
commands (`commands/`), sub-agents and workflow templates, connectors (`connectors/`), MCP
client support (`mcp/`), the injection scanner and cost tracking (`cost-tracker.ts`).
The React UI is an application, not a package — it lives in `apps/web/src`
(React 19 + Vite + Tailwind 4 + base-ui/react). There is no `@waggle/ui`
package. The desktop binary (`app/`) loads the `apps/web` build. Representative
surfaces:
### Other packages
- **ChatArea**: Main conversation interface with streaming, tool cards, approval gates, and file upload.
- **MemoryBrowser**: Frame list with search, importance filters, and knowledge graph visualization.
- **WorkspaceHome**: Context-rich home screen with summary, decisions, threads, and suggestions.
- **Settings**: Tabbed settings (Models, Permissions, Vault, Appearance, Advanced).
- **Cockpit**: System dashboard showing health, schedules, runtime stats, connectors, trust audit.
- **Capabilities**: Skill/pack browser with install state and family grouping.
- **Events**: Tool event log with grouping and completion animations.
- **Onboarding**: First-run setup flow (API key, workspace creation, starter skills, import).
| Package | Role |
|---|---|
| `@waggle/core` | Config (`config.json`), the vault, `WaggleDB` (`waggle.db`), workspaces, file storage, embeddings, local telemetry, logger |
| `@waggle/shared` | Shared types, Zod schemas, the MCP server catalog |
| `@waggle/memory-contract` | The `MemoryStore` interface, record model, capability map, an in-memory store and the compatibility suite |
| `@waggle/memory-mem0` | `MemoryStore` on the open-source mem0 library |
| `@waggle/marketplace` | Marketplace catalog (SQLite with full-text search), installer, security scan, sync |
| `@waggle/sdk` | Skill and plugin SDK, starter skills, capability packs |
| `@waggle/cli` | A terminal REPL on the same memory store and `waggle.db` |
| `@waggle-ai/waggle` (`packages/launcher`) | The server installer (`install`, `run`, `doctor`, `update`, `uninstall`) |
### @waggle/marketplace
`packages/team-server`, `packages/waggle-dance` and `packages/worker` hold team mode. They stay
in the repository but are not built, tested in the root run, or shipped (ADR-0003).
`apps/browser-ext` is not part of the release.
Marketplace infrastructure. SQLite-based catalog with FTS5 search.
### Desktop shell (`app/`)
- **MarketplaceDB**: 120+ packages across skills, plugins, and MCP servers. Auto-seeded from bundled data.
- **MarketplaceInstaller**: Install/uninstall with dependency tracking.
- **SecurityGate**: Heuristic-based security scanner. Scans for dangerous patterns before install.
- **MarketplaceSync**: Syncs catalog from configured sources.
- **Enterprise Packs**: KVARK-dependent packs (only available with enterprise connection).
A Tauri 2 shell in Rust (`app/src-tauri`). There is no separate frontend in `app/`: the window
loads the `apps/web` build. The shell:
### @waggle/waggle-dance
- starts the bundled sidecar with the bundled Node.js, on port 3333 or a free port if 3333 is
taken, waits until it reports ready, and stops it (SIGTERM first) when the app quits;
- writes the sidecar's output to `<data>/logs/service.log`;
- keeps one instance running, adds a tray icon, and toggles the window with Ctrl+Shift+W;
- exposes a short list of IPC commands, allowed explicitly in `app/src-tauri/capabilities/`.
Swarm orchestration protocol for multi-agent coordination.
## A chat turn
- **Protocol**: Message types for task assignment, status updates, and result collection.
- **Dispatcher**: Routes work to available agents based on capability and load.
- **HiveQuery**: Broadcast queries across multiple agents for parallel investigation.
1. The UI sends `POST /api/chat` with the message, workspace and session, and reads the reply as
a Server-Sent Events stream.
2. The orchestrator recalls memory for the message (see [memory.md](memory.md)) and builds the
system prompt from the core rules, the persona, active skills and workspace context.
3. The agent loop calls the model through the built-in proxy (local Ollama models are called
directly). When the model asks for a tool,
the loop checks the approval rules (some actions wait for the user to approve), runs the
tool, and scans the tool output for prompt injection before the model sees it. External
output is passed to the model as data, never as instructions.
4. Text, tool calls and approval requests stream to the UI as they happen.
5. The session is appended to `<data>/workspaces/<id>/sessions/<session>.jsonl`. Costs go into
the execution traces in `waggle.db`, and the finished turn is queued for background fact
extraction.
### @waggle/worker
## Data
Background task processing for team mode.
One data directory per user: `WAGGLE_DATA_DIR`, or `~/.waggle`. [install.md](install.md#where-your-data-lives)
lists what it contains.
- **BullMQ Integration**: Redis-backed job queues.
- **Execution Strategies**: Parallel (fan-out), sequential (pipeline), and coordinator (master-worker).
- **Agent Worker**: Real `runAgentLoop` execution in background worker processes.
- **Memory** goes only through `MemoryStore` (`@waggle/memory-contract`). The shipped store keeps
its SQLite files in `<data>/memory/`. Embeddings come from an in-process model, so memory
works offline. See [memory.md](memory.md).
- **`waggle.db`** holds Waggle's own data, which is not memory: automations, notifications,
held actions, skill hashes, thumbs feedback, cost tracking, the install audit trail, the file
index, and the profile card and task list per scope.
- **The vault** (`vault.json`, key in `.vault-key`) keeps provider keys and connector credentials,
each encrypted with AES-256-GCM.
- Local telemetry (`telemetry.db`, off by default) and the audit log (`audit.db`) have their own
files.
## Data Flow
The SQLite files are opened with better-sqlite3, a native module (ADR-0008).
### Chat Message Flow
## Models
```
User Input
--> POST /api/chat (Fastify route)
--> Workspace context loaded (memory, state, persona)
--> System prompt composed (core + persona + skills + context)
--> runAgentLoop() invoked
--> LLM API call (Anthropic proxy or direct)
--> Tool calls parsed and executed
--> Approval gate check (if sensitive)
--> Tool result returned
--> Memory auto-save (decisions, facts, preferences)
--> SSE events streamed to client
--> Session persisted to .jsonl file
--> UI renders streaming response
- **Provider keys.** The user enters keys in Settings → Models or in the Vault. The proxy calls
the provider directly from the user's computer.
- **Local models.** The Waggle-managed Ollama runtime, or an Ollama the user already runs
(`OLLAMA_HOST`, default `http://localhost:11434`).
- **Cost tracking.** `CostTracker` prices each call and the execution traces are kept in
`waggle.db` (ADR-0004). Settings → Models sets an optional daily budget.
## Installer and server archive
The server installer (`packages/launcher`, ADR-0009) is one self-contained script that uses only
Node.js built-in modules. It downloads or reads a server archive, checks its SHA-256, unpacks it
into a per-user program directory and writes a `waggle-server` command. The command runs the
archive's own Node.js, so the user's Node.js is needed only for the first `npx` call.
A server archive (`waggle-server-<version>-<target>.tar.gz`) contains the same sidecar payload
the desktop app ships, the built web UI under `web/`, and a `manifest.json` with the version,
target and Node.js version. `run` starts `service.js` with the environment the desktop shell
uses, plus `WAGGLE_FRONTEND_DIR` pointing at `web/`.
## How a release is built
Native modules (`better-sqlite3`, `onnxruntime-node`) must match the bundled Node.js, so each
target is built on its own system (ADR-0008). The desktop build scripts in `app/package.json`
run one staging chain into `app/src-tauri/resources/`:
1. `scripts/bundle-node.mjs` downloads and verifies the pinned Node.js (22.23.2);
2. `scripts/build-sidecar.mjs` bundles the sidecar into `service.js`;
3. `scripts/bundle-native-deps.mjs` copies the native modules for the target;
4. `scripts/stage-sidecar-deps.mjs` stages the packages the bundle keeps external;
5. `apps/web` is built with Vite into `apps/web/dist`;
6. `tauri build` produces the installers: `.exe` (NSIS) and `.msi` on Windows, `.app` and
`.dmg` on macOS, `.deb` and `.AppImage` on Linux.
Then `npm run build:server-archive` (`scripts/build-server-archive.mjs`) packs the same staged
payload and `apps/web/dist` into the server archive for that target, with a `.sha256` next to it.
```bash
npm ci
(cd app && npm ci)
(cd app && npm run tauri:build:mac:arm64) # or tauri:build:mac:x64, tauri:build:win, tauri:build
npm run build:server-archive # set TARGET_ARCH=x64 after an x64 macOS build
```
### Memory Flow
The Windows build must run on Windows; see [docs/oss/build-windows.md](oss/build-windows.md).
The first community release is unsigned ([docs/oss/signing.md](oss/signing.md)). The release
workflow for the community edition is not set up yet, so releases are built by hand on each
system.
```
Conversation
--> Agent detects important information
--> save_memory tool called
--> FrameStore.add() writes to workspace .mind
--> Embeddings generated (sqlite-vec)
--> Knowledge graph updated (entity extraction)
Shipped dependencies are checked for licenses that allow MIT distribution
(`npm run check:licenses`, and `cargo deny` for the Rust crates), and their notices are in
[`THIRD_PARTY_NOTICES.md`](../THIRD_PARTY_NOTICES.md).
Later search:
--> search_memory tool called
--> MultiMind.search() queries personal + workspace minds
--> FTS5 + vector similarity results merged
--> Top results injected into agent context
```
## Extension points
### Workspace Startup Flow
- **Skills**: Markdown files with YAML frontmatter in `<data>/skills/`, added to the system
prompt when active. See [guides/capabilities.md](guides/capabilities.md).
- **Plugins and MCP servers**: installed from the marketplace or a local directory.
- **Connectors**: classes in `packages/agent/src/connectors/`, registered in
`packages/server/src/local/setup-connectors.ts`. A connected service adds tools to the agent.
- **Slash commands**: `CommandDefinition`s in `packages/agent/src/commands/`, registered with the
`CommandRegistry`.
- **Memory backends**: an implementation of `MemoryStore` that passes the compatibility suite in
`@waggle/memory-contract`.
```
Open workspace
--> GET /api/workspaces/:id/context
--> Load workspace mind (MindDB)
--> Read recent memory frames
--> Extract decisions from memories
--> Read session files (titles, summaries)
--> Extract progress items (tasks, completions, blockers)
--> Build workspace state summary
--> Generate contextual suggested prompts
--> UI renders Home screen
```
## Security
## Extension Points
### Adding a New Tool
1. Define the tool in the appropriate category under `packages/agent/src/`
2. Follow the `ToolDefinition` interface: name, description, parameters (JSON Schema), handler function
3. Register the tool in the agent's tool list
4. If the tool is sensitive, add it to the approval gate check list
### Adding a New Connector
1. Implement the `ConnectorCapability` interface in `packages/server/src/services/connectors/`
2. Define `id`, `name`, `service`, `authType`, `connect()`, `healthCheck()`, and `generateTools()`
3. Register in `packages/server/src/local/index.ts` with `connectorRegistry.register()`
4. The connector's tools are automatically available when credentials are in the vault
### Adding a Skill
Create a markdown file in `~/.waggle/skills/`. The skill content is appended to the agent's system prompt. Use YAML frontmatter for metadata:
```markdown
---
name: my-skill
permissions:
- read_file
- web_search
---
# My Skill
Instructions for the agent...
```
### Adding a Slash Command
1. Create a `CommandDefinition` in `packages/agent/src/commands/`
2. Implement `name`, `aliases`, `description`, `usage`, and `handler`
3. Register with `registry.register()` in the appropriate registration function
### Adding a Workflow Template
1. Define a factory function that returns a `WorkflowTemplate` with steps
2. Register in the `WORKFLOW_TEMPLATES` map in `packages/agent/src/`
3. Each step defines a role, instructions, and optional tool restrictions
## Storage Locations
| Data | Location | Format |
|------|----------|--------|
| Personal memory | `~/.waggle/default.mind` | SQLite |
| Workspace memory | `~/.waggle/workspaces/{id}/workspace.mind` | SQLite |
| Sessions | `~/.waggle/workspaces/{id}/sessions/*.jsonl` | JSON Lines |
| Tasks | `~/.waggle/workspaces/{id}/tasks.jsonl` | JSON Lines |
| File registry | `~/.waggle/workspaces/{id}/files.jsonl` | JSON Lines |
| Config | `~/.waggle/config.json` | JSON |
| Vault | `~/.waggle/vault.db` | SQLite (encrypted values) |
| Marketplace | `~/.waggle/marketplace.db` | SQLite |
| Skills | `~/.waggle/skills/*.md` | Markdown |
| Plugins | `~/.waggle/plugins/` | Package directories |
| Permissions | `~/.waggle/permissions.json` | JSON |
## Security Model
- **Vault**: AES-256-GCM encryption for all secrets. Keys never stored in plain text after vault migration.
- **Approval Gates**: Sensitive tool executions require explicit user approval.
- **SecurityGate**: Marketplace installs scanned for dangerous patterns. CRITICAL severity always blocked.
- **Content Hashing**: SHA-256 hashes detect unauthorized skill modifications.
- **Audit Trail**: Every capability install, uninstall, and security decision is recorded.
- **Input Validation**: All route parameters validated against path traversal and injection.
- **YOLO Mode**: Opt-in auto-approval, disabled by default.
The threat model, the controls and the known gaps are in [`THREAT_MODEL.md`](../THREAT_MODEL.md).
In short: the user is trusted, external content is not. Connector input, tool output and recalled
memory pass the injection scanner; secrets live in the vault; sensitive tools wait for approval;
the sidecar answers only local requests that carry the session token.

View File

@@ -1,172 +1,3 @@
# Contributing to Waggle
# Contributing
## Prerequisites
- **Node.js 20+** (required)
- **Rust toolchain** (only for the desktop app -- `app/` package)
- **Docker** (only for team mode tests -- PostgreSQL and Redis)
## Setup
```bash
git clone <repository-url> waggle-os # the public repository location is not decided yet
cd waggle-os
npm install
```
## Running the App
```bash
# Local server / sidecar (http://localhost:3333)
cd packages/server && npx tsx src/local/start.ts
# — or, from the repo root: npm run dev:server
# Web app (http://localhost:8080)
npm run dev # — or: npm run dev:web
# Desktop app (requires Rust)
cd app && npm run tauri dev
# CLI REPL
cd packages/cli && npx tsx src/index.ts
```
## Running Tests
Tests are the product's safety net. All PRs must pass the full test suite.
```bash
# Run all tests (3000+ across 190+ files)
npx vitest run
# Watch mode during development
npx vitest
# Run tests for a specific package
npx vitest run packages/core
# Run a specific test file
npx vitest run packages/agent/src/__tests__/tools.test.ts
# Coverage report
npx vitest run --coverage
```
### Test Requirements
- All existing tests must pass before submitting a PR
- New features require accompanying tests
- Bug fixes require a regression test
- Team mode tests require Docker services running (`docker compose up -d`)
### Test Organization
Tests live alongside source files in `__tests__/` directories or as `.test.ts` siblings. The monorepo uses a single Vitest config at the root.
## Pull Request Process
1. **Fork** the repository and create a feature branch from `main`
2. **Read the CLAUDE.md** for execution rules and product truths
3. **Make your changes** following the slice-based approach (one focused change per PR)
4. **Write tests** for new functionality
5. **Run the full test suite**: `npx vitest run`
6. **Verify the build**: `npx tsc --noEmit`
7. **Submit a pull request** against `main`
8. **Describe your changes**: what was added, what was preserved, what was tested
### PR Title Format
Use descriptive titles that indicate the type of change:
- `feat: add Notion connector` -- new feature
- `fix: memory search scope filtering` -- bug fix
- `refactor: extract FrameStore from MindDB` -- code restructuring
- `test: add coverage for approval gates` -- test additions
- `docs: update API reference` -- documentation
## Code Style
### TypeScript
- ESM modules (`"type": "module"` in package.json)
- Explicit imports (no barrel re-exports)
- Strict TypeScript (`strict: true`)
- Use `type` imports where possible: `import type { Foo } from './foo.js'`
- Include `.js` extensions in imports (ESM requirement)
### File Organization
- One concept per file where practical
- Co-locate tests: `foo.ts` and `__tests__/foo.test.ts`
- Route files export a Fastify plugin async function
- Types go in the `@waggle/shared` package if used across packages
### Naming Conventions
- Files: `kebab-case.ts`
- Types/Interfaces: `PascalCase`
- Functions/variables: `camelCase`
- Constants: `UPPER_SNAKE_CASE`
- Route handlers: descriptive comments with HTTP method and path
### Error Handling
- Route handlers catch errors and return appropriate HTTP status codes
- Non-critical operations use try/catch with empty catch (logging is acceptable)
- Critical operations throw with descriptive error messages
- Avoid swallowing errors silently in core logic
## Package Structure
### Adding to an Existing Package
1. Add your source file in the appropriate directory
2. Export from the package's `index.ts` if it's a public API
3. Add tests in the `__tests__/` directory
4. Run `npx vitest run packages/<name>` to verify
### Key Directories
```
packages/<name>/
src/
index.ts # Public exports
__tests__/ # Test files
package.json # Package metadata
tsconfig.json # TypeScript config
```
## Product Rules
Read `CLAUDE.md` in the repo root for the full execution protocol. Key rules:
- **Waggle is workspace-native** -- do not collapse into a global chat
- **Memory is a product primitive** -- do not treat it as decorative
- **Tool transparency matters** -- users see what the agent does
- **Approval gates are required** for sensitive operations
- **No scope reduction without approval** -- do not simplify features "for now"
- **Tests are part of the product** -- not an afterthought
## Troubleshooting
### Windows: sidecar fails to start with an esbuild platform error
The Fastify sidecar runs through `tsx`, which uses esbuild. On a clean Windows
machine the platform-specific esbuild binary is sometimes not resolved, and
`npm run dev:server` (or `npx tsx src/local/start.ts`) fails with an error like
`Cannot find module @esbuild/win32-x64` or an esbuild version/host mismatch.
Fix it by installing the matching Windows esbuild binary without adding it to
`package.json`:
```bash
npm i @esbuild/win32-x64@0.28.0 --no-save
```
This affects **Windows only** — macOS and Linux resolve their esbuild binaries
normally. The version should match the esbuild your install resolved; `0.28.0`
is the known-good pin for the sidecar.
## Questions?
Open an issue for architecture questions, feature proposals, or bug reports.
Moved to [CONTRIBUTING.md](../CONTRIBUTING.md) in the repository root.

View File

@@ -1,97 +0,0 @@
# Getting Started with Waggle
Welcome to Waggle — your AI operating system with persistent memory.
## Quick Start
### 1. Install Waggle for Windows
Use only the signed Windows Solo `.exe` installer and SHA-256 identified by a **GO** [launch recommendation](production-readiness/09-LAUNCH_RECOMMENDATION.md). If that recommendation is not GO, no packaged desktop artifact is release-approved; use the source-development instructions in the repository instead. macOS desktop packaging and certification remain roadmap work.
Run the installer and launch Waggle. The Windows Solo release contract does not require developer Node.js, Docker, Python, LiteLLM, administrator access, or a separate Ollama installation.
### 2. Connect a model
The first-launch wizard offers two supported paths:
- **Private local model:** open **Local model**, choose **Install private runtime**, then download and verify the recommended model. Waggle keeps the managed runtime and model in its private data directory; no system Ollama or Docker installation is required.
- **Cloud provider:** open **API key**, choose a provider, and paste your own provider API key. Waggle validates it live when the provider is reachable, labels any unverified result, and stores it encrypted in Vault.
At least one working local model or cloud provider is needed for chat. You can choose **I'll do this later**, but chat remains unavailable until a model is configured.
External coding-agent authentication is separate from Waggle's model setup. Install each supported client yourself and use its own sign-in flow: Claude Code (`claude auth login --claudeai`), Codex (`codex login`), and Hermes' built-in provider OAuth (`hermes auth add openai-codex --type oauth`). Waggle uses the client's existing user session; do not paste or copy those credentials into Waggle.
### 3. Create Your First Workspace
- Choose a template (Sales, Research, Legal, etc.) or start blank
- Pick a persona (Researcher, Writer, Analyst, etc.)
- Name your workspace
### 4. Start Working
Type anything in the chat. Your agent can:
- Search the web (works immediately, no setup)
- Create Word documents with professional formatting
- Read and write files in your workspace
- Run shell commands (sandboxed)
- Run 15 workflow commands (type `/` to see them)
- Remember everything across sessions
### 5. The Memory Magic
After your first conversation, try closing and reopening the workspace.
Type: "What do you remember about our discussion?"
Your agent remembers everything — decisions, context, preferences.
## Key Features
### Workflow Commands
Type `/` in chat to see all commands:
- `/research [topic]` — deep web research with synthesis
- `/draft [type]` — create documents with professional formatting
- `/plan [goal]` — structured planning with steps
- `/catchup` — get a summary of where things stand
- `/decide [question]` — structured decision analysis
- `/review [topic]` — review work or documents
- `/spawn [task]` — delegate work to a sub-agent
- `/skills` — browse and install new capabilities
- `/status` — workspace health and statistics
- `/memory` — explore what your agent remembers
- `/focus` — set the current work focus
- `/now` — quick workspace snapshot
- `/help` — see all available commands
### Personas
Press `Ctrl+Shift+P` to switch personas. Each changes how your agent thinks:
- **Researcher**: deep investigation with citations
- **Writer**: document creation with formatting
- **Analyst**: data analysis with structured output
- **Planner**: project planning and task breakdown
- ...and more
### Keyboard Shortcuts
- `Ctrl+K` — search everything
- `Ctrl+Shift+1` through `Ctrl+Shift+7` — switch views
- `Ctrl+Shift+P` — switch persona
- `/` — workflow commands
### Memory View
Press `Ctrl+Shift+5` to browse everything your agent remembers.
Search, filter by type, and explore the knowledge graph.
### Workspace Home
When you open a workspace, you see the "Workspace Now" overview:
- A summary of where things stand
- Recent decisions and open items
- Recent conversation threads
- Key memories
Once you start chatting, click the **Workspace Overview** toggle above the messages to return to this view at any time.
## Product Scopes
Waggle uses four product tiers:
- **Trial** — 15 days of the Team experience, then Solo
- **Solo (Free)** — personal productivity with persistent memory
- **Team** — shared workspaces, WaggleDance, and governance
- **Enterprise** — sovereign KVARK deployment, compliance, and audit trails
## Need Help?
Type `/help` in chat for a full command reference.

View File

@@ -1,211 +1,100 @@
# Capabilities
# Skills, plugins and the marketplace
Capabilities are the extensions that make Waggle powerful: skills, plugins, MCP servers, workflow templates, hooks, and commands. This guide covers how to discover, install, and manage them.
Capabilities extend what the agent knows and can do. This guide covers the kinds of capability,
how to install them and how Waggle checks them.
## Capability Types
Most of the screens below appear at the **Everything** interface level (Settings → General).
| Type | What It Is | Storage |
|------|-----------|---------|
| **Skill** | Markdown file that extends the agent's system prompt with domain knowledge and instructions | `~/.waggle/skills/*.md` |
| **Plugin** | Structured package with a manifest that adds tools and behaviors | `~/.waggle/plugins/` |
| **MCP Server** | Model Context Protocol server that provides external tools | Configured in settings |
| **Workflow Template** | Multi-step agent orchestration (e.g., research-team, review-pair, plan-execute) | Built into `@waggle/agent` |
| **Hook** | Event-driven callback (before/after tool calls, session start/end, etc.) | Registered in agent state |
| **Command** | Slash command (`/research`, `/draft`, etc.) | Built into `@waggle/agent` |
## Kinds of capability
## Built-in Capability Packs
| Kind | What it is | Where it lives |
|---|---|---|
| Skill | A Markdown file with instructions and domain knowledge, added to the agent's prompt when active | `<data>/skills/*.md` |
| Plugin | A package with a manifest that adds tools and skills | `<data>/plugins/` |
| MCP server | A Model Context Protocol server that gives the agent external tools | Settings, MCP Hub |
| Workflow | A multi-agent recipe, such as `research-team`, `review-pair` or `plan-execute` | Built in, or created with `/workflow` |
| Command | A slash command such as `/research` or `/draft` | Built in ([reference](../reference/commands.md)) |
Waggle ships with 5 curated packs. Each pack bundles several skills that work together.
## Starter skills and capability packs
### Research Workflow
Waggle ships with starter skills in seven families: Writing & Docs, Research & Analysis,
Decision Support, Planning & Organization, Communication, Code & Engineering, and Creative &
Ideation. Install them one by one in **Skills Hub**, or as packs:
Skills for investigation and synthesis. Includes `research-synthesis`, `explain-concept`, and the `research-team` multi-agent workflow.
| Pack | Skills |
|---|---|
| Research Workflow | `research-synthesis`, `explain-concept`, `research-team` |
| Writing Suite | `draft-memo`, `compare-docs`, `extract-actions` |
| Planning Master | `daily-plan`, `task-breakdown`, `plan-execute`, `decision-matrix` |
| Team Collaboration | `catch-up`, `status-update`, `meeting-prep`, `review-pair` |
| Decision Framework | `decision-matrix`, `risk-assessment`, `retrospective` |
### Writing Suite
Installing a pack skips skills that are already installed. The "Team Collaboration" pack is a
set of skills for working with other people; it does not need team mode.
Skills for document creation and editing. Includes `draft-memo`, `compare-docs`, and `extract-actions`.
## Writing your own skill
### Planning Master
Skills for task decomposition and execution. Includes `daily-plan`, `task-breakdown`, and the `plan-execute` workflow.
### Team Collaboration
Skills for coordination and communication. Includes `catch-up`, `status-update`, and `meeting-prep`.
### Decision Framework
Skills for structured decision-making. Includes `decision-matrix`, `risk-assessment`, and `retrospective`.
## Installing Packs
### From the UI
1. Navigate to **Capabilities** in the sidebar (or click the grid icon)
2. Click **Browse Packs**
3. Each pack shows its skills, install state (available / incomplete / complete), and description
4. Click **Install** to install all skills in the pack at once
5. Already-installed skills are skipped
### From the API
```bash
# Install the Research Workflow pack
curl -X POST http://localhost:3333/api/skills/capability-packs/research-workflow
# Install a single skill from the starter pack
curl -X POST http://localhost:3333/api/skills/starter-pack/draft-memo
```
## Installing Individual Skills
### From the Starter Catalog
1. Go to **Capabilities** > **Skills**
2. Browse by family: Writing & Docs, Research & Analysis, Decision Support, Planning & Organization, Communication, Code & Engineering, Creative & Ideation
3. Click **Install** on any skill
4. The skill is copied to `~/.waggle/skills/` and loaded immediately
### Creating Custom Skills
Skills are markdown files. Create a file in `~/.waggle/skills/`:
A skill is a Markdown file in `<data>/skills/` (by default `~/.waggle/skills/`). Optional YAML
frontmatter gives it a name and other metadata:
```markdown
# My Custom Skill
---
name: weekly-report
description: Write the weekly status report in our format
---
# Weekly report
Instructions for the agent when this skill is active.
## When to Use
- Trigger conditions
## How to Respond
- Response format guidelines
- Quality standards
When asked for the weekly report:
- Start with the three most important changes.
- List risks with an owner each.
- Keep it under one page.
```
Or use the API:
```bash
curl -X POST http://localhost:3333/api/skills \
-H "Content-Type: application/json" \
-d '{"name": "my-skill", "content": "# My Skill\n\nInstructions here."}'
```
You can also create and edit skills in **Skills Hub**. `/skills` lists the active skills in a
chat.
## Marketplace
The marketplace catalog contains 120+ packages across skills, plugins, and MCP servers from curated sources.
**Marketplace** lists skills, plugins and MCP servers from curated sources. Search it, read a
package's details and install it. `/marketplace search <query>` and
`/marketplace install <name>` do the same from a chat; `/marketplace sync` refreshes the catalog
from its sources.
### Searching
### Security scan
```bash
# Search by keyword
curl "http://localhost:3333/api/marketplace/search?query=research&limit=10"
Every marketplace install is scanned first for dangerous patterns, such as reading credentials,
unexpected network calls or destructive file operations. The result decides what happens:
# Filter by type
curl "http://localhost:3333/api/marketplace/search?type=skill&category=analysis"
```
| Severity | Result |
|---|---|
| Clean, low | The install proceeds |
| Medium | The install proceeds with warnings |
| High | Blocked unless you confirm that you accept the risk |
| Critical | Always blocked |
Or use the `/marketplace search <query>` slash command in any workspace.
Installs, uninstalls and security decisions are recorded in the install audit trail in
`waggle.db`.
### Installing from Marketplace
```bash
# Install by package ID
curl -X POST http://localhost:3333/api/marketplace/install \
-H "Content-Type: application/json" \
-d '{"packageId": 42}'
```
Or use `/marketplace install <name>`.
### Security Scanning
Every marketplace install goes through the **SecurityGate** scanner. Results determine whether the install proceeds:
| Severity | Action |
|----------|--------|
| CLEAN | Install proceeds immediately |
| LOW | Install proceeds, logged to audit trail |
| MEDIUM | Install proceeds with warnings in response |
| HIGH | Blocked unless `force=true` (override logged to audit) |
| CRITICAL | Always blocked, cannot override |
### Syncing the Catalog
```bash
# Sync from all configured sources
curl -X POST http://localhost:3333/api/marketplace/sync
```
Or use `/marketplace sync`.
## Trust Model
Waggle uses a multi-layer trust model:
1. **Source trust** -- starter-pack skills are trusted by default; marketplace and user-created skills get assessed
2. **Content analysis** -- heuristic scan for dangerous patterns (credential access, network calls, file system mutations)
3. **Risk level** -- low, medium, high, critical based on what the capability does
4. **Approval class** -- standard (auto-approve), review (log), force-override (user acknowledged risk), blocked
5. **Content hash** -- SHA-256 hash of each skill file, checked at startup to detect unauthorized modifications
### Audit Trail
Every install, uninstall, and security decision is recorded in the audit store. View it:
- **UI**: Capabilities > Cockpit > Trust Audit section
- **API**: `GET /api/audit/installs`
### Hash Verification
At startup, Waggle checks each installed skill's content hash against the stored hash. If a skill file was modified outside of Waggle, it is flagged in the hash status:
```bash
curl http://localhost:3333/api/skills/hash-status
```
If a skill or plugin you installed from the marketplace does not show up in the agent, restart
Waggle. The marketplace installer's reload request does not reach the running server yet.
## Plugins
Plugins are structured packages with manifests that can add tools and extend agent behavior.
A plugin is a directory with a manifest. Install one from the marketplace or from a local
directory, then enable or disable it. A disabled plugin stays installed but adds nothing to the
agent.
### Installing a Plugin
## MCP servers
```bash
curl -X POST http://localhost:3333/api/plugins/install \
-H "Content-Type: application/json" \
-d '{"sourceDir": "/path/to/my-plugin"}'
```
**MCP Hub** shows the installed Model Context Protocol servers with their state, lets you start,
stop, test and remove them, and installs new ones from its catalog or from a server you
describe yourself. Catalog installs go through the same security scan as the marketplace.
### Enabling / Disabling
## Trust checks
```bash
# Enable
curl -X POST http://localhost:3333/api/capabilities/plugins/my-plugin/enable
# Disable
curl -X POST http://localhost:3333/api/capabilities/plugins/my-plugin/disable
```
### Uninstalling
```bash
curl -X DELETE http://localhost:3333/api/plugins/my-plugin
```
## Viewing Capability Status
The **Cockpit** (accessible from the sidebar) shows a live dashboard of all capabilities:
- **Plugins**: name, state, tool count, skill count
- **MCP Servers**: name, state, healthy status, tool count
- **Skills**: name, content length
- **Tools**: total count (native + plugin + MCP)
- **Commands**: all registered slash commands
- **Hooks**: registered count, recent activity log
- **Workflows**: available templates with step counts
API equivalent:
```bash
curl http://localhost:3333/api/capabilities/status
```
- **Source**: starter skills are trusted; marketplace and your own skills are assessed.
- **Content scan**: the heuristic scan described above.
- **Approval**: capabilities that ask for risky actions go through the same approval rules as
any other tool call (Settings → Permissions).
- **Content hash**: Waggle records a SHA-256 hash of each installed skill and checks it at
startup, so a skill changed outside Waggle is flagged.

View File

@@ -1,195 +1,98 @@
# Connectors
# Connectors and channels
Connectors let Waggle interact with external services -- GitHub, Slack, Google, Jira, and 25 others. Credentials are stored in the encrypted vault, and sensitive operations go through approval gates.
**Connectors** let the agent work with services you use, such as GitHub, Slack or Google Drive.
**Channels** let you talk to Waggle from a messaging app. Credentials for both are kept in the
encrypted Vault on your computer, and actions that change something go through approvals.
## Vault Setup
## The Vault
Before connecting any service, you need to understand the vault. The vault is Waggle's encrypted credential store, using AES-256-GCM encryption. It lives at `~/.waggle/vault.db` and is the single source of truth for all secrets.
The Vault stores provider keys, connector credentials and other secrets in
`<data>/vault.json`. Each entry is encrypted with AES-256-GCM using a key kept in
`<data>/.vault-key`. Open **Vault** to see the stored secrets (names only), add one, reveal a
value or delete it.
### Adding a Secret to the Vault
Provider keys added in Settings → Models land in the Vault too.
**From the UI:**
1. Go to **Settings** > **Vault**
2. Click **Add Secret**
3. Enter the name (e.g., `GITHUB_TOKEN`) and value
4. Click **Save**
## Native connectors
**From the API:**
```bash
curl -X POST http://localhost:3333/api/vault \
-H "Content-Type: application/json" \
-d '{"name": "GITHUB_TOKEN", "value": "ghp_your_token_here"}'
```
Waggle has 30 built-in connectors:
### Suggested Keys
| Area | Connectors |
|---|---|
| Code | GitHub, GitLab, Bitbucket |
| Chat | Slack, Discord, Microsoft Teams |
| Email and calendar | Gmail, Google Calendar, Outlook (calendar and email), Email via SendGrid |
| Documents and files | Google Docs, Google Drive, Google Sheets, OneDrive, Microsoft OneNote, Dropbox, Notion, Confluence, Obsidian |
| Projects | Jira, Linear, Asana, Trello, Monday.com, Airtable |
| CRM | HubSpot, Salesforce, Pipedrive |
| Data | PostgreSQL |
| Other services | Composio, a bridge to many more services |
The vault suggests common API key names that are not yet configured:
### Connect a service
- `ANTHROPIC_API_KEY` -- LLM provider
- `OPENAI_API_KEY` -- LLM provider
- `GITHUB_TOKEN` -- GitHub API
- `SLACK_BOT_TOKEN` -- Slack Bot
- `JIRA_API_TOKEN` -- Jira Cloud
- `GOOGLE_API_KEY` -- Google services
- `TAVILY_API_KEY` -- Web search
- `BRAVE_API_KEY` -- Web search
- `SENDGRID_API_KEY` -- Email sending
- `GOOGLE_CALENDAR_TOKEN` -- Calendar access
1. Open **Connector Hub** (at the Everything interface level).
2. Choose the service and **Connect**.
3. Enter what the form asks for: a token, an API key, an email and token, a file path for
Obsidian, or a connection string for PostgreSQL. The form links to where the service issues
it.
## Native Connectors
When a service is connected, the agent gets tools for it, for example creating issues and
pull requests on GitHub or searching pages in Confluence. `/connectors` lists the connected
services in a chat.
Waggle registers 29 native connectors at startup. Each connector has a defined auth type and generates agent tools when credentials are available.
**Disconnect** removes the credentials from the Vault. Connector Hub also shows each
connector's health and a history of what was done with it.
| # | Connector | Service | Auth Type |
|---|-----------|---------|-----------|
| 1 | GitHub | GitHub API | Bearer token (PAT) |
| 2 | Slack | Slack Bot API | Bot token |
| 3 | Jira | Jira Cloud | Basic auth (email + API token) |
| 4 | Email (SendGrid) | SendGrid API | API key |
| 5 | Google Calendar | Google Calendar API | OAuth token |
| 6 | Discord | Discord Bot API | Bot token |
| 7 | Linear | Linear API | API key |
| 8 | Asana | Asana API | Bearer token |
| 9 | Trello | Trello API | API key |
| 10 | Monday | Monday.com API | API key |
| 11 | Notion | Notion API | Integration token |
| 12 | Confluence | Atlassian API | Basic auth |
| 13 | Obsidian | Local vault | File path |
| 14 | HubSpot | HubSpot API | Bearer token |
| 15 | Salesforce | Salesforce API | OAuth token |
| 16 | Pipedrive | Pipedrive API | API key |
| 17 | Airtable | Airtable API | Bearer token |
| 18 | GitLab | GitLab API | Bearer token (PAT) |
| 19 | Bitbucket | Bitbucket API | App password |
| 20 | Dropbox | Dropbox API | OAuth token |
| 21 | PostgreSQL | PostgreSQL | Connection string |
| 22 | Gmail | Gmail API | OAuth token |
| 23 | Google Docs | Google Docs API | OAuth token |
| 24 | Google Drive | Google Drive API | OAuth token |
| 25 | Google Sheets | Google Sheets API | OAuth token |
| 26 | MS Teams | Microsoft Graph API | OAuth token |
| 27 | Outlook | Microsoft Graph API | OAuth token |
| 28 | OneDrive | Microsoft Graph API | OAuth token |
| 29 | Composio | Composio Bridge | API key |
Composio keeps the credentials for the services behind it on Composio's side, not in Waggle's
Vault.
## Connecting a Service
## Approvals
### From the UI
When the agent wants to do something with an effect outside the chat, such as sending an email,
posting a message, creating a ticket or pushing a commit, it pauses and shows an approval card
with the tool and its input. Nothing happens until you choose **Approve** or **Deny**.
1. Open the **Cockpit** from the sidebar
2. Scroll to the **Connectors** section
3. Click **Connect** on the service you want
4. Enter your credentials (token, API key, or OAuth details)
5. Click **Save**
**Settings** → **Permissions** sets how often Waggle asks:
The connector status changes from "Disconnected" to "Connected".
| Mode | Behavior |
|---|---|
| Ask every time | Approve every write, edit and other action that changes something |
| Ask only for risky | Writes and edits pass; pushes, installs and cross-workspace actions still ask |
| Never ask | Everything passes except a fixed list of critical actions |
### From the API
## Channels
```bash
# Connect GitHub with a personal access token
curl -X POST http://localhost:3333/api/connectors/github/connect \
-H "Content-Type: application/json" \
-d '{"token": "ghp_your_token_here"}'
**Settings** → **Channels** connects messaging apps, so you can message Waggle from them.
# Connect Jira with email + API token
curl -X POST http://localhost:3333/api/connectors/jira/connect \
-H "Content-Type: application/json" \
-d '{"apiKey": "your_jira_token", "email": "you@company.com"}'
```
| Channel | What you need |
|---|---|
| Telegram | A bot token from @BotFather |
| Discord | A bot token from the Discord developer portal |
| Slack | An app token (Socket Mode) and a bot token |
| WhatsApp | A phone to pair by QR code |
### Disconnecting
### WhatsApp
```bash
curl -X POST http://localhost:3333/api/connectors/github/disconnect
```
WhatsApp runs through `whatsapp-web.js`, an unofficial client that drives WhatsApp Web in a
browser. WhatsApp does not allow this and may block the account: link a secondary number, not
your personal one.
This removes the credentials from the vault and any associated metadata.
- Waggle uses Chrome, Edge or Chromium if one is installed (or the browser named in
`CHROME_PATH`). Otherwise it downloads Chrome for Testing (about 170 MB) into
`<data>/browsers` the first time you start WhatsApp. On Linux on ARM, install Chromium
yourself.
- Start the channel, then scan the pairing QR code with WhatsApp on your phone (Linked
devices).
- The session is kept as a browser profile in `<data>/channels/whatsapp/session`. It is
protected by file permissions, not by the Vault.
- Only text messages are handled. Voice, video and other media are ignored.
## Checking Connector Health
## Troubleshooting
Each connector can report its health status:
```bash
curl http://localhost:3333/api/connectors/github/health
```
Response:
```json
{
"id": "github",
"name": "GitHub",
"status": "connected",
"lastChecked": "2026-03-19T10:30:00.000Z",
"tokenExpiresAt": null
}
```
Possible statuses: `connected`, `disconnected`, `expired`, `error`.
## Connector Tools
When a connector is connected (credentials in vault), the agent gains tools for that service. For example, connecting GitHub gives the agent:
- Create issues
- List repositories
- Read file contents
- Create pull requests
The exact tools depend on the connector implementation. Tools appear in the agent's tool list and are visible in the Cockpit capabilities dashboard.
## Approval Gates
Sensitive connector operations go through approval gates. When the agent wants to:
- Send an email
- Create a Jira ticket
- Post a Slack message
- Push a git commit
It pauses and shows an approval card in the chat. You see:
- **Tool name** (e.g., `send_email`)
- **Input** (e.g., recipient, subject, body)
- **Approve** or **Deny** buttons
The agent waits for your decision before proceeding. This prevents accidental or unwanted actions.
### YOLO Mode
If you trust the agent fully, you can enable **YOLO Mode** in Settings > Permissions. This auto-approves all tool executions without asking. You can also set per-workspace overrides for specific tools.
## Composio Bridge
The 29th connector, Composio, is a bridge to 250+ additional services. If you have a Composio account:
1. Add your Composio API key to the vault
2. Connect the Composio connector
3. The agent gains access to Composio-managed services
Composio manages its own credential lifecycle. Note: Composio credentials are stored and managed by Composio's infrastructure, not in Waggle's local vault.
## Enterprise Connectors (KVARK)
For enterprise deployments, KVARK provides an additional layer of governed connectors with:
- 28+ document connectors (SharePoint, Box, Google Drive, etc.)
- Permission-aware retrieval (respects source system ACLs)
- Semantic search with reranking
- Full audit trail
Enterprise connectors require a KVARK connection. See the [API Reference](../reference/api.md) for the `/api/marketplace/enterprise-packs` endpoint.
## Troubleshooting Connectors
### "Connector not found"
The connector ID must match exactly (lowercase). Check `GET /api/connectors` for the full list.
### "Vault not available"
The vault database could not be initialized. Check that `~/.waggle/` is writable and the vault.db file is not corrupted.
### Token Expired
Some OAuth-based connectors (Google, Microsoft) have tokens that expire. Re-connect the service to refresh.
### No Tools Appearing
After connecting, the agent tools are regenerated on the next chat message. If tools still do not appear, restart the server.
- **A connector shows as disconnected after a restart.** Check its health in Connector Hub. If
the token expired (common with Google and Microsoft tokens), connect it again with a new one.
- **The agent has no tools for a connected service.** Tools are rebuilt on the next message. If
they still do not appear, restart Waggle.
- **"Vault not available".** Check that the data directory is writable. If `vault.json` cannot
be read, Waggle copies it to `vault.json.bak` and treats the Vault as empty; you then need to
enter the secrets again.

View File

@@ -1,211 +1,131 @@
# Getting Started with Waggle
# Getting started
This guide walks you through installing Waggle, configuring your API key, creating your first workspace, having your first conversation, and understanding how memory works.
This guide takes you from a fresh install to your first conversation, and explains how Waggle
remembers things between chats.
## Prerequisites
## 1. Install
- **Node.js 20+** (for local server and CLI)
- **An LLM API key** (Anthropic recommended; OpenAI, Google, and 100+ others supported)
- **Rust toolchain** (only if building the desktop app from source)
Install the desktop app or the server installer as described in [install.md](../install.md). Then
open Waggle: start the desktop app, or run `waggle-server`, which opens
http://localhost:3333 in your browser.
## Installation
## 2. Go through the setup
### Option 1: One-line self-host (Linux / macOS)
The first launch walks you through a short setup:
Best for a VPS or homelab, where you want a headless server rather than the desktop app:
1. **Who are you**: your name, role and the kind of work you do. Waggle keeps this in your profile
on this computer and uses it to tailor answers.
2. **Model**: add a model (next section). You can skip this, but chat stays unavailable until a
model is set up.
3. **Pick a starting point**: a template for your first workspace, such as Research Hub, Sales
Pipeline, Engineering or Legal & Compliance, or **Blank Workspace**. Each template comes with a
matching persona.
4. **What's first?**: type a first task for the agent, or pick a suggestion.
```bash
curl -fsSL <repository-raw-url>/main/install.sh | bash # the public repository location is not decided yet
```
## 3. Connect a model
The installer checks prerequisites (Node.js 20+, git — no sudo), clones the repo, builds the packages and web UI, then starts the sidecar and prints its URL (`http://127.0.0.1:3333`). A short wizard (all Enter-defaulted) lets you change the install dir, port, and data dir; add `--yes` to accept every default non-interactively. It boots in echo mode with zero API keys, so the UI works right away — add a provider key later under **Settings → API Keys**.
Waggle needs at least one working model. Choose one of two ways, in the setup or later in
**Settings** → **Models**:
Manage the server afterward with `scripts/waggle-server.sh {start|stop|status|logs}`. Windows users should use the desktop app (Option 2) — the one-line installer targets Linux and macOS only.
- **API key**: choose a provider (Anthropic, OpenAI, Google, DeepSeek, xAI, Mistral, Alibaba
Qwen, MiniMax, Zhipu GLM, Moonshot Kimi, Perplexity or OpenRouter) and paste your key. Waggle
checks it with the provider when it can reach it, and stores it encrypted in the **Vault** on
this computer.
- **Local model**: choose **Install private runtime**. Waggle downloads the official Ollama
runtime, checks it and runs it from its own data directory. Then download a model; Waggle
suggests one that fits your computer. No separate Ollama install, Docker or administrator
rights are needed. If you already run Ollama, Waggle finds it.
### Option 2: Desktop App (Recommended)
In **Settings** → **Models** you also choose the default model, a fallback model and an optional
daily budget.
Download the latest release for your platform from the repository's Releases page (the public repository location is not decided yet).
## 4. Your first conversation
**Windows**: Run the `.msi` installer. Waggle appears in your Start menu.
Type in the chat. The agent streams its answer, and you see what it does along the way:
**macOS**: Open the `.dmg` and drag Waggle to Applications.
- **Tool steps**, such as reading a file, searching the web or saving a memory.
- **Approval requests** for actions that change something outside the chat, such as writing a
file or sending a message. The agent waits until you approve or deny. Settings →
**Permissions** sets how often Waggle asks.
- **Memory**: when you tell the agent something worth keeping, it saves it.
The desktop app bundles a Node.js sidecar that runs the local server automatically.
Good first messages:
### Option 3: CLI / Web
If you prefer a browser-based interface or want to run Waggle without the desktop shell:
```bash
# Clone the repository
git clone <repository-url> waggle
cd waggle
npm install
# Start the local server
cd packages/server
npx tsx src/local/start.ts
```
The server starts on http://localhost:3333. Open it in any browser.
### Option 4: CLI REPL
For a terminal-native experience:
```bash
cd packages/cli
npx tsx src/index.ts
```
## Step 1: Add Your API Key
Waggle needs at least one LLM provider key to function. Anthropic (Claude) is recommended.
### Desktop / Web UI
1. Open **Settings** (gear icon in the sidebar or press `Ctrl+,`)
2. Go to the **Models** tab
3. Click **Add Provider**
4. Select **Anthropic** and paste your API key (starts with `sk-ant-`)
5. Click **Save**
Your key is stored in the local vault (AES-256-GCM encrypted), never sent to Waggle's servers.
### CLI / Config File
Edit `~/.waggle/config.json`:
```json
{
"defaultModel": "claude-sonnet-4-6",
"providers": {
"anthropic": {
"apiKey": "sk-ant-your-key-here",
"models": ["claude-sonnet-4-6", "claude-haiku-3"]
}
}
}
```
### Verify Your Key
In Settings > Models, click **Test Key**. A green checkmark means you are ready.
## Step 2: Create Your First Workspace
Workspaces are the core organizational unit in Waggle. Each workspace has its own memory, sessions, files, and context. Think of a workspace as a dedicated brain for a project or topic.
1. Press **Ctrl+N** or click **New Workspace** in the sidebar
2. Enter a name (e.g., "Product Research" or "Q1 Planning")
3. Choose a group (e.g., "Work", "Personal", "Learning")
4. Optionally select a persona (Researcher, Writer, Coder, etc.)
5. Optionally link a directory on disk for file-aware operations
6. Click **Create**
You land on the **Workspace Home** screen. It shows a summary, suggested prompts, and recent threads.
## Step 3: Your First Conversation
Type a message in the input area. Here are good first messages:
- "Tell me about this project so I can remember it"
- "Help me think through what to work on first"
- "Here is what this project is about: …"
- "Help me plan what to work on first."
- "What can you do in this workspace?"
The agent responds with streaming output. You will see:
### Slash commands
- **Tool calls** shown as collapsible cards (file reads, web searches, memory saves)
- **Memory saves** happening automatically when the agent learns something important
- **Approval gates** for sensitive operations (the agent asks before executing risky actions)
Type `/` in the chat to see the commands, for example `/catchup` for a summary of where the
workspace stands, `/research <topic>`, `/draft <type> [topic]` or `/plan <goal>`. `/help` lists
them all; the [commands reference](../reference/commands.md) describes each one.
### Try a Slash Command
### Files
Type `/catchup` to get a workspace restart summary. Type `/help` to see all 14 commands.
Attach a file to the chat to let the agent read it: PDF, Word (`.docx`), PowerPoint (`.pptx`),
Excel (`.xlsx`), CSV, images, ZIP archives and text or code files, up to 10 MB each.
### Upload a File
## 5. How memory works
Click the paperclip icon or drag a file into the chat. Waggle supports:
Waggle keeps two kinds of memory, both on your computer:
- **Documents**: PDF, DOCX, PPTX
- **Spreadsheets**: XLSX, CSV
- **Images**: PNG, JPG, GIF, WebP, SVG
- **Code**: Any text-based source file
- **Archives**: ZIP (lists contents)
- **Personal memory** follows you across all workspaces: who you are, your preferences, facts
that are not tied to one project.
- **Workspace memory** belongs to one workspace: decisions, findings and project context.
Files are ingested into workspace memory and available to the agent.
Before it answers, the agent recalls what is relevant from personal memory and the current
workspace. Memories get there in three ways:
## Step 4: Understanding Memory
- **You ask**: "Remember that we chose PostgreSQL for the new service."
- **The agent decides** something is worth keeping and saves it.
- **Background extraction**: every few messages, Waggle picks out facts about you, such as your
role or how you like answers, and saves them to personal memory. Turn this off in **Settings**
→ **General** → **Memory**.
Memory is a core product primitive, not a side feature. Two memory layers work together:
Open **Memory** to browse, search, correct, confirm or forget memories. `/memory <query>` searches
from the chat. More detail: [memory.md](../memory.md).
### Personal Mind (`~/.waggle/default.mind`)
## 6. Come back later
Your personal knowledge base. Facts about you, your preferences, recurring context. Shared across all workspaces.
When you return to a workspace:
### Workspace Mind (`~/.waggle/workspaces/{id}/workspace.mind`)
- **Home** shows recent activity and suggests where to continue;
- `/catchup` gives a briefing on where the workspace stands;
- your earlier chats are listed in the workspace, ready to resume;
- the agent recalls the workspace's memory before its first answer.
Project-specific memory. Decisions, research findings, architectural choices, meeting notes. Scoped to one workspace.
## Personas
### How Memory Works
A persona tunes how the agent works: its instructions, preferred tools and suggested commands.
Waggle ships with personas such as Researcher, Writer, Analyst, Coder, Project Manager, Executive
Assistant, Marketer, Legal Counsel and General Purpose. Press `Ctrl+Shift+P` (`Cmd+Shift+P` on
macOS) to switch. See [workspaces.md](workspaces.md#personas).
1. **Auto-save**: The agent automatically saves important information during conversations -- decisions, facts, preferences, and findings.
2. **Explicit save**: You can say "Remember that we decided to use PostgreSQL" and the agent writes it to the appropriate mind.
3. **Memory search**: The agent searches memory before responding, giving you continuity across sessions.
4. **Memory browser**: Open the Memory tab in any workspace to browse, search, and manage stored frames.
## Interface levels
### Memory Frames
**Settings** → **General** offers three interface levels: **Essential**, **Standard** and
**Everything**. Essential shows the basics (Home, Chat, Memory, Files, Vault, Settings).
Everything adds agents, skills, connectors, the marketplace, automations and the system tools.
Each memory unit is a "frame" with:
- **Content**: The actual information
- **Importance**: critical, important, normal, temporary
- **Frame type**: Information (I), Decision (D), Preference (P), etc.
- **Timestamp**: When it was created
- **Access count**: How often it has been retrieved
## Keyboard shortcuts
## Step 5: Return Tomorrow
When you come back to a workspace, Waggle gives you an instant catch-up:
1. **Workspace Home** shows a summary of what happened, recent decisions, and suggested next prompts
2. **Type `/catchup`** for a detailed briefing
3. **Resume a thread** by clicking any recent session in the sidebar
4. **Context is automatic** -- the agent loads relevant memory before its first response
This is the core daily-use loop:
> Open workspace -> instant context -> real work help -> memory-first response -> visible progress -> return later without losing thread
## Next Steps
- **[Workspaces Guide](workspaces.md)** -- Workspace types, switching, home screen, personas
- **[Capabilities Guide](capabilities.md)** -- Install skill packs and browse the marketplace
- **[Connectors Guide](connectors.md)** -- Connect GitHub, Slack, Google, and 26 other services
- **[Commands Reference](../reference/commands.md)** -- All 14 slash commands with examples
- **[Team Mode Guide](team-mode.md)** -- Set up shared workspaces for your team
## File Locations
| Item | Path |
|------|------|
| Config | `~/.waggle/config.json` |
| Personal mind | `~/.waggle/default.mind` |
| Workspace minds | `~/.waggle/workspaces/{id}/workspace.mind` |
| Session logs | `~/.waggle/workspaces/{id}/sessions/*.jsonl` |
| Installed skills | `~/.waggle/skills/*.md` |
| Installed plugins | `~/.waggle/plugins/` |
| Marketplace DB | `~/.waggle/marketplace.db` |
| Vault (encrypted) | `~/.waggle/vault.db` |
| Server logs | Console output (stdout) |
## Keyboard Shortcuts
On macOS use `Cmd` instead of `Ctrl`.
| Shortcut | Action |
|----------|--------|
| `Ctrl+N` | New workspace |
| `Ctrl+,` | Settings |
| `Ctrl+K` | Quick switch workspace |
| `Ctrl+Shift+M` | Toggle memory browser |
| `Enter` | Send message |
| `Shift+Enter` | Newline in message |
| `/` | Start slash command |
|---|---|
| `Ctrl+K` | Search everything |
| `Ctrl+Shift+P` | Switch persona |
| `Ctrl+Tab` | Switch workspace |
| `Ctrl+Shift+N` | Open the chat of the active workspace |
| `Ctrl+/` or `?` | Show all shortcuts |
| `Enter` / `Shift+Enter` | Send / new line |
| `Ctrl+Shift+W` | Show or hide the desktop app window (desktop app only) |
## Next steps
- [Workspaces](workspaces.md): workspaces, sessions, personas and folders on disk
- [Skills, plugins and the marketplace](capabilities.md)
- [Connectors and channels](connectors.md)
- [Troubleshooting](troubleshooting.md)
- [Where your data lives](../install.md#where-your-data-lives)

View File

@@ -1,207 +1,141 @@
# Troubleshooting
Common issues, error codes, and solutions.
Common problems and what to do about them. Paths use `<data>` for the data directory:
`~/.waggle` by default (`%USERPROFILE%\.waggle` on Windows), or `WAGGLE_DATA_DIR`.
## API Key Issues
## Installing
### "No API key configured"
### Windows or macOS refuses to open the installer or the app
The agent cannot run without an LLM provider key.
The first release is not signed. See [install.md](../install.md): on Windows choose **More
info** → **Run anyway**; on macOS use **Open Anyway** in System Settings → Privacy & Security, or
`xattr -dr com.apple.quarantine /Applications/Waggle.app`.
**Fix:** Go to Settings > Models and add your Anthropic key (starts with `sk-ant-`). Or edit `~/.waggle/config.json` directly:
### The AppImage does not start on Linux
```json
{
"defaultModel": "claude-sonnet-4-6",
"providers": {
"anthropic": {
"apiKey": "sk-ant-your-key-here",
"models": ["claude-sonnet-4-6"]
}
}
}
```
Install FUSE 2 (`libfuse2` or `libfuse2t64` on Ubuntu, `fuse-libs` on Fedora), or use the `.deb`.
### "API key is too short" / "must start with sk-ant-"
### The server installer stops with an error
The key format validation failed.
| Message | What to do |
|---|---|
| "This build has no download location yet. Pass --from …" | The default download location is not set yet. Pass the archive: `--from <path or URL>` |
| "There is no Waggle server build for …" | Your system is not supported. Builds exist for Windows x64, macOS (Apple silicon and Intel) and Linux x64 |
| "The archive checksum does not match" | The download is damaged or not the published file. Download it again |
| "No checksum found at ….sha256" | The `.sha256` file is missing next to the archive URL. Pass `--sha256 <hex>` if you have the checksum from another source |
| "This archive is for …; this system needs …" | You downloaded the archive for another system |
| "Windows cannot update the program it is running" | Stop the server, then run `npx @waggle-ai/waggle update` (or `uninstall`) |
| "Waggle needs Node.js 20 or newer to install" | Update Node.js for the `npx` call; Waggle itself runs on its own Node.js |
**Fix:** Anthropic keys must start with `sk-ant-` and be at least 20 characters. OpenAI keys start with `sk-`. Copy the full key from your provider dashboard.
Run `waggle-server doctor` to check an existing installation.
### Key works in API but not in Waggle
## Starting
The built-in Anthropic proxy translates OpenAI-format requests to Anthropic format. If you are using a non-standard provider, you may need LiteLLM as a proxy:
### The desktop app stays on "Starting Waggle…"
Close the app and look at the server log: `<data>/logs/service.log` (the previous run is in
`service.log.1`). It usually names the problem, such as a data directory that is not writable.
On Windows, Waggle needs the WebView2 runtime, which ships with current Windows 10 and 11. If the
window stays white, install WebView2 from Microsoft.
### Port 3333 is in use
The desktop app picks another free port by itself. For the server installer:
```bash
docker compose up litellm
waggle-server --port 3334
```
Then set your LiteLLM URL in Settings > Advanced.
When running from source: `WAGGLE_PORT=3334 npm run dev:server`.
## Server Issues
To see what uses the port: `lsof -i :3333` on macOS and Linux, `netstat -ano | findstr 3333` on
Windows.
### Server won't start
### The page is blank or assets return 404 (running from source)
**Check port availability:**
```bash
# Is port 3333 already in use?
lsof -i :3333 # macOS/Linux
netstat -ano | findstr 3333 # Windows
```
The sidecar registers the files in `dist/` when it starts. After `npm run build`, restart it.
Use the UI the sidecar serves at http://localhost:3333; the Vite dev server (`npm run dev:web`)
cannot sign in to the sidecar yet.
**Fix:** Kill the existing process or change the port:
```bash
PORT=3334 npx tsx src/local/start.ts
```
## Models
### "SQLITE_CANTOPEN" error
### "No AI model is ready"
The `.mind` database file cannot be opened.
Chat needs at least one working model. Add a provider key in **Settings** → **Models** (API key
tab), or install the private runtime and a local model there (Local model tab).
**Fix:**
- Check that `~/.waggle/` exists and is writable
- Check that no other process has the `.mind` file locked
- If the file is corrupted, rename it (data will be lost) and let Waggle create a fresh one
### A provider key is rejected
### Server crashes with "out of memory"
Copy the whole key again from the provider's console. Waggle checks the key's format and, when
the provider is reachable, tests it. A key that worked before can stop working when the provider
account runs out of credit or the key is revoked.
Large workspace minds or many concurrent operations can exhaust memory.
### Local model downloads are slow or large
**Fix:**
- Restart the server
- If recurring, check your mind file size: `ls -la ~/.waggle/default.mind`
- Consider running memory consolidation: `POST /api/cron/{consolidation-id}/trigger`
The managed Ollama runtime and the models are large downloads (the Linux runtime alone is about
1.4 GB). They are stored in `<data>/runtimes/ollama` and `<data>/models/ollama`. Keep the window
open until the download is verified.
## Memory Issues
## Memory
### Memory not saving
### Waggle does not remember something
Memories are saved automatically during conversations when the agent determines something is important.
- Say it explicitly: "Remember that …".
- Check the scope. Workspace memories are only recalled in their workspace; personal memories
everywhere. `/search-all <query>` searches all workspaces.
- Open **Memory** and search for it. If it is there but marked temporary, it is not recalled.
**Check:**
1. Verify the workspace mind path exists: `~/.waggle/workspaces/{id}/workspace.mind`
2. Check that the disk has free space
3. Try saving explicitly: "Remember that [important fact]"
### "Learn facts about me from chats" is not available
### Search returns no results
Background fact extraction needs a model. Set one up in **Settings** → **Models**.
FTS5 search requires at least 3 characters.
### "This memory store was built with embedder …"
**Fix:**
- Use longer queries (3+ characters)
- Check you are searching the right scope (personal, workspace, or all)
- Verify memories exist: open the Memory tab in the right panel
The memory store was created with another embedding model, whose vectors cannot be compared with
the current one. Switch back to that model, or quit Waggle and move `<data>/memory/` aside to
start a new, empty store.
### Memory from another workspace showing up
### Memory needs a network connection the first time
This is expected behavior. The agent searches both personal and workspace minds. Personal mind memories are shared across all workspaces.
The embedding model used by memory is downloaded on first use into `<data>/models/`. After that,
memory works offline.
**Fix:** If a memory should be workspace-specific, it should have been saved to the workspace mind (this happens automatically for project-specific context).
## Connectors and channels
## Connector Issues
See [connectors.md](connectors.md#troubleshooting).
### "Vault not available"
## Your data
The encrypted vault database failed to initialize.
### Where is my data?
**Fix:**
- Check that `~/.waggle/` is writable
- If `~/.waggle/vault.db` exists but is corrupted, rename it and restart
- The vault auto-migrates from plain config.json on first access
In `<data>`; [install.md](../install.md#where-your-data-lives) lists what each file holds. Data
leaves your computer only for the services you set up (model providers, connectors, channels,
marketplace sources) and, if you allowed analytics, one setup event without your chats, files or
memories.
### Connector shows "disconnected" after restart
### Move Waggle to another computer
Credentials persist in the vault across restarts. If a connector shows disconnected:
Quit Waggle and copy the whole data directory. On the new computer, install Waggle and put the
directory in the same place (or point `WAGGLE_DATA_DIR` at it). The Vault key (`.vault-key`)
must travel with `vault.json`, or the stored secrets cannot be read.
1. Check the health endpoint: `GET /api/connectors/{id}/health`
2. If the token expired, re-connect with fresh credentials
3. If the service is unreachable, check your network
### Start over
### "Connector not found" (404)
Quit Waggle and delete the data directory, or use **Settings** → **General** → **Erase all my
data**, which wipes it the next time Waggle starts. Data you already sent to cloud model providers
is not erased by this; ask those providers.
Connector IDs are lowercase. Use `GET /api/connectors` to see all registered IDs.
## Questions
### Approval gate stuck
**Which models work?** Models from Anthropic, OpenAI, Google, DeepSeek, xAI, Mistral, Alibaba,
MiniMax, Zhipu, Moonshot, Perplexity and OpenRouter with your own key, and local models through
Ollama.
If an approval card appears but you cannot click Approve/Deny:
**What does it cost?** Waggle is free. You pay your model provider for what you use. **Usage &
Cost** shows the estimated cost of your model calls, and Settings → Models can set a daily
budget.
**Fix:**
1. Check `GET /api/approval/pending` to see pending approvals
2. Approve via API: `POST /api/approval/{requestId}` with `{"approved": true}`
3. If the request expired, send a new message to the agent
## Desktop App Issues
### White screen after launch
The Tauri WebView2 runtime may not be installed (Windows).
**Fix:** Download and install the [WebView2 Runtime](https://developer.microsoft.com/en-us/microsoft-edge/webview2/).
### Sidecar not starting
The Node.js sidecar needs Node.js 20+ in the system PATH.
**Fix:**
- Install Node.js 20+ from https://nodejs.org
- Restart the app after installation
- Check the Tauri console for error messages
### Notifications not appearing (Windows)
**Fix:**
- Check Windows notification settings for Waggle
- Ensure "Focus Assist" is not blocking notifications
- The app must be running (tray icon visible)
## Team Mode Issues
### Cannot connect to team server
**Check:**
- The server URL is correct (include `https://`)
- The auth token is valid
- The team server is reachable: `curl https://your-server/health`
### "Team server connection timed out"
**Fix:** The team server health check has a 5-second timeout. Check that:
- The server is running
- There are no firewall rules blocking the connection
- DNS resolves correctly
### Tasks not syncing
Task data is stored per-workspace in JSONL files. In team mode, tasks are stored on the team server.
**Fix:** Check team connection status: `GET /api/team/status`
## Common Error Codes
| Code | Meaning | Fix |
|------|---------|-----|
| 400 | Bad request -- missing or invalid parameters | Check the API reference for required fields |
| 404 | Resource not found | Verify the ID/name exists |
| 409 | Conflict -- resource already exists | The skill/plugin is already installed |
| 413 | File too large | Files must be under 10 MB |
| 503 | Service unavailable | The required service (vault, marketplace, plugin runtime) is not ready |
## FAQ
**Q: Where is my data stored?**
A: All data is in `~/.waggle/` on your machine. Nothing is sent to cloud servers unless you explicitly connect a team server or external service.
**Q: Can I move my data to another machine?**
A: Yes. Copy the entire `~/.waggle/` directory. The `.mind` files are portable SQLite databases.
**Q: How do I reset everything?**
A: Delete `~/.waggle/` and restart. Waggle creates fresh defaults on startup.
**Q: Which LLM models work?**
A: Waggle works best with Claude (Anthropic). It also supports OpenAI, Google Gemini, and any model available through LiteLLM. The built-in proxy handles Anthropic natively.
**Q: How much does it cost to run?**
A: Waggle itself is free. You pay only for LLM API usage. The Cockpit status bar shows estimated cost per session. A typical conversation costs $0.05-0.50 depending on length and model.
**Q: Can I use it offline?**
A: Waggle requires an LLM API connection for agent responses. Memory, workspace management, and the UI work offline.
**Does it work offline?** With a local model, yes, once the runtime, the model and the embedding
model are downloaded. With a provider key, chat needs a connection to that provider; your
workspaces, files and memory stay available offline.

View File

@@ -1,149 +1,74 @@
# Workspaces
Workspaces are the core organizational unit in Waggle. Each workspace is a dedicated brain for a project, topic, or area of work. It has its own memory, sessions, files, tasks, and optionally a linked directory on disk.
A workspace holds one project or area of work: its chats, its files, its memory and the persona
the agent uses there. Your personal memory is shared by all workspaces; everything else stays in
its workspace.
## Creating a Workspace
## Creating a workspace
Press **Ctrl+N** or click **New Workspace** in the sidebar.
Create a workspace from **Home** or the workspace list. You choose:
| Field | Required | Description |
|-------|----------|-------------|
| Name | Yes | Display name (e.g., "Q1 Planning", "Product Research") |
| Group | Yes | Category for sidebar grouping (e.g., "Work", "Personal") |
| Icon | No | Emoji or character for visual identification |
| Model | No | Override the default LLM model for this workspace |
| Persona | No | Assign a specialized agent persona |
| Directory | No | Link a folder on disk for file-aware operations |
| Field | Description |
|---|---|
| Name | "What project or area is this for?", for example "Acme Client" or "Q3 Launch" |
| Template | Optional. A starting setup with a matching persona, such as Research Hub or Engineering |
| Group | A category for grouping workspaces in the list, such as Work or Personal |
| Storage type | **Virtual**: Waggle keeps the workspace's files in its data directory. **Local**: the workspace uses a folder on your disk |
| Agent | Optional. The persona to use in this workspace |
When you create your first workspace, Waggle auto-installs the starter skills (draft-memo, research-synthesis, extract-actions, etc.) if they are not already present.
The first setup creates your first workspace from the template you pick.
## Workspace Types
## Storage: virtual or a folder on disk
### Personal Workspaces
- **Virtual** workspaces keep their files in `<data>/workspaces/<id>/files`.
- **Local** workspaces point at a folder you choose. The agent's file tools (read, write, edit,
search) work in that folder, and its git tools work on the repository there. Writes go
through the approval rules in Settings → Permissions. Shell commands run with your user's
rights and are not sandboxed; see the [threat model](../../THREAT_MODEL.md).
Created locally, stored on your machine. Memory lives in `~/.waggle/workspaces/{id}/workspace.mind`. Only you can access them.
## Chats (sessions)
### Team Workspaces
Each conversation in a workspace is a session. Sessions are stored as JSON Lines files in
`<data>/workspaces/<id>/sessions/`.
Linked to a team server. Created from the Team panel after connecting to a team server. Team workspaces support:
- Shared memory that syncs between team members
- Task boards visible to the whole team
- Real-time presence (who is online, who is typing)
- Admin-governed capability policies
A workspace's team status is indicated by a team badge in the sidebar.
## Workspace Home Screen
When you open a workspace, you see the Home screen with:
1. **Summary** -- a narrative description of what this workspace is about, how many memories and sessions it has, and when it was last active.
2. **Recent Decisions** -- key decisions extracted from your conversation history.
3. **Recent Threads** -- your last 5 sessions, clickable to resume.
4. **Suggested Prompts** -- contextual suggestions based on workspace state:
- New workspace: "Tell me about this project", "What can you do?"
- Returning workspace: "Catch me up", "Continue: [last thread]", "What should I do next?"
5. **Progress Items** -- tasks, completions, and blockers extracted from sessions.
6. **Stats** -- memory count, session count, file count.
The Home screen is never a blank chat. It always gives you a reason to engage.
## Sessions
Each conversation thread is a **session**. Sessions are stored as `.jsonl` files in `~/.waggle/workspaces/{id}/sessions/`.
### Creating Sessions
- Click the **+** button in the sidebar to start a new session
- Or just start typing -- a session is created automatically
### Session Metadata
Each session has:
- **Title** -- derived from the first user message, or set manually
- **Summary** -- auto-generated after 4+ messages (heuristic, no LLM needed)
- **Outcome** -- what changed, open items, next step (extracted at session end)
### Renaming Sessions
Click the session title in the sidebar and type a new name, or use the `PATCH /api/sessions/:id` endpoint.
### Searching Across Sessions
Use the search bar in the sidebar to find messages across all sessions in the current workspace. Matches show snippets with context.
### Exporting Sessions
Right-click a session and choose **Export as Markdown** to get a clean document with timestamps and formatted messages.
## Switching Workspaces
- Click any workspace in the left sidebar
- Press **Ctrl+K** for the quick-switch dialog
- Workspaces are grouped by their category (Work, Personal, etc.)
Each workspace in the sidebar shows a hue-colored dot for visual differentiation.
- Start a new chat from the workspace, or just type: a session is created on the first message.
- A session is titled from its first message; you can rename it.
- Search finds messages across the sessions of the current workspace.
- A session can be exported as Markdown.
## Personas
Personas are specialized agent configurations. Assigning a persona to a workspace tunes the agent's behavior without changing the core capabilities.
A persona sets how the agent works in a workspace: its instructions, the tools it prefers, the
commands it suggests and, for some, a default workflow. Waggle ships with 22 personas: General
Purpose, Researcher, Writer, Analyst, Coder, Planner, Verifier, Coordinator, Project Manager,
Senior PM, Executive Assistant, Sales Rep, Marketer, Customer Support, Operations Manager, Data
Engineer, HR Manager, Recruiter, Legal Counsel, Business Finance, Strategy Consultant and
Creative Director.
| Persona | Focus | Default Workflow |
|---------|-------|-----------------|
| Researcher | Deep investigation, multi-source synthesis | research-team |
| Writer | Document drafting, editing, tone adaptation | -- |
| Coder | Software development, debugging, code review | -- |
| Analyst | Data analysis, decision matrices, pattern recognition | -- |
| Project Manager | Task tracking, status reports, planning | plan-execute |
| Executive Assistant | Email drafting, meeting prep, correspondence | -- |
| Sales Rep | Lead research, outreach, pipeline management | research-team |
| Marketer | Content creation, campaign planning, SEO | -- |
Switch the persona with `Ctrl+Shift+P` (`Cmd+Shift+P` on macOS). Some personas are read-only:
they cannot use tools that write. You can also create your own agents in **Agents** (at the
Everything interface level).
### Changing Persona
## Workspace memory
Open workspace settings (gear icon on the workspace home) and select a different persona. The change takes effect on the next message.
Each workspace has its own memory, separate from your personal memory:
### Persona Tool Presets
- **Workspace memory** holds project context: decisions, findings, notes.
- **Personal memory** holds what is true across workspaces: your preferences, your role,
recurring facts.
Each persona has a curated tool set. The Coder persona enables git tools; the Researcher enables web search; the Executive Assistant enables document generation. All tools remain available -- the persona just adjusts defaults and suggestions.
In a workspace the agent reads both. It does not read other workspaces' memory unless you ask
it to search all workspaces (`/search-all <query>`). See [memory.md](../memory.md).
## Directory Association
Open **Memory** to browse, search, correct, confirm or forget memories.
Linking a workspace to a directory on disk enables:
## Switching workspaces
- `read_file`, `write_file`, `edit_file` operate relative to the linked directory
- `search_files` and `search_content` scan the directory tree
- `git_status`, `git_diff`, `git_log`, `git_commit` work on the repo in that directory
- File listings appear in the workspace context
- Pick a workspace from **Home** or the workspace list.
- `Ctrl+Tab` opens the workspace switcher; `Ctrl+K` searches everything, workspaces included.
To link a directory, set it during workspace creation or update it in workspace settings.
## Deleting a workspace
## Workspace Memory
Each workspace has its own `.mind` database separate from your personal mind.
- **Workspace mind** stores project-specific context: decisions, research, architecture choices
- **Personal mind** stores cross-workspace knowledge: your preferences, name, recurring facts
When the agent searches memory, it queries both minds and merges results, prioritizing workspace-specific memories when relevant.
### Memory Browser
Click the **Memory** tab in the right panel to browse all frames in the current workspace. You can:
- Search by keyword (FTS5 full-text search)
- Filter by importance level
- View the knowledge graph of entities and relationships
- Delete outdated or incorrect frames
## Deleting a Workspace
Right-click a workspace in the sidebar and choose **Delete**. This removes:
- The workspace entry from the workspace list
- Session files
- The workspace `.mind` file
- Task and file registry data
Personal mind memories are not affected.
Deleting a workspace removes its memory, its sessions and its virtual files
(`<data>/workspaces/<id>/`). A folder on disk linked as Local storage is not deleted. Personal
memory is not affected.

279
docs/install.md Normal file
View File

@@ -0,0 +1,279 @@
# Installing Waggle
There are two ways to install Waggle. Both run the same server and the same web UI, and both
keep your data in the same place.
| | Desktop app | Server installer |
|---|---|---|
| What you get | A Waggle window, started from the Start menu, Applications or your launcher | A `waggle-server` command; you use Waggle in your browser |
| Needs | Nothing else | Node.js 20 or newer for the first `npx` call only |
| Formats | Windows `.exe` and `.msi`, macOS `.dmg`, Linux `.deb` and `.AppImage` | One archive per system, downloaded by the installer |
Supported systems in this release: Windows x64, macOS on Apple silicon (arm64) and Intel
(x64), and Linux x64 with glibc (for example Debian, Ubuntu, Fedora). Other systems, such as
Windows on ARM or Linux on ARM, have no build.
Neither way needs Python, Docker or a compiler. Each build carries its own Node.js runtime
(22.23.2) and the native modules that match it.
> **Unsigned first release.** The installers of the first community release are not signed.
> Windows and macOS warn about them. The sections below show how to get past the warning.
> Download Waggle only from the project's release page.
## Desktop app
### Windows
1. Download `Waggle_<version>_x64-setup.exe`. A `.msi` package is also available; use the
`.exe` unless you deploy with MSI tools. The `.exe` installs for the current user and does
not need administrator rights.
2. If the browser warns that the file is not commonly downloaded, choose to keep it (in Edge:
**...** → **Keep**).
3. Run the installer. SmartScreen shows "Windows protected your PC". Choose **More info**, then
**Run anyway**.
4. Start Waggle from the Start menu.
Waggle uses the WebView2 runtime, which ships with current Windows 10 and 11.
### macOS
1. Download the `.dmg` for your Mac: `Waggle_<version>_aarch64.dmg` for Apple silicon,
`Waggle_<version>_x64.dmg` for Intel. (Apple menu → **About This Mac** shows the chip.)
2. Open the `.dmg` and drag **Waggle** to **Applications**.
3. Open Waggle. Because the app is not signed, macOS blocks the first launch:
- macOS 15 and later: after the warning, open **System Settings** → **Privacy & Security**,
scroll to the message about Waggle and choose **Open Anyway**.
- Earlier versions: Control-click (or right-click) Waggle in Applications, choose **Open**,
then **Open** again in the dialog.
- If macOS says the app "is damaged" or still refuses, remove the download quarantine flag
in Terminal and open it again:
```bash
xattr -dr com.apple.quarantine /Applications/Waggle.app
```
You only need to do this once.
### Linux
Debian, Ubuntu and other distributions with apt:
```bash
sudo apt install ./Waggle_<version>_amd64.deb
```
apt installs the libraries the app needs (WebKitGTK and GTK). Start Waggle from your
application launcher.
AppImage, for other distributions:
```bash
chmod +x Waggle_<version>_amd64.AppImage
./Waggle_<version>_amd64.AppImage
```
An AppImage needs FUSE 2. If it fails with a FUSE error, install it (`libfuse2` on Ubuntu 22.04,
`libfuse2t64` on Ubuntu 24.04 and later, `fuse-libs` on Fedora).
Linux packages are not signed. If the release page lists SHA-256 checksums, compare them before
you install:
```bash
sha256sum Waggle_<version>_amd64.deb
```
### What the desktop app does on start
The window shows "Starting Waggle…" while the app starts its own server in the background. The
server listens on `127.0.0.1` port 3333, or on another free port if 3333 is taken. Its log is in
`~/.waggle/logs/service.log` (on Windows `%USERPROFILE%\.waggle\logs\service.log`).
### Update the desktop app
The desktop app does not update itself in this release. Quit Waggle, then install the new
version over the old one:
- Windows: run the new installer.
- macOS: drag the new Waggle to Applications and replace the old one.
- Linux: `sudo apt install ./Waggle_<new version>_amd64.deb`, or replace the AppImage file.
Your data is not touched.
### Uninstall the desktop app
- Windows: **Settings** → **Apps** → **Installed apps** (**Apps & features** on Windows 10) →
**Waggle** → **Uninstall**. The uninstaller always keeps your data, even if you tick its
"Delete app data" box.
- macOS: quit Waggle and move **Waggle** from Applications to the Trash.
- Linux: remove the package (`sudo apt remove waggle`; `dpkg -l | grep -i waggle` shows its
name), or delete the AppImage file.
Your data stays in the data directory; see [Where your data lives](#where-your-data-lives).
## Server installer
The server installer puts the Waggle server on your computer and starts it. You then use Waggle
in your browser at http://localhost:3333.
> **Temporary names.** The package name `@waggle-ai/waggle` and the command `waggle-server` are
> working names until the product name is decided. The installer also has no default download
> location yet, because the location of the public repository is not decided. Until then, pass
> the archive with `--from`, as shown below.
### Install
You need Node.js 20 or newer for this one command. After that, Waggle runs on its own Node.js
runtime and does not use yours.
```bash
npx @waggle-ai/waggle install --from <archive path or URL>
```
The archive for your system is named `waggle-server-<version>-<target>.tar.gz`, where
`<target>` is `windows-x64`, `macos-arm64`, `macos-x64` or `linux-x64`. A `.sha256` file is
published next to it.
The installer:
1. checks the archive against its SHA-256 (for a URL it reads `<URL>.sha256`; for a local file it
reads `<file>.sha256` if one is next to it). A mismatch stops the install. Pass
`--sha256 <hex>` to give the checksum yourself;
2. unpacks it into a program directory;
3. writes the `waggle-server` command.
| System | Program directory | `waggle-server` command |
|---|---|---|
| Windows | `%LOCALAPPDATA%\Waggle\server` | `%LOCALAPPDATA%\Waggle\server\bin\waggle-server.cmd` |
| macOS | `~/Library/Application Support/Waggle/server` | `~/.local/bin/waggle-server` |
| Linux | `~/.local/share/waggle/server` (or `$XDG_DATA_HOME/waggle/server`) | `~/.local/bin/waggle-server` |
The installer never edits your `PATH`. If the command's directory is not on your `PATH`, it
prints the full path to run and the directory to add.
Once a download location exists, `npx @waggle-ai/waggle install` without `--from` downloads
the archive for your system. `WAGGLE_RELEASE_BASE_URL` points it at a mirror.
### Run
```bash
waggle-server
```
This is the same as `waggle-server run`. It starts the server, waits until it answers and opens
http://localhost:3333 in your browser. The server runs in that terminal; press Ctrl+C to stop
it. It listens on this computer only (`127.0.0.1`).
| Option | Meaning |
|---|---|
| `--port <number>`, `-p` | Use another port (default 3333) |
| `--no-open` | Do not open the browser |
| `--data-dir <path>` | Keep data in another directory (default `$WAGGLE_DATA_DIR` or `~/.waggle`) |
| `--dir <path>` | Use a program directory other than the default |
If Waggle already runs on the port, `waggle-server` only opens the browser.
### Check the installation
```bash
waggle-server doctor
```
`doctor` checks that this system has a build, the installed files, the bundled Node.js runtime,
that SQLite loads, that the data directory is writable, the port, and whether
`waggle-server` is on your `PATH`. It exits with an error code if a check fails.
### Update
`update` installs the version of the installer you run it with:
```bash
npx @waggle-ai/waggle@latest update # once a download location exists
waggle-server update --from <archive path or URL> # a specific archive
```
Your data is not touched. On Windows a running program cannot be replaced: stop the server
first, and run `update` through `npx`, not through the installed `waggle-server`.
### Uninstall
```bash
waggle-server uninstall
```
This removes the program directory and the `waggle-server` command. Your data stays in the data
directory. On Windows, stop the server and run `npx @waggle-ai/waggle uninstall`.
All commands also take `--help` and `--version`.
## First launch
Waggle opens a short setup:
1. **Welcome** and **Who are you**: your name, role and the kind of work you do, kept on this
computer in your profile.
2. **Model**: choose how Waggle thinks (see below). You can skip this step, but chat stays
unavailable until a model is set up.
3. **Pick a starting point**: a template for your first workspace (for example Research Hub,
Sales Pipeline or Engineering), or **Blank Workspace**.
4. **What's first?**: give the agent its first task, or pick a suggestion.
### Choose a model
- **API key.** Paste a key from a provider you already use: Anthropic, OpenAI, Google,
DeepSeek, xAI, Mistral, Alibaba (Qwen), MiniMax, Zhipu (GLM), Moonshot (Kimi), Perplexity or
OpenRouter. Waggle checks the key with the provider and stores it encrypted on this computer.
Requests go from your computer straight to that provider.
- **Local model.** Choose **Install private runtime**. Waggle downloads the official Ollama
runtime into its data directory, checks the download's checksum and runs it for you. Then
download a model (Waggle suggests one that fits your hardware). Nothing else needs to be
installed, and chats stay on your computer. The downloads are large: the Linux runtime alone
is about 1.4 GB, and a model adds several GB. If you already run Ollama yourself, Waggle uses
it.
You can change both later in **Settings** → **Models**. Keys are also listed in the **Vault**.
### Analytics
Release builds may carry a key for product analytics. If yours does, Waggle asks once whether it
may send usage analytics. Nothing is sent until you choose **Allow**. If you allow it, Waggle
sends one event when you finish the setup, with the template, persona and model you chose. Your
chats, files and memories are never sent. You can turn analytics off again in **Settings** →
**General** → **Privacy & Telemetry**. Builds from source have no key: they never ask and never
send.
## Where your data lives
Both ways of installing use one data directory: `~/.waggle` (on Windows
`%USERPROFILE%\.waggle`). Set `WAGGLE_DATA_DIR` to use another directory; the server installer
also takes `--data-dir`.
| Path in the data directory | What it holds |
|---|---|
| `config.json` | Settings |
| `vault.json`, `.vault-key` | Provider keys and connector credentials, encrypted with AES-256-GCM |
| `waggle.db` | Automations, notifications, cost tracking, your profile card and task list |
| `memory/` | Your memories (see [memory.md](memory.md)) |
| `workspaces/<id>/` | Each workspace: settings, chat sessions (`sessions/*.jsonl`) and files |
| `skills/`, `plugins/` | Installed skills and plugins |
| `marketplace.db` | The marketplace catalog |
| `models/` | The embedding model used by memory, downloaded on first use; local model weights in `models/ollama/` |
| `runtimes/ollama/` | The Waggle-managed Ollama runtime |
| `channels/`, `browsers/` | Messaging channel sessions, and a browser downloaded for WhatsApp if none is installed |
| `logs/` | The desktop app's server log |
Uninstalling Waggle, either way, keeps this directory. To remove your data, quit Waggle and
delete the directory, or use **Settings** → **General** → **Erase all my data**, which wipes it
the next time Waggle starts.
To move Waggle to another computer, quit it and copy the whole directory.
The commercial edition of Waggle uses the same default directory. If you use both on one
computer, give the community edition its own directory with `WAGGLE_DATA_DIR`.
## Run from source
See the [README](../README.md#run-from-source) and [CONTRIBUTING.md](../CONTRIBUTING.md).
## Problems
See [troubleshooting](guides/troubleshooting.md).

176
docs/memory.md Normal file
View File

@@ -0,0 +1,176 @@
# Memory
Waggle remembers facts, decisions and preferences across chats and keeps them on your computer.
This page describes how memory works in the community edition, for users who want to know what
is kept and for contributors who change memory code.
The decisions behind it are in [ADR-0002](oss/adr/0002-memory-contract-local-mem0.md) and
[ADR-0007](oss/adr/0007-memory-contract.md).
## The memory contract
Waggle reaches memory only through one interface, `MemoryStore`, in the package
`@waggle/memory-contract` (`packages/memory-contract/src/types.ts`). No other code queries a
memory database directly. The package also holds an in-memory store for development and tests,
and a compatibility suite that every implementation must pass.
The implementation that ships is `@waggle/memory-mem0` (`packages/memory-mem0/src/index.ts`).
It runs the open-source [mem0](https://github.com/mem0ai/mem0) library (`mem0ai`, Apache-2.0,
pinned to 3.3.1) inside the Waggle server. The hosted Mem0 Platform is not used, and nothing is
sent to a cloud memory service.
### Records
A memory record has:
| Field | Values |
|---|---|
| `text` | The memory itself |
| `scope` | `personal`, or one workspace |
| `kind` | `fact`, `event`, `preference`, `profile`, `decision`, `summary`, `note` |
| `importance` | `critical`, `important`, `normal`, `temporary` |
| `source` | `user_stated`, `tool_verified`, `agent_inferred`, `import`, `system` |
| `origin` | Which part of Waggle wrote it, for example `chat`, `agent-run`, `loop` or `extraction` |
| `sessionId` | The chat it came from, if any |
| `createdAt`, `updatedAt` | ISO 8601 timestamps |
| `metadata` | Free fields set by the caller (title, tags and so on) |
Ids are unique across all scopes.
### Scopes
- **Personal** memory follows you across all workspaces: who you are, how you like to work,
facts that are not tied to one project.
- **Workspace** memory belongs to one workspace: its decisions, findings and files.
In a workspace, the agent reads both its personal memory and that workspace's memory. It never
reads another workspace's memory unless you ask it to search all workspaces (for example with
`/search-all`).
### Operations
| Operation | What it does |
|---|---|
| `remember` | Stores a text as one memory, or extracts facts from a conversation with a model. Identical text in the same scope is not stored twice. |
| `search` | Returns the memories most relevant to a query, best first (default 10) |
| `list` | Returns memories newest first (default 50) |
| `count` | Counts the memories that match a filter |
| `get` | Reads one memory by id |
| `update` | Changes the text, kind, importance or metadata of a memory |
| `forget` | Deletes one memory |
| `forgetMatching` | Deletes every memory that matches a filter |
| `history` | Lists the changes to one memory, oldest first |
Filters select by scopes, kinds, minimum importance, origin, chat session and a creation-time
window.
### Capabilities
A store reports what it can do, and the web UI hides what it cannot:
| Capability | mem0 store | Meaning |
|---|---|---|
| `extraction` | Yes, when a model is set up | `remember` can extract facts from a conversation |
| `semanticSearch` | Yes | Search ranks by meaning, not only by shared words |
| `history` | Yes | The change log of each memory is kept |
| `knowledgeGraph` | No | Entities and relations between memories. Not part of this release. |
## Where mem0 keeps its data
Everything is in `memory/` inside the data directory (`~/.waggle/memory/` by default):
| File | Content |
|---|---|
| `vectors.db` | Memories and their embeddings (SQLite) |
| `history.db` | The change log, and the last messages used for fact extraction (SQLite) |
| `vectors_entities.db` | A second store mem0 creates next to `vectors.db` (SQLite) |
| `waggle-memory.json` | Which embedding model built the store |
| `config.json` | mem0's own settings |
All memories belong to one local user. The scope is stored as mem0's agent id (`personal` or
`workspace:<id>`), so mem0 never compares facts across scopes.
mem0's own telemetry is turned off before the library loads, so it makes no network requests
of its own. A test checks this.
When you forget a memory, Waggle also deletes its old text from `history.db`, so the text does
not survive in the change log.
### Embeddings
Search compares embeddings: number vectors that capture the meaning of a text. Waggle computes
them on your computer with a small model (`all-MiniLM-L6-v2`), downloaded on first use into
`models/` in the data directory. After that, memory works without a network connection.
The store records which embedding model built it and refuses to open with a different one,
because their vectors cannot be compared. To start over with another model, move the
`memory/` directory aside.
## How the agent uses memory
### Recall
Before it answers, the agent recalls what is relevant to your message:
- it searches personal memory and the current workspace's memory (mem0 combines vector and
keyword search);
- it adds the most important memories of the workspace, even if they do not match the words;
- it adds facts about you (kind `profile`) and recent events, each in its own section;
- a question about a period ("what did we do last week") limits the search to that period;
- a catch-up question ("where were we?", "what did we decide?") recalls the workspace's
important memories and decisions instead of searching for the words;
- `temporary` memories are left out.
The recalled text passes the prompt-injection scanner first. If it looks like an attempt to
give the agent instructions, the whole recall is dropped for that turn.
An optional reranker can reorder search results; it is off by default
(`WAGGLE_RERANKER=1` turns it on).
### Writing
Memories are written:
- when you ask ("Remember that we chose PostgreSQL") or the agent decides something is worth
keeping, through its `save_memory` tool;
- from finished agent runs, scheduled loops, connector fetches and indexed workspace files;
- from summaries when a long chat is compacted;
- by background fact extraction (next section).
### Background fact extraction
While you chat, Waggle can pick out facts about you, such as your role or how you like answers,
and save them to personal memory as kind `profile`.
- Finished chat turns are collected per chat. After six messages, or after a two-minute pause,
they are handed to mem0, which asks a model to extract facts.
- The model is the one you chat with. mem0 calls it through the Waggle server's built-in
provider proxy, so a local model keeps this on your computer, and a provider key sends these
messages to that provider, as chat does.
- Long messages are cut to their first 4,000 characters.
- A failed extraction is logged and never blocks a chat.
- Turn it off in **Settings** → **General** → **Memory** ("Learn facts about me from chats").
It is on by default, and unavailable when no model is set up.
## Managing memory
Open **Memory** in Waggle to browse, search, correct, confirm or forget what is kept.
`/memory <query>` searches from a chat.
Not in this release: importing chat history from other AI tools, the knowledge graph, the wiki,
and the memory server for external tools (MCP).
## For contributors
- Reach memory only through `MemoryStore`. Do not query a memory database with SQL and do not
import mem0 outside `@waggle/memory-mem0`.
- Waggle's own data (automations, cost tracking, notifications, your profile card, the task
list) is not memory. It lives in `waggle.db`, opened by `WaggleDB` in `@waggle/core`.
- A new implementation of the contract must pass the compatibility suite in
`@waggle/memory-contract`.
- `list`, `count` and `forgetMatching` read every memory of the scopes involved. That is fine at
personal scale.
- Upgrading `mem0ai` means re-running the compatibility suite and re-checking that mem0 sends
no telemetry (ADR-0007).
- Tests use a word-based embedder that needs no model download:
`WAGGLE_MEMORY_EMBEDDER=words`.

View File

@@ -1,22 +1,35 @@
# API Reference
# Local API reference
The Waggle local server runs on `http://localhost:3333`. All endpoints accept and return JSON unless otherwise noted.
The Waggle server runs on `http://localhost:3333` and listens on `127.0.0.1` only. The web UI
uses this API; it is not a stable public interface and can change between releases. Endpoints
accept and return JSON unless noted otherwise. The routes live in
`packages/server/src/local/routes/`.
## Authentication
Every `/api/*` request needs the session token as `Authorization: Bearer <token>`. Server-Sent
Event streams that cannot send headers accept it as `?token=`. The web UI gets the token from
`GET /api/auth/session-token`, which answers only same-origin requests from the page the server
serves (the desktop app gets it through its own launch credential). Requests with a `Host`
header other than a local one are refused.
This page lists the main route groups, not every route.
## Chat
| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/chat` | Send a message and receive an SSE stream of agent responses. Body: `{ message, workspaceId, sessionId, model? }` |
| POST | `/api/chat` | Send a message and receive an SSE stream of the agent's reply. Body: `{ message, workspaceId?, sessionId?, model?, persona? }` |
| GET | `/api/history` | Get conversation history. Query: `?session=ID&workspace=ID` |
The chat endpoint streams responses via Server-Sent Events (SSE). Events include `message`, `tool_call`, `tool_result`, `approval_request`, `done`, and `error`.
The chat endpoint streams the reply as Server-Sent Events; see [Chat stream events](#chat-stream-events).
## Workspaces
| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/workspaces` | List all workspaces |
| POST | `/api/workspaces` | Create a workspace. Body: `{ name, group, icon?, model?, personaId?, directory?, teamId? }` |
| POST | `/api/workspaces` | Create a workspace. Body: `{ name, group, icon?, model?, personaId?, templateId?, storageType?: 'virtual' \| 'local', storagePath? }` |
| GET | `/api/workspaces/:id` | Get workspace by ID |
| PUT | `/api/workspaces/:id` | Update workspace. Body: `{ name?, group?, icon?, model?, personaId? }` |
| DELETE | `/api/workspaces/:id` | Delete workspace |
@@ -27,20 +40,40 @@ The chat endpoint streams responses via Server-Sent Events (SSE). Events include
| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/workspaces/:wid/sessions` | List sessions for a workspace, sorted by last active |
| POST | `/api/workspaces/:wid/sessions` | Create a new session. Body: `{ title? }` |
| GET | `/api/workspaces/:wid/sessions/search` | Search across sessions. Query: `?q=query&limit=20` |
| GET | `/api/workspaces/:wid/sessions/:sid/export` | Export session as Markdown. Returns `text/markdown` |
| PATCH | `/api/sessions/:id` | Rename a session. Body: `{ title }`. Query: `?workspace=ID` |
| DELETE | `/api/sessions/:id` | Delete a session. Query: `?workspace=ID` |
| GET | `/api/workspaces/:workspaceId/sessions` | List sessions for a workspace, sorted by last active |
| POST | `/api/workspaces/:workspaceId/sessions` | Create a new session. Body: `{ title? }` |
| GET | `/api/workspaces/:workspaceId/sessions/search` | Search across sessions. Query: `?q=query&limit=20` |
| GET | `/api/workspaces/:workspaceId/sessions/:sessionId/export` | Export a session as Markdown (`text/markdown`) |
| GET | `/api/workspaces/:workspaceId/sessions/:sessionId/timeline` | Tool events of a session |
| PATCH | `/api/sessions/:sessionId` | Rename a session. Body: `{ title }`. Query: `?workspace=ID` |
| DELETE | `/api/sessions/:sessionId` | Delete a session. Query: `?workspace=ID` |
## Memory
All memory routes go through the memory contract ([memory.md](../memory.md)). Some paths still
say "frames", the name used by the old memory engine; they return memory records.
| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/memory/search` | Search memory. Query: `?q=query&scope=all|personal|workspace&limit=20&workspace=ID` |
| GET | `/api/memory/frames` | Recent frames without search. Query: `?workspace=ID&limit=50` |
| GET | `/api/memory/graph` | Knowledge graph entities and relations. Query: `?workspace=ID` |
| GET | `/api/memory/capabilities` | What the memory store supports, and the extraction setting |
| PUT | `/api/memory/settings` | Turn background fact extraction on or off. Body: `{ extraction: boolean }` |
| GET | `/api/memory/search` | Search memory. Query: `?q=query&scope=all\|personal\|workspace\|global&workspace=ID&limit=20&since=&until=` (`all` is personal plus the given workspace; `global` is personal plus every workspace) |
| GET | `/api/memory/frames` | Newest personal and workspace memories. Query: `?workspace=ID&limit=50&since=&until=` |
| POST | `/api/memory/frames` | Save a memory. Body: `{ content, workspaceId?, importance?, kind?, source? }` |
| PUT | `/api/memory/frames/:id` | Edit a memory's text or importance |
| DELETE | `/api/memory/frames/:id` | Delete a memory |
| GET | `/api/memory/stats` | Memory counts. Query: `?workspace=ID` |
| GET | `/api/memory` | List memories. Query: `?mind=personal\|workspace&workspace=ID&kind=&status=&q=&limit=` |
| GET | `/api/memory/:id` | One memory |
| POST | `/api/memory` | Create a memory stated by the user |
| PATCH | `/api/memory/:id` | Edit text, importance, kind, title, tags, evidence or status |
| DELETE | `/api/memory/:id` | Delete a memory |
| POST | `/api/memory/:id/archive` | Archive a memory (reversible) |
| POST | `/api/memory/:id/confirm` | Mark a memory as confirmed by the user |
| GET | `/api/memory/:id/trace` | The execution that produced a memory ("why did you do that?") |
| POST | `/api/memory/erase` | Forget one memory (`{ id }`) or every memory saved from one chat (`{ sessionId }`) |
| POST | `/api/memory/merge` | Merge several memories of one scope into one |
| GET | `/api/memory/graph` | Always returns an empty graph: the knowledge graph is not part of this release |
## Agent
@@ -67,9 +100,9 @@ The chat endpoint streams responses via Server-Sent Events (SSE). Events include
| GET | `/api/settings` | Read config: default model, providers (masked keys), paths |
| PUT | `/api/settings` | Update config. Body: `{ defaultModel?, providers? }` |
| POST | `/api/settings/test-key` | Validate API key format. Body: `{ provider, apiKey }` |
| POST | `/api/settings/probe-provider` | Live-probe a STORED provider key by id. Body: `{ provider }` → `{ configured, valid, verified, error? }` |
| GET | `/api/settings/permissions` | Read permission settings (YOLO mode, external gates) |
| PUT | `/api/settings/permissions` | Update permissions. Body: `{ yoloMode?, externalGates?, workspaceOverrides? }` |
| POST | `/api/settings/probe-provider` | Test a stored provider key with the provider. Body: `{ provider }` → `{ configured, valid, verified, error? }` |
| GET | `/api/settings/permissions` | Read the approval settings |
| PUT | `/api/settings/permissions` | Update the approval settings. Body: `{ defaultAutonomy?, externalGates?, workspaceOverrides? }` (`yoloMode` is still accepted) |
## Vault
@@ -120,7 +153,6 @@ The chat endpoint streams responses via Server-Sent Events (SSE). Events include
| GET | `/api/marketplace/search` | Search catalog. Query: `?query=text&type=skill&category=cat&limit=20&offset=0` |
| GET | `/api/marketplace/packs` | List all capability packs |
| GET | `/api/marketplace/packs/:slug` | Pack detail with packages |
| GET | `/api/marketplace/enterprise-packs` | Enterprise packs (requires KVARK) |
| POST | `/api/marketplace/install` | Install package. Body: `{ packageId, installPath?, settings?, force? }` |
| POST | `/api/marketplace/uninstall` | Uninstall package. Body: `{ packageId }` |
| GET | `/api/marketplace/installed` | List installed packages |
@@ -176,23 +208,16 @@ The chat endpoint streams responses via Server-Sent Events (SSE). Events include
| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/ingest` | Ingest files. Body: `{ files: [{ name, content (base64) }], workspaceId? }`. Max 15MB. |
| POST | `/api/ingest` | Ingest files. Body: `{ files: [{ name, content (base64) }], workspaceId? }`. Up to 10 MB per file; the request body is limited to 15 MB. |
Supported types: images (PNG, JPG, GIF, WebP, SVG), documents (PDF, DOCX, PPTX), spreadsheets (XLSX, CSV), text/code (50+ extensions), archives (ZIP).
## Import
| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/import/preview` | Preview import from ChatGPT or Claude export. Body: `{ data, source: "chatgpt"|"claude" }` |
| POST | `/api/import/commit` | Import and save to personal memory. Body: `{ data, source }` |
## Feedback
| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/feedback` | Record feedback. Body: `{ sessionId, messageIndex, rating: "up"|"down", reason?, detail? }` |
| GET | `/api/feedback/stats` | Improvement stats: positive rate, top issues, corrections, trend |
| POST | `/api/feedback` | Record thumbs up or down on a reply. Body: `{ sessionId, messageIndex, rating: "up"\|"down", reason?, detail? }` |
| GET | `/api/feedback/stats` | Feedback statistics |
## Notifications
@@ -206,19 +231,11 @@ Supported types: images (PNG, JPG, GIF, WebP, SVG), documents (PDF, DOCX, PPTX),
|--------|------|-------------|
| GET | `/api/audit/installs` | Recent install audit trail. Query: `?limit=20` |
## Team
## Built-in provider proxy
| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/team/connect` | Connect to team server. Body: `{ serverUrl, token }` |
| POST | `/api/team/disconnect` | Disconnect from team server |
| GET | `/api/team/status` | Current team connection status |
## Anthropic Proxy
| Method | Path | Description |
|--------|------|-------------|
| POST | `/v1/chat/completions` | OpenAI-compatible endpoint that translates to Anthropic API. Used by internal agent loop. |
| POST | `/v1/chat/completions` | OpenAI-compatible endpoint used by the agent loop and memory extraction. Translates Claude requests to Anthropic's Messages API and forwards other providers' models to their OpenAI-compatible APIs |
## Commands
@@ -226,17 +243,20 @@ Supported types: images (PNG, JPG, GIF, WebP, SVG), documents (PDF, DOCX, PPTX),
|--------|------|-------------|
| POST | `/api/commands/execute` | Execute a slash command. Body: `{ command, workspaceId, sessionId }` |
## SSE Streaming
## Chat stream events
The `/api/chat` endpoint uses Server-Sent Events for real-time streaming. Event types:
`POST /api/chat` answers with Server-Sent Events. The event names the chat route sends:
| Event | Description |
|-------|-------------|
| `message` | Agent text chunk |
| `tool_call` | Agent is calling a tool (shows tool name and input) |
| `tool_result` | Tool execution result |
| `approval_request` | Agent needs approval before proceeding |
| `approval_resolved` | Approval was granted or denied |
| `memory_saved` | A memory frame was auto-saved |
| `done` | Agent turn complete |
| `error` | Error occurred |
| `token` | A chunk of the agent's text |
| `step` | A progress step of the turn (recall, thinking, tool use and so on) |
| `tool` | The agent calls a tool |
| `tool_result` | The result of a tool call |
| `approval_required` | A tool call waits for the user's approval |
| `approval_held` | A tool call was held for later approval |
| `model_switch` | The turn moved to another model |
| `file_created` | A tool created a file |
| `notification` | A notification for the user |
| `done` | The turn is complete |
| `error` | The turn failed |

View File

@@ -1,27 +1,41 @@
# Commands Reference
# Slash commands
Waggle provides 14 slash commands for quick actions. Type `/` in any workspace to see autocomplete suggestions.
Type `/` in a chat to see the commands with autocomplete. A command is `/name` followed by its
arguments; aliases work the same way as the name. Many commands hand a prepared request to the
agent, which then uses its normal tools and approvals.
## Command List
The commands are defined in `packages/agent/src/commands/` (`workflow-commands.ts` and
`marketplace-commands.ts`).
| Command | Aliases | Args | Description |
|---------|---------|------|-------------|
| `/catchup` | `/catch-up`, `/recap` | -- | Workspace restart summary. Shows recent activity, memories, and state so you can get up to speed instantly. |
| `/now` | `/current`, `/where` | -- | Current workspace state. What is happening right now -- active threads, recent changes, open items. |
| `/research` | `/investigate` | `<topic>` | Launch multi-agent research. Spawns the `research-team` workflow with multiple agents investigating the topic in parallel. |
| `/draft` | `/write` | `<type> [topic]` | Start a drafting workflow. Supports any document type: blog, report, email, proposal, memo. Uses the `review-pair` workflow for drafts with review. |
| `/decide` | `/decision`, `/weigh` | `<question>` | Create a structured decision matrix with options, pros/cons, risk, and effort columns. Provides an evaluation framework for systematic decision-making. |
| `/review` | `/critique`, `/check` | -- | Review the last output with a critic agent. Spawns the `review-pair` workflow to analyze the most recent response for accuracy and completeness. |
| `/spawn` | `/agent`, `/summon` | `<role> [task]` | Spawn a specialist sub-agent. Available roles: `researcher`, `writer`, `coder`, `analyst`, `reviewer`, `planner`. |
| `/skills` | `/abilities`, `/tools` | -- | Show active skills in this workspace. Lists all loaded skill files with their names. |
| `/status` | `/report`, `/progress` | -- | Project status summary. Shows workspace state including tasks, progress, blockers, and recent activity. |
| `/memory` | `/remember`, `/recall` | `[query]` | Search workspace memory. Without arguments, shows usage help. With a query, searches both personal and workspace minds. |
| `/plan` | `/decompose`, `/break-down` | `<goal>` | Break a goal into actionable tasks. Uses the `plan-execute` workflow to create a structured task list with dependencies. |
| `/focus` | `/narrow`, `/scope` | `<topic>` | Narrow agent focus to a specific topic. Subsequent responses prioritize this context. Use again to change focus. |
| `/marketplace` | `/mp`, `/market` | `<subcommand> [args]` | Marketplace operations. Sub-commands: `search`, `install`, `packs`, `installed`, `sync`. See details below. |
| `/help` | `/commands`, `/?` | -- | List all available commands with descriptions. |
## Command list
## Detailed Examples
| Command | Aliases | Arguments | What it does |
|---|---|---|---|
| `/catchup` | `/catch-up`, `/recap` | | Summary of where the workspace stands: recent activity, memories and state |
| `/now` | `/current`, `/where` | | What is happening in the workspace right now |
| `/status` | `/report`, `/progress` | | Project status: tasks, progress, blockers and recent activity |
| `/research` | `/investigate` | `<topic>` | Runs the `research-team` workflow on a topic |
| `/draft` | `/write` | `<type> [topic]` | Drafts a document (memo, report, email, proposal…) with a review cycle |
| `/decide` | `/decision`, `/weigh` | `<question>` | Builds a decision matrix with options, pros, cons, risk and effort |
| `/review` | `/critique`, `/check` | | Has a critic agent review the last answer |
| `/plan` | `/decompose`, `/break-down` | `<goal>` | Breaks a goal into a task list |
| `/spawn` | `/agent`, `/summon` | `<role> [task]` | Starts a specialist sub-agent: `researcher`, `writer`, `coder`, `analyst`, `reviewer` or `planner` |
| `/focus` | `/narrow`, `/scope` | `<topic>` | Narrows the agent's focus to a topic until you change it |
| `/memory` | `/remember`, `/recall` | `<query>` | Searches personal and workspace memory |
| `/search-all` | `/find-all` | `<query>` | Searches personal memory and all workspaces |
| `/skills` | `/abilities`, `/tools` | | Lists the active skills |
| `/plugins` | | | Lists installed plugins and capabilities |
| `/connectors` | `/integrations`, `/connections` | | Lists connected services and their status |
| `/marketplace` | `/mp`, `/market` | `<subcommand> [args]` | Marketplace: `search`, `install`, `packs`, `installed`, `sync` |
| `/workflow` | `/wf` | `<create\|list\|run> [args]` | Creates, lists or runs multi-agent workflows |
| `/export` | | `<memories\|sessions\|all\|workspace>` | Exports workspace data with the agent's help |
| `/import` | | `<source>` | Reads a file, URL or pasted text and saves what matters as workspace memories |
| `/cli` | `/cli-tools` | `[allow\|deny\|discover] [name]` | Shows or changes which command-line programs the agent may run |
| `/pr` | `/pull-request`, `/merge-request` | `<title>` | Creates a pull request from the current branch of the workspace's repository |
| `/settings` | | | Shows the current workspace and agent settings |
| `/help` | `/commands`, `/?` | | Lists all commands |
## Examples
### /catchup
@@ -29,72 +43,55 @@ Waggle provides 14 slash commands for quick actions. Type `/` in any workspace t
/catchup
```
Output: A structured briefing with what this workspace is about, recent sessions, decisions, memory count, and suggested next steps. Use this every time you return to a workspace after a break.
A briefing for when you come back to a workspace: what it is about, recent sessions, decisions
and suggested next steps.
### /research
```
/research quantum computing applications in drug discovery
/research applications of quantum computing in drug discovery
```
Spawns the `research-team` multi-agent workflow:
1. A researcher agent investigates the topic
2. Findings are synthesized and cross-referenced
3. Results are presented with citations and confidence levels
Runs the `research-team` workflow: research agents investigate the topic and their findings are
combined into one answer.
### /draft
```
/draft blog post about AI safety best practices
/draft report quarterly metrics for Q1 2026
/draft email to client about project timeline changes
/draft report quarterly metrics for Q1
/draft email to the client about the timeline change
```
The agent determines the document type from the first word and adapts its formatting accordingly. If the `review-pair` workflow is available, the draft goes through a review cycle.
The first word is the document type.
### /decide
```
/decide Should we use PostgreSQL or MongoDB for the new project?
/decide Should we use PostgreSQL or MongoDB for the new service?
```
Produces a decision matrix template:
| Option | Pros | Cons | Risk | Effort |
|--------|------|------|------|--------|
| PostgreSQL | | | | |
| MongoDB | | | | |
Ask the agent to fill it in: "Please analyze this decision for me."
Produces a matrix with a row per option and columns for pros, cons, risk and effort. Ask the
agent to fill it in.
### /spawn
```
/spawn researcher Find recent papers on transformer architectures
/spawn coder Implement a rate limiter middleware
/spawn analyst Compare our metrics against industry benchmarks
/spawn researcher Find recent papers on retrieval-augmented generation
/spawn coder Write a rate limiter middleware
```
The sub-agent runs with the specified role and task, then returns its results to the main conversation.
The sub-agent works on the task and returns its result to the conversation.
### /memory
### /memory and /search-all
```
/memory architecture decisions
/memory last meeting notes
/memory project goals
/search-all project deadlines
```
Searches both personal and workspace memory using FTS5 full-text search. Results include content, importance level, and dates.
### /plan
```
/plan Build a user dashboard with analytics
/plan Migrate the database to PostgreSQL
```
Creates a structured plan with ordered steps, dependencies, and success criteria. The agent can then execute steps sequentially.
`/memory` searches personal memory and the current workspace's memory. `/search-all` also
searches every other workspace and groups the results by workspace. See
[memory.md](../memory.md).
### /marketplace
@@ -106,33 +103,32 @@ Creates a structured plan with ordered steps, dependencies, and success criteria
/marketplace sync
```
| Sub-command | Description |
|-------------|-------------|
| `search <query>` | Search the marketplace catalog by keyword. Returns up to 10 results with name, type, category, and description. |
| `install <name>` | Install a package by name. Searches for the best match, runs SecurityGate scan, and installs. |
| `packs` | List all capability packs grouped by priority tier. |
| `installed` | Show all currently installed packages with status and install date. |
| `sync` | Trigger a manual sync from all configured marketplace sources. Reports added/updated counts. |
| Subcommand | What it does |
|---|---|
| `search <query>` | Searches the catalog, up to 10 results |
| `install <name>` | Finds the best match, runs the security scan and installs it |
| `packs` | Lists the capability packs |
| `installed` | Lists installed packages |
| `sync` | Refreshes the catalog from its sources |
## Command Parsing
### /workflow
Commands follow the format `/commandName arg1 arg2 ...`. The parser:
```
/workflow list
/workflow run research-team
/workflow create Research competitors, summarize findings and draft an executive brief
```
1. Strips the leading `/`
2. Splits on the first space to get the command name and arguments
3. Resolves aliases (e.g., `/mp` resolves to `/marketplace`)
4. Executes the handler with the argument string and workspace context
## Adding a command
Partial matching is supported for autocomplete but not for execution. You must type the full command name or alias.
Commands are `CommandDefinition` objects registered with the `CommandRegistry`
(`packages/agent/src/commands/command-registry.ts`):
## Adding Custom Commands
- `name`: the command name, lowercase, without `/`;
- `aliases`: other names, also without `/`;
- `description` and `usage`: shown in `/help`;
- `handler(args, context)`: returns the reply text. A reply that starts with
`AGENT_LOOP_REROUTE_PREFIX` is sent to the agent as a request instead of shown directly.
Commands are registered in the `CommandRegistry`. To add a custom command, create a `CommandDefinition` with:
- `name` -- the primary command name (lowercase)
- `aliases` -- alternative names
- `description` -- shown in `/help` output
- `usage` -- usage string with argument placeholders
- `handler` -- async function receiving `(args: string, context: CommandContext)`
See `packages/agent/src/commands/` for implementation examples.
Register a new command in `registerWorkflowCommands` or in a registration function of your
own, called from the sidecar (`packages/server/src/local/index.ts`).