feat(agent-audit): add Hermes Agent + unified breakdown table

Add hermes to the audit client set. Capture via HERMES_HOME-isolated
temp config pointing at the OpenAI loopback; one-shot with
`hermes chat -q "hi"`. Patch openai-loopback to return non-streaming
JSON when the request omits stream:true (hermes default).

Replace per-client categorize.mjs tables with a single unified table
(one column per agent, canonical row labels) plus a top-5 discrepancies
section. Implemented in lib/breakdown-unified.mjs.

Author: ChipWolf

skills/agent-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-audit
-description: Capture each installed coding-agent client's fresh-chat prompt overhead (Claude Code, OpenCode, Codex, pi, Cursor) and report system-only plus first-turn request sizes in characters and approximate tokens. Use when asked to audit, measure, or compare agent prompt overhead.
+description: Capture each installed coding-agent client's fresh-chat prompt overhead (Claude Code, OpenCode, Codex, pi, Hermes Agent, Cursor) and report system-only plus first-turn request sizes in characters and approximate tokens. Use when asked to audit, measure, or compare agent prompt overhead.
 ---
 
 ## Purpose
@@ -15,7 +15,7 @@ From the skill directory, or wherever the dir is mounted:
 ./audit.sh                 # All detected clients, summary table to stdout
 ./audit.sh --raw           # Also write captured prompts under $AGENT_AUDIT_OUT_DIR
 ./audit.sh --breakdown     # Also print per-category composition tables (base/tools/MCP/skills/memory)
-./audit.sh claude codex    # Only the named clients (claude, opencode, codex, pi, cursor)
+./audit.sh claude codex    # Only the named clients (claude, opencode, codex, pi, hermes, cursor)
 ```
 
 Defaults:
@@ -26,14 +26,20 @@ Defaults:
 
 ## Per-category breakdown (`--breakdown`)
 
-The summary table reports both system-only size (`SYS_*`) and fuller first-turn request overhead (`FIRST_*`; see "What the size figures cover"). `--breakdown` adds a second view: how each prompt divides into named categories — the same "where do the bytes go" decomposition Cursor and Claude Desktop surface in their UIs (base prompt vs tool defs vs MCP vs skills vs memory). Implemented in `lib/categorize.mjs`, which re-reads the raw capture audit.sh already wrote into the out dir.
+The summary table reports both system-only size (`SYS_*`) and fuller first-turn request overhead (`FIRST_*`; see "What the size figures cover"). `--breakdown` adds two further views rendered by `lib/breakdown-unified.mjs`:
 
-| Client   | Source read              | Categories surfaced                                                                 |
+1. **Unified table** — one column per agent, mapping per-client raw category labels to a shared canonical set so rows align across agents.
+2. **Top-5 discrepancies** — the five canonical categories (or the overall total) with the largest absolute spread across agents, with per-agent values and a plain-English note.
+
+Per-client raw categories and source files:
+
+| Client   | Source read              | Raw categories surfaced                                                             |
 |----------|--------------------------|-------------------------------------------------------------------------------------|
 | Claude   | `claude-request.json`    | base prompt (system), built-in tools, MCP tool definitions, memory (CLAUDE.md chain), skills catalogue, MCP server instructions, reminders & user msg |
 | OpenCode | `opencode-prompt.json` + `opencode-request.json` | base prompt, environment (`<env>`), memory (AGENTS.md), skills (`<available_skills>`), context-window protection, provider tool schemas |
 | Codex    | `codex-prompt-input.json` + `codex-request.json` | wire base instructions, permissions instructions, skills (`<skills_instructions>`), provider tool schemas |
 | pi       | `pi-system.txt` + `pi-request.json` | base prompt, tools list, guidelines & pi docs, environment, provider tool schemas |
+| Hermes   | `hermes-request.json`    | base prompt (preamble), skills (`<available_skills>`), memory (project context injected from cwd), provider tool schemas |
 
 The `FIRST_*` columns now use captured or locally-rendered first-turn request material consistently: prompt text plus provider tool/function schemas. `SYS_*` preserves the narrower local system/developer text for debugging client prompt changes. Categorization is marker-driven (XML tags, section headers); if a client reorders or renames a section, the affected category falls back into "base prompt" rather than erroring — watch for an implausibly large base bucket after a CLI upgrade.
 
@@ -47,9 +53,10 @@ Each client requires a different trick because none expose "dump my system promp
 | OpenCode     | Throwaway TS plugin for system text + OpenAI-compatible loopback provider for the actual build-agent request | `lib/opencode-plugin.ts`, `lib/openai-loopback.mjs` |
 | Codex        | Built-in `codex debug prompt-input` for system text + temporary `CODEX_HOME` custom provider pointed at loopback | `lib/openai-loopback.mjs` |
 | pi           | Node ESM importing `buildSystemPrompt` and tool definitions from pi's `dist/core/` | `lib/pi-dump.mjs`, `lib/pi-request-dump.mjs` |
+| Hermes       | Temporary `HERMES_HOME` dir with `config.yaml` pointing at loopback; one-shot via `hermes chat -q "hi"`; OpenAI chat/completions format (non-streaming) | `lib/openai-loopback.mjs` |
 | Cursor       | Detect install only; no CLI ships on macOS today                    | none                         |
 
-The `--breakdown` view is a post-processing pass over those captures, not a separate capture: `lib/categorize.mjs` re-reads each client's raw JSON/text from the out dir.
+The `--breakdown` view is a post-processing pass over those captures, not a separate capture: `lib/breakdown-unified.mjs` re-reads each client's raw JSON from the out dir.
 
 ## What the size figures cover
 
@@ -60,6 +67,7 @@ The `--breakdown` view is a post-processing pass over those captures, not a sepa
 - Codex's `FIRST_*` comes from a temporary custom provider in `CODEX_HOME` pointed at the loopback server. Its `SYS_*` still uses `codex debug prompt-input` for the local developer payload.
 - pi has no provider loopback in the audit yet; `FIRST_*` is rendered locally from pi's system prompt plus the active tool definitions, so it is comparable for prompt/tool overhead but not a wire capture.
 - pi walks ancestor directories for `AGENTS.md`/`CLAUDE.md` so its size scales with cwd. The throwaway cwd gives the baseline; rerun from a real project root to compare.
+- Hermes: uses `HERMES_HOME` env var to isolate to a temp dir so the real `~/.hermes/config.yaml` is never touched. Hermes injects AGENTS.md/CLAUDE.md from the cwd as "Project Context" — the throwaway cwd gives the baseline (no project context). The version is read from Python package metadata (`importlib.metadata`). Hermes sends non-streaming OpenAI chat/completions requests; the loopback detects `stream: undefined` and returns a plain JSON response (not SSE).
 
 ## Caveats
 

skills/agent-audit/audit.sh

@@ -24,7 +24,7 @@ KEEP_RAW=0
 
 BREAKDOWN=0
 
-ALL_CLIENTS=(claude opencode codex pi cursor)
+ALL_CLIENTS=(claude opencode codex pi hermes cursor)
 SELECTED=()
 
 for arg in "$@"; do
@@ -35,7 +35,7 @@ for arg in "$@"; do
 		sed -n '2,13p' "$0"
 		exit 0
 		;;
-	claude | opencode | codex | pi | cursor) SELECTED+=("$arg") ;;
+	claude | opencode | codex | pi | hermes | cursor) SELECTED+=("$arg") ;;
 	*)
 		echo "agent-audit: unknown argument: $arg" >&2
 		exit 2
@@ -191,11 +191,11 @@ audit_claude() {
 
 	# Invoke claude with the loopback as the API endpoint. -p forces one-shot mode.
 	# `|| true` because the dummy response may make claude exit non-zero on some versions.
-	(cd "$cwd" && \
+	(cd "$cwd" &&
 		ANTHROPIC_BASE_URL="http://127.0.0.1:$port" \
-		ANTHROPIC_AUTH_TOKEN="audit-dummy" \
-		ANTHROPIC_API_KEY="audit-dummy" \
-		mise_x claude -p "hi" --output-format json >"$OUT_DIR/claude-stdout.json" 2>"$OUT_DIR/claude-stderr.log") || true
+			ANTHROPIC_AUTH_TOKEN="audit-dummy" \
+			ANTHROPIC_API_KEY="audit-dummy" \
+			mise_x claude -p "hi" --output-format json >"$OUT_DIR/claude-stdout.json" 2>"$OUT_DIR/claude-stderr.log") || true
 
 	# Loopback should have exited after capturing. Give it a moment.
 	wait "$server_pid" 2>/dev/null || true
@@ -265,11 +265,11 @@ audit_opencode() {
 	config=$(printf '{"$schema":"https://opencode.ai/config.json","model":"%s","plugin":["%s"],"provider":{"audit":{"npm":"@ai-sdk/openai-compatible","name":"Audit Loopback","options":{"baseURL":"http://127.0.0.1:%s/v1","apiKey":"audit-dummy"},"models":{"audit-model":{"name":"Audit Model"}}}}}' "$model" "$plugin_url" "$port")
 
 	(
-		cd "$cwd" && \
+		cd "$cwd" &&
 			OC_AUDIT_OUT="$system_capture" \
-			OC_AUDIT_NO_EXIT=1 \
-			OPENCODE_CONFIG_CONTENT="$config" \
-			opencode run --model "$model" "hi" >"$OUT_DIR/opencode-stdout.log" 2>"$OUT_DIR/opencode-stderr.log"
+				OC_AUDIT_NO_EXIT=1 \
+				OPENCODE_CONFIG_CONTENT="$config" \
+				opencode run --model "$model" "hi" >"$OUT_DIR/opencode-stdout.log" 2>"$OUT_DIR/opencode-stderr.log"
 	) || true &
 	local opencode_pid=$!
 	for _ in $(seq 1 200); do
@@ -378,10 +378,10 @@ request_max_retries = 0
 stream_max_retries = 0
 EOF
 
-	(cd "$cwd" && \
+	(cd "$cwd" &&
 		CODEX_HOME="$codex_home" \
-		AGENT_AUDIT_DUMMY_KEY="audit-dummy" \
-		mise_x codex exec --skip-git-repo-check --ephemeral --model audit-model "hi" >"$OUT_DIR/codex-stdout.log" 2>"$OUT_DIR/codex-stderr.log") || true
+			AGENT_AUDIT_DUMMY_KEY="audit-dummy" \
+			mise_x codex exec --skip-git-repo-check --ephemeral --model audit-model "hi" >"$OUT_DIR/codex-stdout.log" 2>"$OUT_DIR/codex-stderr.log") || true
 	wait "$server_pid" 2>/dev/null || true
 
 	if [ ! -s "$request_capture" ]; then
@@ -434,6 +434,82 @@ audit_pi() {
 	emit pi "$version" "$system_chars" "$system_tokens" "$first_turn_chars" "$first_turn_tokens" "rendered system + tool request locally"
 }
 
+# ---------- Hermes ----------
+audit_hermes() {
+	local cmd=""
+	if have hermes; then
+		cmd="hermes"
+	elif have hermes-agent; then
+		cmd="hermes-agent"
+	else
+		emit hermes "not installed" 0 0 0 0 "no hermes on PATH"
+		return
+	fi
+	if ! have node; then
+		emit hermes "?" 0 0 0 0 "node required for loopback"
+		return
+	fi
+
+	local version
+	version="$(python3 -c "import importlib.metadata; print(importlib.metadata.version('hermes-agent'))" 2>/dev/null ||
+		ls -d /opt/homebrew/Cellar/hermes-agent/*/ 2>/dev/null | head -1 | xargs basename ||
+		echo "unknown")"
+	[ -z "$version" ] && version="unknown"
+
+	local hermes_home cwd capture port_file log_file server_pid port
+	hermes_home="$OUT_DIR/hermes-home"
+	mkdir -p "$hermes_home"
+	cwd="$(throwaway_cwd hermes)"
+	capture="$OUT_DIR/hermes-request.json"
+	port_file="$OUT_DIR/hermes.port"
+	log_file="$OUT_DIR/hermes-loopback.log"
+
+	server_pid="$(start_openai_loopback "$capture" "$port_file" "$log_file")"
+	if ! port="$(wait_for_port "$port_file" "$server_pid")"; then
+		emit hermes "$version" 0 0 0 0 "loopback failed to bind"
+		return
+	fi
+
+	# Minimal config: redirect to loopback, disable retries, cap at 1 turn
+	cat >"$hermes_home/config.yaml" <<EOF
+model:
+  provider: custom
+  default: audit-model
+  base_url: http://127.0.0.1:$port/v1
+  api_key: audit-dummy
+agent:
+  max_turns: 1
+  api_max_retries: 0
+EOF
+
+	(cd "$cwd" &&
+		HERMES_HOME="$hermes_home" \
+			"$cmd" chat -q "hi" >"$OUT_DIR/hermes-stdout.log" 2>"$OUT_DIR/hermes-stderr.log") || true
+	wait "$server_pid" 2>/dev/null || true
+
+	if [ ! -s "$capture" ]; then
+		emit hermes "$version" 0 0 0 0 "provider request not captured; check hermes-stderr.log"
+		return
+	fi
+
+	# Extract the system message text for SYS_* columns
+	local prompt_file="$OUT_DIR/hermes-system.txt"
+	node -e '
+		const j = JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"));
+		const sys = (j.messages || []).find(m => m.role === "system");
+		const text = typeof sys?.content === "string" ? sys.content
+			: (sys?.content || []).map(c => c.text || "").join("");
+		process.stdout.write(text);
+	' "$capture" >"$prompt_file" 2>/dev/null || true
+
+	local system_chars system_tokens first_turn_chars first_turn_tokens
+	system_chars=$(count_chars <"$prompt_file")
+	system_tokens=$(estimate_tokens "$system_chars")
+	first_turn_chars=$(openai_first_turn_chars "$capture")
+	first_turn_tokens=$(estimate_tokens "$first_turn_chars")
+	emit hermes "$version" "$system_chars" "$system_tokens" "$first_turn_chars" "$first_turn_tokens" "captured via loopback"
+}
+
 # ---------- Cursor ----------
 audit_cursor() {
 	# Cursor has no headless CLI mode and the app may not be installed.
@@ -467,12 +543,15 @@ if [ "$BREAKDOWN" -eq 1 ]; then
 	if ! have node; then
 		printf '\n(breakdown skipped: node not on PATH)\n'
 	else
-		printf '\nPer-category composition (where the bytes go):\n'
+		# Collect only clients that captured data, then render unified table + top-5.
+		CAPTURED_CLIENTS=()
 		while IFS=$'\t' read -r client _version _system_chars _system_tokens first_turn_chars _first_turn_tokens _note; do
-			# Skip clients that never captured anything (e.g. cursor, not installed).
 			[ "$first_turn_chars" = "0" ] && continue
-			node "$LIB_DIR/categorize.mjs" "$client" "$OUT_DIR" || true
+			CAPTURED_CLIENTS+=("$client")
 		done <"$RESULTS_FILE"
+		if [ ${#CAPTURED_CLIENTS[@]} -gt 0 ]; then
+			node "$LIB_DIR/breakdown-unified.mjs" "$OUT_DIR" "${CAPTURED_CLIENTS[@]}" || true
+		fi
 	fi
 fi