agenthud 0.1.0

package/README.md

@@ -0,0 +1,66 @@
+# agenthud
+
+Terminal dashboard for AI agent development.
+
+```
+┌─ Git ────────────────────────────────────────────────────┐
+│ main · +1068 -166 · 12 commits · 23 files                │
+│ • 1d00dc0 refactor: rename project from agent-dashboa... │
+│ • 3529727 fix: Decisions separator line width now mat... │
+│ • d7652c4 fix: use proper box character for Decisions... │
+│ • 1594987 feat: move progress bar to Plan title line     │
+│ • d5a9f4d feat: improve Plan panel and Tests panel di... │
+└──────────────────────────────────────────────────────────┘
+
+┌─ Plan ─────────────────────────────────── 7/10 ███████░░░┐
+│ Build agenthud CLI tool                                  │
+│ ✓ Set up project (npm, TypeScript, Vitest)               │
+│ ✓ Implement git data collection module                   │
+│ ✓ Create GitPanel UI component                           │
+│ ✓ Add CLI entry point with watch mode                    │
+│ ✓ Fix getTodayStats bug                                  │
+│ ○ Add --dir flag for project directory                   │
+│ ○ Add --json flag for JSON output                        │
+│ ✓ Add PlanPanel component                                │
+│ ✓ Add TestPanel component                                │
+│ ○ Publish to npm                                         │
+├─ Decisions ──────────────────────────────────────────────┤
+│ • Use dependency injection for git module testing        │
+│ • Use Ink for terminal UI                                │
+│ • Use git log --numstat for stats instead of git diff... │
+└──────────────────────────────────────────────────────────┘
+
+┌─ Tests ──────────────────────────────────────────────────┐
+│ ⚠ Outdated (1 commit behind)                             │
+│ ✓ 70 passed · 3529727 · 40m ago                          │
+└──────────────────────────────────────────────────────────┘
+```
+
+## Install
+```bash
+npx agenthud
+```
+
+## Features
+
+- **Git**: Branch, commits, line changes
+- **Plan**: Progress, decisions from `.agent/plan.json`
+- **Tests**: Results with outdated detection
+
+## Setup
+
+Add to your `CLAUDE.md`:
+```markdown
+Maintain `.agent/` directory:
+- Update `plan.json` when plan changes
+- Update `decisions.json` for key decisions
+```
+
+## Keyboard
+
+- `q` - quit
+- `r` - refresh
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,514 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import React2 from "react";
+import { render } from "ink";
+
+// src/ui/App.tsx
+import { useState, useEffect, useCallback } from "react";
+import { Box as Box4, Text as Text4, useApp, useInput } from "ink";
+
+// src/ui/GitPanel.tsx
+import { Box, Text } from "ink";
+
+// src/ui/constants.ts
+var PANEL_WIDTH = 60;
+var CONTENT_WIDTH = PANEL_WIDTH - 4;
+var SEPARATOR = "\u2500".repeat(CONTENT_WIDTH);
+function truncate(text, maxLength) {
+  if (text.length <= maxLength) return text;
+  return text.slice(0, maxLength - 3) + "...";
+}
+
+// src/ui/GitPanel.tsx
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+var MAX_COMMITS = 5;
+var MAX_MESSAGE_LENGTH = CONTENT_WIDTH - 10;
+function GitPanel({ branch, commits, stats }) {
+  if (branch === null) {
+    return /* @__PURE__ */ jsxs(Box, { flexDirection: "column", borderStyle: "single", paddingX: 1, width: PANEL_WIDTH, children: [
+      /* @__PURE__ */ jsx(Box, { marginTop: -1, children: /* @__PURE__ */ jsx(Text, { children: " Git " }) }),
+      /* @__PURE__ */ jsx(Text, { dimColor: true, children: "Not a git repository" })
+    ] });
+  }
+  const displayCommits = commits.slice(0, MAX_COMMITS);
+  const hasCommits = commits.length > 0;
+  const commitWord = commits.length === 1 ? "commit" : "commits";
+  const fileWord = stats.files === 1 ? "file" : "files";
+  return /* @__PURE__ */ jsxs(Box, { flexDirection: "column", borderStyle: "single", paddingX: 1, width: PANEL_WIDTH, children: [
+    /* @__PURE__ */ jsx(Box, { marginTop: -1, children: /* @__PURE__ */ jsx(Text, { children: " Git " }) }),
+    /* @__PURE__ */ jsxs(Text, { children: [
+      /* @__PURE__ */ jsx(Text, { color: "green", children: branch }),
+      hasCommits && /* @__PURE__ */ jsxs(Fragment, { children: [
+        /* @__PURE__ */ jsx(Text, { dimColor: true, children: " \xB7 " }),
+        /* @__PURE__ */ jsxs(Text, { color: "green", children: [
+          "+",
+          stats.added
+        ] }),
+        /* @__PURE__ */ jsx(Text, { children: " " }),
+        /* @__PURE__ */ jsxs(Text, { color: "red", children: [
+          "-",
+          stats.deleted
+        ] }),
+        /* @__PURE__ */ jsxs(Text, { dimColor: true, children: [
+          " \xB7 ",
+          commits.length,
+          " ",
+          commitWord,
+          " \xB7 ",
+          stats.files,
+          " ",
+          fileWord
+        ] })
+      ] })
+    ] }),
+    hasCommits ? /* @__PURE__ */ jsx(Fragment, { children: displayCommits.map((commit) => /* @__PURE__ */ jsxs(Text, { children: [
+      "\u2022 ",
+      /* @__PURE__ */ jsx(Text, { dimColor: true, children: commit.hash.slice(0, 7) }),
+      " ",
+      truncate(commit.message, MAX_MESSAGE_LENGTH)
+    ] }, commit.hash)) }) : /* @__PURE__ */ jsx(Text, { dimColor: true, children: "No commits today" })
+  ] });
+}
+
+// src/ui/PlanPanel.tsx
+import { Box as Box2, Text as Text2 } from "ink";
+import { Fragment as Fragment2, jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
+var BOX = { tl: "\u250C", tr: "\u2510", bl: "\u2514", br: "\u2518", h: "\u2500", v: "\u2502" };
+var PROGRESS_BAR_WIDTH = 10;
+var MAX_STEP_LENGTH = CONTENT_WIDTH - 2;
+var MAX_DECISION_LENGTH = CONTENT_WIDTH - 2;
+function createProgressBar(done, total) {
+  if (total === 0) return "\u2591".repeat(PROGRESS_BAR_WIDTH);
+  const filled = Math.round(done / total * PROGRESS_BAR_WIDTH);
+  const empty = PROGRESS_BAR_WIDTH - filled;
+  return "\u2588".repeat(filled) + "\u2591".repeat(empty);
+}
+var INNER_WIDTH = PANEL_WIDTH - 2;
+function createTitleLine(done, total) {
+  const label = " Plan ";
+  const count = ` ${done}/${total} `;
+  const bar = createProgressBar(done, total);
+  const dashCount = PANEL_WIDTH - 3 - label.length - count.length - bar.length;
+  const dashes = BOX.h.repeat(Math.max(0, dashCount));
+  return BOX.tl + BOX.h + label + dashes + count + bar + BOX.tr;
+}
+function createBottomLine() {
+  return BOX.bl + BOX.h.repeat(INNER_WIDTH) + BOX.br;
+}
+function padLine(content) {
+  const padding = INNER_WIDTH - content.length;
+  return content + " ".repeat(Math.max(0, padding));
+}
+function createDecisionsHeader() {
+  const label = "\u2500 Decisions ";
+  const dashCount = PANEL_WIDTH - 1 - label.length - 1;
+  return label + "\u2500".repeat(dashCount) + "\u2524";
+}
+function PlanPanel({ plan, decisions, error }) {
+  if (error || !plan) {
+    return /* @__PURE__ */ jsxs2(Box2, { flexDirection: "column", width: PANEL_WIDTH, children: [
+      /* @__PURE__ */ jsxs2(Text2, { children: [
+        BOX.tl,
+        BOX.h,
+        " Plan ",
+        BOX.h.repeat(INNER_WIDTH - 7),
+        BOX.tr
+      ] }),
+      /* @__PURE__ */ jsxs2(Text2, { children: [
+        BOX.v,
+        padLine(" " + (error || "No plan found")),
+        BOX.v
+      ] }),
+      /* @__PURE__ */ jsx2(Text2, { children: createBottomLine() })
+    ] });
+  }
+  const doneCount = plan.steps.filter((s) => s.status === "done").length;
+  const totalCount = plan.steps.length;
+  return /* @__PURE__ */ jsxs2(Box2, { flexDirection: "column", width: PANEL_WIDTH, children: [
+    /* @__PURE__ */ jsx2(Text2, { children: createTitleLine(doneCount, totalCount) }),
+    /* @__PURE__ */ jsxs2(Text2, { children: [
+      BOX.v,
+      padLine(" " + truncate(plan.goal, CONTENT_WIDTH)),
+      BOX.v
+    ] }),
+    plan.steps.map((step, index) => {
+      const stepText = " " + (step.status === "done" ? "\u2713" : step.status === "in-progress" ? "\u2192" : "\u25CB") + " " + truncate(step.step, MAX_STEP_LENGTH);
+      return /* @__PURE__ */ jsxs2(Text2, { children: [
+        BOX.v,
+        padLine(stepText),
+        BOX.v
+      ] }, index);
+    }),
+    decisions.length > 0 && /* @__PURE__ */ jsxs2(Fragment2, { children: [
+      /* @__PURE__ */ jsxs2(Text2, { children: [
+        "\u251C",
+        /* @__PURE__ */ jsx2(Text2, { dimColor: true, children: createDecisionsHeader() })
+      ] }),
+      decisions.map((decision, index) => {
+        const decText = " \u2022 " + truncate(decision.decision, MAX_DECISION_LENGTH);
+        return /* @__PURE__ */ jsxs2(Text2, { children: [
+          BOX.v,
+          /* @__PURE__ */ jsx2(Text2, { dimColor: true, children: padLine(decText) }),
+          BOX.v
+        ] }, index);
+      })
+    ] }),
+    /* @__PURE__ */ jsx2(Text2, { children: createBottomLine() })
+  ] });
+}
+
+// src/ui/TestPanel.tsx
+import { Box as Box3, Text as Text3 } from "ink";
+import { Fragment as Fragment3, jsx as jsx3, jsxs as jsxs3 } from "react/jsx-runtime";
+function formatRelativeTime(timestamp) {
+  const now = Date.now();
+  const then = new Date(timestamp).getTime();
+  const diffMs = now - then;
+  const diffMins = Math.floor(diffMs / 6e4);
+  const diffHours = Math.floor(diffMs / 36e5);
+  const diffDays = Math.floor(diffMs / 864e5);
+  if (diffMins < 1) return "just now";
+  if (diffMins < 60) return `${diffMins}m ago`;
+  if (diffHours < 24) return `${diffHours}h ago`;
+  return `${diffDays}d ago`;
+}
+function TestPanel({
+  results,
+  isOutdated,
+  commitsBehind,
+  error
+}) {
+  if (error || !results) {
+    return /* @__PURE__ */ jsxs3(Box3, { flexDirection: "column", borderStyle: "single", paddingX: 1, width: PANEL_WIDTH, children: [
+      /* @__PURE__ */ jsx3(Box3, { marginTop: -1, children: /* @__PURE__ */ jsx3(Text3, { children: " Tests " }) }),
+      /* @__PURE__ */ jsx3(Text3, { dimColor: true, children: error || "No test results" })
+    ] });
+  }
+  const hasFailures = results.failures.length > 0;
+  const relativeTime = formatRelativeTime(results.timestamp);
+  return /* @__PURE__ */ jsxs3(Box3, { flexDirection: "column", borderStyle: "single", paddingX: 1, width: PANEL_WIDTH, children: [
+    /* @__PURE__ */ jsx3(Box3, { marginTop: -1, children: /* @__PURE__ */ jsx3(Text3, { children: " Tests " }) }),
+    isOutdated && /* @__PURE__ */ jsxs3(Text3, { color: "yellow", children: [
+      "\u26A0 Outdated (",
+      commitsBehind,
+      " ",
+      commitsBehind === 1 ? "commit" : "commits",
+      " behind)"
+    ] }),
+    /* @__PURE__ */ jsxs3(Text3, { children: [
+      /* @__PURE__ */ jsxs3(Text3, { color: "green", children: [
+        "\u2713 ",
+        results.passed,
+        " passed"
+      ] }),
+      results.failed > 0 && /* @__PURE__ */ jsxs3(Fragment3, { children: [
+        "  ",
+        /* @__PURE__ */ jsxs3(Text3, { color: "red", children: [
+          "\u2717 ",
+          results.failed,
+          " failed"
+        ] })
+      ] }),
+      results.skipped > 0 && /* @__PURE__ */ jsxs3(Fragment3, { children: [
+        "  ",
+        /* @__PURE__ */ jsxs3(Text3, { dimColor: true, children: [
+          "\u25CB ",
+          results.skipped,
+          " skipped"
+        ] })
+      ] }),
+      /* @__PURE__ */ jsxs3(Text3, { dimColor: true, children: [
+        " ",
+        "\xB7 ",
+        results.hash,
+        " \xB7 ",
+        relativeTime
+      ] })
+    ] }),
+    hasFailures && /* @__PURE__ */ jsxs3(Fragment3, { children: [
+      /* @__PURE__ */ jsx3(Text3, { dimColor: true, children: SEPARATOR }),
+      results.failures.map((failure, index) => /* @__PURE__ */ jsxs3(Box3, { flexDirection: "column", children: [
+        /* @__PURE__ */ jsxs3(Text3, { color: "red", children: [
+          "\u2717 ",
+          truncate(failure.file, CONTENT_WIDTH - 2)
+        ] }),
+        /* @__PURE__ */ jsxs3(Text3, { children: [
+          "  ",
+          "\u2022 ",
+          truncate(failure.name, CONTENT_WIDTH - 4)
+        ] })
+      ] }, index))
+    ] })
+  ] });
+}
+
+// src/data/git.ts
+import { execSync as nodeExecSync } from "child_process";
+var execFn = (command, options2) => nodeExecSync(command, options2);
+function getCurrentBranch() {
+  try {
+    const result = execFn("git branch --show-current", {
+      encoding: "utf-8"
+    });
+    return result.trim();
+  } catch {
+    return null;
+  }
+}
+function getTodayCommits() {
+  try {
+    const result = execFn('git log --since=midnight --format="%h|%aI|%s"', {
+      encoding: "utf-8"
+    });
+    const lines = result.trim().split("\n").filter(Boolean);
+    return lines.map((line) => {
+      const [hash, timestamp, ...messageParts] = line.split("|");
+      return {
+        hash,
+        message: messageParts.join("|"),
+        timestamp: new Date(timestamp)
+      };
+    });
+  } catch {
+    return [];
+  }
+}
+function getTodayStats() {
+  try {
+    const result = execFn('git log --since=midnight --numstat --format=""', {
+      encoding: "utf-8"
+    });
+    const lines = result.trim().split("\n").filter(Boolean);
+    let added = 0;
+    let deleted = 0;
+    const filesSet = /* @__PURE__ */ new Set();
+    for (const line of lines) {
+      const [addedStr, deletedStr, filename] = line.split("	");
+      if (addedStr === "-" || deletedStr === "-") {
+        if (filename) filesSet.add(filename);
+        continue;
+      }
+      added += parseInt(addedStr, 10) || 0;
+      deleted += parseInt(deletedStr, 10) || 0;
+      if (filename) filesSet.add(filename);
+    }
+    return { added, deleted, files: filesSet.size };
+  } catch {
+    return { added: 0, deleted: 0, files: 0 };
+  }
+}
+
+// src/data/plan.ts
+import { readFileSync as nodeReadFileSync } from "fs";
+import { join } from "path";
+var AGENT_DIR = ".agent";
+var PLAN_FILE = "plan.json";
+var DECISIONS_FILE = "decisions.json";
+var MAX_DECISIONS = 3;
+var readFileFn = (path) => nodeReadFileSync(path, "utf-8");
+function getPlanData(dir = process.cwd()) {
+  const planPath = join(dir, AGENT_DIR, PLAN_FILE);
+  const decisionsPath = join(dir, AGENT_DIR, DECISIONS_FILE);
+  let plan = null;
+  let decisions = [];
+  let error;
+  try {
+    const content = readFileFn(planPath);
+    plan = JSON.parse(content);
+  } catch (e) {
+    if (e instanceof SyntaxError) {
+      error = "Invalid plan.json";
+    } else {
+      error = "No plan found";
+    }
+    plan = null;
+  }
+  try {
+    const content = readFileFn(decisionsPath);
+    const parsed = JSON.parse(content);
+    decisions = (parsed.decisions || []).slice(0, MAX_DECISIONS);
+  } catch {
+    decisions = [];
+  }
+  return { plan, decisions, error };
+}
+
+// src/data/tests.ts
+import { readFileSync as nodeReadFileSync2 } from "fs";
+import { execSync as nodeExecSync2 } from "child_process";
+import { join as join2 } from "path";
+var AGENT_DIR2 = ".agent";
+var TEST_RESULTS_FILE = "test-results.json";
+var readFileFn2 = (path) => nodeReadFileSync2(path, "utf-8");
+var getHeadHashFn = () => {
+  return nodeExecSync2("git rev-parse --short HEAD", { encoding: "utf-8" }).trim();
+};
+var getCommitCountFn = (fromHash) => {
+  const result = nodeExecSync2(`git rev-list ${fromHash}..HEAD --count`, {
+    encoding: "utf-8"
+  }).trim();
+  return parseInt(result, 10) || 0;
+};
+function getTestData(dir = process.cwd()) {
+  const testResultsPath = join2(dir, AGENT_DIR2, TEST_RESULTS_FILE);
+  let results = null;
+  let isOutdated = false;
+  let commitsBehind = 0;
+  let error;
+  try {
+    const content = readFileFn2(testResultsPath);
+    results = JSON.parse(content);
+  } catch (e) {
+    if (e instanceof SyntaxError) {
+      error = "Invalid test-results.json";
+    } else {
+      error = "No test results";
+    }
+    return { results: null, isOutdated: false, commitsBehind: 0, error };
+  }
+  try {
+    const currentHash = getHeadHashFn();
+    if (results.hash !== currentHash) {
+      isOutdated = true;
+      commitsBehind = getCommitCountFn(results.hash);
+    }
+  } catch {
+    isOutdated = false;
+    commitsBehind = 0;
+  }
+  return { results, isOutdated, commitsBehind, error };
+}
+
+// src/ui/App.tsx
+import { jsx as jsx4, jsxs as jsxs4 } from "react/jsx-runtime";
+var REFRESH_INTERVAL = 5e3;
+var REFRESH_SECONDS = REFRESH_INTERVAL / 1e3;
+function useGitData() {
+  const [data, setData] = useState(() => ({
+    branch: getCurrentBranch(),
+    commits: getTodayCommits(),
+    stats: getTodayStats()
+  }));
+  const refresh = useCallback(() => {
+    setData({
+      branch: getCurrentBranch(),
+      commits: getTodayCommits(),
+      stats: getTodayStats()
+    });
+  }, []);
+  return [data, refresh];
+}
+function usePlanData() {
+  const [data, setData] = useState(() => getPlanData());
+  const refresh = useCallback(() => {
+    setData(getPlanData());
+  }, []);
+  return [data, refresh];
+}
+function useTestData() {
+  const [data, setData] = useState(() => getTestData());
+  const refresh = useCallback(() => {
+    setData(getTestData());
+  }, []);
+  return [data, refresh];
+}
+function App({ mode }) {
+  const { exit } = useApp();
+  const [gitData, refreshGit] = useGitData();
+  const [planData, refreshPlan] = usePlanData();
+  const [testData, refreshTest] = useTestData();
+  const [countdown, setCountdown] = useState(REFRESH_SECONDS);
+  const refreshAll = useCallback(() => {
+    refreshGit();
+    refreshPlan();
+    refreshTest();
+    setCountdown(REFRESH_SECONDS);
+  }, [refreshGit, refreshPlan, refreshTest]);
+  useEffect(() => {
+    if (mode !== "watch") return;
+    const interval = setInterval(refreshAll, REFRESH_INTERVAL);
+    return () => clearInterval(interval);
+  }, [mode, refreshAll]);
+  useEffect(() => {
+    if (mode !== "watch") return;
+    const tick = setInterval(() => {
+      setCountdown((prev) => prev > 1 ? prev - 1 : REFRESH_SECONDS);
+    }, 1e3);
+    return () => clearInterval(tick);
+  }, [mode]);
+  useInput(
+    (input) => {
+      if (mode !== "watch") return;
+      if (input === "q") {
+        exit();
+      }
+      if (input === "r") {
+        refreshAll();
+      }
+    },
+    { isActive: mode === "watch" }
+  );
+  return /* @__PURE__ */ jsxs4(Box4, { flexDirection: "column", children: [
+    /* @__PURE__ */ jsx4(Box4, { children: /* @__PURE__ */ jsx4(
+      GitPanel,
+      {
+        branch: gitData.branch,
+        commits: gitData.commits,
+        stats: gitData.stats
+      }
+    ) }),
+    /* @__PURE__ */ jsx4(Box4, { marginTop: 1, children: /* @__PURE__ */ jsx4(
+      PlanPanel,
+      {
+        plan: planData.plan,
+        decisions: planData.decisions,
+        error: planData.error
+      }
+    ) }),
+    /* @__PURE__ */ jsx4(Box4, { marginTop: 1, children: /* @__PURE__ */ jsx4(
+      TestPanel,
+      {
+        results: testData.results,
+        isOutdated: testData.isOutdated,
+        commitsBehind: testData.commitsBehind,
+        error: testData.error
+      }
+    ) }),
+    mode === "watch" && /* @__PURE__ */ jsx4(Box4, { marginTop: 1, width: PANEL_WIDTH, children: /* @__PURE__ */ jsxs4(Text4, { dimColor: true, children: [
+      "\u21BB ",
+      countdown,
+      "s \xB7 ",
+      /* @__PURE__ */ jsx4(Text4, { color: "cyan", children: "q:" }),
+      " quit \xB7 ",
+      /* @__PURE__ */ jsx4(Text4, { color: "cyan", children: "r:" }),
+      " refresh"
+    ] }) })
+  ] });
+}
+
+// src/cli.ts
+var clearFn = () => console.clear();
+function clearScreen() {
+  clearFn();
+}
+function parseArgs(args) {
+  const hasOnce = args.includes("--once");
+  const hasWatch = args.includes("--watch") || args.includes("-w");
+  if (hasOnce) {
+    return { mode: "once" };
+  }
+  return { mode: "watch" };
+}
+
+// src/index.ts
+var options = parseArgs(process.argv.slice(2));
+if (options.mode === "watch") {
+  clearScreen();
+}
+var { waitUntilExit } = render(React2.createElement(App, { mode: options.mode }));
+if (options.mode === "once") {
+  setTimeout(() => process.exit(0), 100);
+} else {
+  waitUntilExit().then(() => process.exit(0));
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "agenthud",
+  "version": "0.1.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",
+  "bin": {
+    "agenthud": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "scripts"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:save": "npx tsx scripts/save-test-results.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/neochoon/agenthud.git"
+  },
+  "keywords": [
+    "cli",
+    "agent",
+    "dashboard",
+    "monitoring",
+    "claude",
+    "ai",
+    "terminal"
+  ],
+  "author": "",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/neochoon/agenthud/issues"
+  },
+  "homepage": "https://github.com/neochoon/agenthud#readme",
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "@types/react": "^19.2.7",
+    "ink-testing-library": "^4.0.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  },
+  "dependencies": {
+    "ink": "^6.6.0",
+    "react": "^19.2.3"
+  }
+}

package/scripts/save-test-results.ts

@@ -0,0 +1,131 @@
+#!/usr/bin/env npx tsx
+/**
+ * Wrapper script to run vitest and save results with git context.
+ *
+ * Usage:
+ *   npx tsx scripts/save-test-results.ts
+ *   npm run test:save
+ *
+ * Output:
+ *   .agent/test-results.json
+ */
+
+import { execSync } from "child_process";
+import { writeFileSync, mkdirSync, existsSync } from "fs";
+import { join } from "path";
+
+interface VitestResult {
+  numPassedTests: number;
+  numFailedTests: number;
+  numPendingTests: number;
+  testResults: Array<{
+    name: string;
+    assertionResults: Array<{
+      title: string;
+      status: "passed" | "failed" | "pending";
+    }>;
+  }>;
+}
+
+interface TestFailure {
+  file: string;
+  name: string;
+}
+
+interface TestResults {
+  hash: string;
+  timestamp: string;
+  passed: number;
+  failed: number;
+  skipped: number;
+  failures: TestFailure[];
+}
+
+function getGitHash(): string {
+  try {
+    return execSync("git rev-parse --short HEAD", { encoding: "utf-8" }).trim();
+  } catch {
+    return "unknown";
+  }
+}
+
+function runVitest(): VitestResult | null {
+  try {
+    const output = execSync("npx vitest run --reporter=json", {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    return JSON.parse(output) as VitestResult;
+  } catch (e: unknown) {
+    // Vitest exits with code 1 if tests fail, but still outputs JSON
+    const error = e as { stdout?: string };
+    if (error.stdout) {
+      try {
+        return JSON.parse(error.stdout) as VitestResult;
+      } catch {
+        return null;
+      }
+    }
+    return null;
+  }
+}
+
+function extractFailures(vitestResult: VitestResult): TestFailure[] {
+  const failures: TestFailure[] = [];
+
+  for (const testFile of vitestResult.testResults) {
+    for (const assertion of testFile.assertionResults) {
+      if (assertion.status === "failed") {
+        failures.push({
+          file: testFile.name.replace(process.cwd() + "/", ""),
+          name: assertion.title,
+        });
+      }
+    }
+  }
+
+  return failures;
+}
+
+function main(): void {
+  console.log("Running tests...\n");
+
+  const vitestResult = runVitest();
+
+  if (!vitestResult) {
+    console.error("Failed to run vitest or parse results");
+    process.exit(1);
+  }
+
+  const results: TestResults = {
+    hash: getGitHash(),
+    timestamp: new Date().toISOString(),
+    passed: vitestResult.numPassedTests,
+    failed: vitestResult.numFailedTests,
+    skipped: vitestResult.numPendingTests,
+    failures: extractFailures(vitestResult),
+  };
+
+  // Ensure .agent directory exists
+  const agentDir = join(process.cwd(), ".agent");
+  if (!existsSync(agentDir)) {
+    mkdirSync(agentDir, { recursive: true });
+  }
+
+  // Write results
+  const outputPath = join(agentDir, "test-results.json");
+  writeFileSync(outputPath, JSON.stringify(results, null, 2));
+
+  // Print summary
+  console.log(`\n✓ ${results.passed} passed`);
+  if (results.failed > 0) {
+    console.log(`✗ ${results.failed} failed`);
+  }
+  if (results.skipped > 0) {
+    console.log(`○ ${results.skipped} skipped`);
+  }
+  console.log(`\nSaved to ${outputPath}`);
+  console.log(`Git hash: ${results.hash}`);
+}
+
+main();