@tonyclaw/llm-inspector 1.19.1 → 1.19.2

package/.output/server/index.mjs

@@ -35,110 +35,110 @@ const headers = ((m) => function headersRouteRule(event) {
   }
 });
 const assets = {
-  "/assets/CompareDrawer-DtERUdIt.js": {
+  "/assets/index-EvnsNPOK.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": '"4a1f-iUikoccqSI5dxDV/DitC+V4SyF4"',
-    "mtime": "2026-06-18T01:14:51.128Z",
+    "etag": '"74-Ttr2CWyviy8DiIX5gb9+i1f50ew"',
+    "mtime": "2026-06-18T08:23:57.371Z",
+    "size": 116,
+    "path": "../public/assets/index-EvnsNPOK.js"
+  },
+  "/assets/alibaba-TTwafVwX.svg": {
+    "type": "image/svg+xml",
+    "etag": '"171b-6dyV5K8QjiaY35sN9qNprh9zDIs"',
+    "mtime": "2026-06-18T08:23:57.367Z",
+    "size": 5915,
+    "path": "../public/assets/alibaba-TTwafVwX.svg"
+  },
+  "/assets/index-Bqi9RAGS.css": {
+    "type": "text/css; charset=utf-8",
+    "etag": '"177a9-QMoW/GsYu1jERI0JyFHA9CiB/o0"',
+    "mtime": "2026-06-18T08:23:57.371Z",
+    "size": 96169,
+    "path": "../public/assets/index-Bqi9RAGS.css"
+  },
+  "/assets/CompareDrawer-BzTsEelr.js": {
+    "type": "text/javascript; charset=utf-8",
+    "etag": '"4a1f-Qg1+Rt9EXNIgQdrNcwWDBW4GbSo"',
+    "mtime": "2026-06-18T08:23:57.371Z",
     "size": 18975,
-    "path": "../public/assets/CompareDrawer-DtERUdIt.js"
+    "path": "../public/assets/CompareDrawer-BzTsEelr.js"
   },
   "/assets/minimax-BPMzvuL-.jpeg": {
     "type": "image/jpeg",
     "etag": '"1b06-IwivU89ko5UTMUM1/t7hn4sQK9A"',
-    "mtime": "2026-06-18T01:14:51.128Z",
+    "mtime": "2026-06-18T08:23:57.370Z",
     "size": 6918,
     "path": "../public/assets/minimax-BPMzvuL-.jpeg"
   },
-  "/assets/index-B8ttyigz.js": {
+  "/assets/main-Br2EjrqZ.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": '"74-b0SfzNSVRwMMxI9rB/BBMzOdSls"',
-    "mtime": "2026-06-18T01:14:51.128Z",
-    "size": 116,
-    "path": "../public/assets/index-B8ttyigz.js"
+    "etag": '"50a37-vmFQ+AWLZBZB2He0hGozNaRNVJI"',
+    "mtime": "2026-06-18T08:23:57.371Z",
+    "size": 330295,
+    "path": "../public/assets/main-Br2EjrqZ.js"
   },
-  "/assets/json-viewer-CztuZ9cT.js": {
+  "/assets/json-viewer-DIHZbEId.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": '"1e651-ZXyBYCz6WZX+FFKagLcAEHfl5xM"',
-    "mtime": "2026-06-18T01:14:51.128Z",
+    "etag": '"1e651-45Abi6ZVH/q1l0aOWq20PEO9Tcg"',
+    "mtime": "2026-06-18T08:23:57.371Z",
     "size": 124497,
-    "path": "../public/assets/json-viewer-CztuZ9cT.js"
-  },
-  "/assets/index-DeJyypsp.css": {
-    "type": "text/css; charset=utf-8",
-    "etag": '"17504-zMXz49VysEK/ru01MvYLc8/SiPI"',
-    "mtime": "2026-06-18T01:14:51.128Z",
-    "size": 95492,
-    "path": "../public/assets/index-DeJyypsp.css"
+    "path": "../public/assets/json-viewer-DIHZbEId.js"
   },
-  "/assets/RequestAnatomy-Cx_vluvK.js": {
+  "/assets/RequestAnatomy-D-swiaii.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": '"142a-Yhymkf38kgBJoPDw4VNi/Dr6f+k"',
-    "mtime": "2026-06-18T01:14:51.128Z",
+    "etag": '"142a-gnEHcgfEHRgV0NMxY0iXIZHIAC0"',
+    "mtime": "2026-06-18T08:23:57.371Z",
     "size": 5162,
-    "path": "../public/assets/RequestAnatomy-Cx_vluvK.js"
+    "path": "../public/assets/RequestAnatomy-D-swiaii.js"
   },
-  "/assets/ResponseView-5F8Ms5z4.js": {
+  "/assets/ResponseView-DvdH2bGk.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": '"6e91-th7Dsd8aj+055p7AR8JrAwuhP30"',
-    "mtime": "2026-06-18T01:14:51.128Z",
+    "etag": '"6e91-Q4HU85yuyXxRWZzw+CnDW/vnjAo"',
+    "mtime": "2026-06-18T08:23:57.371Z",
     "size": 28305,
-    "path": "../public/assets/ResponseView-5F8Ms5z4.js"
+    "path": "../public/assets/ResponseView-DvdH2bGk.js"
   },
-  "/assets/StreamingChunkSequence-CKDCWfu9.js": {
+  "/assets/ReplayDialog-Dxxo80xO.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": '"d81-j+RBgIkb3QoxK8obtxQiGw8pId4"',
-    "mtime": "2026-06-18T01:14:51.128Z",
+    "etag": '"11c0-L7iZUpQjkDLpKkR+MgAZO1Q6ns8"',
+    "mtime": "2026-06-18T08:23:57.371Z",
+    "size": 4544,
+    "path": "../public/assets/ReplayDialog-Dxxo80xO.js"
+  },
+  "/assets/StreamingChunkSequence-D_RzgyKq.js": {
+    "type": "text/javascript; charset=utf-8",
+    "etag": '"d81-8i4/6r70kba84fXrnFFC/+/S8Sw"',
+    "mtime": "2026-06-18T08:23:57.371Z",
     "size": 3457,
-    "path": "../public/assets/StreamingChunkSequence-CKDCWfu9.js"
+    "path": "../public/assets/StreamingChunkSequence-D_RzgyKq.js"
   },
   "/assets/zhipuai-BPNAnxo-.svg": {
     "type": "image/svg+xml",
     "etag": '"2bf8-hNaLCTi89nOFCsIIfWpP/jrfo0s"',
-    "mtime": "2026-06-18T01:14:51.128Z",
+    "mtime": "2026-06-18T08:23:57.370Z",
     "size": 11256,
     "path": "../public/assets/zhipuai-BPNAnxo-.svg"
   },
-  "/assets/_sessionId-C-aKd1Ky.js": {
+  "/assets/_sessionId-DdODJCYY.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": '"d2-gL7mjPIXj+6BHz4XUVVdKjuvNDk"',
-    "mtime": "2026-06-18T01:14:51.128Z",
+    "etag": '"d2-f13W0xvGzYOxgV34bdQslyMj4WE"',
+    "mtime": "2026-06-18T08:23:57.371Z",
     "size": 210,
-    "path": "../public/assets/_sessionId-C-aKd1Ky.js"
-  },
-  "/assets/main-CR9IJlz1.js": {
-    "type": "text/javascript; charset=utf-8",
-    "etag": '"50a37-XeRUA7+G6lgGxJXRg+juq8ZZbMM"',
-    "mtime": "2026-06-18T01:14:51.128Z",
-    "size": 330295,
-    "path": "../public/assets/main-CR9IJlz1.js"
-  },
-  "/assets/alibaba-TTwafVwX.svg": {
-    "type": "image/svg+xml",
-    "etag": '"171b-6dyV5K8QjiaY35sN9qNprh9zDIs"',
-    "mtime": "2026-06-18T01:14:51.128Z",
-    "size": 5915,
-    "path": "../public/assets/alibaba-TTwafVwX.svg"
-  },
-  "/assets/ProxyViewerContainer-DfxRK7Nt.js": {
-    "type": "text/javascript; charset=utf-8",
-    "etag": '"76d0d-d2XlfO92n/Dltmn6NOHQY/Ui+fw"',
-    "mtime": "2026-06-18T01:14:51.128Z",
-    "size": 486669,
-    "path": "../public/assets/ProxyViewerContainer-DfxRK7Nt.js"
+    "path": "../public/assets/_sessionId-DdODJCYY.js"
   },
   "/assets/qwen-CONDcHqt.png": {
     "type": "image/png",
     "etag": '"572c3-cdJAPaHdOvFCGzuaQjagdgOu6XE"',
-    "mtime": "2026-06-18T01:14:51.128Z",
+    "mtime": "2026-06-18T08:23:57.371Z",
     "size": 357059,
     "path": "../public/assets/qwen-CONDcHqt.png"
   },
-  "/assets/ReplayDialog-VMsGnJSI.js": {
+  "/assets/ProxyViewerContainer-BHm-n-_W.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": '"11c0-t7Uuk+IRrGGdj7fX41f/Jt6J41I"',
-    "mtime": "2026-06-18T01:14:51.128Z",
-    "size": 4544,
-    "path": "../public/assets/ReplayDialog-VMsGnJSI.js"
+    "etag": '"76fed-fJVWNR0ZLTxGc3xnZxX5o1sFXvc"',
+    "mtime": "2026-06-18T08:23:57.371Z",
+    "size": 487405,
+    "path": "../public/assets/ProxyViewerContainer-BHm-n-_W.js"
   }
 };
 function readAsset(id) {

package/README.md

@@ -18,6 +18,7 @@
 - **Web UI**：`http://localhost:25947`
 - **Proxy**：`http://localhost:25947/proxy`
 - **MCP Server**：`http://localhost:25947/api/mcp`
+- **Chrome Companion**：`extensions/chrome`（通过 `chrome://extensions` 以 Load unpacked 方式加载）
 
 ## 核心能力
 
@@ -53,6 +54,8 @@ llm-inspector
 ```bash
 llm-inspector --no-open
 llm-inspector --port 3000
+llm-inspector --background
+llm-inspector --force-restart
 llm-inspector --config-dir ./local-config
 llm-inspector --providers '[{"name":"OpenAI","apiKey":"sk-...","models":["gpt-4o-mini"],"openaiBaseUrl":"https://api.openai.com/v1","authHeader":"bearer","createdAt":"2026-01-01T00:00:00.000Z","updatedAt":"2026-01-01T00:00:00.000Z","id":"demo"}]'
 ```
@@ -73,6 +76,23 @@ bun install
 bun run dev
 ```
 
+### Chrome Companion 扩展
+
+仓库内提供了一个轻量 Chrome 侧边栏扩展，用来连接本机 llm-inspector、查看运行状态和最近请求，并快速打开 Dashboard 或复制代理命令。
+
+```text
+extensions/chrome
+```
+
+启动方式：
+
+1. 先运行 `llm-inspector` 或 `bun run dev`。
+2. 打开 `chrome://extensions`。
+3. 开启 **Developer mode**。
+4. 点击 **Load unpacked**。
+5. 选择 `extensions/chrome` 目录。
+6. 点击扩展图标打开侧边栏。
+
 ## 配置 Provider
 
 打开 Web UI，进入 **Settings** 添加 Provider：
@@ -315,6 +335,8 @@ ANTHROPIC_BASE_URL=http://localhost:25947/proxy claude
 - [架构说明](docs/Architecture.md)
 - [开发指南](docs/Development.md)
 - [MCP Server](docs/MCP-Server.md)
+- [CHANGELOG](CHANGELOG.md) — release notes
+- [CONTRIBUTING](CONTRIBUTING.md) — how to land a change
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tonyclaw/llm-inspector",
-  "version": "1.19.1",
+  "version": "1.19.2",
   "type": "module",
   "description": "LLM API proxy inspector — captures and displays requests/responses from AI coding tools in a web UI",
   "license": "MIT",
@@ -40,6 +40,8 @@
     "lint": "eslint .",
     "format": "biome format --write .",
     "format:check": "biome format .",
+    "extension:zip": "node scripts/pack-chrome-extension.mjs",
+    "extension:release": "node scripts/release-chrome-extension.mjs",
     "knip": "knip",
     "check": "bun format && bun typecheck && bun lint",
     "prepare": "husky",

package/src/cli/detect-tools.ts

@@ -47,6 +47,7 @@ function which(bin: string): string | null {
       const out = execFileSync("where", [bin], {
         encoding: "utf8",
         timeout: 3000,
+        windowsHide: true,
         stdio: ["ignore", "pipe", "ignore"],
       });
       const first = out.split(/\r?\n/).find((line) => line.trim().length > 0);

package/src/cli/templates/skill-onboard.ts

@@ -257,15 +257,15 @@ New-Item -ItemType Directory -Force -Path $dir | Out-Null
 
 ## Phase 3: Start proxy
 
-**EXPLAIN:** "Time to start the proxy. It binds to port ${port} by default, kills any process already on that port, and prints the URL."
+**EXPLAIN:** "Time to start the proxy. It binds to port ${port} by default, reuses an already-running healthy llm-inspector, and prints the URL. Use \`--force-restart\` only when you intentionally want to replace the existing process."
 
 **DO:** Skip this phase entirely if the Phase 0 health check already reported \`PROXY: up\` and the user opted to skip done phases.
 
-**DO:** Otherwise, start the proxy in the background. On Windows, the npm shim is a \`.cmd\`/PowerShell file — \`Start-Process -FilePath "llm-inspector"\` returns "Invalid Win32 application" because Windows can't decide which shim to run. Use \`cmd /c start /B\` to background it through the cmd interpreter.
+**DO:** Otherwise, start the proxy with the explicit \`--background --no-open\` flags. On Windows, resolve the npm shim first and launch it through \`Start-Process -WindowStyle Hidden\` so setup does not flash a command window.
 
 \`\`\`bash
 # Unix / macOS / WSL
-nohup llm-inspector --no-open > /tmp/llm-inspector.log 2>&1 &
+llm-inspector --background --no-open > /tmp/llm-inspector.log 2>&1
 \`\`\`
 
 \`\`\`powershell
@@ -278,14 +278,14 @@ $err = Join-Path $env:TEMP 'llm-inspector.err.log'
 $found = Get-Command llm-inspector -ErrorAction SilentlyContinue
 if ($found) {
   $shim = $found.Source
-  $args = '--no-open'
+  $args = '--background','--no-open'
 } elseif (Test-Path (Join-Path $env:APPDATA 'npm/llm-inspector.cmd')) {
   $shim = Join-Path $env:APPDATA 'npm/llm-inspector.cmd'
-  $args = '--no-open'
+  $args = '--background','--no-open'
 } else {
   # bin not on PATH and not at the default npm prefix — let cmd resolve it
   $shim = 'cmd.exe'
-  $args = '/c','start','/B','llm-inspector','--no-open'
+  $args = '/c','llm-inspector','--background','--no-open'
 }
 Start-Process -FilePath $shim -ArgumentList $args -RedirectStandardOutput $log -RedirectStandardError $err -WindowStyle Hidden
 \`\`\`

package/src/cli.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
-import { spawn, execSync } from "node:child_process";
+import { spawn, execSync, type ChildProcess } from "node:child_process";
+import { createConnection } from "node:net";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { existsSync } from "node:fs";
@@ -8,6 +9,7 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
 const DEFAULT_PORT = 25947;
+const LOCAL_PROBE_TIMEOUT_MS = 2000;
 
 /**
  * Subcommand router. The legacy one-liner UX (`llm-inspector` with no args,
@@ -23,18 +25,107 @@ if (subcommand === "onboard") {
   process.exit(code);
 }
 
-runStart(process.argv.slice(2));
+await runStart(process.argv.slice(2));
 
 // -----------------------------------------------------------------------------
 // Legacy `start` behavior — start the proxy on the configured port. Extracted
 // into a function so the router above can keep the top-level flow readable.
 // -----------------------------------------------------------------------------
-function runStart(args: string[]): void {
+async function isInspectorHealthy(port: number): Promise<boolean> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), LOCAL_PROBE_TIMEOUT_MS);
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/api/health`, {
+      cache: "no-store",
+      signal: controller.signal,
+    });
+    return response.ok;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function isPortAcceptingConnections(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = createConnection({ host: "127.0.0.1", port });
+    const finish = (value: boolean): void => {
+      socket.removeAllListeners();
+      socket.destroy();
+      resolve(value);
+    };
+
+    socket.setTimeout(LOCAL_PROBE_TIMEOUT_MS);
+    socket.once("connect", () => finish(true));
+    socket.once("timeout", () => finish(false));
+    socket.once("error", () => finish(false));
+  });
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+async function waitForInspectorHealthy(port: number, timeoutMs: number): Promise<boolean> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (await isInspectorHealthy(port)) return true;
+    await sleep(250);
+  }
+  return false;
+}
+
+function openBrowser(targetUrl: string): void {
+  let command: string[] | undefined;
+  // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check
+  switch (process.platform) {
+    case "darwin":
+      command = ["open", targetUrl];
+      break;
+    case "linux":
+      command = ["xdg-open", targetUrl];
+      break;
+    case "win32":
+      command = ["cmd", "/c", "start", "", targetUrl];
+      break;
+    default:
+      // Unsupported platform - do nothing
+      break;
+  }
+  if (command === undefined) return;
+  const [bin, ...cmdArgs] = command;
+  if (bin === undefined) return;
+  const browserProcess = spawn(bin, cmdArgs, {
+    stdio: "ignore",
+    detached: true,
+    windowsHide: true,
+  });
+  browserProcess.unref();
+}
+
+function waitForProcessExit(child: ChildProcess): Promise<number> {
+  return new Promise((resolve) => {
+    child.once("exit", (code) => {
+      resolve(code ?? 1);
+    });
+    child.once("error", () => {
+      resolve(1);
+    });
+  });
+}
+
+async function runStart(args: string[]): Promise<void> {
   const envPort = process.env["PORT"];
   const portDefault = envPort !== undefined ? Number(envPort) : DEFAULT_PORT;
 
   let port = portDefault;
   let open = true;
+  let openWasSpecified = false;
+  let background = false;
+  let forceRestart = false;
   let configDir: string | undefined;
   let providersJson: string | undefined;
 
@@ -48,9 +139,18 @@ function runStart(args: string[]): void {
         break;
       case "--no-open":
         open = false;
+        openWasSpecified = true;
         break;
       case "--open":
         open = true;
+        openWasSpecified = true;
+        break;
+      case "--force-restart":
+      case "--restart":
+        forceRestart = true;
+        break;
+      case "--background":
+        background = true;
         break;
       case "--config-dir":
         configDir = args[i + 1];
@@ -65,6 +165,12 @@ function runStart(args: string[]): void {
     }
   }
 
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    console.error(`Invalid port: ${String(port)}. Use --port <1-65535>.`);
+    process.exitCode = 1;
+    return;
+  }
+
   /**
    * Check if a port is in use and kill the process using it
    */
@@ -79,6 +185,7 @@ function runStart(args: string[]): void {
         const output = execSync(`netstat -ano | findstr :${targetPort}`, {
           encoding: "utf8",
           timeout: 5000,
+          windowsHide: true,
         });
         const lines = output.trim().split("\n");
         for (const line of lines) {
@@ -99,8 +206,12 @@ function runStart(args: string[]): void {
 
         for (const pid of pids) {
           try {
-            console.log(`Killing process ${pid} on port ${port}...`);
-            execSync(`taskkill /PID ${pid} /F`, { encoding: "utf8", timeout: 5000 });
+            console.log(`Killing process ${pid} on port ${targetPort}...`);
+            execSync(`taskkill /PID ${pid} /F`, {
+              encoding: "utf8",
+              timeout: 5000,
+              windowsHide: true,
+            });
           } catch {
             // Process may have already exited
           }
@@ -120,7 +231,7 @@ function runStart(args: string[]): void {
 
         for (const pid of pids) {
           try {
-            console.log(`Killing process ${pid} on port ${port}...`);
+            console.log(`Killing process ${pid} on port ${targetPort}...`);
             execSync(`kill -9 ${pid}`, { encoding: "utf8", timeout: 5000 });
           } catch {
             // Process may have already exited
@@ -134,11 +245,28 @@ function runStart(args: string[]): void {
 
   process.env["PORT"] = String(port);
 
-  // Kill any existing process on the port
-  killProcessOnPort(port);
-
   const url = `http://localhost:${port}`;
 
+  if (!forceRestart && (await isInspectorHealthy(port))) {
+    console.log(`llm-inspector is already running at ${url}`);
+    console.log(`Use --force-restart to restart the existing instance.`);
+    if (open && openWasSpecified) {
+      openBrowser(url);
+    }
+    return;
+  }
+
+  if (!forceRestart && (await isPortAcceptingConnections(port))) {
+    console.error(`Port ${port} is already in use, but it is not a healthy llm-inspector.`);
+    console.error(`Stop that process, choose --port <n>, or re-run with --force-restart.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (forceRestart) {
+    killProcessOnPort(port);
+  }
+
   console.log(`Server running at ${url}`);
   console.log(`   Proxy: ${url}/proxy`);
   console.log(``);
@@ -157,29 +285,6 @@ function runStart(args: string[]): void {
     `   Example: ROUTES='{"claude-":"https://api.anthropic.com","MiniMax":"https://api.minimaxi.com/anthropic"}'`,
   );
 
-  const openBrowser = (targetUrl: string): void => {
-    let command: string[] | undefined;
-    // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check
-    switch (process.platform) {
-      case "darwin":
-        command = ["open", targetUrl];
-        break;
-      case "linux":
-        command = ["xdg-open", targetUrl];
-        break;
-      case "win32":
-        command = ["cmd", "/c", "start", targetUrl];
-        break;
-      default:
-        // Unsupported platform - do nothing
-        break;
-    }
-    if (command === undefined) return;
-    const [bin, ...cmdArgs] = command;
-    if (bin === undefined) return;
-    spawn(bin, cmdArgs, { stdio: "ignore", detached: true });
-  };
-
   if (open) {
     openBrowser(url);
   }
@@ -211,10 +316,22 @@ function runStart(args: string[]): void {
     serverEnv["LLM_INSPECTOR_PROVIDERS_JSON"] = providersJson;
   }
   const serverProcess = spawn(process.execPath, [serverPath], {
-    stdio: ["ignore", "inherit", "inherit"],
-    detached: true,
+    stdio: background ? ["ignore", "ignore", "ignore"] : "inherit",
+    detached: background,
     env: serverEnv,
+    windowsHide: background,
   });
 
-  serverProcess.unref();
+  if (background) {
+    serverProcess.unref();
+    if (await waitForInspectorHealthy(port, 5000)) {
+      console.log(`llm-inspector background server is ready at ${url}`);
+      return;
+    }
+    console.error(`llm-inspector background server did not become ready at ${url}.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  process.exitCode = await waitForProcessExit(serverProcess);
 }

package/src/components/ProxyViewerContainer.tsx

@@ -61,6 +61,8 @@ function filterLogs(
 }
 
 const DEBOUNCE_MS = 50;
+const HASH_SCROLL_ATTEMPTS = 12;
+const HASH_HIGHLIGHT_MS = 1800;
 
 function buildLogsStreamUrl(sessionId: string | undefined): string {
   if (sessionId === undefined) return "/api/logs/stream";
@@ -93,6 +95,7 @@ export function ProxyViewerContainer({
   const [error, setError] = useState<string | null>(null);
   const eventSourceRef = useRef<EventSource | null>(null);
   const reconnectTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const handledHashRef = useRef<string | null>(null);
 
   // O(1) log lookup by id
   const logIndexRef = useRef<Map<number, number>>(new Map());
@@ -214,6 +217,55 @@ export function ProxyViewerContainer({
     };
   }, [connectSSE]);
 
+  useEffect(() => {
+    const hash = window.location.hash;
+    if (!hash.startsWith("#log-")) return;
+    if (handledHashRef.current === hash) return;
+    const targetId = hash.slice(1);
+    let cancelled = false;
+    let attempts = 0;
+    let highlightedTarget: HTMLElement | null = null;
+    let highlightTimer: number | null = null;
+
+    const tryScrollToLog = (): void => {
+      if (cancelled) return;
+      const target = document.getElementById(targetId);
+      if (target !== null) {
+        handledHashRef.current = hash;
+        target.scrollIntoView({ block: "center", behavior: "smooth" });
+        if (target instanceof HTMLElement) {
+          highlightedTarget = target;
+          target.setAttribute("data-deep-link-highlight", "true");
+          highlightTimer = window.setTimeout(() => {
+            target.removeAttribute("data-deep-link-highlight");
+          }, HASH_HIGHLIGHT_MS);
+          target.focus({ preventScroll: true });
+          if (target.getAttribute("data-nav-action") === "expand") {
+            target.click();
+          }
+        }
+        return;
+      }
+
+      attempts += 1;
+      if (attempts < HASH_SCROLL_ATTEMPTS) {
+        window.setTimeout(tryScrollToLog, 100);
+      }
+    };
+
+    tryScrollToLog();
+
+    return () => {
+      cancelled = true;
+      if (highlightTimer !== null) {
+        window.clearTimeout(highlightTimer);
+      }
+      if (highlightedTarget !== null) {
+        highlightedTarget.removeAttribute("data-deep-link-highlight");
+      }
+    };
+  }, [logs.length]);
+
   const handleClearAll = useCallback(() => {
     if (initialSessionId !== undefined && allLogs.length === 0) return;
     void (async () => {

package/src/components/proxy-viewer/LogEntryHeader.tsx

@@ -151,6 +151,7 @@ export const LogEntryHeader = memo(function ({
   return (
     <TooltipProvider>
       <div
+        id={`log-${log.id}`}
         role="button"
         tabIndex={0}
         data-nav-id={`log-${log.id}`}