clawmatrix 0.3.1 → 0.4.0

package/cli/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "clawmatrix-cli",
+  "version": "0.3.1",
+  "description": "ClawMatrix mesh cluster CLI — zero-dependency, connects directly to OpenClaw gateway via WebSocket",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "clawmatrix": "./bin/clawmatrix.mjs"
+  },
+  "files": [
+    "bin/",
+    "skills/"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "openclaw",
+    "clawmatrix",
+    "mesh",
+    "cluster",
+    "cli"
+  ],
+  "scripts": {
+    "test": "bun test"
+  }
+}

package/cli/skills/clawmatrix/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: clawmatrix
+description: Use the clawmatrix CLI to interact with remote devices (phones, computers, servers) in a mesh cluster — run tools, check location, get battery status, read/write files, execute commands, and more on any connected node.
+---
+
+Use the `clawmatrix` CLI to interact with the ClawMatrix mesh cluster. Remote nodes can be phones (iPhone/Android), computers, or servers. You can invoke any tool available on remote nodes — including getting device location, battery status, running shell commands, reading/writing files, and more.
+
+All commands output LLM-friendly text (no ANSI colors) when stdout is not a TTY.
+
+## Quick Start
+
+1. Run `clawmatrix status` to see connected nodes and their capabilities
+2. Run `clawmatrix tools <nodeId>` to see what tools a node offers
+3. Run `clawmatrix call <nodeId> <tool> '<params>'` to invoke a tool
+
+## Cluster Status
+
+```bash
+clawmatrix status          # Cluster topology: peers, agents, models, tags
+clawmatrix status --json   # Structured JSON output
+clawmatrix check <nodeId>  # Quick reachability check with latency
+```
+
+Always start with `clawmatrix status` to understand the current topology before performing other operations.
+
+## Remote Tools
+
+```bash
+clawmatrix tools                        # List all remote tools (compact)
+clawmatrix tools <nodeId>               # Tools on a specific node
+clawmatrix tools --describe <tool>      # Full usage and parameter schema
+clawmatrix tools --filter <keyword>     # Search by name or description
+```
+
+Use `--describe` to understand a tool's parameters before calling it.
+
+## Invoke Tools
+
+```bash
+clawmatrix call <nodeId> <tool> '<json-params>'    # Single tool invocation
+clawmatrix call <nodeId> <tool> '<json-params>' -t 30000  # With timeout (ms)
+```
+
+```bash
+clawmatrix batch <nodeId> '[{"tool":"t1","params":{}},{"tool":"t2","params":{}}]'
+clawmatrix batch <nodeId> --no-stop-on-error '[...]'  # Continue on failure
+```
+
+Batch supports stdin: `echo '<json>' | clawmatrix batch <nodeId>`
+
+## Models
+
+```bash
+clawmatrix models                   # All cluster models
+clawmatrix models --node <nodeId>   # Filter by node
+```
+
+## Events
+
+```bash
+clawmatrix events                       # Unconsumed events
+clawmatrix events --type <type>         # Filter by type
+clawmatrix events --source <nodeId>     # Filter by source node
+clawmatrix events --consume <id1,id2>   # Mark events as consumed
+clawmatrix events --all                 # Include consumed events
+```
+
+## Peer Approval
+
+```bash
+clawmatrix approve <approvalId>         # Approve a pending peer
+clawmatrix deny <approvalId>            # Deny a pending peer
+clawmatrix approval list                # List pending/approved/denied peers
+clawmatrix approval revoke <nodeId>     # Revoke an approved peer
+```
+
+## Notifications (Dynamic Island / Live Activity)
+
+Push progress notifications to the user's iPhone via `clawmatrix notify`. This triggers the Dynamic Island and lock screen Live Activity.
+
+**Use this proactively when running long tasks** (iOS builds, large refactors, test suites, batch operations) so the user can track progress without watching the terminal.
+
+```bash
+# Start a notification
+clawmatrix notify "iOS 构建" --detail "正在编译..."
+# Returns: {"taskId":"<id>", "action":"start", "targets":1}
+
+# Update progress
+clawmatrix notify "iOS 构建" --action update --task-id <id> --detail "链接中..." --progress 80
+
+# End (success)
+clawmatrix notify "iOS 构建" --action end --task-id <id>
+```
+
+Options: `--detail <text>`, `--progress <0-100>`, `--action start|update|end`, `--task-id <id>`, `--tool <name>`
+
+## Workflow
+
+1. Run `clawmatrix status` to see the cluster topology
+2. Use `clawmatrix tools --filter <keyword>` to find relevant tools
+3. Use `clawmatrix tools --describe <tool>` to check parameters
+4. Use `clawmatrix call` or `clawmatrix batch` to invoke tools
+5. If a call fails, run `clawmatrix check <nodeId>` to verify connectivity
+6. For long-running tasks, use `clawmatrix notify` to push progress to the user's phone

package/openclaw.plugin.json

@@ -3,6 +3,7 @@
   "name": "ClawMatrix",
   "description": "Decentralized mesh cluster for inter-gateway communication, model proxy, task handoff, and tool proxy.",
   "providers": ["clawmatrix"],
+  "skills": ["./cli/skills"],
   "configSchema": {
     "type": "object",
     "additionalProperties": true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmatrix",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Decentralized mesh cluster plugin for OpenClaw — inter-gateway communication, model proxy, task handoff, and tool proxy.",
   "type": "module",
   "license": "MIT",
@@ -17,6 +17,7 @@
   "files": [
     "src/",
     "!src/**/*.test.ts",
+    "cli/",
     "openclaw.plugin.json",
     "BOOTSTRAP.md",
     "README.md"