Team Projects 📋

Multi-agent project management for OpenClaw. Run agent teams that plan, assign, execute, and track work together. Includes a Control UI plugin tab for visual project tracking and a right-edge Team Chat drawer for live agent activity.

Overview

This skill enables a coordinator agent to manage projects across multiple specialist agents:

CODEBLOCK0

Each agent works independently with their own tools and workspace. The coordinator tracks progress, manages dependencies, and advances the project.

UI Components

1. Projects Tab (sidebar)

A full project dashboard registered as a plugin tab in the Control sidebar under the "Control" group. Shows project cards, task boards with phase sections, team overview, and progress stats.

2. Team Chat Drawer (right edge)

A slide-out panel accessible from a vertical "Team" tab fixed to the right edge of the screen. Shows:

• - Live agent activity feed (sub-agent sessions, messages)
• Project progress bar
• Task overview (collapsible)
• Quick message input to send commands

Installation

Step 1: Config Prerequisites

Add to openclaw.json:

CODEBLOCK1

Add subagents.allowAgents to the coordinator agent's list entry (NOT on agents.defaults):

CODEBLOCK2

⚠️ Critical: allowAgents must be on the agent's own entry in agents.list. Setting it on agents.defaults.subagents does NOT work. The code reads resolveAgentConfig(cfg, requesterAgentId)?.subagents?.allowAgents which resolves the per-agent config, not defaults.

Step 2: Gateway Plugin Installation (for Projects tab)

The Projects tab requires installing a gateway plugin. This involves 4 registration points in the OpenClaw source:

2a. Plugin SDK entry

Create src/plugin-sdk/team-projects.ts:

CODEBLOCK3

2b. Plugin extension

Create extensions/team-projects/openclaw.plugin.json:

CODEBLOCK4

Create extensions/team-projects/index.ts — see gateway-plugin/index.ts.

2c. Register in build pipeline (4 files)

tsdown.config.ts — Add "team-projects" to the pluginSdkEntrypoints array.

src/plugins/loader.ts — Add to the pluginSdkScopedAliasEntries array:
CODEBLOCK5

scripts/write-plugin-sdk-entry-dts.ts — Add "team-projects" to the entrypoints array.

package.json — Add to the exports map:
CODEBLOCK6

2d. Enable in config

CODEBLOCK7

Step 3: UI View Installation

3a. Team Projects view

Copy gateway-plugin/team-projects-view.ts to ui/src/ui/views/team-projects.ts.

3b. Team Chat Drawer

Copy gateway-plugin/team-chat-drawer.ts to ui/src/ui/views/team-chat-drawer.ts.

⚠️ Critical: No Shadow DOM — The OpenClaw app uses createRenderRoot() { return this; }, so Lit css tagged templates are NOT applied. All styles must be embedded as inline <style> tags in the rendered HTML. The team-chat-drawer uses an inline <style> block inside renderTeamChatEdgeTab() so styles are present even when the drawer is closed.

3c. Wire into app-render.ts

See gateway-plugin/app-render-patch.ts for the integration points:

1. 1. Import renderTeamChatDrawer and renderTeamChatEdgeTab from INLINECODE31
2. Before </main>, add INLINECODE33
3. After </main>, add the edge tab and drawer renders
4. Add the renderPluginTabContent() function

3d. Wire into app-gateway.ts

See gateway-plugin/app-gateway-patch.ts for the integration points:

1. 1. Import uiPluginRegistry from INLINECODE38
2. Import renderTeamProjects from INLINECODE40
3. In onHello, after applySnapshot(), call INLINECODE43
4. Add the registerTeamProjectsPlugin() function

3e. Add view state fields

In ui/src/ui/app-view-state.ts, add to AppViewState:

CODEBLOCK8

In ui/src/ui/app-settings.ts, add teamChatOpen?: boolean to SettingsHost type, and add defensive cleanup in applyTabSelection():

CODEBLOCK9

Step 4: Build & Restart

CODEBLOCK10

Hard-refresh the browser (Ctrl+Shift+R) to load the new UI assets.

Usage

Creating a Project

Tell the coordinator agent what you want to build. It will:

1. 1. Create the project with appropriate phases
2. Break down work into tasks
3. Assign tasks to agents based on capabilities
4. Dispatch ready tasks

Example prompt:

"Create a team project to redesign our company website. @researcher should analyze competitors, @writer should draft copy, and @coder should build it in React. Priority: launch in 2 weeks."

The Coordinator's Workflow

The coordinator uses CLI tools to manage the project board:

CODEBLOCK11

Dispatching Tasks

The orchestrator identifies ready tasks (dependencies met, not yet dispatched):

CODEBLOCK12

Then dispatch via OpenClaw's native sessions_spawn:

CODEBLOCK13

Agent Communication

Agents can communicate using @-mentions:

• - @agentId — Direct message to an agent (routed via sessions_send)
• @all / @team — Broadcast to all project agents
• #taskid — Reference a task
• TASKCOMPLETE: #taskid — Signal task completion
• TASKBLOCKED: #task_id — Signal a blocker

Tracking Progress

CODEBLOCK14

Updating Tasks

CODEBLOCK15

Data Model

Project

CODEBLOCK16

Storage

• - Projects: INLINECODE53
• Chat logs: INLINECODE54
• Orchestrator state: INLINECODE55

Architecture

How It Works

CODEBLOCK17

Key Design Decisions

1. 1. Push-based completion — No polling. OpenClaw's subagent-announce system delivers completion events automatically.
2. Dependency gates — The orchestrator only dispatches tasks whose dependsOn are all done.
3. Tool isolation — Each agent gets only the tools they need. A researcher can't exec arbitrary code; a coder can't send messages to external channels.
4. File-based persistence — Simple JSON storage. No database required. Works on any OpenClaw instance.
5. CLI-first — All operations available via CLI. The UI is optional.
6. Agent-native — Uses OpenClaw's existing sessions_spawn, sessions_send, and agents_list tools. No custom transport.
7. Plugin architecture — Projects tab registered via OpenClaw's uiPluginRegistry (client-side). Team Chat drawer uses inline <style> tags for CSS (no Shadow DOM).
8. Client-side plugin registration — Since the gateway plugin view registration pipeline isn't fully wired end-to-end, the Projects tab is registered client-side in app-gateway.ts during onHello. This is reliable and avoids depending on gateway-side plugin infrastructure.

Plugin Registration Points (4 required for gateway plugin)

When adding a new gateway plugin to OpenClaw, you must register it in 4 places:

File	What to add
INLINECODE66	SDK type entry (exports OpenClawPluginApi etc.)
INLINECODE68 → INLINECODE69

Jiti alias so runtime can resolve openclaw/plugin-sdk/<id> |
| tsdown.config.ts → pluginSdkEntrypoints | Build entry so dist/plugin-sdk/<id>.js gets generated |
| scripts/write-plugin-sdk-entry-dts.ts | DTS entry generator |
| package.json → exports → ./plugin-sdk/<id> | Package subpath export |

Missing any one of these causes Cannot find module errors at runtime.

CSS Gotcha: No Shadow DOM

OpenClaw's OpenClawApp uses createRenderRoot() { return this; } — it renders directly to the DOM without Shadow DOM. This means:

• - Lit css tagged templates (used with static styles) are never applied
• All styles must be embedded as <style> tags in the HTML returned by render functions
• The teamChatDrawerStyles export was originally dead code until fixed to use inline styles

Coordinator Prompt Template

The coordinator agent should include templates/coordinator-prompt.md in its system prompt (or SOUL.md). This gives it the commands and workflow for managing projects.

Worker agents should include templates/worker-prompt.md for task completion protocols.

Known Issues & Gotchas

allowAgents must be per-agent

Setting agents.defaults.subagents.allowAgents: ["*"] does NOT work. The code at agents-list-tool.ts:49 reads:

const allowAgents = resolveAgentConfig(cfg, requesterAgentId)?.subagents?.allowAgents ?? [];

This resolves the per-agent config entry, not defaults. You must add it to the agent's entry in agents.list.

dependsOn normalization

The CLI passes --dependsOn task_abc as a string, not an array. The project store and orchestrator both normalize with Array.isArray() checks. If you create tasks programmatically, always pass an array.

UI requires hard refresh

After rebuilding the UI (pnpm ui:build) and restarting the gateway, browsers may cache the old JS bundle. Always hard-refresh (Ctrl+Shift+R) after UI changes.

Icon availability

The icon used for the Projects tab must exist in ui/src/ui/icons.ts. Available icons include: fileText, folder, barChart, zap, brain, settings, plug, etc. Custom icon names like clipboard-list won't work — use fileText instead.

Limitations

• - No real-time UI sync — The UI reads from JSON files; updates appear on refresh, not live push.
• No native gateway RPC — The project board is managed via CLI tools, not gateway RPC methods (yet).
• Single coordinator — One agent coordinates per project (though you could have different coordinators for different projects).
• No cost tracking — Task cost/token tracking depends on OpenClaw's session usage system.
• Client-side plugin registration — The gateway-side plugin view registration pipeline (registerView → hello snapshot → loadFromGateway) is scaffolded but not fully wired. Plugin tabs are registered client-side instead.

Future Enhancements

• - [ ] Gateway RPC plugin for live UI updates via WebSocket
• [ ] Kanban drag-and-drop in the sidebar
• [ ] Gantt chart / timeline view
• [ ] Automated task creation from GitHub issues
• [ ] Cost/token budget per task
• [ ] Agent capability auto-detection from tools config
• [ ] Cron-based project health checks
• [ ] Gateway-side plugin view registration (when pipeline is complete)

Files

CODEBLOCK19