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](references/telegram-ui.md) for full button layouts, callback routing, and platform fallbacks. ## Quick Reference | Command | Action | |---------|--------| | `workplace init [path]` | Initialize workplace (scan existing or set up new) | | `workplace list` | List all workplaces (inline buttons to switch) | | `workplace switch <name\|uuid>` | Switch active workplace | | `workplace scan [path]` | Discover .git workplaces in subdirectories | | `workplace link <path>` | Link a related workplace | | `workplace unlink <path\|uuid>` | Remove a linked workplace | | `workplace status` | Current workplace info + agent status | | `workplace agents` | List agents in current workplace | | `workplace agent start <name>` | Start an agent (runs as sub-agent) | | `workplace agent stop <name>` | Stop a running agent | | `workplace kernel start` | Start persistent kernel agent | | `workplace kernel stop` | Stop kernel agent | | `workplace export [zip\|json]` | Export workplace config | | `workplace import <file>` | Import workplace from export | | `workplace load <path\|name\|uuid>` | Load/open a registered workplace for quick access | | `workplace unload <name\|uuid>` | Unload a workplace from the loaded set | | `workplace loaded` | List all currently loaded workplaces | | `workplace delete <name\|uuid>` | Remove from registry | | `workplace deploy <env>` | Show/run deploy instructions | | `workplace sync <ide>` | Generate context for cursor/claude/opencode/all | | `workplace sessions` | List chat sessions for current workplace | | `workplace session new [label]` | Create a new chat session | | `workplace session continue [label]` | Resume a saved session | | `workplace session delete <label>` | Delete a saved session | | `workplace session rename <old> <new>` | Rename a session | ## 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. ```json [ { "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](references/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](references/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](references/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](references/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`. ```bash # 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](references/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](references/ide-sync.md) for implementation details. ## Scripts | Script | Purpose | |--------|---------| | `scripts/init_workplace.sh` | Initialize .workplace/ in a directory | | `scripts/scan_workplaces.sh` | Find .git workplaces under a path | | `scripts/loaded_workplaces.sh` | Manage loaded/open workplaces (list/load/unload/status) | | `scripts/build.sh` | Build Rust server for current platform | ## 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](references/commands.md) for full command reference with examples.