openclaw-inspector 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Taras Lukavyi
+
+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,136 @@
+# OpenClaw Inspector 🔍
+
+**Your AI agent has full access to your machine. Are you sure it's behaving?**
+
+[OpenClaw](https://openclaw.ai) (and Clawdbot) can run shell commands, edit files, push to git, install packages, access your camera, take screenshots — essentially do *anything* on your system. It runs autonomously in background sessions, cron jobs, and sub-agents. Most of the time, you never see what it does.
+
+**OpenClaw Inspector** lets you see everything. It's a local web app that reads your bot's session history and shows you exactly what happened — every command, every file edit, every tool call. It automatically flags dangerous actions so you can catch problems before they escalate.
+
+## When you need this
+
+- 🤔 **"What did my bot do while I was away?"** — Browse all sessions including deleted ones
+- 🚨 **"Did it run anything dangerous?"** — Auto-detects `rm -rf`, `git push --force`, `sudo`, config edits, secret exposure, and more
+- 📱 **"Did it access my camera/screen?"** — Flags surveillance actions (screenshots, camera, location tracking)
+- 📊 **"I have 100+ sessions, how do I review them all?"** — Track read progress, filter by status, mark sessions as reviewed
+- 🔄 **"I want to monitor in real-time"** — Live updates via SSE, toast notifications for new messages
+
+## Quick start
+
+```bash
+npx openclaw-inspector
+```
+
+Opens at http://localhost:9100. That's it.
+
+### Custom port
+
+```bash
+PORT=9101 npx openclaw-inspector
+```
+
+### Custom sessions directory
+
+```bash
+SESSIONS_DIR=~/.openclaw/agents/main/sessions npx openclaw-inspector
+```
+
+## What it detects
+
+| Category | Examples | Severity |
+|----------|----------|----------|
+| **Destructive filesystem** | `rm -rf`, `shred`, `find -delete` | 🔴 Critical |
+| **Git destructive** | `git push --force`, `git reset --hard`, `git clean -f` | 🔴 Critical |
+| **Repo/account actions** | `gh repo delete`, `gh repo edit --visibility public` | 🔴 Critical |
+| **Config changes** | `sed -i`, writing to `.env`, `.ssh/`, `.zshrc` | 🟡 Warning |
+| **Package/system** | `sudo`, `brew uninstall`, `chmod 777` | 🟡 Warning |
+| **Process killing** | `kill -9`, `killall`, `pkill` | 🟡 Warning |
+| **Secrets/network** | `curl -X POST`, exported tokens/passwords | 🟡 Warning |
+| **Surveillance** | Screenshots, camera access, screen recording, location | 🟡 Warning |
+| **Cron changes** | `crontab`, `launchctl`, `systemctl` | 🟡 Warning |
+
+Rules are fully customizable — edit `~/.openclaw-inspector/danger-rules.json`.
+
+## Features
+
+- **Multi-axis filtering** — filter by review status (unread/in progress/reviewed), session type (active/orphan/deleted), and danger level — all combinable
+- **Read progress tracking** — click any message to mark everything up to that point as reviewed; a blue divider shows where you left off
+- **Live updates** — new messages and sessions appear automatically with toast notifications
+- **Tool call previews** — see URLs, file paths, search queries, and commands inline without expanding
+- **Session renaming** — click the title to give any session a custom label
+- **Message search** — full-text search within a session
+- **Mobile responsive** — works on phones and tablets
+- **State persistence** — all filters, sort order, and UI state saved in localStorage
+
+## Live monitoring
+
+Inspector watches your sessions directory in real-time. When your bot starts a new conversation, receives a message, or runs a tool — it appears instantly in the UI. No need to refresh the page.
+
+- New sessions appear in the sidebar automatically
+- New messages stream into the currently open session
+- Toast notifications show activity in other sessions
+- Works for background sessions, cron jobs, and sub-agents too
+
+## Privacy & security
+
+- 🔒 **100% local** — everything runs on your machine. No cloud, no telemetry, no external connections
+- 📁 **Read-only** — Inspector never modifies, deletes, or interferes with your sessions. It only reads JSONL files from disk
+- 🏠 **Localhost only** — server binds to `127.0.0.1` by default, inaccessible from the network
+- 💾 **Your data stays yours** — progress and settings stored in `~/.openclaw-inspector/`, never sent anywhere
+
+## Configuration
+
+### Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | `9100` | Server port |
+| `HOST` | `127.0.0.1` | Bind address (localhost only by default) |
+| `SESSIONS_DIR` | auto-detect (`~/.openclaw/` or `~/.clawdbot/`) | Path to session JSONL files |
+| `DATA_DIR` | `~/.openclaw-inspector` | User config and progress storage |
+
+### User data (`~/.openclaw-inspector/`)
+
+Created automatically on first launch:
+
+- `danger-rules.json` — danger detection rules (customize freely, won't be overwritten on updates)
+- `progress.json` — read progress (persists across devices if you sync the folder)
+
+### Remote access via Tailscale
+
+To access Inspector from your phone or another device:
+
+```bash
+# Serve local port via Tailscale HTTPS
+tailscale serve https:9100 / http://localhost:9100
+```
+
+Then open `https://your-machine.tailnet.ts.net:9100` from any device on your tailnet.
+
+## Development
+
+```bash
+git clone https://github.com/Lukavyi/openclaw-inspector.git
+cd openclaw-inspector
+npm install
+
+# Terminal 1: Backend
+node server.js
+
+# Terminal 2: Vite dev server with HMR
+npm run dev
+```
+
+Open http://localhost:5173 (proxies API to backend).
+
+```bash
+npm test          # Unit tests (Vitest)
+npm run build     # Production build → dist/
+```
+
+## Built with OpenClaw 🤖
+
+This entire project was vibe-coded through [OpenClaw](https://openclaw.ai) — from the first line of code to npm publish. No manual coding involved. The irony of an AI agent building its own inspector is not lost on us.
+
+## License
+
+MIT

package/danger-rules.json

@@ -0,0 +1,110 @@
+{
+  "rules": [
+    {
+      "category": "destructive-fs",
+      "severity": "critical",
+      "label": "Destructive filesystem",
+      "patterns": [
+        "rm\\s+(-[a-zA-Z]*r[a-zA-Z]*|--recursive)",
+        "rm\\s+(-[a-zA-Z]*f[a-zA-Z]*)",
+        "rmdir\\s",
+        "shred\\s",
+        "unlink\\s",
+        "find\\s.*-delete",
+        "find\\s.*-exec\\s+rm"
+      ]
+    },
+    {
+      "category": "git-destructive",
+      "severity": "critical",
+      "label": "Git destructive",
+      "patterns": [
+        "git\\s+push\\s+(-[a-zA-Z]*f|--force)",
+        "git\\s+reset\\s+--hard",
+        "git\\s+clean\\s+(-[a-zA-Z]*f)",
+        "git\\s+checkout\\s+--\\s+\\.",
+        "git\\s+branch\\s+(-[a-zA-Z]*[dD])"
+      ]
+    },
+    {
+      "category": "repo-actions",
+      "severity": "critical",
+      "label": "Repo/account actions",
+      "patterns": [
+        "gh\\s+repo\\s+delete",
+        "gh\\s+repo\\s+edit\\s+--visibility\\s+public",
+        "gh\\s+issue\\s+delete",
+        "gh\\s+pr\\s+close"
+      ]
+    },
+    {
+      "category": "config-changes",
+      "severity": "warning",
+      "label": "Config changes",
+      "patterns": [
+        "\\b(nano|vim|vi|code|edit)\\s+.*\\.(env|json|ya?ml|toml|conf|cfg|ini)\\b",
+        "\\bsed\\s+(-[a-zA-Z]*i)",
+        "\\b(cat|echo|printf)\\s.*>\\s*.*\\.(env|json|ya?ml|toml|conf|cfg)",
+        "\\.ssh/",
+        "\\.gitconfig",
+        "\\.zshrc",
+        "\\.zprofile",
+        "\\.bashrc"
+      ]
+    },
+    {
+      "category": "package-system",
+      "severity": "warning",
+      "label": "Package/system changes",
+      "patterns": [
+        "brew\\s+(uninstall|remove)",
+        "npm\\s+(uninstall|remove)\\s+-g",
+        "pip\\s+uninstall",
+        "chmod\\s+(777|666|000)",
+        "chown\\s",
+        "sudo\\s"
+      ]
+    },
+    {
+      "category": "process-kill",
+      "severity": "warning",
+      "label": "Process killing",
+      "patterns": [
+        "kill\\s+(-9|-SIGKILL)",
+        "killall\\s",
+        "pkill\\s"
+      ]
+    },
+    {
+      "category": "secrets-network",
+      "severity": "warning",
+      "label": "Secrets/network",
+      "patterns": [
+        "curl\\s.*(-X\\s*POST|-d\\s)",
+        "(token|secret|password|api.?key)=\\S+",
+        "\\bexport\\s+(TOKEN|SECRET|API_KEY|PASSWORD)"
+      ]
+    },
+    {
+      "category": "cron-changes",
+      "severity": "warning",
+      "label": "Cron changes",
+      "patterns": [
+        "crontab\\s",
+        "launchctl\\s+(load|unload|remove)",
+        "systemctl\\s+(enable|disable|stop)"
+      ]
+    },
+    {
+      "category": "surveillance",
+      "severity": "warning",
+      "label": "Surveillance/privacy",
+      "toolRules": [
+        { "toolName": "browser", "actions": ["screenshot", "snapshot"] },
+        { "toolName": "nodes", "actions": ["camera_snap", "camera_clip", "camera_list", "screen_record", "location_get"] },
+        { "toolName": "image", "actions": null },
+        { "toolName": "peekaboo", "actions": null }
+      ]
+    }
+  ]
+}