psinetron-opencode-visualizer 1.0.3 → 1.0.5

package/LICENSE

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

@@ -1,40 +1,60 @@
-# OpenCode Visualizer
+# 👾 psinetron-opencode-visualizer
 
-Real-time pixel-art office scene that visualizes OpenCode AI agent sessions. Watch your agents walk, sit at desks, type on laptops, drink coffee, and react to events — all rendered in a charming retro pixel-art style.
+[![MIT License](https://img.shields.io/github/license/psinetron/opencode-visualiser)](https://github.com/psinetron/opencode-visualiser/blob/main/LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/psinetron/opencode-visualiser.svg)](https://github.com/psinetron/opencode-visualiser/stargazers)
+[![NPM Version](https://img.shields.io/npm/v/psinetron-opencode-visualizer.svg)](https://www.npmjs.com/package/psinetron-opencode-visualizer)
 
-![OpenCode Visualizer](visualizer/textures/background.png)
+**Bringing the custom cruiser ethos to AI orchestration.** Turning raw OpenCode terminal logs into cozy 2D pixel office chaos. Watch your agents work, idle, and celebrate success in a bustling virtual office.
 
-## Features
+---
 
-- **5 unique pixel-art characters** — each with distinct idle, working, and reaction animations
-- **12 animation states** — idle, walking, sitting, typing, drinking coffee, scratching head, yawning, error reactions, and more
-- **Persistent office layout** — 5 desks, a coffee zone, and a rest area with Y-sorted rendering
-- **Real-time WebSocket sync** — events stream from OpenCode sessions to the visualizer instantly
-- **Cross-platform standalone window** — automatically opens in Chrome app mode on macOS, Windows, and Linux; falls back to default browser
+## 🔥 Witness the Chaos
 
-## Requirements
+<img src="images/cover.png" width="100%" alt="OpenCode Visualizer" />
 
-- [OpenCode](https://opencode.ai)
-- [Bun](https://bun.sh) (runtime)
-- Chrome, Chromium, or Edge (for app-mode window; optional — any browser works)
+<!--
+THIS IS THE MOST IMPORTANT PART FOR HYPE.
+When you create your video-demo for X.com (MP4), convert it to a small GIF (e.g., using CapCut or online converters like ezgif) and place it here.
 
-## Installation
+For example, uncomment the line below when you have a GIF in your repo:
+
+<img src="visualizer-demo.gif" width="100%" alt="OpenCode Visualizer Demo" />
+
+*Placeholder for the awesome video demo you are going to record. It should show the JSON logs in the terminal transforming into the pixel art office.*
+-->
+
+---
+
+## ✨ Features
+
+- **Real-time Visualization:** Watch your OpenCode agents move around their office as they execute tools, search files, and write code.
+- **Cozy Pixel Art Aesthetic:** A calming, gamified view of complex AI orchestration.
+- **Mult-Agent Support:** Visualizes multiple agents (Explore, Scout, etc.) simultaneously in the same shared office space.
+- **Customization (Skins):** Each agent has a custom skin saved in `.opencode/viz-skin.json`.
+- **Unique Agent Animations:** Each of the 5 characters has its own set of unique idle, walk, work, and reaction animations.
+- **Zero Friction Launch:** Pure Bun & TypeScript. Launches a cross-platform, isolated Chrome "app" window using native OS calls. No heavy Electron needed.
+
+---
+
+## 🚀 Installation
+
+*Note: Requires [Bun](https://bun.sh) to be installed.*
 
 ### Via OpenCode UI (recommended)
 
-1. Press `Cmd+P` (`Ctrl+P` on Windows/Linux) to open the command palette
+1. Press `Control+P` (`Ctrl+P` on Windows/Linux) to open the command palette
 2. Select **Install plugin**
-3. Enter the package name: `slybeaver-opencode-visualizer`
+3. Enter the package name: `psinetron-opencode-visualizer`
 
 OpenCode will install the plugin and automatically add it to your project's `opencode.json`.
 
 ### Manual configuration
 
-Add the plugin to your OpenCode config (`opencode.json` or `opencode.jsonc`):
+Add the plugin to your OpenCode config (`opencode.json`):
 
 ```json
 {
-  "plugin": ["slybeaver-opencode-visualizer"]
+  "plugin": ["psinetron-opencode-visualizer"]
 }
 ```
 
@@ -46,68 +66,18 @@ Or install from a local path:
 }
 ```
 
-## How It Works
 
-```
-OpenCode session
-    │ event hook
-    ▼
-Plugin (index.ts) ─── WebSocket ───► Bun Server (port 5173)
-                                          │ broadcast
-                                          ▼
-                                   Frontend (Canvas, 1024×768)
-                                   Pixel-art office with animated agents
-```
 
-1. The plugin starts a Bun HTTP + WebSocket server on `localhost:5173`
-2. It opens the visualizer in a Chrome app window (or your default browser)
-3. OpenCode session events stream through WebSocket to the visualizer
-4. The canvas renders agents navigating the office, sitting at desks, and animating in real time
+---
 
-## Project Structure
+## 🎨 Customization (Skins)
 
-```
-├── index.ts              # Plugin entry point (server + WebSocket + Chrome launcher)
-├── opencode.json         # OpenCode plugin manifest
-├── package.json          # npm metadata
-├── visualizer/
-│   ├── index.html        # SPA canvas app (all rendering logic in <script>)
-│   ├── textures/         # Background, desk, and coffee table sprites
-│   └── person1-5/        # Character sprites (8 rotation + 6-8 animation types each)
-│       └── personN/
-│           ├── rotations/     # Direction sprites (N, S, E, W, NE, NW, SE, SW)
-│           └── animations/   # Frame-by-frame animation sprites (idle, walk, sit, work, coffee, scratch, yawn)
-```
+The plugin automatically assigns a random pixel art skin to each agent and saves it to `.opencode/viz-skin.json` in your project folder. You can manually edit this file to change skins.
 
-## Agent States
-
-| State | Description |
-|-------|-------------|
-| `idle` | Standing still, breathing animation |
-| `walking` | Walking to a destination |
-| `walking_to_desk` | Heading to an assigned desk |
-| `sitting` | Sitting down transition |
-| `working` | Typing on a laptop |
-| `drinking` | At the coffee zone |
-| `scratching` | Idle desk animation — scratching head |
-| `yawning` | Idle desk animation — yawning |
-| `error` | Reacting to an error |
-| `flash` | White flash on session diff |
-| `idle_rest` | Standing in the rest area |
-| `leaving` | Walking to the exit door |
-
-## Development
-
-```bash
-# Run the plugin (requires OpenCode)
-opencode
-
-# The visualizer runs at http://localhost:5173
-# Open it manually in any browser
-```
+Available skins: `person1`, `person2`, `person3`, `person4`, `person5`.
 
-No build step required — Bun runs TypeScript directly.
+---
 
-## License
+## 📜 License
 
-MIT
+MIT License. See LICENSE for more information. Built, not bought, by psinetron.

package/index.ts

@@ -1,182 +1,21 @@
 import type { Plugin } from "@opencode-ai/plugin"
 import { join } from "path"
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs"
-import { platform } from "os"
 
 const SERVER_PORT = 5173
+const DAEMON_PATH = join(import.meta.dir, "visualizer", "ocv-server.ts")
 
-// ─── WebSocket server ───────────────────────────────────────────────
+let daemonStarted = false
 
-interface PluginClient {
-  instanceId: string
-  ws: WebSocket
-  cwd: string
-  skin: string
-  connectedAt: number
-}
-
-interface FrontendClient {
-  ws: WebSocket
-}
-
-const pluginClients = new Map<string, PluginClient>()
-const frontendClients = new Set<FrontendClient>()
-let windowOpened = false
-function broadcast(data: Record<string, unknown>) {
-  const msg = JSON.stringify(data)
-  for (const client of frontendClients) {
-    if (client.ws.readyState === WebSocket.OPEN) {
-      try { client.ws.send(msg) } catch {}
-    }
-  }
-}
-
-function openBrowserWindow() {
-  if (windowOpened) return
-  windowOpened = true
-  const url = `http://localhost:${SERVER_PORT}`
-
-  setTimeout(() => {
-    if (frontendClients.size > 0) return
-
-    const os = platform()
-
-    try {
-      if (os === "darwin") {
-        Bun.spawn(["open", "-n", "-a", "Google Chrome", "--args", `--app=${url}`, "--window-size=1024,768"], {
-          stdio: ["ignore", "ignore", "ignore"],
-        })
-      } else if (os === "win32") {
-        Bun.spawn(["cmd.exe", "/c", "start", "chrome", `--app=${url}`, "--window-size=1024,768"], {
-          stdio: ["ignore", "ignore", "ignore"],
-        })
-      } else {
-        Bun.spawn(["google-chrome", `--app=${url}`, "--window-size=1024,768"], {
-          stdio: ["ignore", "ignore", "ignore"],
-        })
-      }
-    } catch {
-      console.warn(`[visualizer] Failed to open Chrome app window, open manually: ${url}`)
-    }
-  }, 3000)
-}
-
-let shutdownTimer: ReturnType<typeof setTimeout> | null = null
-let server: ReturnType<typeof Bun.serve> | null = null
-
-function resetShutdownTimer() {
-  if (shutdownTimer) clearTimeout(shutdownTimer)
-  shutdownTimer = setTimeout(() => {
-    if (pluginClients.size === 0) {
-      server?.stop()
-      process.exit(0)
-    }
-  }, 10_000)
-}
-
-try {
-  const VISUALIZER_DIR = join(import.meta.dir, "visualizer")
-
-  server = Bun.serve({
-    port: SERVER_PORT,
-    hostname: "127.0.0.1",
-    async fetch(req) {
-      if (server.upgrade(req)) {
-        return
-      }
-      try {
-        const url = new URL(req.url)
-        const pathname = url.pathname === "/" ? "/index.html" : url.pathname
-        const filePath = join(VISUALIZER_DIR, pathname)
-        if (existsSync(filePath)) {
-          return new Response(Bun.file(filePath), {
-            headers: { "Cache-Control": "no-store, no-cache, must-revalidate" },
-          })
-        }
-        return new Response("Not found", { status: 404 })
-      } catch {
-        return new Response("<h1>Visualization server — error</h1>", {
-          headers: { "Content-Type": "text/html" },
-          status: 500,
-        })
-      }
-    },
-    websocket: {
-      open(_ws) {},
-      message(ws, message) {
-        let data: Record<string, unknown>
-        try {
-          data = JSON.parse(message as string)
-        } catch {
-          return
-        }
-
-        switch (data.type) {
-          case "register": {
-            const id = data.instanceId as string
-            pluginClients.set(id, {
-              instanceId: id,
-              ws,
-              cwd: (data.cwd as string) || "",
-              skin: (data.skin as string) || "",
-              connectedAt: Date.now(),
-            })
-
-            broadcast({
-              type: "instance.added",
-              instanceId: id,
-              cwd: data.cwd,
-              skin: data.skin,
-            })
-
-            openBrowserWindow()
-            resetShutdownTimer()
-            break
-          }
-
-          case "frontend.register": {
-            frontendClients.add({ ws })
-            const instances = [...pluginClients.values()].map((c) => ({
-              instanceId: c.instanceId,
-              cwd: c.cwd,
-              skin: c.skin,
-            }))
-            ws.send(JSON.stringify({ type: "state.sync", instances }))
-            break
-          }
-
-          case "event": {
-            broadcast({
-              type: "instance.event",
-              instanceId: data.instanceId,
-              event: data.event,
-            })
-            break
-          }
-        }
-      },
-      close(ws) {
-        for (const [id, client] of pluginClients) {
-          if (client.ws === ws) {
-            pluginClients.delete(id)
-            broadcast({ type: "instance.removed", instanceId: id })
-            break
-          }
-        }
-
-        for (const client of frontendClients) {
-          if (client.ws === ws) {
-            frontendClients.delete(client)
-            break
-          }
-        }
-
-        resetShutdownTimer()
-      },
-    },
-  })
-} catch (err) {
-  console.error("[visualizer] Failed to start server:", err)
+function ensureDaemon() {
+  if (daemonStarted) return
+  daemonStarted = true
+  try {
+    const proc = Bun.spawn(["bun", DAEMON_PATH], {
+      stdio: ["ignore", "ignore", "ignore"],
+    })
+    proc.unref()
+  } catch {}
 }
 
 // ─── Plugin client ──────────────────────────────────────────────────
@@ -200,7 +39,7 @@ function resolveSkin(cwd: string): string {
 
 let ws: WebSocket | null = null
 let reconnectTimer: ReturnType<typeof setTimeout> | null = null
-const instanceId = `oc-${process.pid}-${Math.random().toString(36).slice(2, 8)}`
+const instanceId = `oc-${process.pid}-${Math.random().toString(36).substring(2, 10)}`
 
 function connectToServer(skin: string): Promise<void> {
   return new Promise((resolve, reject) => {
@@ -265,7 +104,9 @@ function sendEvent(eventType: string, payload: Record<string, unknown> = {}) {
 
 const VisualizerPlugin: Plugin = async ({ project, client, $, directory, worktree }) => {
   const skin = resolveSkin(directory)
-  // Wait up to 6 seconds for the server to be ready
+
+  ensureDaemon()
+
   for (let i = 0; i < 20; i++) {
     try {
       await connectToServer(skin)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "psinetron-opencode-visualizer",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "main": "index.ts",
   "description": "OpenCode session visualizer — real-time pixel-art office scene with animated agents",
   "files": [
@@ -9,5 +9,8 @@
   ],
   "keywords": ["opencode", "opencode-plugin", "visualizer", "monitor"],
   "license": "MIT",
-  "type": "module"
+  "type": "module",
+  "devDependencies": {
+    "@opencode-ai/plugin": "^0.1.0"
+  }
 }

package/visualizer/index.html

@@ -248,6 +248,8 @@ function getFreeCoffeeSpot() {
 }
 
 function createAgent(instanceId, cwd, skin) {
+  const existing = agents.find(a => a.instanceId === instanceId)
+  if (existing) return existing
   if (agents.length >= 5) return null
   const id = agentIdCounter++
   const skinIds = Object.keys(SKINS)
@@ -752,24 +754,21 @@ function connect() {
     try { data = JSON.parse(e.data) } catch { return }
 
     switch (data.type) {
-      case "state.sync":
-        {
-          const syncIds = new Set((data.instances || []).map(inst => inst.instanceId))
-          if (syncIds.size > 0) {
-            for (const a of [...agents]) {
-              if (!syncIds.has(a.instanceId)) {
-                removeAgent(a.instanceId)
-              }
-            }
-            for (const inst of data.instances || []) {
-              const existing = agents.find(a => a.instanceId === inst.instanceId)
-              if (!existing) {
-                createAgent(inst.instanceId, inst.cwd, inst.skin)
-              }
-            }
+      case "state.sync": {
+        const syncIds = new Set((data.instances || []).map(i => i.instanceId))
+        for (const a of [...agents]) {
+          if (!syncIds.has(a.instanceId)) {
+            removeAgent(a.instanceId)
+          }
+        }
+        for (const inst of data.instances || []) {
+          const existing = agents.find(a => a.instanceId === inst.instanceId)
+          if (!existing) {
+            createAgent(inst.instanceId, inst.cwd, inst.skin)
           }
         }
         break
+      }
       case "instance.added":
         createAgent(data.instanceId, data.cwd, data.skin)
         break

package/visualizer/ocv-server.ts

@@ -0,0 +1,153 @@
+// ocv-server.ts — standalone WebSocket server daemon
+// Lives independently of any opencode instance — survives plugin process kills
+import { join } from "path"
+import { existsSync } from "fs"
+import { platform } from "os"
+
+const SERVER_PORT = 5173
+
+interface PluginClient {
+  instanceId: string
+  ws: WebSocket
+  cwd: string
+  skin: string
+  connectedAt: number
+}
+
+interface FrontendClient {
+  ws: WebSocket
+}
+
+const pluginClients = new Map<string, PluginClient>()
+const frontendClients = new Set<FrontendClient>()
+
+function broadcast(data: Record<string, unknown>) {
+  const msg = JSON.stringify(data)
+  for (const client of frontendClients) {
+    if (client.ws.readyState === WebSocket.OPEN) {
+      try { client.ws.send(msg) } catch {}
+    }
+  }
+}
+
+function openBrowser() {
+  const url = `http://localhost:${SERVER_PORT}`
+  const os = platform()
+
+  setTimeout(() => {
+    if (frontendClients.size > 0) return
+    try {
+      if (os === "darwin") {
+        Bun.spawn(["open", "-n", "-a", "Google Chrome", "--args", `--app=${url}`, "--window-size=1024,768"], {
+          stdio: ["ignore", "ignore", "ignore"],
+        })
+      } else if (os === "win32") {
+        Bun.spawn(["cmd.exe", "/c", "start", "chrome", `--app=${url}`, "--window-size=1024,768"], {
+          stdio: ["ignore", "ignore", "ignore"],
+        })
+      } else {
+        Bun.spawn(["google-chrome", `--app=${url}`, "--window-size=1024,768"], {
+          stdio: ["ignore", "ignore", "ignore"],
+        })
+      }
+    } catch {
+      // Nothing to do — user can open manually
+    }
+  }, 3000)
+}
+
+let shutdownTimer: ReturnType<typeof setTimeout> | null = null
+let server: ReturnType<typeof Bun.serve> | null = null
+
+function resetShutdownTimer() {
+  if (shutdownTimer) clearTimeout(shutdownTimer)
+  shutdownTimer = setTimeout(() => {
+    if (pluginClients.size === 0 && frontendClients.size === 0) {
+      server?.stop()
+      process.exit(0)
+    }
+  }, 300_000)
+}
+
+const VISUALIZER_DIR = import.meta.dir
+
+server = Bun.serve({
+  port: SERVER_PORT,
+  hostname: "127.0.0.1",
+  async fetch(req) {
+    if (server.upgrade(req)) return
+    try {
+      const url = new URL(req.url)
+      const pathname = url.pathname === "/" ? "/index.html" : url.pathname
+      const filePath = join(VISUALIZER_DIR, pathname)
+      if (existsSync(filePath)) {
+        return new Response(Bun.file(filePath), {
+          headers: { "Cache-Control": "no-store, no-cache, must-revalidate" },
+        })
+      }
+      return new Response("Not found", { status: 404 })
+    } catch {
+      return new Response("<h1>Server error</h1>", {
+        headers: { "Content-Type": "text/html" },
+        status: 500,
+      })
+    }
+  },
+  websocket: {
+    open(_ws) {},
+    message(ws, message) {
+      let data: Record<string, unknown>
+      try { data = JSON.parse(message as string) } catch { return }
+
+      switch (data.type) {
+        case "register": {
+          const id = data.instanceId as string
+          pluginClients.set(id, {
+            instanceId: id,
+            ws,
+            cwd: (data.cwd as string) || "",
+            skin: (data.skin as string) || "",
+            connectedAt: Date.now(),
+          })
+          broadcast({ type: "instance.added", instanceId: id, cwd: data.cwd, skin: data.skin })
+          ws.send(JSON.stringify({ type: "registered" }))
+          openBrowser()
+          resetShutdownTimer()
+          break
+        }
+        case "frontend.register": {
+          frontendClients.add({ ws })
+          const instances = [...pluginClients.values()].map((c) => ({
+            instanceId: c.instanceId,
+            cwd: c.cwd,
+            skin: c.skin,
+          }))
+          ws.send(JSON.stringify({ type: "state.sync", instances }))
+          break
+        }
+        case "event": {
+          broadcast({ type: "instance.event", instanceId: data.instanceId, event: data.event })
+          break
+        }
+      }
+    },
+    close(ws) {
+      for (const [id, client] of pluginClients) {
+        if (client.ws === ws) {
+          pluginClients.delete(id)
+          broadcast({ type: "instance.removed", instanceId: id })
+          break
+        }
+      }
+      for (const client of frontendClients) {
+        if (client.ws === ws) {
+          frontendClients.delete(client)
+          break
+        }
+      }
+      resetShutdownTimer()
+    },
+  },
+})
+
+console.log(`[ocv-server] Listening on http://localhost:${SERVER_PORT}`)