agenthud 0.8.5 → 0.9.0

package/dist/{main-LOBTW45O.js → main-NHQJ23YJ.js}

@@ -247,12 +247,14 @@ import { homedir } from "os";
 import { join as join2 } from "path";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 var CONFIG_PATH = join2(homedir(), ".agenthud", "config.yaml");
+var STATE_PATH = join2(homedir(), ".agenthud", "state.yaml");
 var DEFAULT_GLOBAL_CONFIG = {
   refreshIntervalMs: 2e3,
   logDir: join2(homedir(), ".agenthud", "logs"),
   hiddenSessions: [],
   hiddenSubAgents: [],
-  filterPresets: [[], ["response"], ["commit"]]
+  filterPresets: [[], ["response"], ["commit"]],
+  hiddenProjects: []
 };
 function parseInterval(value) {
   const match = value.match(/^(\d+)(s|m)$/);
@@ -260,76 +262,175 @@ function parseInterval(value) {
   const n = parseInt(match[1], 10);
   return match[2] === "m" ? n * 60 * 1e3 : n * 1e3;
 }
-function loadGlobalConfig() {
-  const config = { ...DEFAULT_GLOBAL_CONFIG };
-  if (!existsSync(CONFIG_PATH)) {
-    return config;
-  }
-  let raw;
+function ensureAgenthudDir() {
+  const dir = join2(homedir(), ".agenthud");
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+function writeDefaultConfig() {
+  ensureAgenthudDir();
+  const defaultYaml = `# AgentHUD user settings.
+# App-managed state (hidden sessions/projects) lives in state.yaml.
+
+# How often to poll for activity updates
+refreshInterval: 2s
+
+# Where 's' key saves activity logs
+logDir: ~/.agenthud/logs
+
+# Activity filter presets (cycle with 'f' key in viewer)
+# Each list is one preset; [] means "all". First preset is the default.
+filterPresets:
+  - []
+  - ["response"]
+  - ["commit"]
+`;
   try {
-    raw = readFileSync2(CONFIG_PATH, "utf-8");
+    writeFileSync(CONFIG_PATH, defaultYaml, "utf-8");
   } catch {
-    return config;
   }
-  let parsed;
+}
+function writeState(state) {
+  ensureAgenthudDir();
   try {
-    parsed = parseYaml(raw) ?? {};
+    writeFileSync(STATE_PATH, stringifyYaml(state), "utf-8");
   } catch {
-    return config;
   }
-  if (typeof parsed.refreshInterval === "string") {
-    const ms = parseInterval(parsed.refreshInterval);
-    if (ms !== null) config.refreshIntervalMs = ms;
+}
+function rewriteConfigWithoutHideFields(raw) {
+  const cleaned = {};
+  for (const [k, v] of Object.entries(raw)) {
+    if (k === "hiddenSessions" || k === "hiddenSubAgents" || k === "hiddenProjects")
+      continue;
+    cleaned[k] = v;
   }
-  if (typeof parsed.logDir === "string") {
-    config.logDir = parsed.logDir.replace(/^~/, homedir());
+  try {
+    writeFileSync(CONFIG_PATH, stringifyYaml(cleaned), "utf-8");
+  } catch {
   }
-  if (Array.isArray(parsed.hiddenSessions)) {
-    config.hiddenSessions = parsed.hiddenSessions.filter(
-      (s) => typeof s === "string"
-    );
+}
+function loadGlobalConfig() {
+  const config = { ...DEFAULT_GLOBAL_CONFIG };
+  let configRaw = {};
+  let configHadHideFields = false;
+  if (existsSync(CONFIG_PATH)) {
+    try {
+      const text = readFileSync2(CONFIG_PATH, "utf-8");
+      configRaw = parseYaml(text) ?? {};
+    } catch {
+      configRaw = {};
+    }
+  } else {
+    writeDefaultConfig();
   }
-  if (Array.isArray(parsed.hiddenSubAgents)) {
-    config.hiddenSubAgents = parsed.hiddenSubAgents.filter(
-      (s) => typeof s === "string"
-    );
+  if (typeof configRaw.refreshInterval === "string") {
+    const ms = parseInterval(configRaw.refreshInterval);
+    if (ms !== null) config.refreshIntervalMs = ms;
+  }
+  if (typeof configRaw.logDir === "string") {
+    config.logDir = configRaw.logDir.replace(/^~/, homedir());
   }
-  if (Array.isArray(parsed.filterPresets)) {
-    const presets = parsed.filterPresets.filter(Array.isArray).map(
+  if (Array.isArray(configRaw.filterPresets)) {
+    const presets = configRaw.filterPresets.filter(Array.isArray).map(
       (p) => p.filter((t) => typeof t === "string")
     );
     if (presets.length > 0) config.filterPresets = presets;
   }
+  const legacyHidden = {};
+  for (const key of [
+    "hiddenSessions",
+    "hiddenSubAgents",
+    "hiddenProjects"
+  ]) {
+    if (Array.isArray(configRaw[key])) {
+      configHadHideFields = true;
+      legacyHidden[key] = configRaw[key].filter(
+        (s) => typeof s === "string"
+      );
+    }
+  }
+  let stateRaw = {};
+  if (existsSync(STATE_PATH)) {
+    try {
+      const text = readFileSync2(STATE_PATH, "utf-8");
+      stateRaw = parseYaml(text) ?? {};
+    } catch {
+      stateRaw = {};
+    }
+  }
+  for (const key of [
+    "hiddenSessions",
+    "hiddenSubAgents",
+    "hiddenProjects"
+  ]) {
+    if (Array.isArray(stateRaw[key])) {
+      config[key] = stateRaw[key].filter(
+        (s) => typeof s === "string"
+      );
+    }
+  }
+  if (configHadHideFields) {
+    const merged = {
+      hiddenSessions: config.hiddenSessions.length > 0 ? config.hiddenSessions : legacyHidden.hiddenSessions ?? [],
+      hiddenSubAgents: config.hiddenSubAgents.length > 0 ? config.hiddenSubAgents : legacyHidden.hiddenSubAgents ?? [],
+      hiddenProjects: config.hiddenProjects.length > 0 ? config.hiddenProjects : legacyHidden.hiddenProjects ?? []
+    };
+    writeState(merged);
+    rewriteConfigWithoutHideFields(configRaw);
+    config.hiddenSessions = merged.hiddenSessions;
+    config.hiddenSubAgents = merged.hiddenSubAgents;
+    config.hiddenProjects = merged.hiddenProjects;
+  }
   return config;
 }
-function writeConfig(updates) {
-  const configDir = join2(homedir(), ".agenthud");
-  if (!existsSync(configDir)) {
-    mkdirSync(configDir, { recursive: true });
-  }
-  let raw = {};
-  if (existsSync(CONFIG_PATH)) {
+function updateState(updates) {
+  let state = {
+    hiddenSessions: [],
+    hiddenSubAgents: [],
+    hiddenProjects: []
+  };
+  if (existsSync(STATE_PATH)) {
     try {
-      raw = parseYaml(readFileSync2(CONFIG_PATH, "utf-8")) ?? {};
+      const text = readFileSync2(STATE_PATH, "utf-8");
+      const raw = parseYaml(text) ?? {};
+      for (const key of [
+        "hiddenSessions",
+        "hiddenSubAgents",
+        "hiddenProjects"
+      ]) {
+        if (Array.isArray(raw[key])) {
+          state[key] = raw[key].filter(
+            (s) => typeof s === "string"
+          );
+        }
+      }
     } catch {
-      raw = {};
     }
   }
-  if (updates.hiddenSessions !== void 0)
-    raw.hiddenSessions = updates.hiddenSessions;
-  if (updates.hiddenSubAgents !== void 0)
-    raw.hiddenSubAgents = updates.hiddenSubAgents;
-  writeFileSync(CONFIG_PATH, stringifyYaml(raw), "utf-8");
+  for (const key of [
+    "hiddenSessions",
+    "hiddenSubAgents",
+    "hiddenProjects"
+  ]) {
+    if (updates[key] !== void 0) {
+      state[key] = updates[key];
+    }
+  }
+  writeState(state);
 }
 function hideSession(id) {
   const config = loadGlobalConfig();
   if (config.hiddenSessions.includes(id)) return;
-  writeConfig({ hiddenSessions: [...config.hiddenSessions, id] });
+  updateState({ hiddenSessions: [...config.hiddenSessions, id] });
 }
 function hideSubAgent(id) {
   const config = loadGlobalConfig();
   if (config.hiddenSubAgents.includes(id)) return;
-  writeConfig({ hiddenSubAgents: [...config.hiddenSubAgents, id] });
+  updateState({ hiddenSubAgents: [...config.hiddenSubAgents, id] });
+}
+function hideProject(name) {
+  const config = loadGlobalConfig();
+  if (config.hiddenProjects.includes(name)) return;
+  updateState({ hiddenProjects: [...config.hiddenProjects, name] });
 }
 function ensureLogDir(logDir) {
   if (!existsSync(logDir)) {
@@ -432,7 +533,7 @@ function parseModelName(modelId) {
 }
 function getToolDetail(_toolName, input) {
   if (!input) return "";
-  if (input.command) return stripAnsi(input.command.replace(/\n/g, " "));
+  if (input.command) return stripAnsi(input.command);
   if (input.file_path) return basename(input.file_path);
   if (input.pattern) return stripAnsi(input.pattern);
   if (input.query) return stripAnsi(input.query);
@@ -471,7 +572,7 @@ function parseActivitiesFromLines(lines) {
           type: "user",
           icon: ICONS.User,
           label: "User",
-          detail: userText.replace(/\n/g, " ")
+          detail: userText
         });
       }
     }
@@ -493,7 +594,7 @@ function parseActivitiesFromLines(lines) {
               type: "thinking",
               icon: ICONS.Thinking,
               label: "Thinking",
-              detail: block.thinking.replace(/\n/g, " ")
+              detail: block.thinking
             });
           } else if (block.type === "tool_use" && block.name) {
             if (block.name === "TodoWrite") continue;
@@ -518,7 +619,7 @@ function parseActivitiesFromLines(lines) {
               type: "response",
               icon: ICONS.Response,
               label: "Response",
-              detail: block.text.replace(/\n/g, " ")
+              detail: block.text
             });
           }
         }
@@ -581,7 +682,15 @@ function sessionIsOnDate(session, date, activities) {
   }
   return activities.some((a) => isSameLocalDay(a.timestamp, date));
 }
+function flattenForOneLine(s) {
+  return s.replace(/[\r\n\t]+/g, " ").trim();
+}
 function truncateDetail(detail, limit) {
+  const flat = flattenForOneLine(detail);
+  if (limit === 0 || flat.length <= limit) return flat;
+  return flat.slice(0, limit);
+}
+function truncateRaw(detail, limit) {
   if (limit === 0 || detail.length <= limit) return detail;
   return detail.slice(0, limit);
 }
@@ -628,7 +737,7 @@ function generateReport(sessions, options2) {
             time: formatTime(a.timestamp),
             icon: a.icon,
             label: a.label,
-            detail: truncateDetail(a.detail, detailLimit)
+            detail: truncateRaw(a.detail, detailLimit)
           }))
         };
       });
@@ -640,7 +749,7 @@ function generateReport(sessions, options2) {
           time: formatTime(a.timestamp),
           icon: a.icon,
           label: a.label,
-          detail: truncateDetail(a.detail, detailLimit)
+          detail: truncateRaw(a.detail, detailLimit)
         })),
         subAgents: subAgentBlocks
       };
@@ -723,7 +832,14 @@ function createBottomLine(panelWidth = DEFAULT_PANEL_WIDTH) {
   return BOX.bl + BOX.h.repeat(getInnerWidth(panelWidth)) + BOX.br;
 }
 var SEPARATOR = "\u2500".repeat(CONTENT_WIDTH);
-var getDisplayWidth = stringWidth;
+var widthCache = /* @__PURE__ */ new Map();
+function getDisplayWidth(s) {
+  const cached = widthCache.get(s);
+  if (cached !== void 0) return cached;
+  const w = stringWidth(s);
+  widthCache.set(s, w);
+  return w;
+}
 
 // src/data/sessions.ts
 function getProjectsDir() {
@@ -790,6 +906,71 @@ function readModelName(filePath) {
   }
   return null;
 }
+var SYSTEM_PREFIXES = [
+  "<command-name>",
+  "<command-message>",
+  "<command-args>",
+  "<local-command-stdout>",
+  "<local-command-caveat>",
+  "<system-reminder>",
+  "<bash-input>",
+  "<bash-stdout>",
+  "<bash-stderr>",
+  "<user-prompt-submit-hook>"
+];
+function isSystemNoise(text) {
+  const trimmed = text.trimStart();
+  return SYSTEM_PREFIXES.some((p) => trimmed.startsWith(p));
+}
+function readFirstUserPrompt(filePath) {
+  if (!existsSync3(filePath)) return null;
+  let content;
+  try {
+    content = readFileSync4(filePath, "utf-8");
+  } catch {
+    return null;
+  }
+  for (const line of content.split("\n")) {
+    if (!line.trim()) continue;
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (entry.type !== "user") continue;
+    if (entry.toolUseResult !== void 0) continue;
+    const raw = entry.message?.content;
+    let text;
+    if (typeof raw === "string") {
+      text = raw;
+    } else if (Array.isArray(raw)) {
+      const textBlock = raw.find(
+        (b) => b && b.type === "text" && typeof b.text === "string"
+      );
+      text = textBlock?.text ?? "";
+    } else {
+      continue;
+    }
+    if (!text || isSystemNoise(text)) continue;
+    const firstLine = text.split("\n").find((l) => l.trim()) ?? "";
+    if (!firstLine || isSystemNoise(firstLine)) continue;
+    const trimmed = firstLine.trim();
+    return trimmed.length > 80 ? trimmed.slice(0, 80) : trimmed;
+  }
+  return null;
+}
+function readEntrypoint(filePath) {
+  if (!existsSync3(filePath)) return null;
+  try {
+    const firstLine = readFileSync4(filePath, "utf-8").split("\n")[0];
+    if (!firstLine) return null;
+    const entry = JSON.parse(firstLine);
+    return typeof entry.entrypoint === "string" ? entry.entrypoint : null;
+  } catch {
+    return null;
+  }
+}
 function buildSubAgents(parentId, projectDir, config, projectName) {
   const subagentsDir = join3(projectDir, parentId, "subagents");
   if (!existsSync3(subagentsDir)) return [];
@@ -819,7 +1000,9 @@ function buildSubAgents(parentId, projectDir, config, projectName) {
         modelName: readModelName(filePath),
         subAgents: [],
         agentId: agentId ?? void 0,
-        taskDescription: taskDescription ?? void 0
+        taskDescription: taskDescription ?? void 0,
+        nonInteractive: false,
+        firstUserPrompt: null
       };
     } catch {
       return null;
@@ -831,7 +1014,12 @@ function buildSubAgents(parentId, projectDir, config, projectName) {
 function discoverSessions(config) {
   const projectsDir = getProjectsDir();
   if (!existsSync3(projectsDir)) {
-    return { sessions: [], totalCount: 0, timestamp: (/* @__PURE__ */ new Date()).toISOString() };
+    return {
+      projects: [],
+      coldProjects: [],
+      totalCount: 0,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
   }
   let projectDirs;
   try {
@@ -843,7 +1031,12 @@ function discoverSessions(config) {
       }
     });
   } catch {
-    return { sessions: [], totalCount: 0, timestamp: (/* @__PURE__ */ new Date()).toISOString() };
+    return {
+      projects: [],
+      coldProjects: [],
+      totalCount: 0,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
   }
   const allSessions = [];
   for (const encodedDir of projectDirs) {
@@ -874,37 +1067,71 @@ function discoverSessions(config) {
           lastModifiedMs: stat.mtimeMs,
           status: getSessionStatus(stat.mtimeMs),
           modelName: readModelName(filePath),
-          subAgents
+          subAgents,
+          nonInteractive: readEntrypoint(filePath) === "sdk-cli",
+          firstUserPrompt: readFirstUserPrompt(filePath)
         });
       } catch {
       }
     }
   }
-  allSessions.sort((a, b) => {
-    const statusOrder = {
-      hot: 0,
-      warm: 1,
-      cool: 2,
-      cold: 3
-    };
-    const statusDiff = statusOrder[a.status] - statusOrder[b.status];
+  const byProject = /* @__PURE__ */ new Map();
+  for (const s of allSessions) {
+    if (config.hiddenSessions.includes(s.hideKey)) continue;
+    const arr = byProject.get(s.projectPath) ?? [];
+    arr.push(s);
+    byProject.set(s.projectPath, arr);
+  }
+  const statusOrder = {
+    hot: 0,
+    warm: 1,
+    cool: 2,
+    cold: 3
+  };
+  const allProjects = [];
+  for (const [projectPath, sessions] of byProject) {
+    if (sessions.length === 0) continue;
+    const projectName = sessions[0].projectName;
+    if (config.hiddenProjects.includes(projectName)) continue;
+    sessions.sort((a, b) => {
+      if (a.nonInteractive !== b.nonInteractive) {
+        return a.nonInteractive ? 1 : -1;
+      }
+      const statusDiff = statusOrder[a.status] - statusOrder[b.status];
+      if (statusDiff !== 0) return statusDiff;
+      return b.lastModifiedMs - a.lastModifiedMs;
+    });
+    const hotness = sessions[0].status;
+    allProjects.push({ name: projectName, projectPath, sessions, hotness });
+  }
+  const activeProjects = allProjects.filter((p) => p.hotness !== "cold");
+  const coldProjects = allProjects.filter((p) => p.hotness === "cold");
+  activeProjects.sort((a, b) => {
+    const statusDiff = statusOrder[a.hotness] - statusOrder[b.hotness];
     if (statusDiff !== 0) return statusDiff;
-    return b.lastModifiedMs - a.lastModifiedMs;
+    return b.sessions[0].lastModifiedMs - a.sessions[0].lastModifiedMs;
   });
-  const visible = allSessions.filter(
-    (s) => !config.hiddenSessions.includes(s.hideKey)
+  const countSessions = (projects) => projects.reduce(
+    (sum, p) => sum + p.sessions.length + p.sessions.reduce((s, sn) => s + sn.subAgents.length, 0),
+    0
   );
-  const totalCount = visible.length + visible.reduce((sum, s) => sum + s.subAgents.length, 0);
+  const totalCount = countSessions(activeProjects) + countSessions(coldProjects);
   return {
-    sessions: visible,
+    projects: activeProjects,
+    coldProjects,
     totalCount,
     timestamp: (/* @__PURE__ */ new Date()).toISOString()
   };
 }
 
 // src/data/summaryRunner.ts
+function agenthudHomeDir() {
+  const dir = join4(homedir3(), ".agenthud");
+  if (!existsSync4(dir)) mkdirSync2(dir, { recursive: true });
+  return dir;
+}
 function summariesDir() {
-  const dir = join4(homedir3(), ".agenthud", "summaries");
+  const dir = join4(agenthudHomeDir(), "summaries");
   if (!existsSync4(dir)) mkdirSync2(dir, { recursive: true });
   return dir;
 }
@@ -974,7 +1201,8 @@ async function runSummary(options2) {
   const prompt = resolvePrompt(options2.prompt);
   return new Promise((resolve) => {
     const proc = spawn("claude", ["-p", prompt], {
-      stdio: ["pipe", "pipe", "pipe"]
+      stdio: ["pipe", "pipe", "pipe"],
+      cwd: agenthudHomeDir()
     });
     let cacheStream = null;
     cacheStream = createWriteStream(cached, { encoding: "utf-8" });
@@ -1025,7 +1253,7 @@ async function runSummary(options2) {
 // src/ui/App.tsx
 import { existsSync as existsSync5, watch, writeFileSync as writeFileSync2 } from "fs";
 import { join as join5 } from "path";
-import { Box as Box4, Text as Text4, useApp, useInput, useStdout } from "ink";
+import { Box as Box5, Text as Text5, useApp, useInput, useStdout } from "ink";
 import { useCallback, useEffect as useEffect2, useMemo, useRef, useState as useState2 } from "react";
 
 // src/ui/ActivityViewerPanel.tsx
@@ -1063,20 +1291,21 @@ function formatActivityTime(date, now) {
   const day = String(date.getDate()).padStart(2, "0");
   return `${month}/${day} ${time}`;
 }
+function flattenForOneLine2(detail) {
+  return detail.replace(/[\r\n\t]+/g, " ").trim();
+}
 function truncateDetail2(detail, maxWidth) {
-  if (getDisplayWidth(detail) <= maxWidth) return detail;
+  const flat = flattenForOneLine2(detail);
+  if (getDisplayWidth(flat) <= maxWidth) return flat;
   let truncated = "";
-  let currentWidth = 0;
-  for (const char of detail) {
+  let width = 0;
+  for (const char of flat) {
     const charWidth = getDisplayWidth(char);
-    if (currentWidth + charWidth > maxWidth - 3) {
-      truncated += "...";
-      break;
-    }
+    if (width + charWidth > maxWidth - 1) break;
     truncated += char;
-    currentWidth += charWidth;
+    width += charWidth;
   }
-  return truncated;
+  return `${truncated}\u2026`;
 }
 function ActivityViewerPanel({
   activities,
@@ -1279,10 +1508,114 @@ function DetailViewPanel({
   ] });
 }
 
+// src/ui/HelpPanel.tsx
+import { Box as Box3, Text as Text3 } from "ink";
+import { jsx as jsx3, jsxs as jsxs3 } from "react/jsx-runtime";
+var SECTIONS = [
+  {
+    title: "Session tree",
+    rows: [
+      ["\u2191 \u2193 / k j", "Move selection"],
+      ["PgUp / Ctrl+B", "Page up"],
+      ["PgDn / Ctrl+F", "Page down"],
+      ["\u21B5", "Expand/collapse project, session, or summary"],
+      ["h", "Hide selected (project/session/sub-agent)"],
+      ["Tab", "Switch focus to activity viewer"],
+      ["r", "Refresh now"]
+    ]
+  },
+  {
+    title: "Activity viewer",
+    rows: [
+      ["\u2191 \u2193 / k j", "Scroll one line"],
+      ["PgUp/Dn, Ctrl+B/F", "Scroll one page"],
+      ["Ctrl+U / Ctrl+D", "Scroll half page"],
+      ["g", "Jump to live (newest)"],
+      ["G", "Jump to oldest"],
+      ["\u21B5", "Open detail view for selected activity"],
+      ["f", "Cycle filter preset (set in config.yaml)"],
+      ["s", "Save activity log to ~/.agenthud/logs/"],
+      ["Tab", "Switch focus to session tree"]
+    ]
+  },
+  {
+    title: "Detail view",
+    rows: [
+      ["\u2191 \u2193 / k j", "Scroll"],
+      ["\u21B5 / Esc / q", "Close"]
+    ]
+  },
+  {
+    title: "Always available",
+    rows: [
+      ["?", "Toggle this help"],
+      ["q", "Quit (or close detail/help)"]
+    ]
+  },
+  {
+    title: "CLI commands",
+    rows: [
+      ["agenthud report", "Print activity for a date as Markdown/JSON"],
+      ["agenthud summary", "LLM-summarize a day via claude -p (cached)"],
+      ["agenthud --help", "Full CLI usage"]
+    ]
+  },
+  {
+    title: "Files",
+    rows: [
+      ["~/.agenthud/config.yaml", "User settings (edit freely)"],
+      ["~/.agenthud/state.yaml", "Hidden items (app-managed)"],
+      ["~/.agenthud/summary-prompt.md", "LLM prompt template"],
+      ["~/.agenthud/summaries/", "Cached daily summaries"]
+    ]
+  }
+];
+function HelpPanel({
+  width,
+  height
+}) {
+  const allKeys = SECTIONS.flatMap((s) => s.rows.map((r) => r[0]));
+  const keyColumn = Math.min(
+    30,
+    Math.max(...allKeys.map((k) => getDisplayWidth(k)))
+  );
+  const padTo = (s, w) => {
+    const pad = Math.max(0, w - getDisplayWidth(s));
+    return s + " ".repeat(pad);
+  };
+  const lines = [];
+  lines.push(
+    /* @__PURE__ */ jsx3(Text3, { bold: true, children: "AgentHUD Help" }, "title")
+  );
+  lines.push(/* @__PURE__ */ jsx3(Text3, { children: " " }, "title-sp"));
+  for (let s = 0; s < SECTIONS.length; s++) {
+    if (s > 0) lines.push(/* @__PURE__ */ jsx3(Text3, { children: " " }, `sp-${s}`));
+    lines.push(
+      /* @__PURE__ */ jsx3(Text3, { bold: true, color: "cyan", children: SECTIONS[s].title }, `title-${s}`)
+    );
+    for (let r = 0; r < SECTIONS[s].rows.length; r++) {
+      const [key, desc] = SECTIONS[s].rows[r];
+      const isCli = key.trim().startsWith("agenthud");
+      const isFile = key.includes("~/.agenthud");
+      lines.push(
+        /* @__PURE__ */ jsxs3(Text3, { children: [
+          /* @__PURE__ */ jsx3(Text3, { dimColor: true, children: " " }),
+          /* @__PURE__ */ jsx3(Text3, { color: isCli ? "cyan" : isFile ? "green" : void 0, children: padTo(key, keyColumn) }),
+          /* @__PURE__ */ jsx3(Text3, { children: " " }),
+          /* @__PURE__ */ jsx3(Text3, { dimColor: true, children: desc })
+        ] }, `row-${s}-${r}`)
+      );
+    }
+  }
+  const visible = lines.slice(0, height);
+  return /* @__PURE__ */ jsx3(Box3, { flexDirection: "column", width, children: visible });
+}
+
 // src/ui/hooks/useHotkeys.ts
 function useHotkeys({
   focus,
   detailMode,
+  helpMode,
   onSwitchFocus,
   onScrollUp,
   onScrollDown,
@@ -1301,9 +1634,21 @@ function useHotkeys({
   onDetailScrollUp,
   onDetailScrollDown,
   onFilter,
+  onHelp,
   filterLabel
 }) {
   const handleInput = (input, key) => {
+    if (helpMode) {
+      if (key.return || key.escape || input === "q" || input === "?") {
+        onHelp();
+        return;
+      }
+      return;
+    }
+    if (input === "?") {
+      onHelp();
+      return;
+    }
     if (detailMode) {
       if (key.upArrow || input === "k") {
         onDetailScrollUp();
@@ -1402,13 +1747,14 @@ function useHotkeys({
       }
     }
   };
-  const statusBarItems = detailMode ? ["\u2191\u2193/jk: scroll", "\u21B5/Esc: close"] : focus === "tree" ? [
+  const statusBarItems = helpMode ? ["\u21B5/Esc/q/?: close"] : detailMode ? ["\u2191\u2193/jk: scroll", "\u21B5/Esc: close", "?: help"] : focus === "tree" ? [
     "Tab: viewer",
     "\u2191\u2193/jk: select",
     "PgUp/Dn: page",
     "\u21B5: expand",
     "h: hide",
     "r: refresh",
+    "?: help",
     "q: quit"
   ] : [
     "Tab: sessions",
@@ -1418,6 +1764,7 @@ function useHotkeys({
     "G: oldest",
     "\u21B5: detail",
     `f: ${filterLabel}`,
+    "?: help",
     "q: quit"
   ];
   return { handleInput, statusBarItems };
@@ -1440,8 +1787,8 @@ function useSpinner(active, intervalMs = 100) {
 
 // src/ui/SessionTreePanel.tsx
 import { homedir as homedir4 } from "os";
-import { Box as Box3, Text as Text3 } from "ink";
-import { jsx as jsx3, jsxs as jsxs3 } from "react/jsx-runtime";
+import { Box as Box4, Text as Text4 } from "ink";
+import { Fragment, jsx as jsx4, jsxs as jsxs4 } from "react/jsx-runtime";
 function formatElapsed(lastModifiedMs) {
   const elapsed = Date.now() - lastModifiedMs;
   const seconds = Math.floor(elapsed / 1e3);
@@ -1481,23 +1828,24 @@ function SessionRow({
   prefix,
   contentWidth
 }) {
-  const isParent = prefix === "";
+  const isParent = prefix === "    ";
   const statusColor = getStatusColor(session.status);
   const badge = `[${session.status}]`;
   const elapsed = formatElapsed(session.lastModifiedMs);
   const model = session.modelName ?? "";
-  const name = isParent ? session.projectName || session.id.slice(0, 8) : session.agentId ?? session.id.slice(0, 8);
-  const shortId = isParent && session.projectName ? ` #${session.id.slice(0, 4)}` : "";
+  const isNonInteractive = session.nonInteractive;
+  const rawName = isParent ? isNonInteractive ? `(#${session.id.slice(0, 4)})` : `#${session.id.slice(0, 4)}` : session.agentId ?? session.id.slice(0, 8);
+  const shortIdDisplay = "";
   const rightParts = [elapsed];
   if (model) rightParts.push(model);
   const rightSide = rightParts.join(" ");
-  const leftCore = `${prefix}${name}${shortId} ${badge}`;
-  const leftCoreWidth = getDisplayWidth(leftCore);
+  const leftCoreBase = `${prefix}${rawName}${shortIdDisplay} ${badge}`;
+  const leftCoreWidth = getDisplayWidth(leftCoreBase);
   const rightWidth = getDisplayWidth(rightSide);
   const middleAvailable = contentWidth - leftCoreWidth - 1 - rightWidth - 1;
   let middleText = "";
   if (middleAvailable > 3) {
-    const raw = isParent ? session.projectPath ? formatProjectPath(session.projectPath) : "" : session.taskDescription ?? "";
+    const raw = isParent ? session.firstUserPrompt ?? "" : session.taskDescription ?? "";
     if (raw) {
       const truncated = truncatePath(raw, middleAvailable);
       if (truncated) middleText = truncated;
@@ -1509,42 +1857,56 @@ function SessionRow({
     contentWidth - leftCoreWidth - getDisplayWidth(middleSection) - rightWidth
   );
   const gap = " ".repeat(gapWidth);
-  const fullLine = leftCore + middleSection + gap + rightSide;
+  const fullLine = leftCoreBase + middleSection + gap + rightSide;
   const linePadding = Math.max(0, contentWidth - getDisplayWidth(fullLine));
   const highlight = isSelected && hasFocus;
-  return /* @__PURE__ */ jsxs3(Text3, { children: [
+  const shouldDim = isNonInteractive;
+  return /* @__PURE__ */ jsxs4(Text4, { children: [
     BOX.v,
     " ",
-    /* @__PURE__ */ jsxs3(Text3, { backgroundColor: highlight ? "blue" : void 0, bold: highlight, children: [
-      /* @__PURE__ */ jsx3(Text3, { children: prefix }),
-      /* @__PURE__ */ jsx3(Text3, { bold: true, children: name }),
-      shortId ? /* @__PURE__ */ jsx3(Text3, { dimColor: true, children: shortId }) : null,
-      /* @__PURE__ */ jsx3(Text3, { children: " " }),
-      /* @__PURE__ */ jsx3(Text3, { color: statusColor, children: badge }),
-      middleText ? /* @__PURE__ */ jsx3(Text3, { dimColor: true, children: middleSection }) : null,
-      /* @__PURE__ */ jsx3(Text3, { children: gap }),
-      /* @__PURE__ */ jsx3(Text3, { dimColor: true, children: elapsed }),
-      model ? /* @__PURE__ */ jsx3(Text3, { dimColor: true, children: ` ${model}` }) : null
-    ] }),
+    /* @__PURE__ */ jsxs4(
+      Text4,
+      {
+        backgroundColor: highlight ? "blue" : void 0,
+        bold: highlight,
+        dimColor: shouldDim && !highlight,
+        children: [
+          /* @__PURE__ */ jsx4(Text4, { dimColor: shouldDim && !highlight, children: prefix }),
+          /* @__PURE__ */ jsx4(Text4, { bold: !shouldDim, children: rawName }),
+          shortIdDisplay ? /* @__PURE__ */ jsx4(Text4, { dimColor: true, children: shortIdDisplay }) : null,
+          /* @__PURE__ */ jsx4(Text4, { children: " " }),
+          /* @__PURE__ */ jsx4(Text4, { color: statusColor, children: badge }),
+          middleText ? /* @__PURE__ */ jsx4(Text4, { dimColor: true, children: middleSection }) : null,
+          /* @__PURE__ */ jsx4(Text4, { children: gap }),
+          /* @__PURE__ */ jsx4(Text4, { dimColor: true, children: elapsed }),
+          model ? /* @__PURE__ */ jsx4(Text4, { dimColor: true, children: ` ${model}` }) : null
+        ]
+      }
+    ),
     " ".repeat(linePadding),
     BOX.v
   ] });
 }
 function appendSessionRows(result, session, expandedIds) {
-  const isExpanded = expandedIds.has(session.id);
+  const isCold = session.status === "cold";
+  const sessionCollapsedKey = `__collapsed-session-${session.id}`;
+  const sessionExpandedKey = `__expanded-session-${session.id}`;
+  const sessionHidden = isCold ? !expandedIds.has(sessionExpandedKey) : expandedIds.has(sessionCollapsedKey);
+  if (sessionHidden) return;
+  const subAgentsFullyExpanded = expandedIds.has(session.id) || isCold && expandedIds.has(sessionExpandedKey);
   const hotWarm = session.subAgents.filter(
     (s) => s.status === "hot" || s.status === "warm"
   );
   const cool = session.subAgents.filter((s) => s.status === "cool");
   const cold = session.subAgents.filter((s) => s.status === "cold");
-  if (isExpanded) {
+  if (subAgentsFullyExpanded) {
     const all = [...hotWarm, ...cool, ...cold];
     for (let i = 0; i < all.length; i++) {
       const isLast = i === all.length - 1;
       result.push({
         kind: "session",
         session: all[i],
-        prefix: `${isLast ? "\u2514\u2500 " : "\u251C\u2500 "}\xBB `
+        prefix: `        ${isLast ? "\u2514\u2500 " : "\u251C\u2500 "}\xBB `
       });
     }
   } else {
@@ -1554,7 +1916,7 @@ function appendSessionRows(result, session, expandedIds) {
       result.push({
         kind: "session",
         session: hotWarm[i],
-        prefix: `${isLast ? "\u2514\u2500 " : "\u251C\u2500 "}\xBB `
+        prefix: `        ${isLast ? "\u2514\u2500 " : "\u251C\u2500 "}\xBB `
       });
     }
     if (hasSummary) {
@@ -1567,25 +1929,65 @@ function appendSessionRows(result, session, expandedIds) {
     }
   }
 }
-function flattenSessions(sessions, expandedIds) {
+function flattenSessions(projects, coldProjects, expandedIds) {
   const result = [];
-  const visibleSessions = sessions.filter((s) => s.status !== "cold");
-  const coldSessions = sessions.filter((s) => s.status === "cold");
-  for (const session of visibleSessions) {
-    result.push({ kind: "session", session, prefix: "" });
-    appendSessionRows(result, session, expandedIds);
-  }
-  if (coldSessions.length > 0) {
-    result.push({ kind: "cold-sessions-summary", count: coldSessions.length });
-    if (expandedIds.has("__cold__")) {
-      for (const session of coldSessions) {
-        result.push({ kind: "session", session, prefix: "" });
+  for (const project of projects) {
+    const sentinelId = `__proj-${project.name}__`;
+    result.push({ kind: "project", project, sentinelId });
+    const collapsed = expandedIds.has(`__collapsed-${sentinelId}`);
+    if (!collapsed) {
+      for (const session of project.sessions) {
+        result.push({ kind: "session", session, prefix: "    " });
         appendSessionRows(result, session, expandedIds);
       }
     }
   }
+  if (coldProjects.length > 0) {
+    result.push({ kind: "cold-projects-summary", count: coldProjects.length });
+    if (expandedIds.has("__cold__")) {
+      for (const project of coldProjects) {
+        const sentinelId = `__proj-${project.name}__`;
+        result.push({ kind: "project", project, sentinelId });
+        const expanded = expandedIds.has(`__expanded-${sentinelId}`);
+        if (expanded) {
+          for (const session of project.sessions) {
+            result.push({ kind: "session", session, prefix: "    " });
+            appendSessionRows(result, session, expandedIds);
+          }
+        }
+      }
+    }
+  }
   return result;
 }
+function ProjectRow({
+  project,
+  isSelected,
+  hasFocus,
+  contentWidth
+}) {
+  const nameText = `> ${project.name}`;
+  const pathText = project.projectPath ? formatProjectPath(project.projectPath) : "";
+  const nameWidth = getDisplayWidth(nameText);
+  const pathWidth = pathText ? getDisplayWidth(pathText) : 0;
+  const gapWidth = pathText ? 2 : 0;
+  const totalWidth = nameWidth + gapWidth + pathWidth;
+  const padding = Math.max(0, contentWidth - totalWidth);
+  const highlight = isSelected && hasFocus;
+  return /* @__PURE__ */ jsxs4(Text4, { children: [
+    BOX.v,
+    " ",
+    /* @__PURE__ */ jsxs4(Text4, { backgroundColor: highlight ? "blue" : void 0, bold: !highlight, children: [
+      nameText,
+      pathText ? /* @__PURE__ */ jsxs4(Fragment, { children: [
+        "  ",
+        /* @__PURE__ */ jsx4(Text4, { dimColor: true, children: pathText })
+      ] }) : null,
+      " ".repeat(padding)
+    ] }),
+    BOX.v
+  ] });
+}
 function SubagentSummaryRow({
   coolCount,
   coldCount,
@@ -1597,16 +1999,16 @@ function SubagentSummaryRow({
   if (coolCount > 0) parts.push(`${coolCount} cool`);
   if (coldCount > 0) parts.push(`${coldCount} cold`);
   const hint = " +";
-  const text = `\u2514\u2500 ... ${parts.join("  ")}`;
+  const text = `        \u2514\u2500 ... ${parts.join("  ")}`;
   const padding = Math.max(
     0,
     contentWidth - getDisplayWidth(text) - getDisplayWidth(hint)
   );
   const active = isSelected && hasFocus;
-  return /* @__PURE__ */ jsxs3(Text3, { children: [
+  return /* @__PURE__ */ jsxs4(Text4, { children: [
     BOX.v,
     " ",
-    /* @__PURE__ */ jsxs3(Text3, { dimColor: !active, inverse: active, children: [
+    /* @__PURE__ */ jsxs4(Text4, { dimColor: !active, inverse: active, children: [
       text,
       " ".repeat(padding),
       hint
@@ -1614,7 +2016,7 @@ function SubagentSummaryRow({
     BOX.v
   ] });
 }
-function ColdSessionsSummaryRow({
+function ColdProjectsSummaryRow({
   count,
   isSelected,
   hasFocus,
@@ -1629,8 +2031,8 @@ function ColdSessionsSummaryRow({
   const dashes = BOX.h.repeat(dashCount);
   const line = `${BOX.ml}${BOX.h}${label}${dashes}${hint}${BOX.mr}`;
   const highlight = isSelected && hasFocus;
-  return /* @__PURE__ */ jsx3(
-    Text3,
+  return /* @__PURE__ */ jsx4(
+    Text4,
     {
       backgroundColor: highlight ? "blue" : void 0,
       bold: highlight,
@@ -1640,7 +2042,8 @@ function ColdSessionsSummaryRow({
   );
 }
 function SessionTreePanel({
-  sessions,
+  projects,
+  coldProjects,
   selectedId,
   hasFocus,
   width = DEFAULT_PANEL_WIDTH,
@@ -1651,28 +2054,30 @@ function SessionTreePanel({
   const contentWidth = innerWidth - 1;
   const titleLine = createTitleLine("Sessions", "", width);
   const bottomLine = createBottomLine(width);
-  if (sessions.length === 0) {
+  const totalProjectCount = projects.length + coldProjects.length;
+  if (totalProjectCount === 0) {
     const emptyText = "No Claude sessions";
     const emptyPadding = Math.max(0, contentWidth - emptyText.length);
-    return /* @__PURE__ */ jsxs3(Box3, { flexDirection: "column", width, children: [
-      /* @__PURE__ */ jsx3(Text3, { children: titleLine }),
-      /* @__PURE__ */ jsxs3(Text3, { children: [
+    return /* @__PURE__ */ jsxs4(Box4, { flexDirection: "column", width, children: [
+      /* @__PURE__ */ jsx4(Text4, { children: titleLine }),
+      /* @__PURE__ */ jsxs4(Text4, { children: [
         BOX.v,
         " ",
-        /* @__PURE__ */ jsx3(Text3, { dimColor: true, children: emptyText }),
+        /* @__PURE__ */ jsx4(Text4, { dimColor: true, children: emptyText }),
         " ".repeat(emptyPadding),
         BOX.v
       ] }),
-      /* @__PURE__ */ jsx3(Text3, { children: bottomLine })
+      /* @__PURE__ */ jsx4(Text4, { children: bottomLine })
     ] });
   }
-  const flatRows = flattenSessions(sessions, expandedIds);
+  const flatRows = flattenSessions(projects, coldProjects, expandedIds);
   const totalRows = flatRows.length;
   const selectedFlatIndex = flatRows.findIndex((row) => {
+    if (row.kind === "project") return selectedId === row.sentinelId;
     if (row.kind === "session") return row.session.id === selectedId;
     if (row.kind === "subagent-summary")
       return selectedId === `__sub-${row.parentId}__`;
-    if (row.kind === "cold-sessions-summary") return selectedId === "__cold__";
+    if (row.kind === "cold-projects-summary") return selectedId === "__cold__";
     return false;
   });
   const needsOverflow = maxRows !== void 0 && totalRows > maxRows;
@@ -1684,10 +2089,19 @@ function SessionTreePanel({
   }
   const displayRows = flatRows.slice(scrollTop, scrollTop + visibleCount);
   const hiddenBelow = totalRows - (scrollTop + displayRows.length);
-  return /* @__PURE__ */ jsxs3(Box3, { flexDirection: "column", width, children: [
-    /* @__PURE__ */ jsx3(Text3, { children: titleLine }),
+  return /* @__PURE__ */ jsxs4(Box4, { flexDirection: "column", width, children: [
+    /* @__PURE__ */ jsx4(Text4, { children: titleLine }),
     displayRows.map(
-      (row, idx) => row.kind === "session" ? /* @__PURE__ */ jsx3(
+      (row, idx) => row.kind === "project" ? /* @__PURE__ */ jsx4(
+        ProjectRow,
+        {
+          project: row.project,
+          isSelected: selectedId === row.sentinelId,
+          hasFocus,
+          contentWidth
+        },
+        `project-${row.project.name}-${idx}`
+      ) : row.kind === "session" ? /* @__PURE__ */ jsx4(
         SessionRow,
         {
           session: row.session,
@@ -1697,7 +2111,7 @@ function SessionTreePanel({
           contentWidth
         },
         `${row.session.id}-${idx}`
-      ) : row.kind === "subagent-summary" ? /* @__PURE__ */ jsx3(
+      ) : row.kind === "subagent-summary" ? /* @__PURE__ */ jsx4(
         SubagentSummaryRow,
         {
           coolCount: row.coolCount,
@@ -1707,8 +2121,8 @@ function SessionTreePanel({
           hasFocus
         },
         `subagent-summary-${idx}`
-      ) : /* @__PURE__ */ jsx3(
-        ColdSessionsSummaryRow,
+      ) : /* @__PURE__ */ jsx4(
+        ColdProjectsSummaryRow,
         {
           count: row.count,
           isSelected: selectedId === "__cold__",
@@ -1718,35 +2132,42 @@ function SessionTreePanel({
         "cold-summary"
       )
     ),
-    hiddenBelow > 0 && /* @__PURE__ */ jsxs3(Text3, { children: [
+    hiddenBelow > 0 && /* @__PURE__ */ jsxs4(Text4, { children: [
       BOX.v,
       " ",
-      /* @__PURE__ */ jsx3(Text3, { dimColor: true, children: `... ${hiddenBelow} more` }),
+      /* @__PURE__ */ jsx4(Text4, { dimColor: true, children: `... ${hiddenBelow} more` }),
       " ".repeat(
         Math.max(0, contentWidth - `... ${hiddenBelow} more`.length - 1)
       ),
       BOX.v
     ] }),
-    /* @__PURE__ */ jsx3(Text3, { children: bottomLine })
+    /* @__PURE__ */ jsx4(Text4, { children: bottomLine })
   ] });
 }
 
 // src/ui/App.tsx
-import { jsx as jsx4, jsxs as jsxs4 } from "react/jsx-runtime";
+import { Fragment as Fragment2, jsx as jsx5, jsxs as jsxs5 } from "react/jsx-runtime";
 var VIEWER_HEIGHT_FRACTION = 0.55;
 function subSummarySentinel(parentId) {
   return {
     id: `__sub-${parentId}__`,
+    hideKey: "",
     filePath: "",
     projectPath: "",
     projectName: "",
     lastModifiedMs: 0,
     status: "cold",
     modelName: null,
-    subAgents: []
+    subAgents: [],
+    nonInteractive: false
   };
 }
 function appendSubAgentRows(result, session, expandedIds) {
+  const isCold = session.status === "cold";
+  const sessionCollapsedKey = `__collapsed-session-${session.id}`;
+  const sessionExpandedKey = `__expanded-session-${session.id}`;
+  const sessionHidden = isCold ? !expandedIds.has(sessionExpandedKey) : expandedIds.has(sessionCollapsedKey);
+  if (sessionHidden) return;
   if (expandedIds.has(session.id)) {
     result.push(...session.subAgents);
   } else {
@@ -1764,27 +2185,47 @@ function appendSubAgentRows(result, session, expandedIds) {
 }
 function flattenSessions2(tree, expandedIds) {
   const result = [];
-  const visible = tree.sessions.filter((s) => s.status !== "cold");
-  const cold = tree.sessions.filter((s) => s.status === "cold");
-  for (const s of visible) {
-    result.push(s);
-    appendSubAgentRows(result, s, expandedIds);
+  const projectToFlat = (project, isCold) => {
+    const sentinelId = `__proj-${project.name}__`;
+    result.push({
+      id: sentinelId,
+      hideKey: "",
+      filePath: "",
+      projectPath: project.projectPath,
+      projectName: project.name,
+      lastModifiedMs: 0,
+      status: project.hotness,
+      modelName: null,
+      subAgents: [],
+      nonInteractive: false
+    });
+    const shouldShowSessions = isCold ? expandedIds.has(`__expanded-${sentinelId}`) : !expandedIds.has(`__collapsed-${sentinelId}`);
+    if (shouldShowSessions) {
+      for (const session of project.sessions) {
+        result.push(session);
+        appendSubAgentRows(result, session, expandedIds);
+      }
+    }
+  };
+  for (const project of tree.projects) {
+    projectToFlat(project, false);
   }
-  if (cold.length > 0) {
+  if (tree.coldProjects.length > 0) {
     result.push({
       id: "__cold__",
+      hideKey: "",
       filePath: "",
       projectPath: "",
-      projectName: `${cold.length} cold`,
+      projectName: `${tree.coldProjects.length} cold`,
       lastModifiedMs: 0,
       status: "cold",
       modelName: null,
-      subAgents: []
+      subAgents: [],
+      nonInteractive: false
     });
     if (expandedIds.has("__cold__")) {
-      for (const s of cold) {
-        result.push(s);
-        appendSubAgentRows(result, s, expandedIds);
+      for (const project of tree.coldProjects) {
+        projectToFlat(project, true);
       }
     }
   }
@@ -1813,8 +2254,9 @@ function App({ mode }) {
     () => discoverSessions(config)
   );
   const [selectedId, setSelectedId] = useState2(() => {
-    const first = sessionTree.sessions[0];
-    return first?.id ?? null;
+    const firstProject = sessionTree.projects[0];
+    if (firstProject) return `__proj-${firstProject.name}__`;
+    return null;
   });
   const [focus, setFocus] = useState2("tree");
   const [scrollOffset, setScrollOffset] = useState2(0);
@@ -1830,6 +2272,7 @@ function App({ mode }) {
   );
   const [detailScrollOffset, setDetailScrollOffset] = useState2(0);
   const [filterIndex, setFilterIndex] = useState2(0);
+  const [helpMode, setHelpMode] = useState2(false);
   const allFlat = useMemo(
     () => flattenSessions2(sessionTree, expandedIds),
     [sessionTree, expandedIds]
@@ -1844,19 +2287,35 @@ function App({ mode }) {
     activitiesLengthRef.current = activities.length;
     activitiesRef.current = activities;
   }, [activities]);
+  const lastLoadedFileRef = useRef(null);
   useEffect2(() => {
-    const node = allFlatRef.current.find((s) => s.id === selectedId);
+    let node = allFlatRef.current.find((s) => s.id === selectedId);
+    if (node && selectedId?.startsWith("__proj-") && selectedId.endsWith("__")) {
+      const projectName = selectedId.slice(7, -2);
+      const project = sessionTree.projects.find((p) => p.name === projectName) ?? sessionTree.coldProjects.find((p) => p.name === projectName);
+      if (project && project.sessions.length > 0) {
+        node = project.sessions[0];
+      } else {
+        node = void 0;
+      }
+    }
+    const newFile = node?.filePath ?? null;
+    const fileChanged = lastLoadedFileRef.current !== newFile;
+    lastLoadedFileRef.current = newFile;
     if (node?.filePath) {
       setActivities(parseSessionHistory(node.filePath));
-      setScrollOffset(0);
-      setIsLive(true);
-      setNewCount(0);
-      setViewerCursorLine(0);
+      if (fileChanged) {
+        setScrollOffset(0);
+        setIsLive(true);
+        setNewCount(0);
+        setViewerCursorLine(0);
+        setGitActivities([]);
+      }
     } else {
       setActivities([]);
+      if (fileChanged) setGitActivities([]);
     }
-    setGitActivities([]);
-  }, [selectedId]);
+  }, [selectedId, sessionTree]);
   useEffect2(() => {
     setScrollOffset(0);
     setIsLive(true);
@@ -1900,7 +2359,8 @@ function App({ mode }) {
     const updatedFlat = flattenSessions2(tree, expandedIds);
     const node = updatedFlat.find((s) => s.id === selectedId);
     if (!node) {
-      const parentSession = tree.sessions.find(
+      const allSessions = tree.projects?.flatMap((p) => p.sessions) ?? [];
+      const parentSession = allSessions.find(
         (s) => s.subAgents.some((sa) => sa.id === selectedId)
       );
       if (parentSession) setSelectedId(parentSession.id);
@@ -1995,6 +2455,8 @@ function App({ mode }) {
   const { handleInput, statusBarItems } = useHotkeys({
     focus,
     detailMode,
+    helpMode,
+    onHelp: () => setHelpMode((m) => !m),
     onSwitchFocus: () => setFocus((f) => f === "tree" ? "viewer" : "tree"),
     onScrollUp: () => {
       if (focus === "tree") {
@@ -2137,6 +2599,23 @@ function App({ mode }) {
         return;
       }
       if (focus !== "tree" || !selectedId) return;
+      if (selectedId.startsWith("__proj-") && selectedId.endsWith("__")) {
+        const projectName = selectedId.slice(7, -2);
+        const isCold = sessionTree.coldProjects.some(
+          (p) => p.name === projectName
+        );
+        const toggleKey = isCold ? `__expanded-${selectedId}` : `__collapsed-${selectedId}`;
+        setExpandedIds((prev) => {
+          const next = new Set(prev);
+          if (next.has(toggleKey)) {
+            next.delete(toggleKey);
+          } else {
+            next.add(toggleKey);
+          }
+          return next;
+        });
+        return;
+      }
       if (selectedId === "__cold__") {
         setExpandedIds((prev) => {
           const next = new Set(prev);
@@ -2158,7 +2637,8 @@ function App({ mode }) {
             setSelectedId(parentId);
           } else {
             next.add(parentId);
-            const parent = sessionTree.sessions.find((s) => s.id === parentId);
+            const allSessions2 = sessionTree.projects?.flatMap((p) => p.sessions) ?? [];
+            const parent = allSessions2.find((s) => s.id === parentId);
             const firstNew = parent?.subAgents.find(
               (sa) => sa.status === "cool" || sa.status === "cold"
             );
@@ -2168,38 +2648,51 @@ function App({ mode }) {
         });
         return;
       }
-      const parentSession = sessionTree.sessions.find(
-        (s) => s.id === selectedId
-      );
-      if (!parentSession || !parentSession.subAgents.some(
-        (s) => s.status === "cool" || s.status === "cold"
-      ))
+      const allSessions3 = [
+        ...sessionTree.projects.flatMap((p) => p.sessions),
+        ...sessionTree.coldProjects.flatMap((p) => p.sessions)
+      ];
+      const selectedSessionObj = allSessions3.find((s) => s.id === selectedId);
+      if (selectedSessionObj && selectedSessionObj.subAgents.length > 0) {
+        const isCold = selectedSessionObj.status === "cold";
+        const toggleKey = isCold ? `__expanded-session-${selectedId}` : `__collapsed-session-${selectedId}`;
+        setExpandedIds((prev) => {
+          const next = new Set(prev);
+          if (next.has(toggleKey)) {
+            next.delete(toggleKey);
+            if (!isCold) setSelectedId(selectedId);
+          } else {
+            next.add(toggleKey);
+            if (isCold) {
+              const firstSub = selectedSessionObj.subAgents[0];
+              if (firstSub) setSelectedId(firstSub.id);
+            }
+          }
+          return next;
+        });
         return;
-      setExpandedIds((prev) => {
-        const next = new Set(prev);
-        if (next.has(selectedId)) {
-          next.delete(selectedId);
-        } else {
-          next.add(selectedId);
-        }
-        return next;
-      });
+      }
     },
     onHide: () => {
       if (focus !== "tree" || !selectedId) return;
+      if (selectedId.startsWith("__proj-") && selectedId.endsWith("__")) {
+        const projectName = selectedId.slice(7, -2);
+        hideProject(projectName);
+        refresh();
+        const nextId = allFlat[selectedIndex + 1]?.id ?? allFlat[selectedIndex - 1]?.id ?? null;
+        setSelectedId(nextId);
+        return;
+      }
       if (selectedId === "__cold__") {
-        const coldSessions = sessionTree.sessions.filter(
-          (s) => s.status === "cold"
-        );
+        const coldSessions = sessionTree.coldProjects?.flatMap((p) => p.sessions) ?? [];
         for (const s of coldSessions) hideSession(s.hideKey);
         const nextId = allFlat[selectedIndex - 1]?.id ?? null;
         refresh();
         setSelectedId(nextId);
         return;
       }
-      const selectedSession2 = sessionTree.sessions.find(
-        (s) => s.id === selectedId
-      );
+      const allSessions4 = sessionTree.projects?.flatMap((p) => p.sessions) ?? [];
+      const selectedSession2 = allSessions4.find((s) => s.id === selectedId);
       if (selectedSession2) {
         hideSession(selectedSession2.hideKey);
         const nextId = allFlat[selectedIndex + 1]?.id ?? allFlat[selectedIndex - 1]?.id ?? null;
@@ -2207,7 +2700,7 @@ function App({ mode }) {
         setSelectedId(nextId);
         return;
       }
-      for (const s of sessionTree.sessions) {
+      for (const s of allSessions4) {
         const selectedSubAgent = s.subAgents.find((sa) => sa.id === selectedId);
         if (selectedSubAgent) {
           hideSubAgent(selectedSubAgent.hideKey);
@@ -2225,55 +2718,67 @@ function App({ mode }) {
     filterLabel
   });
   useInput((input, key) => handleInput(input, key), { isActive: isWatchMode });
-  const selectedSession = allFlat.find((s) => s.id === selectedId);
+  const rawSelected = allFlat.find((s) => s.id === selectedId);
+  const isProjectSentinel = !!selectedId && selectedId.startsWith("__proj-") && selectedId.endsWith("__");
+  let selectedSession = rawSelected;
+  if (isProjectSentinel && selectedId) {
+    const projectName = selectedId.slice(7, -2);
+    const project = sessionTree.projects.find((p) => p.name === projectName) ?? sessionTree.coldProjects.find((p) => p.name === projectName);
+    if (project && project.sessions.length > 0) {
+      selectedSession = project.sessions[0];
+    }
+  }
   const isPlaceholderSelected = !selectedSession || selectedId === "__cold__" || !!selectedId && selectedId.startsWith("__sub-") && selectedId.endsWith("__");
   const sessionDisplayName = isPlaceholderSelected ? "No session selected" : selectedSession.projectPath ? selectedSession.projectName || selectedSession.id.slice(0, 8) : selectedSession.agentId ?? selectedSession.id.slice(0, 8);
-  return /* @__PURE__ */ jsxs4(Box4, { flexDirection: "column", children: [
-    migrationWarning && /* @__PURE__ */ jsx4(Box4, { marginBottom: 1, children: /* @__PURE__ */ jsx4(Text4, { color: "yellow", children: "Config moved to ~/.agenthud/config.yaml" }) }),
-    isWatchMode && /* @__PURE__ */ jsxs4(Box4, { marginBottom: 1, justifyContent: "space-between", width, children: [
-      /* @__PURE__ */ jsxs4(Text4, { dimColor: true, children: [
+  return /* @__PURE__ */ jsxs5(Box5, { flexDirection: "column", children: [
+    isWatchMode && /* @__PURE__ */ jsxs5(Box5, { marginBottom: 1, justifyContent: "space-between", width, children: [
+      /* @__PURE__ */ jsxs5(Text5, { dimColor: true, children: [
         spinner,
         " AgentHUD v",
         getVersion()
       ] }),
-      /* @__PURE__ */ jsx4(Text4, { dimColor: true, children: statusBarItems.join(" \xB7 ") })
+      /* @__PURE__ */ jsx5(Text5, { dimColor: true, children: statusBarItems.join(" \xB7 ") })
     ] }),
-    /* @__PURE__ */ jsx4(
-      SessionTreePanel,
-      {
-        sessions: sessionTree.sessions,
-        selectedId,
-        hasFocus: focus === "tree",
-        width,
-        maxRows: treeRows,
-        expandedIds
-      }
-    ),
-    /* @__PURE__ */ jsx4(Box4, { marginTop: 1, children: detailMode && detailActivity ? /* @__PURE__ */ jsx4(
-      DetailViewPanel,
-      {
-        activity: detailActivity,
-        sessionName: sessionDisplayName,
-        scrollOffset: detailScrollOffset,
-        visibleRows: viewerRows,
-        width
-      }
-    ) : /* @__PURE__ */ jsx4(
-      ActivityViewerPanel,
-      {
-        activities: mergedActivities,
-        sessionName: sessionDisplayName,
-        scrollOffset,
-        isLive,
-        newCount,
-        visibleRows: viewerRows,
-        width,
-        cursorLine: viewerCursorLine,
-        hasFocus: focus === "viewer",
-        spinner,
-        filterLabel
-      }
-    ) })
+    helpMode ? /* @__PURE__ */ jsx5(HelpPanel, { width, height: height - 2 }) : /* @__PURE__ */ jsxs5(Fragment2, { children: [
+      migrationWarning && /* @__PURE__ */ jsx5(Box5, { marginBottom: 1, children: /* @__PURE__ */ jsx5(Text5, { color: "yellow", children: "Config moved to ~/.agenthud/config.yaml" }) }),
+      /* @__PURE__ */ jsx5(
+        SessionTreePanel,
+        {
+          projects: sessionTree.projects ?? [],
+          coldProjects: sessionTree.coldProjects ?? [],
+          selectedId,
+          hasFocus: focus === "tree",
+          width,
+          maxRows: treeRows,
+          expandedIds
+        }
+      ),
+      /* @__PURE__ */ jsx5(Box5, { marginTop: 1, children: detailMode && detailActivity ? /* @__PURE__ */ jsx5(
+        DetailViewPanel,
+        {
+          activity: detailActivity,
+          sessionName: sessionDisplayName,
+          scrollOffset: detailScrollOffset,
+          visibleRows: viewerRows,
+          width
+        }
+      ) : /* @__PURE__ */ jsx5(
+        ActivityViewerPanel,
+        {
+          activities: mergedActivities,
+          sessionName: sessionDisplayName,
+          scrollOffset,
+          isLive,
+          newCount,
+          visibleRows: viewerRows,
+          width,
+          cursorLine: viewerCursorLine,
+          hasFocus: focus === "viewer",
+          spinner,
+          filterLabel
+        }
+      ) })
+    ] })
   ] });
 }