agent-log-viewer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Latand
+
+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,124 @@
+# Live Log Viewer
+
+A local web UI that turns raw Codex / Claude Code agent logs into a readable,
+live-updating chat feed. It discovers every session, subagent, Codex companion
+job and background shell task on your machine, links them into a parent→child
+tree, and tails the selected one in real time.
+
+## What it shows
+
+- **Claude Code sessions** (`~/.claude/projects/**/*.jsonl`) and their
+  subagents, rendered as a chat: user bubbles, assistant prose, tool-call
+  cards with ✓/✗ statuses and expandable output.
+- **Codex CLI sessions** (`~/.codex/sessions/**/rollout-*.jsonl`) with command
+  cards, patches and service events.
+- **Codex companion jobs** (`~/.claude/plugins/data/codex-openai-codex/state`)
+  with a one-click jump to the full rollout session behind each job.
+- **Background shell tasks** (`claude-<uid>/**/tasks/*.output` under the OS
+  temp dir — `/tmp` on Linux, `$TMPDIR` on macOS) — the originating Bash
+  command is recovered from the session transcript and shown above the
+  terminal output.
+
+## Highlights
+
+- **Parentage tree**: session → subagents → codex jobs → rollouts → background
+  tasks, built server-side by scanning transcripts (append-only incremental,
+  cached — the warm `/api/files` poll stays around 100 ms).
+- **Conversations first**: filter chips «Все · Розмови · Активні», stable
+  alphabetical project groups, most-recently-updated first inside a project,
+  technical noise collected under a collapsed «⚙ Технічне» group.
+- **Live activity**: content-based badges — a transcript is "працює" while
+  mid-turn and "закінчив" once the final assistant message lands.
+- **Deep links**: every selection is reflected in the URL (`#f=<path>`), so a
+  link opens that exact log.
+- Model chips (`fable-5`, `gpt-5.5`, `sonnet`…), collapsible tree with
+  persisted state, follow-mode autoscroll, service-event toggle, line filter.
+
+## Run
+
+Requires [bun](https://bun.sh) (or npm/pnpm), Node 20.9+, and
+[tmux](https://github.com/tmux/tmux) for the composer/spawn features (`brew
+install tmux` on macOS, or your distro's package on Linux).
+
+Once the package is published to npm, the quickstart is:
+
+```bash
+bunx agent-log-viewer
+```
+
+Local clone workflow:
+
+```bash
+bun install
+bun run build
+bun start --port 8898 --hostname 127.0.0.1
+# open http://127.0.0.1:8898/
+```
+
+`bun dev` works too (needs a high OS file-watch limit for large homedirs).
+
+## Platform support
+
+Linux is the native target: process discovery reads `/proc` directly. macOS
+is supported through a portable backend that shells out to `ps` and `lsof`
+instead — same live-process detection, tmux composer targeting, agent
+spawn/kill and background-task discovery, just a bit more subprocess
+overhead per scan. The backend is chosen automatically by `process.platform`
+(see `src/lib/proc/`); `VIEWER_PROC_BACKEND=portable` forces the portable
+path on Linux too, for testing.
+
+Without tmux installed, log viewing still works; the composer, agent spawn
+and resume-into-pane features are unavailable.
+
+## Доступ через Tailscale
+
+```bash
+bunx agent-log-viewer --tailscale
+```
+
+`--tailscale` запускає локальний сервер на `127.0.0.1` і відкриває його в
+tailnet через foreground-процес `tailscale serve <port>`. Публічний інтернет
+через Funnel не використовується.
+
+CLI створює 32-символьний ключ доступу, додає його в tailnet URL як `?k=...`,
+а після першого відкриття сервер зберігає `llv_auth` cookie на 30 днів.
+`--new-token` генерує новий ключ і одразу робить недійсними всі старі
+cookie — перевірка порівнює хеш кожного разу з поточним токеном, тож стара
+кука з попереднім ключем більше не проходить.
+
+Термінал одразу друкує tailnet URL і QR-код для сканування телефоном. Той
+самий QR доступний і в самому веб-інтерфейсі: кнопка з іконкою QR у шапці
+списку проєктів відкриває попап з кодом і посиланням у вигляді тексту (з
+кнопкою «копіювати»).
+QR малюється повністю на клієнті (пакет `qrcode`, без зовнішніх запитів) і
+віддається лише вже авторизованим клієнтам — той самий токен-гейт із
+`src/proxy.ts` захищає й `/api/access`. Якщо сервер запущено без
+`--tailscale`, кнопка показує підказку запустити
+`bunx agent-log-viewer --tailscale`.
+
+Кожен, хто має tailnet-доступ до цього URL, може читати всі agent transcripts,
+включно з чутливими даними, які потрапили в сесію, і може виконувати команди
+через `/api/tmux` та `/api/spawn`. Ставтеся до tailnet URL як до секрета — не
+пересилайте його стороннім.
+
+## Security model
+
+The log APIs refuse any path that does not resolve into one of the whitelisted
+log roots (see `src/lib/scanner/roots.ts`). Mutating endpoints exist:
+`/api/tmux` sends keys to tmux sessions and `/api/spawn` starts commands.
+
+By default the CLI binds to `127.0.0.1`. With `--tailscale`, access is exposed
+inside the tailnet via `tailscale serve` and guarded by the token gate in
+`src/proxy.ts`. Non-loopback binds also force token mode. Treat any URL
+containing `?k=` as a credential.
+
+## Architecture
+
+See [ARCHITECTURE.md](ARCHITECTURE.md): route handlers under
+`src/app/api/*`, a pure scanner pipeline under `src/lib/scanner/*`
+(discover → describe → activity → model → links), React components under
+`src/components/*`. Caches live on `globalThis` and survive dev hot-reload.
+
+## License
+
+MIT

package/bin/cli.mjs

@@ -0,0 +1,479 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import http from "node:http";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { detectTailscale, getToken, readStatus, serve as serveTailscale, TailscaleError } from "./tailscale.mjs";
+
+const DEFAULT_PORT = 8898;
+const DEFAULT_HOSTNAME = "127.0.0.1";
+const READINESS_TIMEOUT_MS = 15_000;
+const READINESS_INTERVAL_MS = 200;
+
+const cliPath = fileURLToPath(import.meta.url);
+const cliDir = dirname(cliPath);
+
+function usage() {
+  return `Використання: agent-log-viewer [опції]
+
+Опції:
+  -p, --port <n>       Порт для локального сервера (типово ${DEFAULT_PORT})
+  -H, --hostname <h>   Адреса прив'язки (типово ${DEFAULT_HOSTNAME})
+      --tailscale      Доступ через Tailscale
+      --no-open        Не відкривати браузер
+      --new-token      Створити новий ключ доступу
+  -v, --version        Показати версію
+  -h, --help           Показати довідку`;
+}
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+function parsePort(value) {
+  const port = Number(value);
+  if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+    fail(`Некоректний порт: ${value}`);
+  }
+  return port;
+}
+
+function requireValue(args, index, flag) {
+  const value = args[index + 1];
+  if (!value || value.startsWith("-")) {
+    fail(`Опція ${flag} потребує значення.`);
+  }
+  return value;
+}
+
+function parseArgs(args) {
+  const options = {
+    port: DEFAULT_PORT,
+    hostname: DEFAULT_HOSTNAME,
+    tailscale: false,
+    noOpen: false,
+    newToken: false,
+    help: false,
+    version: false,
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === "-p" || arg === "--port") {
+      const value = requireValue(args, index, arg);
+      options.port = parsePort(value);
+      index += 1;
+    } else if (arg.startsWith("--port=")) {
+      options.port = parsePort(arg.slice("--port=".length));
+    } else if (arg === "-H" || arg === "--hostname") {
+      options.hostname = requireValue(args, index, arg);
+      index += 1;
+    } else if (arg.startsWith("--hostname=")) {
+      const value = arg.slice("--hostname=".length);
+      if (!value) {
+        fail("Опція --hostname потребує значення.");
+      }
+      options.hostname = value;
+    } else if (arg === "--tailscale") {
+      options.tailscale = true;
+    } else if (arg === "--no-open") {
+      options.noOpen = true;
+    } else if (arg === "--new-token") {
+      options.newToken = true;
+    } else if (arg === "-v" || arg === "--version") {
+      options.version = true;
+    } else if (arg === "-h" || arg === "--help") {
+      options.help = true;
+    } else {
+      fail(`Невідома опція: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+function isLoopbackHostname(hostname) {
+  return hostname === "127.0.0.1" || hostname === "localhost" || hostname === "::1";
+}
+
+function findPackageRoot(startDir) {
+  let currentDir = startDir;
+
+  while (true) {
+    const packageJsonPath = join(currentDir, "package.json");
+    if (existsSync(packageJsonPath)) {
+      return currentDir;
+    }
+
+    const parentDir = dirname(currentDir);
+    if (parentDir === currentDir) {
+      fail("Не вдалося знайти package.json для agent-log-viewer.");
+    }
+    currentDir = parentDir;
+  }
+}
+
+function readPackageJson(packageRoot) {
+  const packageJsonPath = join(packageRoot, "package.json");
+  try {
+    return JSON.parse(readFileSync(packageJsonPath, "utf8"));
+  } catch (error) {
+    fail(
+      error instanceof Error
+        ? `Не вдалося прочитати package.json: ${error.message}`
+        : "Не вдалося прочитати package.json.",
+    );
+  }
+}
+
+function resolveServer(packageRoot) {
+  const publishedStandalone = join(packageRoot, "dist", "standalone", "server.js");
+  if (existsSync(publishedStandalone)) {
+    return {
+      command: process.execPath,
+      args: [publishedStandalone],
+      cwd: join(packageRoot, "dist", "standalone"),
+      label: "server.js",
+    };
+  }
+
+  const repoStandalone = join(packageRoot, ".next", "standalone", "server.js");
+  if (existsSync(repoStandalone)) {
+    return {
+      command: process.execPath,
+      args: [repoStandalone],
+      cwd: join(packageRoot, ".next", "standalone"),
+      label: "server.js",
+    };
+  }
+
+  const nextBin = join(packageRoot, "node_modules", ".bin", "next");
+  if (!existsSync(nextBin)) {
+    fail("Не знайдено standalone server.js або локальний next.");
+  }
+
+  return {
+    command: nextBin,
+    args: ["start"],
+    cwd: packageRoot,
+    label: "next start",
+  };
+}
+
+function buildChildEnv(options, runtime) {
+  const env = {
+    ...process.env,
+    PORT: String(options.port),
+    // zsh exports HOSTNAME with the machine name on this user's machine; setting it here keeps standalone bound to the requested address.
+    HOSTNAME: options.hostname,
+  };
+
+  if (runtime.llvToken) {
+    env.LLV_TOKEN = runtime.llvToken;
+  }
+
+  if (runtime.llvTsHost) {
+    env.LLV_TS_HOST = runtime.llvTsHost;
+  }
+
+  if (runtime.tailnetUrl) {
+    env.LLV_TS_URL = runtime.tailnetUrl;
+  }
+
+  return env;
+}
+
+function startServer(server, options, runtime, tailscaleProcessRef) {
+  const child = spawn(server.command, server.args, {
+    cwd: server.cwd,
+    env: buildChildEnv(options, runtime),
+    stdio: ["ignore", "inherit", "pipe"],
+  });
+
+  const state = {
+    sawAddressInUse: false,
+    stopping: false,
+  };
+
+  child.stderr.on("data", (chunk) => {
+    const text = chunk.toString("utf8");
+    if (text.includes("EADDRINUSE")) {
+      state.sawAddressInUse = true;
+      console.error(`Порт ${options.port} зайнятий. Спробуйте: bunx agent-log-viewer --port ${options.port + 1}`);
+      if (!child.killed) {
+        child.kill("SIGTERM");
+      }
+      return;
+    }
+
+    process.stderr.write(chunk);
+  });
+
+  child.on("error", (error) => {
+    fail(`Не вдалося запустити сервер: ${error.message}`);
+  });
+
+  child.on("exit", async (code, signal) => {
+    if (state.stopping) {
+      return;
+    }
+
+    // The server dying on its own (crash, EADDRINUSE) still leaves `tailscale
+    // serve` running as our child; stop it through the bounded path (SIGTERM,
+    // 2s, SIGKILL) so an unexpected server exit does not orphan the tailnet
+    // mapping even when serve ignores SIGTERM.
+    if (tailscaleProcessRef?.current) {
+      await stopChild(tailscaleProcessRef.current);
+    }
+
+    if (state.sawAddressInUse) {
+      process.exit(1);
+    }
+
+    if (signal) {
+      process.exit(0);
+    }
+
+    process.exit(code ?? 1);
+  });
+
+  return { child, state };
+}
+
+function wait(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+function probe(url) {
+  return new Promise((resolve) => {
+    const request = http.get(url, (response) => {
+      response.resume();
+      resolve(response.statusCode !== undefined && response.statusCode >= 200 && response.statusCode < 500);
+    });
+
+    request.on("error", () => {
+      resolve(false);
+    });
+
+    request.setTimeout(READINESS_INTERVAL_MS, () => {
+      request.destroy();
+      resolve(false);
+    });
+  });
+}
+
+async function portAlreadyResponds(port) {
+  return probe(`http://127.0.0.1:${port}/api/files`);
+}
+
+async function waitForReadiness(port) {
+  const deadline = Date.now() + READINESS_TIMEOUT_MS;
+  const url = `http://127.0.0.1:${port}/api/files`;
+
+  while (Date.now() < deadline) {
+    if (await probe(url)) {
+      return;
+    }
+
+    await wait(READINESS_INTERVAL_MS);
+  }
+
+  throw new Error(`Сервер не відповів за ${READINESS_TIMEOUT_MS / 1000} секунд.`);
+}
+
+function localUrl(options) {
+  const host = options.hostname === "::1" ? "[::1]" : options.hostname;
+  return `http://${host}:${options.port}/`;
+}
+
+function printBanner(version, options) {
+  console.log(`  ✳ Live Log Viewer v${version}`);
+  console.log(`  Відкрито:  ${localUrl(options)}`);
+  console.log("  Читає логи з ~/.claude/projects, ~/.codex/sessions.");
+  console.log("  Ctrl+C — зупинити.  --tailscale — доступ з телефона.");
+}
+
+async function printTailscaleBanner(runtime) {
+  if (!runtime.tailnetUrl) {
+    return;
+  }
+
+  console.log(`  Tailnet:   ${runtime.tailnetUrl}`);
+  const qrcodeModule = await import("qrcode-terminal");
+  const qrcode = qrcodeModule.default ?? qrcodeModule;
+  await new Promise((resolve) => {
+    qrcode.generate(runtime.tailnetUrl, { small: true }, (qr) => {
+      console.log(qr);
+      resolve();
+    });
+  });
+  console.log("  Посилання містить ключ доступу — не пересилайте його стороннім.");
+  console.log("  Після першого відкриття ключ зберігається у cookie на 30 днів.");
+}
+
+function openBrowser(url) {
+  const opener =
+    process.platform === "linux" ? "xdg-open" : process.platform === "darwin" ? "open" : null;
+
+  if (!opener) {
+    return;
+  }
+
+  const child = spawn(opener, [url], {
+    stdio: "ignore",
+    detached: true,
+  });
+  child.unref();
+}
+
+async function stopChild(processHandle) {
+  const { child, state } = processHandle;
+  state.stopping = true;
+
+  if (child.exitCode !== null || child.signalCode !== null) {
+    return;
+  }
+
+  await new Promise((resolve) => {
+    const timeout = setTimeout(() => {
+      if (child.exitCode === null && child.signalCode === null) {
+        child.kill("SIGKILL");
+      }
+    }, 2_000);
+
+    child.once("exit", () => {
+      clearTimeout(timeout);
+      resolve();
+    });
+
+    if (!child.killed) {
+      child.kill("SIGTERM");
+    }
+  });
+}
+
+async function stopAll(serverProcess, tailscaleProcess) {
+  await Promise.all([
+    serverProcess ? stopChild(serverProcess) : Promise.resolve(),
+    tailscaleProcess ? stopChild(tailscaleProcess) : Promise.resolve(),
+  ]);
+}
+
+function installSignalHandlers(serverProcess, tailscaleProcessRef) {
+  const shutdown = async () => {
+    await stopAll(serverProcess, tailscaleProcessRef.current);
+    process.exit(0);
+  };
+
+  process.once("SIGINT", shutdown);
+  process.once("SIGTERM", shutdown);
+}
+
+async function prepareRuntime(options) {
+  const runtime = {
+    llvToken: undefined,
+    llvTsHost: undefined,
+    tailnetUrl: undefined,
+    tailscalePath: undefined,
+  };
+
+  const nonLoopbackBind = !isLoopbackHostname(options.hostname);
+  if (nonLoopbackBind) {
+    console.error("Увага: нелокальна адреса відкриває viewer для мережі, тому режим ключа доступу увімкнено примусово.");
+  }
+
+  if (options.tailscale) {
+    const tailscalePath = await detectTailscale();
+    const status = await readStatus(tailscalePath);
+    const { token } = await getToken({ rotate: options.newToken });
+    runtime.llvToken = token;
+    runtime.llvTsHost = status.dnsName;
+    runtime.tailnetUrl = `https://${status.dnsName}/?k=${token}`;
+    runtime.tailscalePath = tailscalePath;
+    options.hostname = DEFAULT_HOSTNAME;
+    return runtime;
+  }
+
+  if (nonLoopbackBind) {
+    const { token } = await getToken({ rotate: options.newToken });
+    runtime.llvToken = token;
+  }
+
+  return runtime;
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  const packageRoot = findPackageRoot(cliDir);
+  const packageJson = readPackageJson(packageRoot);
+  const version = typeof packageJson.version === "string" ? packageJson.version : "0.0.0";
+
+  if (options.help) {
+    console.log(usage());
+    return;
+  }
+
+  if (options.version) {
+    console.log(version);
+    return;
+  }
+
+  let runtime;
+  try {
+    runtime = await prepareRuntime(options);
+  } catch (error) {
+    if (error instanceof TailscaleError) {
+      fail(error.message);
+    }
+    throw error;
+  }
+
+  if (await portAlreadyResponds(options.port)) {
+    console.error(`Порт ${options.port} зайнятий. Спробуйте: bunx agent-log-viewer --port ${options.port + 1}`);
+    process.exit(1);
+  }
+
+  const server = resolveServer(packageRoot);
+  const tailscaleProcessRef = { current: null };
+  const serverProcess = startServer(server, options, runtime, tailscaleProcessRef);
+  installSignalHandlers(serverProcess, tailscaleProcessRef);
+
+  if (options.tailscale && runtime.tailscalePath) {
+    tailscaleProcessRef.current = serveTailscale(runtime.tailscalePath, options.port);
+  }
+
+  try {
+    await waitForReadiness(options.port);
+  } catch (error) {
+    await stopAll(serverProcess, tailscaleProcessRef.current);
+    fail(error instanceof Error ? error.message : "Сервер не готовий.");
+  }
+
+  if (
+    serverProcess.state.sawAddressInUse ||
+    serverProcess.child.exitCode !== null ||
+    serverProcess.child.signalCode !== null
+  ) {
+    process.exit(serverProcess.state.sawAddressInUse ? 1 : (serverProcess.child.exitCode ?? 1));
+  }
+
+  printBanner(version, options);
+  if (options.tailscale) {
+    await printTailscaleBanner(runtime);
+  }
+
+  if (!options.noOpen && process.stdout.isTTY) {
+    openBrowser(localUrl(options));
+  }
+}
+
+main().catch((error) => {
+  fail(error instanceof Error ? error.message : String(error));
+});