agent-log-viewer 0.1.1 → 0.3.0

package/README.md

@@ -1,9 +1,16 @@
 # 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.
+`agent-log-viewer` is 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.
+
+Everything runs locally against files already on disk. There is no database and
+no external service — the app reads `~/.claude` and `~/.codex` and renders what
+it finds.
+
+![The chat feed: user bubbles, assistant prose, and tool-call cards with
+statuses and expandable output](docs/media/chat-feed.png)
 
 ## What it shows
 
@@ -24,29 +31,42 @@ tree, and tails the selected one in real time.
 - **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.
+- **Live activity**: content-based badges — a transcript reads *working* while
+  it is mid-turn and *done* 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.
+- **Project scheme**: each project is a pannable, zoomable diagram — the root
+  conversation on top, spawned agents one generation below, arrows colored by
+  engine. Quiet branches and tasks collapse under their nearest ancestor.
+- **English or Ukrainian UI**, model chips (`fable-5`, `gpt-5.5`, `sonnet`…),
+  collapsible tree with persisted state, follow-mode autoscroll, service-event
+  toggle, and a line filter.
 
-## Run
+## Screenshots
+
+The session parentage tree, wiring root conversations to their spawned agents:
+
+![Session parentage tree](docs/media/session-tree.png)
 
-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).
+| A Codex CLI session | The overview board |
+| --- | --- |
+| ![Codex session with command cards and patches](docs/media/codex-session.png) | ![Overview board across projects](docs/media/overview-board.png) |
 
-Once the package is published to npm, the quickstart is:
+## Run
+
+The package is published to npm, so the quickstart needs no clone:
 
 ```bash
 bunx agent-log-viewer
+# or
+npx agent-log-viewer
 ```
 
-Local clone workflow:
+This starts the server on `127.0.0.1:8898` and opens your browser.
+
+### From a local clone
+
+With bun:
 
 ```bash
 bun install
@@ -55,20 +75,91 @@ 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).
+With npm (note the `--` that forwards flags to the start script):
+
+```bash
+npm install
+npm run build
+npm start -- --port 8898 --hostname 127.0.0.1
+```
+
+`start` serves the output of the last `build`, so run `build` first. For
+development, `bun dev` runs the app with hot reload (it needs a high OS
+file-watch limit for large home directories).
+
+**Prerequisites:** Node ≥ 20.9, and bun or npm/pnpm. `tmux` is optional — see
+[Platform support](#platform-support).
+
+### CLI options
+
+```
+agent-log-viewer [options]
+```
+
+| Option | Description |
+| --- | --- |
+| `-p, --port <n>` | Port for the local server (default `8898`). |
+| `-H, --hostname <h>` | Bind address (default `127.0.0.1`). |
+| `--tailscale` | Expose the viewer inside your tailnet (see below). |
+| `--new-token` | Generate a fresh access key and invalidate old cookies. |
+| `--no-open` | Don't open the browser on start. |
+| `-v, --version` | Print the version. |
+| `-h, --help` | Show usage. |
 
 ## 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`
+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.
+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.
+The package supports Linux and macOS. The package's `os` field blocks Windows
+installs with `EBADPLATFORM`. WSL works as Linux.
+
+`tmux` is optional. Without it, log viewing, the parentage tree, live activity
+and deep links all work; the composer, agent spawn/kill and resume-into-pane
+features need tmux (`brew install tmux` on macOS, or your distro's package on
+Linux).
+
+## Language
+
+The UI defaults to English and shows a compact EN/UK toggle in the project
+list header. The locale is resolved as `localStorage` key `llv_lang` first,
+then the browser language (Ukrainian if the browser prefers it), then English.
+
+CLI messages are English by default, and switch to Ukrainian with
+`LLV_LANG=uk` or a `uk_*` value in `LANG`/`LC_ALL`.
+
+## Dictation / voice input
+
+Composers that talk to agents have a mic button for dictating messages. By
+default transcription runs fully locally via faster-whisper — no audio leaves
+the machine. Run `scripts/setup-whisper.sh` once to install the local engine.
+
+Two cloud backends are available as an explicit per-machine opt-in (never a UI
+toggle): ChatGPT (reuses your local Codex login) and ElevenLabs Scribe (the
+only one with live, streaming transcription). Select with
+`LLV_TRANSCRIBE_BACKEND=local|chatgpt|elevenlabs` or by writing the backend
+name to `~/.config/agent-log-viewer/transcribe-backend`; local is the default.
+
+See [docs/transcription.md](docs/transcription.md) for setup, key locations,
+and troubleshooting.
+
+## Review loops
+
+The viewer orchestrates implement→review cycles: a long-lived implementer
+agent in tmux, a fresh read-only reviewer per round over the full diff,
+automatic relay of findings, and a verdict deck in the scheme view. Start one
+from the **Flow** chip above a conversation pane; presets pair engines and
+reasoning efforts per role (e.g. `Codex high → Fable`).
+
+See [docs/review-loop.md](docs/review-loop.md) for the round protocol,
+presets, the HTTP automation API, and troubleshooting. A Claude Code skill
+for driving flows from an agent ships in `.claude/skills/review-loop/` —
+agents working in a clone pick it up automatically.
 
 ## Tailscale access
 
@@ -76,29 +167,29 @@ and resume-into-pane features are unavailable.
 bunx agent-log-viewer --tailscale
 ```
 
-`--tailscale` starts the local server on `127.0.0.1` and exposes it inside
-your tailnet through a foreground `tailscale serve <port>` process. The
-public internet (Funnel) is never used.
-
-The CLI generates a 32-character access key, appends it to the tailnet URL
-as `?k=...`, and after the first visit the server sets an `llv_auth` cookie
-for 30 days. `--new-token` generates a fresh key and immediately invalidates
-every old cookie — each request compares the hash against the current token,
-so a cookie minted with a previous key no longer passes.
-
-The terminal prints the tailnet URL along with a QR code to scan with a
-phone. The same QR is available inside the web UI: the QR-icon button in the
-project list header opens a popover with the code and the link as text (with
-a copy button). The QR is rendered entirely client-side (the `qrcode`
-package, no external requests) and is served only to already-authorized
-clients — the same token gate from `src/proxy.ts` also protects
-`/api/access`. When the server runs without `--tailscale`, the button shows
-a hint to start `bunx agent-log-viewer --tailscale`.
+`--tailscale` starts the local server on `127.0.0.1` and exposes it inside your
+tailnet through a foreground `tailscale serve <port>` process. The public
+internet (Funnel) is never used.
+
+The CLI generates a 32-character access key, appends it to the tailnet URL as
+`?k=...`, and after the first visit the server sets an `llv_auth` cookie for 30
+days. `--new-token` generates a fresh key and immediately invalidates every old
+cookie — each request compares the hash against the current token, so a cookie
+minted with a previous key no longer passes.
+
+The terminal prints the tailnet URL along with a QR code to scan with a phone.
+The same QR is available inside the web UI: the QR-icon button in the project
+list header opens a popover with the code and the link as text (with a copy
+button). The QR is rendered entirely client-side (the `qrcode` package, no
+external requests) and is served only to already-authorized clients — the same
+token gate from `src/proxy.ts` also protects `/api/access`. When the server
+runs without `--tailscale`, the button shows a hint to start
+`bunx agent-log-viewer --tailscale`.
 
 Anyone with tailnet access to this URL can read all agent transcripts,
-including any sensitive data that landed in a session, and can execute
-commands through `/api/tmux` and `/api/spawn`. Treat the tailnet URL as a
-secret — do not forward it to anyone else.
+including any sensitive data that landed in a session, and can execute commands
+through `/api/tmux` and `/api/spawn`. Treat the tailnet URL as a secret — do
+not forward it to anyone else.
 
 ## Security model
 
@@ -111,12 +202,41 @@ 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.
 
+## Environment variables
+
+All optional. Transcription variables are documented in full in
+[docs/transcription.md](docs/transcription.md).
+
+| Variable | Effect |
+| --- | --- |
+| `VIEWER_PROC_BACKEND` | `portable` or `linux` — force the process-discovery backend (auto-selected by default). |
+| `LLV_LANG` | `uk` or `en` — force the CLI message language. |
+| `LLV_TRANSCRIBE_BACKEND` | `local`, `chatgpt`, or `elevenlabs` — pick the dictation backend (default `local`). |
+| `LLV_WHISPER_MODEL` | faster-whisper model size (default `small`). |
+| `LLV_WHISPER_DEVICE` | `cpu` (default) or `cuda`. |
+| `LLV_WHISPER_VENV` | Path to the whisper virtualenv (default `~/.cache/agent-log-viewer/whisper-venv`). |
+| `LLV_ELEVENLABS_STT_MODEL` | ElevenLabs batch model override. |
+| `ELEVENLABS_API_KEY` | ElevenLabs API key for the ElevenLabs backend. |
+
+## Config paths
+
+The viewer keeps its state under the standard XDG directories, named after the
+package:
+
+- `~/.config/agent-log-viewer/` — access `token`, `transcribe-backend`, and
+  `elevenlabs-api-key`.
+- `~/.cache/agent-log-viewer/whisper-venv` — the local transcription
+  virtualenv.
+
+Legacy `live-log-viewer` paths are still honored as read-only fallbacks, so
+existing setups keep working without changes.
+
 ## 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.
+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
 

package/bin/cli.mjs

@@ -16,8 +16,50 @@ const READINESS_INTERVAL_MS = 200;
 const cliPath = fileURLToPath(import.meta.url);
 const cliDir = dirname(cliPath);
 
-function usage() {
-  return `Використання: agent-log-viewer [опції]
+/* Dependency-free CLI localization: English by default, Ukrainian when
+   LLV_LANG=uk or the locale (LC_ALL/LANG) is a uk_* / uk.* variant. */
+function detectLang() {
+  const explicit = (process.env.LLV_LANG || "").toLowerCase();
+  if (explicit === "uk" || explicit === "en") return explicit;
+  const loc = (process.env.LC_ALL || process.env.LANG || "").toLowerCase();
+  return loc === "uk" || loc.startsWith("uk_") || loc.startsWith("uk.") ? "uk" : "en";
+}
+
+const LANG = detectLang();
+
+const MESSAGES = {
+  en: {
+    usage: () => `Usage: agent-log-viewer [options]
+
+Options:
+  -p, --port <n>       Port for the local server (default ${DEFAULT_PORT})
+  -H, --hostname <h>   Bind address (default ${DEFAULT_HOSTNAME})
+      --tailscale      Access over Tailscale
+      --no-open        Don't open the browser
+      --new-token      Create a new access key
+  -v, --version        Show the version
+  -h, --help           Show this help`,
+    badPort: (value) => `Invalid port: ${value}`,
+    flagNeedsValue: (flag) => `Option ${flag} requires a value.`,
+    hostnameNeedsValue: () => "Option --hostname requires a value.",
+    unknownOption: (arg) => `Unknown option: ${arg}`,
+    noPackageJson: () => "Couldn't find package.json for agent-log-viewer.",
+    readPackageJsonErr: (detail) => `Couldn't read package.json: ${detail}`,
+    readPackageJsonErrGeneric: () => "Couldn't read package.json.",
+    noServer: () => "No standalone server.js or local next found.",
+    portBusy: (port) => `Port ${port} is busy. Try: bunx agent-log-viewer --port ${port + 1}`,
+    serverStartFail: (detail) => `Couldn't start the server: ${detail}`,
+    serverTimeout: (seconds) => `The server didn't respond within ${seconds} seconds.`,
+    bannerOpened: (url) => `  Opened:    ${url}`,
+    bannerReads: () => "  Reads logs from ~/.claude/projects, ~/.codex/sessions.",
+    bannerStop: () => "  Ctrl+C — stop.  --tailscale — access from your phone.",
+    tsLinkWarn: () => "  The link contains an access key — don't forward it to others.",
+    tsCookie: () => "  After the first open the key is stored in a cookie for 30 days.",
+    nonLocalWarn: () => "Warning: a non-local address exposes the viewer to the network, so access-key mode is forced on.",
+    serverNotReady: () => "Server not ready.",
+  },
+  uk: {
+    usage: () => `Використання: agent-log-viewer [опції]
 
 Опції:
   -p, --port <n>       Порт для локального сервера (типово ${DEFAULT_PORT})
@@ -26,7 +68,32 @@ function usage() {
       --no-open        Не відкривати браузер
       --new-token      Створити новий ключ доступу
   -v, --version        Показати версію
-  -h, --help           Показати довідку`;
+  -h, --help           Показати довідку`,
+    badPort: (value) => `Некоректний порт: ${value}`,
+    flagNeedsValue: (flag) => `Опція ${flag} потребує значення.`,
+    hostnameNeedsValue: () => "Опція --hostname потребує значення.",
+    unknownOption: (arg) => `Невідома опція: ${arg}`,
+    noPackageJson: () => "Не вдалося знайти package.json для agent-log-viewer.",
+    readPackageJsonErr: (detail) => `Не вдалося прочитати package.json: ${detail}`,
+    readPackageJsonErrGeneric: () => "Не вдалося прочитати package.json.",
+    noServer: () => "Не знайдено standalone server.js або локальний next.",
+    portBusy: (port) => `Порт ${port} зайнятий. Спробуйте: bunx agent-log-viewer --port ${port + 1}`,
+    serverStartFail: (detail) => `Не вдалося запустити сервер: ${detail}`,
+    serverTimeout: (seconds) => `Сервер не відповів за ${seconds} секунд.`,
+    bannerOpened: (url) => `  Відкрито:  ${url}`,
+    bannerReads: () => "  Читає логи з ~/.claude/projects, ~/.codex/sessions.",
+    bannerStop: () => "  Ctrl+C — зупинити.  --tailscale — доступ з телефона.",
+    tsLinkWarn: () => "  Посилання містить ключ доступу — не пересилайте його стороннім.",
+    tsCookie: () => "  Після першого відкриття ключ зберігається у cookie на 30 днів.",
+    nonLocalWarn: () => "Увага: нелокальна адреса відкриває viewer для мережі, тому режим ключа доступу увімкнено примусово.",
+    serverNotReady: () => "Сервер не готовий.",
+  },
+};
+
+const m = MESSAGES[LANG];
+
+function usage() {
+  return m.usage();
 }
 
 function fail(message) {
@@ -37,7 +104,7 @@ function fail(message) {
 function parsePort(value) {
   const port = Number(value);
   if (!Number.isInteger(port) || port < 1 || port > 65_535) {
-    fail(`Некоректний порт: ${value}`);
+    fail(m.badPort(value));
   }
   return port;
 }
@@ -45,7 +112,7 @@ function parsePort(value) {
 function requireValue(args, index, flag) {
   const value = args[index + 1];
   if (!value || value.startsWith("-")) {
-    fail(`Опція ${flag} потребує значення.`);
+    fail(m.flagNeedsValue(flag));
   }
   return value;
 }
@@ -76,7 +143,7 @@ function parseArgs(args) {
     } else if (arg.startsWith("--hostname=")) {
       const value = arg.slice("--hostname=".length);
       if (!value) {
-        fail("Опція --hostname потребує значення.");
+        fail(m.hostnameNeedsValue());
       }
       options.hostname = value;
     } else if (arg === "--tailscale") {
@@ -90,7 +157,7 @@ function parseArgs(args) {
     } else if (arg === "-h" || arg === "--help") {
       options.help = true;
     } else {
-      fail(`Невідома опція: ${arg}`);
+      fail(m.unknownOption(arg));
     }
   }
 
@@ -112,7 +179,7 @@ function findPackageRoot(startDir) {
 
     const parentDir = dirname(currentDir);
     if (parentDir === currentDir) {
-      fail("Не вдалося знайти package.json для agent-log-viewer.");
+      fail(m.noPackageJson());
     }
     currentDir = parentDir;
   }
@@ -125,8 +192,8 @@ function readPackageJson(packageRoot) {
   } catch (error) {
     fail(
       error instanceof Error
-        ? `Не вдалося прочитати package.json: ${error.message}`
-        : "Не вдалося прочитати package.json.",
+        ? m.readPackageJsonErr(error.message)
+        : m.readPackageJsonErrGeneric(),
     );
   }
 }
@@ -154,7 +221,7 @@ function resolveServer(packageRoot) {
 
   const nextBin = join(packageRoot, "node_modules", ".bin", "next");
   if (!existsSync(nextBin)) {
-    fail("Не знайдено standalone server.js або локальний next.");
+    fail(m.noServer());
   }
 
   return {
@@ -204,7 +271,7 @@ function startServer(server, options, runtime, tailscaleProcessRef) {
     const text = chunk.toString("utf8");
     if (text.includes("EADDRINUSE")) {
       state.sawAddressInUse = true;
-      console.error(`Порт ${options.port} зайнятий. Спробуйте: bunx agent-log-viewer --port ${options.port + 1}`);
+      console.error(m.portBusy(options.port));
       if (!child.killed) {
         child.kill("SIGTERM");
       }
@@ -215,7 +282,7 @@ function startServer(server, options, runtime, tailscaleProcessRef) {
   });
 
   child.on("error", (error) => {
-    fail(`Не вдалося запустити сервер: ${error.message}`);
+    fail(m.serverStartFail(error.message));
   });
 
   child.on("exit", async (code, signal) => {
@@ -285,7 +352,7 @@ async function waitForReadiness(port) {
     await wait(READINESS_INTERVAL_MS);
   }
 
-  throw new Error(`Сервер не відповів за ${READINESS_TIMEOUT_MS / 1000} секунд.`);
+  throw new Error(m.serverTimeout(READINESS_TIMEOUT_MS / 1000));
 }
 
 function localUrl(options) {
@@ -295,9 +362,9 @@ function localUrl(options) {
 
 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 — доступ з телефона.");
+  console.log(m.bannerOpened(localUrl(options)));
+  console.log(m.bannerReads());
+  console.log(m.bannerStop());
 }
 
 async function printTailscaleBanner(runtime) {
@@ -314,8 +381,8 @@ async function printTailscaleBanner(runtime) {
       resolve();
     });
   });
-  console.log("  Посилання містить ключ доступу — не пересилайте його стороннім.");
-  console.log("  Після першого відкриття ключ зберігається у cookie на 30 днів.");
+  console.log(m.tsLinkWarn());
+  console.log(m.tsCookie());
 }
 
 function openBrowser(url) {
@@ -386,7 +453,7 @@ async function prepareRuntime(options) {
 
   const nonLoopbackBind = !isLoopbackHostname(options.hostname);
   if (nonLoopbackBind) {
-    console.error("Увага: нелокальна адреса відкриває viewer для мережі, тому режим ключа доступу увімкнено примусово.");
+    console.error(m.nonLocalWarn());
   }
 
   if (options.tailscale) {
@@ -436,7 +503,7 @@ async function main() {
   }
 
   if (await portAlreadyResponds(options.port)) {
-    console.error(`Порт ${options.port} зайнятий. Спробуйте: bunx agent-log-viewer --port ${options.port + 1}`);
+    console.error(m.portBusy(options.port));
     process.exit(1);
   }
 
@@ -453,7 +520,7 @@ async function main() {
     await waitForReadiness(options.port);
   } catch (error) {
     await stopAll(serverProcess, tailscaleProcessRef.current);
-    fail(error instanceof Error ? error.message : "Сервер не готовий.");
+    fail(error instanceof Error ? error.message : m.serverNotReady());
   }
 
   if (