oleg.m/waggle-os
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

moving
Some checks failed
Installer Smoke / installer-smoke (push) Has been cancelled
Details

Browse Source
This commit is contained in:
Oleg Maslov
2026-09-02 10:10:29 +02:00
commit 0c3e2ead3b
3841 changed files with 970576 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

211
docs/guides/capabilities.md Normal file
View File

@@ -0,0 +1,211 @@
# Capabilities
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.
## Capability Types
| 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` |
## Built-in Capability Packs
Waggle ships with 5 curated packs. Each pack bundles several skills that work together.
### Research Workflow
Skills for investigation and synthesis. Includes `research-synthesis`, `explain-concept`, and the `research-team` multi-agent workflow.
### Writing Suite
Skills for document creation and editing. Includes `draft-memo`, `compare-docs`, and `extract-actions`.
### 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/`:
```markdown
# My Custom Skill
Instructions for the agent when this skill is active.
## When to Use
- Trigger conditions
## How to Respond
- Response format guidelines
- Quality standards
```
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."}'
```
## Marketplace
The marketplace catalog contains 120+ packages across skills, plugins, and MCP servers from curated sources.
### Searching
```bash
# Search by keyword
curl "http://localhost:3333/api/marketplace/search?query=research&limit=10"
# Filter by type
curl "http://localhost:3333/api/marketplace/search?type=skill&category=analysis"
```
Or use the `/marketplace search <query>` slash command in any workspace.
### 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
```
## Plugins
Plugins are structured packages with manifests that can add tools and extend agent behavior.
### Installing a Plugin
```bash
curl -X POST http://localhost:3333/api/plugins/install \
-H "Content-Type: application/json" \
-d '{"sourceDir": "/path/to/my-plugin"}'
```
### Enabling / Disabling
```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
```

195
docs/guides/connectors.md Normal file
View File

@@ -0,0 +1,195 @@
# Connectors
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.
## Vault Setup
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.
### Adding a Secret to the Vault
**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**
**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"}'
```
### Suggested Keys
The vault suggests common API key names that are not yet configured:
- `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
## Native Connectors
Waggle registers 29 native connectors at startup. Each connector has a defined auth type and generates agent tools when credentials are available.
| # | 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 |
## Connecting a Service
### From the UI
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**
The connector status changes from "Disconnected" to "Connected".
### From the API
```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"}'
# 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"}'
```
### Disconnecting
```bash
curl -X POST http://localhost:3333/api/connectors/github/disconnect
```
This removes the credentials from the vault and any associated metadata.
## Checking Connector Health
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.

211
docs/guides/getting-started.md Normal file
View File

@@ -0,0 +1,211 @@
# 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 https://raw.githubusercontent.com/marolinik/waggle-os/main/install.sh | bash
```
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 [GitHub Releases](https://github.com/marolinik/waggle/releases).
**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 https://github.com/marolinik/waggle.git
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 |

202
docs/guides/team-mode.md Normal file
View File

@@ -0,0 +1,202 @@
# Team Mode
Waggle Team Mode lets multiple users share workspaces, assign tasks, see who is online, and govern agent capabilities through an admin dashboard. It runs as a separate server backed by PostgreSQL and Redis.
## Architecture
Team Mode adds a **team server** alongside the local Waggle server:
- **Local server** (localhost:3333) -- your personal agent, memory, and workspace management
- **Team server** (your-server:3334) -- shared workspaces, presence, tasks, capability governance
The desktop app connects to both. Local operations stay fast; team operations sync through the team server.
## Docker Setup
The simplest way to run the team server is with Docker Compose.
### Prerequisites
- Docker and Docker Compose installed
- An Anthropic (or other LLM) API key
### Start the Services
```bash
cd waggle-poc
# Set your API key
export ANTHROPIC_API_KEY=sk-ant-your-key-here
# Start PostgreSQL, Redis, and LiteLLM
docker compose up -d
```
This starts:
- **PostgreSQL** on port 5434 (user: `waggle`, password: `waggle_dev`, database: `waggle`)
- **Redis** on port 6381
- **LiteLLM** on port 4000 (model proxy)
### Start the Team Server
```bash
cd packages/server
DATABASE_URL=postgresql://waggle:waggle_dev@localhost:5434/waggle \
REDIS_URL=redis://localhost:6381 \
npx tsx src/index.ts
```
The team server starts on port 3334 by default.
## Cloud Deployment (Render)
For a hosted team server:
1. Create a new **Web Service** on Render from the waggle repository
2. Set the **Build Command**: `npm install && npm run build`
3. Set the **Start Command**: `cd packages/server && node dist/index.js`
4. Add environment variables:
- `DATABASE_URL` -- your PostgreSQL connection string
- `REDIS_URL` -- your Redis connection string
- `CLERK_SECRET_KEY` -- for authentication (Clerk)
- `CLERK_PUBLISHABLE_KEY` -- for client auth
5. Deploy
## Connecting to a Team Server
### From the Desktop App
1. Go to **Settings** > **Team**
2. Enter the server URL (e.g., `https://your-team.render.com`)
3. Enter your authentication token
4. Click **Connect**
Waggle validates the connection by hitting the team server's `/health` endpoint.
### From the API
```bash
curl -X POST http://localhost:3333/api/team/connect \
-H "Content-Type: application/json" \
-d '{"serverUrl": "https://your-team.render.com", "token": "your-auth-token"}'
```
## Shared Workspaces
Team workspaces are created on the team server and synced to each member's local Waggle instance.
### Creating a Team Workspace
1. Connect to a team server (see above)
2. Press **Ctrl+N** to create a new workspace
3. Enable the **Team** toggle
4. Select the team and your role
5. Click **Create**
### Memory Sync
Team workspaces sync memory frames between members:
- When one member saves a decision, it appears in everyone's workspace mind
- Personal mind remains private -- only workspace mind is shared
- Author attribution shows who contributed each memory
## Task Board
Each team workspace has a task board for lightweight project management.
### Creating Tasks
```bash
curl -X POST http://localhost:3333/api/workspaces/{id}/tasks \
-H "Content-Type: application/json" \
-d '{"title": "Review Q1 metrics", "assigneeName": "Alice"}'
```
Or ask the agent: "Create a task for Alice to review Q1 metrics."
### Task States
Tasks move through three states: `open` -> `in_progress` -> `done`.
### Filtering
```bash
# Get all open tasks
curl "http://localhost:3333/api/workspaces/{id}/tasks?status=open"
```
## WebSocket Presence
Team Mode uses WebSocket push with a 60-second polling fallback for presence:
- See who is online in a shared workspace
- See who is actively typing
- Get real-time notifications for task assignments and team messages
## Admin Dashboard
Team admins access the admin dashboard at the team server URL. It provides:
### Members Management
- View all team members and their roles (owner, admin, member, viewer)
- Invite new members
- Change roles
### Capability Governance
Two-layer governance model:
**Layer 1: Role Policies**
Define which capabilities each role can use. Example: viewers can only use read tools, members can use write tools, admins can use all tools.
**Layer 2: Per-Capability Overrides**
Fine-grained overrides for specific capabilities. Example: allow a specific member to use `send_email` even if their role policy doesn't include it.
### Approval Request Queue
When a member tries to use a capability they do not have:
1. The agent tool `request_team_capability` creates a request
2. The request appears in the admin queue
3. An admin approves or rejects it
4. The member is notified
### Waggle Dance Messages
View inter-agent communication in team workflows. The Waggle Dance protocol lets agents coordinate tasks, share findings, and report progress.
## Capability Governance API
```bash
# List role policies
curl http://localhost:3333/api/team/governance/policies
# Create a policy
curl -X POST http://localhost:3333/api/team/governance/policies \
-H "Content-Type: application/json" \
-d '{"role": "member", "capabilities": ["read_file", "search_files", "search_memory"]}'
# List pending capability requests
curl http://localhost:3333/api/team/governance/requests?status=pending
# Approve a request
curl -X PATCH http://localhost:3333/api/team/governance/requests/{id} \
-H "Content-Type: application/json" \
-d '{"decision": "approved"}'
```
## Disconnecting
```bash
curl -X POST http://localhost:3333/api/team/disconnect
```
This removes the team server configuration but preserves any local copies of team workspace data.
## Team Server Status
```bash
# Check connection status
curl http://localhost:3333/api/team/status
```
Returns the server URL, connection state, user ID, and display name.

207
docs/guides/troubleshooting.md Normal file
View File

@@ -0,0 +1,207 @@
# Troubleshooting
Common issues, error codes, and solutions.
## API Key Issues
### "No API key configured"
The agent cannot run without an LLM provider key.
**Fix:** Go to Settings > Models and add your Anthropic key (starts with `sk-ant-`). Or edit `~/.waggle/config.json` directly:
```json
{
"defaultModel": "claude-sonnet-4-6",
"providers": {
"anthropic": {
"apiKey": "sk-ant-your-key-here",
"models": ["claude-sonnet-4-6"]
}
}
}
```
### "API key is too short" / "must start with sk-ant-"
The key format validation failed.
**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.
### Key works in API but not in Waggle
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:
```bash
docker compose up litellm
```
Then set your LiteLLM URL in Settings > Advanced.
## Server Issues
### Server won't start
**Check port availability:**
```bash
# Is port 3333 already in use?
lsof -i :3333 # macOS/Linux
netstat -ano | findstr 3333 # Windows
```
**Fix:** Kill the existing process or change the port:
```bash
PORT=3334 npx tsx src/local/start.ts
```
### "SQLITE_CANTOPEN" error
The `.mind` database file cannot be opened.
**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
### Server crashes with "out of memory"
Large workspace minds or many concurrent operations can exhaust memory.
**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`
## Memory Issues
### Memory not saving
Memories are saved automatically during conversations when the agent determines something is important.
**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]"
### Search returns no results
FTS5 search requires at least 3 characters.
**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
### Memory from another workspace showing up
This is expected behavior. The agent searches both personal and workspace minds. Personal mind memories are shared across all workspaces.
**Fix:** If a memory should be workspace-specific, it should have been saved to the workspace mind (this happens automatically for project-specific context).
## Connector Issues
### "Vault not available"
The encrypted vault database failed to initialize.
**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
### Connector shows "disconnected" after restart
Credentials persist in the vault across restarts. If a connector shows disconnected:
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
### "Connector not found" (404)
Connector IDs are lowercase. Use `GET /api/connectors` to see all registered IDs.
### Approval gate stuck
If an approval card appears but you cannot click Approve/Deny:
**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.

149
docs/guides/workspaces.md Normal file
View File

@@ -0,0 +1,149 @@
# 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.
## Creating a Workspace
Press **Ctrl+N** or click **New Workspace** in the sidebar.
| 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 |
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.
## Workspace Types
### Personal Workspaces
Created locally, stored on your machine. Memory lives in `~/.waggle/workspaces/{id}/workspace.mind`. Only you can access them.
### Team Workspaces
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.
## Personas
Personas are specialized agent configurations. Assigning a persona to a workspace tunes the agent's behavior without changing the core capabilities.
| 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 | -- |
### Changing Persona
Open workspace settings (gear icon on the workspace home) and select a different persona. The change takes effect on the next message.
### Persona Tool Presets
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.
## Directory Association
Linking a workspace to a directory on disk enables:
- `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
To link a directory, set it during workspace creation or update it in workspace settings.
## 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.