create-claude-flow-codex-ui 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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

@@ -0,0 +1,82 @@
+# create-claude-flow-codex-ui
+
+`npm create` initializer that sets up Claude Flow Codex and adds a live agent-progress admin UI.
+
+## What it does
+
+When you run the initializer, it:
+
+1. Runs:
+
+```bash
+npx claude-flow@alpha init --codex --full
+```
+
+2. Adds admin dashboard files to:
+
+```text
+src/admin/
+```
+
+3. Adds npm scripts in the target project:
+
+- `claudeflow:admin:sync`
+- `claudeflow:admin:sync:once`
+- `claudeflow:admin:ui`
+
+## Usage
+
+Recommended (`npm create`):
+
+```bash
+npm create claude-flow-codex-ui@alpha my-project
+```
+
+Initialize in current directory:
+
+```bash
+npm create claude-flow-codex-ui@alpha .
+```
+
+Equivalent direct invocation:
+
+```bash
+npx create-claude-flow-codex-ui@alpha my-project
+```
+
+Legacy explicit command still supported:
+
+```bash
+npx create-claude-flow-codex-ui@alpha init my-project
+```
+
+Options:
+
+- `--force` overwrite existing `src/admin/*` files and script keys
+- `--skip-claude-flow-init` skip running `npx claude-flow@alpha init --codex --full`
+
+For `npm create`, pass initializer flags after `--`:
+
+```bash
+npm create claude-flow-codex-ui@alpha my-project -- --force
+```
+
+## Run the admin UI in scaffolded project
+
+Terminal 1:
+
+```bash
+npm run claudeflow:admin:sync
+```
+
+Terminal 2:
+
+```bash
+npm run claudeflow:admin:ui
+```
+
+Then open:
+
+```text
+http://127.0.0.1:4173
+```

package/bin/claude-flow-codex-ui.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import "./create-claude-flow-codex-ui.mjs";

package/bin/create-claude-flow-codex-ui.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { run } from "../src/cli/init.mjs";
+
+run(process.argv.slice(2)).catch((error) => {
+  process.stderr.write(`${error.message}\n`);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "create-claude-flow-codex-ui",
+  "version": "0.1.0-alpha.0",
+  "description": "npm create initializer for Claude Flow Codex full setup plus live swarm admin dashboard.",
+  "type": "module",
+  "bin": {
+    "create-claude-flow-codex-ui": "bin/create-claude-flow-codex-ui.mjs",
+    "claude-flow-codex-ui": "bin/create-claude-flow-codex-ui.mjs"
+  },
+  "files": [
+    "bin",
+    "src/cli",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "node --check bin/create-claude-flow-codex-ui.mjs && node --check src/cli/init.mjs",
+    "package:dry-run": "npm pack --dry-run"
+  },
+  "keywords": [
+    "create",
+    "initializer",
+    "boilerplate",
+    "claude-flow",
+    "codex",
+    "swarm",
+    "dashboard",
+    "telemetry"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha"
+  },
+  "license": "MIT"
+}

package/src/cli/init.mjs

@@ -0,0 +1,246 @@
+import { spawn } from "node:child_process";
+import { access, copyFile, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(__dirname, "..", "..");
+const templateRoot = path.join(packageRoot, "templates", "admin");
+
+const RUNTIME_GITIGNORE_ENTRIES = [
+  ".codex/",
+  ".agents/",
+  ".claude-flow/",
+  ".swarm/",
+];
+
+const ADMIN_SCRIPTS = {
+  "claudeflow:admin:sync": "node src/admin/sync-telemetry.mjs --interval 2000",
+  "claudeflow:admin:sync:once": "node src/admin/sync-telemetry.mjs --once",
+  "claudeflow:admin:ui": "node src/admin/dev-server.mjs",
+};
+
+export async function run(argv) {
+  const args = normalizeArgs(argv);
+
+  if (args.includes("-h") || args.includes("--help") || args[0] === "help") {
+    printHelp();
+    return;
+  }
+
+  const options = parseOptions(args);
+  const targetDir = path.resolve(process.cwd(), options.targetDir || ".");
+
+  await mkdir(targetDir, { recursive: true });
+
+  log(`Target directory: ${targetDir}`);
+
+  if (!options.skipClaudeFlowInit) {
+    await runClaudeFlowInit(targetDir);
+  } else {
+    log("Skipping claude-flow init (--skip-claude-flow-init).", "warn");
+  }
+
+  const copied = await copyTemplateTree(templateRoot, path.join(targetDir, "src", "admin"), {
+    force: options.force,
+  });
+  log(`Admin UI files copied: ${copied.copied} (skipped: ${copied.skipped})`);
+
+  const pkgResult = await patchTargetPackageJson(targetDir, { force: options.force });
+  log(`package.json ${pkgResult.created ? "created" : "updated"}; scripts added: ${pkgResult.addedScripts}`);
+
+  await ensureGitignoreEntries(targetDir, RUNTIME_GITIGNORE_ENTRIES);
+  log(".gitignore updated with Claude Flow runtime entries.");
+
+  log("Scaffold complete.", "success");
+  log("Run 'npm run claudeflow:admin:sync' and 'npm run claudeflow:admin:ui' in the target project.");
+}
+
+function normalizeArgs(argv) {
+  const args = [...argv];
+  if (!args.length) {
+    return [];
+  }
+  if (args[0] === "init") {
+    return args.slice(1);
+  }
+  return args;
+}
+
+function parseOptions(tokens) {
+  const options = {
+    targetDir: ".",
+    skipClaudeFlowInit: false,
+    force: false,
+  };
+
+  for (let i = 0; i < tokens.length; i += 1) {
+    const token = tokens[i];
+    if (token === "--skip-claude-flow-init") {
+      options.skipClaudeFlowInit = true;
+      continue;
+    }
+    if (token === "--force") {
+      options.force = true;
+      continue;
+    }
+    if (token.startsWith("--")) {
+      throw new Error(`Unknown option: ${token}`);
+    }
+    if (options.targetDir !== ".") {
+      throw new Error(`Unexpected argument: ${token}`);
+    }
+    options.targetDir = token;
+  }
+
+  return options;
+}
+
+async function runClaudeFlowInit(targetDir) {
+  log("Running: npx claude-flow@alpha init --codex --full");
+  const npxCommand = process.platform === "win32" ? "npx.cmd" : "npx";
+
+  await runCommand(npxCommand, ["claude-flow@alpha", "init", "--codex", "--full"], {
+    cwd: targetDir,
+  });
+}
+
+async function patchTargetPackageJson(targetDir, { force }) {
+  const packageJsonPath = path.join(targetDir, "package.json");
+  let pkg;
+  let created = false;
+
+  if (await fileExists(packageJsonPath)) {
+    const raw = await readFile(packageJsonPath, "utf8");
+    pkg = JSON.parse(raw);
+  } else {
+    created = true;
+    pkg = {
+      name: inferPackageName(targetDir),
+      version: "0.1.0",
+      private: true,
+      scripts: {},
+    };
+  }
+
+  if (!pkg.scripts || typeof pkg.scripts !== "object") {
+    pkg.scripts = {};
+  }
+
+  let addedScripts = 0;
+  for (const [name, command] of Object.entries(ADMIN_SCRIPTS)) {
+    if (!(name in pkg.scripts) || force) {
+      pkg.scripts[name] = command;
+      addedScripts += 1;
+    }
+  }
+
+  const serialized = `${JSON.stringify(pkg, null, 2)}\n`;
+  await writeFile(packageJsonPath, serialized, "utf8");
+
+  return { created, addedScripts };
+}
+
+async function ensureGitignoreEntries(targetDir, entries) {
+  const gitignorePath = path.join(targetDir, ".gitignore");
+  const current = (await fileExists(gitignorePath))
+    ? await readFile(gitignorePath, "utf8")
+    : "";
+
+  const lines = current.split(/\r?\n/);
+  const toAdd = entries.filter((entry) => !lines.includes(entry));
+
+  if (!toAdd.length) {
+    return;
+  }
+
+  const prefix = current && !current.endsWith("\n") ? "\n" : "";
+  const content = `${current}${prefix}${toAdd.join("\n")}\n`;
+  await writeFile(gitignorePath, content, "utf8");
+}
+
+async function copyTemplateTree(fromDir, toDir, { force }) {
+  const counters = { copied: 0, skipped: 0 };
+  await mkdir(toDir, { recursive: true });
+
+  const entries = await readdir(fromDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const sourcePath = path.join(fromDir, entry.name);
+    const targetPath = path.join(toDir, entry.name);
+
+    if (entry.isDirectory()) {
+      const nested = await copyTemplateTree(sourcePath, targetPath, { force });
+      counters.copied += nested.copied;
+      counters.skipped += nested.skipped;
+      continue;
+    }
+
+    const exists = await fileExists(targetPath);
+    if (exists && !force) {
+      counters.skipped += 1;
+      continue;
+    }
+
+    await mkdir(path.dirname(targetPath), { recursive: true });
+    await copyFile(sourcePath, targetPath);
+    counters.copied += 1;
+  }
+
+  return counters;
+}
+
+async function runCommand(command, args, options = {}) {
+  await new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd || process.cwd(),
+      stdio: "inherit",
+      shell: false,
+    });
+
+    child.on("error", reject);
+    child.on("exit", (code) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+      reject(new Error(`Command failed (${code}): ${command} ${args.join(" ")}`));
+    });
+  });
+}
+
+function inferPackageName(targetDir) {
+  const raw = path.basename(targetDir).toLowerCase();
+  const safe = raw
+    .replace(/[^a-z0-9._-]/g, "-")
+    .replace(/--+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return safe || "claude-flow-project";
+}
+
+async function fileExists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function log(message, level = "info") {
+  const tag = level.toUpperCase().padEnd(7, " ");
+  process.stdout.write(`[${tag}] ${message}\n`);
+}
+
+function printHelp() {
+  process.stdout.write(
+    `create-claude-flow-codex-ui\n\n` +
+      `Usage:\n` +
+      `  npm create claude-flow-codex-ui@alpha [target-dir] [-- --force] [-- --skip-claude-flow-init]\n` +
+      `  npx create-claude-flow-codex-ui@alpha [target-dir] [--force] [--skip-claude-flow-init]\n` +
+      `  npx create-claude-flow-codex-ui@alpha init [target-dir] [--force] [--skip-claude-flow-init]\n\n` +
+      `What it does:\n` +
+      `  1) Runs: npx claude-flow@alpha init --codex --full\n` +
+      `  2) Adds a live admin UI at src/admin for agent/task progress\n` +
+      `  3) Adds npm scripts for telemetry sync and dashboard server\n`
+  );
+}

package/templates/admin/README.md

@@ -0,0 +1,49 @@
+# Swarm Admin Visualization
+
+This dashboard visualizes live agent activity from `src/admin/state/swarm-state.json`.
+
+## 1) Start Telemetry Sync (real data)
+
+```bash
+node src/admin/sync-telemetry.mjs --interval 2000
+```
+
+By default it reads:
+- `.claude-flow/agents/store.json`
+- `.claude-flow/tasks/store.json`
+
+And writes:
+- `src/admin/state/swarm-state.json`
+
+Optional flags:
+- `--once` (single sync tick and exit)
+- `--swarm-id <id>`
+- `--orch-id <id>`
+- `--agents-path <path>`
+- `--tasks-path <path>`
+- `--output <path>`
+- `--max-events <n>`
+
+## 2) Start Dashboard Server
+
+```bash
+node src/admin/dev-server.mjs
+```
+
+Open:
+- `http://127.0.0.1:4173`
+
+The dashboard now uses a WebSocket stream (`/__swarm_ws`) for state updates and falls back to HTTP polling if the socket drops.
+
+## Validation (one-shot)
+
+```bash
+node src/admin/sync-telemetry.mjs --once
+```
+
+This confirms state JSON can be generated from live Claude Flow stores.
+
+## Simulation Mode
+
+Add `?simulate=1` if you want visual playback in addition to real telemetry:
+- `http://127.0.0.1:4173/?simulate=1`