@teamclaws/teamclaw 2026.3.21

package/README.md

@@ -0,0 +1,37 @@
+# @teamclaws/teamclaw
+
+TeamClaw is an **OpenClaw plugin** that turns multiple roles into a collaborative virtual software team.
+
+It supports:
+
+- `controller` / `worker` modes
+- single-instance `localRoles`
+- clarifications, workspace browsing, and Web UI
+- Git-based collaboration
+- on-demand worker provisioning with `process`, `docker`, and `kubernetes`
+
+## Install
+
+If you already have OpenClaw installed, add the plugin with:
+
+```bash
+openclaw plugins install @teamclaws/teamclaw
+```
+
+Then enable and configure TeamClaw in your `openclaw.json`.
+
+## Recommended first setup
+
+For a first-time setup, the safest path is:
+
+1. Start with a single machine and `controller + localRoles`
+2. Validate the workflow with a small smoke-test task
+3. Expand to distributed or on-demand workers after the basics are working
+
+## Documentation
+
+For complete setup and architecture details, see:
+
+- Installation guide: <https://github.com/topcheer/teamclaw/blob/main/INSTALL.md>
+- Repository overview: <https://github.com/topcheer/teamclaw/blob/main/README.md>
+- Design notes: <https://github.com/topcheer/teamclaw/blob/main/DESIGN.md>

package/api.ts

@@ -0,0 +1,10 @@
+export { emptyPluginConfigSchema } from "openclaw/plugin-sdk/core";
+export type {
+  AnyAgentTool,
+  OpenClawPluginApi,
+  OpenClawPluginService,
+  OpenClawPluginServiceContext,
+  OpenClawPluginToolContext,
+  OpenClawPluginToolFactory,
+  PluginLogger,
+} from "openclaw/plugin-sdk/core";

package/index.ts

@@ -0,0 +1,246 @@
+import type { OpenClawPluginApi } from "./api.js";
+import { parsePluginConfig } from "./src/types.js";
+import type { TaskExecutionEventInput, WorkerIdentity } from "./src/types.js";
+import { buildConfigSchema } from "./src/config.js";
+import { loadTeamState } from "./src/state.js";
+import { createRoleTaskExecutor } from "./src/task-executor.js";
+import { createWorkerService } from "./src/worker/worker-service.js";
+import { createWorkerPromptInjector } from "./src/worker/prompt-injector.js";
+import { createWorkerTools } from "./src/worker/tools.js";
+import { MessageQueue } from "./src/worker/message-queue.js";
+import { createControllerService } from "./src/controller/controller-service.js";
+import { LocalWorkerManager } from "./src/controller/local-worker-manager.js";
+import { createControllerPromptInjector } from "./src/controller/prompt-injector.js";
+import { createControllerTools } from "./src/controller/controller-tools.js";
+import { publishWorkerRepo, syncWorkerRepo } from "./src/git-collaboration.js";
+
+const plugin = {
+  id: "teamclaw",
+  name: "TeamClaw",
+  description:
+    "Virtual team collaboration - multiple OpenClaw instances form a virtual software company with role-based task routing.",
+  configSchema: buildConfigSchema(),
+  register(api: OpenClawPluginApi) {
+    const config = parsePluginConfig(api.pluginConfig as Record<string, unknown>);
+    const logger = api.logger;
+
+    if (config.mode === "controller") {
+      registerController(api, config);
+    } else {
+      registerWorker(api, config);
+    }
+  },
+};
+
+export default plugin;
+
+function registerController(api: OpenClawPluginApi, config: ReturnType<typeof parsePluginConfig>) {
+  const logger = api.logger;
+  const localWorkerManager = new LocalWorkerManager({
+    config,
+    logger,
+    runtime: api.runtime,
+  });
+
+  // Service (starts HTTP server + mDNS + WebSocket)
+  api.registerService(createControllerService({ config, logger, runtime: api.runtime, localWorkerManager }));
+
+  // Prompt injection
+  api.on("before_prompt_build", async (_event: unknown, ctx: { sessionKey?: string | null }) => {
+    const localIdentity = localWorkerManager.getIdentityForSession(ctx.sessionKey);
+    const localMessageQueue = localWorkerManager.getMessageQueueForSession(ctx.sessionKey);
+    if (localIdentity && localMessageQueue) {
+      const injector = createWorkerPromptInjector(
+        { ...config, role: localIdentity.role },
+        () => localIdentity,
+        localMessageQueue,
+      );
+      return injector() ?? {};
+    }
+
+    const state = await loadTeamState(config.teamName);
+    const injector = createControllerPromptInjector({
+      config,
+      getTeamState: () => state,
+    });
+    return injector() ?? {};
+  });
+
+  // Tools - register all controller tools via factory returning an array
+  const controllerUrl = `http://localhost:${config.port}`;
+  api.registerTool((ctx: { sessionKey?: string | null }) => {
+    const localIdentity = localWorkerManager.getIdentityForSession(ctx.sessionKey);
+    if (localIdentity) {
+      return createWorkerTools({
+        config: { ...config, role: localIdentity.role },
+        getIdentity: () => localIdentity,
+      });
+    }
+
+    return createControllerTools({
+      config,
+      controllerUrl,
+      getTeamState: () => null,
+    });
+  });
+}
+
+function registerWorker(api: OpenClawPluginApi, config: ReturnType<typeof parsePluginConfig>) {
+  const logger = api.logger;
+  const messageQueue = new MessageQueue();
+  let currentControllerUrl: string | null = null;
+  let currentWorkerId: string | null = null;
+
+  function getIdentity(): WorkerIdentity | null {
+    if (!currentWorkerId || !currentControllerUrl) return null;
+    return {
+      workerId: currentWorkerId,
+      role: config.role,
+      controllerUrl: currentControllerUrl,
+      registeredAt: Date.now(),
+    };
+  }
+
+  async function reportExecutionEvent(taskId: string, event: TaskExecutionEventInput): Promise<void> {
+    if (!currentControllerUrl) {
+      return;
+    }
+
+    try {
+      const res = await fetch(`${currentControllerUrl}/api/v1/tasks/${taskId}/execution`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          ...event,
+          workerId: currentWorkerId ?? undefined,
+          role: config.role,
+        }),
+      });
+      if (!res.ok) {
+        logger.warn(`Worker: failed to record execution event for ${taskId} (${res.status})`);
+      }
+    } catch (err) {
+      logger.warn(`Worker: failed to POST execution event for ${taskId}: ${String(err)}`);
+    }
+  }
+
+  const getWorkerSessionKey = (taskId: string) => `teamclaw-task-${taskId}`;
+
+  const taskExecutor = createRoleTaskExecutor({
+    runtime: api.runtime,
+    logger,
+    role: config.role,
+    taskTimeoutMs: config.taskTimeoutMs,
+    getSessionKey: getWorkerSessionKey,
+    getIdempotencyKey: (taskId) => `teamclaw-${taskId}`,
+    reportExecutionEvent,
+  });
+
+  // Service
+  api.registerService(
+    createWorkerService({
+      config,
+      logger,
+      onIdentityEstablished: (identity) => {
+        currentControllerUrl = identity.controllerUrl;
+        currentWorkerId = identity.workerId;
+      },
+      prepareTaskAssignment: async (assignment) => {
+        if (!assignment.repo?.enabled || !currentControllerUrl) {
+          return;
+        }
+
+        await reportExecutionEvent(assignment.taskId, {
+          type: "lifecycle",
+          phase: "repo_sync_started",
+          source: "worker",
+          status: "running",
+          message: `Preparing ${assignment.repo.mode} git workspace sync before task execution.`,
+        });
+
+        try {
+          const syncResult = await syncWorkerRepo(config, logger, currentControllerUrl, assignment.repo);
+          await reportExecutionEvent(assignment.taskId, {
+            type: "lifecycle",
+            phase: "repo_sync_completed",
+            source: "worker",
+            status: "running",
+            message: syncResult.message,
+          });
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          await reportExecutionEvent(assignment.taskId, {
+            type: "error",
+            phase: "repo_sync_failed",
+            source: "worker",
+            status: "running",
+            message,
+          });
+          throw err;
+        }
+      },
+      publishTaskAssignment: async (assignment) => {
+        if (!assignment.repo?.enabled || !currentControllerUrl || !currentWorkerId) {
+          return;
+        }
+
+        await reportExecutionEvent(assignment.taskId, {
+          type: "lifecycle",
+          phase: "repo_publish_started",
+          source: "worker",
+          status: "running",
+          message: `Publishing task changes through ${assignment.repo.mode} git collaboration.`,
+        });
+
+        try {
+          const publishResult = await publishWorkerRepo(config, logger, currentControllerUrl, assignment.repo, {
+            taskId: assignment.taskId,
+            workerId: currentWorkerId,
+            role: config.role,
+          });
+          await reportExecutionEvent(assignment.taskId, {
+            type: "lifecycle",
+            phase: publishResult.published ? "repo_publish_completed" : "repo_publish_skipped",
+            source: "worker",
+            status: "running",
+            message: publishResult.message,
+          });
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          await reportExecutionEvent(assignment.taskId, {
+            type: "error",
+            phase: "repo_publish_failed",
+            source: "worker",
+            status: "running",
+            message,
+          });
+          throw err;
+        }
+      },
+      taskExecutor,
+      cancelTaskExecution: async (taskId) => {
+        const sessionKey = getWorkerSessionKey(taskId);
+        try {
+          await api.runtime.subagent.deleteSession({ sessionKey });
+          logger.info(`Worker: cancelled subagent session ${sessionKey} for task ${taskId}`);
+          return true;
+        } catch (err) {
+          logger.warn(`Worker: failed to cancel session ${sessionKey} for task ${taskId}: ${String(err)}`);
+          return false;
+        }
+      },
+      messageQueue,
+    }),
+  );
+
+  // Prompt injection
+  api.on("before_prompt_build", async () => {
+    const injector = createWorkerPromptInjector(config, getIdentity, messageQueue);
+    return injector() ?? {};
+  });
+
+  // Tools - register all worker tools via factory returning an array
+  api.registerTool(() => {
+    return createWorkerTools({ config, getIdentity });
+  });
+}

package/openclaw.plugin.json

@@ -0,0 +1,41 @@
+{
+  "id": "teamclaw",
+  "name": "TeamClaw",
+  "description": "Virtual team collaboration plugin - multiple OpenClaw instances form a virtual software company with role-based task routing.",
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "mode": {
+        "type": "string",
+        "enum": ["controller", "worker"],
+        "default": "worker",
+        "description": "Plugin mode: controller manages the team, worker executes tasks"
+      },
+      "port": {
+        "type": "number",
+        "default": 9527,
+        "description": "HTTP server port for this instance"
+      },
+      "role": {
+        "type": "string",
+        "default": "developer",
+        "description": "Worker role (only used in worker mode)"
+      },
+      "controllerUrl": {
+        "type": "string",
+        "default": "",
+        "description": "Manual controller URL fallback (used when mDNS discovery fails)"
+      },
+      "teamName": {
+        "type": "string",
+        "default": "default",
+        "description": "Team name for mDNS identification"
+      },
+      "heartbeatIntervalMs": {
+        "type": "number",
+        "default": 10000,
+        "description": "Heartbeat interval in milliseconds"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@teamclaws/teamclaw",
+  "version": "2026.3.21",
+  "description": "OpenClaw virtual software team orchestration plugin",
+  "private": false,
+  "keywords": [
+    "openclaw",
+    "plugin",
+    "teamclaw",
+    "multi-agent",
+    "orchestration"
+  ],
+  "homepage": "https://github.com/topcheer/teamclaw/tree/main/src#readme",
+  "bugs": {
+    "url": "https://github.com/topcheer/teamclaw/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/topcheer/teamclaw.git",
+    "directory": "src"
+  },
+  "type": "module",
+  "files": [
+    "README.md",
+    "api.ts",
+    "index.ts",
+    "openclaw.plugin.json",
+    "src/",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "pack:dry-run": "npm pack --dry-run --json --ignore-scripts",
+    "release:check": "node ../scripts/teamclaw-package-check.mjs src"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "0.34.48",
+    "bonjour-service": "^1.3.0",
+    "json5": "^2.2.3",
+    "ws": "^8.19.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.0"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.3.14"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "release": {
+      "publishToNpm": true
+    }
+  }
+}

package/src/config.ts

@@ -0,0 +1,297 @@
+import type { PluginConfig } from "./types.js";
+import { parsePluginConfig } from "./types.js";
+import { ROLE_IDS } from "./roles.js";
+
+function buildConfigSchema() {
+  return {
+    jsonSchema: {
+      type: "object" as const,
+      properties: {
+        mode: {
+          type: "string" as const,
+          enum: ["controller", "worker"],
+          default: "worker",
+          description: "Plugin mode: controller manages the team, worker executes tasks",
+        },
+        port: {
+          type: "number" as const,
+          default: 9527,
+          description: "HTTP server port for this instance",
+        },
+        role: {
+          type: "string" as const,
+          default: "developer",
+          description: "Worker role (only used in worker mode)",
+        },
+        controllerUrl: {
+          type: "string" as const,
+          default: "",
+          description: "Manual controller URL fallback (used when mDNS discovery fails)",
+        },
+        teamName: {
+          type: "string" as const,
+          default: "default",
+          description: "Team name for mDNS identification",
+        },
+        heartbeatIntervalMs: {
+          type: "number" as const,
+          default: 10000,
+          description: "Heartbeat interval in milliseconds",
+        },
+        taskTimeoutMs: {
+          type: "number" as const,
+          default: 1800000,
+          description: "Maximum time in milliseconds to wait for a role task to finish",
+        },
+        gitEnabled: {
+          type: "boolean" as const,
+          default: true,
+          description: "Enable TeamClaw git-backed workspace collaboration",
+        },
+        gitRemoteUrl: {
+          type: "string" as const,
+          default: "",
+          description: "Optional remote repository URL for distributed worker clone/pull/push",
+        },
+        gitDefaultBranch: {
+          type: "string" as const,
+          default: "main",
+          description: "Default branch name for the shared TeamClaw workspace repository",
+        },
+        gitAuthorName: {
+          type: "string" as const,
+          default: "TeamClaw",
+          description: "Git author name used for TeamClaw-managed workspace commits",
+        },
+        gitAuthorEmail: {
+          type: "string" as const,
+          default: "teamclaw@local",
+          description: "Git author email used for TeamClaw-managed workspace commits",
+        },
+        localRoles: {
+          type: "array" as const,
+          default: [],
+          description: "Controller-local roles executed in this same OpenClaw instance",
+          items: {
+            type: "string" as const,
+            enum: ROLE_IDS,
+          },
+        },
+        workerProvisioningType: {
+          type: "string" as const,
+          enum: ["none", "process", "docker", "kubernetes"],
+          default: "none",
+          description: "Controller-only on-demand worker launch backend",
+        },
+        workerProvisioningControllerUrl: {
+          type: "string" as const,
+          default: "",
+          description: "Controller URL injected into provisioned workers; required for docker/kubernetes",
+        },
+        workerProvisioningRoles: {
+          type: "array" as const,
+          default: [],
+          description: "Restrict on-demand launches to specific roles; empty means all roles",
+          items: {
+            type: "string" as const,
+            enum: ROLE_IDS,
+          },
+        },
+        workerProvisioningMinPerRole: {
+          type: "number" as const,
+          default: 0,
+          description: "Minimum number of ready workers to keep warm per role",
+        },
+        workerProvisioningMaxPerRole: {
+          type: "number" as const,
+          default: 1,
+          description: "Maximum on-demand workers to launch per role",
+        },
+        workerProvisioningIdleTtlMs: {
+          type: "number" as const,
+          default: 120000,
+          description: "Terminate provisioned idle workers after this many milliseconds",
+        },
+        workerProvisioningStartupTimeoutMs: {
+          type: "number" as const,
+          default: 120000,
+          description: "Fail a launch if the worker does not register within this many milliseconds",
+        },
+        workerProvisioningImage: {
+          type: "string" as const,
+          default: "",
+          description: "Container image used by docker/kubernetes provisioners",
+        },
+        workerProvisioningPassEnv: {
+          type: "array" as const,
+          default: [],
+          description: "Environment variable names copied from the controller into provisioned workers",
+          items: {
+            type: "string" as const,
+          },
+        },
+        workerProvisioningExtraEnv: {
+          type: "object" as const,
+          default: {},
+          description: "Extra environment variables injected into provisioned workers",
+          additionalProperties: {
+            type: "string" as const,
+          },
+        },
+        workerProvisioningDockerNetwork: {
+          type: "string" as const,
+          default: "",
+          description: "Optional Docker network name for launched worker containers",
+        },
+        workerProvisioningDockerMounts: {
+          type: "array" as const,
+          default: [],
+          description: "Optional Docker bind mounts for launched worker containers",
+          items: {
+            type: "string" as const,
+          },
+        },
+        workerProvisioningKubernetesNamespace: {
+          type: "string" as const,
+          default: "default",
+          description: "Kubernetes namespace for launched worker pods",
+        },
+        workerProvisioningKubernetesContext: {
+          type: "string" as const,
+          default: "",
+          description: "Optional kubectl context used by the Kubernetes provisioner",
+        },
+        workerProvisioningKubernetesServiceAccount: {
+          type: "string" as const,
+          default: "",
+          description: "Optional service account name for launched worker pods",
+        },
+        workerProvisioningKubernetesLabels: {
+          type: "object" as const,
+          default: {},
+          description: "Extra labels applied to launched worker pods",
+          additionalProperties: {
+            type: "string" as const,
+          },
+        },
+        workerProvisioningKubernetesAnnotations: {
+          type: "object" as const,
+          default: {},
+          description: "Extra annotations applied to launched worker pods",
+          additionalProperties: {
+            type: "string" as const,
+          },
+        },
+      },
+    },
+    uiHints: {
+      mode: { label: "Mode", help: "controller manages the team, worker executes tasks" },
+      port: { label: "Port", help: "HTTP server port for this instance" },
+      role: { label: "Role", help: "Worker role (worker mode only)" },
+      controllerUrl: { label: "Controller URL", help: "Manual fallback if mDNS discovery fails" },
+      teamName: { label: "Team Name", help: "Team identifier for mDNS" },
+      heartbeatIntervalMs: { label: "Heartbeat Interval", help: "In milliseconds, minimum 1000" },
+      taskTimeoutMs: {
+        label: "Task Timeout",
+        help: "Maximum time to wait for a role task to finish before marking it failed (in milliseconds)",
+      },
+      gitEnabled: {
+        label: "Git Collaboration",
+        help: "Enable automatic git-backed workspace bootstrapping and worker repo sync",
+      },
+      gitRemoteUrl: {
+        label: "Git Remote URL",
+        help: "Optional remote repository URL; when empty, distributed workers use controller-hosted git bundles",
+      },
+      gitDefaultBranch: {
+        label: "Git Default Branch",
+        help: "Default branch name for the TeamClaw workspace repository",
+      },
+      gitAuthorName: {
+        label: "Git Author Name",
+        help: "Author name for TeamClaw-managed workspace commits",
+      },
+      gitAuthorEmail: {
+        label: "Git Author Email",
+        help: "Author email for TeamClaw-managed workspace commits",
+      },
+      localRoles: {
+        label: "Local Roles",
+        help: "Controller mode only: run these roles as local virtual workers inside the same OpenClaw instance",
+      },
+      workerProvisioningType: {
+        label: "On-demand Worker Provider",
+        help: "Launch missing workers on demand using process, Docker, or Kubernetes",
+      },
+      workerProvisioningControllerUrl: {
+        label: "Provisioned Worker Controller URL",
+        help: "URL that launched workers use to call back into the controller",
+      },
+      workerProvisioningRoles: {
+        label: "Provisioned Roles",
+        help: "Only launch these roles on demand; leave empty for all roles",
+      },
+      workerProvisioningMinPerRole: {
+        label: "Warm Workers Per Role",
+        help: "Minimum idle workers to keep warm per role",
+      },
+      workerProvisioningMaxPerRole: {
+        label: "Max Workers Per Role",
+        help: "Maximum concurrent on-demand workers per role",
+      },
+      workerProvisioningIdleTtlMs: {
+        label: "Idle TTL",
+        help: "Terminate an idle provisioned worker after this many milliseconds",
+      },
+      workerProvisioningStartupTimeoutMs: {
+        label: "Startup Timeout",
+        help: "Fail a launch if the worker does not register in time",
+      },
+      workerProvisioningImage: {
+        label: "Provisioning Image",
+        help: "Container image for docker/kubernetes provisioners",
+      },
+      workerProvisioningPassEnv: {
+        label: "Pass-through Env",
+        help: "Environment variable names copied from controller to provisioned workers",
+      },
+      workerProvisioningExtraEnv: {
+        label: "Extra Env",
+        help: "Static environment variables injected into provisioned workers",
+      },
+      workerProvisioningDockerNetwork: {
+        label: "Docker Network",
+        help: "Optional Docker network for launched worker containers",
+      },
+      workerProvisioningDockerMounts: {
+        label: "Docker Mounts",
+        help: "Optional Docker bind mounts for launched worker containers",
+      },
+      workerProvisioningKubernetesNamespace: {
+        label: "Kubernetes Namespace",
+        help: "Namespace for launched worker pods",
+      },
+      workerProvisioningKubernetesContext: {
+        label: "Kubernetes Context",
+        help: "Optional kubectl context for the Kubernetes provider",
+      },
+      workerProvisioningKubernetesServiceAccount: {
+        label: "Kubernetes Service Account",
+        help: "Optional service account for launched worker pods",
+      },
+      workerProvisioningKubernetesLabels: {
+        label: "Kubernetes Labels",
+        help: "Extra labels applied to launched worker pods",
+      },
+      workerProvisioningKubernetesAnnotations: {
+        label: "Kubernetes Annotations",
+        help: "Extra annotations applied to launched worker pods",
+      },
+    },
+    parse(raw: unknown): PluginConfig {
+      return parsePluginConfig(raw as Record<string, unknown>);
+    },
+  };
+}
+
+export { buildConfigSchema };