clawps 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kevin Smith
+
+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,116 @@
+# clawps 🐾
+
+A procps-style package of utilities for [OpenClaw](https://openclaw.ai) sessions.
+
+```
+$ clawps
+
+STATUS  AGENT                                MODEL             CONTEXT     IDLE      CHANNEL     KIND
+-------------------------------------------------------------------------------------------------------------
+active  Kevin Smith (@spleck)                kimi-k2.5         15K/250K    2m        telegram    other
+stale   Daily SPA Generator                  kimi-k2.5         250K/250K   4h        cron        other
+-----------------------------------------------------------------------------------------------------------
+2 sessions
+```
+
+```
+$ clawtop
+
+  PID   SESSIONS                          MODEL        CPU    MSGS    CTX/MAX    UPTIME
+-------------------------------------------------------------------------------------------------
+ 1699   Kevin Smith (main)                minimax-m2.5  0.1    142     45K/250K   12m
+ 1705   pm-daily-spas (isolated)          kimi-k2.5     0.0    28      12K/250K   4h
+-------------------------------------------------------------------------------------------------
+Total: 2 sessions | Context: 57K/500K (11%)
+```
+
+## Installation
+
+```bash
+# Clone or download
+git clone https://github.com/spleck/clawps.git
+cd clawps
+
+# Make executable and link to your PATH
+chmod +x clawps.js
+ln -s $(pwd)/clawps.js ~/.local/bin/clawps
+
+chmod +x clawtop.js
+ln -s $(pwd)/clawtop.js ~/.local/bin/clawtop
+
+# Or install globally via npm
+npm link
+```
+
+Make sure `~/.local/bin` is in your PATH:
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+## Requirements
+
+- Node.js 18+
+- OpenClaw gateway running (default: localhost:18789)
+- Gateway auth token read from `~/.openclaw/openclaw.json`
+
+## Utilities
+
+### clawps
+
+Process-style session listing.
+
+```bash
+clawps              # Basic session listing
+clawps -v           # Verbose/detailed output
+clawps --json       # JSON output for scripting
+clawps -w           # Watch mode (auto-refresh)
+clawps -w -n5       # Watch mode, refresh every 5 seconds
+clawps --no-color   # Disable colors
+```
+
+### clawtop
+
+Top-style real-time session monitor.
+
+```bash
+clawtop             # Real-time monitoring (default 3s refresh)
+clawtop -n5         # Refresh every 5 seconds
+clawtop --json      # JSON output for scripting
+clawtop --no-color  # Disable colors
+```
+
+## Output
+
+### clawps
+
+| Column | Description |
+|--------|-------------|
+| STATUS | active 🟢 / idle 🟡 / stale 🔴 |
+| AGENT | Session/agent display name |
+| MODEL | AI model in use (shortened) |
+| CONTEXT | Current / max tokens (e.g., `15K/250K`) |
+| IDLE | Time since last activity |
+| CHANNEL | Communication channel |
+| KIND | Session type |
+
+### clawtop
+
+| Column | Description |
+|--------|-------------|
+| PID | Process/Session ID |
+| SESSIONS | Session name and type |
+| MODEL | AI model in use |
+| CPU | Estimated CPU usage |
+| MSGS | Message count this session |
+| CTX/MAX | Context usage |
+| UPTIME | Session runtime |
+
+## How It Works
+
+Both tools query your local OpenClaw gateway via the `sessions_list` tool:
+- `clawps` — formats sessions like Unix `ps`
+- `clawtop` — monitors like Unix `top`
+
+## License
+
+MIT

package/clawps.js

@@ -0,0 +1,351 @@
+#!/usr/bin/env node
+/**
+ * clawps - List OpenClaw sessions like the `ps` command
+ * Usage: clawps [options]
+ */
+
+const http = require('http');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+// ANSI color codes
+const COLORS = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  white: '\x1b[37m',
+  gray: '\x1b[90m',
+};
+
+// Parse CLI arguments
+const args = process.argv.slice(2);
+const options = {
+  color: !args.includes('--no-color') && process.stdout.isTTY,
+  verbose: args.includes('-v') || args.includes('--verbose'),
+  help: args.includes('-h') || args.includes('--help'),
+  json: args.includes('--json'),
+  watch: args.includes('-w') || args.includes('--watch'),
+  interval: 2000, // ms for watch mode
+};
+
+// Watch interval override
+const intervalArg = args.find(a => a.startsWith('-n'));
+if (intervalArg) {
+  const val = parseInt(intervalArg.replace('-n', ''), 10);
+  if (!isNaN(val)) options.interval = val * 1000;
+}
+
+function printHelp() {
+  console.log(`
+Usage: clawps [options]
+
+Options:
+  -h, --help       Show this help message
+  -v, --verbose    Show detailed session information
+  --no-color       Disable colored output
+  --json           Output as JSON
+  -w, --watch      Refresh continuously (like watch command)
+  -n<secs>         Watch interval in seconds (default: 2)
+
+Examples:
+  clawps              # Basic session listing
+  clawps -v           # Verbose output
+  clawps --no-color   # Plain text output
+  clawps -w -n5       # Refresh every 5 seconds
+`);
+}
+
+if (options.help) {
+  printHelp();
+  process.exit(0);
+}
+
+function color(code, text) {
+  return options.color ? `${COLORS[code]}${text}${COLORS.reset}` : text;
+}
+
+function getGatewayConfig() {
+  const configPath = path.join(os.homedir(), '.openclaw', 'openclaw.json');
+  try {
+    const raw = fs.readFileSync(configPath, 'utf8');
+    const config = JSON.parse(raw);
+    return {
+      port: config.gateway?.port || 18789,
+      token: config.gateway?.auth?.token,
+    };
+  } catch (err) {
+    return { port: 18789, token: null };
+  }
+}
+
+function invokeTool(tool, args = {}) {
+  return new Promise((resolve, reject) => {
+    const { port, token } = getGatewayConfig();
+    const postData = JSON.stringify({ tool, args });
+    
+    const headers = {
+      'Content-Type': 'application/json',
+      'Accept': 'application/json',
+      'Content-Length': Buffer.byteLength(postData),
+    };
+    
+    if (token) {
+      headers['Authorization'] = `Bearer ${token}`;
+    }
+
+    const req = http.request({
+      hostname: 'localhost',
+      port,
+      path: '/tools/invoke',
+      method: 'POST',
+      headers,
+    }, (res) => {
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => {
+        try {
+          const parsed = JSON.parse(data);
+          if (parsed.ok && parsed.result) {
+            // Extract sessions from the tool result
+            const result = parsed.result;
+            if (result.content && result.content[0]?.text) {
+              // Parse the JSON text content
+              const innerResult = JSON.parse(result.content[0].text);
+              resolve(innerResult.sessions || []);
+            } else if (result.details?.sessions) {
+              resolve(result.details.sessions);
+            } else {
+              resolve([]);
+            }
+          } else {
+            reject(new Error(parsed.error?.message || 'Unknown error'));
+          }
+        } catch (e) {
+          reject(new Error('Invalid JSON response'));
+        }
+      });
+    });
+
+    req.on('error', reject);
+    req.setTimeout(5000, () => {
+      req.destroy();
+      reject(new Error('Request timeout'));
+    });
+    req.write(postData);
+    req.end();
+  });
+}
+
+function formatDuration(ms) {
+  if (!ms || ms < 0) return '0s';
+  const seconds = Math.floor(ms / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+  const days = Math.floor(hours / 24);
+
+  if (days > 0) return `${days}d${hours % 24}h`;
+  if (hours > 0) return `${hours}h${minutes % 60}m`;
+  if (minutes > 0) return `${minutes}m${seconds % 60}s`;
+  return `${seconds}s`;
+}
+
+function formatBytes(bytes) {
+  if (!bytes) return '0B';
+  const units = ['B', 'K', 'M', 'G'];
+  let idx = 0;
+  while (bytes >= 1024 && idx < units.length - 1) {
+    bytes /= 1024;
+    idx++;
+  }
+  return `${Math.round(bytes)}${units[idx]}`;
+}
+
+function getAgentName(session) {
+  // Extract agent name from session key or display name
+  if (session.displayName) {
+    // Remove common prefixes/suffixes for cleaner display
+    return session.displayName
+      .replace(/^Cron: /, '')
+      .replace(/^agent:main:/, '');
+  }
+  const parts = session.key?.split(':') || [];
+  return parts[parts.length - 1] || 'unknown';
+}
+
+function getModelShort(model) {
+  if (!model) return '-';
+  return model
+    .replace('moonshot/', '')
+    .replace('openrouter/', 'or/')
+    .substring(0, 20);
+}
+
+function getStatusIndicator(session) {
+  const now = Date.now();
+  const idle = now - (session.updatedAt || 0);
+  
+  // Consider session active if updated in last 5 minutes
+  if (idle < 5 * 60 * 1000) {
+    return color('green', '●');
+  }
+  // Idle if updated in last 30 minutes
+  if (idle < 30 * 60 * 1000) {
+    return color('yellow', '○');
+  }
+  return color('red', '○');
+}
+
+function truncate(str, len) {
+  if (!str) return '-'.padEnd(len);
+  if (str.length <= len) return str.padEnd(len);
+  return str.substring(0, len - 1) + '…';
+}
+
+async function listSessions() {
+  try {
+    const sessions = await invokeTool('sessions_list', {});
+
+    if (options.json) {
+      console.log(JSON.stringify(sessions, null, 2));
+      return;
+    }
+
+    if (sessions.length === 0) {
+      console.log(color('dim', 'No active sessions.'));
+      return;
+    }
+
+    const now = Date.now();
+
+    if (options.verbose) {
+      // Verbose table format
+      console.log();
+      console.log(color('bright', 'OpenClaw Sessions'));
+      console.log(color('dim', '═'.repeat(100)));
+      
+      sessions.forEach((s, i) => {
+        const idle = now - (s.updatedAt || 0);
+        const status = getStatusIndicator(s);
+        const agentName = getAgentName(s);
+        
+        console.log(`${status} ${color('bright', agentName)}`);
+        console.log(`   Key:      ${color('gray', s.key || '-')}`);
+        console.log(`   Session:  ${color('cyan', s.sessionId?.substring(0, 8) || '-')}`);
+        console.log(`   Kind:     ${s.kind || '-'}`);
+        console.log(`   Channel:  ${s.channel || '-'}`);
+        console.log(`   Model:    ${getModelShort(s.model)}`);
+        const currentTokens = s.totalTokens || 0;
+        const maxTokens = s.contextWindow || s.contextTokens || 0;
+        console.log(`   Context:  ${formatBytes(currentTokens)} / ${formatBytes(maxTokens)}`);
+        console.log(`   Idle:     ${formatDuration(idle)}`);
+        console.log(`   Updated:  ${new Date(s.updatedAt).toLocaleTimeString()}`);
+        
+        if (s.label) {
+          console.log(`   Label:    ${color('magenta', s.label)}`);
+        }
+        if (s.abortedLastRun) {
+          console.log(`   ${color('red', '⚠ Last run aborted')}`);
+        }
+        
+        if (i < sessions.length - 1) console.log();
+      });
+      
+      console.log(color('dim', '═'.repeat(100)));
+      console.log(`${color('green', '●')} Active  ${color('yellow', '○')} Idle  ${color('red', '○')} Stale`);
+      console.log();
+    } else {
+      // Compact ps-like format
+      // Columns: STATUS AGENT MODEL CONTEXT IDLE CHANNEL KIND
+      const headers = ['STATUS', 'AGENT', 'MODEL', 'CONTEXT', 'IDLE', 'CHANNEL', 'KIND'];
+      const widths = [8, 35, 18, 12, 10, 12, 12];
+      
+      // Header
+      console.log();
+      const headerLine = [
+        color('bright', truncate(headers[0], widths[0])),
+        color('bright', truncate(headers[1], widths[1])),
+        '  ',
+        color('bright', truncate(headers[2], widths[2])),
+        color('bright', truncate(headers[3], widths[3])),
+        color('bright', truncate(headers[4], widths[4])),
+        color('bright', truncate(headers[5], widths[5])),
+        color('bright', truncate(headers[6], widths[6])),
+      ].join('');
+      console.log(headerLine);
+      console.log(color('dim', '-'.repeat(widths.reduce((a, b) => a + b, 0) + 2)));
+      
+      // Rows
+      sessions.forEach(s => {
+        const idle = now - (s.updatedAt || 0);
+        const idleStr = formatDuration(idle);
+        const agentName = getAgentName(s);
+        const model = getModelShort(s.model);
+        const currentTokens = s.totalTokens || 0;
+        const maxTokens = s.contextWindow || s.contextTokens || 0;
+        const context = `${formatBytes(currentTokens)}/${formatBytes(maxTokens)}`;
+        const channel = s.channel || '-';
+        const kind = s.kind || '-';
+        
+        let statusStr;
+        if (idle < 5 * 60 * 1000) {
+          statusStr = color('green', 'active'.padEnd(8));
+        } else if (idle < 30 * 60 * 1000) {
+          statusStr = color('yellow', 'idle'.padEnd(8));
+        } else {
+          statusStr = color('red', 'stale'.padEnd(8));
+        }
+        
+        const row = [
+          statusStr,
+          truncate(agentName, widths[1]),
+          '  ',
+          truncate(model, widths[2]),
+          context.padEnd(widths[3]),
+          idleStr.padEnd(widths[4]),
+          truncate(channel, widths[5]),
+          truncate(kind, widths[6]),
+        ].join('');
+        
+        console.log(row);
+      });
+      
+      console.log(color('dim', '-'.repeat(widths.reduce((a, b) => a + b, 0))));
+      console.log(`${sessions.length} session${sessions.length !== 1 ? 's' : ''}`);
+      console.log();
+    }
+  } catch (err) {
+    console.error(color('red', `Error: ${err.message}`));
+    if (err.message.includes('ECONNREFUSED')) {
+      console.error(color('dim', 'Is the OpenClaw gateway running?'));
+    }
+    process.exit(1);
+  }
+}
+
+async function main() {
+  if (options.watch) {
+    console.clear();
+    console.log(color('dim', `Watching every ${options.interval/1000}s (Ctrl+C to exit)...`));
+    console.log();
+    
+    const run = async () => {
+      console.clear();
+      console.log(color('dim', `Watching every ${options.interval/1000}s (Ctrl+C to exit)...`));
+      await listSessions();
+    };
+    
+    await run();
+    setInterval(run, options.interval);
+  } else {
+    await listSessions();
+  }
+}
+
+main();

package/clawtop.js

@@ -0,0 +1,646 @@
+#!/usr/bin/env node
+
+/**
+ * clawtop - A top-like utility for monitoring OpenClaw instances
+ * Lightweight, cross-platform session monitor
+ * 
+ * Usage: node clawtop.js [options]
+ *   -n, --iterations  Number of iterations (default: infinite)
+ *   -d, --delay       Delay in seconds between updates (default: 2)
+ *   -s, --sort       Sort by: cpu, mem, idle, tokens (default: cpu)
+ *   -h, --help       Show this help
+ * 
+ * Keyboard shortcuts (when running):
+ *   q        Quit
+ *   r        Reverse sort order
+ *   s        Change sort field
+ *   Space    Pause/Resume updates
+ *   h        Show help
+ */
+
+import http from 'http';
+import https from 'https';
+import { execSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import readline from 'readline';
+import os from 'os';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Default config
+const CONFIG = {
+  delay: 2,
+  iterations: Infinity,
+  sortBy: 'cpu',
+  reverse: false,
+  maxSessions: 20,
+  showSystem: true,
+  color: true
+};
+
+// State
+let paused = false;
+let showingHelp = false;
+let inputBuffer = '';
+let awaitingInput = null; // 'delay' or 'iterations'
+
+// Colors (disable on Windows or no-color)
+const isWindows = process.platform === 'win32';
+const noColor = process.env.NO_COLOR || isWindows;
+
+const C = noColor ? {
+  reset: '', bright: '', dim: '', green: '', yellow: '', red: '', cyan: '', magenta: '', white: '', gray: ''
+} : {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  dim: '\x1b[2m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+  cyan: '\x1b[36m',
+  magenta: '\x1b[35m',
+  white: '\x1b[37m',
+  gray: '\x1b[90m'
+};
+
+function getGatewayConfig() {
+  const configPaths = [
+    process.env.HOME + '/.openclaw/openclaw.json',
+    process.env.USERPROFILE + '/.openclaw/openclaw.json',
+    '/etc/openclaw/openclaw.json'
+  ];
+  
+  for (const configPath of configPaths) {
+    try {
+      if (fs.existsSync(configPath)) {
+        const raw = fs.readFileSync(configPath, 'utf8');
+        const config = JSON.parse(raw);
+        return {
+          port: config.gateway?.port || 18789,
+          token: config.gateway?.auth?.token,
+          host: config.gateway?.host || 'localhost'
+        };
+      }
+    } catch {}
+  }
+  return { port: 18789, token: null, host: 'localhost' };
+}
+
+function formatBytes(bytes) {
+  if (bytes === 0) return '0B';
+  const k = 1024;
+  const sizes = ['B', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return parseFloat((bytes / Math.pow(k, i)).toFixed(1)) + ' ' + sizes[i];
+}
+
+function formatDuration(seconds) {
+  if (!seconds || seconds < 0) return '--';
+  const days = Math.floor(seconds / 86400);
+  const hours = Math.floor((seconds % 86400) / 3600);
+  const mins = Math.floor((seconds % 3600) / 60);
+  if (days > 0) return `${days}d ${hours}h`;
+  if (hours > 0) return `${hours}h ${mins}m`;
+  return `${mins}m`;
+}
+
+function formatNumber(num) {
+  if (num >= 1000000) return (num / 1000000).toFixed(1) + 'M';
+  if (num >= 1000) return (num / 1000).toFixed(1) + 'K';
+  return num.toString();
+}
+
+function getSystemInfo() {
+  const info = {
+    os: 'Unknown',
+    arch: process.arch,
+    nodeVersion: process.version,
+    platform: process.platform,
+    cpuCount: os.cpus().length,
+    totalMem: os.totalmem(),
+    uptime: os.uptime(),
+    cpuUsage: 0,
+    freeMem: os.freemem(),
+    usedMem: os.totalmem() - os.freemem()
+  };
+  
+  // Try to get OS info
+  try {
+    if (process.platform === 'darwin') {
+      const out = execSync('sw_vers -productVersion 2>/dev/null', { encoding: 'utf8', timeout: 2000 });
+      info.os = 'macOS ' + out.trim();
+    } else if (process.platform === 'linux') {
+      const out = execSync('cat /etc/os-release 2>/dev/null | grep PRETTY_NAME | cut -d= -f2 | tr -d "\""', { encoding: 'utf8', timeout: 2000 });
+      info.os = out.trim() || 'Linux';
+    } else if (process.platform === 'win32') {
+      info.os = 'Windows';
+    }
+  } catch {
+    info.os = process.platform;
+  }
+  
+  return info;
+}
+
+// Get current CPU usage by comparing idle times
+let lastCpuInfo = null;
+function getCpuUsage() {
+  const cpus = os.cpus();
+  let totalIdle = 0;
+  let totalTick = 0;
+  
+  for (const cpu of cpus) {
+    for (const type in cpu.times) {
+      totalTick += cpu.times[type];
+    }
+    totalIdle += cpu.times.idle;
+  }
+  
+  if (lastCpuInfo) {
+    const idleDiff = totalIdle - lastCpuInfo.idle;
+    const totalDiff = totalTick - lastCpuInfo.total;
+    if (totalDiff > 0) {
+      const usage = 100 - (100 * idleDiff / totalDiff);
+      lastCpuInfo = { idle: totalIdle, total: totalTick };
+      return Math.round(usage);
+    }
+  }
+  
+  lastCpuInfo = { idle: totalIdle, total: totalTick };
+  return null;
+}
+
+function getGatewayUptime() {
+  try {
+    if (process.platform === 'darwin') {
+      // Use ps to find openclaw-gateway process directly
+      const out = execSync('ps aux | grep "openclaw-gateway" | grep -v grep | head -1', { encoding: 'utf8', timeout: 2000 });
+      const match = out.trim().match(/^\S+\s+(\d+)/);
+      if (match) {
+        const pid = match[1];
+        const startOut = execSync(`ps -o lstart= -p ${pid} 2>/dev/null`, { encoding: 'utf8', timeout: 2000 });
+        const startTime = new Date(startOut.trim());
+        if (!isNaN(startTime.getTime())) {
+          return Math.floor((Date.now() - startTime.getTime()) / 1000);
+        }
+      }
+    } else if (process.platform === 'linux') {
+      const out = execSync('pgrep -f openclaw-gateway 2>/dev/null | head -1', { encoding: 'utf8', timeout: 2000 });
+      const pid = parseInt(out.trim());
+      if (pid) {
+        const startOut = execSync(`ps -o lstart= -p ${pid} 2>/dev/null`, { encoding: 'utf8', timeout: 2000 });
+        const startTime = new Date(startOut.trim());
+        if (!isNaN(startTime.getTime())) {
+          return Math.floor((Date.now() - startTime.getTime()) / 1000);
+        }
+      }
+    } else if (process.platform === 'win32') {
+      // Windows: use wmic to get creation date
+      const out = execSync('wmic process where "name=\'node.exe\' and commandline like \'%openclaw%\'" get ProcessId,CreationDate 2>/dev/null', { encoding: 'utf8', timeout: 3000 });
+      const lines = out.trim().split('\n').filter(l => l.trim());
+      if (lines.length > 1) {
+        // Parse the second line (first is headers)
+        const parts = lines[1].trim().split(/\s+/);
+        if (parts.length >= 2) {
+          const pid = parseInt(parts[parts.length - 2]);
+          const createDate = parts[parts.length - 1];
+          // CreationDate format: 20260212170000.000000-000
+          const dateMatch = createDate.match(/^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})/);
+          if (dateMatch) {
+            const startTime = new Date(
+              parseInt(dateMatch[1]), parseInt(dateMatch[2]) - 1, parseInt(dateMatch[3]),
+              parseInt(dateMatch[4]), parseInt(dateMatch[5]), parseInt(dateMatch[6])
+            );
+            if (!isNaN(startTime.getTime())) {
+              return Math.floor((Date.now() - startTime.getTime()) / 1000);
+            }
+          }
+        }
+      }
+    }
+  } catch {}
+  return null;
+}
+
+async function fetchSessions(config) {
+  return new Promise((resolve, reject) => {
+    const { port, token, host } = config;
+    const postData = JSON.stringify({ tool: 'sessions_list', args: { activeMinutes: 60, messageLimit: 1 } });
+    
+    const headers = {
+      'Content-Type': 'application/json',
+      'Accept': 'application/json',
+      'Content-Length': Buffer.byteLength(postData)
+    };
+    
+    if (token) {
+      headers['Authorization'] = `Bearer ${token}`;
+    }
+
+    const req = http.request({
+      hostname: host,
+      port,
+      path: '/tools/invoke',
+      method: 'POST',
+      headers,
+      timeout: 5000
+    }, (res) => {
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => {
+        try {
+          const parsed = JSON.parse(data);
+          if (parsed.ok && parsed.result) {
+            const result = parsed.result;
+            if (result.content && result.content[0]?.text) {
+              const innerResult = JSON.parse(result.content[0].text);
+              resolve(innerResult.sessions || []);
+            } else if (result.details?.sessions) {
+              resolve(result.details.sessions);
+            } else {
+              resolve([]);
+            }
+          } else {
+            reject(new Error(parsed.error?.message || 'API error'));
+          }
+        } catch (e) {
+          reject(new Error('Invalid JSON: ' + e.message));
+        }
+      });
+    });
+
+    req.on('error', (err) => reject(new Error('Request failed: ' + err.message)));
+    req.on('timeout', () => { req.destroy(); reject(new Error('Request timeout')); });
+    req.write(postData);
+    req.end();
+  });
+}
+
+// Simple health check - just verifies gateway is reachable
+async function checkGatewayHealth(config) {
+  return new Promise((resolve) => {
+    const { port, token, host } = config;
+    
+    const req = http.request({
+      hostname: host,
+      port,
+      path: '/health',
+      method: 'GET',
+      timeout: 3000
+    }, (res) => {
+      resolve(res.statusCode === 200);
+    });
+    
+    req.on('error', () => resolve(false));
+    req.on('timeout', () => { req.destroy(); resolve(false); });
+    req.end();
+  });
+}
+
+function calculateCpuUsage(session, prevSession, elapsedMs) {
+  if (!session || !prevSession || elapsedMs < 500) return 0;
+  const currTokens = session.totalTokens || 0;
+  const prevTokens = prevSession.totalTokens || 0;
+  const diff = currTokens - prevTokens;
+  if (diff <= 0) return 0;
+  const tps = diff / (elapsedMs / 1000);
+  return Math.min(100, tps);
+}
+
+function sortSessions(sessions, sortBy, reverse) {
+  const sorted = [...sessions].sort((a, b) => {
+    let valA, valB;
+    
+    switch (sortBy) {
+      case 'cpu':
+        valA = a._cpu || 0;
+        valB = b._cpu || 0;
+        break;
+      case 'mem':
+      case 'tokens':
+        valA = a.totalTokens || 0;
+        valB = b.totalTokens || 0;
+        break;
+      case 'idle':
+        valA = a.updatedAt || 0;
+        valB = b.updatedAt || 0;
+        break;
+      case 'name':
+        valA = (a.displayName || a.key || '').toLowerCase();
+        valB = (b.displayName || b.key || '').toLowerCase();
+        break;
+      default:
+        valA = a._cpu || 0;
+        valB = b._cpu || 0;
+    }
+    
+    if (typeof valA === 'string') {
+      return reverse ? valB.localeCompare(valA) : valA.localeCompare(valB);
+    }
+    return reverse ? valB - valA : valA - valB;
+  });
+  
+  return sorted;
+}
+
+function clearScreen() {
+  process.stdout.write('\x1b[2J\x1b[H');
+}
+
+function moveToTop() {
+  process.stdout.write('\x1b[H');
+}
+
+function render(sysInfo, gwUptime, sessionCount, sessions, error, delay) {
+  const width = process.stdout.columns || 80;
+  
+  // If showing help, render that instead
+  if (showingHelp) {
+    const helpLines = [
+      '',
+      '  CLAWTOP - Keyboard Shortcuts',
+      '',
+      '  q         Quit',
+      '  Space     Pause/Resume updates',
+      '  r         Reverse sort order',
+      '  s         Cycle sort field (cpu → mem → idle → tokens → name)',
+      '  d         Change delay (prompts for seconds)',
+      '  n         Change iterations (prompts for number, 0 = infinite)',
+      '  h         Toggle this help',
+      '',
+      '  Press any key to return...',
+      ''
+    ];
+    clearScreen();
+    console.log(C.cyan + C.bright + '┌─ CLAWTOP HELP ────────────────────────────────────────────────────────────┐' + C.reset);
+    helpLines.forEach(line => console.log(line));
+    console.log(C.cyan + '└───────────────────────────────────────────────────────────────────────────────┘' + C.reset);
+    return;
+  }
+  
+  // If awaiting input, show that
+  if (awaitingInput === 'delay') {
+    clearScreen();
+    console.log(C.cyan + '┌─ CLAWTOP ─────────────────────────────────────────────────────────────────────┐' + C.reset);
+    console.log(C.yellow + '  Enter delay in seconds (current: ' + CONFIG.delay + 's): ' + C.reset + inputBuffer);
+    console.log(C.gray + '  Press Enter to confirm, Esc to cancel' + C.reset);
+    console.log(C.cyan + '└───────────────────────────────────────────────────────────────────────────────┘' + C.reset);
+    return;
+  }
+  
+  if (awaitingInput === 'iterations') {
+    clearScreen();
+    console.log(C.cyan + '┌─ CLAWTOP ─────────────────────────────────────────────────────────────────────┐' + C.reset);
+    const iterStr = CONFIG.iterations === Infinity ? 'infinite' : CONFIG.iterations;
+    console.log(C.yellow + '  Enter iterations (current: ' + iterStr + '): ' + C.reset + inputBuffer);
+    console.log(C.gray + '  Press Enter to confirm, Esc to cancel' + C.reset);
+    console.log(C.cyan + '└───────────────────────────────────────────────────────────────────────────────┘' + C.reset);
+    return;
+  }
+  
+  // Normal render
+  clearScreen();
+  
+  const statusLine = paused ? C.yellow + ' [PAUSED] ' + C.reset : '';
+  console.log(C.cyan + C.bright + '┌─ CLAWTOP ─────────────────────────────────────────────────────────────────────┐' + C.reset);
+  console.log(C.gray + '  OpenClaw session monitor' + statusLine + ' '.repeat(width - 45) + C.gray + `Refresh: ${delay}s` + C.reset);
+  console.log(C.cyan + '├──────────────────────────────────────────────────────────────────────────────┤' + C.reset);
+  
+  if (CONFIG.showSystem) {
+    const cpuUsage = sysInfo.cpuUsage !== null ? sysInfo.cpuUsage : 0;
+    const memPercent = sysInfo.totalMem > 0 ? Math.round((sysInfo.usedMem / sysInfo.totalMem) * 100) : 0;
+    const sysLine = `  ${C.cyan}OS:${C.reset} ${sysInfo.os}  ${C.cyan}CPU:${C.reset} ${cpuUsage}%  ${C.cyan}Mem:${C.reset} ${formatBytes(sysInfo.usedMem)}/${formatBytes(sysInfo.totalMem)} (${memPercent}%)  ${C.cyan}Uptime:${C.reset} ${formatDuration(sysInfo.uptime)}`;
+    console.log(sysLine.substring(0, width - 2));
+    
+    const gwLine = `  ${C.magenta}Gateway:${C.reset} ${gwUptime ? formatDuration(gwUptime) : C.red + 'offline' + C.reset}  ${C.magenta}Sessions:${C.reset} ${sessionCount}  ${C.magenta}Node:${C.reset} ${sysInfo.nodeVersion}`;
+    console.log(gwLine.substring(0, width - 2));
+  }
+  
+  console.log(C.cyan + '├──────────────────────────────────────────────────────────────────────────────┤' + C.reset);
+  
+  const sortIndicator = (field) => CONFIG.sortBy === field ? (CONFIG.reverse ? '▼' : '▲') : ' ';
+  console.log(C.white + C.bright + 
+    `  ${sortIndicator('name')} NAME                         ${sortIndicator('cpu')} CPU   ${sortIndicator('mem')} TOKENS    ${sortIndicator('idle')} IDLE    CHANNEL` + 
+    C.reset);
+  console.log(C.cyan + '├──────────────────────────────────────────────────────────────────────────────┤' + C.reset);
+  
+  if (error) {
+    console.log(C.red + '  Error: ' + error + C.reset);
+    console.log(C.gray + `  Gateway may be offline. Config: ${config.host}:${config.port}` + C.reset);
+  } else if (sessions.length === 0) {
+    console.log(C.gray + '  No active sessions' + C.reset);
+  } else {
+    sessions.forEach((s) => {
+      const name = (s.displayName || s.key || 'unknown').substring(0, 27).padEnd(27);
+      const cpu = s._cpu || 0;
+      const tokens = s.totalTokens || 0;
+      const idleMs = s.updatedAt ? Date.now() - s.updatedAt : 0;
+      let idleStr;
+      if (idleMs < 60000) idleStr = Math.round(idleMs / 1000) + 's';
+      else if (idleMs < 3600000) idleStr = Math.round(idleMs / 60000) + 'm';
+      else idleStr = Math.round(idleMs / 3600000) + 'h';
+      
+      const channel = (s.channel || '-').substring(0, 10);
+      
+      let nameColor = C.white;
+      let cpuColor = C.gray;
+      
+      if (idleMs < 5 * 60 * 1000) {
+        nameColor = C.green;
+        cpuColor = cpu > 50 ? C.red : (cpu > 20 ? C.yellow : C.green);
+      } else if (idleMs < 30 * 60 * 1000) {
+        nameColor = C.yellow;
+      } else {
+        nameColor = C.gray;
+      }
+      
+      const cpuStr = cpu > 0 ? cpu.toFixed(1) + '%' : '-';
+      const tokensStr = tokens > 0 ? formatNumber(tokens) : '-';
+      
+      console.log(`  ${nameColor}${name}${C.reset} ${cpuColor}${cpuStr.padStart(6)}${C.reset} ${tokensStr.padStart(9)} ${idleStr.padStart(7)}  ${channel}`);
+    });
+  }
+  
+  console.log(C.cyan + '├──────────────────────────────────────────────────────────────────────────────┤' + C.reset);
+  console.log(C.gray + `  Sort: ${CONFIG.sortBy} (s)  Reverse: ${CONFIG.reverse ? 'ON' : 'OFF'} (r)  Delay: ${CONFIG.delay}s (d)  Quit: q  Help: h` + C.reset);
+  console.log(C.cyan + '└───────────────────────────────────────────────────────────────────────────────┘' + C.reset);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '-h' || arg === '--help') {
+      console.log(`
+clawtop - A top-like utility for monitoring OpenClaw instances
+
+Usage: node clawtop.js [options]
+
+Options:
+  -n, --iterations N   Number of iterations (default: infinite)
+  -d, --delay N        Delay in seconds between updates (default: 2)
+  -s, --sort FIELD     Sort by: cpu, mem, idle, tokens, name (default: cpu)
+  --no-color           Disable colored output
+  --no-system          Hide system info
+  -h, --help           Show this help
+
+Keyboard shortcuts (when running):
+  Space    Pause/Resume updates
+  q        Quit
+  r        Reverse sort order
+  s        Cycle sort field
+  d        Change delay (prompts)
+  n        Change iterations (prompts)
+  h        Toggle help
+
+Examples:
+  node clawtop.js
+  node clawtop.js -n 5
+  node clawtop.js -d 5 -s idle
+`);
+      process.exit(0);
+    } else if (arg === '-n' || arg === '--iterations') {
+      CONFIG.iterations = parseInt(args[++i]) || Infinity;
+    } else if (arg === '-d' || arg === '--delay') {
+      CONFIG.delay = parseInt(args[++i]) || 2;
+    } else if (arg === '-s' || arg === '--sort') {
+      CONFIG.sortBy = args[++i] || 'cpu';
+    } else if (arg === '--no-color') {
+      Object.keys(C).forEach(k => C[k] = '');
+    } else if (arg === '--no-system') {
+      CONFIG.showSystem = false;
+    }
+  }
+  
+  const config = getGatewayConfig();
+  let iterations = 0;
+  let prevSessions = [];
+  let lastTime = Date.now();
+  let lastRenderTime = Date.now();
+  
+  // Setup input handling
+  if (process.stdin.isTTY) {
+    readline.emitKeypressEvents(process.stdin);
+    process.stdin.setRawMode(true);
+    
+    process.stdin.on('keypress', (str, key) => {
+      // Handle help toggle
+      if (key.name === 'h' && !awaitingInput) {
+        showingHelp = !showingHelp;
+        lastRenderTime = Date.now(); // Force render
+        return;
+      }
+      
+      // If showing help, any key closes it
+      if (showingHelp) {
+        showingHelp = false;
+        lastRenderTime = Date.now();
+        return;
+      }
+      
+      // Handle input modes
+      if (awaitingInput) {
+        if (key.name === 'escape') {
+          awaitingInput = null;
+          inputBuffer = '';
+        } else if (key.name === 'return' || key.name === 'enter') {
+          if (awaitingInput === 'delay') {
+            const newDelay = parseInt(inputBuffer);
+            if (newDelay > 0 && newDelay <= 3600) {
+              CONFIG.delay = newDelay;
+            }
+          } else if (awaitingInput === 'iterations') {
+            const newIter = parseInt(inputBuffer);
+            if (!isNaN(newIter)) {
+              CONFIG.iterations = newIter === 0 ? Infinity : newIter;
+            }
+          }
+          awaitingInput = null;
+          inputBuffer = '';
+        } else if (key.name === 'backspace') {
+          inputBuffer = inputBuffer.slice(0, -1);
+        } else if (str && str.length === 1 && /[\d]/.test(str)) {
+          inputBuffer += str;
+        }
+        lastRenderTime = Date.now();
+        return;
+      }
+      
+      // Regular keyboard shortcuts
+      if (key.name === 'q' || (key.ctrl && key.name === 'c')) {
+        console.log('\n' + C.gray + 'Goodbye!' + C.reset);
+        process.exit(0);
+      } else if (key.name === 'space') {
+        paused = !paused;
+      } else if (key.name === 'r') {
+        CONFIG.reverse = !CONFIG.reverse;
+      } else if (key.name === 's') {
+        const fields = ['cpu', 'mem', 'idle', 'tokens', 'name'];
+        const idx = fields.indexOf(CONFIG.sortBy);
+        CONFIG.sortBy = fields[(idx + 1) % fields.length];
+      } else if (key.name === 'd') {
+        awaitingInput = 'delay';
+        inputBuffer = '';
+      } else if (key.name === 'n') {
+        awaitingInput = 'iterations';
+        inputBuffer = '';
+      }
+      
+      lastRenderTime = Date.now();
+    });
+  }
+  
+  // Main loop
+  while (iterations < CONFIG.iterations) {
+    // Skip iteration if paused, but still render to show paused state
+    if (!paused && !showingHelp && !awaitingInput) {
+      const now = Date.now();
+      const elapsed = now - lastTime;
+      lastTime = now;
+      
+      const sysInfo = getSystemInfo();
+      sysInfo.cpuUsage = getCpuUsage();
+      const gwUptime = getGatewayUptime();
+      
+      let sessions = [];
+      let error = null;
+      try {
+        sessions = await fetchSessions(config);
+      } catch (err) {
+        error = err.message;
+      }
+      
+      sessions = sessions.map(s => {
+        const prev = prevSessions.find(ps => ps.key === s.key);
+        s._cpu = calculateCpuUsage(s, prev, elapsed);
+        return s;
+      });
+      
+      sessions = sortSessions(sessions, CONFIG.sortBy, CONFIG.reverse).slice(0, CONFIG.maxSessions);
+      prevSessions = sessions;
+      
+      render(sysInfo, gwUptime, sessions.length, sessions, error, CONFIG.delay);
+      iterations++;
+    } else if (paused || showingHelp || awaitingInput) {
+      // Still render to show state
+      const sysInfo = getSystemInfo();
+      sysInfo.cpuUsage = getCpuUsage();
+      const gwUptime = getGatewayUptime();
+      render(sysInfo, gwUptime, prevSessions.length, prevSessions, null, CONFIG.delay);
+    }
+    
+    // Calculate sleep time - use shorter interval when paused/input
+    const sleepTime = (paused || showingHelp || awaitingInput) ? 500 : CONFIG.delay * 1000;
+    await new Promise(resolve => setTimeout(resolve, sleepTime));
+  }
+  
+  console.log(C.gray + '\nCompleted ' + CONFIG.iterations + ' iterations.' + C.reset);
+}
+
+main().catch(err => {
+  console.error(C.red + 'Fatal error: ' + err.message + C.reset);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "clawps",
+  "version": "1.0.0",
+  "description": "OpenClaw session utilities, in the style of the procps package",
+  "main": "clawps.js",
+  "bin": {
+    "clawps": "./clawps.js",
+    "clawtop": "./clawtop.js"
+  },
+  "scripts": {
+    "install": "node install.js"
+  },
+  "keywords": ["openclaw", "cli", "sessions", "procps", "utilities"],
+  "author": "Kevin Smith",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}