chat-glass 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lindow Consulting Ltd
+
+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,71 @@
+# chat-glass
+
+Visual thinking companion for Claude Code.
+
+chat-glass gives Claude Code the ability to create rich, interactive visualizations -- diagrams, charts, comparisons, flowcharts -- and display them in a live-reloading browser viewer.
+
+## What it does
+
+When Claude Code needs to explain something visually, it delegates to the chat-glass agent. The agent writes a self-contained HTML file, and chat-glass serves it in a browser viewer with a gallery of past visualizations. Everything updates in real time via WebSocket.
+
+## Quick start
+
+```bash
+npm install -g chat-glass
+chat-glass install-agent
+```
+
+That's it. The agent is now available in Claude Code. When a visual explanation would help, Claude will automatically use it.
+
+To install the agent for only the current project:
+
+```bash
+chat-glass install-agent --local
+```
+
+## How it works
+
+1. Claude Code decides a visual would help and delegates to the chat-glass subagent
+2. The subagent writes a self-contained HTML file to `.chat-glass/pages/`
+3. The subagent runs `chat-glass show`, which starts a local server (or reloads an existing one)
+4. The browser viewer updates in real time via WebSocket
+5. A gallery strip lets you browse all past visualizations
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `chat-glass show` | Open the visualization viewer (starts server if needed) |
+| `chat-glass list` | List saved visualizations |
+| `chat-glass clean` | Delete all saved pages |
+| `chat-glass install-agent` | Install the chat-glass agent file globally |
+| `chat-glass install-agent --local` | Install the agent for the current project only |
+| `chat-glass --help` | Show help |
+
+## Configuration
+
+chat-glass stores data in a `.chat-glass/` directory in your project root:
+
+```
+.chat-glass/
+  config.json    # Server state (port, pid, timestamps)
+  pages/         # Generated HTML visualizations
+    latest.html  # Symlink to most recent page
+```
+
+The server listens on `127.0.0.1` on a port in the range 3737-3747 and shuts down automatically after 30 minutes of inactivity.
+
+## For contributors
+
+```bash
+git clone https://github.com/tfLConsulting/chat-glass.git
+cd chat-glass
+npm install
+npm test
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.
+
+## License
+
+[MIT](LICENSE)

package/agent/chat-glass.md

@@ -0,0 +1,109 @@
+---
+name: chat-glass
+description: >
+  Use this agent whenever a visual explanation would be clearer than text.
+  Comparisons, architectures, flows, data, relationships, tradeoffs,
+  layouts, timelines, hierarchies — any time showing is better than telling.
+  Be proactive: if something would benefit from a visual, use this without
+  being asked.
+tools: Write, Bash
+---
+
+You are a visualization agent. You receive a plain-English description of something to visualize and produce a single self-contained HTML file.
+
+## Output rules
+
+1. Generate exactly one HTML file — inline all CSS and JS, no external stylesheets or scripts except CDN libraries.
+2. Write the file to `.chat-glass/pages/{timestamp}.html` where timestamp is the current time formatted as `YYYY-MM-DDTHH-mm-ss` (filesystem-safe ISO). Create the directory if it does not exist.
+3. Run `chat-glass show` via Bash to open/reload the viewer.
+4. Return a single sentence describing what you visualized. Nothing more.
+5. **Never** return HTML, SVG, or code in your response to the main agent.
+6. If `chat-glass show` outputs a screenshot path, include it in your response
+   as: "Screenshot: /path/to/screenshot.png" — this lets the calling context
+   see what was rendered.
+
+## HTML file requirements
+
+- Must be fully self-contained and renderable by opening the file directly
+- Must include a descriptive `<title>` tag (the gallery uses this)
+- Target viewport: approximately 1200 x 800 pixels
+- No scrolling required — content should fit in view
+
+## CDN libraries you may use
+
+Pick whichever fits the visualization best:
+
+- **Tailwind CSS** — utility styling via `<script src="https://cdn.tailwindcss.com"></script>`
+- **Mermaid** — diagrams, flowcharts, sequence diagrams, gantt charts
+- **D3.js** — custom data visualizations, force graphs, trees
+- **Chart.js** — bar, line, pie, radar, and other standard charts
+- **Prism / Highlight.js** — syntax-highlighted code blocks
+- **KaTeX** — mathematical notation
+- **Three.js** — 3D visualizations
+- Any other CDN library that fits the task
+
+## Style guide
+
+### Theme
+
+- Background: `#1a1a2e` (deep blue-black)
+- Text: `#e0e0e0`
+- Accent palette — rotate through these: `#00d4ff`, `#ff6b6b`, `#4ecdc4`, `#ffe66d`, `#a29bfe`
+
+### Typography
+
+- Body: system font stack (`-apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif`)
+- Headings/labels that need character: pull a single Google Font via CDN — vary it per visualization
+- Monospace: `'SF Mono', 'Fira Code', 'Cascadia Code', monospace`
+
+### Layout principles
+
+- Generous whitespace — let the content breathe
+- Content centered with max-width ~1000px
+- Use CSS grid/flexbox for layout
+- No scrolling if possible — fit the viewport
+- No unnecessary chrome or decoration
+
+### Diagram style
+
+- Prefer organic SVG feel over rigid boxes
+- Rounded corners, subtle shadows, curved connecting lines
+- Use color to encode meaning, not decoration
+
+### Comparison style
+
+- Side-by-side cards with clear headers and key points
+- Color-coded borders for pros/cons or categories
+- Highlight differences with accent colors
+
+### Flow / process style
+
+- Nodes as rounded rectangles
+- Edges as curved SVG paths with arrowheads
+- Subtle load animation if it aids understanding
+
+### Data visualization style
+
+- Clean axes, minimal gridlines
+- Direct labels preferred over legends
+- Accent colors for data series
+- No chartjunk — every pixel should inform
+
+## Timestamp generation
+
+Use this Bash one-liner to generate the filename timestamp:
+```bash
+date +%Y-%m-%dT%H-%M-%S
+```
+
+Or in JavaScript:
+```javascript
+new Date().toISOString().replace(/:/g, '-').replace(/\..+/, '')
+```
+
+## Example workflow
+
+1. Receive: "Show the request lifecycle through our middleware stack"
+2. Write: `.chat-glass/pages/2025-06-15T14-30-22.html` containing a styled flowchart
+3. Run: `chat-glass show` — output includes the server URL and optionally a screenshot path
+4. Reply: "Created a flowchart showing the request lifecycle through the middleware stack. Screenshot: /path/to/project/.chat-glass/pages/screenshot-1718459422000.png"

package/bin/cli.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+
+import show from "../src/commands/show.js";
+import installAgent from "../src/commands/install-agent.js";
+import list from "../src/commands/list.js";
+import clean from "../src/commands/clean.js";
+
+const commands = {
+  show,
+  "install-agent": installAgent,
+  list,
+  clean,
+};
+
+function printUsage() {
+  console.log(`chat-glass — Visual thinking companion for Claude Code
+
+Usage: chat-glass <command>
+
+Commands:
+  show            Open the visualization viewer
+  install-agent   Install the chat-glass agent file
+  list            List saved visualizations
+  clean           Delete all saved pages
+
+Options:
+  --help          Show this help message`);
+}
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (!command || command === "--help" || command === "-h") {
+  printUsage();
+  process.exit(0);
+}
+
+const handler = commands[command];
+
+if (!handler) {
+  console.error(`Unknown command: ${command}\n`);
+  printUsage();
+  process.exit(1);
+}
+
+try {
+  await handler(args.slice(1));
+} catch (err) {
+  console.error(`Error: ${err.message}`);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "chat-glass",
+  "version": "1.0.0",
+  "description": "Visual thinking companion for Claude Code",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "chat-glass": "./bin/cli.js"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "dev": "node bin/cli.js install-agent --local --dev"
+  },
+  "files": [
+    "src",
+    "bin",
+    "agent"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tfLConsulting/chat-glass.git"
+  },
+  "homepage": "https://github.com/tfLConsulting/chat-glass",
+  "bugs": {
+    "url": "https://github.com/tfLConsulting/chat-glass/issues"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "visualization",
+    "ai",
+    "developer-tools"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.0.18",
+    "vitest": "^4.0.18"
+  },
+  "dependencies": {
+    "open": "^11.0.0",
+    "puppeteer-core": "^24.0.0",
+    "ws": "^8.19.0"
+  }
+}

package/src/commands/clean.js

@@ -0,0 +1,33 @@
+import { readdir, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { pagesDir, getProjectDir } from "../utils/paths.js";
+
+export default async function clean() {
+  const dir = pagesDir(getProjectDir());
+  let files;
+  try {
+    files = await readdir(dir);
+  } catch {
+    console.log("No pages directory found.");
+    return;
+  }
+
+  const targets = files.filter((f) => f.endsWith(".html"));
+
+  if (targets.length === 0) {
+    console.log("No pages to clean.");
+    return;
+  }
+
+  let removed = 0;
+  for (const filename of targets) {
+    try {
+      await unlink(join(dir, filename));
+      removed++;
+    } catch {
+      // skip files that can't be removed
+    }
+  }
+
+  console.log(`Removed ${removed} page(s).`);
+}

package/src/commands/install-agent.js

@@ -0,0 +1,64 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PACKAGE_ROOT = resolve(__dirname, "..", "..");
+const AGENT_SOURCE = join(PACKAGE_ROOT, "agent", "chat-glass.md");
+const CLI_PATH = join(PACKAGE_ROOT, "bin", "cli.js");
+
+export default async function installAgent(args = []) {
+  const isLocal = args.includes("--local");
+  const isDev = args.includes("--dev");
+
+  const destDir = isLocal
+    ? join(process.cwd(), ".claude", "agents")
+    : join(homedir(), ".claude", "agents");
+
+  const destPath = join(destDir, "chat-glass.md");
+
+  // Read source agent file
+  let source;
+  try {
+    source = await readFile(AGENT_SOURCE, "utf8");
+  } catch {
+    console.error("Could not read agent file from package. Is chat-glass installed correctly?");
+    process.exit(1);
+  }
+
+  // Dev mode: rewrite `chat-glass` commands to use the local checkout
+  if (isDev) {
+    const localCmd = `node ${CLI_PATH}`;
+    source = source.replace(/`chat-glass show`/g, `\`${localCmd} show\``);
+    source = source.replace(/`chat-glass /g, `\`${localCmd} `);
+    source = source.replace(
+      /Run: `node .* show`/,
+      `Run: \`${localCmd} show\``
+    );
+  }
+
+  // Check if destination already exists and is identical
+  try {
+    const existing = await readFile(destPath, "utf8");
+    if (existing === source) {
+      console.log("Agent already up to date.");
+      return;
+    }
+  } catch {
+    // File doesn't exist yet — that's fine
+  }
+
+  // Write agent file
+  await mkdir(destDir, { recursive: true });
+  await writeFile(destPath, source, "utf8");
+
+  if (isDev) {
+    console.log(`Agent installed (dev mode) — commands point to ${CLI_PATH}`);
+  } else if (isLocal) {
+    console.log("Agent installed to .claude/agents/chat-glass.md — available in this project");
+  } else {
+    console.log("Agent installed to ~/.claude/agents/chat-glass.md — available in all projects");
+  }
+}

package/src/commands/list.js

@@ -0,0 +1,42 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { pagesDir, getProjectDir } from "../utils/paths.js";
+
+function extractTitle(html) {
+  const match = html.match(/<title>(.*?)<\/title>/i);
+  return match ? match[1] : null;
+}
+
+export default async function list() {
+  const dir = pagesDir(getProjectDir());
+  let files;
+  try {
+    files = await readdir(dir);
+  } catch {
+    console.log("No pages directory found.");
+    return;
+  }
+
+  const htmlFiles = files
+    .filter((f) => f.endsWith(".html") && f !== "latest.html")
+    .sort((a, b) => b.localeCompare(a));
+
+  if (htmlFiles.length === 0) {
+    console.log("No pages found.");
+    return;
+  }
+
+  for (const filename of htmlFiles) {
+    let title = null;
+    try {
+      const content = await readFile(join(dir, filename), "utf8");
+      title = extractTitle(content);
+    } catch {
+      // skip unreadable files
+    }
+    const display = title ? `${filename}  ${title}` : filename;
+    console.log(display);
+  }
+
+  console.log(`\n${htmlFiles.length} page(s)`);
+}

package/src/commands/show.js

@@ -0,0 +1,215 @@
+import { spawn } from "node:child_process";
+import { readdir, symlink, unlink } from "node:fs/promises";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readConfig, ensureDirs, writeConfig } from "../utils/config.js";
+import { pagesDir, latestPath, getProjectDir } from "../utils/paths.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const SERVER_ENTRY = resolve(__dirname, "..", "server", "start.js");
+
+const HEALTH_CHECK_TIMEOUT_MS = 2000;
+const SERVER_START_TIMEOUT_MS = 5000;
+const READY_POLL_INTERVAL_MS = 200;
+const READY_MAX_ATTEMPTS = 15;
+
+async function isServerAlive(port) {
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), HEALTH_CHECK_TIMEOUT_MS);
+    const res = await fetch(`http://127.0.0.1:${port}/health`, {
+      signal: controller.signal,
+    });
+    clearTimeout(timeout);
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function updateLatestSymlink(projectDir) {
+  const dir = pagesDir(projectDir);
+  let files;
+  try {
+    files = await readdir(dir);
+  } catch {
+    return;
+  }
+
+  const htmlFiles = files
+    .filter((f) => f.endsWith(".html") && f !== "latest.html")
+    .sort();
+
+  if (htmlFiles.length === 0) return;
+
+  const newest = htmlFiles[htmlFiles.length - 1];
+  const linkPath = latestPath(projectDir);
+
+  // Remove existing symlink/file
+  try {
+    await unlink(linkPath);
+  } catch {
+    // doesn't exist yet
+  }
+
+  await symlink(newest, linkPath);
+}
+
+async function spawnServer(projectDir) {
+  const child = spawn(process.execPath, [SERVER_ENTRY, projectDir], {
+    detached: true,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+
+  // Read the port from stdout
+  let stdout = "";
+  let stderr = "";
+
+  // Wait for the server to write its port, or fail
+  const port = await new Promise((resolvePort, reject) => {
+    const timeout = setTimeout(() => {
+      reject(new Error("Server failed to start within 5 seconds"));
+    }, SERVER_START_TIMEOUT_MS);
+
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
+      const parsed = parseInt(stdout.trim(), 10);
+      if (parsed > 0) {
+        clearTimeout(timeout);
+        resolvePort(parsed);
+      }
+    });
+
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+
+    child.on("error", (err) => {
+      clearTimeout(timeout);
+      reject(err);
+    });
+
+    child.on("exit", (code) => {
+      if (code !== null && code !== 0) {
+        clearTimeout(timeout);
+        reject(new Error(stderr.trim() || `Server exited with code ${code}`));
+      }
+    });
+  });
+
+  // Detach — let the server run independently
+  child.unref();
+  child.stdout.destroy();
+  child.stderr.destroy();
+
+  return port;
+}
+
+async function waitForReady(port, maxAttempts = READY_MAX_ATTEMPTS) {
+  for (let i = 0; i < maxAttempts; i++) {
+    if (await isServerAlive(port)) return true;
+    await new Promise((r) => setTimeout(r, READY_POLL_INTERVAL_MS));
+  }
+  return false;
+}
+
+export async function show(projectDir, { openBrowser = true } = {}) {
+  // 1. Ensure directories exist
+  await ensureDirs(projectDir);
+
+  // 2. Update latest.html symlink
+  await updateLatestSymlink(projectDir);
+
+  // 3. Check if server is already running
+  const config = await readConfig(projectDir);
+  let port = config.port;
+  let isNew = false;
+
+  let alive = false;
+  if (port && config.pid) {
+    // Check if the process is still alive and responding
+    if (isProcessAlive(config.pid)) {
+      alive = await isServerAlive(port);
+    }
+    // Stale config — process is dead
+    if (!alive) {
+      port = null;
+    }
+  }
+
+  if (!alive) {
+    // 4. Start server as background process
+    port = await spawnServer(projectDir);
+
+    // 5. Wait for server to be ready
+    const ready = await waitForReady(port);
+    if (!ready) {
+      throw new Error("Server started but failed to respond");
+    }
+
+    isNew = true;
+  }
+
+  // 6. Open browser on first start
+  if (isNew && openBrowser) {
+    try {
+      const open = (await import("open")).default;
+      await open(`http://localhost:${port}`);
+    } catch {
+      // Non-fatal — headless environments may not have a browser
+    }
+
+    // Track that browser was opened
+    const currentConfig = await readConfig(projectDir);
+    await writeConfig(projectDir, { ...currentConfig, browserOpened: true });
+  }
+
+  // 7. Ping reload
+  try {
+    await fetch(`http://127.0.0.1:${port}/reload`);
+  } catch {
+    // Non-fatal
+  }
+
+  // 8. Attempt screenshot capture
+  let screenshot = null;
+  try {
+    const { captureScreenshot } = await import("../utils/screenshot.js");
+    const outputFile = resolve(pagesDir(projectDir), `screenshot-${Date.now()}.png`);
+    screenshot = await captureScreenshot(port, outputFile);
+  } catch {
+    // Non-fatal — screenshot is a bonus
+  }
+
+  return { port, isNew, screenshot };
+}
+
+export default async function showCommand() {
+  try {
+    const projectDir = getProjectDir();
+    const { port, screenshot } = await show(projectDir);
+    console.log(`chat-glass running on http://localhost:${port}`);
+    if (screenshot) {
+      console.log(`screenshot: ${screenshot}`);
+    }
+  } catch (err) {
+    if (err.message.includes("No free port")) {
+      console.error(
+        "All ports 3737-3747 in use. Close some chat-glass instances."
+      );
+    } else {
+      console.error(`Failed to start server: ${err.message}`);
+    }
+    process.exit(1);
+  }
+}

package/src/index.js

@@ -0,0 +1,4 @@
+export { startServer } from "./server/index.js";
+export { findFreePort } from "./utils/port.js";
+export { readConfig, writeConfig, ensureDirs } from "./utils/config.js";
+export { pagesDir, configPath, latestPath, getProjectDir } from "./utils/paths.js";