shadow-claw 1.23.4 → 1.24.1

package/README.md

@@ -2,23 +2,43 @@
 
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/xt-ml/shadow-claw)
 
-A browser-native, fully-featured AI assistant. TypeScript + Web Components + IndexedDB + File System API.
+A browser-native, fully-featured AI assistant — runs as a PWA, a native desktop app, a Node.js server, and via the `shadow-claw` CLI. TypeScript + Web Components + IndexedDB + File System API.
 
 [![ShadowClaw Screenshot](https://xt-ml.github.io/shadow-claw/assets/screenshots/shadow-claw-screenshot-1920x1052.png)](https://xt-ml.github.io/shadow-claw/)
 
 ## Quick Start
 
+### 1. Launch ShadowClaw instantly without cloning the repo
+
 ```bash
-npm install && npm run dev  # Dev server → http://localhost:8888
+npx shadow-claw dev --open
 ```
 
-Open Settings, select a provider (or use browser Prompt API), and start chatting.
+Open Settings, select your AI provider (or use the in-browser Prompt API / local models), and start chatting.
+
+### 2. Scaffold a Project or Knowledge Hub
+
+Create a custom template with pages and site configuration:
+
+```bash
+npx shadow-claw init my-assistant
+cd my-assistant
+npx shadow-claw dev --open
+```
+
+### 3. From Source (Contributing / Development)
+
+```bash
+git clone https://github.com/xt-ml/shadow-claw.git
+cd shadow-claw
+npm install && npm run dev  # Dev server → http://localhost:8888
+```
 
-**Desktop:** `npm run electron` or `npm run electron:build` for distributable.
+**Desktop App:** `npm run electron` or `npm run electron:build` for distributable installer.
 
 ## What is ShadowClaw?
 
-A fully-functional agent runtime that runs entirely in the browser—no AI processing on a server. Built with TypeScript, it provides:
+A fully-functional agent runtime built on browser-native technology — the orchestration and tool-use loop run client-side, with AI inference routing to remote APIs, local servers, or in-browser models depending on your configuration. Built with TypeScript, it provides:
 
 - **Multi-model support**: OpenRouter, Anthropic, Google Gemini, AWS Bedrock, Ollama, Llamafile, Mesh LLM, Transformers.js, and browser-native Prompt API
 - **Web Components UI**: Native Custom Elements + TC39 Signals for reactive updates
@@ -378,6 +398,23 @@ npm run electron:build:win   # Build Electron for Windows
 npm run electron:build:mac   # Build Electron for macOS
 ```
 
+### CLI Runtime Commands
+
+The `shadow-claw` CLI connects to a running server or browser clients to interact with active sessions:
+
+```bash
+npx shadow-claw clients                              # List connected browser/Electron clients
+npx shadow-claw send "your prompt" --client <id>    # Send a message to a connected client
+npx shadow-claw backup                               # Trigger OPFS workspace backup
+npx shadow-claw backup list                          # List available backup snapshots
+npx shadow-claw backup delete --backup-id <id>      # Delete a backup snapshot
+npx shadow-claw tasks --client <id>                  # List scheduled tasks on a client
+npx shadow-claw webrtc listen                        # Start headless WebRTC DataChannel daemon
+npx shadow-claw peer-id                              # Get or generate persistent CLI Peer ID
+```
+
+Commands support `--transport webrtc` for direct peer-to-peer DataChannel execution with connected browser clients. Control plane authentication uses `SHADOWCLAW_CONTROL_TOKEN` (env) or `--token` flag. The control plane endpoint and token are printed to the console on server start.
+
 ## License
 
 AGPLv3. Core logic derived from [openbrowserclaw](https://github.com/sachaa/openbrowserclaw) (MIT).

package/bin/cli.mjs

@@ -8,6 +8,12 @@ import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 
 import { runBuild } from "./build/build.mjs";
+import { runClientsCommand } from "./commands/clients.mjs";
+import { runSendCommand } from "./commands/send.mjs";
+import { runBackupCommand } from "./commands/backup.mjs";
+import { runTasksCommand } from "./commands/tasks.mjs";
+import { runPeerIdCommand } from "./commands/peer-id.mjs";
+import { runWebRtcListenCommand } from "./commands/webrtc-listen.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -421,4 +427,164 @@ slug: "home"
     }
   });
 
+// ---------------------------------------------------------------------------
+// PEER-ID / WEBRTC COMMAND
+// ---------------------------------------------------------------------------
+program
+  .command("peer-id [action] [customId]")
+  .alias("webrtc-peer-id")
+  .description(
+    "Get, generate, or renew the WebRTC CLI peer ID stored in .cache/cli-peer-id",
+  )
+  .option(
+    "-r, --renew",
+    "Force renewal / generation of a new WebRTC CLI peer ID",
+  )
+  .option("--set <id>", "Set a specific custom WebRTC CLI peer ID")
+  .option("--cache-dir <dir>", "Custom cache directory (defaults to .cache)")
+  .option("-q, --quiet", "Output only the peer ID string")
+  .option("--json", "Output peer ID and file path as JSON")
+  .action(async (action, customId, options) => {
+    const opts = { ...options };
+    if (customId && !opts.set) {
+      opts.set = customId;
+    }
+    await runPeerIdCommand(action, opts);
+  });
+
+program
+  .command("webrtc [action] [customId]")
+  .description(
+    "Manage WebRTC CLI configuration and peer identity (.cache/cli-peer-id)\n\n" +
+      "  Actions:\n" +
+      "    (default)  Show or generate the CLI peer ID\n" +
+      "    listen     Register as a live PeerJS peer — browser tabs can then\n" +
+      "               connect directly without a control-plane connection",
+  )
+  .option(
+    "-r, --renew",
+    "Force renewal / generation of a new WebRTC CLI peer ID",
+  )
+  .option("--set <id>", "Set a specific custom WebRTC CLI peer ID")
+  .option("--cache-dir <dir>", "Custom cache directory (defaults to .cache)")
+  .option("-q, --quiet", "Output only the peer ID string")
+  .option("--json", "Output peer ID and file path as JSON")
+  // listen-specific options
+  .option("--host <host>", "PeerJS signaling server host (for listen)")
+  .option("--port <port>", "PeerJS signaling server port (for listen)", "8888")
+  .option("--path <path>", "PeerJS signaling server path (for listen)", "/")
+  .option(
+    "--secure",
+    "Use TLS (wss://) for the signaling server (for listen)",
+    false,
+  )
+  .option(
+    "--trusted-peer <id>",
+    "Accept connections only from this peer ID (repeatable, for listen)",
+    (v, prev) => (prev ? [...prev, v] : [v]),
+    [],
+  )
+  .option("--verbose", "Verbose connection logging (for listen)", false)
+  .option("--renew-peer-id", "Renew CLI peer ID before listening", false)
+  .action(async (action, customId, options) => {
+    if (action === "listen") {
+      await runWebRtcListenCommand(options);
+      return;
+    }
+    const opts = { ...options };
+    if (customId && !opts.set) {
+      opts.set = customId;
+    }
+    await runPeerIdCommand(action, opts);
+  });
+
+// ---------------------------------------------------------------------------
+// CLIENTS COMMAND
+// ---------------------------------------------------------------------------
+program
+  .command("clients")
+  .description("List connected / registered browser and Electron clients")
+  .option("--host <host>", "Control plane host")
+  .option("--port <port>", "Control plane port")
+  .option("--token <token>", "Control token")
+  .option("--transport <transport>", "Transport to use: http | webrtc", "http")
+  .option("--peer-id <id>", "Custom WebRTC CLI peer ID")
+  .option(
+    "--renew-peer-id",
+    "Renew WebRTC CLI peer ID before connecting",
+    false,
+  )
+  .option("--cache-dir <dir>", "Custom cache directory")
+  .action(async (options) => {
+    await runClientsCommand(options);
+  });
+
+// ---------------------------------------------------------------------------
+// SEND COMMAND
+// ---------------------------------------------------------------------------
+program
+  .command("send <message>")
+  .description("Send a message/prompt to a connected client")
+  .option("--client <id>", "Target client ID (defaults to first available)")
+  .option("--group <groupId>", "Target conversation group ID")
+  .option("--host <host>", "Control plane host")
+  .option("--port <port>", "Control plane port")
+  .option("--token <token>", "Control token")
+  .option("--transport <transport>", "Transport to use: http | webrtc", "http")
+  .option("--peer-id <id>", "Custom WebRTC CLI peer ID")
+  .option("--renew-peer-id", "Renew WebRTC CLI peer ID before sending", false)
+  .option("--cache-dir <dir>", "Custom cache directory")
+  .action(async (message, options) => {
+    await runSendCommand(message, options);
+  });
+
+// ---------------------------------------------------------------------------
+// BACKUP COMMAND
+// ---------------------------------------------------------------------------
+program
+  .command("backup [action]")
+  .description(
+    "Trigger or manage client workspace backups (trigger | list | delete)",
+  )
+  .option("--client <id>", "Client ID")
+  .option("--backup-id <id>", "Backup ID (for delete)")
+  .option("--group <groupId>", "Specific workspace group ID")
+  .option("--host <host>", "Control plane host")
+  .option("--port <port>", "Control plane port")
+  .option("--token <token>", "Control token")
+  .option("--transport <transport>", "Transport to use: http | webrtc", "http")
+  .option("--peer-id <id>", "Custom WebRTC CLI peer ID")
+  .option(
+    "--renew-peer-id",
+    "Renew WebRTC CLI peer ID before connecting",
+    false,
+  )
+  .option("--cache-dir <dir>", "Custom cache directory")
+  .action(async (action, options) => {
+    await runBackupCommand(action || "trigger", options);
+  });
+
+// ---------------------------------------------------------------------------
+// TASKS COMMAND
+// ---------------------------------------------------------------------------
+program
+  .command("tasks")
+  .description("List scheduled tasks on a connected client")
+  .option("--client <id>", "Target client ID")
+  .option("--group <groupId>", "Filter tasks by conversation group ID")
+  .option("--host <host>", "Control plane host")
+  .option("--port <port>", "Control plane port")
+  .option("--token <token>", "Control token")
+  .option("--transport <transport>", "Transport to use: http | webrtc", "http")
+  .option("--peer-id <id>", "Custom WebRTC CLI peer ID")
+  .option(
+    "--renew-peer-id",
+    "Renew WebRTC CLI peer ID before connecting",
+    false,
+  )
+  .option("--cache-dir <dir>", "Custom cache directory")
+  .action(async (options) => {
+    await runTasksCommand(options);
+  });
+
 program.parse(process.argv);

package/bin/cli.test.mjs

@@ -49,6 +49,66 @@ describe("shadow-claw CLI", () => {
     expect(stdout).toContain("run");
     expect(stdout).toContain("serve");
     expect(stdout).toContain("init");
+    expect(stdout).toContain("clients");
+    expect(stdout).toContain("send");
+    expect(stdout).toContain("backup");
+    expect(stdout).toContain("tasks");
+    expect(stdout).toContain("peer-id");
+    expect(stdout).toContain("webrtc");
+  });
+
+  it("manages WebRTC CLI peer ID with peer-id command", async () => {
+    const cacheDir = path.join(tempDir, ".cache");
+
+    // 1. Get/generate new peer ID
+    const { stdout: out1 } = await execFileAsync(process.execPath, [
+      cliPath,
+      "peer-id",
+      "--cache-dir",
+      cacheDir,
+      "--json",
+    ]);
+    const json1 = JSON.parse(out1);
+    expect(json1.peerId).toMatch(/^cli-[0-9a-z]+$/);
+    expect(json1.renewed).toBe(true);
+
+    // 2. Subsequent call returns existing peer ID
+    const { stdout: out2 } = await execFileAsync(process.execPath, [
+      cliPath,
+      "peer-id",
+      "--cache-dir",
+      cacheDir,
+      "-q",
+    ]);
+    expect(out2.trim()).toBe(json1.peerId);
+
+    // 3. Renew peer ID
+    const { stdout: out3 } = await execFileAsync(process.execPath, [
+      cliPath,
+      "peer-id",
+      "--renew",
+      "--cache-dir",
+      cacheDir,
+      "--json",
+    ]);
+    const json3 = JSON.parse(out3);
+    expect(json3.peerId).not.toBe(json1.peerId);
+    expect(json3.renewed).toBe(true);
+
+    // 4. Set custom peer ID
+    const { stdout: out4 } = await execFileAsync(process.execPath, [
+      cliPath,
+      "peer-id",
+      "--set",
+      "my-custom-cli-peer",
+      "--cache-dir",
+      cacheDir,
+      "-q",
+    ]);
+    expect(out4.trim()).toBe("my-custom-cli-peer");
+
+    const saved = await readFile(path.join(cacheDir, "cli-peer-id"), "utf8");
+    expect(saved.trim()).toBe("my-custom-cli-peer");
   });
 
   it("initializes a new template with init command", async () => {

package/bin/commands/backup.mjs

@@ -0,0 +1,70 @@
+/**
+ * ShadowClaw CLI — `backup` command
+ * Triggers or lists workspace backups.
+ */
+
+import { CliControlClient } from "../utils/control-client.mjs";
+
+export async function runBackupCommand(action = "trigger", options = {}) {
+  const client = new CliControlClient(options);
+
+  try {
+    if (action === "list") {
+      const backups = await client.listBackups(options.client);
+      if (!backups || backups.length === 0) {
+        console.log("No backups found.");
+        return;
+      }
+
+      console.log(`Available backups (${backups.length}):\n`);
+      backups.forEach((b, idx) => {
+        const dateStr = new Date(b.timestamp).toISOString();
+        const sizeMb = (b.totalBytes / (1024 * 1024)).toFixed(2);
+        console.log(`  ${idx + 1}. [${b.id}] Client: ${b.clientId}`);
+        console.log(`     Date:  ${dateStr}`);
+        console.log(`     Files: ${b.fileCount} (${sizeMb} MB)\n`);
+      });
+      return;
+    }
+
+    if (action === "delete") {
+      if (!options.backupId) {
+        console.error("Error: --backup-id is required for delete action.");
+        process.exitCode = 1;
+        return;
+      }
+      await client.deleteBackup(options.backupId, options.client);
+      console.log(`Backup ${options.backupId} deleted.`);
+      return;
+    }
+
+    // Default: Trigger backup
+    let targetClientId = options.client;
+    if (!targetClientId) {
+      const clients = await client.listClients();
+      if (!clients || clients.length === 0) {
+        console.error("Error: No clients are connected to back up.");
+        process.exitCode = 1;
+        return;
+      }
+      targetClientId = clients[0].clientId;
+    }
+
+    console.log(`Requesting backup from client ${targetClientId}...`);
+    const result = await client.sendCommand(targetClientId, "trigger-backup", {
+      groupId: options.group,
+      token: client.token,
+    });
+
+    if (result.success) {
+      console.log("Backup completed successfully.");
+      console.log(JSON.stringify(result.data, null, 2));
+    } else {
+      console.error(`Backup failed: ${result.error}`);
+      process.exitCode = 1;
+    }
+  } catch (err) {
+    console.error(`Error executing backup command: ${err.message}`);
+    process.exitCode = 1;
+  }
+}

package/bin/commands/clients.mjs

@@ -0,0 +1,41 @@
+/**
+ * ShadowClaw CLI — `clients` command
+ * Lists connected clients and their capabilities.
+ */
+
+import { CliControlClient } from "../utils/control-client.mjs";
+
+export async function runClientsCommand(options = {}) {
+  const client = new CliControlClient(options);
+  try {
+    const clients = await client.listClients();
+
+    if (!clients || clients.length === 0) {
+      console.log("No clients currently registered or connected.");
+      return;
+    }
+
+    console.log(`Connected / registered clients (${clients.length}):\n`);
+    clients.forEach((c, idx) => {
+      const lastSeenSec = Math.max(
+        0,
+        Math.floor((Date.now() - c.lastSeen) / 1000),
+      );
+      const lastSeenStr =
+        lastSeenSec < 60
+          ? `${lastSeenSec}s ago`
+          : `${Math.floor(lastSeenSec / 60)}m ago`;
+
+      console.log(`  ${idx + 1}. ${c.deviceLabel} (id: ${c.clientId})`);
+      if (c.peerId) {
+        console.log(`     Peer ID:      ${c.peerId}`);
+      }
+      console.log(`     Capabilities: ${c.capabilities.join(", ") || "none"}`);
+      console.log(`     Version:      ${c.version}`);
+      console.log(`     Last seen:    ${lastSeenStr}\n`);
+    });
+  } catch (err) {
+    console.error(`Error fetching clients: ${err.message}`);
+    process.exitCode = 1;
+  }
+}

package/bin/commands/peer-id.mjs

@@ -0,0 +1,76 @@
+/**
+ * ShadowClaw CLI — `peer-id` command
+ * Manages the WebRTC CLI peer ID stored in .cache/cli-peer-id.
+ */
+
+import {
+  getCliPeerIdFilePath,
+  getOrCreateCliPeerId,
+  readCliPeerId,
+  renewCliPeerId,
+} from "../utils/webrtc-control-client.mjs";
+
+export async function runPeerIdCommand(action = "get", options = {}) {
+  const cacheDir = options.cacheDir;
+  const filePath = getCliPeerIdFilePath(cacheDir);
+
+  const shouldRenew = Boolean(
+    options.renew ||
+    action === "renew" ||
+    action === "generate" ||
+    action === "new",
+  );
+  const customSetId =
+    options.set || (action === "set" && options.id ? options.id : null);
+
+  let peerId = "";
+  let isRenewed = false;
+
+  if (customSetId) {
+    peerId = renewCliPeerId(customSetId, cacheDir);
+    isRenewed = true;
+  } else if (shouldRenew) {
+    peerId = renewCliPeerId(undefined, cacheDir);
+    isRenewed = true;
+  } else {
+    const existing = readCliPeerId(cacheDir);
+    if (existing) {
+      peerId = existing;
+      isRenewed = false;
+    } else {
+      peerId = getOrCreateCliPeerId(undefined, cacheDir);
+      isRenewed = true;
+    }
+  }
+
+  if (options.quiet) {
+    console.log(peerId);
+    return { peerId, filePath, isRenewed };
+  }
+
+  if (options.json) {
+    console.log(
+      JSON.stringify(
+        {
+          peerId,
+          filePath,
+          renewed: isRenewed,
+        },
+        null,
+        2,
+      ),
+    );
+    return { peerId, filePath, isRenewed };
+  }
+
+  if (customSetId) {
+    console.log(`WebRTC CLI Peer ID set to: ${peerId}`);
+  } else if (isRenewed) {
+    console.log(`WebRTC CLI Peer ID created/renewed: ${peerId}`);
+  } else {
+    console.log(`WebRTC CLI Peer ID: ${peerId}`);
+  }
+  console.log(`Stored in: ${filePath}`);
+
+  return { peerId, filePath, isRenewed };
+}

package/bin/commands/peer-id.test.mjs

@@ -0,0 +1,104 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  jest,
+  describe,
+  it,
+  expect,
+  beforeEach,
+  afterEach,
+} from "@jest/globals";
+import { runPeerIdCommand } from "./peer-id.mjs";
+import {
+  getCliPeerIdFilePath,
+  readCliPeerId,
+} from "../utils/webrtc-control-client.mjs";
+
+describe("runPeerIdCommand", () => {
+  let tempDir;
+  let logSpy;
+
+  beforeEach(() => {
+    tempDir = path.join(
+      os.tmpdir(),
+      "test-cli-peer-id-" +
+        Date.now() +
+        "-" +
+        Math.random().toString(36).slice(2),
+    );
+    logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    if (logSpy) logSpy.mockRestore();
+    try {
+      if (fs.existsSync(tempDir)) {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+      }
+    } catch (_) {}
+  });
+
+  it("creates and retrieves a new peer ID if none exists", async () => {
+    const result = await runPeerIdCommand("get", { cacheDir: tempDir });
+    expect(result.peerId).toMatch(/^cli-[0-9a-z]+$/);
+    expect(result.isRenewed).toBe(true);
+
+    const saved = readCliPeerId(tempDir);
+    expect(saved).toBe(result.peerId);
+  });
+
+  it("returns existing peer ID without changing it on subsequent calls", async () => {
+    const res1 = await runPeerIdCommand("get", { cacheDir: tempDir });
+    const res2 = await runPeerIdCommand("get", { cacheDir: tempDir });
+
+    expect(res2.peerId).toBe(res1.peerId);
+    expect(res2.isRenewed).toBe(false);
+  });
+
+  it("renews peer ID when action is 'renew'", async () => {
+    const res1 = await runPeerIdCommand("get", { cacheDir: tempDir });
+    const res2 = await runPeerIdCommand("renew", { cacheDir: tempDir });
+
+    expect(res2.peerId).not.toBe(res1.peerId);
+    expect(res2.isRenewed).toBe(true);
+    expect(readCliPeerId(tempDir)).toBe(res2.peerId);
+  });
+
+  it("renews peer ID when --renew flag is passed", async () => {
+    const res1 = await runPeerIdCommand("get", { cacheDir: tempDir });
+    const res2 = await runPeerIdCommand("get", {
+      cacheDir: tempDir,
+      renew: true,
+    });
+
+    expect(res2.peerId).not.toBe(res1.peerId);
+    expect(res2.isRenewed).toBe(true);
+  });
+
+  it("sets a custom peer ID when --set is passed", async () => {
+    const res = await runPeerIdCommand("get", {
+      cacheDir: tempDir,
+      set: "custom-my-peer",
+    });
+
+    expect(res.peerId).toBe("custom-my-peer");
+    expect(res.isRenewed).toBe(true);
+    expect(readCliPeerId(tempDir)).toBe("custom-my-peer");
+  });
+
+  it("supports quiet mode and json mode", async () => {
+    const resQuiet = await runPeerIdCommand("get", {
+      cacheDir: tempDir,
+      quiet: true,
+    });
+    expect(resQuiet.peerId).toBeDefined();
+
+    const resJson = await runPeerIdCommand("get", {
+      cacheDir: tempDir,
+      json: true,
+    });
+    expect(resJson.peerId).toBe(resQuiet.peerId);
+    expect(resJson.filePath).toBe(getCliPeerIdFilePath(tempDir));
+  });
+});

package/bin/commands/send.mjs

@@ -0,0 +1,51 @@
+/**
+ * ShadowClaw CLI — `send` command
+ * Dispatches a prompt / message to a connected client.
+ */
+
+import { CliControlClient } from "../utils/control-client.mjs";
+
+export async function runSendCommand(message, options = {}) {
+  if (!message || typeof message !== "string" || !message.trim()) {
+    console.error("Error: Message cannot be empty.");
+    process.exitCode = 1;
+    return;
+  }
+
+  const client = new CliControlClient(options);
+  try {
+    let targetClientId = options.client;
+
+    if (!targetClientId) {
+      const clients = await client.listClients();
+      if (!clients || clients.length === 0) {
+        console.error("Error: No clients are connected.");
+        process.exitCode = 1;
+        return;
+      }
+      targetClientId = clients[0].clientId;
+      console.log(
+        `Targeting client: ${clients[0].deviceLabel} (${targetClientId})`,
+      );
+    }
+
+    console.log(`Sending message to ${targetClientId}...`);
+    const result = await client.sendCommand(targetClientId, "send-message", {
+      text: message.trim(),
+      groupId: options.group,
+    });
+
+    if (result.success) {
+      console.log("Message successfully dispatched.");
+      if (result.data) {
+        console.log(JSON.stringify(result.data, null, 2));
+      }
+    } else {
+      console.error(`Error from client: ${result.error}`);
+      process.exitCode = 1;
+    }
+  } catch (err) {
+    console.error(`Error sending message: ${err.message}`);
+    process.exitCode = 1;
+  }
+}