agello 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark
+
+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,103 @@
+# agello
+
+**agent + hello.** Talk to a coding agent running in a [herdr](https://herdr.dev) pane from your browser.
+
+- Chat with the agent from a web page; terminal input, browser input and agent replies are shown as separate bubbles
+- Live session status, tool activity, and prompts queued while the agent is busy (same order as the terminal)
+- Conversation saved per pane in the browser, kept across reloads
+- Optional live view of a `terminal-browser` screen, with an on/off switch to control it yourself
+- Embeddable `<agent-bridge>` web component
+
+Currently supports **Claude Code** sessions.
+
+## Requirements
+
+- [Bun](https://bun.sh) >= 1.1
+- [herdr](https://herdr.dev) (the agent must run inside a herdr pane)
+- Optional: `terminal-browser` for the screen panel
+
+## Install
+
+```sh
+bun add -g agello      # or: npm i -g agello  (Bun is still required to run it)
+```
+
+Or run without installing: `bunx agello start --open`
+
+From source:
+
+```sh
+git clone https://github.com/obov/agello
+cd agello
+bun link               # puts `agello` on your PATH
+```
+
+## Usage
+
+Run inside the herdr pane where the agent is running (`$HERDR_PANE_ID` is picked up automatically):
+
+```sh
+agello start --open      # start in the background and open the page
+agello status            # list running servers
+agello stop              # stop
+```
+
+Or target another pane:
+
+```sh
+agello start --pane w1:p2 --port 8766
+```
+
+Messages sent from the page arrive in the agent as:
+
+```
+[browser] action=message your text
+```
+
+The approve / reject buttons send `action=approve` / `action=reject`.
+
+### Commands
+
+| Command | Description |
+|---|---|
+| `agello start [options]` | Start a server in the background |
+| `agello stop [--port N \| --all]` | Stop a server |
+| `agello status [--json]` | List running servers and agent state |
+| `agello open [--port N]` | Open the page in the default browser |
+
+`start` options: `--pane <id>`, `--port <n>` (default 8765), `--session <id>`, `--browser <terminal-browser key>`, `--allow-origin <origin>` (repeatable), `--open`, `--foreground`.
+
+State and logs: `~/.local/state/agello/<port>.json`, `<port>.log`.
+
+## Embed
+
+```html
+<script type="module" src="http://127.0.0.1:8765/agent-bridge.js"></script>
+<agent-bridge screen style="height: 600px"></agent-bridge>
+```
+
+| Attribute | |
+|---|---|
+| `server` | server origin (default: where the script was loaded from) |
+| `heading` | header text |
+| `screen` | show the terminal-browser screen panel |
+| `no-header`, `no-actions`, `no-history` | hide header / hide approve-reject / don't persist chat |
+
+Theme with CSS variables: `--ab-accent`, `--ab-bg`, `--ab-panel`, `--ab-text`, `--ab-muted`, `--ab-line`.
+Events: `agent-status`, `agent-message`, `agent-tool`, `agent-queue`, `agent-screen`. Method: `el.send(text, action)`.
+See `web/embed-example.html`.
+
+## How it works
+
+- **Send**: `herdr agent prompt <pane> "<text>"` (kept to 3 lines so Claude Code does not treat it as a paste)
+- **Status**: `herdr agent get` / `herdr pane get`, polled every 1.5s
+- **Chat**: tails the Claude Code transcript (`$CLAUDE_CONFIG_DIR/projects/*/<session>.jsonl`) and streams it over SSE
+- **Screen**: finds the terminal-browser CDP port via `terminal-browser ls --json` and relays `Page.startScreencast` frames; user control forwards `Input.*` events only
+
+## Security
+
+The server listens on `127.0.0.1` only. Data and input endpoints accept requests from the same origin and `localhost` pages only; other origins get `403` unless added with `--allow-origin`. Anything allowed to post to `/send` can type into your agent session, so keep the allow list short.
+
+## License
+
+MIT

package/bin/agello.ts

@@ -0,0 +1,262 @@
+#!/usr/bin/env bun
+// agello: talk to a coding agent in a herdr pane from the browser.
+
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, openSync, readdirSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { parseArgs } from "node:util";
+import pkg from "../package.json";
+import { startServer } from "../src/server.ts";
+
+const NAME = "agello";
+const DEFAULT_PORT = 8765;
+const STATE_DIR = join(process.env.XDG_STATE_HOME ?? join(homedir(), ".local", "state"), NAME);
+
+const HELP = `${NAME} ${pkg.version}: talk to a coding agent in a herdr pane from the browser
+
+Usage:
+  ${NAME} start [options]      Start a bridge server in the background
+  ${NAME} stop [--port N|--all] Stop a running server
+  ${NAME} status [--json]      List running servers
+  ${NAME} open [--port N]      Open the bridge page in the default browser
+  ${NAME} help | --version
+
+start options:
+  --pane <id>            herdr pane of the agent (default: $HERDR_PANE_ID)
+  --port <n>             port (default: ${DEFAULT_PORT})
+  --session <id>         expected agent session id (default: session seen at start)
+  --browser <key>        terminal-browser key for the screen panel (default: same herdr tab)
+  --allow-origin <o>     extra allowed origin for embedding, repeatable ("null" for file://)
+  --open                 open the page after starting
+  --foreground           run in this process instead of the background
+
+Requires: bun, herdr. Optional: terminal-browser (screen panel).
+State and logs: ${STATE_DIR}
+`;
+
+type Instance = {
+  pid: number;
+  port: number;
+  pane: string;
+  session?: string;
+  url: string;
+  log: string;
+  startedAt: string;
+};
+
+// ---------- state files ----------
+
+const statePath = (port: number) => join(STATE_DIR, `${port}.json`);
+const logPath = (port: number) => join(STATE_DIR, `${port}.log`);
+
+function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readInstance(port: number): Promise<Instance | null> {
+  const f = Bun.file(statePath(port));
+  if (!(await f.exists())) return null;
+  try {
+    const inst = (await f.json()) as Instance;
+    if (isAlive(inst.pid)) return inst;
+  } catch {}
+  rmSync(statePath(port), { force: true }); // stale
+  return null;
+}
+
+async function listInstances(): Promise<Instance[]> {
+  if (!existsSync(STATE_DIR)) return [];
+  const ports = readdirSync(STATE_DIR)
+    .map((f) => f.match(/^(\d+)\.json$/)?.[1])
+    .filter(Boolean)
+    .map(Number);
+  const all = await Promise.all(ports.map(readInstance));
+  return all.filter((i): i is Instance => !!i).sort((a, b) => a.port - b.port);
+}
+
+async function fetchStatus(url: string): Promise<any | null> {
+  try {
+    const res = await fetch(`${url}/status`, { signal: AbortSignal.timeout(4000) });
+    return res.ok ? await res.json() : null;
+  } catch {
+    return null;
+  }
+}
+
+function openUrl(url: string) {
+  const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+  Bun.spawn([cmd, url], { stdout: "ignore", stderr: "ignore" });
+}
+
+const fail = (msg: string): never => {
+  console.error(`${NAME}: ${msg}`);
+  process.exit(1);
+};
+
+// ---------- commands ----------
+
+async function cmdStart(argv: string[]) {
+  const { values: o } = parseArgs({
+    args: argv,
+    options: {
+      pane: { type: "string", default: process.env.HERDR_PANE_ID },
+      port: { type: "string", default: String(DEFAULT_PORT) },
+      session: { type: "string" },
+      browser: { type: "string" },
+      "allow-origin": { type: "string", multiple: true, default: [] },
+      open: { type: "boolean", default: false },
+      foreground: { type: "boolean", default: false },
+    },
+  });
+  const port = Number(o.port);
+  if (!o.pane) fail("--pane is required (HERDR_PANE_ID is not set; run inside herdr or pass --pane)");
+  if (!Bun.which("herdr")) fail("herdr not found on PATH");
+  mkdirSync(STATE_DIR, { recursive: true });
+
+  const existing = await readInstance(port);
+  if (existing) {
+    console.log(`already running: ${existing.url} (pane ${existing.pane}, pid ${existing.pid})`);
+    if (o.open) openUrl(existing.url);
+    return;
+  }
+
+  if (o.foreground) {
+    const srv = await startServer({
+      port,
+      pane: o.pane!,
+      session: o.session,
+      browser: o.browser,
+      allowOrigins: o["allow-origin"] as string[],
+    });
+    const inst: Instance = {
+      pid: process.pid,
+      port,
+      pane: srv.pane,
+      session: srv.session,
+      url: srv.url,
+      log: logPath(port),
+      startedAt: new Date().toISOString(),
+    };
+    await Bun.write(statePath(port), JSON.stringify(inst, null, 2));
+    const shutdown = () => {
+      srv.stop();
+      rmSync(statePath(port), { force: true });
+      process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    console.log(`listening ${srv.url} pane=${srv.pane} session=${srv.session} transcript=${srv.transcript}`);
+    if (o.open) openUrl(srv.url);
+    return;
+  }
+
+  // Background: re-run this CLI with --foreground, detached, logging to a file.
+  const args = argv.filter((a) => a !== "--open");
+  const log = openSync(logPath(port), "a");
+  const child = spawn(process.execPath, [import.meta.path, "start", "--foreground", ...args], {
+    detached: true,
+    stdio: ["ignore", log, log],
+    env: { ...process.env, HERDR_PANE_ID: o.pane },
+  });
+  child.unref();
+
+  const url = `http://127.0.0.1:${port}`;
+  const deadline = Date.now() + 15000;
+  while (Date.now() < deadline) {
+    if (child.exitCode !== null || !isAlive(child.pid!)) fail(`server exited; see ${logPath(port)}`);
+    if ((await readInstance(port)) && (await fetchStatus(url))) {
+      console.log(`started: ${url} (pane ${o.pane}, pid ${child.pid})`);
+      console.log(`log: ${logPath(port)}`);
+      if (o.open) openUrl(url);
+      return;
+    }
+    await Bun.sleep(200);
+  }
+  fail(`server did not become ready in 15s; see ${logPath(port)}`);
+}
+
+async function cmdStop(argv: string[]) {
+  const { values: o } = parseArgs({
+    args: argv,
+    options: { port: { type: "string" }, all: { type: "boolean", default: false } },
+  });
+  const targets = o.all
+    ? await listInstances()
+    : [await readInstance(Number(o.port ?? DEFAULT_PORT))].filter((i): i is Instance => !!i);
+  if (!targets.length) {
+    console.log("not running");
+    return;
+  }
+  for (const inst of targets) {
+    process.kill(inst.pid, "SIGTERM");
+    const deadline = Date.now() + 3000;
+    while (isAlive(inst.pid) && Date.now() < deadline) await Bun.sleep(100);
+    if (isAlive(inst.pid)) process.kill(inst.pid, "SIGKILL");
+    rmSync(statePath(inst.port), { force: true });
+    console.log(`stopped: ${inst.url} (pid ${inst.pid})`);
+  }
+}
+
+async function cmdStatus(argv: string[]) {
+  const { values: o } = parseArgs({ args: argv, options: { json: { type: "boolean", default: false } } });
+  const list = await listInstances();
+  const rows = await Promise.all(list.map(async (i) => ({ ...i, agent: await fetchStatus(i.url) })));
+  if (o.json) {
+    console.log(JSON.stringify(rows, null, 2));
+    return;
+  }
+  if (!rows.length) {
+    console.log("no running servers");
+    return;
+  }
+  for (const r of rows) {
+    const a = r.agent;
+    const state = !a ? "unreachable" : a.alive ? a.status : `dead (${a.reason})`;
+    const name = a?.label ? `${a.label} (${r.pane})` : r.pane;
+    console.log(`${r.url}  pane=${name}  agent=${state}  pid=${r.pid}`);
+  }
+}
+
+async function cmdOpen(argv: string[]) {
+  const { values: o } = parseArgs({ args: argv, options: { port: { type: "string" } } });
+  const inst = await readInstance(Number(o.port ?? DEFAULT_PORT));
+  if (!inst) fail(`not running on port ${o.port ?? DEFAULT_PORT}; run \`${NAME} start\``);
+  openUrl(inst!.url);
+  console.log(inst!.url);
+}
+
+// ---------- main ----------
+
+const [cmd, ...rest] = Bun.argv.slice(2);
+switch (cmd) {
+  case "start":
+    await cmdStart(rest);
+    break;
+  case "stop":
+    await cmdStop(rest);
+    break;
+  case "status":
+    await cmdStatus(rest);
+    break;
+  case "open":
+    await cmdOpen(rest);
+    break;
+  case "--version":
+  case "-v":
+    console.log(pkg.version);
+    break;
+  case undefined:
+  case "help":
+  case "--help":
+  case "-h":
+    console.log(HELP);
+    break;
+  default:
+    fail(`unknown command: ${cmd}\n\n${HELP}`);
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "agello",
+  "version": "0.1.0",
+  "description": "Talk to a coding agent in a herdr pane from the browser: chat, live status, and a shared browser screen.",
+  "keywords": [
+    "herdr",
+    "claude-code",
+    "coding-agent",
+    "browser",
+    "bridge",
+    "cli",
+    "bun"
+  ],
+  "homepage": "https://github.com/obov/agello#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/obov/agello.git"
+  },
+  "bugs": {
+    "url": "https://github.com/obov/agello/issues"
+  },
+  "type": "module",
+  "bin": {
+    "agello": "bin/agello.ts"
+  },
+  "files": [
+    "bin",
+    "src",
+    "web"
+  ],
+  "engines": {
+    "bun": ">=1.1"
+  },
+  "license": "MIT"
+}

package/src/run.ts

@@ -0,0 +1,28 @@
+// Run a CLI and return stdout, or null on failure/timeout.
+//
+// - The child is killed after `timeout` ms.
+// - Completion is decided by the process exit, not by stdout EOF: a killed
+//   child's own subprocess can keep the pipe open, and waiting for EOF would
+//   stall the caller until that orphan exits.
+// - stderr is ignored (an unread pipe can fill up and block the child).
+export async function run(cmd: string[], timeout = 3000): Promise<string | null> {
+  try {
+    const p = Bun.spawn(cmd, { stdout: "pipe", stderr: "ignore", timeout });
+    const out = new Response(p.stdout).text();
+    const code = await p.exited;
+    if (code !== 0) return null;
+    return await out;
+  } catch {
+    return null;
+  }
+}
+
+export async function runJson(cmd: string[], timeout = 3000): Promise<any | null> {
+  const out = await run(cmd, timeout);
+  if (out === null) return null;
+  try {
+    return JSON.parse(out);
+  } catch {
+    return null;
+  }
+}

package/src/screencast.ts

@@ -0,0 +1,179 @@
+import { runJson } from "./run.ts";
+
+// terminal-browser screen relay: CDP Page.startScreencast -> SSE (/screen).
+//
+// Discovers the terminal-browser instance with `terminal-browser ls --all --json`,
+// follows its active tab, and streams JPEG frames only while at least one
+// viewer is connected. input() forwards whitelisted CDP Input.* commands
+// from the viewer to the page (user control).
+
+type Browser = {
+  key: string;
+  cdpPort: number;
+  pane?: { tab: string; pane: string };
+  tabs: { id: number; url: string; title: string; active: boolean; targetId: string; agentControlled: boolean }[];
+};
+
+export type ScreenMeta = {
+  connected: boolean;
+  browser?: string;
+  url?: string;
+  title?: string;
+  agentControlled?: boolean;
+};
+
+export function createScreencast(opts: { browserKey?: string; herdrTab?: () => Promise<string | undefined> }) {
+  const viewers = new Set<ReadableStreamDefaultController>();
+  const enc = new TextEncoder();
+
+  let meta: ScreenMeta = { connected: false };
+  let lastFrame: { data: string; w: number; h: number } | null = null;
+  let ws: WebSocket | null = null;
+  let wsTarget = "";
+  let msgId = 0;
+  let timer: Timer | null = null;
+
+  const emit = (c: ReadableStreamDefaultController, event: string, data: unknown) => {
+    try {
+      c.enqueue(enc.encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`));
+    } catch {
+      viewers.delete(c);
+    }
+  };
+  const broadcast = (event: string, data: unknown) => viewers.forEach((c) => emit(c, event, data));
+
+  function setMeta(next: ScreenMeta) {
+    if (JSON.stringify(next) === JSON.stringify(meta)) return;
+    meta = next;
+    broadcast("meta", meta);
+  }
+
+  async function listBrowsers(): Promise<Browser[]> {
+    // timeout: a hung terminal-browser must not pile up processes or stall sync
+    return (await runJson(["terminal-browser", "ls", "--all", "--json"], 3000))?.browsers ?? [];
+  }
+
+  async function pickBrowser(): Promise<Browser | undefined> {
+    const all = await listBrowsers();
+    if (opts.browserKey) return all.find((b) => b.key === opts.browserKey);
+    const tab = await opts.herdrTab?.();
+    return all.find((b) => b.pane?.tab === tab) ?? all[0];
+  }
+
+  function disconnect() {
+    ws?.close();
+    ws = null;
+    wsTarget = "";
+  }
+
+  function connect(port: number, targetId: string) {
+    disconnect();
+    const url = `ws://127.0.0.1:${port}/devtools/page/${targetId}`;
+    wsTarget = url;
+    const sock = new WebSocket(url);
+    ws = sock;
+    const call = (method: string, params: object = {}) =>
+      sock.send(JSON.stringify({ id: ++msgId, method, params }));
+
+    sock.onopen = () => {
+      call("Page.enable");
+      call("Page.startScreencast", { format: "jpeg", quality: 70, maxWidth: 1600, maxHeight: 1600 });
+    };
+    sock.onmessage = (ev) => {
+      const msg = JSON.parse(String(ev.data));
+      if (msg.method !== "Page.screencastFrame") return;
+      const { data, metadata, sessionId } = msg.params;
+      call("Page.screencastFrameAck", { sessionId });
+      lastFrame = { data, w: metadata.deviceWidth, h: metadata.deviceHeight };
+      broadcast("frame", lastFrame);
+    };
+    sock.onclose = () => {
+      if (ws === sock) {
+        ws = null;
+        wsTarget = "";
+      }
+    };
+  }
+
+  let syncing = false; // skip a tick while the previous sync is still running
+  async function sync() {
+    if (syncing) return;
+    syncing = true;
+    try {
+      await syncOnce();
+    } finally {
+      syncing = false;
+    }
+  }
+
+  async function syncOnce() {
+    const b = await pickBrowser();
+    const tab = b?.tabs.find((t) => t.active);
+    if (!b || !tab) {
+      disconnect();
+      lastFrame = null;
+      setMeta({ connected: false });
+      return;
+    }
+    const url = `ws://127.0.0.1:${b.cdpPort}/devtools/page/${tab.targetId}`;
+    if (url !== wsTarget || !ws) connect(b.cdpPort, tab.targetId);
+    setMeta({
+      connected: true,
+      browser: b.key,
+      url: tab.url,
+      title: tab.title,
+      agentControlled: tab.agentControlled,
+    });
+  }
+
+  function start() {
+    if (timer) return;
+    sync();
+    timer = setInterval(sync, 1500);
+  }
+  function stop() {
+    if (timer) clearInterval(timer);
+    timer = null;
+    disconnect();
+    lastFrame = null;
+    meta = { connected: false };
+  }
+
+  // SSE response for one viewer.
+  function handle(): Response {
+    let ctrl!: ReadableStreamDefaultController;
+    let ping: Timer;
+    const stream = new ReadableStream({
+      start(c) {
+        ctrl = c;
+        viewers.add(c);
+        emit(c, "meta", meta);
+        if (lastFrame) emit(c, "frame", lastFrame);
+        ping = setInterval(() => emit(c, "ping", {}), 15000);
+        start();
+      },
+      cancel() {
+        clearInterval(ping);
+        viewers.delete(ctrl);
+        if (viewers.size === 0) stop();
+      },
+    });
+    return new Response(stream, {
+      headers: { "Content-Type": "text/event-stream", "Cache-Control": "no-cache", Connection: "keep-alive" },
+    });
+  }
+
+  const INPUT_METHODS = new Set(["Input.dispatchMouseEvent", "Input.dispatchKeyEvent", "Input.insertText"]);
+  function input(raw: string) {
+    let m: any;
+    try {
+      m = JSON.parse(raw);
+    } catch {
+      return;
+    }
+    if (!INPUT_METHODS.has(m?.method) || !ws || ws.readyState !== WebSocket.OPEN) return;
+    ws.send(JSON.stringify({ id: ++msgId, method: m.method, params: m.params ?? {} }));
+  }
+
+  return { handle, input };
+}