@foothill/agent-move 1.0.6

package/README.md

@@ -0,0 +1,266 @@
+<div align="center">
+
+# AgentMove
+
+**Watch your AI coding agents come alive.**
+
+A real-time pixel-art visualizer that turns AI coding sessions into a living 2D world. Agents walk between rooms, use tools, chat, and rest — all rendered at 60fps in your browser.
+
+```
+npx agent-move@latest
+```
+
+<br>
+
+<img src=".github/screenshot.png" alt="AgentMove screenshot showing pixel-art agents in a 2D world with 9 activity zones" width="800">
+
+<br>
+<br>
+
+[![npm version](https://img.shields.io/npm/v/agent-move)](https://www.npmjs.com/package/agent-move)
+[![license](https://img.shields.io/npm/l/agent-move)](LICENSE)
+
+</div>
+
+---
+
+## What You're Looking At
+
+AgentMove reads AI coding agent session files and maps every tool call to one of **9 activity zones**. Each agent gets a unique pixel-art character that physically walks between zones as it works.
+
+It uses a **hybrid data pipeline** — JSONL file watching for rich data (tokens, costs, full text) combined with Claude Code hooks for precise lifecycle events (session start/end, tool success/failure, permissions).
+
+| Zone | What Happens There | Tools |
+|------|--------------------|-------|
+| **Files** | Reading, writing, editing code | Read, Write, Edit, Glob |
+| **Terminal** | Running shell commands | Bash |
+| **Search** | Searching code and the web | Grep, WebSearch |
+| **Web** | Browsing, fetching, MCP tools | WebFetch, Playwright, MCP `*` |
+| **Thinking** | Planning and asking questions | EnterPlanMode, AskUserQuestion |
+| **Messaging** | Talking to other agents | SendMessage |
+| **Tasks** | Managing work items | TaskCreate, TaskUpdate |
+| **Spawn** | Agents arriving and departing | Agent, TeamCreate |
+| **Idle** | Resting after inactivity | — |
+
+## Getting Started
+
+### Prerequisites
+
+- **Node.js 18+**
+- **Claude Code** installed and used at least once (so `~/.claude/` exists)
+- Works on **Windows**, **macOS**, and **Linux**
+
+### One Command
+
+```bash
+npx agent-move@latest
+```
+
+That's it. The server starts, hooks are auto-installed, your browser opens, and any active coding session is visualized immediately.
+
+On first run, AgentMove automatically:
+1. Installs Claude Code hooks into `~/.claude/settings.json` (17 event types)
+2. Creates a hook script at `~/.agent-move/hooks/hook-sender.js`
+3. Starts the server and opens your browser
+
+### Options
+
+```bash
+npx agent-move@latest --port 4000    # custom port (default: 3333)
+npx agent-move@latest --no-open      # don't auto-open the browser
+npx agent-move@latest --help         # show all options
+```
+
+### Hooks Management
+
+Hooks are auto-installed on first run. You can also manage them manually:
+
+```bash
+npx agent-move@latest hooks status      # check if hooks are installed
+npx agent-move@latest hooks install     # (re)install hooks
+npx agent-move@latest hooks uninstall   # remove hooks
+```
+
+AgentMove works without hooks too — it falls back to JSONL file watching. Hooks add precise session lifecycle, tool success/failure tracking, and permission management.
+
+### From Source (for development)
+
+```bash
+git clone https://github.com/AbdullahSAhmad/agent-move.git
+cd agent-move
+npm install
+npm run dev
+```
+
+This starts the server on `:3333` and the Vite dev server on `:5173` with hot reload.
+
+## Features
+
+### Hooks Integration
+
+- **Auto-install** — hooks are set up on first run, no manual config needed
+- **17 event types** — SessionStart, SessionEnd, PreToolUse, PostToolUse, PermissionRequest, SubagentStart, and more
+- **Precise lifecycle** — exact session start/end instead of timeout guessing
+- **Tool outcomes** — see green (success) vs red (failure) on completed tool calls
+- **Permission management** — approve/deny tool permissions from the visualization UI
+- **Notification dashboard** — priority-based feed of permissions, failures, idle alerts
+- **Graceful fallback** — everything works without hooks via JSONL watching
+
+### Visualization
+
+- **Programmatic pixel-art sprites** — 16x16 characters rendered at 3x scale, no external image assets
+- **12 color palettes** — each agent gets a distinct look
+- **6 sprite variants** — Human, Robot, Wizard, Ninja, Skeleton, Slime
+- **Animations** — idle breathing, walking between zones, working effects
+- **Role badges** — MAIN, SUB, LEAD, MEMBER based on session type
+- **Speech bubbles** — show the current tool or text output above each agent
+- **Relationship lines** — dashed connections between parent/child and team agents
+- **Zone glow** — rooms light up when agents are inside
+- **Particle effects** — sparkles on tool use
+- **Agent trails** — toggle fading trail dots behind moving agents (`T`)
+- **Day/night cycle** — ambient lighting based on your local time (`N`)
+- **4 themes** — Office, Space, Castle, Cyberpunk — selectable from the top bar
+- **Glassmorphism UI** — modern bento-grid layout with flow lines
+
+### Dashboard
+
+- **Sidebar navigation** — collapsible sidebar with section navigation
+- **Top bar** — live stats (active agents, idle count, total cost, token velocity), and quick actions
+- **Agent list** — live sidebar with zone, current tool, token counts, and status indicators
+- **Agent detail panel** — click any agent to see model, role, tokens, uptime, git branch, recent files with diff viewer, and scrolling activity feed
+- **Agent customization** — rename agents and change their color palette (persisted in localStorage)
+- **Minimap** — clickable overview showing zone layout, agent positions, and viewport (`` ` ``)
+- **Activity feed** — scrollable event log with timestamps and filtering
+- **Waterfall view** — Chrome DevTools-style timeline showing tool durations per agent
+- **Relationship graph** — interactive force-directed graph of agent parent/child/teammate connections
+
+### Analytics
+
+- **Total cost tracking** — real-time cost estimation including cache read/creation token pricing
+- **Cache efficiency** — cache hit rate percentage and estimated savings
+- **Token velocity** — tokens/min with sparkline chart and trend indicator
+- **Cost by agent** — per-agent cost breakdown with bar charts
+- **Time by zone** — cumulative time distribution across zones (including idle)
+- **Tool usage** — frequency breakdown of the most-used tools
+- **Session duration** — per-agent uptime with active/idle status
+- **Cost threshold alerts** — configurable budget alert with visual notification
+
+### Leaderboard
+
+- **Agent rankings** — sortable by tokens, cost, duration, or tool count
+- **Medal badges** — top 3 agents highlighted
+- **Visual bars** — proportional token usage comparison
+
+### Navigation & Controls
+
+- **Pan & zoom** — scroll wheel to zoom, click and drag to pan the world
+- **Command palette** — fuzzy search for any action (`Ctrl+K`)
+- **Focus mode** — follow an agent with smooth camera tracking (`F` to cycle, `Esc` to exit)
+- **Timeline** — scrubber with live/replay modes, speed control (0.5x–8x), event filters, and per-agent swim lanes
+- **Session export** — generate a markdown report of the session (`E`)
+- **Sound effects** — synthesized audio for spawn, zone changes, tool use, idle, and shutdown (`M` to mute)
+- **Toast notifications** — popup alerts for agent lifecycle events (spawn, idle, shutdown)
+- **Keyboard shortcuts** — press `?` to see all available shortcuts
+- **Auto-reconnect** — WebSocket reconnects with exponential backoff if the connection drops
+
+## How It Works
+
+```
+                    ┌─────────────────┐
+Hook events ──────→ │                 │
+  (17 types,        │  AgentState     │
+   push-based)      │  Manager        │──→ Broadcaster ──→ WebSocket ──→ Client
+                    │                 │
+JSONL watching ───→ │  (merged state) │
+  (byte-offset,     └─────────────────┘
+   pull-based)
+```
+
+Hook events provide **lifecycle accuracy** (exact session start/end, tool success/failure).
+JSONL parsing provides **rich data** (token counts, costs, full response text).
+
+## Architecture
+
+Three-package monorepo (npm workspaces):
+
+```
+agent-move/
+├── bin/cli.js              # npx entry point (auto-installs hooks)
+├── packages/
+│   ├── shared/             # Types & constants (zero dependencies)
+│   │   └── src/
+│   │       ├── types/          AgentState, HookEvent, ServerMessage, ZoneConfig
+│   │       └── constants/      tool→zone map, zone configs, color palettes
+│   ├── server/             # Fastify backend
+│   │   └── src/
+│   │       ├── hooks/          hook event manager, hook installer
+│   │       ├── watcher/        chokidar file watcher, JSONL parser
+│   │       ├── state/          agent state machine, anomaly detector, tool chains
+│   │       ├── ws/             WebSocket broadcaster
+│   │       └── routes/         REST API
+│   └── client/             # Pixi.js frontend
+│       └── src/
+│           ├── sprites/        pixel-art data, palette resolver, sprite variants
+│           ├── world/          zone renderer, grid, camera, themes, layout engine
+│           ├── agents/         sprite logic, movement, relationships
+│           ├── effects/        particles, zone glow, agent trails, flow lines
+│           ├── connection/     WebSocket client, state store
+│           ├── audio/          sound effects, notifications
+│           └── ui/             sidebar, panels, overlays, waterfall, activity feed
+```
+
+## Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `Ctrl+K` | Command palette |
+| `?` | Shortcuts help |
+| `F` | Cycle focus between agents |
+| `Esc` | Exit focus mode |
+| `A` | Toggle analytics |
+| `L` | Toggle leaderboard |
+| `T` | Toggle agent trails |
+| `N` | Toggle day/night cycle |
+| `M` | Toggle sound |
+| `E` | Export session |
+| `` ` `` | Toggle minimap |
+| `P` | Cycle theme |
+| `H` | Toggle heatmap |
+
+## API
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /api/health` | Health check |
+| `GET /api/state` | All agent states as JSON |
+| `POST /hook` | Claude Code hook event receiver |
+| `WS /ws` | Real-time agent event stream |
+
+The WebSocket sends a `full_state` snapshot on connect, then incremental events: `agent:spawn`, `agent:update`, `agent:idle`, `agent:shutdown`, `permission:request`, `hooks:status`.
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| Port already in use | `npx agent-move@latest --port 4444` |
+| Hooks not working | `npx agent-move@latest hooks status` to check, then `hooks install` to fix |
+| No agents showing up | Make sure Claude Code is running — agents appear when sessions are active |
+| Build artifacts missing (from source) | Run `npm run build` |
+| Permission denied on port | Use a port above 1024: `--port 3333` |
+| Browser didn't open | Visit `http://localhost:3333` manually, or check `--no-open` flag |
+
+Need more help? [Open an issue](https://github.com/AbdullahSAhmad/agent-move/issues)
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|------------|
+| Renderer | [Pixi.js](https://pixijs.com/) v8 (WebGL) |
+| Server | [Fastify](https://fastify.dev/) + [@fastify/websocket](https://github.com/fastify/fastify-websocket) |
+| File watching | [chokidar](https://github.com/paulmillr/chokidar) v3 |
+| Client build | [Vite](https://vite.dev/) |
+| Language | TypeScript (strict, ES modules) |
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+
+const args = process.argv.slice(2);
+
+// ── Colors (works on all terminals, no dependencies) ────────────────────────
+const c = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+  magenta: '\x1b[35m',
+  blue: '\x1b[34m',
+  white: '\x1b[37m',
+  bgCyan: '\x1b[46m',
+  bgBlue: '\x1b[44m',
+};
+
+// Disable colors if NO_COLOR env or dumb terminal
+const noColor = process.env.NO_COLOR || process.env.TERM === 'dumb';
+if (noColor) Object.keys(c).forEach(k => { c[k] = ''; });
+
+function logo() {
+  console.log();
+  console.log(`${c.cyan}${c.bold}     _                    _   __  __`);
+  console.log(`    / \\   __ _  ___ _ __ | |_|  \\/  | _____   _____`);
+  console.log(`   / _ \\ / _\` |/ _ \\ '_ \\| __| |\\/| |/ _ \\ \\ / / _ \\`);
+  console.log(`  / ___ \\ (_| |  __/ | | | |_| |  | | (_) \\ V /  __/`);
+  console.log(` /_/   \\_\\__, |\\___|_| |_|\\__|_|  |_|\\___/ \\_/ \\___|`);
+  console.log(`         |___/`);
+  console.log(`${c.reset}${c.dim}  Watch your AI agents come alive as pixel-art characters${c.reset}`);
+  console.log();
+}
+
+function status(icon, label, detail) {
+  console.log(`  ${icon}  ${c.bold}${label}${c.reset}  ${c.dim}${detail}${c.reset}`);
+}
+
+function troubleshooting() {
+  console.log();
+  console.log(`${c.dim}  ── Troubleshooting ──────────────────────────────────────${c.reset}`);
+  console.log(`${c.dim}  Port in use?        ${c.reset}npx @foothill/agent-move --port 4444`);
+  console.log(`${c.dim}  Hooks not working?  ${c.reset}npx @foothill/agent-move hooks status`);
+  console.log(`${c.dim}  Reinstall hooks:    ${c.reset}npx @foothill/agent-move hooks install`);
+  console.log(`${c.dim}  Remove hooks:       ${c.reset}npx @foothill/agent-move hooks uninstall`);
+  console.log(`${c.dim}  Report issues:      ${c.reset}https://github.com/FoothillSolutions/agent-move/issues`);
+  console.log();
+}
+
+// ── help ──────────────────────────────────────────────────────────────────────
+if (args.includes('--help') || args.includes('-h')) {
+  logo();
+  console.log(`${c.bold}  Usage:${c.reset}`);
+  console.log(`    ${c.cyan}npx @foothill/agent-move${c.reset}                     Start the visualization server`);
+  console.log(`    ${c.cyan}npx @foothill/agent-move --port 4444${c.reset}         Use a custom port`);
+  console.log(`    ${c.cyan}npx @foothill/agent-move hooks install${c.reset}       Install Claude Code hooks`);
+  console.log(`    ${c.cyan}npx @foothill/agent-move hooks uninstall${c.reset}     Remove Claude Code hooks`);
+  console.log(`    ${c.cyan}npx @foothill/agent-move hooks status${c.reset}        Check hooks installation`);
+  console.log();
+  console.log(`${c.bold}  Options:${c.reset}`);
+  console.log(`    ${c.dim}--port <n>${c.reset}    Server port (default: 3333)`);
+  console.log(`    ${c.dim}--no-open${c.reset}     Don't auto-open the browser`);
+  console.log(`    ${c.dim}--help${c.reset}        Show this help`);
+  console.log();
+  process.exit(0);
+}
+
+// ── hooks subcommand ──────────────────────────────────────────────────────────
+if (args[0] === 'hooks') {
+  const sub = args[1];
+  async function runHooks() {
+    const { installHooks, uninstallHooks, checkHookStatus } =
+      await import('../packages/server/dist/hooks/hook-installer.js');
+
+    if (sub === 'install') {
+      const portIdx = args.indexOf('--port');
+      const port = portIdx !== -1 ? parseInt(args[portIdx + 1], 10) : 3333;
+      const result = installHooks(port);
+      console.log();
+      status(`${c.green}+${c.reset}`, 'Hooks installed', `(${result.scriptPath})`);
+      status(`${c.green}+${c.reset}`, 'Settings updated', `(${result.settingsPath})`);
+      console.log();
+      console.log(`${c.dim}  Hooks will send events to http://localhost:${port}/hook${c.reset}`);
+      console.log(`${c.dim}  Start the server with: ${c.reset}npx @foothill/agent-move`);
+      console.log();
+    } else if (sub === 'uninstall') {
+      const result = uninstallHooks();
+      console.log();
+      status(`${c.yellow}-${c.reset}`, 'Hooks removed', result.message);
+      console.log();
+    } else if (sub === 'status') {
+      const s = checkHookStatus();
+      console.log();
+      if (s.installed) {
+        status(`${c.green}*${c.reset}`, 'Hooks installed', `(${s.events.length} events registered)`);
+        status(s.scriptExists ? `${c.green}*${c.reset}` : `${c.red}!${c.reset}`, 'Hook script', s.scriptExists ? 'exists' : 'MISSING — run `agent-move hooks install`');
+      } else {
+        status(`${c.dim}-${c.reset}`, 'Hooks not installed', '');
+        console.log(`${c.dim}  Run ${c.reset}npx @foothill/agent-move hooks install${c.dim} to enable real-time events.${c.reset}`);
+      }
+      console.log();
+    } else {
+      console.log();
+      console.log(`${c.bold}  Usage:${c.reset} agent-move hooks <install|uninstall|status> [--port <n>]`);
+      console.log();
+    }
+  }
+  runHooks().catch((err) => {
+    console.error(`\n  ${c.red}!${c.reset}  ${err?.message ?? err}\n`);
+    process.exit(1);
+  });
+
+} else {
+  // ── server (default) ────────────────────────────────────────────────────────
+  const preferredPort = (() => {
+    const idx = args.indexOf('--port');
+    if (idx !== -1 && args[idx + 1]) {
+      const p = parseInt(args[idx + 1], 10);
+      if (!Number.isNaN(p) && p > 0 && p < 65536) return p;
+      console.error(`\n  ${c.red}!${c.reset}  Invalid port: ${args[idx + 1]}\n`);
+      process.exit(1);
+    }
+    return 3333;
+  })();
+
+  const skipOpen = args.includes('--no-open');
+
+  process.env.AGENT_MOVE_PORT = String(preferredPort);
+  process.env.__AGENT_MOVE_CLI = '1';
+
+  async function run() {
+    logo();
+
+    // ── Step 1: Auto-install hooks ──────────────────────────────────────────
+    try {
+      const { checkHookStatus, installHooks } =
+        await import('../packages/server/dist/hooks/hook-installer.js');
+      const hookStatus = checkHookStatus();
+      if (!hookStatus.installed) {
+        const result = installHooks(preferredPort);
+        status(`${c.green}+${c.reset}`, 'Hooks', `auto-installed (${result.scriptPath})`);
+      } else if (!hookStatus.scriptExists) {
+        // Hooks registered but script missing — reinstall
+        const result = installHooks(preferredPort);
+        status(`${c.yellow}~${c.reset}`, 'Hooks', `reinstalled (script was missing)`);
+      } else {
+        status(`${c.green}*${c.reset}`, 'Hooks', `ready (${hookStatus.events.length} events)`);
+      }
+    } catch (err) {
+      status(`${c.yellow}!${c.reset}`, 'Hooks', `skipped — ${err?.message ?? 'unknown error'}`);
+      console.log(`${c.dim}    You can install manually: npx @foothill/agent-move hooks install${c.reset}`);
+    }
+
+    // ── Step 2: Start server ────────────────────────────────────────────────
+    const { main } = await import('../packages/server/dist/index.js');
+    const { port } = await main();
+
+    if (port !== preferredPort) {
+      status(`${c.yellow}~${c.reset}`, 'Port', `${preferredPort} was busy, using ${port}`);
+    }
+
+    // ── Step 3: Detect platform ─────────────────────────────────────────────
+    const platforms = { win32: 'Windows', darwin: 'macOS', linux: 'Linux' };
+    const platformName = platforms[process.platform] || process.platform;
+    status(`${c.blue}*${c.reset}`, 'Platform', platformName);
+
+    // ── Step 4: JSONL watch path ────────────────────────────────────────────
+    const os = await import('os');
+    const path = await import('path');
+    const claudeHome = path.join(os.homedir(), '.claude');
+    status(`${c.blue}*${c.reset}`, 'Watching', claudeHome);
+
+    // ── Ready banner ────────────────────────────────────────────────────────
+    const url = `http://localhost:${port}`;
+    console.log();
+    console.log(`  ${c.bgBlue}${c.white}${c.bold}  READY  ${c.reset}  ${c.cyan}${c.bold}${url}${c.reset}`);
+    console.log();
+    console.log(`${c.dim}  Press ${c.reset}Ctrl+C${c.dim} to stop the server${c.reset}`);
+
+    troubleshooting();
+
+    // ── Step 5: Auto-open browser ───────────────────────────────────────────
+    if (!skipOpen) {
+      const { exec } = await import('child_process');
+      let cmd;
+      switch (process.platform) {
+        case 'win32':
+          cmd = `start "" "${url}"`;
+          break;
+        case 'darwin':
+          cmd = `open "${url}"`;
+          break;
+        default:
+          // Linux and others — try xdg-open, fall back to nothing
+          cmd = `xdg-open "${url}" 2>/dev/null || true`;
+          break;
+      }
+      exec(cmd, () => {});
+    }
+  }
+
+  run().catch((err) => {
+    console.error();
+    console.error(`  ${c.red}${c.bold}  FAILED  ${c.reset}  Could not start AgentMove`);
+    console.error();
+
+    const msg = err?.message ?? String(err);
+
+    if (msg.includes('EADDRINUSE')) {
+      console.error(`  ${c.red}!${c.reset}  Port ${preferredPort} is already in use.`);
+      console.error(`${c.dim}    Try: ${c.reset}npx @foothill/agent-move --port ${preferredPort + 1}`);
+    } else if (msg.includes('EACCES')) {
+      console.error(`  ${c.red}!${c.reset}  Permission denied on port ${preferredPort}.`);
+      console.error(`${c.dim}    Try a port above 1024: ${c.reset}npx @foothill/agent-move --port 3333`);
+    } else if (msg.includes('Cannot find module')) {
+      console.error(`  ${c.red}!${c.reset}  Build artifacts missing.`);
+      console.error(`${c.dim}    Run: ${c.reset}npm run build`);
+    } else {
+      console.error(`  ${c.red}!${c.reset}  ${msg}`);
+    }
+
+    console.error();
+    console.error(`${c.dim}  Need help? https://github.com/FoothillSolutions/agent-move/issues${c.reset}`);
+    console.error();
+    process.exit(1);
+  });
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@foothill/agent-move",
+  "version": "1.0.6",
+  "description": "Watch your AI coding agents come alive as pixel-art characters in a 2D world",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/FoothillSolutions/agent-move"
+  },
+  "bin": {
+    "agent-move": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    ".github/screenshot.png",
+    "packages/shared/dist/",
+    "packages/shared/package.json",
+    "packages/server/dist/",
+    "packages/server/package.json",
+    "packages/client/dist/",
+    "packages/client/package.json"
+  ],
+  "workspaces": [
+    "packages/shared",
+    "packages/server",
+    "packages/client"
+  ],
+  "scripts": {
+    "dev": "npm run build -w @agent-move/shared && concurrently -n server,client -c blue,green \"npm run dev -w @agent-move/server\" \"npm run dev -w @agent-move/client\"",
+    "build": "npm run build -w @agent-move/shared && npm run build -w @agent-move/server && npm run build -w @agent-move/client",
+    "typecheck": "tsc -b",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@fastify/cors": "^10.0.2",
+    "@fastify/static": "^8.1.0",
+    "@fastify/websocket": "^11.0.2",
+    "chokidar": "^3.6.0",
+    "fastify": "^5.2.1"
+  },
+  "devDependencies": {
+    "concurrently": "^9.1.2",
+    "esbuild": "^0.27.3",
+    "typescript": "^5.7.3"
+  },
+  "optionalDependencies": {
+    "@rollup/rollup-win32-x64-msvc": "^4.59.0"
+  }
+}