waggle-os/docs/guides/workspaces.md

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.