@ammduncan/easel 0.2.0

package/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ammiel Yawson
+
+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,121 @@
+# easel
+
+A live browser tab for every Claude Code session. Agents push HTML — explanations, mockups, diagrams, diffs, comparisons — to a scrolling feed you keep open in split-screen. No more wall-of-text in the terminal.
+
+```
+┌──────────── Claude Code (left) ────────────┐    ┌────── easel (right) ──────────────┐
+│                                            │    │  s/<session-id>  •  3 pushes • live│
+│  > walk me through the new auth flow       │    │  ───────────────────────────────── │
+│                                            │    │  #1  Auth flow overview            │
+│  pushed to display ↗ — #1                  │    │  ┌────────────────────────────────┐│
+│                                            │    │  │  Three actors talk to each…    ││
+│  > what could break?                       │    │  └────────────────────────────────┘│
+│                                            │    │                                    │
+│  pushed to display ↗ — #2                  │    │  #2  Failure modes                 │
+└────────────────────────────────────────────┘    └────────────────────────────────────┘
+```
+
+## Why
+
+Long markdown explanations bury what the agent is actually doing. Visual content (mockups, comparisons, diagrams) is even worse in a TTY. `easel` gives each chat session its own browser tab, and a single MCP tool — `push` — that the agent uses proactively. The terminal stays as a conversation log; the browser carries the substance.
+
+## Install
+
+Requires Node 20+, `git`, and Claude Code.
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/AmmDuncan/easel/main/scripts/install.sh | bash
+```
+
+The installer clones to `~/.local/share/easel` (override with `EASEL_DIR=…`), runs `npm install && npm run build`, then registers the MCP at user scope and adds two `SessionStart` hooks (session-id capture + auto-open tab). Idempotent — safe to re-run to update.
+
+Restart Claude Code afterwards.
+
+### Manual install
+
+```bash
+git clone https://github.com/AmmDuncan/easel.git ~/work/tools/easel
+cd ~/work/tools/easel
+npm install && npm run build
+bin/easel setup
+```
+
+## Tools the agent gets
+
+| Tool | What it does |
+|---|---|
+| `push({ html, title?, kind? })` | Append an HTML card to this session's scrolling feed |
+| `open()` | Force-open a fresh browser tab for the current session |
+| `config({ preset?, theme?, density? })` | Switch palette / mode / layout live across every tab |
+| `label({ label })` | Name the session so it's findable in the switcher |
+
+Agents invoke them as `mcp__easel__push`, `mcp__easel__open`, etc.
+
+## Theming
+
+- **Presets**: `paper` (warm pitstop-style, amber accent — default), `aurora` (deep canvas + violet glow halos), `slate` (cool neutral, cyan accent)
+- **Themes**: light / dark, with sun-moon toggle in the topbar
+- **Density**: `carded` (bordered cards) or `flat` (no chrome, whitespace separates pushes)
+- Three swatches + density toggle live in the topbar; config persists in `~/.easel/config.json` and SSE-broadcasts across all open tabs
+
+## Sessions
+
+- Each Claude Code session gets its own URL: `localhost:7878/s/<session-id>`
+- Session IDs come from Claude Code itself (via the pitstop-style SessionStart hook)
+- Sessions auto-rename to `cwd-basename` by default; you can rename them via the click-to-edit label in the topbar, or the agent can via the `label` tool
+- Idle sessions (>24h since last push) are GC'd every 10 minutes
+- Up to 50 pushes per session; oldest evicted from disk first
+- Per-push delete (trash icon on each card) + per-session delete (hover any row in the switcher or index)
+
+## Tool surface
+
+The MCP exposes one server (`display`) with four tools. HTML is rendered in a sandboxed iframe (`sandbox="allow-scripts"`) with a baseline design system injected — off-white / charcoal, Inter, presentation-scale typography — so plain `<h1>/<h2>/<p>` markup looks right without extra CSS. Authors can also write a full `<!DOCTYPE html>` document and take ownership of styling.
+
+Inside pushed HTML, semantic chips are available out of the box:
+
+```html
+<span class="chip bug">BUG</span>
+<span class="chip ux">UX</span>
+<span class="chip polish">POLISH</span>
+<span class="chip ok">OK</span>
+<span class="chip info">INFO</span>
+<span class="chip accent">FOCUS</span>
+```
+
+Each is themed for both light and dark with a soft outer glow.
+
+## Files
+
+```
+src/
+  mcp.ts              stdio MCP — exposes push / open / config / label (as mcp__easel__*)
+  http-server.ts      express + SSE + static client + sweeper
+  http-entry.ts       process entry for the HTTP server
+  server-manager.ts   lockfile + spawn coordination
+  session-store.ts    disk persistence + retention sweep
+  session-id.ts       3-tier resolver (env / hook file / transcript scan)
+  config-store.ts     preset / theme / density persistence
+  paths.ts            shared constants
+  cli.ts              `easel open|url|setup|config|server|version`
+  client/
+    viewer.html       single-session feed
+    index.html        sessions index page
+    viewer.css        viewer + index styles
+    viewer.js         feed wiring + SSE + theming
+    index.css         index styles + preset/density picker
+    index.js          index page client
+scripts/
+  easel-session-id.mjs  SessionStart hook (Node, zero deps)
+  install.sh            one-shot installer
+  copy-client.mjs       build-time copy of client assets
+bin/
+  easel                 shebang → dist/cli.js
+```
+
+## Author
+
+Built by Claude Code with @ammielyawson, across a series of focused chat sessions. Session-id resolution lifted from [pitstop](https://github.com/AmmDuncan/pitstop) — thanks.
+
+## Licence
+
+MIT.

package/bin/easel

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import("../dist/cli.js");

package/dist/cli.js

@@ -0,0 +1,368 @@
+#!/usr/bin/env node
+import { spawn, spawnSync } from "node:child_process";
+import { copyFileSync, mkdirSync, readFileSync, rmSync, writeFileSync, existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import { ensureHttpServer, readLock } from "./server-manager.js";
+import { resolveClaudeSessionId } from "./session-id.js";
+import { HOOK_DIR, DATA_ROOT } from "./paths.js";
+import { registerSession } from "./session-store.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = resolve(__dirname, "..");
+function help() {
+    console.log(`easel — live browser feed for Claude Code for Claude Code sessions
+
+Usage:
+  easel open            ensure server is running, open this session's tab (or skip if a tab is already alive)
+  easel open --quiet    same but no stdout (for SessionStart hook)
+  easel open --force    always open a new browser tab regardless of presence
+  easel url             print this session's URL
+  easel config                    print current { preset, theme }
+  easel config preset paper       set preset to paper | aurora | slate
+  easel config theme dark         set theme to light | dark
+  easel config preset aurora theme light   set both at once
+  easel setup           install SessionStart hook + register MCP in ~/.claude/settings.json
+  easel update          git pull + npm install + build + setup (re-runs setup to apply new conventions)
+  easel restart         kill the running HTTP server and respawn it (picks up new builds/paths)
+  easel server          run the HTTP server in the foreground (debug)
+  easel version
+`);
+}
+async function cmdOpen(opts) {
+    mkdirSync(HOOK_DIR, { recursive: true });
+    mkdirSync(DATA_ROOT, { recursive: true });
+    const { port } = await ensureHttpServer();
+    const sessionId = resolveClaudeSessionId();
+    registerSession(sessionId);
+    await registerSessionWithServer(port, sessionId);
+    const url = `http://localhost:${port}/s/${sessionId}`;
+    const shouldOpen = opts.force || (await tabsAlive(port)) === 0;
+    if (shouldOpen) {
+        openInBrowser(url);
+        if (!opts.quiet)
+            console.log(url);
+    }
+    else if (!opts.quiet) {
+        console.log(`[easel] tab already open — registered session ${sessionId.slice(0, 8)} silently. Use the topbar switcher to view it, or 'easel open --force' for a new window.`);
+    }
+}
+async function tabsAlive(port) {
+    try {
+        const r = await fetch(`http://127.0.0.1:${port}/api/presence`, {
+            signal: AbortSignal.timeout(800),
+        });
+        if (!r.ok)
+            return 0;
+        const data = (await r.json());
+        return typeof data.tabs === "number" ? data.tabs : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+async function registerSessionWithServer(port, sessionId) {
+    try {
+        await fetch(`http://127.0.0.1:${port}/api/register`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ sessionId, cwd: process.cwd() }),
+            signal: AbortSignal.timeout(1200),
+        });
+    }
+    catch {
+        /* non-fatal — the session is still usable */
+    }
+}
+async function cmdUrl() {
+    const { port } = await ensureHttpServer();
+    const sessionId = resolveClaudeSessionId();
+    console.log(`http://localhost:${port}/s/${sessionId}`);
+}
+function openInBrowser(url) {
+    const platform = process.platform;
+    const cmd = platform === "darwin" ? "open" : platform === "win32" ? "start" : "xdg-open";
+    const args = platform === "win32" ? ["", url] : [url];
+    try {
+        const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+        child.unref();
+    }
+    catch (err) {
+        console.error(`[easel] couldn't open browser: ${err.message}`);
+    }
+}
+function cmdSetup() {
+    mkdirSync(HOOK_DIR, { recursive: true });
+    const settingsPath = join(homedir(), ".claude", "settings.json");
+    const hookScript = resolve(PROJECT_ROOT, "scripts", "easel-session-id.mjs");
+    const mcpEntry = resolve(PROJECT_ROOT, "dist", "mcp.js");
+    const cliEntry = resolve(PROJECT_ROOT, "bin", "easel");
+    if (!existsSync(hookScript)) {
+        console.error(`[easel] hook script missing at ${hookScript}`);
+        process.exitCode = 1;
+        return;
+    }
+    // 1. Register the MCP via the Claude Code CLI (writes ~/.claude.json).
+    //    Falling back to a direct edit if the CLI isn't on PATH.
+    registerMcp(mcpEntry);
+    // 1b. Install the `using-easel` skill so agents discover when/how to push.
+    installSkill();
+    // 2. Add SessionStart hooks to ~/.claude/settings.json (hooks DO belong here).
+    const settings = existsSync(settingsPath)
+        ? JSON.parse(readFileSync(settingsPath, "utf-8"))
+        : {};
+    // Drop any prior mcpServers.display entry — it lives in ~/.claude.json now.
+    if (settings.mcpServers && typeof settings.mcpServers === "object") {
+        delete settings.mcpServers["display"];
+    }
+    const hooks = settings.hooks ?? {};
+    let sessionStart = hooks.SessionStart ?? [];
+    // Drop legacy entries from prior versions (the old bash hook, paths under the
+    // claude-display name) before re-adding the current Node-based hook.
+    const isLegacy = (block) => {
+        const inner = block?.hooks ?? [block];
+        if (!Array.isArray(inner))
+            return false;
+        return inner.some((h) => {
+            const cmd = h?.command;
+            if (typeof cmd !== "string")
+                return false;
+            return (cmd.includes("claude-display-session-id.sh") ||
+                cmd.includes("easel-session-id.sh") ||
+                cmd.includes("bin/claude-display "));
+        });
+    };
+    sessionStart = sessionStart.filter((b) => !isLegacy(b));
+    const idCaptureBlock = {
+        hooks: [{ type: "command", command: `node ${hookScript}` }],
+    };
+    const autoOpenBlock = {
+        hooks: [{ type: "command", command: `${cliEntry} open --quiet` }],
+    };
+    const containsBlockMatching = (substr) => sessionStart.some((block) => {
+        const inner = block?.hooks ?? [block];
+        return (Array.isArray(inner) ? inner : []).some((h) => typeof h === "object" &&
+            h !== null &&
+            typeof h.command === "string" &&
+            (h.command).includes(substr));
+    });
+    if (!containsBlockMatching("easel-session-id.mjs")) {
+        sessionStart.push(idCaptureBlock);
+    }
+    if (!containsBlockMatching("easel") || !containsBlockMatching("open --quiet")) {
+        sessionStart.push(autoOpenBlock);
+    }
+    hooks.SessionStart = sessionStart;
+    settings.hooks = hooks;
+    mkdirSync(dirname(settingsPath), { recursive: true });
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+    console.log(`[easel] setup complete`);
+    console.log(`  - MCP registered at user scope (\`claude mcp list\` to verify)`);
+    console.log(`  - SessionStart hooks added to ${settingsPath}`);
+    console.log(`Restart Claude Code (fully quit + relaunch) to activate.`);
+}
+function installSkill() {
+    const src = resolve(PROJECT_ROOT, "skills", "using-easel", "SKILL.md");
+    if (!existsSync(src)) {
+        console.warn(`[easel] skill source missing at ${src} — skipping skill install`);
+        return;
+    }
+    const destDir = join(homedir(), ".claude", "skills", "using-easel");
+    const dest = join(destDir, "SKILL.md");
+    mkdirSync(destDir, { recursive: true });
+    copyFileSync(src, dest);
+    // Remove the legacy skill from prior versions if it exists.
+    const legacy = join(homedir(), ".claude", "skills", "using-display");
+    if (existsSync(legacy)) {
+        try {
+            rmSync(legacy, { recursive: true, force: true });
+        }
+        catch {
+            /* swallow */
+        }
+    }
+    console.log(`  - using-easel skill installed to ${dest}`);
+}
+function registerMcp(mcpEntry) {
+    // Try `claude mcp add` first — that's the supported path and writes to ~/.claude.json.
+    // Re-add idempotently by removing first (CLI errors if the name already exists).
+    const trySpawn = (args) => {
+        try {
+            const r = spawnSync("claude", args, {
+                encoding: "utf-8",
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+            return r.status === 0;
+        }
+        catch {
+            return false;
+        }
+    };
+    // Drop any old registrations from prior versions.
+    trySpawn(["mcp", "remove", "display", "--scope", "user"]);
+    trySpawn(["mcp", "remove", "easel", "--scope", "user"]);
+    const added = trySpawn([
+        "mcp",
+        "add",
+        "--scope",
+        "user",
+        "easel",
+        "node",
+        mcpEntry,
+    ]);
+    if (added)
+        return;
+    // Fallback: patch ~/.claude.json directly.
+    const userConfigPath = join(homedir(), ".claude.json");
+    const config = existsSync(userConfigPath)
+        ? JSON.parse(readFileSync(userConfigPath, "utf-8"))
+        : {};
+    const mcpServers = config.mcpServers ?? {};
+    delete mcpServers["display"];
+    mcpServers["easel"] = {
+        type: "stdio",
+        command: "node",
+        args: [mcpEntry],
+    };
+    config.mcpServers = mcpServers;
+    writeFileSync(userConfigPath, JSON.stringify(config, null, 2));
+}
+async function cmdConfig(args) {
+    const { port } = await ensureHttpServer();
+    if (args.length === 0) {
+        const r = await fetch(`http://127.0.0.1:${port}/api/config`);
+        const data = (await r.json());
+        console.log(JSON.stringify(data.config, null, 2));
+        return;
+    }
+    const body = {};
+    for (let i = 0; i < args.length; i += 2) {
+        const key = args[i];
+        const val = args[i + 1];
+        if (!key || !val)
+            continue;
+        if (key === "preset" || key === "theme" || key === "density")
+            body[key] = val;
+    }
+    if (Object.keys(body).length === 0) {
+        console.error("usage: easel config [preset paper|aurora|slate] [theme light|dark] [density carded|flat]");
+        process.exitCode = 1;
+        return;
+    }
+    const r = await fetch(`http://127.0.0.1:${port}/api/config`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    const data = (await r.json());
+    console.log(JSON.stringify(data.config, null, 2));
+}
+function cmdUpdate() {
+    console.log("[easel] checking for updates…");
+    const run = (cmd, args) => spawnSync(cmd, args, { stdio: "inherit", cwd: PROJECT_ROOT });
+    let r = run("git", ["fetch", "--quiet", "origin", "main"]);
+    if (r.status !== 0) {
+        console.error("[easel] git fetch failed");
+        process.exitCode = 1;
+        return;
+    }
+    r = run("git", ["pull", "--ff-only", "--quiet", "origin", "main"]);
+    if (r.status !== 0) {
+        console.error("[easel] git pull failed (local changes? merge conflict?)");
+        process.exitCode = 1;
+        return;
+    }
+    r = run("npm", ["install", "--silent", "--no-audit", "--no-fund"]);
+    if (r.status !== 0) {
+        console.error("[easel] npm install failed");
+        process.exitCode = 1;
+        return;
+    }
+    r = run("npm", ["run", "build", "--silent"]);
+    if (r.status !== 0) {
+        console.error("[easel] build failed");
+        process.exitCode = 1;
+        return;
+    }
+    // Re-run setup so any new hook/skill conventions take effect.
+    cmdSetup();
+    console.log("[easel] updated. Restart Claude Code to pick up tool/skill changes.");
+}
+async function cmdRestart() {
+    const lock = readLock();
+    if (lock?.pid) {
+        try {
+            process.kill(lock.pid, "SIGTERM");
+        }
+        catch {
+            // process is already dead — fine
+        }
+        // give the OS a moment to release the port + clean up
+        await new Promise((r) => setTimeout(r, 300));
+    }
+    try {
+        rmSync(join(DATA_ROOT, "server.lock"));
+    }
+    catch {
+        // no lockfile to remove — fine
+    }
+    const { port } = await ensureHttpServer();
+    console.log(`easel server restarted on port ${port}`);
+}
+async function cmdServer() {
+    const { startHttpServer } = await import("./http-server.js");
+    startHttpServer();
+    process.stdin.resume();
+}
+function cmdVersion() {
+    const pkg = JSON.parse(readFileSync(resolve(PROJECT_ROOT, "package.json"), "utf-8"));
+    console.log(pkg.version);
+}
+async function main() {
+    const [, , cmd, ...rest] = process.argv;
+    switch (cmd) {
+        case "open":
+            await cmdOpen({
+                quiet: rest.includes("--quiet"),
+                force: rest.includes("--force"),
+            });
+            return;
+        case "url":
+            await cmdUrl();
+            return;
+        case "setup":
+            cmdSetup();
+            return;
+        case "server":
+            await cmdServer();
+            return;
+        case "config":
+            await cmdConfig(rest);
+            return;
+        case "update":
+            cmdUpdate();
+            return;
+        case "restart":
+            await cmdRestart();
+            return;
+        case "version":
+        case "--version":
+        case "-v":
+            cmdVersion();
+            return;
+        case undefined:
+        case "help":
+        case "--help":
+        case "-h":
+            help();
+            return;
+        default:
+            console.error(`unknown command: ${cmd}`);
+            help();
+            process.exitCode = 1;
+    }
+}
+main().catch((err) => {
+    console.error("[easel cli] fatal:", err);
+    process.exit(1);
+});