excaliagent 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Martin Popovski
+
+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,3 +1,91 @@
-# Temporary Holding Version
+# excaliagent
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A spatial scratchboard for your Claude Code sessions, on an Excalidraw canvas.
+
+Every session is a card. You drag cards wherever they make sense to you (parked,
+blocked on a colleague, come back to, done) and draw anything around them. The
+app keeps each card's **color and label** in sync with the session and never
+moves, resizes, or edits anything else.
+
+```
+Fix flaky checkout test           ← title (handwritten, larger)
+demo-app · fix/flaky              ← repo · branch
+needs user: input needed · 2m     ← status · what it waits for · last activity
+cache warm 41m                    ← prompt-cache warmth
+herdr: demo-app › oauth           ← herdr workspace › tab
+PR #12                            ← last PR link
+```
+
+| Color | Meaning |
+|---|---|
+| red | needs you (input, permission, trust, blocked) |
+| blue | busy |
+| green | idle, prompt cache still warm: review it before it goes cold |
+| grey | idle, cache cold |
+| dashed, pale | dormant (not running) |
+
+## Run
+
+```sh
+npx excaliagent
+```
+
+It starts a server on `127.0.0.1` and opens the board in your browser.
+
+- **Live sessions** appear in the *inbox* rectangle by themselves.
+- **Dormant sessions** are added from the **Sessions** panel (top right).
+- **Double-click a card** to jump to it: a live session focuses its
+  [herdr](https://herdr.dev) pane and raises the terminal window (Hyprland,
+  Sway). A dormant session is resumed with `claude --resume` in a new herdr
+  tab, in the workspace for that repo. Without herdr, the resume command is
+  copied instead.
+- **Right-click a card** for an excaliagent section on top of the Excalidraw
+  menu: focus or resume, copy the resume command (with or without `cd`), open
+  the PR.
+- A **PR link** (GitHub, Bitbucket, GitLab) shows on the card; the card's link
+  icon opens it.
+- The board is saved to `$XDG_STATE_HOME/excaliagent/scene.json`
+  (default `~/.local/state/excaliagent/`).
+
+Options: `--port`, `--no-open`, `--state-dir`, `--claude-dir`, `--no-herdr`, `--no-raise`.
+See `npx excaliagent --help`.
+
+## Privacy and security
+
+- Reads `~/.claude/sessions/*.json` and the transcript files under
+  `~/.claude/projects/` (only metadata lines: title, branch, timestamps, token
+  usage, PR links; never message content). Installs no hooks, writes nothing
+  outside its state directory.
+- Listens on loopback only. A random token is put into the URL it opens and
+  exchanged for an HttpOnly cookie; every request needs it. Requests with a
+  foreign `Host` (DNS rebinding) or cross-origin writes are refused.
+- Its only actions: focus a herdr pane, raise the terminal window, and start
+  `claude --resume <id>` in a new herdr pane. It never types into a running
+  session.
+
+## herdr (optional)
+
+If [herdr](https://herdr.dev) is running, cards are linked to panes by matching
+the session's process id to the pane's foreground process. No herdr
+integration or plugin is needed. Tested with herdr 0.9.0 and its protocol 22.
+
+## Development
+
+The repo ships a Nix flake with Node 24 and Chromium for the browser tests:
+
+```sh
+direnv allow        # or: nix develop
+npm install
+npm test            # unit tests (vitest)
+npm run test:e2e    # browser tests (playwright) against a mock Claude home
+npm run demo        # the board with a seeded, synthetic set of sessions
+npm run dev         # server + Vite hot reload against your real ~/.claude
+```
+
+Tests never read your real `~/.claude` or talk to your running herdr:
+`test/mock-claude.ts` seeds a throwaway Claude home with dummy processes, and the
+herdr tests start an isolated `herdr server` with its own temp home and socket.
+A privacy test fails if any fixture contains this machine's home path or user
+name.
+
+Docs: [product](docs/product.md), [design](docs/design.md), [roadmap](docs/roadmap.md). Agents start at [AGENTS.md](AGENTS.md).

package/bin/excaliagent.js

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

package/dist/server/args.js

@@ -0,0 +1,51 @@
+import { parseArgs } from "node:util";
+export const USAGE = `Usage: excaliagent [options]
+
+A spatial Excalidraw board for your Claude Code sessions.
+
+Options:
+  --port <n>          Port on 127.0.0.1 (default: random free port)
+  --no-open           Do not open the browser, just print the URL
+  --state-dir <dir>   Where scene.json lives (default: $XDG_STATE_HOME/excaliagent)
+  --claude-dir <dir>  Claude Code home (default: ~/.claude)
+  --no-herdr          Do not link sessions to herdr panes
+  --no-raise          Focus the herdr pane but do not raise its terminal window
+  --dev               Serve the frontend through Vite with hot reload
+  -h, --help          Show this help
+  -v, --version       Show the version
+`;
+export function parseCliArgs(argv) {
+    const { values } = parseArgs({
+        args: argv,
+        strict: true,
+        allowNegative: true,
+        options: {
+            port: { type: "string" },
+            open: { type: "boolean", default: true },
+            dev: { type: "boolean", default: false },
+            herdr: { type: "boolean", default: true },
+            raise: { type: "boolean", default: true },
+            "state-dir": { type: "string" },
+            "claude-dir": { type: "string" },
+            help: { type: "boolean", short: "h", default: false },
+            version: { type: "boolean", short: "v", default: false },
+        },
+    });
+    let port = 0;
+    if (values.port !== undefined) {
+        port = Number(values.port);
+        if (!Number.isInteger(port) || port < 0 || port > 65535)
+            throw new Error(`invalid --port: ${values.port}`);
+    }
+    return {
+        port,
+        open: values.open,
+        dev: values.dev,
+        herdr: values.herdr,
+        raise: values.raise,
+        stateDir: values["state-dir"],
+        claudeDir: values["claude-dir"],
+        help: values.help,
+        version: values.version,
+    };
+}

package/dist/server/cli.js

@@ -0,0 +1,99 @@
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseCliArgs, USAGE } from "./args.js";
+import { createHub } from "./hub.js";
+import { createAppServer } from "./http.js";
+import { createDesktop } from "./desktop/desktop.js";
+import { createHerdrLink, createNoPaneLink } from "./panes/herdr.js";
+import { createSceneStore, defaultStateDir } from "./scene-store.js";
+import { createClaudeSource } from "./sources/claude.js";
+const here = dirname(fileURLToPath(import.meta.url));
+// src/server or dist/server → package root
+const root = join(here, "..", "..");
+function openBrowser(url) {
+    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    try {
+        const child = spawn(cmd, args, { detached: true, stdio: "ignore" });
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        // printing the URL is enough
+    }
+}
+async function main(args) {
+    const token = randomBytes(24).toString("base64url");
+    const source = createClaudeSource({ claudeDir: args.claudeDir });
+    const panes = args.herdr
+        ? createHerdrLink({ desktop: args.raise ? createDesktop({ env: process.env }) : undefined })
+        : createNoPaneLink();
+    const hub = createHub({ source, panes });
+    await hub.start();
+    const scenes = createSceneStore(args.stateDir ?? defaultStateDir());
+    let middleware;
+    let closeVite = async () => { };
+    const server = createAppServer({
+        hub,
+        scenes,
+        token,
+        webRoot: join(root, "dist", "web"),
+        get middleware() {
+            return middleware;
+        },
+    });
+    if (args.dev) {
+        const { createServer } = await import("vite");
+        const vite = await createServer({
+            configFile: join(root, "vite.config.ts"),
+            server: { middlewareMode: true, hmr: { server: server.server } },
+            appType: "spa",
+        });
+        middleware = vite.middlewares;
+        closeVite = () => vite.close();
+    }
+    await server.listen(args.port);
+    const url = `http://127.0.0.1:${server.port}/?token=${token}`;
+    console.log(`excaliagent ${args.dev ? "(dev) " : ""}listening on http://127.0.0.1:${server.port}`);
+    console.log(`scene: ${scenes.path}`);
+    console.log(`herdr: ${panes.available() ? "connected" : args.herdr ? "not running (will retry)" : "disabled"}`);
+    console.log(`open: ${url}`);
+    if (args.open)
+        openBrowser(url);
+    let stopping = false;
+    const stop = async () => {
+        if (stopping)
+            process.exit(1);
+        stopping = true;
+        hub.stop();
+        panes.close();
+        await closeVite();
+        await server.close();
+        process.exit(0);
+    };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+}
+let args;
+try {
+    args = parseCliArgs(process.argv.slice(2));
+}
+catch (err) {
+    console.error(`excaliagent: ${err.message}\n\n${USAGE}`);
+    process.exit(2);
+}
+if (args.help) {
+    console.log(USAGE);
+}
+else if (args.version) {
+    console.log(JSON.parse(readFileSync(join(root, "package.json"), "utf8")).version);
+}
+else {
+    main(args).catch((err) => {
+        console.error("excaliagent:", err);
+        process.exit(1);
+    });
+}

package/dist/server/desktop/desktop.js

@@ -0,0 +1,108 @@
+/**
+ * Raise the desktop window that hosts a process (e.g. the terminal running a
+ * herdr client), so focusing a pane also brings its terminal to the front.
+ *
+ * Walks each candidate pid's ancestors via /proc/<pid>/stat and focuses the
+ * first ancestor that owns a window. Supported: Hyprland (hyprctl) and Sway
+ * (swaymsg). Anything else is a no-op. Never throws.
+ */
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+export const defaultExec = (file, args, opts) => new Promise((resolve, reject) => {
+    execFile(file, args, { timeout: opts.timeout, maxBuffer: 16 << 20, encoding: "utf8" }, (err, stdout) => {
+        if (err)
+            reject(err);
+        else
+            resolve({ stdout });
+    });
+});
+/** ppid from /proc/<pid>/stat; comm (field 2) may contain spaces and parens. */
+export async function parentPid(procRoot, pid) {
+    try {
+        const stat = await readFile(join(procRoot, String(pid), "stat"), "utf8");
+        const rest = stat.slice(stat.lastIndexOf(")") + 1).trim().split(/\s+/);
+        const ppid = Number(rest[1]);
+        return Number.isInteger(ppid) && ppid > 0 ? ppid : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** pid, then its parents up to (excluding) init. */
+async function ancestry(procRoot, pid) {
+    const chain = [];
+    const seen = new Set();
+    let cur = pid;
+    while (cur !== undefined && cur > 1 && !seen.has(cur) && chain.length < 64) {
+        seen.add(cur);
+        chain.push(cur);
+        cur = await parentPid(procRoot, cur);
+    }
+    return chain;
+}
+function hyprland(exec, timeout) {
+    return {
+        async windows() {
+            const { stdout } = await exec("hyprctl", ["clients", "-j"], { timeout });
+            const out = new Map();
+            for (const c of JSON.parse(stdout)) {
+                if (typeof c.pid === "number" && typeof c.address === "string" && !out.has(c.pid))
+                    out.set(c.pid, c.address);
+            }
+            return out;
+        },
+        async focus(address) {
+            await exec("hyprctl", ["dispatch", "focuswindow", `address:${address}`], { timeout });
+        },
+    };
+}
+function sway(exec, timeout) {
+    return {
+        async windows() {
+            const { stdout } = await exec("swaymsg", ["-t", "get_tree"], { timeout });
+            const out = new Map();
+            const walk = (n) => {
+                if (typeof n.pid === "number")
+                    out.set(n.pid, String(n.pid));
+                for (const c of [...(n.nodes ?? []), ...(n.floating_nodes ?? [])])
+                    walk(c);
+            };
+            walk(JSON.parse(stdout));
+            return out;
+        },
+        async focus(pid) {
+            await exec("swaymsg", [`[pid=${pid}]`, "focus"], { timeout });
+        },
+    };
+}
+export function createDesktop(opts = {}) {
+    const { env = process.env, exec = defaultExec, procRoot = "/proc", timeoutMs = 2000 } = opts;
+    const wm = env.HYPRLAND_INSTANCE_SIGNATURE
+        ? hyprland(exec, timeoutMs)
+        : env.SWAYSOCK
+            ? sway(exec, timeoutMs)
+            : undefined;
+    return {
+        async raise(pids) {
+            if (!wm || pids.length === 0)
+                return false;
+            try {
+                const windows = await wm.windows();
+                for (const pid of pids) {
+                    for (const p of await ancestry(procRoot, pid)) {
+                        const target = windows.get(p);
+                        if (target !== undefined) {
+                            await wm.focus(target);
+                            return true;
+                        }
+                    }
+                }
+            }
+            catch {
+                // no compositor, timeout, bad output: just don't raise
+            }
+            return false;
+        },
+    };
+}

package/dist/server/http.js

@@ -0,0 +1,240 @@
+import { createServer } from "node:http";
+import { readFile, stat } from "node:fs/promises";
+import { extname, join, normalize, sep } from "node:path";
+import { timingSafeEqual } from "node:crypto";
+import { SESSION_ID } from "./hub.js";
+const COOKIE = "excaliagent_token";
+const MAX_BODY = 50 * 1024 * 1024;
+const TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".mjs": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".json": "application/json",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".ico": "image/x-icon",
+    ".woff2": "font/woff2",
+    ".woff": "font/woff",
+    ".ttf": "font/ttf",
+    ".wasm": "application/wasm",
+};
+class HttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+function sameToken(a, b) {
+    if (!a)
+        return false;
+    const x = Buffer.from(a);
+    const y = Buffer.from(b);
+    return x.length === y.length && timingSafeEqual(x, y);
+}
+function cookieToken(req) {
+    for (const part of (req.headers.cookie ?? "").split(";")) {
+        const [k, ...v] = part.trim().split("=");
+        if (k === COOKIE)
+            return v.join("=");
+    }
+    return undefined;
+}
+function json(res, status, body) {
+    res.writeHead(status, { "content-type": "application/json", "cache-control": "no-store" });
+    res.end(JSON.stringify(body));
+}
+function text(res, status, body) {
+    res.writeHead(status, { "content-type": "text/plain; charset=utf-8" });
+    res.end(body);
+}
+async function readJson(req) {
+    if (!(req.headers["content-type"] ?? "").startsWith("application/json")) {
+        throw new HttpError(415, "expected application/json");
+    }
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > MAX_BODY)
+            throw new HttpError(413, "body too large");
+        chunks.push(chunk);
+    }
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    catch {
+        throw new HttpError(400, "invalid JSON");
+    }
+}
+export function createAppServer(opts) {
+    const host = opts.host ?? "127.0.0.1";
+    let port = 0;
+    const allowedHosts = () => new Set([`${host}:${port}`, `127.0.0.1:${port}`, `localhost:${port}`]);
+    const allowedOrigins = () => new Set([...allowedHosts()].map((h) => `http://${h}`));
+    async function serveStatic(req, res, pathname) {
+        const root = opts.webRoot;
+        if (!root)
+            return text(res, 404, "not found");
+        let rel;
+        try {
+            rel = decodeURIComponent(pathname);
+        }
+        catch {
+            return text(res, 400, "bad path");
+        }
+        if (rel === "/" || rel === "")
+            rel = "/index.html";
+        const file = normalize(join(root, rel));
+        if (!file.startsWith(normalize(root) + sep))
+            return text(res, 404, "not found");
+        try {
+            if (!(await stat(file)).isFile())
+                return text(res, 404, "not found");
+            const body = await readFile(file);
+            res.writeHead(200, {
+                "content-type": TYPES[extname(file)] ?? "application/octet-stream",
+                "cache-control": rel.startsWith("/assets/") ? "public, max-age=31536000, immutable" : "no-store",
+            });
+            res.end(req.method === "HEAD" ? undefined : body);
+        }
+        catch {
+            text(res, 404, "not found");
+        }
+    }
+    function events(req, res) {
+        res.writeHead(200, {
+            "content-type": "text/event-stream",
+            "cache-control": "no-store",
+            connection: "keep-alive",
+        });
+        const send = (sessions) => res.write(`event: sessions\ndata: ${JSON.stringify(sessions)}\n\n`);
+        send(opts.hub.sessions());
+        const unsubscribe = opts.hub.subscribe(send);
+        const heartbeat = setInterval(() => res.write(": ping\n\n"), 25_000);
+        req.on("close", () => {
+            clearInterval(heartbeat);
+            unsubscribe();
+        });
+    }
+    async function api(req, res, pathname) {
+        const route = `${req.method} ${pathname}`;
+        switch (route) {
+            case "GET /api/sessions":
+                return json(res, 200, opts.hub.sessions());
+            case "GET /api/events":
+                return events(req, res);
+            case "GET /api/picker":
+                return json(res, 200, await opts.hub.picker());
+            case "POST /api/lookup": {
+                const body = (await readJson(req));
+                if (!Array.isArray(body?.ids) || !body.ids.every((i) => typeof i === "string")) {
+                    throw new HttpError(400, "ids must be a string array");
+                }
+                return json(res, 200, await opts.hub.lookup(body.ids));
+            }
+            case "GET /api/scene":
+                return json(res, 200, await opts.scenes.load());
+            case "PUT /api/scene": {
+                const body = (await readJson(req));
+                if (!body || !Array.isArray(body.elements))
+                    throw new HttpError(400, "elements must be an array");
+                const appState = body.appState && typeof body.appState === "object" ? body.appState : {};
+                await opts.scenes.save({ elements: body.elements, appState: appState });
+                res.writeHead(204).end();
+                return;
+            }
+            case "POST /api/focus": {
+                const body = (await readJson(req));
+                if (typeof body?.sessionId !== "string")
+                    throw new HttpError(400, "sessionId required");
+                if (await opts.hub.focus(body.sessionId)) {
+                    res.writeHead(204).end();
+                    return;
+                }
+                return json(res, 409, { error: "no pane" });
+            }
+            case "POST /api/resume": {
+                const body = (await readJson(req));
+                if (typeof body?.sessionId !== "string" || !SESSION_ID.test(body.sessionId)) {
+                    throw new HttpError(400, "sessionId must be a session UUID");
+                }
+                const result = await opts.hub.resume(body.sessionId);
+                if (result === "resumed") {
+                    res.writeHead(204).end();
+                    return;
+                }
+                if (result === "unknown")
+                    return json(res, 404, { error: "unknown session" });
+                return json(res, 409, { error: result === "live" ? "live" : "no herdr" });
+            }
+            default:
+                return json(res, 404, { error: "not found" });
+        }
+    }
+    async function handle(req, res) {
+        if (!allowedHosts().has(req.headers.host ?? ""))
+            return text(res, 421, "unexpected Host header");
+        const url = new URL(req.url ?? "/", "http://localhost");
+        const method = req.method ?? "GET";
+        if (method !== "GET" && method !== "HEAD") {
+            const origin = req.headers.origin;
+            if (origin !== undefined && !allowedOrigins().has(origin))
+                return text(res, 403, "cross-origin request");
+        }
+        const queryToken = url.searchParams.get("token");
+        if (queryToken !== null && method === "GET" && !url.pathname.startsWith("/api/")) {
+            if (!sameToken(queryToken, opts.token))
+                return text(res, 401, "bad token");
+            res.writeHead(302, {
+                location: "/",
+                "set-cookie": `${COOKIE}=${opts.token}; HttpOnly; SameSite=Strict; Path=/`,
+            });
+            res.end();
+            return;
+        }
+        if (!sameToken(cookieToken(req), opts.token)) {
+            return text(res, 401, "excaliagent: open the URL printed in the terminal (it carries the access token).");
+        }
+        if (url.pathname.startsWith("/api/"))
+            return api(req, res, url.pathname);
+        if (opts.middleware)
+            return opts.middleware(req, res, () => text(res, 404, "not found"));
+        return serveStatic(req, res, url.pathname);
+    }
+    const server = createServer((req, res) => {
+        handle(req, res).catch((err) => {
+            const status = err instanceof HttpError ? err.status : 500;
+            if (status === 500)
+                console.error("excaliagent:", err);
+            if (!res.headersSent)
+                json(res, status, { error: err.message });
+            else
+                res.end();
+        });
+    });
+    return {
+        server,
+        get port() {
+            return port;
+        },
+        listen(p) {
+            return new Promise((resolve, reject) => {
+                server.once("error", reject);
+                server.listen(p, host, () => {
+                    server.off("error", reject);
+                    const addr = server.address();
+                    port = typeof addr === "object" && addr ? addr.port : p;
+                    resolve();
+                });
+            });
+        },
+        close() {
+            return new Promise((resolve) => {
+                server.close(() => resolve());
+                server.closeAllConnections();
+            });
+        },
+    };
+}