Sample data in tests, prompts and UI placeholders uses Alex Morgan instead of the maintainer's name; decision attributions say "owner". Personal details in two test fixtures are replaced. Local paths (D:/Projects/...) and paths into the maintainer's planning repository are reworded. Clone and install URLs in CONTRIBUTING.md and the getting started guide use placeholders until the public repository location is decided (Q9). The Benchmarks page no longer names the maintainer's hive-mind repository, and the upstream fixes log names the main Waggle repository instead of an internal git host.
212 lines
7.6 KiB
Markdown
212 lines
7.6 KiB
Markdown
# Getting Started with Waggle
|
|
|
|
This guide walks you through installing Waggle, configuring your API key, creating your first workspace, having your first conversation, and understanding how memory works.
|
|
|
|
## Prerequisites
|
|
|
|
- **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)
|
|
|
|
## Installation
|
|
|
|
### Option 1: One-line self-host (Linux / macOS)
|
|
|
|
Best for a VPS or homelab, where you want a headless server rather than the desktop app:
|
|
|
|
```bash
|
|
curl -fsSL <repository-raw-url>/main/install.sh | bash # the public repository location is not decided yet
|
|
```
|
|
|
|
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**.
|
|
|
|
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.
|
|
|
|
### Option 2: Desktop App (Recommended)
|
|
|
|
Download the latest release for your platform from the repository's Releases page (the public repository location is not decided yet).
|
|
|
|
**Windows**: Run the `.msi` installer. Waggle appears in your Start menu.
|
|
|
|
**macOS**: Open the `.dmg` and drag Waggle to Applications.
|
|
|
|
The desktop app bundles a Node.js sidecar that runs the local server automatically.
|
|
|
|
### 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"
|
|
- "What can you do in this workspace?"
|
|
|
|
The agent responds with streaming output. You will see:
|
|
|
|
- **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)
|
|
|
|
### Try a Slash Command
|
|
|
|
Type `/catchup` to get a workspace restart summary. Type `/help` to see all 14 commands.
|
|
|
|
### Upload a File
|
|
|
|
Click the paperclip icon or drag a file into the chat. Waggle supports:
|
|
|
|
- **Documents**: PDF, DOCX, PPTX
|
|
- **Spreadsheets**: XLSX, CSV
|
|
- **Images**: PNG, JPG, GIF, WebP, SVG
|
|
- **Code**: Any text-based source file
|
|
- **Archives**: ZIP (lists contents)
|
|
|
|
Files are ingested into workspace memory and available to the agent.
|
|
|
|
## Step 4: Understanding Memory
|
|
|
|
Memory is a core product primitive, not a side feature. Two memory layers work together:
|
|
|
|
### Personal Mind (`~/.waggle/default.mind`)
|
|
|
|
Your personal knowledge base. Facts about you, your preferences, recurring context. Shared across all workspaces.
|
|
|
|
### Workspace Mind (`~/.waggle/workspaces/{id}/workspace.mind`)
|
|
|
|
Project-specific memory. Decisions, research findings, architectural choices, meeting notes. Scoped to one workspace.
|
|
|
|
### How Memory Works
|
|
|
|
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.
|
|
|
|
### Memory Frames
|
|
|
|
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
|
|
|
|
## 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
|
|
|
|
| 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 |
|