agenthud 0.10.0 → 0.11.0

package/README.md

@@ -6,7 +6,7 @@
 
 An observability layer for [Claude Code](https://github.com/anthropics/claude-code). **See** your live sessions, **export** structured activity logs, and **summarize** a day or a week into an LLM digest — all from one CLI.
 
-![demo](./output960.gif)
+![demo](./demo/live.gif)
 
 AgentHUD reads Claude Code's session files from `~/.claude/projects/` and gives you three things:
 
@@ -134,7 +134,8 @@ When tracking is on, the tree panel's title shows `[LIVE ⠧]` and the status ba
 
 | Key | Action |
 |-----|--------|
-| `↑` / `k` / `↓` / `j` | Scroll |
+| `↑` / `k` / `↓` / `j` | Scroll one line |
+| `Ctrl+U` / `Ctrl+D` | Half page up / down |
 | `↵` / `Esc` / `q` | Close |
 
 Detail view colors the content based on activity type:

package/dist/index.js

@@ -15,4 +15,4 @@ Error: Node.js ${MIN_NODE_VERSION}+ is required (current: ${process.version})
   process.exit(1);
 }
 if (!process.env.NODE_ENV) process.env.NODE_ENV = "production";
-import("./main-HPL3AG6B.js");
+import("./main-KTFHI6KH.js");

package/dist/{main-HPL3AG6B.js → main-KTFHI6KH.js}

@@ -1,24 +1,14 @@
 // src/main.ts
-import { existsSync as existsSync6, rmSync } from "fs";
+import { existsSync as existsSync6, readdirSync as readdirSync2, realpathSync, rmSync } from "fs";
 import { homedir as homedir5 } from "os";
 import { join as join6 } from "path";
 import { createInterface as createInterface2 } from "readline";
-
-// src/utils/legacyConfig.ts
-import { join, resolve } from "path";
-function isLegacyProjectConfig(cwd, home) {
-  const legacy = resolve(join(cwd, ".agenthud", "config.yaml"));
-  const global = resolve(join(home, ".agenthud", "config.yaml"));
-  return legacy !== global;
-}
-
-// src/main.ts
 import { render } from "ink";
 import React from "react";
 
 // src/cli.ts
 import { readFileSync } from "fs";
-import { dirname, join as join2 } from "path";
+import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 var ALL_TYPES = [
   "response",
@@ -37,7 +27,8 @@ var KNOWN_WATCH_FLAGS = /* @__PURE__ */ new Set([
   "-V",
   "--version",
   "-h",
-  "--help"
+  "--help",
+  "--cwd"
 ]);
 var KNOWN_REPORT_FLAGS = /* @__PURE__ */ new Set([
   "--date",
@@ -66,6 +57,9 @@ Monitors all running Claude Code sessions in real-time.
 Options:
   -w, --watch                   Watch mode (default) \u2014 live updates
   --once                        Print once and exit
+  --cwd                         Scope the view to the Claude project
+                                containing the current directory.
+                                Exits 1 if no such project is found.
   -V, --version                 Show version number
   -h, --help                    Show this help message
 
@@ -103,7 +97,7 @@ Config: ~/.agenthud/config.yaml
 function getVersion() {
   const __dirname2 = dirname(fileURLToPath(import.meta.url));
   const packageJson = JSON.parse(
-    readFileSync(join2(__dirname2, "..", "package.json"), "utf-8")
+    readFileSync(join(__dirname2, "..", "package.json"), "utf-8")
   );
   return packageJson.version;
 }
@@ -144,7 +138,7 @@ function parseArgs(args) {
     return { mode: "watch", command: "version" };
   }
   if (args.includes("--once")) {
-    return { mode: "once" };
+    return args.includes("--cwd") ? { mode: "once", scopeToCwd: true } : { mode: "once" };
   }
   if (args[0] === "report") {
     const rest = args.slice(1);
@@ -367,54 +361,16 @@ function parseArgs(args) {
       };
     }
   }
-  return { mode: "watch" };
-}
-
-// src/utils/altScreen.ts
-var ENTER = "\x1B[?1049h";
-var LEAVE = "\x1B[?1049l";
-var entered = false;
-var left = false;
-function enterAltScreen() {
-  if (entered) return;
-  entered = true;
-  process.stdout.write(ENTER);
-}
-function leaveAltScreen() {
-  if (left || !entered) return;
-  left = true;
-  process.stdout.write(LEAVE);
-}
-var hooksInstalled = false;
-function installAltScreenCleanup() {
-  if (hooksInstalled) return;
-  hooksInstalled = true;
-  process.on("exit", () => {
-    leaveAltScreen();
-  });
-  process.on("SIGINT", () => {
-    leaveAltScreen();
-    process.exit(130);
-  });
-  process.on("SIGTERM", () => {
-    leaveAltScreen();
-    process.exit(143);
-  });
-  process.on("uncaughtException", (err) => {
-    leaveAltScreen();
-    setImmediate(() => {
-      throw err;
-    });
-  });
+  return args.includes("--cwd") ? { mode: "watch", scopeToCwd: true } : { mode: "watch" };
 }
 
 // src/config/globalConfig.ts
 import { existsSync, mkdirSync, readFileSync as readFileSync2, writeFileSync } from "fs";
 import { homedir } from "os";
-import { join as join3 } from "path";
+import { join as join2 } from "path";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
-var CONFIG_PATH = join3(homedir(), ".agenthud", "config.yaml");
-var STATE_PATH = join3(homedir(), ".agenthud", "state.yaml");
+var CONFIG_PATH = join2(homedir(), ".agenthud", "config.yaml");
+var STATE_PATH = join2(homedir(), ".agenthud", "state.yaml");
 var DEFAULT_GLOBAL_CONFIG = {
   refreshIntervalMs: 2e3,
   hiddenSessions: [],
@@ -436,7 +392,7 @@ function parseInterval(value) {
   return match[2] === "m" ? n * 60 * 1e3 : n * 1e3;
 }
 function ensureAgenthudDir() {
-  const dir = join3(homedir(), ".agenthud");
+  const dir = join2(homedir(), ".agenthud");
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
 }
 function writeDefaultConfig() {
@@ -604,8 +560,8 @@ function hideProject(name) {
   updateState({ hiddenProjects: [...config.hiddenProjects, name] });
 }
 function hasProjectLevelConfig() {
-  const candidate = join3(process.cwd(), ".agenthud", "config.yaml");
-  if (candidate === join3(homedir(), ".agenthud", "config.yaml")) return false;
+  const candidate = join2(process.cwd(), ".agenthud", "config.yaml");
+  if (candidate === join2(homedir(), ".agenthud", "config.yaml")) return false;
   return existsSync(candidate);
 }
 
@@ -643,7 +599,7 @@ function getCommitDetail(projectPath, hash) {
   if (!projectPath) return null;
   try {
     return execSync(
-      `git --git-dir="${projectPath}/.git" show --stat --patch --no-color ${hash}`,
+      `git -C "${projectPath}" show --stat --patch --no-color ${hash}`,
       { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }
     ).trim();
   } catch {
@@ -657,7 +613,7 @@ function parseGitCommits(projectPath, startDate, endDate) {
   let raw;
   try {
     raw = execSync(
-      `git --git-dir="${projectPath}/.git" log --format="%ct|%h|%s" --after="${start} 00:00:00" --before="${end} 23:59:59"`,
+      `git -C "${projectPath}" log --format="%ct|%h|%s" --after="${start} 00:00:00" --before="${end} 23:59:59"`,
       { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }
     ).trim();
   } catch {
@@ -769,11 +725,24 @@ function summarizeToolDetail(name, input, result) {
   }
   return getToolDetail(name, input);
 }
+function numberLines(content, start) {
+  const lines = content.split("\n");
+  if (lines.length > 1 && lines[lines.length - 1] === "") lines.pop();
+  const width = String(start + lines.length - 1).length;
+  return lines.map((line, i) => `${String(start + i).padStart(width)}: ${line}`).join("\n");
+}
 function buildToolDetailBody(name, input, result) {
   if (name === "Write") {
     const content = result?.content ?? input?.content;
     if (content) return { text: content, kind: "code" };
   }
+  if (name === "Read") {
+    const content = result?.file?.content;
+    if (content) {
+      const start = result?.file?.startLine ?? input?.offset ?? 1;
+      return { text: numberLines(content, start), kind: "code", numbered: true };
+    }
+  }
   if (name === "Edit" || name === "Write") {
     const hunks = result?.structuredPatch;
     if (hunks && hunks.length > 0) {
@@ -893,6 +862,7 @@ function parseActivitiesFromLines(lines) {
               if (body) {
                 entry2.detailBody = body.text;
                 entry2.detailKind = body.kind;
+                if (body.numbered) entry2.detailNumbered = true;
               }
               activities.push(entry2);
             }
@@ -1062,25 +1032,10 @@ function generateReport(sessions, options2) {
   return lines.join("\n").trimEnd();
 }
 
-// src/data/summaryRunner.ts
-import { spawn } from "child_process";
-import {
-  copyFileSync,
-  createWriteStream,
-  existsSync as existsSync4,
-  mkdirSync as mkdirSync2,
-  readFileSync as readFileSync5,
-  unlinkSync
-} from "fs";
-import { homedir as homedir3 } from "os";
-import { dirname as dirname2, join as join5 } from "path";
-import { createInterface } from "readline";
-import { fileURLToPath as fileURLToPath2 } from "url";
-
 // src/data/sessions.ts
 import { existsSync as existsSync3, readdirSync, readFileSync as readFileSync4, statSync as statSync2 } from "fs";
 import { homedir as homedir2 } from "os";
-import { basename as basename2, join as join4 } from "path";
+import { basename as basename2, join as join3 } from "path";
 
 // src/ui/constants.ts
 import stringWidth from "string-width";
@@ -1170,7 +1125,7 @@ function detectLiveState(tailLines, mtimeMs, now) {
 
 // src/data/sessions.ts
 function getProjectsDir() {
-  return process.env.CLAUDE_PROJECTS_DIR ?? join4(homedir2(), ".claude", "projects");
+  return process.env.CLAUDE_PROJECTS_DIR ?? join3(homedir2(), ".claude", "projects");
 }
 function decodeProjectPath(encoded) {
   const windowsDriveMatch = encoded.match(/^([A-Za-z])--(.*)$/);
@@ -1307,7 +1262,7 @@ function readEntrypoint(filePath) {
   }
 }
 function buildSubAgents(parentId, projectDir, config, projectName) {
-  const subagentsDir = join4(projectDir, parentId, "subagents");
+  const subagentsDir = join3(projectDir, parentId, "subagents");
   if (!existsSync3(subagentsDir)) return [];
   let files;
   try {
@@ -1320,7 +1275,7 @@ function buildSubAgents(parentId, projectDir, config, projectName) {
   return files.map((file) => {
     const id = file.replace(/\.jsonl$/, "");
     const hideKey = `${projectName}/${id}`;
-    const filePath = join4(subagentsDir, file);
+    const filePath = join3(subagentsDir, file);
     try {
       const stat = statSync2(filePath);
       const { agentId, taskDescription } = readSubAgentInfo(filePath);
@@ -1352,7 +1307,36 @@ function buildSubAgents(parentId, projectDir, config, projectName) {
     (n) => n !== null && !config.hiddenSubAgents.includes(n.hideKey)
   ).sort((a, b) => b.lastModifiedMs - a.lastModifiedMs);
 }
-function discoverSessions(config) {
+function findContainingProject(cwd, projectPaths, options2) {
+  const resolve2 = options2?.realpath ?? ((p) => p);
+  const cwdR = resolve2(cwd);
+  let best = null;
+  let bestLen = -1;
+  for (const raw of projectPaths) {
+    let pR;
+    try {
+      pR = resolve2(raw);
+    } catch {
+      continue;
+    }
+    if (cwdR === pR) {
+      if (pR.length > bestLen) {
+        best = raw;
+        bestLen = pR.length;
+      }
+      continue;
+    }
+    const boundary = cwdR[pR.length];
+    if ((boundary === "/" || boundary === "\\") && cwdR.startsWith(pR)) {
+      if (pR.length > bestLen) {
+        best = raw;
+        bestLen = pR.length;
+      }
+    }
+  }
+  return best;
+}
+function discoverSessions(config, options2) {
   const projectsDir = getProjectsDir();
   if (!existsSync3(projectsDir)) {
     return {
@@ -1366,7 +1350,7 @@ function discoverSessions(config) {
   try {
     projectDirs = readdirSync(projectsDir).filter((entry) => {
       try {
-        return statSync2(join4(projectsDir, entry)).isDirectory();
+        return statSync2(join3(projectsDir, entry)).isDirectory();
       } catch {
         return false;
       }
@@ -1380,9 +1364,11 @@ function discoverSessions(config) {
     };
   }
   const allSessions = [];
+  const scope = options2?.scopeToProject ?? null;
   for (const encodedDir of projectDirs) {
-    const projectDir = join4(projectsDir, encodedDir);
+    const projectDir = join3(projectsDir, encodedDir);
     const decodedPath = decodeProjectPath(encodedDir);
+    if (scope !== null && decodedPath !== scope) continue;
     const projectName = basename2(decodedPath);
     let files;
     try {
@@ -1395,7 +1381,7 @@ function discoverSessions(config) {
     for (const file of files) {
       const id = file.replace(/\.jsonl$/, "");
       const hideKey = `${projectName}/${id}`;
-      const filePath = join4(projectDir, file);
+      const filePath = join3(projectDir, file);
       try {
         const stat = statSync2(filePath);
         const subAgents = buildSubAgents(id, projectDir, config, projectName);
@@ -1473,13 +1459,26 @@ function discoverSessions(config) {
 }
 
 // src/data/summaryRunner.ts
+import { spawn } from "child_process";
+import {
+  copyFileSync,
+  createWriteStream,
+  existsSync as existsSync4,
+  mkdirSync as mkdirSync2,
+  readFileSync as readFileSync5,
+  unlinkSync
+} from "fs";
+import { homedir as homedir3 } from "os";
+import { dirname as dirname2, join as join4 } from "path";
+import { createInterface } from "readline";
+import { fileURLToPath as fileURLToPath2 } from "url";
 function agenthudHomeDir() {
-  const dir = join5(homedir3(), ".agenthud");
+  const dir = join4(homedir3(), ".agenthud");
   if (!existsSync4(dir)) mkdirSync2(dir, { recursive: true });
   return dir;
 }
 function summariesDir() {
-  const dir = join5(agenthudHomeDir(), "summaries");
+  const dir = join4(agenthudHomeDir(), "summaries");
   if (!existsSync4(dir)) mkdirSync2(dir, { recursive: true });
   return dir;
 }
@@ -1487,20 +1486,20 @@ function promptFilename(kind) {
   return kind === "daily" ? "summary-prompt.md" : "summary-range-prompt.md";
 }
 function userPromptPath(kind) {
-  return join5(homedir3(), ".agenthud", promptFilename(kind));
+  return join4(homedir3(), ".agenthud", promptFilename(kind));
 }
 function templatePath(kind) {
   const here = dirname2(fileURLToPath2(import.meta.url));
-  return join5(here, "templates", promptFilename(kind));
+  return join4(here, "templates", promptFilename(kind));
 }
 function dateKey(d) {
   return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
 }
 function dailyCachePath(date) {
-  return join5(summariesDir(), `${dateKey(date)}.md`);
+  return join4(summariesDir(), `${dateKey(date)}.md`);
 }
 function rangeCachePath(from, to) {
-  return join5(summariesDir(), `range-${dateKey(from)}_${dateKey(to)}.md`);
+  return join4(summariesDir(), `range-${dateKey(from)}_${dateKey(to)}.md`);
 }
 function isSameLocalDay2(a, b) {
   return a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth() && a.getDate() === b.getDate();
@@ -1959,6 +1958,7 @@ agenthud: combining ${dailyMarkdowns.length} daily summaries into range summary.
 
 // src/ui/App.tsx
 import { existsSync as existsSync5, watch } from "fs";
+import { basename as basename3 } from "path";
 import { Box as Box5, Text as Text5, useApp, useInput, useStdout } from "ink";
 import { useCallback, useEffect as useEffect3, useMemo, useRef, useState as useState3 } from "react";
 
@@ -2255,8 +2255,31 @@ function getLineStyle(category) {
 }
 
 // src/ui/DetailViewPanel.tsx
-import { jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
-function wrapClassified(text, maxWidth, classifier) {
+import { Fragment as Fragment2, jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
+function splitLineNumberGutter(text) {
+  const m = text.match(/^(\s*\d+: )(.*)$/);
+  return m ? [m[1], m[2]] : null;
+}
+function hardWrapByWidth(line, maxWidth) {
+  if (maxWidth <= 0) return [line];
+  const out = [];
+  let cur = "";
+  let curW = 0;
+  for (const ch of line) {
+    const w = getDisplayWidth(ch);
+    if (curW + w > maxWidth && cur !== "") {
+      out.push(cur);
+      cur = ch;
+      curW = w;
+    } else {
+      cur += ch;
+      curW += w;
+    }
+  }
+  if (cur !== "") out.push(cur);
+  return out.length > 0 ? out : [line];
+}
+function wrapClassified(text, maxWidth, classifier, preserveWhitespace = false) {
   if (!text) return [{ text: "(empty)", category: "prose" }];
   const sourceLines = text.split("\n");
   const categories = classifier(sourceLines);
@@ -2268,6 +2291,12 @@ function wrapClassified(text, maxWidth, classifier) {
       out.push({ text: "", category: cat });
       continue;
     }
+    if (preserveWhitespace) {
+      for (const chunk of hardWrapByWidth(line, maxWidth)) {
+        out.push({ text: chunk, category: cat });
+      }
+      continue;
+    }
     const words = line.split(" ");
     let current = "";
     for (const word of words) {
@@ -2294,7 +2323,13 @@ function DetailViewPanel({
   const contentWidth = innerWidth - 1;
   const body = activity.detailBody ?? activity.detail;
   const classifier = activity.detailKind === "diff" ? classifyDiffLines : activity.detailKind === "code" ? classifyCodeFences : activity.type === "commit" ? classifyDiffLines : classifyCodeFences;
-  const allLines = wrapClassified(body, contentWidth, classifier);
+  const preserveWhitespace = activity.detailKind === "diff" || activity.detailKind === "code" || activity.type === "commit";
+  const allLines = wrapClassified(
+    body,
+    contentWidth,
+    classifier,
+    preserveWhitespace
+  );
   const totalLines = allLines.length;
   const clampedOffset = Math.min(
     scrollOffset,
@@ -2321,11 +2356,15 @@ function DetailViewPanel({
     const entry = visibleSlice[i] ?? { text: "", category: "prose" };
     const padding = Math.max(0, contentWidth - getDisplayWidth(entry.text));
     const lineStyle = getLineStyle(entry.category);
+    const gutterSplit = activity.detailNumbered ? splitLineNumberGutter(entry.text) : null;
     contentRows.push(
       /* @__PURE__ */ jsxs2(Text2, { children: [
         BOX.v,
         " ",
-        /* @__PURE__ */ jsx2(Text2, { color: lineStyle.color, dimColor: lineStyle.dimColor, children: entry.text }),
+        gutterSplit ? /* @__PURE__ */ jsxs2(Fragment2, { children: [
+          /* @__PURE__ */ jsx2(Text2, { dimColor: true, children: gutterSplit[0] }),
+          /* @__PURE__ */ jsx2(Text2, { color: lineStyle.color, dimColor: lineStyle.dimColor, children: gutterSplit[1] })
+        ] }) : /* @__PURE__ */ jsx2(Text2, { color: lineStyle.color, dimColor: lineStyle.dimColor, children: entry.text }),
         " ".repeat(padding),
         BOX.v
       ] }, i)
@@ -2497,6 +2536,8 @@ function useHotkeys({
   onDetailClose,
   onDetailScrollUp,
   onDetailScrollDown,
+  onDetailScrollHalfPageUp,
+  onDetailScrollHalfPageDown,
   onFilter,
   onHelp,
   onHelpScroll,
@@ -2544,6 +2585,14 @@ function useHotkeys({
       return;
     }
     if (detailMode) {
+      if (key.ctrl && input === "u") {
+        onDetailScrollHalfPageUp();
+        return;
+      }
+      if (key.ctrl && input === "d") {
+        onDetailScrollHalfPageDown();
+        return;
+      }
       if (key.upArrow || input === "k") {
         onDetailScrollUp();
         return;
@@ -2642,7 +2691,7 @@ function useHotkeys({
     }
   };
   const trackingItems = trackingOn ? ["TRK \u25CF"] : ["t: track"];
-  const statusBarItems = helpMode ? ["\u2191\u2193/jk: scroll", "PgDn/Space: page", "\u21B5/Esc/q/?: close"] : detailMode ? ["\u2191\u2193/jk: scroll", "\u21B5/Esc: close", "?: help"] : focus === "tree" ? [
+  const statusBarItems = helpMode ? ["\u2191\u2193/jk: scroll", "PgDn/Space: page", "\u21B5/Esc/q/?: close"] : detailMode ? ["\u2191\u2193/jk: scroll", "C-u/d: \xBDpage", "\u21B5/Esc: close", "?: help"] : focus === "tree" ? [
     ...trackingItems,
     "Tab: viewer",
     "\u2191\u2193/jk: select",
@@ -2667,24 +2716,12 @@ function useHotkeys({
   return { handleInput, statusBarItems };
 }
 
-// src/ui/hooks/useTick.ts
-import { useEffect, useState } from "react";
-function useTick(active, intervalMs = 100) {
-  const [n, setN] = useState(0);
-  useEffect(() => {
-    if (!active) return;
-    const id = setInterval(() => setN((x) => x + 1), intervalMs);
-    return () => clearInterval(id);
-  }, [active, intervalMs]);
-  return n;
-}
-
 // src/ui/hooks/useSpinner.ts
-import { useEffect as useEffect2, useState as useState2 } from "react";
+import { useEffect, useState } from "react";
 var FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
 function useSpinner(active, intervalMs = 100) {
-  const [index, setIndex] = useState2(0);
-  useEffect2(() => {
+  const [index, setIndex] = useState(0);
+  useEffect(() => {
     if (!active) return;
     const timer = setInterval(() => {
       setIndex((i) => (i + 1) % FRAMES.length);
@@ -2694,10 +2731,22 @@ function useSpinner(active, intervalMs = 100) {
   return active ? FRAMES[index] : "";
 }
 
+// src/ui/hooks/useTick.ts
+import { useEffect as useEffect2, useState as useState2 } from "react";
+function useTick(active, intervalMs = 100) {
+  const [n, setN] = useState2(0);
+  useEffect2(() => {
+    if (!active) return;
+    const id = setInterval(() => setN((x) => x + 1), intervalMs);
+    return () => clearInterval(id);
+  }, [active, intervalMs]);
+  return n;
+}
+
 // src/ui/SessionTreePanel.tsx
 import { homedir as homedir4 } from "os";
 import { Box as Box4, Text as Text4 } from "ink";
-import { Fragment as Fragment2, jsx as jsx4, jsxs as jsxs4 } from "react/jsx-runtime";
+import { Fragment as Fragment3, jsx as jsx4, jsxs as jsxs4 } from "react/jsx-runtime";
 function formatElapsed(lastModifiedMs, now = Date.now()) {
   const elapsed = Math.max(0, now - lastModifiedMs);
   const seconds = Math.floor(elapsed / 1e3);
@@ -2921,7 +2970,7 @@ function ProjectRow({
         dimColor: muted,
         children: [
           nameText,
-          pathText ? /* @__PURE__ */ jsxs4(Fragment2, { children: [
+          pathText ? /* @__PURE__ */ jsxs4(Fragment3, { children: [
             "  ",
             /* @__PURE__ */ jsx4(Text4, { dimColor: true, children: pathText })
           ] }) : null,
@@ -2998,12 +3047,14 @@ function SessionTreePanel({
   maxRows,
   expandedIds = /* @__PURE__ */ new Set(),
   trackingOn = false,
-  spinner = ""
+  spinner = "",
+  scopeLabel
 }) {
   const innerWidth = getInnerWidth(width);
   const contentWidth = innerWidth - 1;
   const titleSuffix = trackingOn ? `[LIVE ${spinner || "\u25BC"}]` : "";
-  const titleLine = createTitleLine("Projects", titleSuffix, width);
+  const titleText = scopeLabel ? `Projects [${scopeLabel}]` : "Projects";
+  const titleLine = createTitleLine(titleText, titleSuffix, width);
   const bottomLine = createBottomLine(width);
   const totalProjectCount = projects.length + coldProjects.length;
   if (totalProjectCount === 0) {
@@ -3097,7 +3148,7 @@ function SessionTreePanel({
 }
 
 // src/ui/App.tsx
-import { Fragment as Fragment3, jsx as jsx5, jsxs as jsxs5 } from "react/jsx-runtime";
+import { Fragment as Fragment4, jsx as jsx5, jsxs as jsxs5 } from "react/jsx-runtime";
 var VIEWER_HEIGHT_FRACTION = 0.55;
 function subSummarySentinel(parentId) {
   return {
@@ -3249,14 +3300,21 @@ function collectAllIds(tree) {
   }
   return ids;
 }
-function App({ mode }) {
+function App({
+  mode,
+  scopeToProject: scopeToProject2
+}) {
   const { exit } = useApp();
   const { stdout } = useStdout();
   const isWatchMode = mode === "watch";
   const config = useMemo(() => loadGlobalConfig(), []);
   const migrationWarning = useMemo(() => hasProjectLevelConfig(), []);
+  const discoverOptions = useMemo(
+    () => scopeToProject2 ? { scopeToProject: scopeToProject2 } : void 0,
+    [scopeToProject2]
+  );
   const [sessionTree, setSessionTree] = useState3(
-    () => discoverSessions(config)
+    () => discoverSessions(config, discoverOptions)
   );
   const [selectedId, setSelectedId] = useState3(() => {
     const firstProject = sessionTree.projects[0];
@@ -3364,7 +3422,7 @@ function App({ mode }) {
   }, [selectedId, isWatchMode]);
   const refresh = useCallback(() => {
     const freshConfig = loadGlobalConfig();
-    const tree = discoverSessions(freshConfig);
+    const tree = discoverSessions(freshConfig, discoverOptions);
     const updatedFlat = flattenSessions2(tree, expandedIds);
     let nextSelected = selectedId;
     if (tracking) {
@@ -3396,7 +3454,7 @@ function App({ mode }) {
       setScrollOffset((o) => o + delta);
       setNewCount((n) => n + delta);
     }
-  }, [selectedId, isLive, expandedIds, tracking]);
+  }, [selectedId, isLive, expandedIds, tracking, discoverOptions]);
   const refreshRef = useRef(refresh);
   useEffect3(() => {
     refreshRef.current = refresh;
@@ -3629,6 +3687,14 @@ function App({ mode }) {
     onDetailScrollDown: () => {
       setDetailScrollOffset((o) => o + 1);
     },
+    onDetailScrollHalfPageUp: () => {
+      const step = Math.max(1, Math.floor(viewerRows / 2));
+      setDetailScrollOffset((o) => Math.max(0, o - step));
+    },
+    onDetailScrollHalfPageDown: () => {
+      const step = Math.max(1, Math.floor(viewerRows / 2));
+      setDetailScrollOffset((o) => o + step);
+    },
     onEnter: () => {
       if (focus === "viewer") {
         const act = getSelectedActivity(
@@ -3838,7 +3904,7 @@ function App({ mode }) {
           helpTotalLinesRef.current = n;
         }
       }
-    ) : /* @__PURE__ */ jsxs5(Fragment3, { children: [
+    ) : /* @__PURE__ */ jsxs5(Fragment4, { children: [
       migrationWarning && /* @__PURE__ */ jsx5(Box5, { marginBottom: 1, children: /* @__PURE__ */ jsx5(Text5, { color: "yellow", children: "Config moved to ~/.agenthud/config.yaml" }) }),
       /* @__PURE__ */ jsx5(
         SessionTreePanel,
@@ -3851,7 +3917,8 @@ function App({ mode }) {
           maxRows: treeRows,
           expandedIds,
           trackingOn: tracking,
-          spinner
+          spinner,
+          scopeLabel: scopeToProject2 ? basename3(scopeToProject2) : void 0
         }
       ),
       /* @__PURE__ */ jsx5(Box5, { marginTop: 1, children: detailMode && detailActivity ? /* @__PURE__ */ jsx5(
@@ -3885,6 +3952,52 @@ function App({ mode }) {
   ] });
 }
 
+// src/utils/altScreen.ts
+var ENTER = "\x1B[?1049h";
+var LEAVE = "\x1B[?1049l";
+var entered = false;
+var left = false;
+function enterAltScreen() {
+  if (entered) return;
+  entered = true;
+  process.stdout.write(ENTER);
+}
+function leaveAltScreen() {
+  if (left || !entered) return;
+  left = true;
+  process.stdout.write(LEAVE);
+}
+var hooksInstalled = false;
+function installAltScreenCleanup() {
+  if (hooksInstalled) return;
+  hooksInstalled = true;
+  process.on("exit", () => {
+    leaveAltScreen();
+  });
+  process.on("SIGINT", () => {
+    leaveAltScreen();
+    process.exit(130);
+  });
+  process.on("SIGTERM", () => {
+    leaveAltScreen();
+    process.exit(143);
+  });
+  process.on("uncaughtException", (err) => {
+    leaveAltScreen();
+    setImmediate(() => {
+      throw err;
+    });
+  });
+}
+
+// src/utils/legacyConfig.ts
+import { join as join5, resolve } from "path";
+function isLegacyProjectConfig(cwd, home) {
+  const legacy = resolve(join5(cwd, ".agenthud", "config.yaml"));
+  const global = resolve(join5(home, ".agenthud", "config.yaml"));
+  return legacy !== global;
+}
+
 // src/main.ts
 var options = parseArgs(process.argv.slice(2));
 if (options.error) {
@@ -3971,10 +4084,39 @@ if (options.mode === "summary") {
   });
   process.exit(exitCode);
 }
+var scopeToProject;
+if (options.scopeToCwd) {
+  const projectsDir = getProjectsDir();
+  let registered = [];
+  try {
+    registered = readdirSync2(projectsDir).map(decodeProjectPath);
+  } catch {
+  }
+  const safeReal = (p) => {
+    try {
+      return realpathSync(p);
+    } catch {
+      return p;
+    }
+  };
+  const match = findContainingProject(process.cwd(), registered, {
+    realpath: safeReal
+  });
+  if (!match) {
+    process.stderr.write(
+      `agenthud: --cwd: no Claude project found at or above ${process.cwd()}
+`
+    );
+    process.exit(1);
+  }
+  scopeToProject = match;
+  process.stderr.write(`agenthud: scope = ${match}
+`);
+}
 if (options.mode === "watch") {
   installAltScreenCleanup();
   enterAltScreen();
 } else {
   if (options.mode === "once") clearScreen();
 }
-render(React.createElement(App, { mode: options.mode }));
+render(React.createElement(App, { mode: options.mode, scopeToProject }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agenthud",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "CLI tool to monitor agent status in real-time. Works with Claude Code, multi-agent workflows, and any AI agent system.",
   "type": "module",
   "main": "dist/index.js",

package/scripts/record-demo.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# Interactive screencast workflow: record what you do in the terminal,
+# automatically encode to demo/live.gif on Ctrl+D.
+#
+# Usage:
+#   scripts/record-demo.sh
+#
+# Override defaults with env vars, e.g.:
+#   COLS=120 ROWS=32 AGG_THEME=dracula scripts/record-demo.sh
+#
+# Dependencies (install once):
+#   brew install asciinema agg
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+CAST="$ROOT/demo/.cache/live.cast"
+GIF="$ROOT/demo/live.gif"
+
+# Wider than the VHS tape's effective area so the split-pane TUI has
+# room to breathe (tree gets ~22 rows, activity viewer ~25 rows at
+# 48 total). For an even more generous recording use e.g.
+# COLS=220 ROWS=56. Most modern emulators honor the xterm resize
+# escape used below.
+COLS="${COLS:-180}"
+ROWS="${ROWS:-48}"
+
+# agg ships: asciinema, dracula, github-dark, github-light, monokai,
+# solarized-dark, solarized-light. Pass a path to a TOML file for
+# anything else (e.g. Catppuccin Mocha).
+AGG_THEME="${AGG_THEME:-monokai}"
+AGG_FONT_SIZE="${AGG_FONT_SIZE:-16}"
+
+for cmd in asciinema agg; do
+  if ! command -v "$cmd" >/dev/null 2>&1; then
+    echo "[record-demo] $cmd not found. Install with: brew install $cmd" >&2
+    exit 1
+  fi
+done
+
+mkdir -p "$(dirname "$CAST")"
+rm -f "$CAST"
+
+# Ask the terminal to resize itself. Works in iTerm2, Terminal.app,
+# kitty, alacritty, wezterm; silently ignored elsewhere.
+printf '\033[8;%d;%dt' "$ROWS" "$COLS"
+
+cat <<EOF
+[record-demo]
+  size   : ${COLS} cols × ${ROWS} rows
+  cast   : ${CAST}
+  gif    : ${GIF}
+
+  Tips:
+    - Type 'clear' once the recording shell appears so the prompt
+      starts on a clean screen (your normal PS1 will be captured
+      otherwise).
+    - Run your scenario at a natural pace.
+    - When you're done, press Ctrl+D (or type 'exit') to stop.
+
+EOF
+
+read -r -p "Press Enter to start recording..." _
+
+asciinema rec "$CAST"
+
+echo
+echo "[record-demo] Encoding ${CAST} → ${GIF}"
+agg --font-size "$AGG_FONT_SIZE" --theme "$AGG_THEME" "$CAST" "$GIF"
+
+echo "[record-demo] Done: ${GIF}"
+echo "[record-demo] Preview: open '${GIF}'"