agenthud 0.9.3 → 0.9.4

package/README.md

@@ -4,10 +4,16 @@
 [![CI](https://github.com/neochoon/agenthud/actions/workflows/ci.yml/badge.svg)](https://github.com/neochoon/agenthud/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/neochoon/agenthud/branch/main/graph/badge.svg)](https://codecov.io/gh/neochoon/agenthud)
 
-When working with AI coding agents like Claude Code, you lose visibility into what's happening across sessions. **AgentHUD** gives you a live session browser in a separate terminal — see every session, sub-agent, and activity as it happens.
+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)
 
+AgentHUD reads Claude Code's session files from `~/.claude/projects/` and gives you three things:
+
+- **Live monitor** ([`agenthud`](#live-monitor)) — a split-view TUI showing every project, session, sub-agent, and activity as it happens.
+- **Structured export** ([`agenthud report`](#report)) — print activity for any date as Markdown or JSON for piping to scripts, dashboards, or other LLMs.
+- **LLM digest** ([`agenthud summary`](#summary)) — synthesize a day or a date range into an engineering summary via the `claude` CLI, with caching so weekly digests are cheap to regenerate.
+
 ## Install
 
 Requires Node.js 20+.
@@ -18,9 +24,9 @@ npx agenthud
 
 Run this in a separate terminal while using Claude Code. Press `?` inside the TUI any time for in-app help.
 
-## What it shows
+## Live monitor
 
-AgentHUD reads Claude Code's session files from `~/.claude/projects/` and displays them in a split view:
+AgentHUD's TUI splits the screen into a project tree and an activity viewer:
 
 ```
 ┌─ Projects ───────────────────────────────────────────────┐
@@ -57,7 +63,7 @@ AgentHUD reads Claude Code's session files from `~/.claude/projects/` and displa
 - Press `f` to cycle through filter presets (configurable).
 - Press `↵` on any row to open a scrollable detail view; on a commit row this shows `git show --stat --patch`.
 
-## Session status
+### Session status
 
 Each session row carries a colored badge derived from when its JSONL file was last touched:
 
@@ -70,7 +76,7 @@ Each session row carries a colored badge derived from when its JSONL file was la
 
 Sub-agents use the same scheme. Projects inherit the hottest status of their sessions; a project is treated as "cold" only when all its sessions are cold.
 
-## Activity types
+### Activity types
 
 | Icon | Type | Description |
 |------|------|-------------|
@@ -85,11 +91,11 @@ Sub-agents use the same scheme. Projects inherit the hottest status of their ses
 | `…` | Thinking | Claude's thinking (requires `showThinkingSummaries: true`) |
 | `◆` | Commit | Git commit in the project (when `--with-git` or in viewer) |
 
-## Keyboard shortcuts
+### Keyboard shortcuts
 
 Full reference is also available inside the app — press `?`.
 
-### Project tree focus
+#### Project tree focus
 
 | Key | Action |
 |-----|--------|
@@ -104,7 +110,7 @@ Full reference is also available inside the app — press `?`.
 | `?` | Help |
 | `q` | Quit |
 
-### Activity viewer focus
+#### Activity viewer focus
 
 | Key | Action |
 |-----|--------|
@@ -122,7 +128,7 @@ Full reference is also available inside the app — press `?`.
 | `?` | Help |
 | `q` | Quit |
 
-### Detail view
+#### Detail view
 
 | Key | Action |
 |-----|--------|
@@ -134,7 +140,7 @@ Detail view colors the content based on activity type:
 - **Git commit detail** (`git show --stat --patch`): added lines green (`+`), removed lines red (`-`), hunk headers cyan (`@@ ... @@`), `commit/Author/Date/diff` metadata dimmed.
 - **Response / thinking / prompt**: text inside triple-backtick code fences renders in cyan so the boundary between prose and code is obvious. No language-specific syntax highlighting — just code-vs-prose separation.
 
-## Behavior
+### Behavior
 
 - **Alternate screen buffer.** Watch mode uses the alt-screen (like `vim`, `htop`, `btop`), so quitting (`q`) restores the pre-launch shell completely. No TUI residue, no "is it still running?" confusion.
 - **Minimum terminal size.** 80 cols × 20 rows. Smaller terminals show a one-line hint and redraw automatically when you resize.
@@ -194,6 +200,10 @@ agenthud summary --prompt "Only commits"    # override prompt
 agenthud summary --last 7d                          # last 7 days, ending today
 agenthud summary --from 2026-05-10 --to 2026-05-16  # explicit range
 agenthud summary --last 7d -y                       # skip per-day confirmations
+
+# Cheaper model — summarization doesn't need Opus-tier reasoning
+agenthud summary --date today --model sonnet        # ~40% cheaper than Opus
+agenthud summary --last 7d --model haiku            # ~80% cheaper, 200K context
 ```
 
 **Daily summaries** are saved to `~/.agenthud/summaries/YYYY-MM-DD.md`. Past dates are cached and returned instantly; today is always regenerated (activity still growing).
@@ -206,6 +216,10 @@ Each missing daily prompts for confirmation just before generation, so you see c
 
 **`--date` formats:** `YYYY-MM-DD`, `today`, `yesterday`, or `-Nd` (N days ago).
 
+**Model selection:** Summarization is a low-reasoning task (structured input → structured markdown) — Sonnet or Haiku usually beats Opus on cost-per-summary with no quality loss. Pass `--model sonnet`, `--model haiku`, or a full model id (`--model claude-sonnet-4-6`). With no flag, `claude` uses its default model.
+
+**Cost warning:** If the day's activity log is large (~300K tokens or more), AgentHUD prints a warning before sending and asks for one more confirmation in interactive mode. `-y` skips the prompt but still prints the warning.
+
 **Requires:** [`@anthropic-ai/claude-code`](https://www.npmjs.com/package/@anthropic-ai/claude-code) installed and authenticated.
 
 ## Configuration

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-S27FZ2BJ.js");
+import("./main-26QL33AJ.js");

package/dist/{main-S27FZ2BJ.js → main-26QL33AJ.js}

@@ -53,6 +53,7 @@ var KNOWN_SUMMARY_FLAGS = /* @__PURE__ */ new Set([
   "--to",
   "--prompt",
   "--force",
+  "--model",
   "-y",
   "--yes"
 ]);
@@ -89,6 +90,7 @@ Commands:
     --to YYYY-MM-DD             Date range: end date (use with --from)
     --prompt TEXT               Override prompt for this run (daily only)
     --force                     Regenerate even if cached
+    --model NAME                Pass --model to claude (e.g. "sonnet", "haiku", or a full model ID)
     -y, --yes                   Skip confirmation prompts for new daily summaries
 
 Environment:
@@ -172,10 +174,18 @@ function parseArgs(args) {
     const includeIdx = rest.indexOf("--include");
     if (includeIdx !== -1) {
       const includeStr = rest[includeIdx + 1];
-      if (includeStr === "all") {
+      if (!includeStr) {
+        reportError = "Invalid --include: missing value.";
+      } else if (includeStr === "all") {
         reportInclude = ALL_TYPES;
-      } else if (includeStr) {
-        reportInclude = includeStr.split(",").map((s) => s.trim()).filter(Boolean);
+      } else {
+        const tokens = includeStr.split(",").map((s) => s.trim()).filter(Boolean);
+        const unknown = tokens.filter((t) => !ALL_TYPES.includes(t));
+        if (unknown.length > 0) {
+          reportError = `Unknown --include type${unknown.length > 1 ? "s" : ""}: ${unknown.map((u) => `"${u}"`).join(", ")}. Valid types: ${ALL_TYPES.join(", ")} (or "all").`;
+        } else {
+          reportInclude = tokens;
+        }
       }
     }
     let reportFormat = "markdown";
@@ -220,13 +230,15 @@ function parseArgs(args) {
     let summaryPrompt;
     let summaryForce = false;
     let summaryAssumeYes = false;
+    let summaryModel;
     let summaryError;
     const FLAGS_WITH_VALUE = /* @__PURE__ */ new Set([
       "--date",
       "--last",
       "--from",
       "--to",
-      "--prompt"
+      "--prompt",
+      "--model"
     ]);
     for (let i = 0; i < rest.length; i++) {
       const arg = rest[i];
@@ -318,6 +330,15 @@ function parseArgs(args) {
         summaryPrompt = val;
       }
     }
+    const modelIdx = rest.indexOf("--model");
+    if (modelIdx !== -1) {
+      const val = rest[modelIdx + 1];
+      if (!val) {
+        summaryError = "Invalid --model: missing value (e.g. --model sonnet).";
+      } else {
+        summaryModel = val;
+      }
+    }
     if (rest.includes("--force")) summaryForce = true;
     if (rest.includes("-y") || rest.includes("--yes")) summaryAssumeYes = true;
     return {
@@ -328,6 +349,7 @@ function parseArgs(args) {
       summaryPrompt,
       summaryForce,
       summaryAssumeYes,
+      summaryModel,
       summaryError
     };
   }
@@ -1391,16 +1413,18 @@ function formatUsage(u) {
 }
 function spawnClaude(opts) {
   return new Promise((resolve2) => {
+    const args = [
+      "-p",
+      "--no-session-persistence",
+      "--output-format",
+      "stream-json",
+      "--verbose"
+    ];
+    if (opts.model) args.push("--model", opts.model);
+    args.push(opts.prompt);
     const proc = spawn(
       "claude",
-      [
-        "-p",
-        "--no-session-persistence",
-        "--output-format",
-        "stream-json",
-        "--verbose",
-        opts.prompt
-      ],
+      args,
       {
         stdio: ["pipe", "pipe", "pipe"],
         cwd: agenthudHomeDir()
@@ -1513,6 +1537,7 @@ function spawnClaude(opts) {
     proc.stdin.end(opts.stdin);
   });
 }
+var REPORT_TOKEN_WARN_THRESHOLD = 3e5;
 async function generateDailySummary(opts) {
   ensureUserPromptFile("daily");
   const isToday = isSameLocalDay2(opts.date, opts.today);
@@ -1556,6 +1581,8 @@ async function generateDailySummary(opts) {
     detailLimit: 0,
     withGit: true
   });
+  const reportBytes = Buffer.byteLength(reportMarkdown, "utf-8");
+  const estimatedTokens = Math.ceil(reportBytes / 4);
   if (opts.announce) {
     const reportLines = reportMarkdown.split("\n");
     const sessionCount = reportLines.filter((l) => l.startsWith("## ")).length;
@@ -1565,11 +1592,9 @@ async function generateDailySummary(opts) {
     const commitCount = reportLines.filter(
       (l) => /^\[\d{2}:\d{2}\] ◆/.test(l)
     ).length;
-    const sizeKb = (Buffer.byteLength(reportMarkdown, "utf-8") / 1024).toFixed(
-      1
-    );
+    const sizeKb = (reportBytes / 1024).toFixed(1);
     process.stderr.write(
-      `agenthud: input: ${sessionCount} sessions, ${activityCount} activities, ${commitCount} commits (${reportLines.length} lines, ${sizeKb}KB)
+      `agenthud: input: ${sessionCount} sessions, ${activityCount} activities, ${commitCount} commits (${reportLines.length} lines, ${sizeKb}KB \u2248 ${estimatedTokens.toLocaleString()} tokens)
 `
     );
   }
@@ -1585,6 +1610,29 @@ async function generateDailySummary(opts) {
       };
     }
   }
+  if (estimatedTokens > REPORT_TOKEN_WARN_THRESHOLD) {
+    const sizeMb = (reportBytes / (1024 * 1024)).toFixed(1);
+    process.stderr.write(
+      `agenthud: \u26A0 report is large (~${estimatedTokens.toLocaleString()} tokens, ${sizeMb}MB). Cost will be high; very long reports may exceed context.
+`
+    );
+    if (!opts.assumeYes) {
+      const proceed = await ask("Send anyway? [Y/n] ", true);
+      if (!proceed) {
+        process.stderr.write(
+          `agenthud: ${dateLabel} \u2014 aborted (report too large).
+`
+        );
+        return {
+          code: 0,
+          markdown: "",
+          fromCache: false,
+          skipped: true,
+          usage: null
+        };
+      }
+    }
+  }
   if (opts.announce) {
     process.stderr.write(
       `agenthud: sending to claude (this may take a minute)...
@@ -1597,7 +1645,8 @@ async function generateDailySummary(opts) {
     prompt,
     stdin: reportMarkdown,
     cachePath: cached,
-    streamToStdout: opts.streamToStdout
+    streamToStdout: opts.streamToStdout,
+    model: opts.model
   });
   if (opts.announce && result.code === 0) {
     process.stderr.write("\n");
@@ -1623,7 +1672,8 @@ async function runSummary(options2) {
     force: options2.force,
     promptOverride: options2.prompt,
     streamToStdout: true,
-    announce: true
+    announce: true,
+    model: options2.model
   });
   return res.code;
 }
@@ -1686,7 +1736,9 @@ agenthud: --- ${label} ---
       force: false,
       streamToStdout: false,
       announce: true,
-      confirmBeforeSpawn: confirmer
+      confirmBeforeSpawn: confirmer,
+      assumeYes: options2.assumeYes,
+      model: options2.model
     });
     if (res.skipped) {
       process.stderr.write(`agenthud: ${label} \u2014 skipped by user.
@@ -1731,7 +1783,8 @@ agenthud: combining ${dailyMarkdowns.length} daily summaries into range summary.
     prompt: metaPrompt,
     stdin: metaInput,
     cachePath: rangeCache,
-    streamToStdout: true
+    streamToStdout: true,
+    model: options2.model
   });
   if (metaResult.code !== 0) {
     return metaResult.code;
@@ -3591,7 +3644,8 @@ if (options.mode === "summary") {
       to: options.summaryTo,
       today,
       force: options.summaryForce ?? false,
-      assumeYes: options.summaryAssumeYes ?? false
+      assumeYes: options.summaryAssumeYes ?? false,
+      model: options.summaryModel
     });
     process.exit(exitCode2);
   }
@@ -3599,7 +3653,8 @@ if (options.mode === "summary") {
     date: options.summaryDate,
     prompt: options.summaryPrompt,
     force: options.summaryForce ?? false,
-    today
+    today,
+    model: options.summaryModel
   });
   process.exit(exitCode);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agenthud",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "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",