multiclaw 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PengQi Shi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,327 @@
-# Temporary Holding Version
+# multiclaw
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/multiclaw)](https://www.npmjs.com/package/multiclaw)
+[![GitHub](https://img.shields.io/badge/GitHub-shipengqi%2Fmulticlaw-blue?logo=github)](https://github.com/shipengqi/multiclaw)
+
+[中文](https://github.com/shipengqi/multiclaw/blob/main/README.zh-CN.md)
+
+Multi-agent orchestration CLI. Define a pipeline of AI agents, give them a requirement, and watch them run in parallel or in sequence based on the dependency graph you declare.
+
+## Prerequisites
+
+At least one AI runtime must be installed:
+
+| Runtime | Install |
+|---------|---------|
+| `claude` (default) | `npm install -g @anthropic-ai/claude-code` |
+
+> **Future support:** We plan to add support for additional runtimes (Codex, OpenCode, Cursor) in upcoming releases.
+
+## Install
+
+```bash
+npm install -g multiclaw
+```
+
+## Quick start
+
+```bash
+# 1. Scaffold a config in the current directory
+multiclaw init
+
+# 2. Run an orchestration
+multiclaw run "Build a REST API for a todo list" --ui
+```
+
+`--ui` opens a real-time Dashboard in the browser. Omit it to run headless.
+
+## Commands
+
+### `multiclaw init`
+
+Interactive scaffold. Creates `multiclaw.config.ts` in the current directory.
+
+Prompts:
+- **Project name** — defaults to the current directory name
+- **Preset** — pipeline template (see [Presets](#presets))
+- **Work directory** — where agents read and write files
+
+### `multiclaw run <requirement> [options]`
+
+Runs the orchestration defined in your config file.
+
+| Option | Description |
+|--------|-------------|
+| `--config <path>` | Path to config file. Auto-discovers `multiclaw.config.ts` if omitted. |
+| `--ui` | Start the Dashboard server and open it in the browser. |
+| `--port <port>` | Dashboard port. Requires `--ui`. Default: `3210`. |
+| `--server-url <url>` | Stream events to a running `multiclaw serve` instance. |
+| `--no-leader` | Skip the leader agent and use the default pipeline directly. |
+
+The `<requirement>` string is injected into every agent's prompt as `{{requirement}}`.
+
+Each run creates an isolated timestamped subdirectory inside `workDir` (e.g. `workspace/run-2026-10-08T12-00-00`).
+
+### `multiclaw serve [options]`
+
+Start a persistent Dashboard server. Useful for CI or when you want a permanent URL to monitor runs.
+
+| Option | Description |
+|--------|-------------|
+| `--port <port>` | Port to listen on. Default: `3210`. |
+
+Connect a run to it with `multiclaw run "..." --server-url http://localhost:3210`.
+
+## Config file
+
+```typescript
+// multiclaw.config.ts
+import { defineConfig, agents } from "multiclaw"
+
+export default defineConfig({
+  name: "My Project",
+  workDir: "./workspace",
+
+  // Variables available as {{key}} in every agent's taskPrompt.
+  // `requirement` is automatically injected from the CLI argument.
+  context: {
+    projectName: "My App",
+  },
+
+  // Optional: runs before the main pipeline to decide which agents are needed.
+  // The leader reads the requirement and the codebase, then outputs the agent IDs to run.
+  leader: agents.leader(),
+
+  logDir: "./logs",         // optional; default: workDir/.multiclaw/logs
+  continueOnError: false,   // optional; keep running if an agent fails
+  maxConcurrency: 4,        // optional; max agents running at once
+
+  dashboard: {
+    port: 3210,
+    autoOpen: true,
+  },
+
+  agents: [
+    {
+      id: "architect",        // unique identifier, used in dependsOn
+      name: "Architect",      // display name
+      icon: "◆",              // optional; shown in terminal and dashboard
+      runtime: "claude",      // optional; default: "claude"
+      model: "opus",          // optional; override default model for this agent
+      systemPrompt: "You are a software architect.", // optional
+      taskPrompt: `Design the system for {{requirement}}.
+Read the brief at {{file:brief.md}} and write architecture.md.`,
+      tools: ["Read", "Write"],
+      dependsOn: [],          // optional; list of agent ids this agent waits for
+      timeout: 600_000,       // optional; ms, default: 600 000 (10 min)
+      retries: 0,             // optional; retry count on failure, default: 0
+      workDir: "architect",   // optional; subdirectory relative to global workDir
+    },
+    {
+      id: "developer",
+      name: "Developer",
+      model: "sonnet",        // override model for this agent
+      taskPrompt: "Read architecture.md and implement the code.",
+      tools: ["Read", "Write", "Bash"],
+      dependsOn: ["architect"],
+    },
+  ],
+})
+```
+
+### Top-level config fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | ✓ | Project name, shown in the dashboard. |
+| `workDir` | string | ✓ | Base directory where agents read and write files. |
+| `agents` | AgentDefinition[] | ✓ | The agent pipeline (see Agent fields below). |
+| `leader` | AgentDefinition | | Optional routing agent (see [Leader](#leader)). |
+| `useLeader` | boolean | | Enable or disable the leader agent. Default: `true` when leader is configured. |
+| `context` | Record<string, string> | | Variables available as `{{key}}` in every prompt. `requirement` is injected automatically. |
+| `logDir` | string | | Log output directory. Default: `workDir/.multiclaw/logs`. |
+| `continueOnError` | boolean | | Keep running when an agent fails. Default: `false`. |
+| `maxConcurrency` | number | | Max agents running in parallel. Default: unlimited. |
+| `dashboard.port` | number | | Dashboard port. Default: `3210`. |
+| `dashboard.autoOpen` | boolean | | Open the dashboard in a browser automatically. Default: `true`. |
+
+### Agent fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | ✓ | Unique identifier. Used in `dependsOn`. |
+| `name` | string | ✓ | Display name shown in terminal and dashboard. |
+| `taskPrompt` | string | ✓ | Prompt sent to the AI runtime. Supports template variables. |
+| `systemPrompt` | string | | Optional system prompt prepended to `taskPrompt`. |
+| `icon` | string | | Unicode icon shown next to the agent name. |
+| `runtime` | string | | `claude` (default). Additional runtimes coming soon. |
+| `model` | string | | Override the default model for this agent. E.g. `"opus"`, `"sonnet"`, `"haiku"`. Takes precedence over `models`. |
+| `models` | Record<string, string> | | Map of runtime names to model names. Used when `model` is not set. E.g. `{ claude: "opus", openai: "gpt-4" }`. |
+| `tools` | string[] | | Allowed tools. Default: `["Read", "Write", "Bash"]`. |
+| `dependsOn` | string[] | | Agent ids that must complete before this agent starts. |
+| `timeout` | number | | Per-agent timeout in ms. Default: `600000` (10 min). |
+| `retries` | number | | Number of retry attempts on failure. Default: `0`. |
+| `workDir` | string | | Subdirectory (relative to global `workDir`) for this agent's CWD. |
+
+### Template variables
+
+Two syntaxes are supported in `taskPrompt` and `systemPrompt`:
+
+| Syntax | Replaced with |
+|--------|--------------|
+| `{{key}}` | The value of `context.key` (or `requirement` from the CLI). |
+| `{{file:path/to/file}}` | The contents of that file, resolved relative to `workDir`. |
+| `{{pipelineAgents}}` | List of all agents running in this pipeline (id: name). Auto-injected; useful for the architect to decompose tasks per agent. |
+
+## Parallelism
+
+Agents are grouped into stages by their dependency graph (topological sort). All agents within the same stage run concurrently. `maxConcurrency` caps how many run at once globally.
+
+```
+Stage 1:  product-manager
+Stage 2:  architect
+Stage 3:  backend-developer  │  ui-designer      ← parallel
+Stage 4:  code-reviewer      │  devops            ← parallel
+```
+
+## Dashboard
+
+The real-time web UI shows:
+
+- Stage timeline with agent status (running / done / failed / skipped)
+- Live streaming logs per agent
+- Per-agent duration and retry count
+- Elapsed time while running; total time on completion
+
+Start it with `--ui` on `run`, or run `multiclaw serve` for a persistent instance.
+
+## Logs
+
+After each run, all generated files are written under `workDir/.multiclaw/runs/run-<timestamp>/` (or `logDir` if set):
+
+```
+workDir/
+└── .multiclaw/
+    └── runs/
+        └── run-2026-10-08T12-00-00/
+            ├── <agent output files>   ← files agents write (e.g. architecture.md)
+            └── logs/
+                ├── <agentId>.log      ← raw stdout per agent
+                └── report.json        ← full orchestration result
+```
+
+| File | Contents |
+|------|----------|
+| `<agentId>.log` | Raw stdout from that agent's process |
+| `report.json` | Full orchestration result (status, duration, output per agent) |
+
+The log path is printed to the terminal at the start of every run.
+
+## Presets
+
+Presets are pipeline templates you can pick during `multiclaw init`:
+
+| Preset | Pipeline | Agents |
+|--------|----------|--------|
+| `simple` | Architect → Arch Design Reviewer → Backend Developer → Code Reviewer | 4 |
+| `backend` | Product Manager → Architect → Arch Design Reviewer → Backend Developer → Tester → Code Reviewer + DevOps | 7 |
+| `fullstack` | Product Manager → Architect → Arch Design Reviewer → Backend Developer + UI Designer → UI Design Reviewer → Frontend Developer → Code Reviewer + DevOps | 9 |
+
+## Leader
+
+The `leader` field adds a routing agent that runs **before** the main pipeline. It reads the requirement and inspects the codebase, then decides which agents are actually needed for this task. Agents the leader omits are skipped.
+
+```typescript
+export default defineConfig({
+  leader: agents.leader(),
+  agents: [
+    agents.architect(),
+    agents.archDesignReviewer({ dependsOn: ["architect"] }),
+    agents.backendDeveloper({ dependsOn: ["arch-design-reviewer"] }),
+    agents.codeReviewer({ dependsOn: ["backend-developer"] }),
+  ],
+})
+```
+
+For a minor bug fix the leader might decide only `backend-developer` and `code-reviewer` are needed, skipping the design stages. For a greenfield feature it runs the full pipeline.
+
+If the leader fails or produces invalid output, multiclaw falls back to running all agents.
+
+### Disabling the leader
+
+You can skip the leader and use the default pipeline directly in three ways:
+
+1. **CLI option** (for a single run):
+   ```bash
+   multiclaw run "your requirement" --no-leader
+   ```
+
+2. **Config file** (per-run, via environment variable or config override):
+   ```typescript
+   export default defineConfig({
+     leader: agents.leader(),
+     useLeader: false, // disable leader
+     agents: [...],
+   })
+   ```
+
+3. **Remove the leader from config** (always use the default pipeline):
+   ```typescript
+   export default defineConfig({
+     // leader field omitted
+     agents: [...],
+   })
+   ```
+
+## Architect and Task Decomposition
+
+When the **architect** agent is in your pipeline, it produces three outputs:
+
+1. **architecture.md** — architecture plan and module breakdown
+2. **api-spec.md** — complete API specification
+3. **task-plan.json** — structured task breakdown for all implementation agents in the pipeline
+
+The `task-plan.json` file helps coordinate work across parallel agents by explicitly assigning scope to each agent. Each implementation agent (backend-developer, frontend-developer, ui-designer, devops, tester, etc.) reads this file to understand its specific responsibilities and dependencies.
+
+**Example task-plan.json:**
+```json
+{
+  "projectName": "My App",
+  "requirement": "Build a todo list API with React UI",
+  "tasks": [
+    {
+      "id": "backend-developer",
+      "title": "REST API",
+      "scope": "Implement all endpoints per api-spec.md",
+      "dependsOn": []
+    },
+    {
+      "id": "frontend-developer",
+      "title": "React UI",
+      "scope": "Build React components following ui-design.md",
+      "dependsOn": []
+    },
+    {
+      "id": "devops",
+      "title": "Deployment",
+      "scope": "Containerize and set up CI/CD",
+      "dependsOn": ["backend-developer", "frontend-developer"]
+    }
+  ]
+}
+```
+
+If the architect is not in your pipeline, dev agents fall back to reading `architecture.md` and `api-spec.md` directly.
+
+## Example
+
+See [`examples/dev-team/`](https://github.com/shipengqi/multiclaw/tree/main/examples/dev-team) for a working three-agent pipeline (Architect → Developer → Reviewer).
+
+```bash
+cd examples/dev-team
+pnpm dev
+```
+
+## License
+
+[MIT](https://github.com/shipengqi/multiclaw/blob/main/LICENSE)

package/dist/index.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { runCommand } from "./commands/run";
+import { initCommand } from "./commands/init";
+import { serveCommand } from "./commands/serve";
+import { upgradeCommand } from "./commands/upgrade";
+const program = new Command();
+program
+    .name("multiclaw")
+    .description("Multi-agent orchestration CLI")
+    .version("0.1.0");
+program
+    .command("init")
+    .description("Scaffold a config file (interactive)")
+    .action(() => initCommand());
+program
+    .command("run <requirement>")
+    .description("Run an orchestration")
+    .option("--config <path>", "Config file path (default: auto-discover ./multiclaw.config.ts)")
+    .option("--ui", "Start Dashboard and open in browser")
+    .option("--port <port>", "Dashboard port (requires --ui)", (v) => parseInt(v, 10))
+    .option("--server-url <url>", "Connect to a running serve process")
+    .option("--no-leader", "Skip the leader agent and use the default pipeline")
+    .action((requirement, opts) => runCommand(requirement, opts));
+program
+    .command("serve")
+    .description("Start a persistent Dashboard server")
+    .option("--port <port>", "Port", (v) => parseInt(v, 10))
+    .action((opts) => serveCommand(opts));
+program
+    .command("upgrade")
+    .description("Upgrade multiclaw to the latest version")
+    .action(() => upgradeCommand());
+program.parseAsync(process.argv).catch((err) => {
+    console.error(`\x1b[31mError: ${err.message ?? err}\x1b[0m`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/lib.js

@@ -0,0 +1,2 @@
+export { defineConfig, agents } from "@multiclawcli/core";
+//# sourceMappingURL=lib.js.map

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "multiclaw",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "type": "module",
+  "bin": {
+    "multiclaw": "dist/index.js"
+  },
+  "main": "dist/lib.js",
+  "types": "dist/lib.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/lib.d.ts",
+      "default": "./dist/lib.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shipengqi/multiclaw.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/shipengqi/multiclaw#readme",
+  "bugs": {
+    "url": "https://github.com/shipengqi/multiclaw/issues"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.7.3",
+    "@multiclawcli/core": "0.2.0",
+    "@multiclawcli/dashboard": "0.2.0",
+    "commander": "^12.0.0",
+    "open": "^10.0.0",
+    "tsx": "^4.7.0",
+    "ws": "^8.16.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "@types/ws": "^8.5.0",
+    "typescript": "^5.4.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts"
+  }
 }

package/src/commands/init.ts

@@ -0,0 +1,128 @@
+import * as fs from "fs"
+import * as path from "path"
+import { execSync } from "child_process"
+import { select, input } from "@inquirer/prompts"
+
+// ─── Agent Block Definitions ──────────────────────────────────────────────────
+
+const AGENT_BLOCKS: Record<string, string> = {
+  simple: `    agents.architect(),
+    agents.archDesignReviewer({ dependsOn: ["architect"] }),
+    agents.backendDeveloper({ dependsOn: ["arch-design-reviewer"] }),
+    agents.codeReviewer({ dependsOn: ["backend-developer"] }),`,
+
+  backend: `    agents.productManager(),
+    agents.architect({ dependsOn: ["product-manager"] }),
+    agents.archDesignReviewer({ dependsOn: ["architect"] }),
+    agents.backendDeveloper({ dependsOn: ["arch-design-reviewer"] }),
+    agents.tester({ dependsOn: ["backend-developer"] }),
+    agents.codeReviewer({ dependsOn: ["tester"] }),
+    agents.devops({ dependsOn: ["tester"] }),`,
+
+  fullstack: `    agents.productManager(),
+    agents.architect({ dependsOn: ["product-manager"] }),
+    agents.archDesignReviewer({ dependsOn: ["architect"] }),
+    agents.backendDeveloper({ dependsOn: ["arch-design-reviewer"] }),
+    agents.uiDesigner({ dependsOn: ["arch-design-reviewer"] }),
+    agents.uiDesignReviewer({ dependsOn: ["ui-designer"] }),
+    agents.frontendDeveloper({ dependsOn: ["ui-design-reviewer"] }),
+    agents.codeReviewer({ dependsOn: ["backend-developer", "frontend-developer"] }),
+    agents.devops({ dependsOn: ["backend-developer", "frontend-developer"] }),`,
+}
+
+const PRESET_DESCRIPTIONS: Record<string, string> = {
+  simple:    "Architect → Arch Design Reviewer → Backend Developer → Code Reviewer  (4 agents)",
+  backend:   "Product Manager → Architect → Arch Design Reviewer → Backend Developer → Tester → Code Reviewer + DevOps  (7 agents)",
+  fullstack: "Product Manager → Architect → Arch Design Reviewer → Backend Developer + UI Designer → UI Design Reviewer → Frontend Developer → Code Reviewer + DevOps  (9 agents)",
+}
+
+const RUNTIME_INSTALL: Record<string, string> = {
+  claude:    "npm install -g @anthropic-ai/claude-code",
+  codex:     "npm install -g @openai/codex",
+  opencode:  "npm install -g opencode",
+  cursor:    "curl https://cursor.com/install | bash",
+}
+
+// ─── Config Generator ─────────────────────────────────────────────────────────
+
+function generateConfig(opts: { preset: string; workDir: string; projectName: string }): string {
+  return `import { defineConfig, agents } from "multiclaw"
+
+export default defineConfig({
+  name: "${opts.projectName}",
+  workDir: "${opts.workDir}",
+  context: {
+    projectName: "${opts.projectName}",
+  },
+  dashboard: { port: 3210, autoOpen: true },
+  agents: [
+${AGENT_BLOCKS[opts.preset]}
+  ],
+})
+`
+}
+
+// ─── Command ──────────────────────────────────────────────────────────────────
+
+export async function initCommand(): Promise<void> {
+  const configPath = path.resolve(process.cwd(), "multiclaw.config.ts")
+  if (fs.existsSync(configPath)) {
+    console.error("\x1b[31mError: multiclaw.config.ts already exists\x1b[0m")
+    process.exit(1)
+  }
+
+  const defaultProjectName = path.basename(process.cwd())
+
+  const projectName = await input({
+    message: "Project name:",
+    default: defaultProjectName,
+  })
+
+  const preset = await select({
+    message: "Select a preset:",
+    choices: [
+      { value: "simple",    name: `simple     — ${PRESET_DESCRIPTIONS.simple}` },
+      { value: "backend",   name: `backend    — ${PRESET_DESCRIPTIONS.backend}` },
+      { value: "fullstack", name: `fullstack  — ${PRESET_DESCRIPTIONS.fullstack}` },
+    ],
+  })
+
+  const workDir = await input({
+    message: "Work directory (where agents read and write files):",
+    default: ".",
+  })
+
+  try {
+    fs.writeFileSync(configPath, generateConfig({ preset, workDir, projectName }))
+    if (workDir !== ".") {
+      fs.mkdirSync(path.resolve(process.cwd(), workDir), { recursive: true })
+    }
+  } catch (err) {
+    console.error(`\x1b[31mError: Failed to create files: ${(err as Error).message}\x1b[0m`)
+    process.exit(1)
+  }
+
+  console.log("")
+  console.log(`\x1b[32m✓\x1b[0m Created multiclaw.config.ts`)
+  console.log(`  preset:   ${preset}  (${PRESET_DESCRIPTIONS[preset]})`)
+  console.log(`  workDir:  ${workDir}`)
+  console.log("")
+  console.log(`> Run: multiclaw run "describe your requirement" --ui`)
+
+  checkRuntime()
+}
+
+function checkRuntime(): void {
+  const runtimes = ["claude", "codex", "opencode"]
+  const available = runtimes.filter((r) => {
+    try { execSync(`${r} --version`, { stdio: "ignore" }); return true }
+    catch { return false }
+  })
+  if (available.length === 0) {
+    console.log("")
+    console.log("\x1b[33mWarning: No AI runtime detected. Install at least one:\x1b[0m")
+    for (const [name, cmd] of Object.entries(RUNTIME_INSTALL)) {
+      console.log(`  \x1b[2m${name.padEnd(12)} ${cmd}\x1b[0m`)
+    }
+  }
+}

package/src/commands/run.ts

@@ -0,0 +1,97 @@
+import * as path from "path"
+import type { Orchestrator } from "@multiclawcli/core"
+import { Orchestrator as OrchestratorImpl, runtimeRegistry } from "@multiclawcli/core"
+import { loadConfig } from "../loader/loadConfig"
+import { ConsoleReporter } from "../reporters/ConsoleReporter"
+import { FileLogWriter } from "../reporters/FileLogWriter"
+
+export interface RunOptions {
+  config?: string
+  ui?: boolean
+  serverUrl?: string
+  port?: number
+  noLeader?: boolean
+}
+
+export async function runCommand(requirement: string, options: RunOptions): Promise<void> {
+  const config = await loadConfig(options.config, requirement)
+
+  if (options.noLeader) {
+    config.useLeader = false
+  }
+
+  const ts = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19)
+  config.workDir = path.join(config.workDir, ".multiclaw", "runs", `run-${ts}`)
+
+  const runtimeNames = new Set(config.agents.map((a) => a.runtime ?? "claude"))
+  for (const name of runtimeNames) {
+    let rt
+    try { rt = runtimeRegistry.get(name) } catch {
+      console.error(`\x1b[31mError: Unknown runtime "${name}". Supported: claude\x1b[0m`)
+      process.exit(1)
+    }
+    if (!(await rt.checkAvailable())) {
+      console.error(`\x1b[31mError: Runtime "${name}" is not available. Make sure the CLI is installed.\x1b[0m`)
+      process.exit(1)
+    }
+  }
+
+  const orchestrator = new OrchestratorImpl(config)
+
+  new ConsoleReporter().attach(orchestrator.eventBus)
+
+  const logDir = config.logDir ?? path.join(config.workDir, "logs")
+  new FileLogWriter(logDir).attach(orchestrator.eventBus)
+  console.log(`\x1b[2mLogs: ${logDir}\x1b[0m`)
+
+  if (options.ui && options.serverUrl) {
+    console.warn("\x1b[33mWarning: --ui and --server-url cannot be used together. Using --ui.\x1b[0m")
+  }
+
+  if (options.ui) {
+    await attachDashboard(orchestrator, config, options)
+  } else if (options.serverUrl) {
+    await attachRemoteServer(orchestrator, options.serverUrl)
+  }
+
+  const result = await orchestrator.run()
+  process.exit(result.success ? 0 : 1)
+}
+
+async function attachDashboard(
+  orchestrator: Orchestrator,
+  config: Awaited<ReturnType<typeof loadConfig>>,
+  options: RunOptions
+): Promise<void> {
+  const { DashboardServer } = await import("@multiclawcli/dashboard/server")
+  const port = options.port ?? config.dashboard?.port ?? 3210
+  const server = new DashboardServer({ port })
+  await server.start()
+  server.bindEventBus(orchestrator.eventBus)
+
+  const url = `http://localhost:${port}`
+  console.log(`\x1b[36mDashboard: ${url}\x1b[0m`)
+
+  if (config.dashboard?.autoOpen ?? true) {
+    const { default: open } = await import("open")
+    await open(url)
+  }
+}
+
+async function attachRemoteServer(
+  orchestrator: Orchestrator,
+  serverUrl: string
+): Promise<void> {
+  const { WebSocket } = await import("ws")
+  const wsUrl = serverUrl.replace(/^https?/, (p) => p === "https" ? "wss" : "ws")
+  const ws = new WebSocket(wsUrl)
+  await new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(`Connection to serve timed out: ${serverUrl}`)), 5000)
+    ws.on("open", () => { clearTimeout(timer); resolve() })
+    ws.on("error", (err) => { clearTimeout(timer); reject(err) })
+  })
+  console.log(`\x1b[36mConnected to Dashboard server: ${serverUrl}\x1b[0m`)
+  orchestrator.eventBus.subscribe((e) => {
+    if (ws.readyState === ws.OPEN) ws.send(JSON.stringify(e))
+  })
+}

package/src/commands/serve.ts

@@ -0,0 +1,12 @@
+export interface ServeOptions {
+  port?: number
+}
+
+export async function serveCommand(options: ServeOptions): Promise<void> {
+  const { DashboardServer } = await import("@multiclawcli/dashboard/server")
+  const port = options.port ?? 3210
+  const server = new DashboardServer({ port, acceptClientEvents: true })
+  await server.start()
+  console.log(`\x1b[36mDashboard running at: http://localhost:${port}\x1b[0m`)
+  console.log(`  In another terminal run: multiclaw run "<requirement>" --server-url http://localhost:${port}`)
+}

package/src/commands/upgrade.ts

@@ -0,0 +1,35 @@
+import { execSync } from "child_process"
+import { createRequire } from "module"
+
+const require = createRequire(import.meta.url)
+
+export async function upgradeCommand(): Promise<void> {
+  const { version: currentVersion } = require("../../package.json") as { version: string }
+
+  console.log(`Current version: v${currentVersion}`)
+  console.log("Checking for updates...")
+
+  let latestVersion: string
+  try {
+    latestVersion = execSync("npm show multiclaw version", { encoding: "utf8" }).trim()
+  } catch {
+    console.error("\x1b[31mError: Failed to fetch latest version from npm registry\x1b[0m")
+    process.exit(1)
+    return
+  }
+
+  if (latestVersion === currentVersion) {
+    console.log(`\x1b[32m✓\x1b[0m Already on the latest version (v${currentVersion})`)
+    return
+  }
+
+  console.log(`Upgrading multiclaw v${currentVersion} → v${latestVersion}...`)
+
+  try {
+    execSync("npm install -g multiclaw@latest", { stdio: "inherit" })
+    console.log(`\x1b[32m✓\x1b[0m Successfully upgraded to v${latestVersion}`)
+  } catch {
+    console.error("\x1b[31mError: Upgrade failed. Try running manually: npm install -g multiclaw@latest\x1b[0m")
+    process.exit(1)
+  }
+}

package/src/index.ts

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import { Command } from "commander"
+import { runCommand } from "./commands/run"
+import { initCommand } from "./commands/init"
+import { serveCommand } from "./commands/serve"
+import { upgradeCommand } from "./commands/upgrade"
+
+const program = new Command()
+
+program
+  .name("multiclaw")
+  .description("Multi-agent orchestration CLI")
+  .version("0.1.0")
+
+program
+  .command("init")
+  .description("Scaffold a config file (interactive)")
+  .action(() => initCommand())
+
+program
+  .command("run <requirement>")
+  .description("Run an orchestration")
+  .option("--config <path>", "Config file path (default: auto-discover ./multiclaw.config.ts)")
+  .option("--ui", "Start Dashboard and open in browser")
+  .option("--port <port>", "Dashboard port (requires --ui)", (v) => parseInt(v, 10))
+  .option("--server-url <url>", "Connect to a running serve process")
+  .option("--no-leader", "Skip the leader agent and use the default pipeline")
+  .action((requirement, opts) => runCommand(requirement, opts))
+
+program
+  .command("serve")
+  .description("Start a persistent Dashboard server")
+  .option("--port <port>", "Port", (v) => parseInt(v, 10))
+  .action((opts) => serveCommand(opts))
+
+program
+  .command("upgrade")
+  .description("Upgrade multiclaw to the latest version")
+  .action(() => upgradeCommand())
+
+program.parseAsync(process.argv).catch((err: unknown) => {
+  console.error(`\x1b[31mError: ${(err as Error).message ?? err}\x1b[0m`)
+  process.exit(1)
+})

package/src/lib.ts

@@ -0,0 +1,2 @@
+export { defineConfig, agents } from "@multiclawcli/core"
+export type { MultiClawConfig, AgentDefinition } from "@multiclawcli/core"

package/src/loader/loadConfig.ts

@@ -0,0 +1,47 @@
+import * as path from "path"
+import * as fs from "fs"
+import type { MultiClawConfig } from "@multiclawcli/core"
+
+const DEFAULT_CONFIG_NAMES = ["multiclaw.config.ts", "multiclaw.config.js"]
+
+function findConfig(configPath?: string): string {
+  if (configPath) {
+    const abs = path.resolve(process.cwd(), configPath)
+    if (!fs.existsSync(abs)) throw new Error(`Config file not found: ${abs}`)
+    return abs
+  }
+  for (const name of DEFAULT_CONFIG_NAMES) {
+    const abs = path.resolve(process.cwd(), name)
+    if (fs.existsSync(abs)) return abs
+  }
+  throw new Error(`No config file found. Create multiclaw.config.ts in the current directory or use --config to specify a path.`)
+}
+
+export async function loadConfig(configPath?: string, requirement?: string): Promise<MultiClawConfig> {
+  const absPath = findConfig(configPath)
+
+  // The compiled CLI cannot natively import .ts files — register tsx ESM hook
+  // so dynamic import can handle TypeScript config files.
+  const { register } = await import("tsx/esm/api")
+  const unregister = register()
+  let mod: Record<string, unknown>
+  try {
+    mod = await import(absPath)
+  } finally {
+    unregister()
+  }
+  const config: MultiClawConfig = (mod.default ?? mod.config) as MultiClawConfig
+
+  if (!config || !Array.isArray(config.agents)) {
+    throw new Error(`Invalid config format — expected: export default defineConfig({...})`)
+  }
+
+  const configDir = path.dirname(absPath)
+  config.workDir = path.resolve(configDir, config.workDir)
+
+  if (requirement !== undefined) {
+    config.context = { ...config.context, requirement }
+  }
+
+  return config
+}

package/src/reporters/ConsoleReporter.ts

@@ -0,0 +1,93 @@
+import type { EventBus, MultiClawEvent } from "@multiclawcli/core"
+
+// Degraded to plain ASCII when NO_COLOR is set, TERM=dumb, or stdout is not a TTY (pipe/CI).
+const isFancy =
+  !process.env.NO_COLOR &&
+  process.env.TERM !== "dumb" &&
+  process.stdout.isTTY === true
+
+const S = isFancy
+  ? { ok: "✓", fail: "✗", run: "›", retry: "↻", skip: "⊘", warn: "⚠", bullet: "·" }
+  : { ok: "+", fail: "x", run: ">", retry: "~", skip: "-", warn: "!", bullet: "*" }
+
+const C = isFancy
+  ? {
+      reset: "\x1b[0m", bold: "\x1b[1m", dim: "\x1b[2m",
+      cyan: "\x1b[36m", green: "\x1b[32m",
+      yellow: "\x1b[33m", red: "\x1b[31m", purple: "\x1b[35m",
+    }
+  : {
+      reset: "", bold: "", dim: "",
+      cyan: "", green: "",
+      yellow: "", red: "", purple: "",
+    }
+
+export class ConsoleReporter {
+  attach(eventBus: EventBus): () => void {
+    return eventBus.subscribe((e) => this.handle(e))
+  }
+
+  private handle(e: MultiClawEvent): void {
+    switch (e.type) {
+      case "orchestration:start": {
+        const line = (isFancy ? "═" : "=").repeat(50)
+        const edge = isFancy ? ["╔", "║", "╚", "╗", "╝"] : ["+", "|", "+", "+", "+"]
+        console.log(`\n${C.bold}${C.purple}${edge[0]}${line}${edge[3]}`)
+        console.log(`${edge[1]}  ${S.run} ${e.payload.name.padEnd(46)}${edge[1]}`)
+        console.log(`${edge[2]}${line}${edge[4]}${C.reset}`)
+        console.log(`${C.cyan}${S.bullet} Agents: ${e.payload.totalAgents}  Stages: ${e.payload.stages.length}${C.reset}\n`)
+        break
+      }
+      case "stage:start": {
+        const dash = (isFancy ? "─" : "-").repeat(16)
+        console.log(`${C.cyan}${dash} Stage ${e.payload.stageIndex + 1} ${dash}${C.reset}`)
+        break
+      }
+      case "agent:start": {
+        console.log(`${C.purple}${S.run} [${e.payload.agentName}] starting...${C.reset}`)
+        break
+      }
+      case "agent:output": {
+        process.stdout.write(`  ${e.payload.chunk}`)
+        break
+      }
+      case "agent:complete": {
+        const d = (e.payload.duration / 1000).toFixed(1)
+        console.log(`${C.green}${S.ok} ${e.payload.agentName} done (${d}s)${C.reset}`)
+        break
+      }
+      case "agent:failed": {
+        console.log(`${C.red}${S.fail} ${e.payload.agentName} failed: ${e.payload.error}${C.reset}`)
+        break
+      }
+      case "agent:skipped": {
+        console.log(`${C.yellow}${S.skip} ${e.payload.agentName} skipped${C.reset}`)
+        break
+      }
+      case "agent:retrying": {
+        console.log(`${C.yellow}${S.retry} ${e.payload.agentName} retry ${e.payload.attempt}/${e.payload.maxAttempts}: ${e.payload.error}${C.reset}`)
+        break
+      }
+      case "orchestration:complete": {
+        const { success, totalDuration, agentResults } = e.payload
+        const line = (isFancy ? "═" : "=").repeat(50)
+        const edge = isFancy ? ["╔", "║", "╚", "╗", "╝"] : ["+", "|", "+", "+", "+"]
+        const title = success ? `${S.ok} All done` : `${S.warn} Done (with failures)`
+        console.log(`\n${C.bold}${C.purple}${edge[0]}${line}${edge[3]}`)
+        console.log(`${edge[1]}  ${title.padEnd(48)}${edge[1]}`)
+        console.log(`${edge[2]}${line}${edge[4]}${C.reset}`)
+        const nameWidth = Math.max(8, ...agentResults.map((r) => r.agentName.length))
+        const totalStr = `${(totalDuration / 1000).toFixed(1)}s`
+        console.log(`  ~ ${"Total".padEnd(nameWidth)}   ${totalStr.padStart(7)}`)
+        for (const r of agentResults) {
+          const icon = r.status === "success" ? S.ok : S.fail
+          const color = r.status === "success" ? C.green : C.red
+          const dur = `${(r.duration / 1000).toFixed(1)}s`
+          console.log(`  ${color}${icon}${C.reset} ${r.agentName.padEnd(nameWidth)}   ${dur.padStart(7)}`)
+        }
+        console.log()
+        break
+      }
+    }
+  }
+}

package/src/reporters/FileLogWriter.ts

@@ -0,0 +1,43 @@
+import * as fs from "fs"
+import * as path from "path"
+import type { EventBus, MultiClawEvent } from "@multiclawcli/core"
+
+export class FileLogWriter {
+  private streams = new Map<string, fs.WriteStream>()
+
+  constructor(private logDir: string) {
+    fs.mkdirSync(logDir, { recursive: true })
+  }
+
+  attach(eventBus: EventBus): () => void {
+    return eventBus.subscribe((e) => this.handle(e))
+  }
+
+  private handle(e: MultiClawEvent): void {
+    if (e.type === "agent:output") {
+      this.getStream(e.payload.agentId).write(e.payload.chunk)
+    }
+    if (e.type === "orchestration:complete") {
+      fs.writeFileSync(
+        path.join(this.logDir, "report.json"),
+        JSON.stringify(e.payload, null, 2)
+      )
+      this.closeAll()
+    }
+  }
+
+  private getStream(agentId: string): fs.WriteStream {
+    if (!this.streams.has(agentId)) {
+      this.streams.set(
+        agentId,
+        fs.createWriteStream(path.join(this.logDir, `${agentId}.log`))
+      )
+    }
+    return this.streams.get(agentId)!
+  }
+
+  private closeAll(): void {
+    for (const s of this.streams.values()) s.end()
+    this.streams.clear()
+  }
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "outDir": "dist", "rootDir": "src" },
+  "references": [
+    { "path": "../core" },
+    { "path": "../dashboard/tsconfig.server.json" }
+  ],
+  "include": ["src"]
+}