Workplace

Workplace Skill

Manage multiple project workplaces with per-workspace agents, isolated memory, and Swarm-style agent orchestration.

/workplace Command (Telegram / Slash)

Hierarchical navigation with parent → child drill-down.

• /workplace or /workplace list → Show top-level view: parent workspaces and standalone workplaces as buttons. Parents show (N) child count. Current workspace marked with ✓.
• Click a parent button → Drill into children. Shows child buttons + "Use parent" + "← Back".
• /workplace <name> → If standalone or child, switch directly. If parent with children, show drill-in.
• /workplace parent:child → Direct switch using colon syntax (e.g. log-stream:logstream).
• /workplace status → Current workspace card with parent, linked, agents, deploy envs.
• /workplace agents → Agent list with start/stop buttons.

Colon Syntax

/workplace log-stream:logstream resolves parent by name, then finds child under that parent. Supports quick switching without navigating menus.

Context Switching

When the user switches workplaces (via button click, name, or colon syntax):

1. Update ~/.openclaw/workspace/.workplaces/current.json with the selected UUID and path
2. Update lastActive in registry.json
3. Load the new workspace's .workplace/config.json for context
4. Send confirmation: name, path, parent (if any), linked workplaces, agent list
5. Check sessions.json for the target workplace UUID:
   • Has sessions → show session buttons ("Continue: {label}" + "New chat session")
   • No sessions → auto-create a new session, confirm in the switch message
6. Subsequent messages in the session should be aware of the active workspace context

Read current.json at the start of any workplace operation to know which workspace is active.

See telegram-ui.md for full button layouts, callback routing, and platform fallbacks.

Quick Reference

Architecture

Registry

Central registry at ~/.openclaw/workspace/.workplaces/:

• registry.json — all known workplaces with UUID, path, hostname, links
• current.json — currently active workplace
• loaded.json — workplaces currently "open/loaded" for quick access and cross-workspace ops

Per-Workplace Structure

Each project gets a .workplace/ directory:

.workplace/
├── config.json          # UUID, name, path, hostname, linked, parent
├── agents/*.md          # Agent role definitions (kernel.md always present)
├── memory/              # Isolated daily logs (YYYY-MM-DD.md)
├── skills/              # Workplace-specific skills (user-managed via git)
├── chat.md              # Inter-agent communication
├── structure.json       # Auto-scanned file tree
├── full-tree.md         # Full tree with parent + linked workplaces (by hostname)
├── process-status.json  # Agent runtime states and errors
└── deploy/              # Deployment docs: dev.md, main.md, pre.md

Loaded Workplaces

loaded.json tracks which workplaces are currently "open". This is distinct from the registry (all known workplaces) and current (the one active workplace). Loaded workplaces are the set you're actively working with — useful for cross-workspace agent orchestration, quick switching, and context awareness.

[
  {
    "uuid": "74cdd6fd-...",
    "name": "log-stream",
    "path": "/Users/dev/opensource/log-stream",
    "loadedAt": "2026-02-17T22:05:00Z",
    "source": "manual"
  }
]

Fields:

• uuid — workplace UUID (matches registry)
• name — display name
• path — absolute filesystem path
• loadedAt — ISO timestamp when loaded
• source — how it was loaded (manual, auto, linked)

Manage via scripts/loaded_workplaces.sh (list/load/unload/status).

Session Management

Per-workplace chat sessions are tracked in ~/.openclaw/workspace/.workplaces/sessions.json. Each workplace UUID maps to an array of sessions (sessionId, label, timestamps) and an activeSession pointer.

When switching workplaces:

1. If the target has saved sessions → show "Continue" buttons + "New chat" button
2. If no saved sessions → auto-create a new session
3. Session transcripts are stored as OpenClaw .jsonl files

On "Continue": set activeSession, load recent context from transcript. On "New chat": generate a new session entry, prompt for optional label.

See telegram-ui.md for full button layouts and callback routing.

Workplace Detection

• Any directory with .git/ is a potential workplace
• Submodules included as nested workplaces
• Parent workplace auto-detected from parent directories
• Manual linking via workplace link

Workflows

Initialize a Workplace

1. Run scripts/init_workplace.sh <path> [--name <name>] [--desc <desc>]
2. For existing projects: scan file structure, read *.md files, analyze project type, suggest agents
3. For empty folders: ask project name, description, language/framework, roles needed
4. Creates .workplace/ structure, registers in central registry, sets as current
5. See init-guide.md for full flow details

Agent System

Agents are defined as .md files in .workplace/agents/ with YAML frontmatter (name, role, triggers, handoff_to). Run agents via sessions_spawn with system prompts built from their definitions + workplace context.

• See agent-system.md for agent creation, Swarm handoff, and runtime details

Inter-Agent Communication

Agents communicate via chat.md using a structured message protocol. The Rust file-watcher server monitors changes and outputs parsed messages as JSON lines.

• See chat-protocol.md for message format spec

Rust File-Watcher Server

Binary at assets/bin/workplace-server-{os}-{arch}. Build from source with scripts/build.sh.

# Start server for a workplace
workplace-server /path/to/project

# Server outputs JSON lines to stdout for each new chat.md message
{"timestamp":"...","sender":"coder","recipient":"reviewer","broadcast":[],"message":"...","line_number":1}

Export/Import

• ZIP: Full .workplace/ folder (memory excluded by default)
• JSON: Config + agent definitions + deploy docs as portable manifest
• Import generates a new UUID to avoid collisions

Chat UI (Telegram / Discord)

On platforms with inline buttons, workplace list shows a clickable switcher. workplace agents shows start/stop buttons per agent. workplace deploy shows environment buttons.

See telegram-ui.md for message formats, button components, and callback handling.

Fallback: numbered text lists on platforms without button support (WhatsApp, Signal).

IDE Integration

Sync workplace context to external coding tools:

• Cursor → .cursor/rules/workplace.mdc (MDC with frontmatter)
• Claude Code → CLAUDE.md (markdown, marker-based updates)
• OpenCode → opencode.jsonc instructions field

Run workplace sync all to update all detected IDEs, or target one: workplace sync cursor.

See ide-sync.md for implementation details.

Scripts

Supermemory Integration

Each workplace uses its UUID as containerTag for supermemory operations:

• Kernel agent saves structure summaries and project facts
• All workplace memories are isolated by containerTag
• Enables cross-session project state awareness

Command Details

See commands.md for full command reference with examples.