Team Projects

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:

User → Coordinator (Koda) → dispatches tasks via sessions_spawn
                            ├── @researcher → web research, data analysis
                            ├── @coder → writing code, building features
                            ├── @writer → copy, documentation, content
                            └── ... any configured agent

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:

{
  "tools": {
    "agentToAgent": {
      "enabled": true,
      "allow": ["*"]
    }
  }
}

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

{
  "agents": {
    "list": [
      {
        "id": "main",
        "default": true,
        "name": "Koda",
        "subagents": {
          "allowAgents": ["*"]
        }
      }
    ]
  }
}

⚠️ 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:

export { emptyPluginConfigSchema } from "../plugins/config-schema.js";
export type {
  OpenClawPluginApi,
  PluginViewRegistration,
} from "../plugins/types.js";

2b. Plugin extension

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

{
  "id": "team-projects",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {}
  }
}

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:

{
  subpath: "team-projects",
  srcFile: "team-projects.ts",
  distFile: "team-projects.js",
},

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

package.json — Add to the exports map:

"./plugin-sdk/team-projects": {
  "types": "./dist/plugin-sdk/team-projects.d.ts",
  "default": "./dist/plugin-sdk/team-projects.js"
},

2d. Enable in config

{
  "plugins": {
    "allow": ["telegram", "discord", "team-projects"],
    "entries": {
      "team-projects": {
        "enabled": true
      }
    }
  }
}

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. Import renderTeamChatDrawer and renderTeamChatEdgeTab from ./views/team-chat-drawer.ts
2. Before </main>, add ${renderPluginTabContent(state)}
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. Import uiPluginRegistry from ./plugins/registry.ts
2. Import renderTeamProjects from ./views/team-projects.ts
3. In onHello, after applySnapshot(), call registerTeamProjectsPlugin()
4. Add the registerTeamProjectsPlugin() function

3e. Add view state fields

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

teamChatOpen: boolean;
teamChatProject: unknown;
teamChatSessions: unknown[];
teamChatActivity: unknown[];
teamChatLoading: boolean;
teamChatInput: string;
teamChatTasksCollapsed: boolean;

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

} else if (host.teamChatOpen) {
  host.teamChatOpen = false;
}

Step 4: Build & Restart

cd ~/openclaw
pnpm build        # Backend (gateway + plugin SDK)
pnpm ui:build     # Control UI
openclaw gateway restart

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. 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:

# Create a project
node {{SKILL_DIR}}/scripts/project-store.js create-project \
  --name "Website Redesign" \
  --description "Full redesign of company website" \
  --coordinator main \
  --agents "researcher,writer,coder"

# Add phases (ordered)
node {{SKILL_DIR}}/scripts/project-store.js add-phase \
  --project PROJECT_ID --name "Research" --description "Competitive analysis"

# Add tasks with assignments and dependencies
node {{SKILL_DIR}}/scripts/project-store.js add-task \
  --project PROJECT_ID --phase PHASE_ID \
  --title "Analyze top 5 competitors" \
  --description "Research competitor websites..." \
  --assignee researcher --priority high

node {{SKILL_DIR}}/scripts/project-store.js add-task \
  --project PROJECT_ID --phase PHASE_ID \
  --title "Write homepage hero copy" \
  --assignee writer --priority high \
  --dependsOn "task_abc123"

Dispatching Tasks

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

# See what's ready to dispatch
node {{SKILL_DIR}}/scripts/orchestrator.js plan PROJECT_ID

Then dispatch via OpenClaw's native sessions_spawn:

sessions_spawn(
  agentId: "researcher",
  task: "Research the top 5 competitors in the AI SaaS space...",
  label: "task_abc123"
)

Agent Communication

Agents can communicate using @-mentions:

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

Tracking Progress

# View project stats
node {{SKILL_DIR}}/scripts/project-store.js stats --id PROJECT_ID

# View work breakdown structure
node {{SKILL_DIR}}/scripts/project-store.js wbs --id PROJECT_ID

# Check and advance completed phases
node {{SKILL_DIR}}/scripts/orchestrator.js advance PROJECT_ID

Updating Tasks

# Mark task in progress
node {{SKILL_DIR}}/scripts/project-store.js update-task \
  --project PROJECT_ID --id TASK_ID --status in_progress

# Mark task done
node {{SKILL_DIR}}/scripts/project-store.js update-task \
  --project PROJECT_ID --id TASK_ID --status done

# Add a comment
node {{SKILL_DIR}}/scripts/project-store.js add-comment \
  --project PROJECT_ID --task TASK_ID \
  --author main --text "Looks good, merging now"

Data Model

Project

project
├── id, name, slug, description
├── status: planning | active | paused | completed | archived
├── coordinator: agentId
├── agents: [agentId, ...]
└── phases[]
    ├── id, name, description, order
    ├── status: pending | active | completed
    └── tasks[]
        ├── id, title, description
        ├── assignee: agentId
        ├── priority: critical | high | medium | low
        ├── status: todo | in_progress | blocked | review | done
        ├── dependsOn: [taskId, ...]
        ├── sessionKey: (set when dispatched)
        ├── artifacts: [paths/URLs]
        └── comments[]

Storage

• Projects: ~/.openclaw/workspace/team-projects/projects.json
• Chat logs: ~/.openclaw/workspace/team-projects/chat_PROJECT_ID.jsonl
• Orchestrator state: ~/.openclaw/workspace/team-projects/orchestrator-state.json

Architecture

How It Works

┌─────────────┐     sessions_spawn      ┌──────────────┐
│ Coordinator  │ ──────────────────────→ │  Worker Agent │
│   (Koda)     │                         │  (researcher) │
│              │ ←── push completion ──── │              │
│  project-    │                         └──────────────┘
│  store.js    │     sessions_spawn      ┌──────────────┐
│              │ ──────────────────────→ │  Worker Agent │
│  orchestr-   │                         │   (coder)     │
│  ator.js     │ ←── push completion ──── │              │
│              │                         └──────────────┘
│  UI plugin   │     sessions_send       ┌──────────────┐
│  tab         │ ←────────────────────── │  Worker Agent │
└─────────────┘     (inter-agent msg)    │   (writer)    │
                                         └──────────────┘

Key Design Decisions

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.